# Zernio API Documentation

This document contains the complete API documentation for the Zernio API.

---

# Changelog

Stay up to date with the latest API changes and improvements

import { Changelog } from '@/components/changelog';

Track all updates to the Zernio API. We announce significant changes here and on our [Telegram channel](https://t.me/zernio_dev) and [X (Twitter)](https://x.com/zernionews).

<Changelog />

---

# CLI

Schedule posts, manage inbox, broadcasts, sequences, and automations across 14 platforms from the terminal. Built for developers and AI agents.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

Schedule posts, manage inbox, broadcasts, sequences, and automations across 14 platforms from the terminal. Built for developers and AI agents. Outputs JSON by default.

## Setup

<Steps>

<Step>
### Install the CLI

```bash
npm install -g @zernio/cli
```
</Step>

<Step>
### Authenticate

<Tabs items={['Browser Login (Recommended)', 'Manual API Key']}>

<Tab value="Browser Login (Recommended)">

```bash
zernio auth:login
```

This opens your browser where you can authorize the CLI. An API key is created automatically and saved to `~/.zernio/config.json`.

You can optionally set a custom device name:

```bash
zernio auth:login --device-name "my-server"
```

Running `auth:login` again from the same device replaces the existing key (no duplicates).

</Tab>

<Tab value="Manual API Key">

```bash
zernio auth:set --key "sk_your-api-key"
```

Get your API key from [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys).

</Tab>

</Tabs>

</Step>

<Step>
### Verify Setup

```bash
zernio auth:check
```

This should confirm your API key is valid and display your account info.
</Step>

</Steps>

## Quick Example

```bash
# Schedule a post for tomorrow at 9am
zernio posts:create \
  --text "Hello from the Zernio CLI!" \
  --accounts <accountId1>,<accountId2> \
  --scheduledAt "2025-06-01T09:00:00Z"

# List your DM conversations
zernio inbox:conversations --platform instagram --pretty

# Create a broadcast and send it
zernio broadcasts:create --profileId <id> --accountId <id> --platform instagram --name "Summer Sale" --message "Check out our deals!"
zernio broadcasts:add-recipients <broadcastId> --useSegment
zernio broadcasts:send <broadcastId>
```

## Commands

### Authentication

| Command | Description |
|---------|-------------|
| `zernio auth:login` | Log in via browser (creates API key automatically) |
| `zernio auth:set --key <key>` | Save API key manually |
| `zernio auth:check` | Verify API key works |

### Profiles

| Command | Description |
|---------|-------------|
| `zernio profiles:list` | List all profiles |
| `zernio profiles:get <id>` | Get profile details |
| `zernio profiles:create --name <name>` | Create a new profile |
| `zernio profiles:update <id>` | Update a profile |
| `zernio profiles:delete <id>` | Delete a profile |

### Accounts

| Command | Description |
|---------|-------------|
| `zernio accounts:list` | List connected social accounts |
| `zernio accounts:get <id>` | Get account details |
| `zernio accounts:health` | Check account health status |

### Posts

| Command | Description |
|---------|-------------|
| `zernio posts:create` | Create a new post |
| `zernio posts:list` | List posts |
| `zernio posts:get <id>` | Get post details |
| `zernio posts:delete <id>` | Delete a post |
| `zernio posts:retry <id>` | Retry a failed post |

### Analytics

| Command | Description |
|---------|-------------|
| `zernio analytics:posts` | Get post performance metrics |
| `zernio analytics:daily` | Get daily engagement stats |
| `zernio analytics:best-time` | Get best times to post |

### Media

| Command | Description |
|---------|-------------|
| `zernio media:upload <file>` | Upload a media file |

### Inbox

Manage DM conversations, comments, and reviews across all connected accounts.

| Command | Description |
|---------|-------------|
| `zernio inbox:conversations` | List DM conversations |
| `zernio inbox:conversation <id>` | Get conversation details |
| `zernio inbox:messages <conversationId>` | Get messages in a conversation |
| `zernio inbox:send <conversationId>` | Send a DM |
| `zernio inbox:comments` | List post comments across accounts |
| `zernio inbox:post-comments <postId>` | Get comments on a specific post |
| `zernio inbox:reply <postId>` | Reply to a comment |
| `zernio inbox:reviews` | List reviews (Facebook, Google Business) |
| `zernio inbox:review-reply <reviewId>` | Reply to a review |

```bash
# List Instagram DMs
zernio inbox:conversations --platform instagram --pretty

# Read messages and reply
zernio inbox:messages <conversationId> --accountId <id>
zernio inbox:send <conversationId> --accountId <id> --message "Thanks for reaching out!"

# Reply to a comment
zernio inbox:reply <postId> --accountId <id> --message "Thank you!" --commentId <commentId>
```

### Contacts

Cross-platform contact CRM with tags, custom fields, and channels.

| Command | Description |
|---------|-------------|
| `zernio contacts:list` | List contacts |
| `zernio contacts:create` | Create a contact |
| `zernio contacts:get <id>` | Get contact details |
| `zernio contacts:update <id>` | Update a contact |
| `zernio contacts:delete <id>` | Delete a contact |
| `zernio contacts:channels <id>` | List channels for a contact |
| `zernio contacts:set-field <id> <slug>` | Set a custom field value |
| `zernio contacts:clear-field <id> <slug>` | Clear a custom field value |
| `zernio contacts:bulk-create` | Bulk create up to 1000 contacts from JSON |

```bash
# Search contacts
zernio contacts:list --search "john" --tag vip --pretty

# Create a contact with a channel
zernio contacts:create --profileId <id> --name "John Doe" --accountId <id> --platform instagram --platformIdentifier <userId>

# Bulk create from file
zernio contacts:bulk-create --profileId <id> --accountId <id> --platform instagram --file ./contacts.json
```

### Broadcasts

Send bulk messages to contacts across any inbox platform.

| Command | Description |
|---------|-------------|
| `zernio broadcasts:list` | List broadcasts |
| `zernio broadcasts:create` | Create a broadcast draft |
| `zernio broadcasts:get <id>` | Get broadcast details with stats |
| `zernio broadcasts:update <id>` | Update a broadcast (draft only) |
| `zernio broadcasts:delete <id>` | Delete a broadcast (draft only) |
| `zernio broadcasts:send <id>` | Send a broadcast immediately |
| `zernio broadcasts:schedule <id>` | Schedule a broadcast for later |
| `zernio broadcasts:cancel <id>` | Cancel a broadcast |
| `zernio broadcasts:recipients <id>` | List broadcast recipients |
| `zernio broadcasts:add-recipients <id>` | Add recipients to a broadcast |

```bash
# Create and send a broadcast
zernio broadcasts:create --profileId <id> --accountId <id> --platform instagram --name "Product Launch" --message "We just launched something new!"
zernio broadcasts:add-recipients <broadcastId> --contactIds <id1>,<id2>,<id3>
zernio broadcasts:send <broadcastId>

# Schedule a WhatsApp broadcast with a template
zernio broadcasts:create --profileId <id> --accountId <id> --platform whatsapp --name "Order Update" --templateName "order_confirmation"
zernio broadcasts:schedule <broadcastId> --scheduledAt "2025-06-01T10:00:00Z"

# Check delivery status
zernio broadcasts:recipients <broadcastId> --status delivered --pretty
```

### Sequences

Drip campaign sequences with timed message steps and automatic enrollment.

| Command | Description |
|---------|-------------|
| `zernio sequences:list` | List sequences |
| `zernio sequences:create` | Create a sequence |
| `zernio sequences:get <id>` | Get sequence details with steps |
| `zernio sequences:update <id>` | Update a sequence |
| `zernio sequences:delete <id>` | Delete a sequence |
| `zernio sequences:activate <id>` | Activate a sequence |
| `zernio sequences:pause <id>` | Pause a sequence |
| `zernio sequences:enroll <id>` | Enroll contacts into a sequence |
| `zernio sequences:unenroll <id> <contactId>` | Unenroll a contact |
| `zernio sequences:enrollments <id>` | List enrollments |

```bash
# Create a welcome sequence (steps defined in JSON file)
zernio sequences:create --profileId <id> --accountId <id> --platform instagram --name "Welcome Series" --stepsFile ./steps.json

# steps.json example:
# [
#   {"order": 1, "delayMinutes": 0, "message": {"text": "Welcome! Thanks for connecting."}},
#   {"order": 2, "delayMinutes": 1440, "message": {"text": "Here are some tips..."}},
#   {"order": 3, "delayMinutes": 4320, "message": {"text": "Check out our latest content!"}}
# ]

# Activate and enroll contacts
zernio sequences:activate <sequenceId>
zernio sequences:enroll <sequenceId> --contactIds <id1>,<id2>

# Monitor enrollments
zernio sequences:enrollments <sequenceId> --status active --pretty
```

### Automations

Comment-to-DM automations for Instagram and Facebook. Auto-DM users who comment specific keywords on your posts.

| Command | Description |
|---------|-------------|
| `zernio automations:list` | List comment-to-DM automations |
| `zernio automations:create` | Create an automation |
| `zernio automations:get <id>` | Get automation details with recent logs |
| `zernio automations:update <id>` | Update an automation |
| `zernio automations:delete <id>` | Delete an automation and all logs |
| `zernio automations:logs <id>` | List trigger logs |

```bash
# Auto-DM anyone who comments "info" or "link"
zernio automations:create \
  --profileId <id> --accountId <id> \
  --platformPostId <igPostId> \
  --name "Lead Magnet" \
  --keywords "info,details,link" \
  --dmMessage "Here's the link you asked for: https://example.com" \
  --commentReply "Check your DMs!"

# Trigger on ALL comments (no keyword filter)
zernio automations:create \
  --profileId <id> --accountId <id> \
  --platformPostId <igPostId> \
  --name "Engagement Boost" \
  --dmMessage "Thanks for engaging! Here's a special offer..."

# Disable an automation
zernio automations:update <automationId> --isActive false

# View trigger logs
zernio automations:logs <automationId> --status sent --pretty
```

## Configuration

The CLI stores settings in `~/.zernio/config.json`. You can also use environment variables:

| Variable | Description | Required |
|----------|-------------|----------|
| `ZERNIO_API_KEY` | Your API key | Yes |
| `ZERNIO_API_URL` | Custom API endpoint | No |

Environment variables override the config file.

## Supported Platforms

Instagram, TikTok, X (Twitter), LinkedIn, Facebook, Threads, YouTube, Bluesky, Pinterest, Reddit, Snapchat, Telegram, and Google Business Profile.

## Links

- [GitHub Repository](https://github.com/zernio-dev/zernio-cli)
- [ClawHub Repository](https://clawhub.ai/mikipalet/zernio-cli)
- [npm Package](https://www.npmjs.com/package/@zernio/cli)
- [SDKs](/sdks)
- [Zernio Dashboard](https://zernio.com)

---

# Quickstart

Get started with the Zernio API - authenticate, connect accounts, and schedule your first post in minutes.

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

Zernio is a social media scheduling platform that lets you manage and publish content across all major platforms from a single API. Whether you're building a social media tool, automating your content workflow, or managing multiple brands, Zernio's API gives you complete control.

**Base URL:** `https://zernio.com/api/v1`

---

## Install the SDK

<Tabs items={['Node.js', 'Python', 'Go', 'Ruby', 'Java', 'PHP', '.NET', 'Rust']}>
<Tab value="Node.js">
```bash
npm install @zernio/node
```
</Tab>
<Tab value="Python">
```bash
pip install zernio-sdk
```
</Tab>
<Tab value="Go">
```bash
go get github.com/zernio-dev/zernio-go
```
</Tab>
<Tab value="Ruby">
```bash
gem install zernio-sdk
```
</Tab>
<Tab value="Java">
```xml
<dependency>
  <groupId>com.zernio</groupId>
  <artifactId>zernio-sdk</artifactId>
  <version>0.0.307</version>
</dependency>
```

```groovy
implementation 'com.zernio:zernio-sdk:0.0.307'
```

On [Maven Central](https://central.sonatype.com/artifact/com.zernio/zernio-sdk). For the latest version, see the [releases](https://github.com/zernio-dev/zernio-java/releases).
</Tab>
<Tab value="PHP">
```bash
composer require zernio-dev/zernio-php
```
</Tab>
<Tab value=".NET">
```bash
dotnet add package Zernio
```
</Tab>
<Tab value="Rust">
```bash
cargo add zernio
```
</Tab>
</Tabs>

## Authentication

All API requests require an API key. The SDKs read from the `ZERNIO_API_KEY` environment variable by default.

### Getting Your API Key

1. Log in to your Zernio account at [zernio.com](https://zernio.com)
2. Go to **Settings → API Keys**
3. Click **Create API Key**
4. Copy the key immediately - you won't be able to see it again

### Set Up the Client

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

const zernio = new Zernio(); // uses ZERNIO_API_KEY env var
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio() # uses ZERNIO_API_KEY env var
```
</Tab>
<Tab value="curl">
```bash
# Set your API key as an environment variable
export ZERNIO_API_KEY="sk_..."

# All requests use the Authorization header
curl https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

**Key format:** `sk_` prefix + 64 hex characters (67 total). Keys are stored as SHA-256 hashes - they're only shown once at creation.

**Security tips:** Use environment variables, create separate keys per app, and rotate periodically. You can also [manage keys via the API](/api-keys/list-api-keys).

---

## Key Concepts

- **Profiles** - Containers that group social accounts together (think "brands" or "projects")
- **Accounts** - Your connected social media accounts, belonging to profiles
- **Posts** - Content to publish, schedulable to multiple accounts across platforms simultaneously
- **Queue** - Optional recurring time slots for auto-scheduling posts

---

## Step 1: Create a Profile

Profiles group your social accounts together. For example, you might have a "Personal Brand" profile with your Twitter and LinkedIn, and a "Company" profile with your business accounts.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { profile } = await zernio.profiles.createProfile({
  name: 'My First Profile',
  description: 'Testing the Zernio API'
});

console.log('Profile created:', profile._id);
```
</Tab>
<Tab value="Python">
```python
result = client.profiles.create_profile(
    name="My First Profile",
    description="Testing the Zernio API"
)

print(f"Profile created: {result.profile['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/profiles \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Profile",
    "description": "Testing the Zernio API"
  }'
```
</Tab>
</Tabs>

Save the `_id` value - you'll need it for the next steps.

## Step 2: Connect a Social Account

Now connect a social media account to your profile. This uses OAuth, so it will redirect to the platform for authorization.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { authUrl } = await zernio.connect.getConnectUrl({
  platform: 'twitter',
  profileId: 'prof_abc123'
});

// Redirect user to this URL to authorize
console.log('Open this URL:', authUrl);
```
</Tab>
<Tab value="Python">
```python
result = client.connect.get_connect_url(
    platform="twitter",
    profile_id="prof_abc123"
)

print(f"Open this URL: {result.auth_url}")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/connect/twitter?profileId=prof_abc123" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

Open the URL in a browser to authorize Zernio to access your Twitter account. After authorization, you'll be redirected back and the account will be connected.

### Available Platforms

Replace `twitter` with any of these:

<PlatformConnectTable />

## Step 3: Get Your Connected Accounts

After connecting, list your accounts to get the account ID:

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

for (const account of accounts) {
  console.log(`${account.platform}: ${account._id}`);
}
```
</Tab>
<Tab value="Python">
```python
result = client.accounts.list_accounts()

for account in result.accounts:
    print(f"{account['platform']}: {account['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/accounts" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

Save the account `_id` - you need it to create posts.

## Step 4: Schedule Your First Post

Now you can schedule a post! Here's how to schedule a tweet for tomorrow at noon:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Hello world! This is my first post from the Zernio API',
  scheduledFor: '2024-01-16T12:00:00',
  timezone: 'America/New_York',
  platforms: [
    { platform: 'twitter', accountId: 'acc_xyz789' }
  ]
});

console.log('Post scheduled:', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Hello world! This is my first post from the Zernio API",
    scheduled_for="2024-01-16T12:00:00",
    timezone="America/New_York",
    platforms=[
        {"platform": "twitter", "accountId": "acc_xyz789"}
    ]
)

print(f"Post scheduled: {result.post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello world! This is my first post from the Zernio API",
    "scheduledFor": "2024-01-16T12:00:00",
    "timezone": "America/New_York",
    "platforms": [
      {"platform": "twitter", "accountId": "acc_xyz789"}
    ]
  }'
```
</Tab>
</Tabs>

Your post is now scheduled and will publish automatically at the specified time.

## Posting to Multiple Platforms

You can post to multiple platforms at once. Just add more entries to the `platforms` array:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Cross-posting to all my accounts!',
  scheduledFor: '2024-01-16T12:00:00',
  timezone: 'America/New_York',
  platforms: [
    { platform: 'twitter', accountId: 'acc_twitter123' },
    { platform: 'linkedin', accountId: 'acc_linkedin456' },
    { platform: 'bluesky', accountId: 'acc_bluesky789' }
  ]
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Cross-posting to all my accounts!",
    scheduled_for="2024-01-16T12:00:00",
    timezone="America/New_York",
    platforms=[
        {"platform": "twitter", "accountId": "acc_twitter123"},
        {"platform": "linkedin", "accountId": "acc_linkedin456"},
        {"platform": "bluesky", "accountId": "acc_bluesky789"}
    ]
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Cross-posting to all my accounts!",
    "scheduledFor": "2024-01-16T12:00:00",
    "timezone": "America/New_York",
    "platforms": [
      {"platform": "twitter", "accountId": "acc_twitter123"},
      {"platform": "linkedin", "accountId": "acc_linkedin456"},
      {"platform": "bluesky", "accountId": "acc_bluesky789"}
    ]
  }'
```
</Tab>
</Tabs>

## Publishing Immediately

To publish right now instead of scheduling, use `publishNow: true`:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'This posts immediately!',
  publishNow: true,
  platforms: [
    { platform: 'twitter', accountId: 'acc_xyz789' }
  ]
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="This posts immediately!",
    publish_now=True,
    platforms=[
        {"platform": "twitter", "accountId": "acc_xyz789"}
    ]
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This posts immediately!",
    "publishNow": true,
    "platforms": [
      {"platform": "twitter", "accountId": "acc_xyz789"}
    ]
  }'
```
</Tab>
</Tabs>

## Creating a Draft

To save a post without publishing or scheduling, omit both `scheduledFor` and `publishNow`:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'I will finish this later...',
  platforms: [
    { platform: 'twitter', accountId: 'acc_xyz789' }
  ]
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="I will finish this later...",
    platforms=[
        {"platform": "twitter", "accountId": "acc_xyz789"}
    ]
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I will finish this later...",
    "platforms": [
      {"platform": "twitter", "accountId": "acc_xyz789"}
    ]
  }'
```
</Tab>
</Tabs>

## What's Next?

- **[Platform Guides](/platforms)** - Learn platform-specific features and requirements
- **[Upload media](/guides/media-uploads)** - Add images and videos to your posts
- **[Set up a queue](/queue/list-queue-slots)** - Create recurring posting schedules
- **[View analytics](/analytics/get-analytics)** - Track how your posts perform
- **[Invite team members](/invites/create-invite-token)** - Collaborate with your team
- **[CLI](/cli)** - Manage posts from the terminal

---

# MCP

Connect AI assistants to the Zernio API using the Model Context Protocol

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

Connect AI assistants to the full Zernio API using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Schedule posts, manage ads, automate DMs, run sequences, and more across 14 platforms, all through natural language.

<Callout type="info">
The Zernio MCP server exposes 300+ tools auto-generated from the Zernio OpenAPI spec, covering every API endpoint. It works with Claude, Claude Code, ChatGPT, Cursor, Windsurf, and any MCP-compatible client.
</Callout>

## Use Zernio in your AI client

Zernio runs as a single hosted MCP server at `https://mcp.zernio.com/mcp`. Pick your client:

**Claude (web, desktop, mobile)** — Settings → Connectors → Add custom connector, then enter `https://mcp.zernio.com/mcp`. You sign in with your Zernio account (OAuth); no API key needed. Full steps in [Setup](#setup) below.

**Claude Code** — install the plugin:

```
/plugin marketplace add zernio-dev/zernio-claude-plugin
/plugin install zernio@zernio
```

It prompts once for your [Zernio API key](https://zernio.com/dashboard/api-keys) (stored in your system keychain).

**ChatGPT** — add a connector pointing at `https://mcp.zernio.com/mcp` and authorize with your Zernio account (OAuth).

**Any MCP client / the MCP Registry** — Zernio is published to the [official MCP Registry](https://registry.modelcontextprotocol.io) as `com.zernio/zernio`. Most MCP clients can add the remote server directly:

```
https://mcp.zernio.com/mcp
```

Authenticate with OAuth (sign in with Zernio) or an `Authorization: Bearer <your API key>` header.

## What You Can Do

Ask your AI assistant things like:

- *"Post 'Hello world!' to Twitter"*
- *"Schedule a LinkedIn post for tomorrow at 9am"*
- *"Show my connected accounts"*
- *"Cross-post this to Twitter and LinkedIn"*
- *"Post this image to Instagram"* (with browser upload flow)
- *"List my ad campaigns"*
- *"Send a WhatsApp broadcast to my contacts"*
- *"Show my inbox conversations"*
- *"Create a comment automation for my latest post"*

## Setup

Choose your preferred setup method:

<Tabs items={['Hosted (recommended)', 'Local (uvx)', 'Local (pip)']}>
<Tab value="Hosted (recommended)">

The hosted MCP server at `mcp.zernio.com` requires no local installation. Just configure your client to connect over HTTP.

<Steps>

<Step>
### Get Your API Key

Go to [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys) and create an API key.
</Step>

<Step>
### Configure Your Client

#### Claude Desktop

Claude Desktop's `claude_desktop_config.json` only supports local stdio servers (`command` + `args`). Remote servers like `mcp.zernio.com` are added through the GUI instead.

<Callout type="info">
The `url` + `headers` form for `claude_desktop_config.json` shown in older guides does not work in current Claude Desktop builds — that file is stdio-only.
</Callout>

Open Claude Desktop and go to **Settings → Connectors → Add custom connector**:

- **Name:** Zernio
- **URL:** `https://mcp.zernio.com/mcp`

Click **Add**. Claude redirects you to sign in and authorize with your Zernio account (OAuth), then the connector activates. You don't paste an API key for this path. The sign-in flow handles authorization.

<Callout type="warn">
If you tried this before and saw "Couldn't reach the MCP server", remove the connector and add it again. Claude caches a failed authorization attempt, so a stale failure persists until you re-add it.
</Callout>

If you'd rather configure it in `claude_desktop_config.json`, use the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) stdio bridge:

<Tabs items={['macOS', 'Windows']}>
<Tab value="macOS">
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
</Tab>
<Tab value="Windows">
```
%APPDATA%\Claude\claude_desktop_config.json
```
</Tab>
</Tabs>

```json
{
  "mcpServers": {
    "zernio": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.zernio.com/mcp",
        "--header",
        "Authorization: Bearer your_api_key_here"
      ]
    }
  }
}
```

<Callout type="warn">
Paste the full `sk_...` API key directly into the `--header` value. Earlier examples used an `${AUTH}` env-var indirection, but Claude Desktop on Windows does not always expand env vars into `npx` args, which leaves the header empty and causes a misleading 404 / OAuth-discovery error.
</Callout>

#### Cursor

Add to your project's `.cursor/mcp.json`:

```json
{
  "zernio": {
    "type": "http",
    "url": "https://mcp.zernio.com/mcp",
    "headers": {
      "Authorization": "Bearer your_api_key_here"
    }
  }
}
```

</Step>

<Step>
### Restart Your Client

Close and reopen your AI client. The Zernio integration will be available immediately.
</Step>

</Steps>

</Tab>
<Tab value="Local (uvx)">

Run the MCP server locally using uvx (no install needed).

<Steps>

<Step>
### Install uv

<Tabs items={['macOS / Linux', 'Windows']}>
<Tab value="macOS / Linux">
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
</Tab>
<Tab value="Windows">
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
</Tab>
</Tabs>
</Step>

<Step>
### Get Your API Key

Go to [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys) and create an API key.
</Step>

<Step>
### Configure Claude Desktop

Open Claude Desktop settings and go to **Developer** > **Edit Config**:

![Claude Desktop Developer Settings](/docs-static/claude-desktop-config.png)

Edit `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "zernio": {
      "command": "uvx",
      "args": ["--from", "zernio-sdk[mcp]", "zernio-mcp"],
      "env": {
        "ZERNIO_API_KEY": "your_api_key_here"
      }
    }
  }
}
```
</Step>

<Step>
### Restart Claude Desktop

Close and reopen Claude Desktop. The Zernio integration will be available immediately.
</Step>

</Steps>

</Tab>
<Tab value="Local (pip)">

Install the MCP server via pip.

```bash
pip install zernio-sdk[mcp]
```

Configure Claude Desktop:

```json
{
  "mcpServers": {
    "zernio": {
      "command": "zernio-mcp",
      "env": {
        "ZERNIO_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

`pip install zernio-sdk[mcp]` puts the `zernio-mcp` command on your PATH. If Claude Desktop can't find it, use the absolute path (run `which zernio-mcp` to get it) or the uvx method above.

</Tab>
</Tabs>

<Callout type="warn">
Replace `your_api_key_here` with your actual API key.
</Callout>

## Available Tools

The MCP server exposes 280+ tools covering the entire Zernio API. Here are the main categories:

### Core Tools

These hand-crafted tools provide the best experience for common tasks:

| Tool | Description |
|------|-------------|
| `accounts_list` | Show all connected social media accounts |
| `accounts_get` | Get account details for a specific platform |
| `profiles_list` / `get` / `create` / `update` / `delete` | Manage profiles |
| `posts_list` / `get` / `create` / `update` / `delete` | Manage posts |
| `posts_publish_now` | Publish a post immediately |
| `posts_cross_post` | Post to multiple platforms at once |
| `posts_retry` / `posts_list_failed` / `posts_retry_all_failed` | Handle failed posts |
| `media_generate_upload_link` | Get a link to upload media files |
| `media_check_upload_status` | Check if media upload is complete |
| `docs_search` | Search the Zernio API documentation |

### Auto-Generated Tools

These tools are auto-generated from the OpenAPI spec and cover every endpoint:

| Category | Examples |
|----------|---------|
| **Ads** | `list_ad_campaigns`, `create_standalone_ad`, `boost_post`, `get_ad_analytics`, `search_ad_interests` |
| **WhatsApp** | `create_whats_app_broadcast`, `send_whats_app_bulk`, `get_whats_app_contacts`, `create_whats_app_template` |
| **Inbox** | `list_inbox_conversations`, `send_inbox_message`, `reply_to_inbox_post`, `list_inbox_reviews` |
| **Contacts** | `list_contacts`, `create_contact`, `bulk_create_contacts`, `set_contact_field_value` |
| **Sequences** | `create_sequence`, `enroll_contacts`, `activate_sequence`, `pause_sequence` |
| **Comment Automations** | `create_comment_automation`, `list_comment_automation_logs` |
| **Broadcasts** | `create_broadcast`, `schedule_broadcast`, `send_broadcast` |
| **Analytics** | `get_analytics`, `get_best_time_to_post`, `get_instagram_demographics`, `get_you_tube_daily_views` |
| **Connect** | `get_connect_url`, `handle_o_auth_callback`, `connect_bluesky_credentials` |
| **Webhooks** | `create_webhook_settings`, `get_webhook_logs`, `test_webhook` |

<Callout type="info">
The auto-generated tools update automatically when new API endpoints are added. You always have access to the latest Zernio API features.
</Callout>

## Tool Reference

Detailed parameters for the core tools.

### Posts

<Callout type="warn">
**Multi-account users (agencies, multi-client setups):** when you have more than one account on the same platform, you must pass `account_id` (or `profile_id`) to disambiguate. The write tools below return an error with the candidate account IDs if the selection is ambiguous, instead of silently picking one. Call `accounts_list` first to discover IDs. Available in `zernio-sdk` 1.4.0+.
</Callout>

#### `posts_create`

Create a social media post. Can be saved as DRAFT, SCHEDULED, or PUBLISHED immediately.

<Callout type="warn">
**Choose the correct mode based on user intent:**

- **DRAFT MODE** (`is_draft=true`): Use when user says "draft", "save for later", "don't publish". Post is saved but NOT published.
- **IMMEDIATE MODE** (`publish_now=true`): Use when user says "publish now", "post now", "immediately". Post goes live right away.
- **SCHEDULED MODE** (default): Use when user says "schedule", "in X minutes/hours". Post is scheduled for future publication.
</Callout>

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| `content` | `string` | The post text/content | Yes | - |
| `platform` | `string` | Target platform: twitter, instagram, linkedin, tiktok, bluesky, facebook, youtube, pinterest, threads, googlebusiness, telegram, snapchat | Yes | - |
| `account_id` | `string` | Specific account to post from. Required when the user has multiple accounts on this platform. Call `accounts_list` to find IDs. | No | `""` |
| `profile_id` | `string` | Scope account auto-resolution to one profile (e.g. one client in an agency setup). Use when `account_id` is unknown but the target profile is. | No | `""` |
| `is_draft` | `boolean` | Set to true to save as DRAFT (not published, not scheduled) | No | `false` |
| `publish_now` | `boolean` | Set to true to publish IMMEDIATELY | No | `false` |
| `schedule_minutes` | `integer` | Minutes from now to schedule. Only used when is_draft=false AND publish_now=false | No | `60` |
| `media_urls` | `string` | Comma-separated URLs of media files to attach (images, videos) | No | `""` |
| `title` | `string` | Post title (required for YouTube, recommended for Pinterest) | No | `""` |

#### `posts_publish_now`

Publish a post immediately to a platform. Convenience wrapper around `posts_create` with `publish_now=true`.

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| `content` | `string` | The post text/content | Yes | - |
| `platform` | `string` | Target platform | Yes | - |
| `account_id` | `string` | Specific account ID. Required when the user has multiple accounts on this platform. | No | `""` |
| `profile_id` | `string` | Scope auto-resolution to a single profile when `account_id` is unknown. | No | `""` |
| `media_urls` | `string` | Comma-separated URLs of media files to attach | No | `""` |

#### `posts_cross_post`

Post the same content to multiple platforms at once. To target multiple accounts of the *same* platform in one call, repeat the platform: `platforms="twitter,twitter"`, `account_ids="acc_a,acc_b"`.

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| `content` | `string` | The post text/content | Yes | - |
| `platforms` | `string` | Comma-separated list of platforms (e.g., 'twitter,linkedin,bluesky'). Repeat a platform to target multiple accounts of it. | Yes | - |
| `account_ids` | `string` | Comma-separated account IDs, parallel to `platforms`. Empty positions fall back to profile/auto-resolution. Required for multi-account users to disambiguate. | No | `""` |
| `profile_id` | `string` | Scope auto-resolution to one profile when `account_ids` is empty. | No | `""` |
| `is_draft` | `boolean` | Set to true to save as DRAFT (not published) | No | `false` |
| `publish_now` | `boolean` | Set to true to publish IMMEDIATELY to all platforms | No | `false` |
| `media_urls` | `string` | Comma-separated URLs of media files to attach | No | `""` |

#### `posts_create_post`

Autogenerated tool that mirrors the full `createPost` REST surface. Use this instead of `posts_create` when you need per-target customisation that the simplified tool doesn't expose: `customContent` (different caption per platform), `customMedia` (different attachments per target), per-target `scheduledFor`, or `platformSpecificData` (TikTok privacy, YouTube category, etc.). The `platforms` argument is a JSON-encoded array of objects with `platform`, `accountId`, and any per-target overrides. Available in `zernio-sdk` 1.4.0+.

#### `posts_list`

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| `status` | `string` | Filter by status: draft, scheduled, published, failed | No | `""` |
| `limit` | `integer` | Maximum number of posts to return | No | `10` |

#### `posts_get` / `posts_delete` / `posts_retry`

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| `post_id` | `string` | The post ID | Yes |

#### `posts_update`

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| `post_id` | `string` | The post ID to update | Yes | - |
| `content` | `string` | New content | No | `""` |
| `scheduled_for` | `string` | New schedule time (ISO string) | No | `""` |
| `title` | `string` | New title | No | `""` |

### Media

#### `media_generate_upload_link`

Generate a unique upload URL for the user to upload files via browser. The flow is:
1. Call this tool to get an upload URL
2. Ask the user to open the URL in their browser
3. User uploads files through the web interface
4. Call `media_check_upload_status` to get the uploaded file URLs
5. Use those URLs when creating the post with `posts_create`

#### `media_check_upload_status`

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| `token` | `string` | The upload token from media_generate_upload_link | Yes |

## Uploading Images & Videos

Since AI clients can't access files on your computer directly, we use a browser upload flow:

<Steps>

<Step>
### Ask to Create an Upload Link

Say something like: *"I want to post an image to Instagram"*

The assistant will give you a unique upload URL.
</Step>

<Step>
### Upload Your File

Open the URL in your browser. You'll see a simple upload page where you can drag & drop your image or video.
</Step>

<Step>
### Confirm Upload

Just say *"done"* or *"uploaded"*. The assistant will check the status and create your post with the media attached.
</Step>

</Steps>

**Supported file types:**
- Images: JPG, PNG, WebP, GIF
- Videos: MP4, MOV, WebM
- Documents: PDF

**Maximum file size:** 5GB

## Example Conversations

### Simple Post

> **You:** Post "Just launched our new feature!" to Twitter
>
> **Assistant:** Published to Twitter (@yourhandle)
> Post ID: post_abc123

### Scheduled Post

> **You:** Schedule a LinkedIn post for tomorrow at 9am: "Excited to announce our Series A funding!"
>
> **Assistant:** Scheduled for LinkedIn (@yourcompany)
> Post ID: post_xyz789
> Scheduled: 2025-03-15 09:00

### Cross-Posting

> **You:** Post "Big news coming soon..." to Twitter and LinkedIn
>
> **Assistant:** Published to: twitter, linkedin
> Post ID: post_multi456

### With Image

> **You:** I want to post a product photo to Instagram
>
> **Assistant:** Upload link generated! Open this link in your browser to upload: https://...
>
> **You:** done
>
> **Assistant:** Upload completed! 1 file uploaded. Creating the post...
> Published to Instagram with 1 media file

## Troubleshooting

### "Command not found: uvx" (local setup only)

Make sure uv is installed and in your PATH:

```bash
# Check if installed
uvx --version

# If not, install it
curl -LsSf https://astral.sh/uv/install.sh | sh
```

You may need to restart your terminal or add uv to your PATH.

### "Invalid API key"

1. Check your API key at [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys)
2. Make sure you copied it correctly (no extra spaces)
3. Verify the key is active

### "No accounts connected"

You need to connect social media accounts at [zernio.com](https://zernio.com) before you can post.

### Changes not taking effect

After editing your client's MCP configuration, you must restart the client completely.

## Links

- [Zernio Dashboard](https://zernio.com)
- [Get API Key](https://zernio.com/dashboard/api-keys)
- [Python SDK](https://github.com/zernio-dev/zernio-python)
- [SDKs](/sdks)
- [MCP Protocol](https://modelcontextprotocol.io/)

---

# Pricing

Pay-per-account pricing — first 2 accounts free, then graduated rates with everything included

Zernio is **usage-based**. You pay per connected social account, with everything (Analytics, Inbox, Ads, unlimited posts) included on every paid account. No plan tiers, no add-ons, no profile limits.

## Free

**$0/month** — first 2 connected accounts are always free.

<Cards>
  <Card title="2 connected accounts" />
  <Card title="Unlimited posts" />
  <Card title="All features included" />
</Cards>

No credit card required. Includes Analytics, Inbox, Ads, and full API access on every account.

---

## Usage

Pay only for the accounts you connect, with all features bundled. Add or remove accounts at any time — billing is prorated by the day.

| Connected accounts | Price per account / month |
|---|---|
| 1–2 | **Free** (covered by a recurring monthly credit) |
| 3–10 | **$6** each |
| 11–100 | **$3** each |
| 101–2,000 | **$1** each |
| 2,001+ | [Custom](https://zernio.com/enterprise) |

The pricing is **graduated**: each account is billed at the rate of its tier band, not at one flat tier. So 20 connected accounts costs `$6 × 8 + $3 × 10 = $78/month` (the first 2 are free).

### Try the calculator

A worked example for common scales:

| You connect | Monthly cost |
|---|---|
| 5 accounts | $18 |
| 20 accounts | $78 |
| 50 accounts | $168 |
| 100 accounts | $258 |
| 500 accounts | $658 |
| 1,000 accounts | $1,158 |
| 2,000 accounts | $2,158 |

For more than **2,000 accounts**, get in touch at [zernio.com/enterprise](https://zernio.com/enterprise) for a custom contract.

---

## What's included

Everything is bundled with every paid account — no add-ons, no upgrades.

| Feature | Free | Paid |
|---|:---:|:---:|
| Full API access | ✓ | ✓ |
| Unlimited posts | ✓ | ✓ |
| All 14 platforms | ✓ | ✓ |
| **Analytics** (post metrics, reach, insights) | ✓ | ✓ |
| **Inbox** (DMs, comments, reviews) | ✓ | ✓ |
| **Ads** (Meta, TikTok, LinkedIn, Pinterest, X, Google) | ✓ | ✓ |

No profile limits, no post-per-month caps, no per-feature pricing. Connect accounts, schedule posts, use every feature.

---

## Other charges

A couple of items aren't priced per account. They appear as separate line items on your invoice when used.

### WhatsApp Business numbers

**From $2 per WhatsApp number / month**, separate from the social-account price. US numbers are $2/mo; numbers in other countries are priced per country (typically $2 to $25/mo) and are shown before you confirm the purchase. Regulated countries require a one-time identity verification (KYC) before the number is provisioned. Separately, Meta bills its own usage fees directly to your WhatsApp Business account, not through Zernio: per delivered template message, and a per-minute rate for outbound calls. Inbound calls and in-window service messages are free.

### X (Twitter) API

X's pay-per-call API costs are **passed through at exact rate, with zero markup**. Each X API operation (post, read, DM, etc.) is metered against your account at X's published price (e.g. $0.005 per Posts: Read, $0.015 per Content: Create). See [docs.x.com/x-api/getting-started/pricing](https://docs.x.com/x-api/getting-started/pricing) for the full table.

X usage applies only when you have an X account connected. Customers can set a monthly X spend cap from the dashboard to avoid surprise bills.

---

## How billing works

- We charge your card automatically as you accrue usage. The first time your accrued usage reaches a small fraud-protection threshold (starting at $10), your card is charged for that amount and the threshold doubles for next time. Established customers see fewer, larger charges; brand-new paying customers see one quick small charge to validate the card.
- Each invoice is itemized — you see exactly which accounts, WhatsApp numbers, and X-API calls you're paying for.
- You can connect or disconnect accounts at any time. Billing prorates by the day.
- Powered by [Metronome](https://metronome.com) on top of Stripe for invoicing.

### Daily proration mechanics

Accounts are metered per day, not per month-snapshot. Every day, our system records which accounts are connected and reports them to the billing engine — one event per active account per day. The per-day mechanism means you only pay for the days each account was actually active.

For a single account in a single tier, the cost works out to:

```
account_cost = tier_rate × (days_active / days_in_month)
```

So a $6/month account connected for 15 days costs **$3** that month. If you connect on day 1 and disconnect on day 15, you're billed for the half you used.

#### How it interacts with graduated tiers

Because pricing is graduated ($6 / $3 / $1), the rate isn't fixed per-account — it depends on your **total billable units for the month**, computed as:

```
billable_units = (sum of all account-days in the month) ÷ days_in_month
```

That total is then run through the graduated tier ladder (first 10 units at $6, next 90 at $3, next 1,900 at $1). You never get charged tier-1 prices for units that fall into tier 2 or 3 — partial usage in higher tiers gets the lower rate.

> **Mental model:** at the end of the month we add up every "account-day" (one per account per day connected), divide by 30, and run the result through the rate ladder. So 100 accounts × 3 days costs the same as 10 accounts × 30 days. The graduated rates apply to the *total*, not to individual accounts.

<PricingCalculator />

The calculator reflects the exact math the billing engine uses: account-days → divide by 30 → graduated tiers → minus $12 free-tier credit.

#### Worked example

A customer has 10 accounts connected for the full month. In week 2 they connect an 11th account, then disconnect it in week 3. In week 4 they connect a 12th, different account, for the rest of the month.

**Step 1 — count account-days:**

| Account group | Days active | Account-days |
|---|---|---|
| 10 baseline accounts | 30 days each | 300 |
| 1 account (week 2 → 3) | 7 days | 7 |
| 1 account (week 4 → end) | 7 days | 7 |
| **Total** | | **314 account-days** |

**Step 2 — convert to billable units:**

```
314 ÷ 30 = 10.467 billable units
```

**Step 3 — apply graduated tiers:**

| Tier | Units in this tier | Rate | Cost |
|---|---|---|---|
| Tier 1 (1-10) | 10 | $6.00 | $60.00 |
| Tier 2 (11-100) | 0.467 | $3.00 | $1.40 |
| **Total gross** | | | **$61.40** |

**Step 4 — apply the free-tier credit:**

| Item | Amount |
|---|---|
| Total gross | $61.40 |
| Free-tier credit (flat per month) | −$12.00 |
| **Net invoice** | **$49.40** |

The total bill is **not** "11 accounts" or "12 accounts" — it's the sum of all account-days converted into billable units, then run through the graduated rates. The 11th and 12th accounts (which only existed for partial weeks) push the total just past the tier-1 boundary, so their fractional contribution is priced at tier 2's $3 rate, not tier 1's $6.

#### Common questions

- **What window does Zernio measure activity in?** Calendar month — account-days accumulate from the 1st to the last day of each month, then flush into a new period.
- **If I disconnect and reconnect the same account, does it count twice?** Each day it's active counts. If it's active for 10 days, disconnected for 5, then reconnected for 10 more (same calendar month), that's 20 account-days for that account.
- **What if I connect a brand-new account mid-month?** Charged from the day it's connected onward, prorated through end-of-month.
- **Which accounts pay tier-1 vs tier-2 rates?** The graduated rate isn't tied to individual accounts — it applies to the **total billable units**. The first 10 units of usage are at $6, units 11-100 at $3, and so on. So if your monthly total works out to 12.5 billable units, the first 10 are billed at $6 and the remaining 2.5 at $3.
- **What about the free-tier credit?** Each calendar month grants $12 of credit (covers the first 2 accounts at the $6 tier). Credit applies to the gross monthly total — it's a flat per-month grant, not per-account.

---

## Get started

<Cards>
  <Card title="Get your API key" href="/" description="Set up authentication to start using the API" />
  <Card title="Quickstart guide" href="/" description="Schedule your first post in minutes" />
</Cards>

Sign up at [zernio.com](https://zernio.com) — first 2 accounts free, no credit card required.

---

# Refer & earn

Earn 20% recurring commission for 12 months when you refer new customers to Zernio.

# Zernio Affiliate Program Terms

Zernio has an affiliate program — refer new customers and earn 20% recurring commission for 12 months. Head to our [affiliate page](https://partners.dub.co/zernio) for the full details and to apply. The terms below cover how it all works.

**Effective date:** The date you submit your application and accept these terms.

This agreement is between Zernio ("we," "us," "the Company") and you, the approved partner ("you," "Partner"). By applying to the Zernio Partner Program ("Program") and accepting these terms, you agree to the following.

## 1. Definitions

**Referral** — a potential customer you introduce to Zernio through your unique partner link.

**Qualified Referral** — a Referral that meets all of the following criteria:

- A first-time Zernio customer who has not previously held an account in our system.
- Completes a qualifying paid subscription (connecting 3 or more social accounts, as the first 2 are free).
- Full, valid payment is received by the Company.
- Remains an active, paying customer for at least 30 days after their initial payment.

The determination of whether a Referral qualifies rests with the Company.

## 2. Eligibility and Approval

The Program is application-based. We review each application individually and reserve the right to approve or decline at our discretion. We may also end a partnership if these terms are not being followed.

## 3. Partner Responsibilities

As a partner, we ask that you:

- Represent Zernio's products and capabilities accurately
- Share your partner link only through authorized methods and channels
- Comply with all applicable advertising, marketing, and data protection laws in your jurisdiction
- Follow the brand guidelines we provide upon approval

## 4. Program Guidelines

To keep the Program fair and sustainable for everyone, the following activities are **not permitted**:

- Bidding on Zernio brand terms in paid search, or running paid advertising that competes directly with Zernio's own campaigns
- Listing Zernio on coupon, deal, or discount aggregator sites without prior approval
- Using automated, incentivized, or artificially inflated traffic methods (including bots, cookie stuffing, or misleading redirects)
- Referring accounts that you own, operate, or control
- Operating sub-affiliate arrangements or reselling access to the Program
- Representing yourself as an employee, agent, or official representative of Zernio
- Misrepresenting Zernio's product capabilities or pricing to drive signups

We understand that most partners would never consider these things, but having them written down protects everyone involved. Violations may result in removal from the Program and forfeiture of unpaid commissions.

## 5. Revenue Share

### Commission

Partners earn a **20% revenue share** on qualifying subscription fees paid by each Qualified Referral, for up to **12 months** from the date of their first payment or until the customer cancels, whichever comes first.

### What's included in the calculation

Commission is calculated on Zernio's own account-based subscription revenue. The following are excluded:

- Taxes, discounts, and promotional credits
- X/Twitter API passthrough costs (billed at exact platform rates with no Zernio margin)
- WhatsApp passthrough charges

## 6. Payment Terms

- **Platform:** Payouts are processed through Dub Partners and facilitated via Stripe.
- **Schedule:** Commissions accrue monthly and are issued at the end of each calendar month.
- **Holding period:** The first month's commission for each new Qualified Referral is held for 30 days after month-end, allowing time to verify eligibility and confirm no refund or cancellation occurred.
- **Minimum payout:** $10 — balances below this threshold carry forward to the following month.
- **Delivery:** Payments are sent within 30 days following month-end.

## 7. Refunds and Adjustments

If a Qualified Referral cancels, receives a refund, initiates a chargeback, or is found to have been obtained through methods that don't comply with these terms, the associated commissions may be adjusted or withheld. We will notify you if this happens.

## 8. Taxes

Partners are responsible for all applicable taxes on earnings received through the Program.

## 9. Intellectual Property

Any trademarks, logos, screenshots, or promotional materials we provide remain the property of Zernio. You're welcome to use them to promote the Program in accordance with our [brand guidelines](https://zernio.com/press), but no ownership rights are transferred. If we update or retire specific materials, we'll ask you to update accordingly.

## 10. Term and Termination

This agreement remains in effect from the date of your acceptance until either party ends it.

- You may leave the Program at any time.
- We may end the partnership at any time, with or without cause, by providing notice. In cases of serious or repeated violations of these terms, we may terminate immediately.

Upon termination, any earned and verified commissions will still be paid out according to the normal schedule. Commissions that haven't yet cleared the 30-day holding period will be reviewed and paid if eligible.

## 11. Changes to the Program

We may update these terms, adjust commission rates, or modify Program mechanics over time. When we do:

- We'll provide at least 15 days' notice by email before changes take effect
- Continued participation after the notice period constitutes acceptance of the updated terms

We're committed to making changes thoughtfully and transparently.

## 12. Disputes

If you believe a commission was calculated incorrectly, please let us know in writing within 30 days of the relevant payment. We'll work together to resolve it.

## 13. General Provisions

- **Governing law:** This agreement is governed by the laws of Spain.
- **Independent relationship:** Partners are independent and are not employees, agents, or contractors of Zernio. Nothing in this agreement creates an employment or agency relationship.
- **Non-exclusivity:** This agreement is non-exclusive. Both parties are free to enter into similar arrangements with others.
- **Entire agreement:** This document represents the complete agreement between both parties regarding the Program and supersedes any prior discussions or understandings.
- **Severability:** If any provision is found to be unenforceable, the remaining provisions continue in full effect.

## 14. Contact

For questions about the Program, reach us at **affiliates@zernio.com**.

---

By submitting your application to the Zernio Partner Program and accepting these terms, you confirm that you have read, understood, and agree to this agreement.

---

# SDKs

Official Zernio API client libraries for Node.js, Python, Go, Ruby, Java, PHP, .NET, and Rust. Post to 14+ social platforms.

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

## Official SDKs

<Cards>
  <Card
    icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>}
    title="Node.js"
    description="github.com/zernio-dev/zernio-node"
    href="https://github.com/zernio-dev/zernio-node"
  />
  <Card
    icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>}
    title="Python"
    description="github.com/zernio-dev/zernio-python"
    href="https://github.com/zernio-dev/zernio-python"
  />
  <Card
    icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>}
    title="Go"
    description="github.com/zernio-dev/zernio-go"
    href="https://github.com/zernio-dev/zernio-go"
  />
  <Card
    icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>}
    title="Ruby"
    description="github.com/zernio-dev/zernio-ruby"
    href="https://github.com/zernio-dev/zernio-ruby"
  />
  <Card
    icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>}
    title="Java"
    description="github.com/zernio-dev/zernio-java"
    href="https://github.com/zernio-dev/zernio-java"
  />
  <Card
    icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>}
    title="PHP"
    description="github.com/zernio-dev/zernio-php"
    href="https://github.com/zernio-dev/zernio-php"
  />
  <Card
    icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>}
    title=".NET"
    description="github.com/zernio-dev/zernio-dotnet"
    href="https://github.com/zernio-dev/zernio-dotnet"
  />
  <Card
    icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>}
    title="Rust"
    description="github.com/zernio-dev/zernio-rust"
    href="https://github.com/zernio-dev/zernio-rust"
  />
</Cards>

## Chat SDK Adapter

Build chatbots that work across all Zernio-supported messaging platforms through a single [Chat SDK](https://chat-sdk.dev) integration.

<Cards>
  <Card
    icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>}
    title="@zernio/chat-sdk-adapter"
    description="Vendor official Chat SDK adapter for Instagram, Facebook, Telegram, WhatsApp, X, Bluesky & Reddit"
    href="https://github.com/zernio-dev/chat-sdk-adapter"
  />
</Cards>

See the full [Chat SDK integration guide](/resources/integrations/chat-sdk) for setup instructions and examples.

## OpenAPI

<Cards>
  <Card
    icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"></path><polyline points="14 2 14 8 20 8"></polyline><line x1="16" y1="13" x2="8" y2="13"></line><line x1="16" y1="17" x2="8" y2="17"></line><polyline points="10 9 9 9 8 9"></polyline></svg>}
    title="OpenAPI Spec"
    description="zernio.com/openapi.yaml"
    href="https://zernio.com/openapi.yaml"
  />
</Cards>

---

# Webhooks

How Zernio webhook deliveries work and the payload sent for each event.

import { Callout } from 'fumadocs-ui/components/callout';

## How to think about webhooks

- Subscribe only to the events you actually handle.
- Treat each delivery as an event notification, not a full source of truth sync.
- Use the webhook event ID as your deduplication key.
- Verify the `X-Zernio-Signature` header when you configure a webhook secret.
- Expect fast acknowledgement from your endpoint and move heavier processing to async jobs.

## Delivery flow

1. Create a webhook endpoint with [Create webhook settings](/webhooks/create-webhook-settings).
2. Choose the events you want to subscribe to.
3. Receive a `POST` request from Zernio whenever one of those events occurs.
4. Return a `2xx` response after you have accepted the payload.
5. Use [Test webhook](/webhooks/test-webhook) and [Webhook logs](https://zernio.com/dashboard/webhooks) to validate your integration.

## Delivery retries

A delivery is considered successful when your endpoint returns a `2xx` response within 5 seconds. Any other outcome (non-`2xx` status, request timeout, connection error) triggers a retry on an exponential backoff schedule capped at 24 hours.

Up to 7 attempts are made per event. The full schedule, measured from the moment the previous attempt finished:

| Attempt | Delay before this attempt | Cumulative time since the first attempt |
| --- | --- | --- |
| 1 | immediate | 0 |
| 2 | 10s | ~10s |
| 3 | 1m 40s | ~1m 50s |
| 4 | 16m 40s | ~18m 30s |
| 5 | 2h 46m 40s | ~3h 5m |
| 6 | 24h (capped) | ~27h 5m |
| 7 | 24h (capped) | ~51h 5m |

After the 7th attempt fails the event is moved to a dead-letter queue and is no longer retried automatically. Failures are visible via [Webhook logs](https://zernio.com/dashboard/webhooks) (`attemptNumber` records which try produced each log entry). Webhooks are never auto-disabled based on failure count, you can pause or remove them from your webhook settings.

<Callout type="info">
**Keep your handler fast.** Acknowledge the request as soon as you have persisted the event, then process it on a background worker. Long-running handlers risk hitting the 5-second timeout and triggering an unnecessary retry.
</Callout>

## Idempotency

Webhook deliveries use **at-least-once** semantics: the same event may arrive more than once if a previous attempt's response was lost or your endpoint took too long to acknowledge. Your handler must therefore be idempotent.

Every payload carries a stable event identifier that is also exposed as a header:

- `payload.id`, the canonical event ID (UUID).
- `X-Zernio-Event-Id`, the same value, repeated as a header for convenience.
- `X-Late-Event-Id`, legacy alias of the above, kept for backward compatibility.

Use this identifier as your deduplication key. A typical pattern is to insert the event ID into a unique-indexed table or cache before processing the payload, and skip processing when the insert conflicts.

## Signature verification

If the webhook has a secret configured, every delivery includes an `X-Zernio-Signature` header. The signature is the lowercase hex `HMAC-SHA256` of the raw request body keyed by your webhook secret.

- `X-Zernio-Signature`, the signature.
- `X-Late-Signature`, legacy alias of the above, kept for backward compatibility.

Read the raw body, compute the HMAC, and compare it to the header value:

```typescript
import crypto from "crypto";

export const POST = async (req: Request) => {
  const webhookSignature = req.headers.get("X-Zernio-Signature");
  if (!webhookSignature) {
    return new Response("No signature provided.", { status: 401 });
  }

  const secret = process.env.ZERNIO_WEBHOOK_SECRET;
  if (!secret) {
    return new Response("No secret provided.", { status: 401 });
  }

  const rawBody = await req.text();

  const computedSignature = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  if (webhookSignature !== computedSignature) {
    return new Response("Invalid signature", { status: 400 });
  }

  const payload = JSON.parse(rawBody);
  // Handle the webhook event
  // ...
};
```

<Callout type="warn">
**Reject unsigned or mismatched requests.** A failed signature check means the request did not originate from Zernio (or the body was tampered with in transit). Do not process the payload.
</Callout>

## Available events

| Event | Description |
| --- | --- |
| [`post.published`](#postpublished) | Fired when a post is successfully published. |
| [`post.failed`](#postfailed) | Fired when a post fails to publish on all target platforms. |
| [`post.partial`](#postpartial) | Fired when a post publishes on some platforms and fails on others. |
| [`post.cancelled`](#postcancelled) | Fired when a post publishing job is cancelled. |
| [`post.scheduled`](#postscheduled) | Fired when a post is scheduled for future publishing. |
| [`post.recycled`](#postrecycled) | Fired when a post is recycled for republishing. |
| [`post.external.created`](#postexternalcreated) | Fired when a post authored natively on the platform (outside Zernio) is detected for the first time. |
| [`post.external.updated`](#postexternalupdated) | Fired when a tracked native post's text or media changes on the platform. |
| [`post.external.deleted`](#postexternaldeleted) | Fired when a tracked native post is detected as removed from the platform. |
| [`account.connected`](#accountconnected) | Fired when a social account is successfully connected. |
| [`account.disconnected`](#accountdisconnected) | Fired when a connected social account becomes disconnected. |
| [`account.ads.initial_sync_completed`](#accountadsinitial_sync_completed) | Fired once per ads-enabled account when the initial 90-day backfill completes. |
| [`message.received`](#messagereceived) | Fired when a new inbox message is received. |
| [`message.sent`](#messagesent) | Fired when an outgoing message is sent from the inbox. |
| [`conversation.started`](#conversationstarted) | Fired once when a new conversation begins between an account and a contact, on any DM platform. |
| [`message.edited`](#messageedited) | Fired when a sender edits a previously-sent message. |
| [`message.deleted`](#messagedeleted) | Fired when a sender deletes (unsends) a message. |
| [`message.delivered`](#messagedelivered) | Fired when an outgoing message is delivered to the recipient. |
| [`message.read`](#messageread) | Fired when an outgoing message is read by the recipient. |
| [`message.failed`](#messagefailed) | Fired when an outgoing message fails to deliver (WhatsApp only). |
| [`reaction.received`](#reactionreceived) | Fired when a participant adds or removes an emoji reaction (WhatsApp, Telegram). |
| [`comment.received`](#commentreceived) | Fired when a new comment is received on a tracked post. |
| [`review.new`](#reviewnew) | Fired when a new review is posted on a connected account. |
| [`review.updated`](#reviewupdated) | Fired when a review is edited or a reply is added. |
| [`lead.received`](#leadreceived) | Fired when a new lead is submitted against a Meta Lead Gen form. |
| [`ad.status_changed`](#adstatus_changed) | Fired when an ad, ad set, or campaign changes status on the ad platform (Meta only). |
| [`call.received`](#callreceived) | Fired when an inbound WhatsApp call reaches one of your numbers and is routed to its destination. |
| [`call.ended`](#callended) | Fired when a WhatsApp call ends; carries duration, end reason, cost breakdown, and the recording when enabled. |
| [`call.failed`](#callfailed) | Fired when a WhatsApp call fails with a hard error before or during bridging. |
| [`call.permission_request`](#callpermission_request) | Fired when a WhatsApp user accepts or rejects your call-permission request. |
| [`whatsapp.number.activated`](#whatsappnumberactivated) | Fired when a WhatsApp number you provisioned finishes setup and is ready to connect. |
| [`whatsapp.number.declined`](#whatsappnumberdeclined) | Fired when a regulated number order is declined in review and no number is activated. |
| [`whatsapp.number.action_required`](#whatsappnumberaction_required) | Fired when the regulator asks for more information on a placed number order; the order stays pending until you provide it. |
| [`whatsapp.number.verification_required`](#whatsappnumberverification_required) | Fired when a regulated number needs end-user ID verification; carries the link to forward. |
| [`whatsapp.number.suspended`](#whatsappnumbersuspended) | Fired when an active number is suspended (e.g. failed payment); carries a `reason`. |
| [`whatsapp.number.reactivated`](#whatsappnumberreactivated) | Fired when a suspended number is usable again. |
| [`whatsapp.number.released`](#whatsappnumberreleased) | Fired when a number is released and no longer usable (terminal); carries a `reason`. |
| [`webhook.test`](#webhooktest) | Fired when sending a test webhook to verify the endpoint configuration. |

---

## `post.published`

Fired when a post is successfully published. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `post.published`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled
- **post** (required) `object`: 
  - **id** (required) `string`: No description
  - **content** (required) `string`: No description
  - **status** (required) `string`: No description
  - **scheduledFor** (required) `string` (date-time): No description
  - **publishedAt** `string` (date-time): No description
  - **platforms** (required) `array[object]`: 
    - **platform** (required) `string`: No description
    - **status** (required) `string`: No description
    - **platformPostId** `string`: No description
    - **publishedUrl** `string`: No description
    - **error** `string`: No description
- **timestamp** (required) `string` (date-time): No description

---

## `post.failed`

Fired when a post fails to publish on all target platforms. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `post.failed`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled
- **post** (required) `object`: 
  - **id** (required) `string`: No description
  - **content** (required) `string`: No description
  - **status** (required) `string`: No description
  - **scheduledFor** (required) `string` (date-time): No description
  - **publishedAt** `string` (date-time): No description
  - **platforms** (required) `array[object]`: 
    - **platform** (required) `string`: No description
    - **status** (required) `string`: No description
    - **platformPostId** `string`: No description
    - **publishedUrl** `string`: No description
    - **error** `string`: No description
- **timestamp** (required) `string` (date-time): No description

---

## `post.partial`

Fired when a post publishes on some platforms and fails on others. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `post.partial`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled
- **post** (required) `object`: 
  - **id** (required) `string`: No description
  - **content** (required) `string`: No description
  - **status** (required) `string`: No description
  - **scheduledFor** (required) `string` (date-time): No description
  - **publishedAt** `string` (date-time): No description
  - **platforms** (required) `array[object]`: 
    - **platform** (required) `string`: No description
    - **status** (required) `string`: No description
    - **platformPostId** `string`: No description
    - **publishedUrl** `string`: No description
    - **error** `string`: No description
- **timestamp** (required) `string` (date-time): No description

---

## `post.cancelled`

Fired when a post publishing job is cancelled. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `post.cancelled`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled
- **post** (required) `object`: 
  - **id** (required) `string`: No description
  - **content** (required) `string`: No description
  - **status** (required) `string`: No description
  - **scheduledFor** (required) `string` (date-time): No description
  - **publishedAt** `string` (date-time): No description
  - **platforms** (required) `array[object]`: 
    - **platform** (required) `string`: No description
    - **status** (required) `string`: No description
    - **platformPostId** `string`: No description
    - **publishedUrl** `string`: No description
    - **error** `string`: No description
- **timestamp** (required) `string` (date-time): No description

---

## `post.scheduled`

Fired when a post is scheduled for future publishing. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `post.scheduled`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled
- **post** (required) `object`: 
  - **id** (required) `string`: No description
  - **content** (required) `string`: No description
  - **status** (required) `string`: No description
  - **scheduledFor** (required) `string` (date-time): No description
  - **publishedAt** `string` (date-time): No description
  - **platforms** (required) `array[object]`: 
    - **platform** (required) `string`: No description
    - **status** (required) `string`: No description
    - **platformPostId** `string`: No description
    - **publishedUrl** `string`: No description
    - **error** `string`: No description
- **timestamp** (required) `string` (date-time): No description

---

## `post.recycled`

Fired when a post is recycled for republishing. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `post.recycled`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled
- **post** (required) `object`: 
  - **id** (required) `string`: No description
  - **content** (required) `string`: No description
  - **status** (required) `string`: No description
  - **scheduledFor** (required) `string` (date-time): No description
  - **publishedAt** `string` (date-time): No description
  - **platforms** (required) `array[object]`: 
    - **platform** (required) `string`: No description
    - **status** (required) `string`: No description
    - **platformPostId** `string`: No description
    - **publishedUrl** `string`: No description
    - **error** `string`: No description
- **timestamp** (required) `string` (date-time): No description

---


## `post.external.created`

Fired when Zernio's background sync detects a post that was authored **natively on the platform** (outside Zernio), such as a Google Business Profile post created in the Google interface. This is **poll-driven** (roughly hourly), not real-time, because most platforms offer no push notification for merchant-authored posts. The payload's `post.source` is always `"external"`, and `post.id` is the platform-native post ID. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<Callout type="info">
  On a freshly connected account, every existing native post is reported as `post.external.created` on the first sync (a one-time backfill). Treat `created` as an idempotent upsert keyed on `post.id`.
</Callout>

<br />

**Payload for `post.external.created`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: post.external.created, post.external.updated, post.external.deleted
- **post** (required): `ExternalPostWebhookPost` - See schema definition
- **account** (required) `object`: 
  - **id** (required) `string`: No description
  - **platform** (required) `string`: No description
  - **username** (required) `string`: No description
- **timestamp** (required) `string` (date-time): No description

---


## `post.external.updated`

Fired when a tracked native post's text or media changes on the platform. Edits are detected by comparing the post's text and media structure and, where the platform exposes one, the platform's own edit timestamp. A media-URL-only refresh (some platforms rotate expiring CDN URLs) does **not** fire this event. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `post.external.updated`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: post.external.created, post.external.updated, post.external.deleted
- **post** (required): `ExternalPostWebhookPost` - See schema definition
- **account** (required) `object`: 
  - **id** (required) `string`: No description
  - **platform** (required) `string`: No description
  - **username** (required) `string`: No description
- **timestamp** (required) `string` (date-time): No description

---


## `post.external.deleted`

Fired when a tracked native post is detected as removed from the platform. The payload's `post.deletedAt` carries the detection time. Coverage is bounded to the most recent posts the platform's listing returns, so deletions of very old posts may not be detected. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `post.external.deleted`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: post.external.created, post.external.updated, post.external.deleted
- **post** (required): `ExternalPostWebhookPost` - See schema definition
- **account** (required) `object`: 
  - **id** (required) `string`: No description
  - **platform** (required) `string`: No description
  - **username** (required) `string`: No description
- **timestamp** (required) `string` (date-time): No description

---


## `account.connected`

Fired when a social account is successfully connected. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `account.connected`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: account.connected
- **account** (required) `object`: 
  - **accountId** (required) `string`: The account's unique identifier (same as used in /v1/accounts/{accountId})
  - **profileId** (required) `string`: The profile's unique identifier this account belongs to
  - **platform** (required) `string`: No description
  - **username** (required) `string`: No description
  - **displayName** `string`: No description
- **timestamp** (required) `string` (date-time): No description

---

## `account.disconnected`

Fired when a connected social account becomes disconnected. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `account.disconnected`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: account.disconnected
- **account** (required) `object`: 
  - **accountId** (required) `string`: The account's unique identifier (same as used in /v1/accounts/{accountId})
  - **profileId** (required) `string`: The profile's unique identifier this account belongs to
  - **platform** (required) `string`: No description
  - **username** (required) `string`: No description
  - **displayName** `string`: No description
  - **disconnectionType** (required) `string`: Whether the disconnection was intentional (user action) or unintentional (token expired/revoked) - one of: intentional, unintentional
  - **reason** (required) `string`: Human-readable reason for the disconnection
- **timestamp** (required) `string` (date-time): No description

---

## `account.ads.initial_sync_completed`

Fired once per ads-enabled account when the initial sync completes. The initial sync runs after an ads-capable account is connected and performs ad-account discovery plus a 90-day historical ad backfill. The payload includes a sync summary reporting whether the backfill succeeded fully or partially and how many ads were synced vs. failed.

When scoping was applied at connect time (see [Scoping sync to specific ad accounts](/guides/connecting-accounts#scoping-sync-to-specific-ad-accounts)), `account.platformAdAccountId` echoes the chosen ad account back (when scope is exactly one) and `account.platformAdAccountIds` lists every `act_*` actually synced.

On failure (`sync.status == "failure"`), the payload also carries optional fields to help branch your UX without parsing prose:
- `sync.error`: raw platform error message (truncated to ~2KB).
- `sync.errorCode` / `sync.errorSubcode`: platform-native error codes when parseable (e.g. Meta `190`, `10`).
- `sync.errorCategory`: a stable enum, one of `token_invalid`, `permission_denied`, `no_ad_accounts`, `rate_limited`, `discovery_failed`, `unknown`. New values may be added; existing ones are stable.

Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `account.ads.initial_sync_completed`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: account.ads.initial_sync_completed
- **account** (required) `object`: 
  - **accountId** (required) `string`: The account's unique identifier (same as used in /v1/accounts/{accountId})
  - **profileId** (required) `string`: The profile's unique identifier this account belongs to
  - **platform** (required) `string`: No description
  - **username** (required) `string`: No description
  - **displayName** `string`: No description
  - **platformUserId** `string`: The platform-side account/ad-account ID (e.g. Meta ad account ID).
  - **profilePicture** `string` (uri): URL of the account's profile picture, when available.
  - **platformAdAccountId** `string`: When the consumer scoped the connect call to a single ad account, this echoes
that ID back so the webhook can be correlated to the originating connect
request without consulting the consumer's DB. Meta uses the `act_*` shape.
 (example: "act_1330190928038136")
  - **platformAdAccountIds** `array[string]`: Every ad-account ID that the connected token could see at discovery time.
Useful for "we synced ads from these accounts" UX without a follow-up API call.
Empty array when the token had no ad-account visibility.

- **sync** (required) `object`: Summary of the initial ads sync backfill results.
  - **status** (required) `string`: Overall outcome of the initial sync. - one of: success, failure
  - **totalAds** (required) `integer`: Total number of ads discovered for backfill.
  - **synced** (required) `integer`: Number of ads successfully synced.
  - **failed** (required) `integer`: Number of ads that failed to sync.
  - **error** `string`: Free-form error message from the platform (typically Meta's Marketing API).
Truncated to ~2KB. Present when `status` is `failure` (and sometimes on `success`
when discovery saw zero ad accounts). For UX branching prefer `errorCategory`;
this field is for human display and debugging.

  - **errorCode** `string`: Platform-native error code if parsed (e.g. Meta `190`, `10`, `200`).
  - **errorSubcode** `string`: Platform-native error subcode if parsed.
  - **errorCategory** `string`: Stable category for UX branching. New values may be added; existing ones are
stable. Mapping:
  - `token_invalid`: access token is expired or revoked. Reconnect.
  - `permission_denied`: token lacks required scope, or the user has no role
    on the Business Manager that owns the ad account. Reconnect with full
    permissions, or have an admin grant access.
  - `no_ad_accounts`: token is valid but sees zero ad accounts. The user
    needs to connect a Business Manager that owns ad accounts.
  - `rate_limited`: platform throttled us. Sync will retry automatically.
  - `discovery_failed`: any other platform-side failure. Inspect `error`.
  - `unknown`: classifier could not categorize the failure.
 - one of: token_invalid, permission_denied, no_ad_accounts, rate_limited, discovery_failed, unknown
- **timestamp** (required) `string` (date-time): No description

---

## `message.received`

Fired when a new inbox message is received. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `message.received`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: message.received
- **message** (required) `object`: 
  - **id** (required) `string`: Internal message ID
  - **conversationId** (required) `string`: Internal conversation ID
  - **platform** (required) `string`: No description - one of: instagram, facebook, telegram, whatsapp
  - **platformMessageId** (required) `string`: Platform's message ID
  - **direction** (required) `string`: No description - one of: incoming, outgoing
  - **text** (required) `string`: Message text content
  - **attachments** (required) `array[object]`: 
    - **type** (required) `string`: Attachment type (image, video, file, sticker, audio)
    - **url** (required) `string`: Attachment URL (may expire for Meta platforms)
    - **payload** `object`: Additional attachment metadata
  - **sender** (required) `object`: 
    - **id** (required) `string`: Sender's platform identifier. For WhatsApp this is the phone
number (without leading `+`) when available, otherwise the
`businessScopedUserId`.

    - **contactId** `string`: Zernio CRM Contact id for this sender, when one exists (omitted for outgoing/business sender).
    - **name** `string`: No description
    - **username** `string`: No description
    - **picture** `string`: No description
    - **phoneNumber** `string`: WhatsApp only. Sender's phone number in E.164 format (with leading `+`).

**Nullable during the BSUID rollout (April 2026+).** WhatsApp
users who adopt a username can message businesses without
exposing a phone number — this field is omitted for them.
Match by `businessScopedUserId` instead. See
`docs/whatsapp-bsuid-migration.md`.

    - **businessScopedUserId** `string`: WhatsApp only. Business-scoped user ID (BSUID) — Meta's canonical
identifier for a WhatsApp user within your business. Present
when Meta includes it in the inbound payload (rollout in
progress since early April 2026). **Recommended primary identity
anchor** going forward; fall back to `phoneNumber` only when
this field is absent.

    - **parentBusinessScopedUserId** `string`: WhatsApp only. Parent BSUID for businesses with linked business
portfolios. Omitted for standalone portfolios.

    - **whatsappUsername** `string`: WhatsApp only. User's WhatsApp username (e.g. `@jane`). Not a
stable identifier — users can change it. Useful for display,
not recommended as an identity anchor.

    - **instagramProfile** `object`: Instagram profile data for the sender. Only present for Instagram conversations.
      - **isFollower** `boolean`: Whether the sender follows your Instagram business account
      - **isFollowing** `boolean`: Whether your Instagram business account follows the sender
      - **followerCount** `integer`: The sender's follower count on Instagram
      - **isVerified** `boolean`: Whether the sender is a verified Instagram user
  - **sentAt** (required) `string` (date-time): No description
  - **isRead** (required) `boolean`: No description
- **conversation** (required): `InboxWebhookConversation` - See schema definition
- **account** (required): `InboxWebhookAccount` - See schema definition
- **metadata** `object`: Interactive message metadata (present when message is a quick reply tap, postback button tap, or inline keyboard callback)
  - **quickReplyPayload** `string`: Payload from a quick reply tap (Facebook/Instagram Messenger).
  - **postbackPayload** `string`: Payload from a postback button tap (Facebook/Instagram Messenger).
  - **postbackTitle** `string`: Title of the tapped postback button (Facebook/Instagram Messenger).
  - **callbackData** `string`: Callback data from an inline keyboard button tap (Telegram).
  - **interactiveType** `string`: WhatsApp only. Which kind of interactive reply the user sent:
`button_reply` (tap on an interactive button), `list_reply` (tap on a
list row), or `nfm_reply` (a WhatsApp Flow submission).
 - one of: button_reply, list_reply, nfm_reply
  - **interactiveId** `string`: WhatsApp only. The `id` of the tapped button or list row, matching the
`id` you supplied when the message was sent. Not set for Flow responses.

  - **buttonPayload** `string`: WhatsApp only. Payload attached to a tapped template button. Template
buttons emit a plain `button` webhook (not an interactive reply), so
`interactiveType` is empty while this field is populated.

  - **flowResponseJson** `string`: WhatsApp only. Raw `nfm_reply.response_json` string returned by a
Flow submission. Useful if you need the exact wire payload; for
typed access use `flowResponseData` instead.

  - **flowResponseData** `object`: WhatsApp only. Parsed Flow response JSON. Populated when
`flowResponseJson` is valid JSON; otherwise omitted. Keys and
value types depend on the specific Flow that was submitted.

  - **storyReply** `object`: Instagram only. Populated when an IG user replies to one of the
account's stories (Meta `messaging_story_replies`). Mutually
exclusive in practice with `isStoryMention`.

    - **storyId** (required) `string`: The Instagram story ID the user replied to.
    - **storyUrl** `string`: Meta CDN URL for the story media. Expires approximately
24 hours after the story posted; consumers must fetch
promptly or treat 404s as expected.

  - **isStoryMention** `boolean`: Instagram only. True when the message was generated by an IG
user mentioning the account in their own story (`story_mention`
attachment type). Mutually exclusive in practice with `storyReply`.

  - **referral** `object`: Ad-click attribution forwarded verbatim from Meta. Populated only on
the FIRST inbound message after the click; absent on subsequent
messages of the same conversation.

The populated subset identifies the source platform:
  - `ctwa_clid` and `source_*` fields: WhatsApp CTWA
    (Click-to-WhatsApp). Attribution window is 7 days from click.
    Forward to Meta Conversions API for Business Messaging replay.
  - `ad_id` and `ads_context_data`: Facebook Messenger CTM
    (Click-to-Message) or Instagram CTD (Click-to-Direct). Use
    `ad_id` to attribute the conversation to a specific ad.

    - **ctwa_clid** `string`: Meta's GCLID-equivalent click identifier.
    - **source_id** `string`: No description
    - **source_type** `string`: No description
    - **source_url** `string`: No description
    - **headline** `string`: No description
    - **body** `string`: No description
    - **media_type** `string`: No description
    - **image_url** `string`: No description
    - **video_url** `string`: No description
    - **thumbnail_url** `string`: No description
    - **ad_id** `string`: Facebook Messenger CTM / Instagram CTD only. The Meta ad ID the
user clicked to start the conversation.

    - **ref** `string`: Optional `ref` parameter passed through from the Meta ad
creative. Facebook Messenger CTM / Instagram CTD only.

    - **source** `string`: Meta-supplied source identifier (e.g. `ADS`). Facebook Messenger
CTM / Instagram CTD only.

    - **type** `string`: Meta-supplied referral type (e.g. `OPEN_THREAD`). Facebook
Messenger CTM / Instagram CTD only.

    - **ads_context_data** `object`: Snapshot of the ad's public context at click time. Facebook
Messenger CTM / Instagram CTD only.

      - **ad_title** `string`: No description
      - **photo_url** `string`: No description
      - **video_url** `string`: No description
      - **post_id** `string`: No description
      - **product_id** `string`: No description
      - **flow_id** `string`: No description
- **timestamp** (required) `string` (date-time): No description

---

## `message.sent`

Fired when an outgoing message is sent from the inbox. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `message.sent`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: message.sent
- **message** (required) `object`: 
  - **id** (required) `string`: Internal message ID
  - **conversationId** (required) `string`: Internal conversation ID
  - **platform** (required) `string`: No description - one of: instagram, facebook, telegram, whatsapp
  - **platformMessageId** (required) `string`: Platform's message ID
  - **direction** (required) `string`: No description - one of: incoming, outgoing
  - **text** (required) `string`: Message text content
  - **attachments** (required) `array[object]`: 
    - **type** (required) `string`: Attachment type (image, video, file, sticker, audio)
    - **url** (required) `string`: Attachment URL (may expire for Meta platforms)
    - **payload** `object`: Additional attachment metadata
  - **sender** (required) `object`: 
    - **id** (required) `string`: No description
    - **contactId** `string`: Zernio CRM Contact id for this sender, when one exists.
    - **name** `string`: No description
    - **username** `string`: No description
    - **picture** `string`: No description
  - **sentAt** (required) `string` (date-time): No description
  - **isRead** (required) `boolean`: No description
- **conversation** (required): `InboxWebhookConversation` - See schema definition
- **account** (required): `InboxWebhookAccount` - See schema definition
- **timestamp** (required) `string` (date-time): No description

---

## `conversation.started`

Fired once when a new conversation begins between one of your connected accounts and a contact, in either direction. Platform-agnostic — covers every DM platform (Instagram, Messenger/Facebook, Telegram, WhatsApp, Twitter, Reddit, Bluesky) with a single subscription. Naturally deduped: a given conversation only fires this event the very first time it appears.

Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `conversation.started`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: conversation.started
- **conversation** (required) `object`: 
  - **id** (required) `string`: Internal conversation ID
  - **platform** (required) `string`: No description - one of: instagram, facebook, telegram, whatsapp, twitter, reddit, bluesky
  - **platformConversationId** (required) `string`: No description
  - **participantId** `string`: Contact's platform identifier (IGSID
  - **participantName** (required) `string`: No description
  - **participantUsername** `string`: Contact's handle when the platform exposes one
  - **participantPicture** `string`: No description
  - **status** (required) `string`: No description - one of: active, archived
  - **contactId** `string`: Zernio CRM Contact ID for the participant, when one exists. Resolved by
joining `participantId` to the ContactChannel collection (same join
used by message.*, reaction.received, and call.* webhooks). Best-effort:
omitted when no channel matches or `participantId` is absent. Lets
integrators seed the CRM straight from `conversation.started` without
waiting for the first `message.*` event.

- **account** (required): `InboxWebhookAccount` - See schema definition
- **startedAt** (required) `string` (date-time): When the conversation document was created.
- **timestamp** (required) `string` (date-time): No description

---

## `message.edited`

Fired when the sender edits a previously-sent message. Supported on **Instagram**, **Facebook Messenger**, and **Telegram**. The payload carries the full `editHistory` (oldest prior version first) so you can reconstruct every version of the message. `message.text` is the latest version. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `message.edited`:**

- **id** (required) `string`: No description
- **event** (required) `string`: No description - one of: message.edited
- **message** (required): `InboxWebhookMessage` - See schema definition
- **editHistory** (required) `array[object]`: Prior versions of the message, oldest first.
  - **text** (required) `string`: No description
  - **attachments** (required) `array[object]`: 
    - **type** `string`: No description
    - **url** `string`: No description
    - **payload** `object`: No description
  - **editedAt** (required) `string` (date-time): No description
- **editCount** (required) `integer`: Total number of edits applied to this message.
- **editedAt** (required) `string` (date-time): When the most recent edit happened.
- **conversation** (required): `InboxWebhookConversation` - See schema definition
- **account** (required): `InboxWebhookAccount` - See schema definition
- **timestamp** (required) `string` (date-time): No description

---

## `message.deleted`

Fired when the sender deletes (unsends) a message. Supported on **Instagram** (incoming unsend) and **WhatsApp** (when the business deletes an outgoing message via the Cloud API). The payload retains the pre-delete `text` and `attachments` so API consumers can access the original content, useful for moderation, compliance, or archival. The Zernio dashboard UI does not show this content. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `message.deleted`:**

- **id** (required) `string`: No description
- **event** (required) `string`: No description - one of: message.deleted
- **message** (required): `InboxWebhookMessage` - See schema definition
- **deletedAt** (required) `string` (date-time): No description
- **conversation** (required): `InboxWebhookConversation` - See schema definition
- **account** (required): `InboxWebhookAccount` - See schema definition
- **timestamp** (required) `string` (date-time): No description

---

## `message.delivered`

Fired when an outgoing message is delivered to the recipient. Supported on **WhatsApp** and **Facebook Messenger**. Instagram doesn't emit a separate delivery event (only `message.read`). Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `message.delivered`:**

- **id** (required) `string`: No description
- **event** (required) `string`: No description - one of: message.delivered, message.read, message.failed
- **message** (required): `InboxWebhookMessage` - See schema definition
- **statusAt** (required) `string` (date-time): When the platform reported this status.
- **error** `object`: Populated only on message.failed.
  - **code** `integer`: No description
  - **title** `string`: No description
  - **message** `string`: No description
  - **explanation** `string`: Plain-language translation of `code` (e.g. for 131026, that the
recipient has likely opted out of marketing messages while utility
templates are unaffected). Null for unmapped codes; fall back to
title/message.

- **conversation** (required): `InboxWebhookConversation` - See schema definition
- **account** (required): `InboxWebhookAccount` - See schema definition
- **timestamp** (required) `string` (date-time): No description

---

## `message.read`

Fired when an outgoing message is read by the recipient. Supported on **WhatsApp**, **Facebook Messenger**, and **Instagram**. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `message.read`:**

- **id** (required) `string`: No description
- **event** (required) `string`: No description - one of: message.delivered, message.read, message.failed
- **message** (required): `InboxWebhookMessage` - See schema definition
- **statusAt** (required) `string` (date-time): When the platform reported this status.
- **error** `object`: Populated only on message.failed.
  - **code** `integer`: No description
  - **title** `string`: No description
  - **message** `string`: No description
  - **explanation** `string`: Plain-language translation of `code` (e.g. for 131026, that the
recipient has likely opted out of marketing messages while utility
templates are unaffected). Null for unmapped codes; fall back to
title/message.

- **conversation** (required): `InboxWebhookConversation` - See schema definition
- **account** (required): `InboxWebhookAccount` - See schema definition
- **timestamp** (required) `string` (date-time): No description

---

## `message.failed`

Fired when an outgoing message fails to deliver. Currently only emitted for **WhatsApp** (Messenger, Instagram, and Telegram don't expose per-message failure via webhook). The payload `error` object includes `code`, `title`, and `message` from the platform, useful for categorising failures (e.g. `131026` for "recipient phone not reachable"). Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `message.failed`:**

- **id** (required) `string`: No description
- **event** (required) `string`: No description - one of: message.delivered, message.read, message.failed
- **message** (required): `InboxWebhookMessage` - See schema definition
- **statusAt** (required) `string` (date-time): When the platform reported this status.
- **error** `object`: Populated only on message.failed.
  - **code** `integer`: No description
  - **title** `string`: No description
  - **message** `string`: No description
  - **explanation** `string`: Plain-language translation of `code` (e.g. for 131026, that the
recipient has likely opted out of marketing messages while utility
templates are unaffected). Null for unmapped codes; fall back to
title/message.

- **conversation** (required): `InboxWebhookConversation` - See schema definition
- **account** (required): `InboxWebhookAccount` - See schema definition
- **timestamp** (required) `string` (date-time): No description

---

## `reaction.received`

Fired when a participant adds or removes an emoji reaction on a message. Supported on **WhatsApp** and **Telegram** (Telegram requires the bot to be an administrator in the chat; reactions in private chats are never delivered to bots). Available on the [Usage plan](/pricing) (or AppSumo with the Inbox add-on).

This is distinct from `message.received`: a reaction is not a message. Branch on it separately so a 👍 isn't treated as an inbound DM.

- `reaction.action` is `added` or `removed`.
- `reaction.emoji` is the emoji reacted with. On WhatsApp removals the platform does not report which emoji was removed, so this may be an empty string when `action` is `removed`.
- `reaction.platformMessageId` is the platform-native id of the reacted-to message and is always present. `reaction.messageId` is the Zernio message id of that message when it can be resolved.

Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `reaction.received`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: reaction.received
- **reaction** (required) `object`: 
  - **emoji** (required) `string`: The emoji reacted with. May be an empty string when `action` is
`removed` on WhatsApp (Meta does not report which emoji was removed).

  - **action** (required) `string`: No description - one of: added, removed
  - **messageId** `string`: Internal Zernio message ID of the reacted-to message, when resolvable from the platform ID.
  - **platformMessageId** (required) `string`: Platform-native ID of the reacted-to message (e.g. WhatsApp wamid).
  - **sender** (required) `object`: The participant who added or removed the reaction.
    - **id** (required) `string`: No description
    - **contactId** `string`: Zernio CRM Contact id for this sender, when one exists.
    - **name** `string`: No description
    - **username** `string`: No description
    - **picture** `string`: No description
    - **phoneNumber** `string`: WhatsApp only. Sender's phone number in E.164 format (with leading `+`), when available.
  - **reactedAt** (required) `string` (date-time): No description
- **conversation** (required): `InboxWebhookConversation` - See schema definition
- **account** (required): `InboxWebhookAccount` - See schema definition
- **timestamp** (required) `string` (date-time): No description

---

## `comment.received`

Fired when a new comment is received on a tracked post. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

The payload includes an optional `comment.ad` object when the comment was made on paid content. For Instagram this carries `ad.id` and `ad.title` directly from the Meta webhook. For Facebook it carries `ad.promotionStatus` (`"active"` for boosted organic posts, `"ineligible"` for dark post creatives). The field is absent for comments on organic posts that are not currently promoted, so clients can filter ad-driven comments with a simple `if (comment.ad) { ... }` check.

<br />

**Payload for `comment.received`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: comment.received
- **comment** (required) `object`: 
  - **id** (required) `string`: Platform comment ID
  - **postId** (required) `string`: Internal post ID (null for posts not published through Zernio)
  - **platformPostId** (required) `string`: Platform's post ID
  - **platform** (required) `string`: No description - one of: instagram, facebook, twitter, youtube, linkedin, bluesky, reddit
  - **text** (required) `string`: Comment text content
  - **author** (required) `object`: 
    - **id** (required) `string`: Author's platform ID
    - **username** `string`: No description
    - **name** `string`: No description
    - **picture** `string`: No description
  - **createdAt** (required) `string` (date-time): No description
  - **isReply** (required) `boolean`: Whether this is a reply to another comment
  - **parentCommentId** (required) `string`: Parent comment ID if this is a reply
  - **ad** `object`: Ad context. Present only when the comment was made on paid content.
Instagram: populated from the webhook payload's value.media.ad_id and value.media.ad_title.
Facebook: populated via a Graph API lookup of the parent post's promotion_status.
Absent for comments on organic posts that are not currently promoted.

    - **id** `string`: Meta ad ID (Instagram only).
    - **title** `string`: Ad creative title (Instagram only).
    - **promotionStatus** `string`: Facebook promotion status returned by Graph API. Common values:
"active" (organic post currently boosted), "ineligible" (dark
post or ad creative, not promotable because it already is an ad).

- **post** (required) `object`: 
  - **id** (required) `string`: Internal post ID (null for posts not published through Zernio)
  - **platformPostId** (required) `string`: Platform's post ID
- **account** (required) `object`: 
  - **id** (required) `string`: Social account ID
  - **platform** (required) `string`: No description
  - **username** (required) `string`: No description
- **timestamp** (required) `string` (date-time): No description

---

## `review.new`

Fired when a new review is posted on a connected account. Currently supported for Google Business Profile (real-time via Pub/Sub). Available on the [Usage plan](/pricing) (or AppSumo with the Inbox add-on). Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `review.new`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: review.new
- **review** (required): `ReviewWebhookReview` - See schema definition
- **account** (required) `object`: 
  - **id** (required) `string`: No description
  - **platform** (required) `string`: No description
  - **username** (required) `string`: No description
- **timestamp** (required) `string` (date-time): No description

---

## `review.updated`

Fired when a review changes: the reviewer edits their text or rating, or a reply is added (via the API or directly through the Google Business dashboard). Available on the [Usage plan](/pricing) (or AppSumo with the Inbox add-on). The payload has the same shape as `review.new`; when a reply is present, `review.hasReply` is `true` and `review.reply` is populated. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `review.updated`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: review.updated
- **review** (required): `ReviewWebhookReview` - See schema definition
- **account** (required) `object`: 
  - **id** (required) `string`: No description
  - **platform** (required) `string`: No description
  - **username** (required) `string`: No description
- **timestamp** (required) `string` (date-time): No description

---

## `lead.received`

Fired when a new lead is submitted against a Meta Lead Gen (Instant) Form and ingested in real time via the Page `leadgen` webhook. Requires the Ads add-on.

`lead.fields` is the flattened question-key to answer map (for multiple-choice questions the value is the option key, e.g. `k1`, not the display label). `lead.formId` / `lead.adId` / `lead.campaignId` give provenance; `lead.adId` is null for organic or test leads. Use `lead.leadgenId` (Meta's lead ID) or the canonical event `id` as your dedup key.

Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `lead.received`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: lead.received
- **lead** (required) `object`: 
  - **id** (required) `string`: Zernio lead ID (AdLead document ID)
  - **leadgenId** (required) `string`: Meta lead ID (the platform's leadgen_id)
  - **formId** (required) `string`: Lead Gen form ID the lead was submitted against
  - **formName** `string`: Human-readable form name (best-effort; may be null)
  - **adId** `string`: Meta ad ID that drove the lead (null for organic/test leads)
  - **adsetId** `string`: No description
  - **campaignId** `string`: No description
  - **fields** (required) `object`: Flattened question key -> answer map. For multiple-choice questions the value is the option key (e.g. "k1"), not the display label.

  - **isOrganic** (required) `boolean`: True when the lead came from an organic post rather than a paid ad
  - **createdAt** (required) `string` (date-time): Meta's lead creation time (ISO 8601)
- **account** (required) `object`: 
  - **id** (required) `string`: Social account ID (the facebook account owning the Page)
  - **platform** (required) `string`: No description - one of: facebook
- **timestamp** (required) `string` (date-time): No description

---

## `ad.status_changed`

Fired when a campaign, ad set, or ad on a connected ad platform changes status. Currently emitted only for **Meta** (`metaads`).

The event is sourced from two Meta `ad_account` webhook fields:
- `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`, `PENDING_REVIEW`, `ARCHIVED`, `DELETED`, `DISAPPROVED`).
- `with_issues_ad_objects` — the ad object entered the `WITH_ISSUES` state. `status.raw` is set to `WITH_ISSUES` and the `error` block is populated from Meta's `error_code` / `error_summary` / `error_message`.

`adObject.level` is one of `CAMPAIGN`, `AD_SET`, or `AD`; creative-level events are not forwarded. Branch on `status.raw` to handle each transition, and use `error.code` (when present) as the stable discriminator — `error.summary` and `error.message` are localized to the ad-account owner's Meta locale.

The `error` block is optional. It's present on most `WITH_ISSUES` events but can be absent (Meta does not always include diagnostics), and is never present on any other status. Always null-check `error` before reading `error.code`.

**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.

Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `ad.status_changed`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: ad.status_changed
- **account** (required) `object`: The connected ad-platform account that owns the ad object.
  - **accountId** (required) `string`: Internal Zernio account ID (same as used in /v1/accounts/{accountId}).
  - **profileId** (required) `string`: Internal Zernio profile ID this account belongs to.
  - **platform** (required) `string`: Ad platform identifier. Currently always `metaads`. (example: "metaads")
  - **username** (required) `string`: Display username of the connected ad-platform account.
  - **displayName** `string`: Human-readable display name of the account, when available.
- **adObject** (required) `object`: The ad-platform object the status change applies to.
  - **level** (required) `string`: Hierarchy level the status applies to. Mirrors Meta's `level`. Creative-level events are not forwarded. - one of: CAMPAIGN, AD_SET, AD
  - **platformId** (required) `string`: Platform-native ID of the campaign / ad set / ad. For Meta this is
the bare numeric ID (e.g. `120244894077860689`).
 (example: "120244894077860689")
  - **platformAdAccountId** (required) `string`: Platform-native ad-account ID. For Meta this uses the `act_<id>`
shape.
 (example: "act_2129800524463520")
- **status** (required) `object`: Status info. Branch on `status.raw` to handle each transition.
  - **raw** (required) `string`: Platform-native status string, forwarded verbatim. For Meta
this is `status_name` from `in_process_ad_objects` (e.g.
`ACTIVE`, `PAUSED`, `PENDING_REVIEW`, `ARCHIVED`, `DELETED`,
`DISAPPROVED`), or `WITH_ISSUES` when sourced from
`with_issues_ad_objects`. Not constrained by an `enum` — Meta
may add new values.
 (example: "ACTIVE")
- **error** `object`: Optional. Present on most `WITH_ISSUES` events, carrying the
platform's error diagnostics. May be absent on some `WITH_ISSUES`
events (Meta does not always include diagnostics). Always absent
for any other `status.raw` value. Always null-check before reading.

  - **code** (required) `string`: Platform-native error code, forwarded verbatim. For Meta this
is `error_code` as a string. Use as the stable discriminator —
`summary` and `message` are localized.
 (example: "2643001")
  - **summary** `string`: Short human-readable summary (Meta `error_summary`). Localized
to the ad-account owner's Meta locale — display only, do not
match on it.
 (example: "Ad Processing Error")
  - **message** `string`: Full human-readable error message (Meta `error_message`).
Localized — display only.

- **timestamp** (required) `string` (date-time): ISO-8601 timestamp the webhook was produced.

---

## `call.received`

Fired when an inbound WhatsApp call reaches one of your numbers and is routed to its configured destination (an AI voice agent, SIP endpoint, or phone number). The payload carries the Zernio call id, caller and business numbers, the destination snapshot (`forwardTo`), and `contactId`/`conversationId` links into the inbox so you can message the caller, during the call or after, with the regular send APIs. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `call.received`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: call.received
- **call** (required) `object`: 
  - **id** `string`: Internal Zernio Call doc id
  - **metaCallId** `string`: Meta wacid.* call id when known
  - **accountId** `string`: No description
  - **phoneNumberId** `string`: Meta phone_number_id
  - **direction** `string`: No description - one of: inbound, outbound
  - **from** `string`: Consumer wa_id / E.164
  - **to** `string`: Business number (E.164)
  - **forwardTo** `string`: Destination snapshot at routing time
  - **contactId** `string`: No description
  - **conversationId** `string`: No description
  - **startedAt** `string` (date-time): No description
- **account** (required): `InboxWebhookAccount` - See schema definition
- **timestamp** (required) `string` (date-time): No description

---

## `call.ended`

Fired when a WhatsApp call ends. Carries `durationSeconds`, the `endReason` (`hangup`, `no_answer`, `rejected`, `error`), a cost breakdown under `call.billing`, and, when recording is enabled on the number, a `recordingUrl` with its expiry. The classic automation here is a missed-call follow-up: on `endReason: "no_answer"`, text the caller back over the linked `conversationId`. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `call.ended`:**

- **id** (required) `string`: No description
- **event** (required) `string`: No description - one of: call.ended
- **call** (required) `object`: 
  - **id** `string`: No description
  - **metaCallId** `string`: No description
  - **accountId** `string`: No description
  - **phoneNumberId** `string`: No description
  - **direction** `string`: No description - one of: inbound, outbound
  - **from** `string`: No description
  - **to** `string`: No description
  - **startedAt** `string` (date-time): No description
  - **endedAt** `string` (date-time): No description
  - **durationSeconds** `integer`: No description
  - **endReason** `string`: No description - one of: hangup, no_answer, rejected, error
  - **recordingUrl** `string`: No description
  - **recordingExpiresAt** `string` (date-time): No description
  - **billing** `object`: 
    - **metaCostUSD** `number`: 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** `number`: No description
    - **recordingCostUSD** `number`: No description
    - **billableCostUSD** `number`: The amount Zernio bills you = Telnyx leg + recording. Excludes Meta (billed by Meta directly).
    - **totalCostUSD** `number`: Full economic cost incl. the Meta portion you pay directly (Meta + Telnyx + recording). Display only, not the Zernio-billed amount.
- **account** (required): `InboxWebhookAccount` - See schema definition
- **timestamp** (required) `string` (date-time): No description

---

## `call.failed`

Fired when a WhatsApp call fails with a hard error before or during bridging (for example, the destination rejected the SIP INVITE). Carries the platform error `code` and `message`. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `call.failed`:**

- **id** (required) `string`: No description
- **event** (required) `string`: No description - one of: call.failed
- **call** (required) `object`: 
  - **id** `string`: No description
  - **metaCallId** `string`: No description
  - **accountId** `string`: No description
  - **phoneNumberId** `string`: No description
  - **direction** `string`: No description - one of: inbound, outbound
  - **from** `string`: No description
  - **to** `string`: No description
  - **failedAt** `string` (date-time): No description
  - **error** `object`: 
    - **code** `integer`: No description
    - **message** `string`: No description
- **account** (required): `InboxWebhookAccount` - See schema definition
- **timestamp** (required) `string` (date-time): No description

---

## `call.permission_request`

Fired when a WhatsApp user responds to your call-permission request (business-initiated calls require one). Carries the user's number, their `response` (`accept` or `reject`), whether it is permanent, and the expiry when it is not. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `call.permission_request`:**

- **id** (required) `string`: No description
- **event** (required) `string`: No description - one of: call.permission_request
- **permission** (required) `object`: 
  - **from** `string`: Consumer wa_id who replied
  - **response** `string`: No description - one of: accept, reject
  - **isPermanent** `boolean`: No description
  - **expirationTimestamp** `string` (date-time): Present only when temporary
  - **responseSource** `string`: Meta's response source, typically `user_action`
- **account** (required): `InboxWebhookAccount` - See schema definition
- **timestamp** (required) `string` (date-time): No description

---

## `whatsapp.number.activated`

Fired when a WhatsApp number you provisioned through Zernio finishes setup and is ready to connect. For regulated (non-US) numbers this can take 1-3 business days after the order is approved, so the webhook saves you from polling. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `whatsapp.number.activated`:**

- **id** `string`: No description
- **event** `string`: No description - one of: whatsapp.number.activated
- **timestamp** `string` (date-time): No description
- **number** `object`: 
  - **id** `string`: No description
  - **phoneNumber** `string`: No description
  - **country** `string`: No description
  - **profileId** `string`: No description

---

## `whatsapp.number.declined`

Fired when a regulated number order is declined during regulatory review and no number is activated. The order never activates and you are never billed for it. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `whatsapp.number.declined`:**

- **id** `string`: No description
- **event** `string`: No description - one of: whatsapp.number.declined
- **timestamp** `string` (date-time): No description
- **number** `object`: 
  - **id** `string`: No description
  - **phoneNumber** `string`: No description
  - **country** `string`: No description
  - **profileId** `string`: No description
- **reason** `string`: No description

---

## `whatsapp.number.action_required`

Fired when the regulator reviewing an already-placed number order asks for more information (for example, a certificate of company incorporation). Nothing was rejected: the order stays pending, but it will not progress until the information is provided. `reason` carries the regulator's request verbatim when available. Provide the missing details from the dashboard's phone-numbers page, or re-submit the relevant fields via the remediation endpoint; the review resumes automatically. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `whatsapp.number.action_required`:**

- **id** `string`: No description
- **event** `string`: No description - one of: whatsapp.number.action_required
- **timestamp** `string` (date-time): No description
- **reason** `string`: No description
- **number** `object`: 
  - **id** `string`: No description
  - **phoneNumber** `string`: No description
  - **country** `string`: No description
  - **profileId** `string`: No description

---

## `whatsapp.number.verification_required`

Fired when a regulated number requires the end user to complete an identity check (for example, Australian mobile numbers). The payload carries a one-time `verificationUrl` to forward to the person whose ID is on file; the order completes once they pass. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `whatsapp.number.verification_required`:**

- **id** `string`: No description
- **event** `string`: No description - one of: whatsapp.number.verification_required
- **timestamp** `string` (date-time): No description
- **number** `object`: 
  - **id** `string`: No description
  - **phoneNumber** `string`: No description
  - **country** `string`: No description
  - **profileId** `string`: No description
- **verificationUrl** `string`: No description

---

## `whatsapp.number.suspended`

Fired when an active number is suspended, for example after a failed payment. The number stops working until the issue is resolved, after which a `whatsapp.number.reactivated` event is sent. The payload carries a `reason` (such as `payment_failed` or `subscription_ended`). Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `whatsapp.number.suspended`:**

- **id** `string`: No description
- **event** `string`: No description - one of: whatsapp.number.suspended
- **timestamp** `string` (date-time): No description
- **number** `object`: 
  - **id** `string`: No description
  - **phoneNumber** `string`: No description
  - **country** `string`: No description
  - **profileId** `string`: No description
- **reason** `string`: No description

---

## `whatsapp.number.reactivated`

Fired when a suspended number is reactivated (for example, the payment recovered) and is usable again. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `whatsapp.number.reactivated`:**

- **id** `string`: No description
- **event** `string`: No description - one of: whatsapp.number.reactivated
- **timestamp** `string` (date-time): No description
- **number** `object`: 
  - **id** `string`: No description
  - **phoneNumber** `string`: No description
  - **country** `string`: No description
  - **profileId** `string`: No description

---

## `whatsapp.number.released`

Fired when a number is released and is no longer usable, whether you released it, a billing cleanup released it, or an admin did. This is terminal. The payload carries a `reason` (such as `user_requested` or `cleanup_suspended`). Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `whatsapp.number.released`:**

- **id** `string`: No description
- **event** `string`: No description - one of: whatsapp.number.released
- **timestamp** `string` (date-time): No description
- **number** `object`: 
  - **id** `string`: No description
  - **phoneNumber** `string`: No description
  - **country** `string`: No description
  - **profileId** `string`: No description
- **reason** `string`: No description

---

## `webhook.test`

Fired when sending a test webhook to verify the endpoint configuration. Subscribe with [Create webhook settings](/webhooks/create-webhook-settings) or [Update webhook settings](/webhooks/update-webhook-settings).

<br />

**Payload for `webhook.test`:**

- **id** (required) `string`: Stable webhook event ID
- **event** (required) `string`: No description - one of: webhook.test
- **message** (required) `string`: Human-readable test message
- **timestamp** (required) `string` (date-time): No description

---

# Bluesky

Schedule and automate Bluesky posts with Zernio API - Text posts, images, videos, threads, and App Password authentication

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Reference

| Property | Value |
|----------|-------|
| Character limit | 300 (HARD LIMIT) |
| Images per post | 4 |
| Videos per post | 1 |
| Image formats | JPEG, PNG, WebP, GIF |
| Image max size | 1 MB (auto-compressed, strict) |
| Video format | MP4 only |
| Video max size | 50 MB |
| Video max duration | 60 seconds |
| Post types | Text, Image, Video, Thread |
| Scheduling | Yes |
| Inbox (DMs) | Yes (text only) |
| Inbox (Comments) | Yes |
| Analytics | No |

## Before You Start

<Callout type="warn">
Bluesky has a **HARD 300 character limit**. This is the **#1 cause of failed posts** -- 95% of all Bluesky failures are character limit exceeded. If you're cross-posting from ANY other platform (Twitter 280 is close but others are 500-63,000 chars), you **MUST** use `customContent` to provide a Bluesky-specific shorter version or your post **WILL** fail.

Bluesky's image limit is **1 MB per image** -- much stricter than any other platform. Most phone photos are 3-5 MB. Zernio auto-compresses, but quality may degrade.

Additional requirements:
- Uses App Passwords, not OAuth (handle + app password from Bluesky Settings)
- 300 char limit includes everything (text, URLs, mentions)
- Each thread item is also limited to 300 characters
- Images are strictly 1 MB per image
</Callout>

## Quick Start

Post to Bluesky in under 60 seconds:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Hello from Zernio API!',
  platforms: [
    { platform: 'bluesky', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to Bluesky!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Hello from Zernio API!",
    platforms=[
        {"platform": "bluesky", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to Bluesky! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from Zernio API!",
    "platforms": [
      {"platform": "bluesky", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

### Text Post

A simple text-only post. Keep it under 300 characters.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Just shipped a new feature!',
  platforms: [
    { platform: 'bluesky', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to Bluesky!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Just shipped a new feature!",
    platforms=[
        {"platform": "bluesky", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to Bluesky! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Just shipped a new feature!",
    "platforms": [
      {"platform": "bluesky", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Image Post

Attach up to 4 images per post. JPEG, PNG, WebP, and GIF formats are supported. Each image must be under 1 MB.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Check out this photo!',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/photo.jpg' }
  ],
  platforms: [
    { platform: 'bluesky', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted with image!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Check out this photo!",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/photo.jpg"}
    ],
    platforms=[
        {"platform": "bluesky", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted with image! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out this photo!",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/photo.jpg"}
    ],
    "platforms": [
      {"platform": "bluesky", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

#### Multi-Image Post

Attach up to 4 images. Remember: each image must be under 1 MB.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Product launch gallery',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/photo1.jpg' },
    { type: 'image', url: 'https://cdn.example.com/photo2.jpg' },
    { type: 'image', url: 'https://cdn.example.com/photo3.jpg' },
    { type: 'image', url: 'https://cdn.example.com/photo4.jpg' }
  ],
  platforms: [
    { platform: 'bluesky', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Multi-image post created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Product launch gallery",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/photo1.jpg"},
        {"type": "image", "url": "https://cdn.example.com/photo2.jpg"},
        {"type": "image", "url": "https://cdn.example.com/photo3.jpg"},
        {"type": "image", "url": "https://cdn.example.com/photo4.jpg"}
    ],
    platforms=[
        {"platform": "bluesky", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Multi-image post created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Product launch gallery",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/photo1.jpg"},
      {"type": "image", "url": "https://cdn.example.com/photo2.jpg"},
      {"type": "image", "url": "https://cdn.example.com/photo3.jpg"},
      {"type": "image", "url": "https://cdn.example.com/photo4.jpg"}
    ],
    "platforms": [
      {"platform": "bluesky", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Video Post

Attach a single video per post. MP4 format only, up to 50 MB, max 60 seconds.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'New product demo',
  mediaItems: [
    { type: 'video', url: 'https://cdn.example.com/demo.mp4' }
  ],
  platforms: [
    { platform: 'bluesky', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Video post created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="New product demo",
    media_items=[
        {"type": "video", "url": "https://cdn.example.com/demo.mp4"}
    ],
    platforms=[
        {"platform": "bluesky", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Video post created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New product demo",
    "mediaItems": [
      {"type": "video", "url": "https://cdn.example.com/demo.mp4"}
    ],
    "platforms": [
      {"platform": "bluesky", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Thread

Create Bluesky threads with multiple connected posts using `platformSpecificData.threadItems`. Each item becomes a reply to the previous post and can have its own content and media. Each thread item is limited to 300 characters.

> **Note:** 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]`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  platforms: [{
    platform: 'bluesky',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      threadItems: [
        {
          content: 'A thread about building APIs',
          mediaItems: [{ type: 'image', url: 'https://cdn.example.com/api.jpg' }]
        },
        { content: 'First, design your endpoints around resources, not actions.' },
        { content: 'Second, always version your API from day one.' },
        { content: 'Finally, document everything! Your future self will thank you.' }
      ]
    }
  }],
  publishNow: true
});
console.log('Thread posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    platforms=[{
        "platform": "bluesky",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "threadItems": [
                {
                    "content": "A thread about building APIs",
                    "mediaItems": [{"type": "image", "url": "https://cdn.example.com/api.jpg"}]
                },
                {"content": "First, design your endpoints around resources, not actions."},
                {"content": "Second, always version your API from day one."},
                {"content": "Finally, document everything! Your future self will thank you."}
            ]
        }
    }],
    publish_now=True
)
post = result.post
print(f"Thread posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": [{
      "platform": "bluesky",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "threadItems": [
          {
            "content": "A thread about building APIs",
            "mediaItems": [{"type": "image", "url": "https://cdn.example.com/api.jpg"}]
          },
          {
            "content": "First, design your endpoints around resources, not actions."
          },
          {
            "content": "Second, always version your API from day one."
          },
          {
            "content": "Finally, document everything! Your future self will thank you."
          }
        ]
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Media Requirements

### Images

| Property | Requirement |
|----------|-------------|
| **Max images** | 4 per post |
| **Formats** | JPEG, PNG, WebP, GIF |
| **Max file size** | 1 MB per image (strict) |
| **Max dimensions** | 2000 x 2000 px |
| **Recommended** | 1200 x 675 px (16:9) |

#### Aspect Ratios

| Type | Ratio | Dimensions |
|------|-------|------------|
| Landscape | 16:9 | 1200 x 675 px |
| Square | 1:1 | 1000 x 1000 px |
| Portrait | 4:5 | 800 x 1000 px |

### Videos

| Property | Requirement |
|----------|-------------|
| **Max videos** | 1 per post |
| **Format** | MP4 only |
| **Max file size** | 50 MB |
| **Max duration** | 60 seconds |
| **Max dimensions** | 1920 x 1080 px |
| **Frame rate** | 30 fps recommended |

#### Recommended Video Specs

| Property | Recommended |
|----------|-------------|
| Resolution | 1280 x 720 px (720p) |
| Aspect ratio | 16:9 (landscape) or 1:1 (square) |
| Frame rate | 30 fps |
| Codec | H.264 |
| Audio | AAC |

## Platform-Specific Fields

All fields go inside `platformSpecificData` on the Bluesky platform entry.

| Field | Type | Description |
|-------|------|-------------|
| `threadItems` | Array\<\{content, mediaItems?\}\> | Complete sequence of posts in a Bluesky thread. The first item becomes the root post and must be provided as `threadItems[0]`. When `threadItems` is provided, top-level `content` is for display/search only and is NOT published. |

## Connection

Bluesky uses **App Passwords** instead of OAuth. To connect a Bluesky account:

1. Go to your Bluesky Settings > App Passwords
2. Create a new App Password (formatted as `xxxx-xxxx-xxxx-xxxx`)
3. Use the connect endpoint with your handle and app password
4. Custom domain handles are supported (e.g., `brand.com` instead of `brand.bsky.social`)

<Tabs items={['Python', 'curl']}>
<Tab value="Python">
```python
account = client.connect.connect_bluesky_credentials(
    identifier="yourhandle.bsky.social",
    app_password="xxxx-xxxx-xxxx-xxxx",
    state="profile_id=YOUR_PROFILE_ID",
)
print(f"Connected: {account['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/connect/bluesky/credentials \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "yourhandle.bsky.social",
    "appPassword": "xxxx-xxxx-xxxx-xxxx",
    "state": "profile_id=YOUR_PROFILE_ID"
  }'
```
</Tab>
</Tabs>

<Callout type="info">
The Node SDK (`@zernio/node`) does not yet expose `connect.connectBlueskyCredentials`. Use the Python SDK or hit the endpoint directly via fetch.
</Callout>

## Rich Text

Zernio auto-detects and converts text to AT Protocol facets. No special formatting is needed from developers:

- `@handle.bsky.social` -- rendered as a clickable profile link
- `#hashtag` -- rendered as a clickable hashtag
- URLs -- rendered as clickable links with preview cards

When your post contains a URL, Bluesky automatically generates a link card preview. For best results, place the URL at the end of your post and ensure the target page has proper Open Graph meta tags.

## Media URL Requirements

<Callout type="error">
**These do not work as media URLs:**
- **Google Drive** -- returns an HTML download page, not the file
- **Dropbox** -- returns an HTML preview page
- **OneDrive / SharePoint** -- returns HTML
- **iCloud** -- returns HTML

Test your URL in an incognito browser window. If you see a webpage instead of the raw image or video, it will not work.
</Callout>

Media URLs must be:
- Publicly accessible (no authentication required)
- Returning actual media bytes with the correct `Content-Type` header
- Not behind redirects that resolve to HTML pages
- Hosted on a fast, reliable CDN

**Supabase URLs:** Zernio auto-proxies Supabase storage URLs, so they work without additional configuration.

## Analytics

> **Included** — Analytics is bundled with every paid account on the [Usage plan](/pricing).

Available metrics via the [Analytics API](/analytics/get-analytics):

| Metric | Available |
|--------|-----------|
| Likes | ✅ |
| Comments | ✅ |
| Shares (reposts) | ✅ |

Bluesky does not provide impressions, reach, clicks, or view counts through its API.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const analytics = await zernio.analytics.getAnalytics({
  platform: 'bluesky',
  fromDate: '2024-01-01',
  toDate: '2024-01-31'
});
console.log(analytics.posts);
```
</Tab>
<Tab value="Python">
```python
analytics = client.analytics.get_analytics(
    platform="bluesky",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(analytics["posts"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics?platform=bluesky&fromDate=2024-01-01&toDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

## What You Can't Do

These features are not available through Bluesky's API:

- Create lists or starter packs
- Create custom feeds
- Pin posts to profile
- Add content warnings or labels
- Send DM attachments (Bluesky's Chat API does not support media)
- See follower counts or profile analytics

## Common Errors

Bluesky has a **19.3% failure rate** across Zernio's platform (3,633 failures out of 18,857 attempts). Here are the most frequent errors and how to fix them:

| Error | What it means | How to fix |
|-------|---------------|------------|
| "Bluesky posts cannot exceed 300 characters" | Content exceeds the 300 char hard limit | Shorten to 300 chars. Use `customContent` for cross-platform posts. |
| "Thread item N exceeds 300 characters" | A specific thread item is too long | Each thread item has its own 300 char limit. Split into more items. |
| "Publishing failed due to max retries reached" | All retries failed | Usually temporary. Retry manually. |
| App Password invalid | Wrong password type or expired credentials | Ensure you're using an App Password (`xxxx-xxxx-xxxx-xxxx`), not your main account password. Create a new one if needed. |
| Image too large | Image exceeds 1 MB limit | Compress images before upload. Zernio auto-compresses, but may degrade quality. |

## Inbox

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

Bluesky supports DMs and comments.

### Direct Messages

| Feature | Supported |
|---------|-----------|
| List conversations | ✅ |
| Fetch messages | ✅ |
| Send text messages | ✅ |
| Send attachments | ❌ (API limitation) |
| Archive/unarchive | ✅ |

### Comments

| Feature | Supported |
|---------|-----------|
| List comments on posts | ✅ |
| Reply to comments | ✅ |
| Delete comments | ✅ |
| Like comments | ✅ (requires CID) |
| Unlike comments | ✅ (requires likeUri) |

### Limitations

- **No DM attachments** - Bluesky's Chat API does not support media
- **Like requires CID** - You must provide the content identifier (`cid`) when liking a comment
- **Unlike requires likeUri** - Store the `likeUri` returned when liking to unlike later

See [Messages](/messages/list-inbox-conversations) and [Comments](/comments/list-inbox-comments) API Reference for endpoint details.

## Related Endpoints

- [Connect Bluesky Account](/guides/connecting-accounts) - App Password authentication
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Image and video uploads
- [Messages](/messages/list-inbox-conversations) and [Comments](/comments/list-inbox-comments)

---

# Discord

Send messages, DMs, embeds, polls, forum posts, threads, schedule events, and manage roles in Discord servers with Zernio API - No bot hosting, no gateway, no intents approval

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Reference

| Property | Value |
|----------|-------|
| Content limit | 2,000 characters (message content) |
| Embeds per message | 10 (max 6,000 chars total) |
| Images per message | Up to 10 attachments |
| Image formats | JPEG, PNG, GIF, WebP |
| Image max size | 25 MB (higher on boosted servers) |
| Video formats | MP4, MOV, WebM |
| Video max size | 25 MB (up to 500 MB on boosted servers) |
| Post types | Messages, Embeds, Polls, Forum Posts, Threads |
| Scheduling | Yes |
| Direct Messages | Outbound only |
| Role management | Yes (list / assign / remove) |
| Member listing | Yes (cursor pagination) |
| Pinned messages | Yes (list / pin / unpin) |
| Scheduled Events | Yes (create / list / update / cancel / delete) |
| Inbox (DM replies) | No (Discord requires a Gateway connection) |
| Inbox (Comments) | No |
| Analytics | No (Discord Bot API limit) |

## Before You Start

<Callout type="warn">
Discord integration uses a **centralized bot token** model. You do NOT need to create a Discord Application, request privileged intents, or host a gateway connection. You add the Zernio bot to your server via OAuth and POST to our REST API.

Key points:
- **No bot hosting required** - we manage the bot infrastructure
- **No intents approval** - MESSAGE_CONTENT and other privileged intents are handled at the bot level
- **No gateway/sharding** - you never connect a WebSocket; everything is REST
- The bot needs: Send Messages, Embed Links, Attach Files, Send Messages in Threads, Create Public Threads, Manage Messages (for pin/unpin), Manage Roles (for role assignment), and Manage Events (for scheduled events) permissions - all granted at install time on new connections.
- **Already-connected servers**: existing Zernio installs predate the Manage Roles and Manage Events permissions. If those endpoints return 502, ask a server admin to either re-invite the bot (picks up new permissions automatically) or manually grant the missing permission on the bot's role in Server Settings → Roles.
</Callout>

<Callout type="info">
**Note on the Server Members Intent**: the `GET /v1/discord/guilds/{guildId}/members` endpoint requires the "Server Members Intent" enabled on the Zernio Discord app. This is on by default for new bot installs. If listing members returns an empty array with no error, this intent is the likely cause.
</Callout>

## Quick Start

Send a message to a Discord channel:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Hello from Zernio API!',
  platforms: [
    {
      platform: 'discord',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: {
        channelId: '1234567890'
      }
    }
  ],
  publishNow: true
});
console.log('Posted to Discord!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Hello from Zernio API!",
    platforms=[
        {
            "platform": "discord",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {
                "channelId": "1234567890"
            }
        }
    ],
    publish_now=True,
)
print(f"Posted to Discord! {result.post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from Zernio API!",
    "platforms": [
      {
        "platform": "discord",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "channelId": "1234567890"
        }
      }
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Connection

Discord uses OAuth2 with our centralized bot:

1. Call `GET /v1/connect/discord?profileId=YOUR_PROFILE_ID` to get the bot invite URL
2. The user authorizes the bot to join their server
3. After authorization, the user selects which channel to post to via `/connect/discord/select-channel`
4. The connected account appears in `GET /v1/accounts`

Each connected account represents one Discord server. The `channelId` in `platformSpecificData` determines which channel receives the message.

## Webhook Identity (Bot Customization)

By default, messages are posted as "Zernio" with the bot's avatar. You can customize the display name and avatar at two levels:

**Account-level default** (applies to every post from this account):

```bash
curl -X PATCH https://zernio.com/api/v1/connect/discord \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_ACCOUNT_ID",
    "webhookUsername": "My Brand",
    "webhookAvatarUrl": "https://example.com/logo.png"
  }'
```

**Per-post override** (overrides account default for a single post):

```json
{
  "platforms": [{
    "platform": "discord",
    "accountId": "YOUR_ACCOUNT_ID",
    "platformSpecificData": {
      "channelId": "1234567890",
      "webhookUsername": "Special Announcement",
      "webhookAvatarUrl": "https://example.com/special-logo.png"
    }
  }],
  "publishNow": true
}
```

<Callout type="info">
Webhook usernames must be 1-80 characters and cannot contain "clyde" or "discord". Send an empty string to reset to the default ("Zernio").
</Callout>

## Embeds

Send rich embedded content alongside or instead of plain text:

```json
{
  "content": "New release shipping today!",
  "platforms": [{
    "platform": "discord",
    "accountId": "YOUR_ACCOUNT_ID",
    "platformSpecificData": {
      "channelId": "1234567890",
      "embeds": [{
        "title": "v2.3.0 Release Notes",
        "description": "Dark mode, new API endpoints, faster uploads.",
        "color": 5814783,
        "url": "https://example.com/changelog",
        "footer": { "text": "Shipped today" },
        "fields": [
          { "name": "New Features", "value": "3", "inline": true },
          { "name": "Bug Fixes", "value": "12", "inline": true }
        ]
      }]
    }
  }],
  "publishNow": true
}
```

Each message supports up to **10 embeds** with a combined character limit of 6,000 across all embed fields.

## Native Polls

Create Discord-native polls (same UX as the Discord client):

```json
{
  "platforms": [{
    "platform": "discord",
    "accountId": "YOUR_ACCOUNT_ID",
    "platformSpecificData": {
      "channelId": "1234567890",
      "poll": {
        "question": { "text": "Ship it now or wait until Monday?" },
        "answers": [
          { "poll_media": { "text": "Ship now" } },
          { "poll_media": { "text": "Wait for Monday" } }
        ],
        "duration": 24,
        "allow_multiselect": false
      }
    }
  }],
  "publishNow": true
}
```

| Poll Property | Value |
|---------------|-------|
| Max answers | 10 |
| Duration range | 1 - 768 hours (32 days) |
| Default duration | 24 hours |
| Multi-select | Optional (default: false) |

<Callout type="info">
Polls are standalone messages. You cannot combine a poll with media attachments in the same message (Discord API limitation).
</Callout>

## Forum Posts

Post starter messages to forum channels (type 15):

```json
{
  "content": "Community call notes for January 15",
  "platforms": [{
    "platform": "discord",
    "accountId": "YOUR_ACCOUNT_ID",
    "platformSpecificData": {
      "channelId": "9999999999",
      "forumThreadName": "Community Call - Jan 15",
      "forumAppliedTags": ["11111111", "22222222"]
    }
  }],
  "publishNow": true
}
```

- `forumThreadName` (required for forum channels) becomes the thread title
- `forumAppliedTags` are snowflake IDs of existing forum tags (max 5 tags per post)
- Use `listForumTags(channelId)` to discover available tags

## Threads

Create a follow-up thread under any published message:

```json
{
  "content": "Main announcement here",
  "platforms": [{
    "platform": "discord",
    "accountId": "YOUR_ACCOUNT_ID",
    "platformSpecificData": {
      "channelId": "1234567890",
      "threadFromMessage": {
        "name": "Discussion Thread",
        "autoArchiveDuration": 1440,
        "rateLimitPerUser": 0
      }
    }
  }],
  "publishNow": true
}
```

`autoArchiveDuration` options: 60, 1440 (1 day), 4320 (3 days), or 10080 (7 days) minutes. `rateLimitPerUser` sets slow-mode in seconds (0-21600).

## Announcement Crosspost

Auto-crosspost messages from announcement channels (type 5) so followers in other servers receive them:

```json
{
  "platformSpecificData": {
    "channelId": "ANNOUNCEMENT_CHANNEL_ID",
    "crosspost": true
  }
}
```

This is a no-op for regular text channels.

## Edit & Delete

- **Edit:** `PUT /v1/posts/{postId}` updates the Discord message content and embeds
- **Delete:** `DELETE /v1/posts/{postId}` deletes the Discord message or cancels a scheduled one

## Rate Limits

Discord applies per-channel, per-guild, and global rate limits. Zernio handles 429 responses with exponential backoff and respects the `X-RateLimit-Reset-After` header automatically. You never need to implement retry logic.

## platformSpecificData Reference

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `channelId` | string | Yes | Target channel snowflake ID |
| `embeds` | array | No | Up to 10 Discord embed objects (6,000 chars total) |
| `poll` | object | No | Native poll (question, answers, duration). Cannot combine with media |
| `crosspost` | boolean | No | Auto-crosspost in announcement channels |
| `forumThreadName` | string | Forum channels | Thread title for forum starter message |
| `forumAppliedTags` | string[] | No | Tag snowflake IDs for forum posts (max 5) |
| `threadFromMessage` | object | No | Create a thread under the published message |
| `threadFromMessage.rateLimitPerUser` | number | No | Slow-mode seconds for thread (0-21600) |
| `tts` | boolean | No | Text-to-speech message |
| `webhookUsername` | string | No | Override display name for this post (1-80 chars) |
| `webhookAvatarUrl` | string | No | Override avatar URL for this post |

## Channel Management

List available channels in the connected guild:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { channels } = await zernio.discord.getDiscordChannels({
  path: { accountId: 'YOUR_ACCOUNT_ID' },
});
```
</Tab>
<Tab value="Python">
```python
res = client.discord.get_discord_channels(account_id="YOUR_ACCOUNT_ID")
```
</Tab>
<Tab value="curl">
```bash
curl https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/discord-channels \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Switch the connected channel:

```bash
curl -X PATCH https://zernio.com/api/v1/connect/discord \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_ACCOUNT_ID",
    "channelId": "NEW_CHANNEL_ID"
  }'
```

Only text (0), announcement (5), and forum (15) channels are supported. A new webhook is automatically created in the target channel.

## Direct Messages

Send a 1:1 message from the bot to a Discord user. Useful for operational
messages outside the channel post flow — onboarding, billing reminders,
password resets, support pings.

```bash
curl -X POST https://zernio.com/api/v1/discord/dms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_ACCOUNT_ID",
    "userId": "1234567890123456789",
    "content": "Welcome to Acme! Reply STOP to opt out."
  }'
```

Same payload shape as channel posts — also accepts `embeds`, `attachments`,
and `tts`. At least one of `content`, `embeds`, or `attachments` is required.

<Callout type="warn">
**Discord constraints to know about:**
- The bot can only DM users it shares **at least one guild** with.
- If the recipient has DMs disabled for non-friends, Discord returns 403
  (surfaces as a 502 platform error).
- Recipient must be identified by Discord **snowflake ID** (not username).
  No public API exists to resolve a username to a snowflake without the
  privileged `guild_members.read` scope.
</Callout>

## Role & Member Management

Four endpoints for community-ops automation: list roles, list members
(paginated), and assign / remove roles per member. Path shape mirrors
Discord's own API so you can map mentally with zero translation.

**List all roles in a guild** (id, name, color, position, permissions,
flags):

```bash
curl "https://zernio.com/api/v1/discord/guilds/GUILD_ID/roles?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**List members** (cursor-paginated, default 100/page, max 1,000):

```bash
curl "https://zernio.com/api/v1/discord/guilds/GUILD_ID/members?accountId=YOUR_ACCOUNT_ID&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json
{
  "data": [
    {
      "user": { "id": "...", "username": "...", "global_name": "..." },
      "nick": null,
      "roles": ["ROLE_ID_A", "ROLE_ID_B"],
      "joined_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": { "nextCursor": "USER_ID", "hasMore": true }
}
```

Pass `&after=NEXT_CURSOR` on the next call until `hasMore: false`.

**Assign a role to a member** (idempotent):

```bash
curl -X PUT "https://zernio.com/api/v1/discord/guilds/GUILD_ID/members/USER_ID/roles/ROLE_ID?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Remove a role from a member** (idempotent):

```bash
curl -X DELETE "https://zernio.com/api/v1/discord/guilds/GUILD_ID/members/USER_ID/roles/ROLE_ID?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Callout type="warn">
**Discord hierarchy rule**: the bot's highest role must be **above** the
target role. If the bot is demoted in the guild's role hierarchy, it loses
the ability to assign higher roles even with the Manage Roles permission.
The `@everyone` role (where `roleId == guildId`) cannot be manipulated.
</Callout>

## Pin / Unpin Messages

Pin messages in a channel for community-ops automation: announcement of
the week, rules channel updates, auto-pin freshly published posts.

**List pinned messages** (max 50 per channel, sorted most-recent first):

```bash
curl "https://zernio.com/api/v1/discord/channels/CHANNEL_ID/pins?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Pin a message** (idempotent):

```bash
curl -X PUT "https://zernio.com/api/v1/discord/channels/CHANNEL_ID/pins/MESSAGE_ID?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Unpin a message** (idempotent):

```bash
curl -X DELETE "https://zernio.com/api/v1/discord/channels/CHANNEL_ID/pins/MESSAGE_ID?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Callout type="info">
Discord caps a channel at 50 pinned messages. Attempting to pin a 51st
returns 400 — unpin one first.
</Callout>

## Scheduled Events

Create Discord-native scheduled events — distinct from messages. They show
up in the server's Events panel and Discord auto-notifies interested
members ahead of start time. Perfect for AMAs, game tournaments, office
hours, livestreams, web3 community events.

Three event types via discriminated union on `entity.type`:

**External event** (Zoom, IRL, off-platform livestream):

```bash
curl -X POST https://zernio.com/api/v1/discord/guilds/GUILD_ID/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_ACCOUNT_ID",
    "name": "Weekly AMA",
    "description": "Bring your questions about the roadmap.",
    "startsAt": "2026-06-15T18:00:00Z",
    "entity": {
      "type": "external",
      "location": "https://zoom.us/j/123456789",
      "endsAt": "2026-06-15T19:00:00Z"
    }
  }'
```

For external events, both `location` and `endsAt` are required.

**Voice channel event**:

```json
{
  "accountId": "YOUR_ACCOUNT_ID",
  "name": "Game Night",
  "startsAt": "2026-06-20T20:00:00Z",
  "entity": { "type": "voice", "channelId": "VOICE_CHANNEL_ID" }
}
```

**Stage channel event**: same shape as voice, with `"type": "stage"` and a
stage channel id.

**List events** (optionally with RSVP count):

```bash
curl "https://zernio.com/api/v1/discord/guilds/GUILD_ID/events?accountId=YOUR_ACCOUNT_ID&withUserCount=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Get / Update / Delete one event**:

```bash
# Fetch
curl "https://zernio.com/api/v1/discord/guilds/GUILD_ID/events/EVENT_ID?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update (any subset of fields)
curl -X PATCH "https://zernio.com/api/v1/discord/guilds/GUILD_ID/events/EVENT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accountId": "YOUR_ACCOUNT_ID", "name": "Updated title" }'

# Cancel (status transition - preserves the event in guild history)
curl -X PATCH "https://zernio.com/api/v1/discord/guilds/GUILD_ID/events/EVENT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accountId": "YOUR_ACCOUNT_ID", "status": "cancelled" }'

# Hard delete (no history retained)
curl -X DELETE "https://zernio.com/api/v1/discord/guilds/GUILD_ID/events/EVENT_ID?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Callout type="info">
Discord doesn't have a dedicated "cancel" endpoint — cancellation is a
status transition via PATCH (`status: 'cancelled'`). Use PATCH if you want
the event preserved in the guild's event history; use DELETE for a hard
delete with no record.
</Callout>

| Event Property | Value |
|----------------|-------|
| Name | Max 100 chars |
| Description | Max 1,000 chars |
| Privacy level | Always GUILD_ONLY (Discord deprecated PUBLIC events) |
| External events | Require `location` (max 100 chars) + `endsAt` |
| Voice/stage events | Require `channelId`; `endsAt` optional |
| Cover image | Optional base64 data URI (PNG / JPEG / GIF) |
| Start time | Must be in the future |

## Related Endpoints

**Connection & posting**

- [Connect Discord Account](/guides/connecting-accounts) - OAuth flow and bot installation
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Discord Settings](/discord/update-discord-settings) - Update webhook identity and switch channels
- [Discord Channels](/discord/get-discord-channels) - List guild channels

**Direct Messages**

- `POST /v1/discord/dms` - Send a 1:1 DM from the bot to a Discord user

**Role & Member management**

- `GET /v1/discord/guilds/{guildId}/roles` - List all roles in a guild
- `GET /v1/discord/guilds/{guildId}/members` - Paginated member list
- `PUT /v1/discord/guilds/{guildId}/members/{userId}/roles/{roleId}` - Assign a role
- `DELETE /v1/discord/guilds/{guildId}/members/{userId}/roles/{roleId}` - Remove a role

**Pinned messages**

- `GET /v1/discord/channels/{channelId}/pins` - List pinned messages
- `PUT /v1/discord/channels/{channelId}/pins/{messageId}` - Pin a message
- `DELETE /v1/discord/channels/{channelId}/pins/{messageId}` - Unpin a message

**Scheduled Events**

- `POST /v1/discord/guilds/{guildId}/events` - Create an event (external / voice / stage)
- `GET /v1/discord/guilds/{guildId}/events` - List events (optionally with RSVP count)
- `GET /v1/discord/guilds/{guildId}/events/{eventId}` - Fetch one event
- `PATCH /v1/discord/guilds/{guildId}/events/{eventId}` - Update or cancel (`status: 'cancelled'`)
- `DELETE /v1/discord/guilds/{guildId}/events/{eventId}` - Hard delete

---

# Facebook

Schedule and automate Facebook Page posts with Zernio API - Feed posts, Stories, multi-image, multi-link carousels, GIFs, and first comments

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Reference

| Property | Value |
|----------|-------|
| Character limit | 63,206 (truncated at ~480 with "See more") |
| Images per post | 10 |
| Videos per post | 1 |
| Image formats | JPEG, PNG, GIF (WebP auto-converted to JPEG) |
| Image max size | 4 MB (Facebook rejects larger in practice) |
| Video formats | MP4, MOV |
| Video max size | 4 GB |
| Video max duration | 240 min (feed), 120 sec (stories) |
| Post types | Feed (text/image/video/multi-image/multi-link carousel), Story, Reel |
| Scheduling | Yes |
| Inbox (DMs) | Yes |
| Inbox (Comments) | Yes |
| Inbox (Reviews) | Yes |
| Comment-to-DM automations | Yes |
| Analytics | Yes |

## Before You Start

<Callout type="warn">
Facebook API only posts to Pages, not personal profiles. You must have a Facebook Page and admin access to it. Also: Facebook often rejects photos larger than 4 MB even though the stated limit is higher. Keep images under 4 MB and use JPEG or PNG format. WebP images are auto-converted to JPEG by Zernio.

- API posts to **Pages only** (not personal profiles)
- User must be Page **Admin** or **Editor**
- Facebook tokens expire frequently -- subscribe to the `account.disconnected` webhook
- Multiple Pages can be managed from one connected account
</Callout>

## Quick Start

Post to a Facebook Page in under 60 seconds:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Hello from Zernio API!',
  platforms: [
    { platform: 'facebook', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to Facebook!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Hello from Zernio API!",
    platforms=[
        {"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to Facebook! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from Zernio API!",
    "platforms": [
      {"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

## Draft Posts (Publishing Tools)

Create an unpublished Facebook draft that appears in **Facebook Publishing Tools** instead of publishing immediately. This is useful for review/approval workflows.

> **Note:** Drafts are supported for feed posts (text, link, image, video) and reels. Drafts are not supported for stories. `firstComment` is skipped when `draft: true`.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Draft post for review before publishing",
    "platforms": [{
      "platform": "facebook",
      "accountId": "YOUR_ACCOUNT_ID"
    }],
    "publishNow": true,
    "facebookSettings": {
      "draft": true
    }
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Draft post for review before publishing',
  platforms: [{ platform: 'facebook', accountId: 'YOUR_ACCOUNT_ID' }],
  publishNow: true,
  facebookSettings: {
    draft: true
  }
});

console.log('Draft created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Draft post for review before publishing",
    platforms=[{"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}],
    publish_now=True,
    facebook_settings={"draft": True}
)

post = result.post
print(f"Draft created! {post['_id']}")
```
</Tab>
</Tabs>

### Text-Only Post

No media required. Facebook is one of the few platforms that supports text-only posts.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Just a text update for our followers.',
  platforms: [
    { platform: 'facebook', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Just a text update for our followers.",
    platforms=[
        {"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Just a text update for our followers.",
    "platforms": [
      {"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Single Image Post

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Check out this photo!',
  mediaItems: [
    { type: 'image', url: 'https://example.com/photo.jpg' }
  ],
  platforms: [
    { platform: 'facebook', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Check out this photo!",
    media_items=[
        {"type": "image", "url": "https://example.com/photo.jpg"}
    ],
    platforms=[
        {"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out this photo!",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/photo.jpg"}
    ],
    "platforms": [
      {"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Multi-Image Post

Facebook supports up to **10 images** in a single post. You cannot mix images and videos in the same post.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Photo dump from the weekend!',
  mediaItems: [
    { type: 'image', url: 'https://example.com/photo1.jpg' },
    { type: 'image', url: 'https://example.com/photo2.jpg' },
    { type: 'image', url: 'https://example.com/photo3.jpg' }
  ],
  platforms: [
    { platform: 'facebook', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Photo dump from the weekend!",
    media_items=[
        {"type": "image", "url": "https://example.com/photo1.jpg"},
        {"type": "image", "url": "https://example.com/photo2.jpg"},
        {"type": "image", "url": "https://example.com/photo3.jpg"}
    ],
    platforms=[
        {"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Photo dump from the weekend!",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/photo1.jpg"},
      {"type": "image", "url": "https://example.com/photo2.jpg"},
      {"type": "image", "url": "https://example.com/photo3.jpg"}
    ],
    "platforms": [
      {"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Multi-Link Carousel Post

Render a post as a 2-5 card carousel where each image has its own click-through link and headline. Useful for product catalogs, listings, or any post where each photo points to a different URL.

Set `facebookSettings.carouselCards` to layer per-card metadata on top of your existing `mediaItems` (one card per image, in order). All items must be images -- video cards aren't supported by Facebook. Optionally set `facebookSettings.carouselLink` to control the "See more" destination shown on the carousel end card.

> **Display truncation:** Facebook renders card titles around 35 characters and descriptions around 30 characters. Longer strings are accepted (up to 255 chars each in the API) but get truncated on render.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Check out our latest inventory',
  mediaItems: [
    { type: 'image', url: 'https://example.com/car-1.jpg' },
    { type: 'image', url: 'https://example.com/car-2.jpg' },
    { type: 'image', url: 'https://example.com/car-3.jpg' }
  ],
  platforms: [
    { platform: 'facebook', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  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' }
    ]
  }
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Check out our latest inventory",
    media_items=[
        {"type": "image", "url": "https://example.com/car-1.jpg"},
        {"type": "image", "url": "https://example.com/car-2.jpg"},
        {"type": "image", "url": "https://example.com/car-3.jpg"}
    ],
    platforms=[
        {"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True,
    facebook_settings={
        "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"}
        ]
    }
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out our latest inventory",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/car-1.jpg"},
      {"type": "image", "url": "https://example.com/car-2.jpg"},
      {"type": "image", "url": "https://example.com/car-3.jpg"}
    ],
    "platforms": [
      {"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "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"}
      ]
    }
  }'
```
</Tab>
</Tabs>

### Video Post

A single video per post. For GIFs, use `type: 'video'` -- they are treated as videos internally, auto-play, and loop.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Watch our latest video!',
  mediaItems: [
    { type: 'video', url: 'https://example.com/video.mp4' }
  ],
  platforms: [
    { platform: 'facebook', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Watch our latest video!",
    media_items=[
        {"type": "video", "url": "https://example.com/video.mp4"}
    ],
    platforms=[
        {"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Watch our latest video!",
    "mediaItems": [
      {"type": "video", "url": "https://example.com/video.mp4"}
    ],
    "platforms": [
      {"platform": "facebook", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Story (Image or Video)

Stories are 24-hour ephemeral content. Media is required. Text captions are **not** displayed on Stories, and interactive stickers are not supported via the API.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  mediaItems: [
    { type: 'image', url: 'https://example.com/story.jpg' }
  ],
  platforms: [{
    platform: 'facebook',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      contentType: 'story'
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    media_items=[
        {"type": "image", "url": "https://example.com/story.jpg"}
    ],
    platforms=[{
        "platform": "facebook",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "contentType": "story"
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaItems": [
      {"type": "image", "url": "https://example.com/story.jpg"}
    ],
    "platforms": [{
      "platform": "facebook",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "contentType": "story"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Reel (Video)

Publish a Facebook Reel (short vertical video). Reels require a **single vertical video**.

> **Note:** `content` is used as the Reel caption. Use `platformSpecificData.title` to set a separate Reel title.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Behind the scenes 🎬",
    "mediaItems": [
      {"type": "video", "url": "https://example.com/reel.mp4"}
    ],
    "platforms": [{
      "platform": "facebook",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "contentType": "reel",
        "title": "Studio day"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Behind the scenes 🎬',
  mediaItems: [
    { type: 'video', url: 'https://example.com/reel.mp4' }
  ],
  platforms: [{
    platform: 'facebook',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      contentType: 'reel',
      title: 'Studio day'
    }
  }],
  publishNow: true
});
console.log('Posted Reel to Facebook!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Behind the scenes 🎬",
    media_items=[
        {"type": "video", "url": "https://example.com/reel.mp4"}
    ],
    platforms=[{
        "platform": "facebook",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "contentType": "reel",
            "title": "Studio day"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Posted Reel to Facebook! {post['_id']}")
```
</Tab>
</Tabs>

**Reel requirements**

- Single video only (no images)
- Vertical video recommended (9:16)
- Duration: 3–60 seconds

### First Comment

Auto-post a first comment immediately after your post is published. Does **not** work with Stories.

> **Note:** `firstComment` is skipped when `draft: true`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'New product launch!',
  mediaItems: [
    { type: 'image', url: 'https://example.com/product.jpg' }
  ],
  platforms: [{
    platform: 'facebook',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      firstComment: 'Link to purchase: https://shop.example.com'
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="New product launch!",
    media_items=[
        {"type": "image", "url": "https://example.com/product.jpg"}
    ],
    platforms=[{
        "platform": "facebook",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "firstComment": "Link to purchase: https://shop.example.com"
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New product launch!",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/product.jpg"}
    ],
    "platforms": [{
      "platform": "facebook",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "firstComment": "Link to purchase: https://shop.example.com"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Geo-Restriction

Restrict who can see your Facebook post by country. This is a hard visibility restriction: users outside the specified countries cannot see the post at all. Supported for feed posts, videos, and reels. Not supported for stories.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This post is only visible in the US and Spain",
    "platforms": [{
      "platform": "facebook",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "geoRestriction": {
          "countries": ["US", "ES"]
        }
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'This post is only visible in the US and Spain',
  platforms: [{
    platform: 'facebook',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      geoRestriction: {
        countries: ['US', 'ES']
      }
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="This post is only visible in the US and Spain",
    platforms=[{
        "platform": "facebook",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "geoRestriction": {
                "countries": ["US", "ES"]
            }
        }
    }],
    publish_now=True
)
```
</Tab>
</Tabs>

`geoRestriction.countries` accepts up to 25 uppercase ISO 3166-1 alpha-2 country codes (e.g. `"US"`, `"GB"`, `"DE"`).

## Media Requirements

### Images

| Property | Feed Post | Story |
|----------|-----------|-------|
| **Max images** | 10 | 1 |
| **Formats** | JPEG, PNG, GIF (WebP auto-converted) | JPEG, PNG |
| **Max file size** | 4 MB | 4 MB |
| **Recommended** | 1200 x 630 px | 1080 x 1920 px |

### Videos

| Property | Feed Video | Story |
|----------|------------|-------|
| **Max videos** | 1 | 1 |
| **Formats** | MP4, MOV | MP4, MOV |
| **Max file size** | 4 GB | 4 GB |
| **Max duration** | 240 minutes | 120 seconds |
| **Min duration** | 1 second | 1 second |
| **Recommended resolution** | 1280 x 720 px min | 1080 x 1920 px |
| **Frame rate** | 30 fps recommended | 30 fps |
| **Codec** | H.264 | H.264 |

## Platform-Specific Fields

All fields below go inside `platformSpecificData` for the Facebook platform entry.

| Field | Type | Description |
|-------|------|-------------|
| `draft` | boolean | When true, creates an unpublished draft in Facebook Publishing Tools instead of publishing immediately. Not supported for Stories. |
| `contentType` | `"story"` \| `"reel"` | Set to `"story"` for Page Stories (24h ephemeral) or `"reel"` for Reels (short vertical video). Defaults to feed post if omitted. |
| `title` | string | Reel title (only for `contentType="reel"`). Separate from the `content` caption. |
| `firstComment` | string | Auto-posted as the first comment after publish. Feed posts and Reels (not Stories). Skipped when `draft` is true. |
| `pageId` | string | Post to a specific Page when the connected account manages multiple Pages. Get available pages with `GET /v1/accounts/{accountId}/facebook-page`. |
| `carouselCards` | array | Multi-link carousel cards (2–5). Requires `mediaItems` with the same length (images only). Mutually exclusive with `contentType="story"` or `"reel"`. |
| `carouselLink` | string | Optional top-level “See more” link for the carousel end card. Only used with `carouselCards`. |
| `geoRestriction` | object | Restrict post visibility to specific countries. See [Geo-Restriction](#geo-restriction) below. |

## Multi-Page Posting

If your connected Facebook account manages multiple Pages, you can list them, set a default, or override per post.

### List Available Pages

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const pages = await zernio.connect.getFacebookPages('YOUR_ACCOUNT_ID');
console.log('Available pages:', pages);
```
</Tab>
<Tab value="Python">
```python
pages = client.connect.get_facebook_pages("YOUR_ACCOUNT_ID")
print("Available pages:", pages)
```
</Tab>
<Tab value="curl">
```bash
curl -X GET https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/facebook-page \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

### Post to Multiple Pages

Use the same `accountId` multiple times with different `pageId` values:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Exciting news from all our brands!',
  platforms: [
    {
      platform: 'facebook',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: { pageId: '111111111' }
    },
    {
      platform: 'facebook',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: { pageId: '222222222' }
    }
  ],
  publishNow: true
});
console.log('Posted to Facebook!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Exciting news from all our brands!",
    platforms=[
        {
            "platform": "facebook",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {"pageId": "111111111"}
        },
        {
            "platform": "facebook",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {"pageId": "222222222"}
        }
    ],
    publish_now=True
)
post = result.post
print(f"Posted to Facebook! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Exciting news from all our brands!",
    "platforms": [
      {
        "platform": "facebook",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "pageId": "111111111"
        }
      },
      {
        "platform": "facebook",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "pageId": "222222222"
        }
      }
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

You can also set a default page with `POST /v1/accounts/{accountId}/facebook-page` so you don't need to pass `pageId` on every request.

## Media URL Requirements

- URLs must be **publicly accessible** via HTTPS
- No redirects, no authentication
- Cloud storage sharing links (Google Drive, Dropbox) may not work -- use direct download URLs
- WebP images are auto-converted to JPEG before upload

## Analytics

> **Included** — Analytics is bundled with every paid account on the [Usage plan](/pricing).

Available metrics via the [Analytics API](/analytics/get-analytics):

| Metric | Available |
|--------|-----------|
| Impressions | ✅ |
| Likes | ✅ |
| Comments | ✅ |
| Shares | ✅ |
| Clicks | ✅ |
| Views | ✅ |

Facebook also provides a dedicated [Page Insights API](/analytics/get-facebook-page-insights) for page-level aggregates (media views, post engagements, video metrics, follower count). Uses current (post-November 2025) Meta metric names; the legacy page_impressions / page_fans / page_fan_adds / page_fan_removes metrics were deprecated by Meta and are rejected by this endpoint. followers_gained and followers_lost are synthesized from Zernio's daily follower snapshotter.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const analytics = await zernio.analytics.getAnalytics({
  platform: 'facebook',
  fromDate: '2024-01-01',
  toDate: '2024-01-31'
});
console.log(analytics.posts);
```
</Tab>
<Tab value="Python">
```python
analytics = client.analytics.get_analytics(
    platform="facebook",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(analytics["posts"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics?platform=facebook&fromDate=2024-01-01&toDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

## What You Can't Do

- Post to **personal profiles** (Pages only)
- Create Events
- Post to Groups (deprecated by Facebook)
- Go Live (requires the separate Facebook Live API)
- Add interactive story stickers
- Target audiences by demographics (age, gender, interests) for organic posts (country-level geo-restriction IS supported, see [Geo-Restriction](#geo-restriction))

## Common Errors

| Error | Meaning | Fix |
|-------|---------|-----|
| "Photos should be smaller than 4MB and saved as JPG or PNG." | Image exceeds actual size limit or unsupported format | Reduce to under 4 MB. Use JPEG or PNG. |
| "Missing or invalid image file" | Facebook couldn't process image -- corrupt, wrong format, or inaccessible URL | Verify URL in an incognito browser. Ensure JPEG/PNG under 4 MB. |
| "Unable to fetch video file from URL." | Facebook's servers couldn't download the video | Use a direct, publicly accessible URL. Avoid cloud storage sharing links. |
| "Facebook tokens expired. Please reconnect." | OAuth token expired | Reconnect the account. Facebook tokens have shorter lifespans. Subscribe to the `account.disconnected` webhook. |
| "Confirm your identity before you can publish as this Page." | Facebook security check triggered | Log into Facebook, go to the Page, and complete identity verification. |
| "Publishing failed due to max retries reached" | All 3 retry attempts failed | Usually temporary. Retry manually or wait and try again. |

## Inbox

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

Facebook has the most complete inbox support across DMs, comments, and reviews.

### Direct Messages

| Feature | Supported |
|---------|-----------|
| List conversations | ✅ |
| Fetch messages | ✅ |
| Send text messages | ✅ |
| Send attachments | ✅ (images, videos, audio, files) |
| Quick replies | ✅ (up to 13, Meta quick_replies) |
| Buttons | ✅ (up to 3, generic template) |
| Carousels | ✅ (generic template, up to 10 elements) |
| Message tags | ✅ (4 types) |
| Archive/unarchive | ✅ |

**Message tags:** Use `messagingType: "MESSAGE_TAG"` with one of: `CONFIRMED_EVENT_UPDATE`, `POST_PURCHASE_UPDATE`, `ACCOUNT_UPDATE`, or `HUMAN_AGENT` to send messages outside the 24-hour messaging window.

### Webhooks

Messenger emits the full set of message lifecycle webhooks:

| Event | When it fires |
|-------|---------------|
| `message.received` | New incoming DM |
| `message.sent` | Outgoing DM is sent |
| `message.edited` | The sender edits a previously-sent message (up to 5 edits per Meta) |
| `message.delivered` | An outgoing DM is delivered to the recipient |
| `message.read` | The recipient reads an outgoing DM |

Messages are stored locally via webhooks. See the [Webhooks](/webhooks) page for payload details.

**Note:** Messenger does not expose incoming-message unsend via webhook, so `message.deleted` is not emitted for Facebook. This is a platform limitation.

### Persistent Menu

Manage the persistent menu shown in Facebook Messenger conversations. Max 3 top-level items, max 5 nested items.

See [Account Settings](/account-settings/get-messenger-menu) for the `GET/PUT/DELETE /v1/accounts/{accountId}/messenger-menu` endpoints.

### Comments

| Feature | Supported |
|---------|-----------|
| List comments on posts | ✅ |
| Reply to comments | ✅ |
| Delete comments | ✅ |
| Like comments | ✅ |
| Hide/unhide comments | ✅ |
| Send private reply (DM after comment) | ✅ (text + up to 13 quick replies OR 1-3 inline buttons, 7-day window, one per comment) |

### Reviews (Pages)

| Feature | Supported |
|---------|-----------|
| List reviews | ✅ |
| Reply to reviews | ✅ |

## Related Endpoints

- [Connect Facebook Account](/guides/connecting-accounts) - OAuth flow
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Image and video uploads
- [Analytics](/analytics/get-analytics) - Post performance metrics
- [Messages](/messages/list-inbox-conversations), [Comments](/comments/list-inbox-comments), and [Reviews](/reviews/list-inbox-reviews)
- [Account Settings](/account-settings/get-messenger-menu) - Persistent menu configuration

---

# Google Ads

Create Search and Display campaigns via Zernio API - No MCC or Standard Access application required

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

<Callout type="info">
**Included with the [Usage plan](/pricing).** No MCC or Standard Access application needed. Zernio operates under our own approved developer token.
</Callout>

<Callout type="warn">
**Display campaigns need two images.** Google's Responsive Display Ads (RDA) require BOTH a landscape (1.91:1, e.g. 1200x628) AND a square (1:1, e.g. 1080x1080) marketing image. Sending only one is rejected upstream as "Too few." (`NOT_ENOUGH_SQUARE_MARKETING_IMAGE_ASSET` or `NOT_ENOUGH_MARKETING_IMAGE_ASSET`). Pass both via `images: { landscape, square }`.
</Callout>

## What's Supported

| Feature | Status |
|---------|--------|
| Search campaigns (Responsive Search Ads) | Yes |
| Display campaigns (Responsive Display Ads) | Yes |
| Campaign > Ad Group > Ad hierarchy | Yes |
| Keyword targeting (Broad, Phrase, Exact) | Yes |
| Geo + language targeting | Yes |
| Real-time analytics (spend, CPC, CPM) | Yes |
| Conversions API (offline/enhanced) via Data Manager | Yes |
| Campaign URL tracking tags — read + update ([details](#url-tracking-tags)) | Yes |
| Performance Max | Roadmap |
| Shopping, Video, Demand Gen | Roadmap |
| Customer Match audiences (create + member upload) | Yes |

## Create a Search Campaign

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.createStandaloneAd({ body: {
  accountId: "acc_googleads_123",
  adAccountId: "987-654-3210",
  name: "US DevOps Search",
  campaignType: "search",
  goal: "traffic",
  budgetAmount: 50,
  budgetType: "daily",
  headline: "Internal Developer Platforms",
  body: "Spec-driven platform engineering.",
  linkUrl: "https://example.com/platform",
  keywords: ["platform engineering tools", "internal developer platform"],
  additionalHeadlines: ["Build your Dev Platform", "Ship DevEx Faster", "Internal Platforms, Done Right"],
  additionalDescriptions: ["Spec-driven platform. Free tier available.", "Enterprise features. Startup price."],
  countries: ["US", "CA", "GB"],
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.create_standalone_ad(
    account_id="acc_googleads_123",
    ad_account_id="987-654-3210",
    name="US DevOps Search",
    campaign_type="search",
    goal="traffic",
    budget_amount=50,
    budget_type="daily",
    headline="Internal Developer Platforms",
    body="Spec-driven platform engineering.",
    link_url="https://example.com/platform",
    keywords=["platform engineering tools", "internal developer platform"],
    additional_headlines=["Build your Dev Platform", "Ship DevEx Faster", "Internal Platforms, Done Right"],
    additional_descriptions=["Spec-driven platform. Free tier available.", "Enterprise features. Startup price."],
    countries=["US", "CA", "GB"],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_googleads_123",
    "adAccountId": "987-654-3210",
    "name": "US DevOps Search",
    "campaignType": "search",
    "goal": "traffic",
    "budgetAmount": 50,
    "budgetType": "daily",
    "headline": "Internal Developer Platforms",
    "body": "Spec-driven platform engineering.",
    "linkUrl": "https://example.com/platform",
    "keywords": ["platform engineering tools", "internal developer platform"],
    "additionalHeadlines": ["Build your Dev Platform", "Ship DevEx Faster", "Internal Platforms, Done Right"],
    "additionalDescriptions": ["Spec-driven platform. Free tier available.", "Enterprise features. Startup price."],
    "countries": ["US", "CA", "GB"]
  }'
```
</Tab>
</Tabs>

<Callout type="info">
**Valid `goal` values for Google Ads:** `engagement`, `traffic`, `awareness`, `video_views`. Conversion-goal campaigns aren't yet supported on `/v1/ads/create`, pass `traffic` for click-optimised delivery. `campaignType` is lowercase (`search` or `display`). `keywords` is a flat array of strings; match types default to broad.
</Callout>

## Create a Display Campaign

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.createStandaloneAd({ body: {
  accountId: "acc_googleads_123",
  adAccountId: "987-654-3210",
  name: "Retargeting Display",
  campaignType: "display",
  goal: "traffic",
  budgetAmount: 40,
  budgetType: "daily",
  headline: "Finish your signup",
  body: "Come back and upgrade today.",
  linkUrl: "https://example.com/upgrade",
  businessName: "Acme",
  images: {
    landscape: "https://cdn.example.com/retarget-1200x628.jpg",
    square: "https://cdn.example.com/retarget-1080x1080.jpg",
  },
  additionalHeadlines: ["Finish your signup", "Get 30% off this week"],
  additionalDescriptions: ["Come back and upgrade today."],
  countries: ["US"],
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.create_standalone_ad(
    account_id="acc_googleads_123",
    ad_account_id="987-654-3210",
    name="Retargeting Display",
    campaign_type="display",
    goal="traffic",
    budget_amount=40,
    budget_type="daily",
    headline="Finish your signup",
    body="Come back and upgrade today.",
    link_url="https://example.com/upgrade",
    business_name="Acme",
    images={
        "landscape": "https://cdn.example.com/retarget-1200x628.jpg",
        "square": "https://cdn.example.com/retarget-1080x1080.jpg",
    },
    additional_headlines=["Finish your signup", "Get 30% off this week"],
    additional_descriptions=["Come back and upgrade today."],
    countries=["US"],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_googleads_123",
    "adAccountId": "987-654-3210",
    "name": "Retargeting Display",
    "campaignType": "display",
    "goal": "traffic",
    "budgetAmount": 40,
    "budgetType": "daily",
    "headline": "Finish your signup",
    "body": "Come back and upgrade today.",
    "linkUrl": "https://example.com/upgrade",
    "businessName": "Acme",
    "images": {
      "landscape": "https://cdn.example.com/retarget-1200x628.jpg",
      "square": "https://cdn.example.com/retarget-1080x1080.jpg"
    },
    "additionalHeadlines": ["Finish your signup", "Get 30% off this week"],
    "additionalDescriptions": ["Come back and upgrade today."],
    "countries": ["US"]
  }'
```
</Tab>
</Tabs>

<Callout type="info">
Display campaigns require `businessName` (max 25 chars) on top of the Search fields. `longHeadline` defaults to `headline` if not supplied (max 90 chars). Both `images.landscape` and `images.square` are required, Google rejects RDA with only one.
</Callout>

## Conversions API

Import offline conversions (deal closed, lead qualified, subscription renewed) into Google Ads via the Data Manager API `ingestEvents` method, the endpoint Google recommends for all new integrations as of December 2025 (replacing the legacy `uploadClickConversions`). Zernio uses the Google Ads account you already connected; no additional OAuth, no developer token to apply for.

The same endpoint handles both attribution paths:
- **Click attribution**, include a `gclid`, `gbraid`, or `wbraid` from the originating ad click
- **Enhanced Conversions for Leads**, include hashed email / phone when no click ID is available

PII is SHA-256 hashed server-side. For `@gmail.com` / `@googlemail.com` addresses, we strip dots and `+suffix` from the local part before hashing per Google's spec so `john.doe+promo@gmail.com` matches `johndoe@gmail.com`.

### Discover available conversion actions

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.ads.listConversionDestinations({
  path: { accountId: 'ACCOUNT_ID' },
});
```
</Tab>
<Tab value="Python">
```python
data = client.ads.list_conversion_destinations(account_id="ACCOUNT_ID")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/accounts/ACCOUNT_ID/conversion-destinations" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Returns every enabled conversion action across accessible customers. The `id` is the conversion action resource name (`customers/{customerId}/conversionActions/{id}`). The `type` field reflects the action's category (PURCHASE, LEAD, SIGN_UP, etc.), Google locks the event type to the conversion action, not the per-event `eventName`.

### Send a conversion event

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.ads.sendConversions({ body: {
  accountId: 'ACCOUNT_ID',
  destinationId: 'customers/1234567890/conversionActions/987654321',
  consent: { adUserData: 'GRANTED', adPersonalization: 'GRANTED' }, // required for EEA/UK
  events: [{
    eventName: 'Purchase',
    eventTime: Math.floor(Date.now() / 1000),
    eventId: 'order_abc_123', // dedup, mapped to transactionId
    value: 129.99,
    currency: 'USD',
    user: {
      email: 'customer@example.com',
      phone: '+14155551234',
      clickIds: { gclid: 'EAIaIQobChMI...' },
    },
  }],
}});
```
</Tab>
<Tab value="Python">
```python
result = client.ads.send_conversions(
    account_id="ACCOUNT_ID",
    destination_id="customers/1234567890/conversionActions/987654321",
    consent={"adUserData": "GRANTED", "adPersonalization": "GRANTED"},
    events=[{
        "eventName": "Purchase",
        "eventTime": int(time.time()),
        "eventId": "order_abc_123",
        "value": 129.99,
        "currency": "USD",
        "user": {
            "email": "customer@example.com",
            "phone": "+14155551234",
            "clickIds": {"gclid": "EAIaIQobChMI..."},
        },
    }],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/conversions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "ACCOUNT_ID",
    "destinationId": "customers/1234567890/conversionActions/987654321",
    "consent": { "adUserData": "GRANTED", "adPersonalization": "GRANTED" },
    "events": [{
      "eventName": "Purchase",
      "eventTime": 1744732800,
      "eventId": "order_abc_123",
      "value": 129.99,
      "currency": "USD",
      "user": {
        "email": "customer@example.com",
        "phone": "+14155551234",
        "clickIds": { "gclid": "EAIaIQobChMI..." }
      }
    }]
  }'
```
</Tab>
</Tabs>

### EEA / UK consent

Google enforces strict consent signaling for European users under the February 2026 Data Manager restrictions. Pass `consent` at the request root with `adUserData` and `adPersonalization` set to `GRANTED` or `DENIED`. Omit the field for non-EEA requests where you don't have consent data; Google applies region defaults.

### Deduplication

Pass a stable `eventId` on every event, Zernio maps it to Google's `transactionId` so repeated uploads of the same conversion are deduped.

### Batching + reporting

Up to 2,000 events per request (Zernio chunks larger batches automatically). Conversions take up to 3 hours to appear in Google Ads reports. The response carries a `requestId` you can reference if conversions don't appear as expected.

## URL tracking tags

Read or update a campaign's click-URL tracking: `trackingUrlTemplate` (the redirect/tracking template, must contain `{lpurl}`) and `finalUrlSuffix` (parse-only `key=value` params appended to the landing page, the part that survives parallel tracking). Operate at the campaign level via the unified ad endpoint, passing any ad in the campaign.

Read the current values:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.ads.getAdTrackingTags({ path: { adId: 'AD_ID' } });
// { platform: 'google', level: 'campaign', trackingUrlTemplate: '{lpurl}?utm_source=google', finalUrlSuffix: 'utm_medium=cpc' }
```
</Tab>
<Tab value="Python">
```python
data = client.ads.get_ad_tracking_tags(ad_id="AD_ID")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/ads/AD_ID/tracking-tags" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Update either field (send only the ones you want to change; omit a field to leave it untouched, pass an empty string to clear it):

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.ads.updateAdTrackingTags({
  path: { adId: 'AD_ID' },
  body: {
    trackingUrlTemplate: '{lpurl}?utm_source=google&utm_campaign={campaignid}',
    finalUrlSuffix: 'utm_medium=cpc',
  },
});
```
</Tab>
<Tab value="Python">
```python
data = client.ads.update_ad_tracking_tags(
    ad_id="AD_ID",
    tracking_url_template="{lpurl}?utm_source=google&utm_campaign={campaignid}",
    final_url_suffix="utm_medium=cpc",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X PATCH "https://zernio.com/api/v1/ads/AD_ID/tracking-tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingUrlTemplate": "{lpurl}?utm_source=google&utm_campaign={campaignid}",
    "finalUrlSuffix": "utm_medium=cpc"
  }'
```
</Tab>
</Tabs>

These reads and writes go through the Google Ads API, which is rate-limited by access tier. A one-off audit is fine; auditing large numbers of campaigns can hit the daily operation cap on Basic access. If you plan high-volume tag auditing, let us know and we'll make sure the underlying account is on the higher tier.

## Customer Match audiences

Target a CRM list via Customer Match. Create an empty audience, then upload members. `adAccountId` is the Google Ads customer ID (no dashes). Email only on Google (any `phone` is ignored); values are SHA256-hashed server-side before upload.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// 1. Create the (empty) Customer Match audience
await zernio.adaudiences.createAdAudience({
  body: {
    accountId: 'acc_googleads_123',
    adAccountId: '1234567890', // Google Ads customer ID
    type: 'customer_list',
    name: 'Newsletter subscribers',
  },
});

// 2. Upload members to the returned audience id
await zernio.adaudiences.addUsersToAdAudience({
  path: { audienceId: 'aud_abc123' }, // id from the create response
  body: { users: [{ email: 'jane@example.com' }, { email: 'sam@example.com' }] },
});
```
</Tab>
<Tab value="Python">
```python
# 1. Create the (empty) Customer Match audience
client.ad_audiences.create_ad_audience(
    account_id="acc_googleads_123",
    ad_account_id="1234567890",  # Google Ads customer ID
    type="customer_list",
    name="Newsletter subscribers",
)

# 2. Upload members to the returned audience id
client.ad_audiences.add_users_to_ad_audience(
    audience_id="aud_abc123",  # id from the create response
    users=[{"email": "jane@example.com"}, {"email": "sam@example.com"}],
)
```
</Tab>
<Tab value="curl">
```bash
# 1. Create
curl -X POST "https://zernio.com/api/v1/ads/audiences" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "accountId": "acc_googleads_123", "adAccountId": "1234567890", "type": "customer_list", "name": "Newsletter subscribers" }'

# 2. Upload members (use the audience id from the create response)
curl -X POST "https://zernio.com/api/v1/ads/audiences/AUDIENCE_ID/users" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "users": [{ "email": "jane@example.com" }, { "email": "sam@example.com" }] }'
```
</Tab>
</Tabs>

## Media Requirements

| Type | Format | Max Size | Notes |
|------|--------|----------|-------|
| Responsive Search Ad | Text | 15 headlines / 4 descriptions | 30/90 chars |
| Responsive Display (landscape) | JPEG, PNG | 5120 KB | 1.91:1, 1200x628 recommended. Required. |
| Responsive Display (square) | JPEG, PNG | 5120 KB | 1:1, 1080x1080 recommended. Required. |
| Keyword | Text | 80 chars | BROAD, PHRASE, EXACT |

## Version Migrations

Google Ads API ships v22, v23, v24... twice a year with breaking changes. Zernio absorbs these at our layer, so your integration keeps working without code changes.

---

# Overview

Complete guide to all social media platforms supported by Zernio API

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Zernio supports 15 major social media platforms. Each platform page includes quick start examples, media requirements, and platform-specific features.

## Platform Quick Reference

<PlatformOverviewTable />

## Getting Started

### 1. Connect an Account

Each platform uses OAuth or platform-specific authentication. Start by connecting an account:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { url } = await zernio.connect.getConnectUrl({
  path: { platform: 'twitter' },
  query: { profileId: 'YOUR_PROFILE_ID' },
});
// Redirect the user to `url` to start the OAuth flow.
```
</Tab>
<Tab value="Python">
```python
res = client.connect.get_connect_url(
    platform="twitter",
    profile_id="YOUR_PROFILE_ID",
)
# Redirect the user to res["url"] to start the OAuth flow.
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/connect/{platform}?profileId=YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Replace `{platform}` with: `twitter`, `instagram`, `facebook`, `linkedin`, `tiktok`, `youtube`, `pinterest`, `reddit`, `bluesky`, `threads`, `googlebusiness`, `telegram`, `snapchat`, `whatsapp`, or `discord`.

### 2. Create a Post

Once connected, create posts targeting specific platforms:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const post = await zernio.posts.createPost({
  body: {
    content: 'Hello from Zernio API!',
    platforms: [
      { platform: 'twitter', accountId: 'YOUR_ACCOUNT_ID' },
    ],
    publishNow: true,
  },
});
```
</Tab>
<Tab value="Python">
```python
post = client.posts.create_post(
    content="Hello from Zernio API!",
    platforms=[
        {"platform": "twitter", "accountId": "YOUR_ACCOUNT_ID"},
    ],
    publish_now=True,
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from Zernio API!",
    "platforms": [
      {"platform": "twitter", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### 3. Cross-Post to Multiple Platforms

Post to multiple platforms simultaneously:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const post = await zernio.posts.createPost({
  body: {
    content: 'Cross-posting to all platforms!',
    platforms: [
      { platform: 'twitter', accountId: 'acc_twitter' },
      { platform: 'linkedin', accountId: 'acc_linkedin' },
      { platform: 'bluesky', accountId: 'acc_bluesky' },
    ],
    publishNow: true,
  },
});
```
</Tab>
<Tab value="Python">
```python
post = client.posts.create_post(
    content="Cross-posting to all platforms!",
    platforms=[
        {"platform": "twitter", "accountId": "acc_twitter"},
        {"platform": "linkedin", "accountId": "acc_linkedin"},
        {"platform": "bluesky", "accountId": "acc_bluesky"},
    ],
    publish_now=True,
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Cross-posting to all platforms!",
    "platforms": [
      {"platform": "twitter", "accountId": "acc_twitter"},
      {"platform": "linkedin", "accountId": "acc_linkedin"},
      {"platform": "bluesky", "accountId": "acc_bluesky"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Platform-Specific Features

Each platform has unique capabilities:

- **Twitter/X** - Threads, polls, scheduled spaces
- **Instagram** - Stories, Reels, Carousels, Collaborators
- **Facebook** - Reels, Stories, Page posts
- **LinkedIn** - Documents (PDFs), Company pages, Personal profiles
- **TikTok** - Privacy settings, duet/stitch controls
- **YouTube** - Shorts, playlists, visibility settings
- **Pinterest** - Boards, Rich pins
- **Reddit** - Subreddits, flairs, NSFW tags, native video uploads (with videogif and custom poster support)
- **Bluesky** - Custom feeds, app passwords
- **Threads** - Reply controls
- **Google Business** - Location posts, offers, events, performance metrics, search keywords
- **Telegram** - Channels, groups, silent messages, protected content
- **Snapchat** - Stories, Saved Stories, Spotlight, Public Profiles
- **WhatsApp** - Template messages, broadcasts, contacts, conversations, Flows (interactive forms)
- **Discord** - Messages, embeds, native polls, forum posts, threads, crosspost

## Analytics KPIs Matrix

Which metrics does the [Analytics API](/analytics/get-analytics) return for each platform?

| Platform | Impressions | Reach | Likes | Comments | Shares | Saves | Clicks | Views |
|----------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| Instagram | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | - | ✅ |
| Facebook | ✅ | - | ✅ | ✅ | ✅ | - | ✅ | ✅ |
| Twitter/X | ✅ | - | ✅ | ✅ | ✅ | - | ✅ | ✅ |
| LinkedIn | ✅ | ✅ | ✅ | ✅ | ✅ | - | ✅ | ✅\* |
| TikTok | - | - | ✅ | ✅ | ✅ | - | - | ✅ |
| YouTube | - | - | ✅ | ✅ | ✅\*\* | - | - | ✅ |
| Threads | ✅ | - | ✅ | ✅ | ✅ | - | - | ✅ |
| Bluesky | - | - | ✅ | ✅ | ✅ | - | - | - |
| Reddit | - | - | ✅ | ✅ | - | - | - | - |
| Pinterest | ✅ | - | - | - | - | ✅ | ✅ | - |
| Snapchat | - | ✅ | - | - | ✅ | - | - | ✅ |
| Telegram | - | - | - | - | - | - | - | - |
| WhatsApp | - | - | - | - | - | - | - | - |
| Google Business\*\*\* | - | - | - | - | - | - | - | - |

\* LinkedIn views only for video posts

\*\* YouTube shares only available via daily Analytics API, not basic Data API

\*\*\* Google Business per-post analytics deprecated by Google with no replacement. Use the [Performance API](/analytics/get-google-business-performance) for location-level metrics (impressions, clicks, calls, directions, bookings).

YouTube also supports [audience demographics](/analytics/get-youtube-demographics) (age, gender, country breakdowns) via a dedicated endpoint.

Google Business also supports [daily performance metrics](/analytics/get-google-business-performance) (impressions, clicks, calls, directions, bookings) and [search keywords](/analytics/get-google-business-search-keywords) via dedicated endpoints.

## Inbox Feature Matrix

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

The Inbox API provides a unified interface for managing DMs, comments, and reviews across all platforms.

### DMs Support

| Platform | List | Fetch | Send Text | Attachments | Quick Replies | Buttons | Edit | Archive |
|----------|------|-------|-----------|-------------|---------------|---------|------|---------|
| Facebook | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | - | ✅ |
| Instagram | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | - | ✅ |
| Twitter/X | ✅ | ✅ | ✅ | ✅ | - | - | - | ❌ |
| Bluesky | ✅ | ✅ | ✅ | ❌ | - | - | - | ✅ |
| Reddit | ✅ | ✅ | ✅ | ❌ | - | - | - | ✅ |
| Telegram | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| WhatsApp | ✅ | ✅ | ✅ | ✅ | - | - | - | ✅ |

### Comments Support

| Platform | List | Post | Reply | Delete | Like | Hide |
|----------|------|------|-------|--------|------|------|
| Facebook | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Instagram | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ |
| Twitter/X | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Bluesky | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| Threads | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ |
| Reddit | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| YouTube | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| LinkedIn | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| TikTok | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |

### Reviews Support

| Platform | List | Reply | Delete Reply |
|----------|------|-------|--------------|
| Facebook | ✅ | ✅ | ❌ |
| Google Business | ✅ | ✅ | ✅ |

### Webhooks

Base message + comment events:

| Platform | `comment.received` | `message.received` | `message.sent` |
|----------|:---:|:---:|:---:|
| Instagram | ✅ | ✅ | ✅ |
| Facebook | ✅ | ✅ | ✅ |
| Twitter/X | ✅ | - | - |
| YouTube | ✅ | - | - |
| LinkedIn | ✅ | - | - |
| Bluesky | ✅ | ✅ | ✅ |
| Reddit | ✅ | ✅ | ✅ |
| Telegram | - | ✅ | ✅ |
| WhatsApp | - | ✅ | ✅ |

Message lifecycle events (edits, unsends, delivery status):

| Platform | `message.edited` | `message.deleted` | `message.delivered` | `message.read` | `message.failed` |
|----------|:---:|:---:|:---:|:---:|:---:|
| Instagram | ✅ | ✅ |, | ✅ |, |
| Facebook | ✅ |, | ✅ | ✅ |, |
| WhatsApp |, | ✅ (business-side) | ✅ | ✅ | ✅ |
| Telegram | ✅ |, |, |, |, |
| Twitter/X |, |, |, |, |, |
| Bluesky |, |, |, |, |, |
| Reddit |, |, |, |, |, |

Dashes indicate the underlying platform API does not expose that event; the gap is a platform limitation, not a Zernio one.

### Account Settings

| Platform | Feature | Endpoint |
|----------|---------|----------|
| Facebook | Persistent menu | `/v1/accounts/{accountId}/messenger-menu` |
| Instagram | Ice breakers | `/v1/accounts/{accountId}/instagram-ice-breakers` |
| Telegram | Bot commands | `/v1/accounts/{accountId}/telegram-commands` |

See [Account Settings](/account-settings/get-messenger-menu) for full endpoint documentation.

### No Support

| Platform | Status | Notes |
|----------|--------|-------|
| Pinterest | No API | No inbox features available |
| Snapchat | No API | No inbox features available |
| TikTok | Not supported | No inbox features available |

### Platform Limitations

| Platform | Limitation |
|----------|------------|
| Instagram | Reply-only comments, no comment likes (deprecated 2018) |
| Twitter/X | DMs require `dm.read` and `dm.write` scopes, no archive/unarchive, reply search cached (2-min TTL) |
| Bluesky | No DM attachments, like requires CID |
| Threads | No DMs, no comment likes, reply-only comments (no top-level), supports hide/unhide |
| Reddit | No DM attachments |
| Telegram | Bot-based, media limits (photos 10MB, videos 50MB) |
| YouTube | No DMs, no comment likes |
| LinkedIn | Org accounts only, no comment likes |
| WhatsApp | Template messages required outside 24h window, no comment support |

See [Messages](/messages/list-inbox-conversations), [Comments](/comments/list-inbox-comments), and [Reviews](/reviews/list-inbox-reviews) API Reference for full endpoint documentation.

## Ad Platforms

<Callout type="info">
**Included** — Ads (Meta, TikTok, LinkedIn, Pinterest, X, Google) is bundled with every paid account on the [Usage plan](/pricing).
</Callout>

Zernio also supports paid advertising across 6 ad networks via the `/v1/ads` endpoints. Create standalone campaigns, boost organic posts, manage audiences, and pull analytics from one REST API.

| Platform | Key | Create | Boost | Audiences | Analytics |
|----------|-----|--------|-------|-----------|-----------|
| [Meta Ads](/platforms/meta-ads) (Facebook + Instagram) | `metaads` | Yes | Yes | Custom + Lookalike | Yes |
| [Google Ads](/platforms/google-ads) | `googleads` | Search + Display | No | No | Yes |
| [LinkedIn Ads](/platforms/linkedin-ads) | `linkedinads` | Yes | Yes | Read-only | Yes |
| [TikTok Ads](/platforms/tiktok-ads) | `tiktokads` | Yes | Spark Ads | Custom + Lookalike | Yes |
| [Pinterest Ads](/platforms/pinterest-ads) | `pinterestads` | Yes | Yes | Basic | Yes |
| [X Ads](/platforms/x-ads) | `xads` | Yes | Yes | No | Yes |

### Ad Hierarchy

| Platform | Top Level | Middle | Bottom |
|----------|-----------|--------|--------|
| Meta Ads | Campaign | Ad Set | Ad |
| Google Ads | Campaign | Ad Group | Ad |
| LinkedIn Ads | Campaign Group | Campaign | Creative |
| TikTok Ads | Campaign | Ad Group | Ad |
| Pinterest Ads | Campaign | Ad Group | Pin |
| X Ads | Campaign | Line Item | Promoted Tweet |

See each platform's page for Quick Start code examples (Node.js, Python, curl) and full endpoint docs.

## API Reference

- [Connect Account](/guides/connecting-accounts) - OAuth flow for all platforms
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Image and video uploads
- [Analytics](/analytics/get-analytics) - Post performance metrics
- [Ads](/ads/list-ads) - Ad management, boost, and analytics
- [Messages](/messages/list-inbox-conversations), [Comments](/comments/list-inbox-comments), and [Reviews](/reviews/list-inbox-reviews)
- [Account Settings](/account-settings/get-messenger-menu) - Platform-specific messaging settings

---

# Instagram

Schedule and automate Instagram posts with Zernio API - Feed, Stories, Reels, Carousels, collaborators, and user tags

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Reference

| Property | Value |
|----------|-------|
| Character limit | 2,200 (caption) |
| Images per post | 1 (feed), 10 (carousel) |
| Videos per post | 1 |
| Image formats | JPEG, PNG |
| Image max size | 8 MB (auto-compressed) |
| Video formats | MP4, MOV |
| Video max size | 300 MB (feed/reels), 100 MB (stories) |
| Video max duration | 90 sec (reels), 60 min (feed), 60 sec (story) |
| Post types | Feed, Carousel, Story, Reel |
| Scheduling | Yes |
| Inbox (DMs) | Yes |
| Inbox (Comments) | Yes (reply-only) |
| Comment-to-DM automations | Yes |
| Story-reply automations | Yes |
| Analytics | Yes |

## Before You Start

<Callout type="warn">
Instagram **requires** a Business or Creator account. Personal accounts cannot post via API.

Google Drive, Dropbox, OneDrive, and iCloud links **do not work** as media URLs. These services return HTML pages, not media files. Instagram's servers cannot fetch media from them. Use direct CDN URLs or upload via Zernio's [media endpoint](/guides/media-uploads).

Additional requirements:
- Media is required for all posts (no text-only)
- 100 posts per 24-hour rolling window (all content types combined)
- First 125 characters of caption are visible before the "more" fold
</Callout>

## Quick Start

Post an image to Instagram in under 60 seconds:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Check out this photo!',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/photo.jpg' }
  ],
  platforms: [
    { platform: 'instagram', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to Instagram!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Check out this photo!",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/photo.jpg"}
    ],
    platforms=[
        {"platform": "instagram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to Instagram! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out this photo!",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/photo.jpg"}
    ],
    "platforms": [
      {"platform": "instagram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

### Feed Post

A single image or video in the main feed. Best aspect ratio is 4:5 (portrait), but 1:1 (square) and 1.91:1 (landscape) are also supported. No `contentType` field is needed -- feed is the default.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Beautiful sunset today #photography',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/sunset.jpg' }
  ],
  platforms: [
    { platform: 'instagram', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Feed post created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Beautiful sunset today #photography",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/sunset.jpg"}
    ],
    platforms=[
        {"platform": "instagram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Feed post created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Beautiful sunset today #photography",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/sunset.jpg"}
    ],
    "platforms": [
      {"platform": "instagram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Carousel

Up to 10 mixed image/video items. All items should share the same aspect ratio -- the first item determines the ratio for the entire carousel.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Trip highlights from last weekend',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/photo1.jpg' },
    { type: 'image', url: 'https://cdn.example.com/photo2.jpg' },
    { type: 'video', url: 'https://cdn.example.com/clip.mp4' },
    { type: 'image', url: 'https://cdn.example.com/photo3.jpg' }
  ],
  platforms: [
    { platform: 'instagram', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Carousel posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Trip highlights from last weekend",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/photo1.jpg"},
        {"type": "image", "url": "https://cdn.example.com/photo2.jpg"},
        {"type": "video", "url": "https://cdn.example.com/clip.mp4"},
        {"type": "image", "url": "https://cdn.example.com/photo3.jpg"}
    ],
    platforms=[
        {"platform": "instagram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Carousel posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Trip highlights from last weekend",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/photo1.jpg"},
      {"type": "image", "url": "https://cdn.example.com/photo2.jpg"},
      {"type": "video", "url": "https://cdn.example.com/clip.mp4"},
      {"type": "image", "url": "https://cdn.example.com/photo3.jpg"}
    ],
    "platforms": [
      {"platform": "instagram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Story

Set `contentType: "story"` to publish to Stories. Stories disappear after 24 hours, text captions are not displayed, and link stickers are not available via the API (this is a limitation of Instagram's Graph API, not Zernio).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/story.jpg' }
  ],
  platforms: [{
    platform: 'instagram',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      contentType: 'story'
    }
  }],
  publishNow: true
});
console.log('Story posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/story.jpg"}
    ],
    platforms=[{
        "platform": "instagram",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "contentType": "story"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Story posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/story.jpg"}
    ],
    "platforms": [{
      "platform": "instagram",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "contentType": "story"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Reel

Set `contentType: "reels"` to publish a Reel, or let Zernio auto-detect it from vertical 9:16 video under 90 seconds. Reels must be vertical (9:16) and no longer than 90 seconds.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'New tutorial is up!',
  mediaItems: [
    { type: 'video', url: 'https://cdn.example.com/reel.mp4' }
  ],
  platforms: [{
    platform: 'instagram',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      contentType: 'reels',
      shareToFeed: true
    }
  }],
  publishNow: true
});
console.log('Reel posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="New tutorial is up!",
    media_items=[
        {"type": "video", "url": "https://cdn.example.com/reel.mp4"}
    ],
    platforms=[{
        "platform": "instagram",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "contentType": "reels",
            "shareToFeed": True
        }
    }],
    publish_now=True
)
post = result.post
print(f"Reel posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New tutorial is up!",
    "mediaItems": [
      {"type": "video", "url": "https://cdn.example.com/reel.mp4"}
    ],
    "platforms": [{
      "platform": "instagram",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "contentType": "reels",
        "shareToFeed": true
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Media Requirements

### Images

| Property | Feed Post | Story | Carousel |
|----------|-----------|-------|----------|
| **Max images** | 1 | 1 | 10 |
| **Formats** | JPEG, PNG | JPEG, PNG | JPEG, PNG |
| **Max file size** | 8 MB | 8 MB | 8 MB each |
| **Recommended** | 1080 x 1350 px | 1080 x 1920 px | 1080 x 1080 px |

#### Aspect Ratios

| Orientation | Ratio | Dimensions | Notes |
|-------------|-------|------------|-------|
| Portrait | 4:5 | 1080 x 1350 px | Best engagement for feed posts |
| Square | 1:1 | 1080 x 1080 px | Standard feed and carousel |
| Landscape | 1.91:1 | 1080 x 566 px | Widest allowed for feed |
| Vertical | 9:16 | 1080 x 1920 px | Stories and Reels only |

Feed posts accept aspect ratios between 0.8 (4:5) and 1.91 (1.91:1). Images outside that range must be posted as Stories or Reels.

### Videos

| Property | Feed | Reel | Story |
|----------|------|------|-------|
| **Formats** | MP4, MOV | MP4, MOV | MP4, MOV |
| **Max file size** | 300 MB | 300 MB | 100 MB |
| **Max duration** | 60 min | 90 sec | 60 sec |
| **Min duration** | 3 sec | 3 sec | 3 sec |
| **Aspect ratio** | 4:5 to 1.91:1 | 9:16 | 9:16 |
| **Resolution** | 1080 px wide | 1080 x 1920 px | 1080 x 1920 px |
| **Codec** | H.264 | H.264 | H.264 |
| **Frame rate** | 30 fps | 30 fps | 30 fps |

Oversized media is auto-compressed. Images above 8 MB, videos above 300 MB (feed/reels) or 100 MB (stories) are compressed automatically. Original files are preserved.

## Platform-Specific Fields

All fields go inside `platformSpecificData` on the Instagram platform entry.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `contentType` | `"story"` \| `"reels"` | (feed) | Omit for regular feed post. Set to `"story"` for Stories or `"reels"` for Reels. |
| `shareToFeed` | boolean | `true` | Reel-specific. Set to `false` to show the Reel in the Reels tab only, not the main feed. |
| `collaborators` | Array\<string\> | -- | Up to 3 usernames. Must be public Business/Creator accounts. Does not work with Stories. |
| `userTags` | Array\<\{username, x, y, mediaIndex?\}\> | -- | Tag users in images (not videos). Coordinates are 0.0 to 1.0. `mediaIndex` targets a specific carousel slide (0-based, defaults to 0). |
| `trialParams` | \{graduationStrategy\} | -- | Trial Reels, shown only to non-followers. `graduationStrategy` is `"MANUAL"` or `"SS_PERFORMANCE"` (auto-graduate if it performs well). |
| `thumbOffset` | number (ms) | `0` | Millisecond offset from video start to use as thumbnail. Ignored if `instagramThumbnail` is set. |
| `instagramThumbnail` | string (URL) | -- | Custom thumbnail for Reels. JPEG or PNG, recommended 1080 x 1920 px. Takes priority over `thumbOffset`. |
| `audioName` | string | -- | Custom audio name for Reels (replaces "Original Audio"). Can only be set at creation. |
| `firstComment` | string | -- | Auto-posted as the first comment. Works with feed posts and carousels, not Stories. Useful for links since captions do not have clickable links. |

## Media URL Requirements

<Callout type="error">
**These do not work as media URLs:**
- **Google Drive** -- returns an HTML download page, not the file
- **Dropbox** -- returns an HTML preview page
- **OneDrive / SharePoint** -- returns HTML
- **iCloud** -- returns HTML

Test your URL in an incognito browser window. If you see a webpage instead of the raw image or video, it will not work.
</Callout>

Media URLs must be:
- Publicly accessible (no authentication required)
- Returning actual media bytes with the correct `Content-Type` header
- Not behind redirects that resolve to HTML pages
- Hosted on a fast, reliable CDN

**Supabase URLs:** Zernio auto-proxies Supabase storage URLs, so they work without additional configuration.

## Analytics

> **Included** — Analytics is bundled with every paid account on the [Usage plan](/pricing).

Available metrics via the [Analytics API](/analytics/get-analytics):

| Metric | Available |
|--------|-----------|
| Impressions | ✅ |
| Reach | ✅ |
| Likes | ✅ |
| Comments | ✅ |
| Shares | ✅ |
| Saves | ✅ |
| Views | ✅ |

Instagram also provides dedicated analytics endpoints for deeper insights:

- **[Account Insights](/analytics/get-instagram-account-insights)** -- Account-level reach, views, accounts engaged, total interactions, follows_and_unfollows, profile links taps. Business or Creator accounts only. Note: only reach supports metricType=time_series; all other metrics (including follows_and_unfollows) are total_value only (Instagram API limitation).
- **[Follower History](/analytics/get-instagram-follower-history)** -- Daily running follower count time series plus followers_gained and followers_lost deltas. Served from Zernio's daily snapshotter since Instagram removed follower_count from its /insights endpoint in Graph API v22+ and never exposed a historical daily series.
- **[Demographics](/analytics/get-instagram-demographics)** -- Audience breakdowns by age, city, country, or gender. Requires at least 100 followers.

### Stories

Stories live for 24 hours. Zernio exposes two endpoints to read them while they're alive plus persists final-state metrics via Meta's `story_insights` webhook so insights remain queryable after the story expires.

- **[List active stories](/instagram/list-instagram-stories)** -- `GET /v1/accounts/{accountId}/instagram/stories` returns the currently-active stories with `mediaType`, `permalink`, `mediaUrl`, `thumbnailUrl`, and `timestamp`. Live videos, reshared stories, and copyright-flagged media are excluded by Meta. `caption`, `likeCount`, and `commentsCount` do not apply to story media.
- **[Story insights](/instagram/get-instagram-story-insights)** -- `GET /v1/accounts/{accountId}/instagram/stories/{storyId}/insights` returns `views`, `reach`, `replies`, `shares`, `profileVisits`, `follows`, `totalInteractions`, and the navigation breakdown (`tapsForward`, `tapsBack`, `exits`, `swipesForward`). The response includes a `source` field of `live` (story still active, fetched from Meta), `cached` (story expired but its `story_insights` webhook payload was captured), or `unavailable` (expired and no webhook payload was captured -- typical when the account connected after the story expired). Counts below 5 may be returned as 0 due to Meta's privacy floor on small audiences.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const analytics = await zernio.analytics.getAnalytics({
  platform: 'instagram',
  fromDate: '2024-01-01',
  toDate: '2024-01-31'
});
console.log(analytics.posts);
```
</Tab>
<Tab value="Python">
```python
analytics = client.analytics.get_analytics(
    platform="instagram",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(analytics["posts"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics?platform=instagram&fromDate=2024-01-01&toDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

## What You Can't Do

These features are not available through Instagram's API:

- Add music to Reels
- Use story stickers (polls, questions, links, countdowns)
- Add location tags
- Go Live
- Create Guides
- Apply filters
- Tag products
- Post to personal accounts (Business or Creator only)
- Create top-level comments (reply-only through the API)

## Common Errors

Instagram has a **10.2% failure rate** across Zernio's platform (35,634 failures out of 348,438 attempts). Here are the most frequent errors and how to fix them:

| Error | Meaning | Fix |
|-------|---------|-----|
| "Cannot process video from this URL. Instagram cannot fetch videos from Google Drive, Dropbox, or OneDrive." | A cloud storage sharing link was used instead of a direct media URL | Use a direct CDN URL. Test in an incognito window -- if you see a webpage, it will not work. |
| "You have reached the maximum of 100 posts per day." | Instagram's hard 24-hour rolling limit | Reduce posting volume. This limit includes all content types (feed, stories, reels, carousels). |
| "Instagram blocked your request." | Automation detection triggered | Reduce posting frequency, vary content. Wait before retrying. |
| "Duplicate content detected." | Identical content was already published recently | Modify the caption or media before retrying. |
| "Media fetch failed, retrying... (failed after 3 attempts)" | Zernio could not download media from the provided URL | Verify the URL is publicly accessible and returns actual media bytes, not an HTML page. |
| "Instagram access token expired." | The OAuth token for this account has expired | Reconnect the account. Subscribe to the `account.disconnected` webhook to catch this proactively. |

## Inbox

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

Instagram supports DMs and comments with some limitations.

### Direct Messages

| Feature | Supported |
|---------|-----------|
| List conversations | ✅ |
| Fetch messages | ✅ |
| Send text messages | ✅ |
| Send attachments | ✅ (images, videos, audio via URL) |
| Quick replies | ✅ (up to 13, Meta quick_replies) |
| Buttons | ✅ (up to 3, generic template) |
| Carousels | ✅ (generic template, up to 10 elements) |
| Message tags | ✅ (`HUMAN_AGENT` only) |
| Archive/unarchive | ✅ |

**Attachment limits:** 8 MB images, 25 MB video/audio. Attachments are automatically uploaded to temp storage and sent as URLs.

**Message tags:** Use `messageTag: "HUMAN_AGENT"` with `messagingType: "MESSAGE_TAG"` to send messages outside the 24-hour messaging window.

#### Instagram Profile Data

Instagram conversations include an optional `instagramProfile` object on participants and webhook senders, useful for routing and automation:

| Field | Type | Description |
|-------|------|-------------|
| `isFollower` | boolean | Whether the participant follows your business account |
| `isFollowing` | boolean | Whether your business account follows the participant |
| `followerCount` | integer | The participant's follower count |
| `isVerified` | boolean | Whether the participant is a verified Instagram user |
| `fetchedAt` | datetime | When this data was last fetched (conversations only) |

Available in:
- `GET /v1/inbox/conversations` and `GET /v1/inbox/conversations/{id}` - on each participant
- `message.received` webhook - on `message.sender`

### Ice Breakers

Manage ice breaker prompts shown when users start a new Instagram DM conversation. Max 4 ice breakers, question max 80 characters.

See [Account Settings](/account-settings/get-instagram-ice-breakers) for the `GET/PUT/DELETE /v1/accounts/{accountId}/instagram-ice-breakers` endpoints.

### Comments

| Feature | Supported |
|---------|-----------|
| List comments on posts | ✅ |
| Post new top-level comment | ❌ (reply-only) |
| Reply to comments | ✅ |
| Delete comments | ✅ |
| Like comments | ❌ (deprecated since 2018) |
| Hide/unhide comments | ✅ |
| Send private reply (DM after comment) | ✅ (text + up to 13 quick replies OR 1-3 inline buttons, 7-day window, one per comment) |

### Webhooks

Instagram emits the full set of message lifecycle webhooks:

| Event | When it fires |
|-------|---------------|
| `message.received` | New incoming DM |
| `message.sent` | Outgoing DM is sent |
| `message.edited` | The sender edits a previously-sent message |
| `message.deleted` | The sender unsends a message |
| `message.read` | The customer reads an outgoing DM |

Messages are stored locally via webhooks. See the [Webhooks](/webhooks) page for payload details.

**`message.deleted` note:** the payload retains the original `text` and `attachments` so API consumers can access pre-delete content for moderation or compliance use cases. The Zernio dashboard UI hides that content.

### Limitations

- **Reply-only comments** - Cannot post new top-level comments, only replies to existing comments
- **No comment likes** - Liking comments was deprecated in 2018

See [Messages](/messages/list-inbox-conversations) and [Comments](/comments/list-inbox-comments) API Reference for endpoint details.

## Related Endpoints

- [Connect Instagram Account](/guides/connecting-accounts) - OAuth flow via Facebook Business
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Image and video uploads
- [Analytics](/analytics/get-analytics) - Post performance metrics
- [Messages](/messages/list-inbox-conversations) and [Comments](/comments/list-inbox-comments) - Inbox API
- [Account Settings](/account-settings/get-instagram-ice-breakers) - Ice breakers configuration

---

# LinkedIn Ads

Create and boost LinkedIn campaigns via Zernio API - No Marketing Developer Platform application required

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

<Callout type="info">
**Included with the [Usage plan](/pricing).** No LinkedIn Marketing Developer Platform application needed. Zernio is an approved partner.
</Callout>

## What's Supported

| Feature | Status |
|---------|--------|
| Boost Company Page posts | Yes |
| Create Single Image / Single Video Ads from scratch (`/v1/ads/create`) | Yes |
| Campaign Group > Campaign > Creative hierarchy | Yes |
| Location + language targeting | Yes |
| Matched Audiences (read + create list-upload segments) | Yes |
| Real-time analytics (spend, CPC, CPM) | Yes |
| Conversions API (CAPI) | Yes |
| Conversion rule CRUD + campaign associations | Yes |
| Conversion attribution metrics readback | Yes |
| Campaign URL tracking tags (Dynamic UTM) — read + update ([details](#url-tracking-tags)) | Yes |
| B2B targeting (job title, seniority, company size) | Roadmap |
| Lead Gen Forms | Roadmap |
| Other ad types from scratch (Carousel / Document / Text / Dynamic / Message) | Roadmap |

## Boost a Company Page Post

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.boostPost({ body: {
  postId: "POST_ID",
  accountId: "ACCOUNT_ID",
  adAccountId: "517258773",            // numeric sponsored account ID (from /v1/ads/accounts)
  name: "Boost product launch",
  goal: "engagement",
  budget: { amount: 50, type: "daily" },
  schedule: { startDate: "2026-04-20", endDate: "2026-04-27" },
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.boost_post(
    post_id="POST_ID",
    account_id="ACCOUNT_ID",
    ad_account_id="517258773",  # numeric sponsored account ID (from /v1/ads/accounts)
    name="Boost product launch",
    goal="engagement",
    budget={"amount": 50, "type": "daily"},
    schedule={"startDate": "2026-04-20", "endDate": "2026-04-27"},
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/boost" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postId": "POST_ID",
    "accountId": "ACCOUNT_ID",
    "adAccountId": "517258773",
    "name": "Boost product launch",
    "goal": "engagement",
    "budget": { "amount": 50, "type": "daily" },
    "schedule": { "startDate": "2026-04-20", "endDate": "2026-04-27" }
  }'
```
</Tab>
</Tabs>

## Create a Single Image or Video Ad

Build an ad from scratch, no existing post needed. Zernio creates a Direct Sponsored Content ("dark post") authored by your Company Page (it never appears on the Page's feed; it only runs as the ad), then wraps it in a campaign group, campaign, and creative.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.createStandaloneAd({ body: {
  accountId: "ACCOUNT_ID",
  adAccountId: "517258773",            // numeric sponsored account ID
  organizationId: "107655573",          // Company Page that authors the ad (or "urn:li:organization:107655573")
  name: "Spring launch (single image)",
  goal: "traffic",                      // engagement | traffic | awareness
  budgetAmount: 50,
  budgetType: "daily",
  headline: "Schedule social posts in one API call",
  body: "The social media API built for developers.",   // post commentary (intro text above the ad)
  imageUrl: "https://cdn.example.com/launch-1200x627.jpg",
  linkUrl: "https://zernio.com",        // destination, required when goal is "traffic"
  callToAction: "LEARN_MORE",           // defaults to LEARN_MORE when linkUrl is set
  countries: ["US"],
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.create_standalone_ad(
    account_id="ACCOUNT_ID",
    ad_account_id="517258773",
    organization_id="107655573",
    name="Spring launch (single image)",
    goal="traffic",
    budget_amount=50,
    budget_type="daily",
    headline="Schedule social posts in one API call",
    body="The social media API built for developers.",
    image_url="https://cdn.example.com/launch-1200x627.jpg",
    link_url="https://zernio.com",
    call_to_action="LEARN_MORE",
    countries=["US"],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "ACCOUNT_ID",
    "adAccountId": "517258773",
    "organizationId": "107655573",
    "name": "Spring launch (single image)",
    "goal": "traffic",
    "budgetAmount": 50,
    "budgetType": "daily",
    "headline": "Schedule social posts in one API call",
    "body": "The social media API built for developers.",
    "imageUrl": "https://cdn.example.com/launch-1200x627.jpg",
    "linkUrl": "https://zernio.com",
    "callToAction": "LEARN_MORE",
    "countries": ["US"]
  }'
```
</Tab>
</Tabs>

### Video ads

For a **single video ad**, swap `imageUrl` for `video: { url }` (the two are mutually exclusive). The clip is uploaded to LinkedIn under the Company Page, the campaign format becomes `SINGLE_VIDEO`, and the `video_views` goal becomes available (it requires a video). LinkedIn auto-generates the poster frame, so a thumbnail isn't required. The request blocks while LinkedIn transcodes the video (short clips take ~10-30s).

```typescript
const ad = await zernio.ads.createStandaloneAd({ body: {
  accountId: "ACCOUNT_ID",
  adAccountId: "517258773",
  organizationId: "107655573",
  name: "Spring launch (video)",
  goal: "video_views",                  // engagement | traffic | awareness | video_views
  budgetAmount: 50,
  budgetType: "daily",
  headline: "See it in action",
  body: "The social media API built for developers.",
  video: { url: "https://cdn.example.com/launch.mp4" },   // MP4 H.264/AAC, 3s-30min, 75KB-500MB
  linkUrl: "https://zernio.com",        // optional unless goal is "traffic"
  callToAction: "LEARN_MORE",
  countries: ["US"],
}});
```

<Callout type="info">
**The ad runs as a Direct Sponsored Content post authored by a Company Page.** Pass that page via `organizationId` (a numeric organization ID or a full `urn:li:organization:N` URN). If you connected the page itself as a Zernio account, or your ad account is owned by an organization, it's inferred and `organizationId` is optional. The authenticated LinkedIn member must be an **Administrator** or **Direct Sponsored Content Poster** of that page, and the page must be associated with the ad account, or LinkedIn returns `403`.

Supported `goal` values: `engagement`, `traffic`, `awareness`, `video_views` (`video_views` requires `video`). `traffic` requires `linkUrl`. `headline` is required; supply exactly one of `imageUrl` or `video`. `body` becomes the post's intro text; `longHeadline` (optional) becomes the secondary description line on image link ads. `callToAction` accepts `LEARN_MORE`, `SIGN_UP`, `DOWNLOAD`, `SUBSCRIBE`, `REGISTER`, `JOIN`, `ATTEND`, `REQUEST_DEMO`, `VIEW_QUOTE`, `APPLY`, `SEE_MORE`, `SHOP_NOW`, `BUY_NOW`. The image is uploaded to LinkedIn under the Company Page; recommended ratio **1.91:1** (e.g. 1200×627), JPEG/PNG/GIF.

Carousel, document, text, lead-gen, and conversion-optimized LinkedIn ads aren't supported via `/v1/ads/create` yet; use `/v1/ads/boost` to promote an existing post of any type in the meantime.
</Callout>

## Budget Minimums

LinkedIn enforces a **$10/day** minimum for any ad format and **$100** minimum lifetime budget for inactive campaigns.

## Matched Audiences

Create a list-upload (contact list) DMP segment and upload members. `adAccountId` is the LinkedIn sponsored account ID. Email only (any `phone` is ignored); values are SHA256-hashed server-side.

Two LinkedIn-specific notes: each upload is a **full replace** of the segment's members (not an append), and LinkedIn segments **cannot be deleted via the API** — remove them from Campaign Manager.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// 1. Create the (empty) list-upload segment
await zernio.adaudiences.createAdAudience({
  body: {
    accountId: 'acc_linkedinads_123',
    adAccountId: '517258773', // LinkedIn sponsored account ID
    type: 'customer_list',
    name: 'Webinar attendees',
  },
});

// 2. Upload the member list (full replace each call)
await zernio.adaudiences.addUsersToAdAudience({
  path: { audienceId: 'aud_abc123' }, // id from the create response
  body: { users: [{ email: 'jane@example.com' }, { email: 'sam@example.com' }] },
});
```
</Tab>
<Tab value="Python">
```python
# 1. Create the (empty) list-upload segment
client.ad_audiences.create_ad_audience(
    account_id="acc_linkedinads_123",
    ad_account_id="517258773",  # LinkedIn sponsored account ID
    type="customer_list",
    name="Webinar attendees",
)

# 2. Upload the member list (full replace each call)
client.ad_audiences.add_users_to_ad_audience(
    audience_id="aud_abc123",  # id from the create response
    users=[{"email": "jane@example.com"}, {"email": "sam@example.com"}],
)
```
</Tab>
<Tab value="curl">
```bash
# 1. Create
curl -X POST "https://zernio.com/api/v1/ads/audiences" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "accountId": "acc_linkedinads_123", "adAccountId": "517258773", "type": "customer_list", "name": "Webinar attendees" }'

# 2. Upload the member list (use the audience id from the create response)
curl -X POST "https://zernio.com/api/v1/ads/audiences/AUDIENCE_ID/users" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "users": [{ "email": "jane@example.com" }, { "email": "sam@example.com" }] }'
```
</Tab>
</Tabs>

## Media Requirements

| Type | Format | Max Size | Notes |
|------|--------|----------|-------|
| Single Image | JPEG, PNG, GIF | 5 MB | 1200x627 recommended |
| Video | MP4 | 200 MB | 3s-30min, 75 MB recommended |
| Carousel | JPEG, PNG | 10 MB/card | 2-10 cards, 1080x1080 |

## Conversions API

Stream offline conversion events (deal closed, lead qualified, trial converted, purchase) back to LinkedIn through the same unified `/v1/ads/conversions` endpoint you already use for Meta and Google. Zernio uses the LinkedIn account you already connected, no separate Conversions API access token to generate from Campaign Manager. PII is SHA-256 hashed server-side per LinkedIn's spec before anything leaves your server (`externalIds` are passed through as plaintext per LinkedIn's requirement).

<Callout type="warn">
**Reconnect required for LinkedIn accounts connected before Zernio shipped Conversions API support.** LinkedIn does not silently upgrade existing OAuth grants with the new `rw_conversions` scope. Accounts that lack it return `403` with code `linkedin_reconnect_required`; pass the user back through the LinkedIn connect flow once and they're set.
</Callout>

### Discover available conversion rules

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.ads.listConversionDestinations({
  path: { accountId: 'ACCOUNT_ID' },
});
```
</Tab>
<Tab value="Python">
```python
data = client.ads.list_conversion_destinations(account_id="ACCOUNT_ID")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/accounts/ACCOUNT_ID/conversion-destinations" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Returns every CONVERSIONS_API rule across every sponsored ad account the connected token can access. Each destination carries an `adAccountId` you'll pass back on subsequent CRUD calls.

### Create a new conversion rule

LinkedIn's conversion rule binds an event `type` (LEAD, PURCHASE, ADD_TO_CART, etc.) to the destination. By default the new rule is auto-associated with every campaign in the ad account; pass `autoAssociationType: "NONE"` to opt out and manage associations explicitly via `/associations`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const dest = await zernio.ads.createConversionDestination({
  path: { accountId: 'ACCOUNT_ID' },
  body: {
    adAccountId: '517258773', // numeric or "urn:li:sponsoredAccount:..."
    name: 'Trial activation',
    type: 'Lead', // unified name OR LinkedIn enum (e.g. "QUALIFIED_LEAD")
    attributionType: 'LAST_TOUCH_BY_CAMPAIGN',
    postClickAttributionWindowSize: 30,
    viewThroughAttributionWindowSize: 7,
  },
});
```
</Tab>
<Tab value="Python">
```python
dest = client.ads.create_conversion_destination(
    account_id="ACCOUNT_ID",
    ad_account_id="517258773",
    name="Trial activation",
    type="Lead",
    attribution_type="LAST_TOUCH_BY_CAMPAIGN",
    post_click_attribution_window_size=30,
    view_through_attribution_window_size=7,
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/accounts/ACCOUNT_ID/conversion-destinations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "adAccountId": "517258773",
    "name": "Trial activation",
    "type": "Lead",
    "attributionType": "LAST_TOUCH_BY_CAMPAIGN",
    "postClickAttributionWindowSize": 30,
    "viewThroughAttributionWindowSize": 7
  }'
```
</Tab>
</Tabs>

### Send a conversion event

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.ads.sendConversions({ body: {
  accountId: 'ACCOUNT_ID',
  destinationId: '25639412', // conversion rule id from listConversionDestinations
  events: [{
    eventName: 'Lead', // informational only — rule type is bound to destination
    eventTime: Math.floor(Date.now() / 1000),
    eventId: 'order_abc_123',
    value: 42.50,
    currency: 'USD',
    user: {
      email: 'customer@example.com',
      firstName: 'Jane',
      lastName: 'Doe',
      country: 'US',
      clickIds: {
        // Optional: improves match rate. Capture from li_fat_id on landing-page URLs
        // after enabling enhanced conversion tracking on the LinkedIn Insight Tag.
        li_fat_id: 'AQH...',
      },
    },
  }],
}});
```
</Tab>
<Tab value="Python">
```python
result = client.ads.send_conversions(
    account_id="ACCOUNT_ID",
    destination_id="25639412",
    events=[{
        "eventName": "Lead",
        "eventTime": int(time.time()),
        "eventId": "order_abc_123",
        "value": 42.50,
        "currency": "USD",
        "user": {
            "email": "customer@example.com",
            "firstName": "Jane",
            "lastName": "Doe",
            "country": "US",
            "clickIds": {"li_fat_id": "AQH..."},
        },
    }],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/conversions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "ACCOUNT_ID",
    "destinationId": "25639412",
    "events": [{
      "eventName": "Lead",
      "eventTime": 1744732800,
      "eventId": "order_abc_123",
      "value": 42.50,
      "currency": "USD",
      "user": {
        "email": "customer@example.com",
        "firstName": "Jane",
        "lastName": "Doe",
        "country": "US",
        "clickIds": { "li_fat_id": "AQH..." }
      }
    }]
  }'
```
</Tab>
</Tabs>

### Standard event names

`Purchase`, `Lead`, `CompleteRegistration`, `AddToCart`, `InitiateCheckout`, `AddPaymentInfo`, `Subscribe`, `StartTrial`, `ViewContent`, `Search`, `Contact`, `SubmitApplication`, `Schedule`. The unified name is informational on LinkedIn — the rule's `type` (set at create time) is what determines the LinkedIn-side conversion category.

### Mapping unified names → LinkedIn `type` enum

| Unified | LinkedIn |
|---|---|
| `Purchase` | `PURCHASE` |
| `Lead` | `LEAD` |
| `CompleteRegistration` | `COMPLETE_SIGNUP` |
| `AddToCart` | `ADD_TO_CART` |
| `InitiateCheckout` | `START_CHECKOUT` |
| `AddPaymentInfo` | `ADD_BILLING_INFO` |
| `Subscribe` | `SUBSCRIBE` |
| `StartTrial` | `START_TRIAL` |
| `ViewContent` | `VIEW_CONTENT` |
| `Search` | `SEARCH` |
| `Contact` | `CONTACT` |
| `SubmitApplication` | `SUBMIT_APPLICATION` |
| `Schedule` | `SCHEDULE` |

You can also pass a LinkedIn enum value directly (e.g. `"QUALIFIED_LEAD"`, `"OUTBOUND_CLICK"`) for types not in the unified set.

### User identifiers

LinkedIn requires at least one of: SHA-256-hashed email, a LinkedIn first-party click ID (`li_fat_id`), an Acxiom or Oracle MOAT identifier, OR `userInfo` containing both `firstName` and `lastName`. Send as many as you have, hashed identifiers materially improve match rate.

### Deduplication

Pass a stable `eventId` on every event. If you also fire the LinkedIn Insight Tag with the same event ID, LinkedIn discards the Conversions API copy and counts only the Insight Tag event. Aligns with LinkedIn's documented dedup behavior.

### Campaign associations

By default `createConversionDestination` auto-associates the new rule with every active, paused, and draft campaign in the ad account (`autoAssociationType: "ALL_CAMPAIGNS"`). Auto-association is one-shot at create time, campaigns added later need explicit association:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.ads.addConversionAssociations({
  path: { accountId: 'ACCOUNT_ID', destinationId: '25639412' },
  body: {
    adAccountId: '517258773',
    campaignIds: ['337643194', '345396555'],
  },
});
```
</Tab>
<Tab value="Python">
```python
result = client.ads.add_conversion_associations(
    account_id="ACCOUNT_ID",
    destination_id="25639412",
    ad_account_id="517258773",
    campaign_ids=["337643194", "345396555"],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/accounts/ACCOUNT_ID/conversion-destinations/25639412/associations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "adAccountId": "517258773", "campaignIds": ["337643194", "345396555"] }'
```
</Tab>
</Tabs>

Returns a per-campaign `succeeded` / `failed` map so you can retry only the rows that didn't take.

### Attribution metrics

Read conversion attribution back from LinkedIn's adAnalytics endpoint, pivoted by date:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.ads.getConversionMetrics({
  path: { accountId: 'ACCOUNT_ID', destinationId: '25639412' },
  query: {
    adAccountId: '517258773',
    startDate: '2026-04-01',
    endDate: '2026-04-30',
    granularity: 'DAILY',
  },
});
```
</Tab>
<Tab value="Python">
```python
data = client.ads.get_conversion_metrics(
    account_id="ACCOUNT_ID",
    destination_id="25639412",
    ad_account_id="517258773",
    start_date="2026-04-01",
    end_date="2026-04-30",
    granularity="DAILY",
)
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/accounts/ACCOUNT_ID/conversion-destinations/25639412/metrics?adAccountId=517258773&startDate=2026-04-01&endDate=2026-04-30&granularity=DAILY" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Returns `externalWebsiteConversions`, `externalWebsitePostClickConversions`, `externalWebsitePostViewConversions`, `conversionValueInLocalCurrency`, `qualifiedLeads`, `costInLocalCurrency` per date bucket.

LinkedIn's retention rules apply: `granularity=DAILY` covers the last ~6 months only; `MONTHLY`/`YEARLY` extends to 24 months; `granularity=ALL` with a range > 6 months auto-rounds to month boundaries.

### Soft-delete

LinkedIn doesn't expose a hard-delete on conversion rules. `DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}?adAccountId=...` flips `enabled: false` (the same operation Campaign Manager's UI delete performs); the rule remains fetchable as `status: 'inactive'`.

### Limits

- 5,000 events per `sendConversions` call (LinkedIn's `BATCH_CREATE` cap)
- 600 requests/min and 300,000 requests/day per token (LinkedIn-side)
- `conversionHappenedAt` must be within the last 90 days
- 365-day attribution windows are only valid for `LEAD`, `PURCHASE`, `ADD_TO_CART`, `QUALIFIED_LEAD`, `SUBMIT_APPLICATION`

## URL tracking tags

LinkedIn's Dynamic UTM Tracking lives at the **campaign** level: a set of params LinkedIn appends to every creative's landing-page URL under that campaign. `dynamicValueParameters` map a key to a LinkedIn token resolved at serve time (`CAMPAIGN_ID`, `CAMPAIGN_NAME`, `CAMPAIGN_GROUP_ID`, `CAMPAIGN_GROUP_NAME`, `CREATIVE_ID`, `ACCOUNT_ID`, `ACCOUNT_NAME`); `customValueParameters` map a key to a static string. Operate on them through the unified ad endpoint, passing any ad in the campaign.

Read the current params:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.ads.getAdTrackingTags({ path: { adId: 'AD_ID' } });
// { platform: 'linkedin', level: 'campaign',
//   dynamicValueParameters: { utm_campaign: 'CAMPAIGN_NAME' },
//   customValueParameters: { utm_source: 'linkedin' } }
```
</Tab>
<Tab value="Python">
```python
data = client.ads.get_ad_tracking_tags(ad_id="AD_ID")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/ads/AD_ID/tracking-tags" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Set or update them (send `dynamicValueParameters` and/or `customValueParameters`):

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.ads.updateAdTrackingTags({
  path: { adId: 'AD_ID' },
  body: {
    dynamicValueParameters: { utm_campaign: 'CAMPAIGN_NAME', utm_content: 'CREATIVE_ID' },
    customValueParameters: { utm_source: 'linkedin', utm_medium: 'paid_social' },
  },
});
```
</Tab>
<Tab value="Python">
```python
data = client.ads.update_ad_tracking_tags(
    ad_id="AD_ID",
    dynamic_value_parameters={"utm_campaign": "CAMPAIGN_NAME", "utm_content": "CREATIVE_ID"},
    custom_value_parameters={"utm_source": "linkedin", "utm_medium": "paid_social"},
)
```
</Tab>
<Tab value="curl">
```bash
curl -X PATCH "https://zernio.com/api/v1/ads/AD_ID/tracking-tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dynamicValueParameters": { "utm_campaign": "CAMPAIGN_NAME", "utm_content": "CREATIVE_ID" },
    "customValueParameters": { "utm_source": "linkedin", "utm_medium": "paid_social" }
  }'
```
</Tab>
</Tabs>

Params set on a campaign apply to all its creatives (existing and new) without re-review. Conversation, Message, and Lead Gen Form ads don't support dynamic UTM params, and any static UTMs baked into a creative's own landing-page URL should not reuse the same keys, or they'll collide.

---

# LinkedIn

Schedule and automate LinkedIn posts with Zernio API - Personal profiles, company pages, images, videos, documents, and multi-organization posting

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Reference

| Property | Value |
|----------|-------|
| Character limit | 3,000 |
| Images per post | 20 |
| Videos per post | 1 |
| Documents per post | 1 (PDF, PPT, PPTX, DOC, DOCX) |
| Image formats | JPEG, PNG, GIF |
| Image max size | 8 MB |
| Video formats | MP4, MOV, AVI |
| Video max size | 5 GB |
| Video max duration | 10 min (personal), 30 min (company page) |
| Post types | Text, Image, Multi-image, Video, Document |
| Scheduling | Yes |
| Inbox (Comments) | Yes (company pages only) |
| Inbox (DMs) | No (LinkedIn blocks third-party DM access) |
| Analytics | Yes |

## Before You Start

<Callout type="warn">
LinkedIn **actively suppresses posts containing external links**. Your post's organic reach can drop 40-50% if you include a URL in the caption. Best practice: put your link in the first comment using the `firstComment` field. Also: LinkedIn rejects duplicate content with a **422 error**. You cannot post the same text twice, even across different time periods.

Additional details:
- Works with **personal profiles** AND **company pages**
- Company pages: full analytics, 30-min video, comments API
- Personal profiles: limited analytics, 10-min video
- Cannot mix media types (images + videos or images + documents in the same post)
- First ~210 characters of your post are visible before the "see more" fold
</Callout>

## Quick Start

Post to LinkedIn in under 60 seconds:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Excited to share our latest update!\n\nWe have been working hard on this feature...',
  platforms: [
    { platform: 'linkedin', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to LinkedIn!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Excited to share our latest update!\n\nWe have been working hard on this feature...",
    platforms=[
        {"platform": "linkedin", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to LinkedIn! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Excited to share our latest update!\n\nWe have been working hard on this feature...",
    "platforms": [
      {"platform": "linkedin", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

### Text-Only Post

Text posts get the highest organic reach on LinkedIn. The first ~210 characters appear before the "see more" fold, so lead with your hook. Up to 3,000 characters total.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'I spent 3 years building the wrong product.\n\nHere is what I learned about validating ideas before writing code...',
  platforms: [
    { platform: 'linkedin', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to LinkedIn!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="I spent 3 years building the wrong product.\n\nHere is what I learned about validating ideas before writing code...",
    platforms=[
        {"platform": "linkedin", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to LinkedIn! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I spent 3 years building the wrong product.\n\nHere is what I learned about validating ideas before writing code...",
    "platforms": [
      {"platform": "linkedin", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Single Image Post

Attach one image to a post. Recommended size is 1200 x 627 px (landscape).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Our new office setup is looking great!',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/office.jpg' }
  ],
  platforms: [
    { platform: 'linkedin', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to LinkedIn!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Our new office setup is looking great!",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/office.jpg"}
    ],
    platforms=[
        {"platform": "linkedin", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to LinkedIn! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Our new office setup is looking great!",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/office.jpg"}
    ],
    "platforms": [
      {"platform": "linkedin", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Multi-Image Post

LinkedIn supports up to **20 images** in a single post. Cannot include videos or documents alongside images.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Highlights from our team retreat!',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/photo1.jpg' },
    { type: 'image', url: 'https://cdn.example.com/photo2.jpg' },
    { type: 'image', url: 'https://cdn.example.com/photo3.jpg' }
  ],
  platforms: [
    { platform: 'linkedin', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to LinkedIn!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Highlights from our team retreat!",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/photo1.jpg"},
        {"type": "image", "url": "https://cdn.example.com/photo2.jpg"},
        {"type": "image", "url": "https://cdn.example.com/photo3.jpg"}
    ],
    platforms=[
        {"platform": "linkedin", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to LinkedIn! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Highlights from our team retreat!",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/photo1.jpg"},
      {"type": "image", "url": "https://cdn.example.com/photo2.jpg"},
      {"type": "image", "url": "https://cdn.example.com/photo3.jpg"}
    ],
    "platforms": [
      {"platform": "linkedin", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Video Post

One video per post. Personal profiles support up to 10 minutes, company pages up to 30 minutes. MP4, MOV, and AVI formats.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Watch our latest product demo',
  mediaItems: [
    { type: 'video', url: 'https://cdn.example.com/demo.mp4' }
  ],
  platforms: [
    { platform: 'linkedin', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to LinkedIn!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Watch our latest product demo",
    media_items=[
        {"type": "video", "url": "https://cdn.example.com/demo.mp4"}
    ],
    platforms=[
        {"platform": "linkedin", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to LinkedIn! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Watch our latest product demo",
    "mediaItems": [
      {"type": "video", "url": "https://cdn.example.com/demo.mp4"}
    ],
    "platforms": [
      {"platform": "linkedin", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Document/Carousel Post

LinkedIn uniquely supports document uploads (PDF, PPT, PPTX, DOC, DOCX) that display as swipeable carousels. Max 100 MB, up to 300 pages. Cannot include images or videos alongside a document.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Download our 2024 Industry Report',
  mediaItems: [
    { type: 'document', url: 'https://cdn.example.com/report.pdf' }
  ],
  platforms: [
    { platform: 'linkedin', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to LinkedIn!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Download our 2024 Industry Report",
    media_items=[
        {"type": "document", "url": "https://cdn.example.com/report.pdf"}
    ],
    platforms=[
        {"platform": "linkedin", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to LinkedIn! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Download our 2024 Industry Report",
    "mediaItems": [
      {"type": "document", "url": "https://cdn.example.com/report.pdf"}
    ],
    "platforms": [
      {"platform": "linkedin", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

**Document tips:**
- First page is the cover/preview -- design it to grab attention
- Design for mobile viewing (large fonts, minimal text per slide)
- Ideal length for engagement: 10-15 pages
- Password-protected PDFs will not work

## Media Requirements

### Images

| Property | Requirement |
|----------|-------------|
| **Max images** | 20 per post |
| **Formats** | JPEG, PNG, GIF |
| **Max file size** | 8 MB per image |
| **Recommended** | 1200 x 627 px |
| **Min dimensions** | 552 x 276 px |
| **Max dimensions** | 8192 x 8192 px |

#### Aspect Ratios

| Type | Ratio | Dimensions | Use Case |
|------|-------|------------|----------|
| Landscape | 1.91:1 | 1200 x 627 px | Link shares, standard |
| Square | 1:1 | 1080 x 1080 px | Engagement |
| Portrait | 1:1.25 | 1080 x 1350 px | Mobile feed |

### Videos

| Property | Requirement |
|----------|-------------|
| **Max videos** | 1 per post |
| **Formats** | MP4, MOV, AVI |
| **Max file size** | 5 GB |
| **Max duration** | 10 min (personal), 30 min (company page) |
| **Min duration** | 3 seconds |
| **Resolution** | 256 x 144 px to 4096 x 2304 px |
| **Aspect ratio** | 1:2.4 to 2.4:1 |
| **Frame rate** | 10-60 fps |

#### Recommended Video Specs

| Property | Recommended |
|----------|-------------|
| Resolution | 1920 x 1080 px (1080p) |
| Aspect ratio | 16:9 (landscape) or 1:1 (square) |
| Frame rate | 30 fps |
| Codec | H.264 |
| Audio | AAC, 192 kbps |
| Bitrate | 10-30 Mbps |

### Documents

| Property | Requirement |
|----------|-------------|
| **Max documents** | 1 per post |
| **Formats** | PDF, PPT, PPTX, DOC, DOCX |
| **Max file size** | 100 MB |
| **Max pages** | 300 pages |

## Platform-Specific Fields

All fields go inside `platformSpecificData` on the LinkedIn platform entry.

| Field | Type | Description |
|-------|------|-------------|
| `documentTitle` | string | 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` | string | Post to a specific LinkedIn company page. Format: `urn:li:organization:123456`. Get available orgs via `GET /v1/accounts/{accountId}/linkedin-organizations`. If omitted, posts to default org or personal profile. |
| `firstComment` | string | Auto-posted as first comment after publish. Best practice: put external links here since LinkedIn suppresses link posts by 40-50%. |
| `disableLinkPreview` | boolean | Set to `true` to suppress the automatic URL preview card. Default: `false`. |
| `geoRestriction` | object | Restrict post visibility to specific countries. Organization pages only, requires 300+ targeted followers. See [Geo-Restriction](#geo-restriction) below. |

## Geo-Restriction

Restrict who can see your LinkedIn post by country. This is a hard visibility restriction: only followers in the specified countries see the post. **Organization pages only** (not personal profiles). LinkedIn requires the targeted audience to exceed 300 followers or the post will be rejected.

```json
{
  "platforms": [{
    "platform": "linkedin",
    "accountId": "YOUR_ORG_ACCOUNT_ID",
    "platformSpecificData": {
      "geoRestriction": {
        "countries": ["US", "ES"]
      }
    }
  }]
}
```

`geoRestriction.countries` accepts up to 25 uppercase ISO 3166-1 alpha-2 country codes. Zernio automatically resolves country codes to LinkedIn geo URNs. Currently supports 44 countries; unsupported country codes are silently skipped.

## LinkedIn Document Titles

LinkedIn requires a title for document (PDF/carousel) posts. Set `platformSpecificData.documentTitle` to control the title shown on LinkedIn.

> **Note:** If `documentTitle` is omitted, Zernio falls back to the media item `title`, then the `filename`.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Download our 2024 Industry Report",
    "mediaItems": [
      {"type": "document", "url": "https://cdn.example.com/report.pdf"}
    ],
    "platforms": [{
      "platform": "linkedin",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "documentTitle": "2024 Industry Report"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Download our 2024 Industry Report',
  mediaItems: [
    { type: 'document', url: 'https://cdn.example.com/report.pdf' }
  ],
  platforms: [{
    platform: 'linkedin',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      documentTitle: '2024 Industry Report'
    }
  }],
  publishNow: true
});
console.log('Posted to LinkedIn!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Download our 2024 Industry Report",
    media_items=[
        {"type": "document", "url": "https://cdn.example.com/report.pdf"}
    ],
    platforms=[{
        "platform": "linkedin",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "documentTitle": "2024 Industry Report"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Posted to LinkedIn! {post['_id']}")
```
</Tab>
</Tabs>

### Multi-Organization Posting

If your connected LinkedIn account manages multiple organizations (company pages), you can post to different organizations from the same account connection.

**List available organizations:**

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const organizations = await zernio.connect.getLinkedInOrganizations('YOUR_ACCOUNT_ID');
console.log('Available organizations:', organizations);
```
</Tab>
<Tab value="Python">
```python
organizations = client.connect.list_linked_in_organizations("YOUR_ACCOUNT_ID")
print("Available organizations:", organizations)
```
</Tab>
<Tab value="curl">
```bash
curl -X GET https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/linkedin-organizations \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

**Post to multiple organizations** using the same `accountId` with different `organizationUrn` values:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Exciting updates from our organization!',
  platforms: [
    {
      platform: 'linkedin',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: { organizationUrn: 'urn:li:organization:111111111' }
    },
    {
      platform: 'linkedin',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: { organizationUrn: 'urn:li:organization:222222222' }
    }
  ],
  publishNow: true
});
console.log('Posted to LinkedIn!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Exciting updates from our organization!",
    platforms=[
        {
            "platform": "linkedin",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {"organizationUrn": "urn:li:organization:111111111"}
        },
        {
            "platform": "linkedin",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {"organizationUrn": "urn:li:organization:222222222"}
        }
    ],
    publish_now=True
)
post = result.post
print(f"Posted to LinkedIn! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Exciting updates from our organization!",
    "platforms": [
      {
        "platform": "linkedin",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "organizationUrn": "urn:li:organization:111111111"
        }
      },
      {
        "platform": "linkedin",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "organizationUrn": "urn:li:organization:222222222"
        }
      }
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

The `organizationUrn` format is `urn:li:organization:` followed by the organization ID.

### First Comment

Put external links in the first comment to avoid LinkedIn's link suppression algorithm:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'We just published our guide to API design patterns.\n\nLink in the first comment.',
  platforms: [{
    platform: 'linkedin',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      firstComment: 'Read the full guide here: https://example.com/api-guide'
    }
  }],
  publishNow: true
});
console.log('Posted to LinkedIn!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="We just published our guide to API design patterns.\n\nLink in the first comment.",
    platforms=[{
        "platform": "linkedin",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "firstComment": "Read the full guide here: https://example.com/api-guide"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Posted to LinkedIn! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "We just published our guide to API design patterns.\n\nLink in the first comment.",
    "platforms": [{
      "platform": "linkedin",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "firstComment": "Read the full guide here: https://example.com/api-guide"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Disable Link Preview

When posting text with URLs and no media, LinkedIn auto-generates a link preview card. To suppress it:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Check out our latest blog post! https://example.com/blog/new-post',
  platforms: [{
    platform: 'linkedin',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      disableLinkPreview: true
    }
  }],
  publishNow: true
});
console.log('Posted to LinkedIn!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Check out our latest blog post! https://example.com/blog/new-post",
    platforms=[{
        "platform": "linkedin",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "disableLinkPreview": True
        }
    }],
    publish_now=True
)
post = result.post
print(f"Posted to LinkedIn! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out our latest blog post! https://example.com/blog/new-post",
    "platforms": [{
      "platform": "linkedin",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "disableLinkPreview": true
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Media URL Requirements

<Callout type="error">
**These do not work as media URLs:**
- **Google Drive** -- returns an HTML download page, not the file
- **Dropbox** -- returns an HTML preview page
- **OneDrive / SharePoint** -- returns HTML
- **iCloud** -- returns HTML

Test your URL in an incognito browser window. If you see a webpage instead of the raw image or video, it will not work.
</Callout>

Media URLs must be:
- Publicly accessible (no authentication required)
- Returning actual media bytes with the correct `Content-Type` header
- Not behind redirects that resolve to HTML pages
- Hosted on a fast, reliable CDN

**Supabase URLs:** Zernio auto-proxies Supabase storage URLs, so they work without additional configuration.

## Analytics

> **Included** — Analytics is bundled with every paid account on the [Usage plan](/pricing).

Available metrics via the [Analytics API](/analytics/get-analytics):

| Metric | Available |
|--------|-----------|
| Impressions | ✅ |
| Reach | ✅ |
| Likes | ✅ |
| Comments | ✅ |
| Shares | ✅ |
| Saves | ✅ (personal accounts only) |
| Sends | ✅ (personal accounts only, LinkedIn messaging) |
| Clicks | ✅ (organization accounts only) |
| Views | ✅ (video posts only) |

LinkedIn also provides dedicated analytics endpoints for deeper insights:

- **[Personal Aggregate Analytics](/analytics/get-linkedin-aggregate-analytics)** -- Totals or daily time series across a personal account's posts. Covers impressions, reach, reactions, comments, shares, saves, sends.
- **[Organization Aggregate Analytics](/analytics/get-linkedin-org-aggregate-analytics)** -- Impressions, clicks, reactions, engagement rate, follower gains (organic vs paid), and page-view metrics for organization pages. Requires the authenticated member to be an ADMINISTRATOR on the org and all three org scopes (r_organization_social + r_organization_followers + r_organization_admin).
- **[Post Analytics](/analytics/get-linkedin-post-analytics)** -- Per-post metrics by URN. Works for both personal and organization accounts (saves and sends are personal-only, org returns 0).
- **[Post Reactions](/analytics/get-linkedin-post-reactions)** -- Individual reactions with reactor profiles (organization accounts only).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const analytics = await zernio.analytics.getAnalytics({
  platform: 'linkedin',
  fromDate: '2024-01-01',
  toDate: '2024-01-31'
});
console.log(analytics.posts);
```
</Tab>
<Tab value="Python">
```python
analytics = client.analytics.get_analytics(
    platform="linkedin",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(analytics["posts"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics?platform=linkedin&fromDate=2024-01-01&toDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

## What You Can't Do

These features are not available through LinkedIn's API:

- Publish long-form articles (linkedin.com/article/new/)
- Create polls
- Create events
- Send InMail or DMs
- Create newsletters
- Add reactions to other posts
- Create hashtag-following or tag connections
- Mix media types (images + videos or images + documents in the same post)

## Common Errors

LinkedIn has a **9.5% failure rate** across Zernio's platform (8,082 failures out of 85,512 attempts). Here are the most frequent errors and how to fix them:

| Error | What it means | How to fix |
|-------|---------------|------------|
| "Content is a duplicate of urn:li:share:XXXX" (422) | Identical or very similar content was already posted | Modify the text meaningfully. LinkedIn's duplicate detection is strict -- even minor rephrasing may not be enough. |
| "Publishing failed during preflight checks" | Rate limiting or validation caught an issue before publishing | Space posts further apart. Check account health in the dashboard. |
| "Publishing failed due to max retries reached" | All 3 retry attempts failed | Temporary issue. Retry manually or check LinkedIn's status page. |
| Token expired | OAuth access token has expired or been revoked | Reconnect the LinkedIn account. Subscribe to the `account.disconnected` webhook to catch this proactively. |
| "Cannot mix media types" | Post contains images + videos or images + documents | Use only one media type per post. |
| Video processing failed | Codec, duration, or aspect ratio is out of spec | Ensure codec is H.264, duration is within limits (10 min personal / 30 min company), and aspect ratio is between 1:2.4 and 2.4:1. |
| Link preview showing wrong image | Open Graph meta tags on the URL are incorrect or missing | Update the `og:image` tag on your website. LinkedIn caches previews -- use the [LinkedIn Post Inspector](https://www.linkedin.com/post-inspector/) to refresh. |

## Inbox

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

LinkedIn supports comments only (no DMs via API).

### Comments

| Feature | Supported |
|---------|-----------|
| List comments on posts | ✅ |
| Reply to comments | ✅ |
| Delete comments | ✅ |
| Like comments | ❌ (API restricted) |

### Limitations

- **No DMs** - LinkedIn's messaging API is not available for third-party apps
- **Organization accounts only** - Comments require an organization (company page) account type
- **No comment likes** - Liking/reacting to comments via API is restricted. However, you can *read* post reactions via [`GET /v1/accounts/{accountId}/linkedin-post-reactions`](/analytics/get-linkedin-post-reactions) (organization accounts only).

See [Comments API Reference](/comments/list-inbox-comments) for endpoint details.

## Related Endpoints

- [Connect LinkedIn Account](/guides/connecting-accounts) - OAuth flow
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Image and video uploads
- [LinkedIn Organizations](/linkedin-mentions/get-linkedin-mentions) - List company pages
- [LinkedIn Mentions](/linkedin-mentions/get-linkedin-mentions) - Track brand mentions
- [LinkedIn Aggregate Analytics](/analytics/get-analytics) - Organization-level analytics
- [LinkedIn Post Analytics](/analytics/get-analytics) - Post-level performance metrics
- [LinkedIn Post Reactions](/analytics/get-linkedin-post-reactions) - Who reacted to a post (organization accounts)
- [Comments](/comments/list-inbox-comments) - Inbox API

---

# Pinterest Ads

Create Promoted Pin campaigns via Zernio API - No Pinterest developer approval required

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

<Callout type="info">
**Included with the [Usage plan](/pricing).** No Pinterest developer approval needed. Zernio handles the advanced scopes registration.
</Callout>

## What's Supported

| Feature | Status |
|---------|--------|
| Promoted Pin campaigns (Campaign > Ad Group > Pin) | Yes |
| Boost existing organic Pins | Yes |
| Demographic + interest targeting | Yes |
| Real-time analytics (spend, saves, closeups, clicks) | Yes |
| Pinterest Conversions API | Roadmap |
| Catalog / Shopping ads | Roadmap |

## Create a Promoted Pin Campaign

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.createStandaloneAd({ body: {
  accountId: "acc_pinterestads_123",
  adAccountId: "549123456789",
  name: "Spring home decor",
  goal: "traffic",
  budgetAmount: 30,
  budgetType: "daily",
  headline: "Freshen up your space",
  body: "Spring drops, limited time.",
  imageUrl: "https://cdn.example.com/spring-decor.jpg",
  linkUrl: "https://example.com/spring-decor",
  countries: ["US", "CA"],
  ageMin: 25,
  ageMax: 44,
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.create_standalone_ad(
    account_id="acc_pinterestads_123",
    ad_account_id="549123456789",
    name="Spring home decor",
    goal="traffic",
    budget_amount=30,
    budget_type="daily",
    headline="Freshen up your space",
    body="Spring drops, limited time.",
    image_url="https://cdn.example.com/spring-decor.jpg",
    link_url="https://example.com/spring-decor",
    countries=["US", "CA"],
    age_min=25,
    age_max=44,
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_pinterestads_123",
    "adAccountId": "549123456789",
    "name": "Spring home decor",
    "goal": "traffic",
    "budgetAmount": 30,
    "budgetType": "daily",
    "headline": "Freshen up your space",
    "body": "Spring drops, limited time.",
    "imageUrl": "https://cdn.example.com/spring-decor.jpg",
    "linkUrl": "https://example.com/spring-decor",
    "countries": ["US", "CA"],
    "ageMin": 25,
    "ageMax": 44
  }'
```
</Tab>
</Tabs>

<Callout type="info">
Pinterest creates a new Pin and promotes it in one call. Required: `headline` (max 100 chars), `body` (max 500 chars), `imageUrl`, `linkUrl`. `boardId` is optional, if omitted, a "Zernio Ads" board is auto-created. Valid `goal` values: `engagement`, `traffic`, `awareness`, `video_views`. To promote an *existing* Pin instead of creating one, use `/v1/ads/boost`.
</Callout>

## Boost an Existing Pin

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.boostPost({ body: {
  postId: "POST_ID",
  accountId: "ACCOUNT_ID",
  adAccountId: "549123456789",
  name: "Boost decor Pin",
  goal: "traffic",
  budget: { amount: 30, type: "daily" },
  schedule: { startDate: "2026-04-20", endDate: "2026-05-20" },
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.boost_post(
    post_id="POST_ID",
    account_id="ACCOUNT_ID",
    ad_account_id="549123456789",
    name="Boost decor Pin",
    goal="traffic",
    budget={"amount": 30, "type": "daily"},
    schedule={"startDate": "2026-04-20", "endDate": "2026-05-20"},
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/boost" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postId": "POST_ID",
    "accountId": "ACCOUNT_ID",
    "adAccountId": "549123456789",
    "name": "Boost decor Pin",
    "goal": "traffic",
    "budget": { "amount": 30, "type": "daily" },
    "schedule": { "startDate": "2026-04-20", "endDate": "2026-05-20" }
  }'
```
</Tab>
</Tabs>

## Pinterest-Native Metrics

Pinterest surfaces **saves** and **closeups** alongside standard click/spend metrics. These are included in `/v1/ads/{id}/analytics`.

## Media Requirements

| Type | Format | Max Size | Notes |
|------|--------|----------|-------|
| Standard Pin | JPEG, PNG | 20 MB | 1000x1500 (2:3) recommended |
| Video Pin | MP4, MOV, M4V | 2 GB | 4s-15min, 9:16 or 1:1 |

---

# Pinterest

Schedule and automate Pinterest Pins with Zernio API - Image pins, video pins, boards, destination links, and cover images

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Reference

| Property | Value |
|----------|-------|
| Title limit | 100 characters |
| Description limit | 500 characters |
| Images per pin | 1 |
| Videos per pin | 1 |
| Image formats | JPEG, PNG, WebP, GIF |
| Image max size | 32 MB |
| Video formats | MP4, MOV |
| Video max size | 2 GB |
| Video duration | 4 sec - 15 min |
| Scheduling | Yes |
| Inbox | No (Pinterest has no API-accessible inbox) |
| Analytics | No (via Zernio) |

## Before You Start

<Callout type="warn">
Pinterest is a **search engine**, not a social feed. Pins are discovered through search and browse, not by followers. This means SEO (title, description, board name) matters more than posting time. Pins have a 3-6 month lifespan, unlike hours on other platforms. Also: `boardId` is effectively required -- always provide it.

Additional requirements:
- A Pinterest Board is required to pin to
- No text-only pins (media is required)
- No carousels or multi-image posts (1 image or 1 video per pin)
- The `link` field is critical for driving traffic
</Callout>

## Quick Start

Create a Pin on Pinterest:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: '10 Tips for Better Photography',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/pin-image.jpg' }
  ],
  platforms: [{
    platform: 'pinterest',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      title: '10 Tips for Better Photography',
      boardId: 'YOUR_BOARD_ID',
      link: 'https://myblog.com/photography-tips'
    }
  }],
  publishNow: true
});
console.log('Pin created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="10 Tips for Better Photography",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/pin-image.jpg"}
    ],
    platforms=[{
        "platform": "pinterest",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "title": "10 Tips for Better Photography",
            "boardId": "YOUR_BOARD_ID",
            "link": "https://myblog.com/photography-tips"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Pin created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "10 Tips for Better Photography",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/pin-image.jpg"}
    ],
    "platforms": [{
      "platform": "pinterest",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "title": "10 Tips for Better Photography",
        "boardId": "YOUR_BOARD_ID",
        "link": "https://myblog.com/photography-tips"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

### Image Pin

A single image pinned to a board. The most common pin type. Use 2:3 aspect ratio (1000x1500 px) for optimal display in the Pinterest feed.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Modern kitchen renovation ideas for small spaces',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/kitchen-ideas.jpg' }
  ],
  platforms: [{
    platform: 'pinterest',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      title: 'Modern Kitchen Renovation Ideas',
      boardId: 'YOUR_BOARD_ID',
      link: 'https://myblog.com/kitchen-renovation'
    }
  }],
  publishNow: true
});
console.log('Image pin created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Modern kitchen renovation ideas for small spaces",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/kitchen-ideas.jpg"}
    ],
    platforms=[{
        "platform": "pinterest",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "title": "Modern Kitchen Renovation Ideas",
            "boardId": "YOUR_BOARD_ID",
            "link": "https://myblog.com/kitchen-renovation"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Image pin created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Modern kitchen renovation ideas for small spaces",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/kitchen-ideas.jpg"}
    ],
    "platforms": [{
      "platform": "pinterest",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "title": "Modern Kitchen Renovation Ideas",
        "boardId": "YOUR_BOARD_ID",
        "link": "https://myblog.com/kitchen-renovation"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Video Pin

A single video pinned to a board. You can optionally set a custom cover image or auto-extract a frame at a specific time.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Quick 5-minute breakfast recipe',
  mediaItems: [
    { type: 'video', url: 'https://cdn.example.com/recipe.mp4' }
  ],
  platforms: [{
    platform: 'pinterest',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      title: '5-Minute Breakfast Recipe',
      boardId: 'YOUR_BOARD_ID',
      link: 'https://myrecipes.com/quick-breakfast',
      coverImageUrl: 'https://cdn.example.com/recipe-cover.jpg'
    }
  }],
  publishNow: true
});
console.log('Video pin created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Quick 5-minute breakfast recipe",
    media_items=[
        {"type": "video", "url": "https://cdn.example.com/recipe.mp4"}
    ],
    platforms=[{
        "platform": "pinterest",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "title": "5-Minute Breakfast Recipe",
            "boardId": "YOUR_BOARD_ID",
            "link": "https://myrecipes.com/quick-breakfast",
            "coverImageUrl": "https://cdn.example.com/recipe-cover.jpg"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Video pin created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Quick 5-minute breakfast recipe",
    "mediaItems": [
      {"type": "video", "url": "https://cdn.example.com/recipe.mp4"}
    ],
    "platforms": [{
      "platform": "pinterest",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "title": "5-Minute Breakfast Recipe",
        "boardId": "YOUR_BOARD_ID",
        "link": "https://myrecipes.com/quick-breakfast",
        "coverImageUrl": "https://cdn.example.com/recipe-cover.jpg"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Media Requirements

### Images

| Property | Requirement |
|----------|-------------|
| **Max images** | 1 per pin |
| **Formats** | JPEG, PNG, WebP, GIF |
| **Max file size** | 32 MB |
| **Recommended** | 1000 x 1500 px (2:3) |
| **Min dimensions** | 100 x 100 px |

#### Aspect Ratios

| Ratio | Dimensions | Use Case |
|-------|------------|----------|
| 2:3 | 1000 x 1500 px | **Optimal** - Standard Pin |
| 1:1 | 1000 x 1000 px | Square Pin |
| 1:2.1 | 1000 x 2100 px | Long Pin (max height) |

> **Best practice:** Use 2:3 aspect ratio for optimal display in the Pinterest feed.

#### GIFs

Pinterest supports animated GIFs. They auto-play in the feed and are treated as images (not video). Max file size is 32 MB, but keeping under 10 MB is recommended for fast loading.

### Videos

| Property | Requirement |
|----------|-------------|
| **Max videos** | 1 per pin |
| **Formats** | MP4, MOV |
| **Max file size** | 2 GB |
| **Duration** | 4 seconds - 15 minutes |
| **Aspect ratio** | 2:3, 1:1, or 9:16 |
| **Resolution** | 1080p recommended |
| **Frame rate** | 25+ fps |

#### Video Specs

| Property | Minimum | Recommended |
|----------|---------|-------------|
| Resolution | 240p | 1080p |
| Bitrate | - | 10 Mbps |
| Audio | - | AAC, 128 kbps |

## Platform-Specific Fields

All fields go inside `platformSpecificData` on the Pinterest platform entry.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `boardId` | string | -- | **Effectively required.** The board to pin to. Get board IDs via `GET /v1/accounts/{accountId}/pinterest-boards`. Aliases: `board_id`, `board`. |
| `title` | string (max 100 chars) | First line of content | Pin title. Searchable by Pinterest users. |
| `link` | string (URL) | -- | Destination link when users click the pin. Must be valid HTTPS. No URL shorteners. **Most important field for driving traffic.** Aliases: `url`. |
| `coverImageUrl` | string (URL) | -- | Custom cover image for video pins. Aliases: `cover_image_url`, `thumbnailUrl`, `thumbnail_url`. |
| `coverImageKeyFrameTime` | number (seconds) | `0` | Auto-extract a video frame at N seconds to use as cover. Ignored if `coverImageUrl` is set. |

## Media URL Requirements

<Callout type="error">
**These do not work as media URLs:**
- **Google Drive** -- returns an HTML download page, not the file
- **Dropbox** -- returns an HTML preview page
- **OneDrive / SharePoint** -- returns HTML
- **iCloud** -- returns HTML

Test your URL in an incognito browser window. If you see a webpage instead of the raw image or video, it will not work.
</Callout>

Media URLs must be:
- Publicly accessible (no authentication required)
- Returning actual media bytes with the correct `Content-Type` header
- Not behind redirects that resolve to HTML pages
- Hosted on a fast, reliable CDN

## Analytics

> **Included** — Analytics is bundled with every paid account on the [Usage plan](/pricing).

Available metrics via the [Analytics API](/analytics/get-analytics):

| Metric | Available |
|--------|-----------|
| Impressions | ✅ |
| Saves | ✅ |
| Clicks | ✅ |

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const analytics = await zernio.analytics.getAnalytics({
  platform: 'pinterest',
  fromDate: '2024-01-01',
  toDate: '2024-01-31'
});
console.log(analytics.posts);
```
</Tab>
<Tab value="Python">
```python
analytics = client.analytics.get_analytics(
    platform="pinterest",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(analytics["posts"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics?platform=pinterest&fromDate=2024-01-01&toDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

## What You Can't Do

These features are not available through Pinterest's API:

- Create Idea Pins (multi-page stories)
- Claim website
- Create Rich Pins (requires meta tags on your website)
- Access Pinterest Analytics (via Zernio)
- Create Shopping catalogs
- Edit or delete pins after creation (via Zernio)
- Create multi-image posts or carousels

## Common Errors

Pinterest has a **21.1% failure rate** across Zernio's platform (7,928 failures out of 37,646 attempts). Here are the most frequent errors and how to fix them:

| Error | Meaning | Fix |
|-------|---------|-----|
| "Invalid URL or request data." | Pinterest could not process the URL or request data | Verify media URL is publicly accessible, returns actual media bytes, and uses HTTPS. |
| "Unable to reach the URL. Please check the URL is correct and try again." | Pinterest's servers cannot fetch your media | Test the URL in an incognito browser. Ensure no authentication is required and there are no redirects to HTML pages. |
| "Pinterest rate limit reached." | Too many API calls in a short window | Space out pins. Avoid bursts of 10+ pins at once. |
| "Pinterest requires a boardId. Provide platformSpecificData.boardId." | No board was specified in the request | Always provide `boardId`. List available boards with `GET /v1/accounts/{accountId}/pinterest-boards`. |

## Inbox

Pinterest does not have inbox features available via API.

- **No DMs** -- Pinterest's messaging API is not available for third-party apps
- **No comments** -- Pin comments are not accessible via API
- **No reviews** -- Pinterest does not have a reviews system

## Related Endpoints

- [Connect Pinterest Account](/guides/connecting-accounts) - OAuth flow
- [Create Post](/posts/create-post) - Pin creation and scheduling
- [Upload Media](/guides/media-uploads) - Image and video uploads
- [Pinterest Boards](/connect/get-pinterest-boards) - List boards for an account

---

# Reddit

Schedule and automate Reddit posts with Zernio API - Text posts, link posts, image posts, subreddit targeting, flair selection, and gallery posts

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Reference

| Property | Value |
|----------|-------|
| Title limit | 300 characters (required, cannot edit after) |
| Body text | 40,000 characters |
| Images per post | 1 (single), multiple (gallery) |
| Videos per post | 1 |
| Image formats | JPEG, PNG, GIF |
| Image max size | 20 MB |
| Post types | Text, Link, Image, Gallery, Native Video |
| Scheduling | Yes |
| Inbox (DMs) | Yes (text only) |
| Inbox (Comments) | Yes |
| Analytics | No |

## Native Video Posts

By default, Zernio uploads the video to Reddit's CDN and submits it as a native video, so it renders inside Reddit's embedded player. The alternative is a link post (`nativeVideo: false`), where the video URL appears as an external link out to wherever you host the file.

Reddit transcodes native videos server-side (1080p/30fps cap). If a subreddit blocks video posts, the submission falls back to a link post automatically.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Demo: native video upload',
  mediaItems: [
    { type: 'video', url: 'https://example.com/demo.mp4' }
  ],
  platforms: [
    {
      platform: 'reddit',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: {
        subreddit: 'videos',
        // nativeVideo: false,  // uncomment to post as a link instead of uploading to Reddit
      }
    }
  ],
  publishNow: true
});
console.log('Native video post created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Demo: native video upload",
    media_items=[
        {"type": "video", "url": "https://example.com/demo.mp4"}
    ],
    platforms=[
        {
            "platform": "reddit",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {
                "subreddit": "videos",
                # "nativeVideo": False,  # uncomment to post as a link instead of uploading to Reddit
            }
        }
    ],
    publish_now=True
)
post = result.post
print(f"Native video post created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
# Default: native video upload (embedded Reddit player).
# To post as a link instead, add  "nativeVideo": false  inside platformSpecificData.
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Demo: native video upload",
    "mediaItems": [
      {"type": "video", "url": "https://example.com/demo.mp4"}
    ],
    "platforms": [
      {
        "platform": "reddit",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "subreddit": "videos"
        }
      }
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Custom poster image

By default Zernio auto-extracts the video's first frame as the poster. Pass `videoPosterUrl` to override it:

```json
"platformSpecificData": {
  "subreddit": "videos",
  "videoPosterUrl": "https://example.com/poster.jpg"
}
```

### Silent looping clips (videogif)

Set `videogif: true` to submit as a silent looping clip. Still uploaded as native video, `videogif` only changes the Reddit kind.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
await zernio.posts.createPost({
  content: 'Short looping clip (videogif)',
  mediaItems: [
    { type: 'video', url: 'https://example.com/loop.mp4' }
  ],
  platforms: [
    {
      platform: 'reddit',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: {
        subreddit: 'gifs',
        videogif: true
      }
    }
  ],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
client.posts.create_post(
    content="Short looping clip (videogif)",
    media_items=[
        {"type": "video", "url": "https://example.com/loop.mp4"}
    ],
    platforms=[
        {
            "platform": "reddit",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {
                "subreddit": "gifs",
                "videogif": True
            }
        }
    ],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Short looping clip (videogif)",
    "mediaItems": [
      {"type": "video", "url": "https://example.com/loop.mp4"}
    ],
    "platforms": [
      {
        "platform": "reddit",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "subreddit": "gifs",
          "videogif": true
        }
      }
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Before You Start

<Callout type="warn">
Reddit is fundamentally different from every other platform. Each subreddit (community) is independently moderated with its **own rules**. There is no universal set of rules. What works in one subreddit will get you banned in another.

Before posting to any subreddit via API, you **must**:
1. Check if the subreddit allows your post type (text, link, or image)
2. Check if flair is required (many subreddits auto-remove posts without flair)
3. Check if the subreddit allows third-party/automated posting
4. Check karma and account age requirements

More than half of all Reddit posts via Zernio fail. Almost every failure is preventable by reading the target subreddit's rules first.

Additional warnings:
- **Title is permanent** -- Reddit titles cannot be edited after posting
- **New accounts are restricted** -- Low karma and new account age will block most subreddits
- **Video rules vary by subreddit** -- Some subreddits block video posts; in those cases Zernio falls back to a link post automatically
- **Each subreddit has unique, independent rules** -- Always check before posting
</Callout>

## Quick Start

Post to Reddit in under 60 seconds:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: "What is your favorite programming language and why?\n\nI have been using Python for years but considering learning Rust.",
  platforms: [
    {
      platform: 'reddit',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: {
        subreddit: 'learnprogramming'
      }
    }
  ],
  publishNow: true
});
console.log('Posted to Reddit!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="What is your favorite programming language and why?\n\nI have been using Python for years but considering learning Rust.",
    platforms=[
        {
            "platform": "reddit",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {
                "subreddit": "learnprogramming"
            }
        }
    ],
    publish_now=True
)
post = result.post
print(f"Posted to Reddit! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What is your favorite programming language and why?\n\nI have been using Python for years but considering learning Rust.",
    "platforms": [
      {
        "platform": "reddit",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "subreddit": "learnprogramming"
        }
      }
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

### Text Post (Self Post)

A text post with a title and optional body. This is the default post type when no media or URL is provided. The first line of `content` becomes the title, and the rest becomes the body. Reddit Markdown is supported in the body.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: "Tips for learning a new programming language\n\nHere are some things that worked for me:\n\n1. Start with the official tutorial\n2. Build a small project immediately\n3. Read other people's code\n4. Contribute to open source",
  platforms: [
    {
      platform: 'reddit',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: {
        subreddit: 'learnprogramming'
      }
    }
  ],
  publishNow: true
});
console.log('Text post created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Tips for learning a new programming language\n\nHere are some things that worked for me:\n\n1. Start with the official tutorial\n2. Build a small project immediately\n3. Read other people's code\n4. Contribute to open source",
    platforms=[
        {
            "platform": "reddit",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {
                "subreddit": "learnprogramming"
            }
        }
    ],
    publish_now=True
)
post = result.post
print(f"Text post created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Tips for learning a new programming language\n\nHere are some things that worked for me:\n\n1. Start with the official tutorial\n2. Build a small project immediately\n3. Read other people'\''s code\n4. Contribute to open source",
    "platforms": [
      {
        "platform": "reddit",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "subreddit": "learnprogramming"
        }
      }
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Link Post

Share an external URL. When `platformSpecificData.url` is provided, Reddit creates a link post instead of a text post. The `content` becomes the post title.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Interesting article about modern API design patterns',
  platforms: [
    {
      platform: 'reddit',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: {
        subreddit: 'programming',
        url: 'https://example.com/api-design-article'
      }
    }
  ],
  publishNow: true
});
console.log('Link post created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Interesting article about modern API design patterns",
    platforms=[
        {
            "platform": "reddit",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {
                "subreddit": "programming",
                "url": "https://example.com/api-design-article"
            }
        }
    ],
    publish_now=True
)
post = result.post
print(f"Link post created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Interesting article about modern API design patterns",
    "platforms": [
      {
        "platform": "reddit",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "subreddit": "programming",
          "url": "https://example.com/api-design-article"
        }
      }
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Image Post

Attach a single image to a post. The `content` becomes the post title.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Check out this view from my hike!',
  mediaItems: [
    { type: 'image', url: 'https://example.com/hiking-photo.jpg' }
  ],
  platforms: [
    {
      platform: 'reddit',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: {
        subreddit: 'hiking'
      }
    }
  ],
  publishNow: true
});
console.log('Image post created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Check out this view from my hike!",
    media_items=[
        {"type": "image", "url": "https://example.com/hiking-photo.jpg"}
    ],
    platforms=[
        {
            "platform": "reddit",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {
                "subreddit": "hiking"
            }
        }
    ],
    publish_now=True
)
post = result.post
print(f"Image post created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out this view from my hike!",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/hiking-photo.jpg"}
    ],
    "platforms": [
      {
        "platform": "reddit",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "subreddit": "hiking"
        }
      }
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Gallery Post

Attach multiple images to create a gallery post. Not all subreddits support galleries.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'My weekend woodworking project - start to finish',
  mediaItems: [
    { type: 'image', url: 'https://example.com/step1.jpg' },
    { type: 'image', url: 'https://example.com/step2.jpg' },
    { type: 'image', url: 'https://example.com/step3.jpg' },
    { type: 'image', url: 'https://example.com/finished.jpg' }
  ],
  platforms: [
    {
      platform: 'reddit',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: {
        subreddit: 'woodworking'
      }
    }
  ],
  publishNow: true
});
console.log('Gallery post created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="My weekend woodworking project - start to finish",
    media_items=[
        {"type": "image", "url": "https://example.com/step1.jpg"},
        {"type": "image", "url": "https://example.com/step2.jpg"},
        {"type": "image", "url": "https://example.com/step3.jpg"},
        {"type": "image", "url": "https://example.com/finished.jpg"}
    ],
    platforms=[
        {
            "platform": "reddit",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {
                "subreddit": "woodworking"
            }
        }
    ],
    publish_now=True
)
post = result.post
print(f"Gallery post created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "My weekend woodworking project - start to finish",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/step1.jpg"},
      {"type": "image", "url": "https://example.com/step2.jpg"},
      {"type": "image", "url": "https://example.com/step3.jpg"},
      {"type": "image", "url": "https://example.com/finished.jpg"}
    ],
    "platforms": [
      {
        "platform": "reddit",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "subreddit": "woodworking"
        }
      }
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Media Requirements

### Images

| Property | Requirement |
|----------|-------------|
| **Max images** | 1 per post (single), multiple (gallery) |
| **Formats** | JPEG, PNG, GIF |
| **Max file size** | 20 MB |
| **Recommended** | 1200 x 628 px |

### Aspect Ratios

Reddit is flexible with aspect ratios:

| Ratio | Use Case |
|-------|----------|
| 16:9 | Standard landscape |
| 4:3 | Classic format |
| 1:1 | Square images |
| 9:16 | Mobile screenshots |

### GIFs

- Static display until clicked
- Max 20 MB
- May convert to video format internally
- Keep under 10 MB for better performance

## Platform-Specific Fields

All fields go inside `platformSpecificData` on the Reddit platform entry.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `subreddit` | string | Effectively yes | Target subreddit (without `r/` prefix). Falls back to account default if omitted. Aliases: `subredditName`, `sr` |
| `title` | string | Yes (by Reddit) | Post title, max 300 characters. Cannot be edited after posting. If omitted, first line of `content` is used. |
| `url` | string | No | External URL for link posts. If provided, creates a link post instead of a text post. |
| `nativeVideo` | boolean | No | Defaults to `true` for video media items (uploads to Reddit's CDN, renders as embedded player). Set `false` to post as a plain link instead. |
| `videogif` | boolean | No | When `true`, submit the native video as a silent looping videogif. |
| `videoPosterUrl` | string | No | Custom poster/thumbnail. If omitted, Zernio auto-extracts the video's first frame. |
| `flairId` | string | Varies | Reddit flair ID. Many subreddits require this. Get flairs via `GET /v1/accounts/{accountId}/reddit-flairs?subreddit=NAME`. Aliases: `redditFlairId` |
| `flairText` | string | No | Custom flair text for subreddits that allow free-text flair. Ignored when `flairId` is provided (`flairId` wins). |
| `nsfw` | boolean | No | Mark the post as NSFW (Not Safe For Work / over 18). |
| `spoiler` | boolean | No | Mark the post as a spoiler (subreddit must have spoiler tagging enabled). |
| `sendreplies` | boolean | No | Whether to receive inbox replies for comments on this post. Set to `false` to opt out. |
| `forceSelf` | boolean | No | Force text/self post even when media is attached. |

### Subreddit Selection

Posts are submitted to the subreddit configured on the connected Reddit account by default. To post to a specific subreddit, set `platformSpecificData.subreddit` (without the `r/` prefix).

### Post Flairs

Some subreddits require a post flair. First, list available flairs for a subreddit:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { flairs } = await zernio.connect.getRedditFlairs('YOUR_ACCOUNT_ID', {
  subreddit: 'socialmedia'
});
console.log(flairs);
```
</Tab>
<Tab value="Python">
```python
result = client.connect.get_reddit_flairs(
    "YOUR_ACCOUNT_ID",
    subreddit="socialmedia"
)
print(result.flairs)
```
</Tab>
<Tab value="curl">
```bash
curl -X GET "https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/reddit-flairs?subreddit=socialmedia" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Then, create a post with `flairId`:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'What is your favorite programming language and why?',
  platforms: [
    {
      platform: 'reddit',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: {
        subreddit: 'socialmedia',
        flairId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
      }
    }
  ],
  publishNow: true
});
console.log('Posted to Reddit!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="What is your favorite programming language and why?",
    platforms=[
        {
            "platform": "reddit",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {
                "subreddit": "socialmedia",
                "flairId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            }
        }
    ],
    publish_now=True
)
post = result.post
print(f"Posted to Reddit! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What is your favorite programming language and why?",
    "platforms": [
      {
        "platform": "reddit",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "subreddit": "socialmedia",
          "flairId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        }
      }
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

If a subreddit requires a flair and you do not provide `flairId`, Zernio will attempt to use the first available flair as a fallback.

## Formatting

Reddit supports Markdown in text post bodies:

```markdown
# Heading
## Subheading
**Bold text**
*Italic text*
~~Strikethrough~~
- Bullet points
1. Numbered lists
[Link text](https://example.com)
> Block quotes
`inline code`
```

## Auto-Retry Behavior

Zernio automatically retries failed Reddit posts in certain situations:

- **Link post in text-only subreddit** -- If a link post fails with a `NO_LINKS` error (subreddit only allows text posts), Zernio auto-retries as a text/self post with the URL included in the body.
- **Missing required flair** -- If a subreddit requires flair but none was provided, Zernio tries to use the first available flair automatically.

## Analytics

> **Included** — Analytics is bundled with every paid account on the [Usage plan](/pricing).

Available metrics via the [Analytics API](/analytics/get-analytics):

| Metric | Available |
|--------|-----------|
| Likes (upvotes) | ✅ |
| Comments | ✅ |

Reddit does not provide impressions, reach, shares, clicks, or view counts through its API.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const analytics = await zernio.analytics.getAnalytics({
  platform: 'reddit',
  fromDate: '2024-01-01',
  toDate: '2024-01-31'
});
console.log(analytics.posts);
```
</Tab>
<Tab value="Python">
```python
analytics = client.analytics.get_analytics(
    platform="reddit",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(analytics["posts"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics?platform=reddit&fromDate=2024-01-01&toDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

## What You Can't Do

These features are not available through Reddit's API:

- Create polls
- Crosspost to other subreddits
- Edit post title after creation
- Add post to collections
- Create live chat threads
- Award/give gold to posts
- See upvote/downvote counts (score only)

## Common Errors

Reddit has a **53.9% failure rate** across Zernio's platform (4,785 failures out of 8,877 attempts). Here are the most frequent errors and how to fix them:

| Error | What it means | How to fix |
|-------|---------------|------------|
| "SUBREDDIT_NOTALLOWED: only trusted members" | Subreddit restricts who can post | Join the community, build karma, or choose a different subreddit |
| "NO_SELFS: doesn't allow text posts" | Subreddit only accepts link or image posts | Provide a URL via `platformSpecificData.url` or attach an image |
| "SUBMIT_VALIDATION_FLAIR_REQUIRED" | Subreddit requires flair on all posts | Fetch flairs with `GET /v1/accounts/{accountId}/reddit-flairs?subreddit=NAME` and provide the correct `flairId` |
| "SUBREDDIT_NOEXIST" | Typo in subreddit name or subreddit is private | Check spelling, do not include the `r/` prefix |
| "AI-generated content not allowed" | Subreddit bans AI-generated content | Write original content or choose a different subreddit |
| "Reddit removed the post" | Moderators or AutoMod removed the post after submission | Check subreddit rules, ensure content complies |
| "Reddit requires a subreddit" | No subreddit was specified and no default is set | Always provide `platformSpecificData.subreddit` |
| "Rate limited" | Reddit's rate limit was hit | Space posts further apart. New accounts are limited to around 10 posts per day. |

## Inbox

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

Reddit supports DMs (private messages) and comments.

### Direct Messages

| Feature | Supported |
|---------|-----------|
| List conversations | ✅ |
| Fetch messages | ✅ |
| Send text messages | ✅ |
| Send attachments | ❌ (API limitation) |
| Archive/unarchive | ✅ |

### Comments

| Feature | Supported |
|---------|-----------|
| List comments on posts | ✅ |
| Reply to comments | ✅ |
| Delete comments | ✅ |
| Upvote/downvote | ✅ |
| Remove vote | ✅ |

### Limitations

- **No DM attachments** - Reddit's API does not support media in private messages
- **Subreddit required** - When replying to comments, you must provide the `subreddit` parameter

See [Messages](/messages/list-inbox-conversations) and [Comments](/comments/list-inbox-comments) API Reference for endpoint details.

## Related Endpoints

- [Connect Reddit Account](/guides/connecting-accounts) - OAuth flow
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Image uploads
- [Reddit Search](/reddit-search/search-reddit) - Search Reddit content
- [Reddit Subreddits](/connect/get-reddit-subreddits) - List subscribed subreddits
- [Reddit Flairs](/connect/get-reddit-flairs) - Get available flairs for a subreddit
- [Messages](/messages/list-inbox-conversations) and [Comments](/comments/list-inbox-comments) - Inbox API

---

# Snapchat

Schedule and automate Snapchat posts with Zernio API - Stories, Saved Stories, Spotlight content, and Public Profile management

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Reference

| Property | Value |
|----------|-------|
| Title limit | 45 chars (Saved Stories) |
| Description limit | 160 chars (Spotlight, including hashtags) |
| Media per post | 1 (single image or video only) |
| Image formats | JPEG, PNG |
| Image max size | 20 MB |
| Video format | MP4 only |
| Video max size | 500 MB |
| Video duration | 5-60 seconds |
| Post types | Story, Saved Story, Spotlight |
| Scheduling | Yes |
| Inbox | No |
| Analytics | Yes (views, viewers, screenshots, shares) |

## Before You Start

<Callout type="warn">
Snapchat requires a Public Profile to publish content. Regular accounts cannot use the API. Also: Snapchat only supports 1 media item per post -- no carousels, no albums. This is the most restrictive platform for content format.

Additional requirements:
- Public Profile required (Person, Business, or Official)
- Single media item only (most restrictive platform)
- No text-only posts
- 9:16 vertical orientation practically required
- Media is encrypted (AES-256-CBC) before upload (handled by Zernio)
</Callout>

## Quick Start

Post to Snapchat in under 60 seconds:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  mediaItems: [
    { type: 'video', url: 'https://example.com/video.mp4' }
  ],
  platforms: [{
    platform: 'snapchat',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      contentType: 'story'
    }
  }],
  publishNow: true
});
console.log('Posted to Snapchat!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    media_items=[
        {"type": "video", "url": "https://example.com/video.mp4"}
    ],
    platforms=[{
        "platform": "snapchat",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "contentType": "story"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Posted to Snapchat! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaItems": [
      {"type": "video", "url": "https://example.com/video.mp4"}
    ],
    "platforms": [{
      "platform": "snapchat",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "contentType": "story"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

Snapchat supports three content types through the Public Profile API:

| Type | Description | Duration | Text Support |
|------|-------------|----------|--------------|
| `story` | Ephemeral snap visible for 24 hours | Temporary | No caption |
| `saved_story` | Permanent story on Public Profile | Permanent | Title (max 45 chars) |
| `spotlight` | Video in Snapchat's entertainment feed | Permanent | Description (max 160 chars, hashtags supported) |

### Story Posts

Stories are ephemeral content visible for 24 hours. No caption or text is supported.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  mediaItems: [
    { type: 'image', url: 'https://example.com/image.jpg' }
  ],
  platforms: [{
    platform: 'snapchat',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      contentType: 'story'
    }
  }],
  publishNow: true
});
console.log('Posted to Snapchat!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    media_items=[
        {"type": "image", "url": "https://example.com/image.jpg"}
    ],
    platforms=[{
        "platform": "snapchat",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "contentType": "story"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Posted to Snapchat! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaItems": [
      {"type": "image", "url": "https://example.com/image.jpg"}
    ],
    "platforms": [{
      "platform": "snapchat",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "contentType": "story"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Saved Story Posts

Saved Stories are permanent content displayed on your Public Profile. The post `content` is used as the title (max 45 characters).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Behind the scenes look!',
  mediaItems: [
    { type: 'video', url: 'https://example.com/video.mp4' }
  ],
  platforms: [{
    platform: 'snapchat',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      contentType: 'saved_story'
    }
  }],
  publishNow: true
});
console.log('Posted to Snapchat!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Behind the scenes look!",
    media_items=[
        {"type": "video", "url": "https://example.com/video.mp4"}
    ],
    platforms=[{
        "platform": "snapchat",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "contentType": "saved_story"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Posted to Snapchat! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Behind the scenes look!",
    "mediaItems": [
      {"type": "video", "url": "https://example.com/video.mp4"}
    ],
    "platforms": [{
      "platform": "snapchat",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "contentType": "saved_story"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Spotlight Posts

Spotlight is Snapchat's TikTok-like entertainment feed. Only video content is supported. The post `content` is used as the description (max 160 characters) and can include hashtags.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Check out this amazing sunset! #sunset #nature #viral',
  mediaItems: [
    { type: 'video', url: 'https://example.com/sunset-video.mp4' }
  ],
  platforms: [{
    platform: 'snapchat',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      contentType: 'spotlight'
    }
  }],
  publishNow: true
});
console.log('Posted to Snapchat!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Check out this amazing sunset! #sunset #nature #viral",
    media_items=[
        {"type": "video", "url": "https://example.com/sunset-video.mp4"}
    ],
    platforms=[{
        "platform": "snapchat",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "contentType": "spotlight"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Posted to Snapchat! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out this amazing sunset! #sunset #nature #viral",
    "mediaItems": [
      {"type": "video", "url": "https://example.com/sunset-video.mp4"}
    ],
    "platforms": [{
      "platform": "snapchat",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "contentType": "spotlight"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Media Requirements

Media is required for all Snapchat posts. Text-only posts are not supported.

### Images

| Property | Requirement |
|----------|-------------|
| **Formats** | JPEG, PNG |
| **Max File Size** | 20 MB |
| **Recommended Dimensions** | 1080 x 1920 px |
| **Aspect Ratio** | 9:16 (portrait) |

### Videos

| Property | Requirement |
|----------|-------------|
| **Format** | MP4 |
| **Max File Size** | 500 MB |
| **Duration** | 5-60 seconds |
| **Min Resolution** | 540 x 960 px |
| **Recommended Dimensions** | 1080 x 1920 px |
| **Aspect Ratio** | 9:16 (portrait) |

Media is automatically encrypted using AES-256-CBC before upload to Snapchat. This is handled entirely by Zernio.

## Platform-Specific Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `contentType` | string | `"story"` | Content type: `"story"`, `"saved_story"`, or `"spotlight"` |

## Connection

Snapchat uses OAuth for authentication and requires selecting a Public Profile to publish content.

### Standard Flow

Redirect users to the Zernio OAuth URL:

```
https://zernio.com/connect/snapchat?profileId=YOUR_PROFILE_ID&redirect_url=https://yourapp.com/callback
```

After authorization, users select a Public Profile, and Zernio redirects back to your `redirect_url` with connection details.

### Headless Mode (Custom UI)

Build your own fully-branded Public Profile selector:

#### Step 1: Initiate OAuth

```
https://zernio.com/api/v1/connect/snapchat?profileId=YOUR_PROFILE_ID&redirect_url=https://yourapp.com/callback&headless=true
```

After OAuth, you'll be redirected to your `redirect_url` with:
- `tempToken` - Temporary access token
- `userProfile` - URL-encoded JSON with user info
- `publicProfiles` - URL-encoded JSON array of available Public Profiles
- `connect_token` - Short-lived token for API authentication
- `platform=snapchat`
- `step=select_public_profile`

#### Step 2: List Public Profiles

<Tabs items={['Python', 'curl']}>
<Tab value="Python">
```python
result = client.connect.list_snapchat_profiles(
    profile_id="YOUR_PROFILE_ID",
    temp_token=temp_token,
    x_connect_token=connect_token
)
public_profiles = result['publicProfiles']
# Display profiles in your custom UI
```
</Tab>
<Tab value="curl">
```bash
curl -X GET "https://zernio.com/api/v1/connect/snapchat/select-profile?profileId=YOUR_PROFILE_ID&tempToken=TEMP_TOKEN" \
  -H "X-Connect-Token: CONNECT_TOKEN"
```
</Tab>
</Tabs>

**Response:**
```json
{
  "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
    }
  ]
}
```

#### Step 3: Select Public Profile

<Tabs items={['Python', 'curl']}>
<Tab value="Python">
```python
result = client.connect.select_snapchat_profile(
    profile_id="YOUR_PROFILE_ID",
    selected_public_profile={
        "id": "abc123-def456",
        "display_name": "My Brand",
        "username": "mybrand"
    },
    temp_token=temp_token,
    user_profile=user_profile,
    x_connect_token=connect_token
)
print(f"Connected: {result['account']['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/connect/snapchat/select-profile \
  -H "X-Connect-Token: CONNECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "YOUR_PROFILE_ID",
    "selectedPublicProfile": {
      "id": "abc123-def456",
      "display_name": "My Brand",
      "username": "mybrand"
    },
    "tempToken": "TEMP_TOKEN",
    "userProfile": {
      "id": "user123",
      "username": "mybrand",
      "displayName": "My Brand"
    }
  }'
```
</Tab>
</Tabs>

**Response:**
```json
{
  "message": "Snapchat connected successfully with public profile",
  "account": {
    "platform": "snapchat",
    "username": "mybrand",
    "displayName": "My Brand",
    "profilePicture": "https://cf-st.sc-cdn.net/...",
    "isActive": true,
    "publicProfileName": "My Brand"
  }
}
```

## Analytics

> **Included** — Analytics is bundled with every paid account on the [Usage plan](/pricing).

Available metrics via the [Analytics API](/analytics/get-analytics):

| Metric | Available |
|--------|-----------|
| Reach (unique viewers) | ✅ |
| Shares | ✅ |
| Views | ✅ |
| Screenshots | ✅ |
| Completion Rate | ✅ |

Analytics are fetched per content type (story, saved_story, spotlight).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const analytics = await zernio.analytics.getAnalytics({
  platform: 'snapchat',
  fromDate: '2024-01-01',
  toDate: '2024-01-31'
});
console.log(analytics.posts);
```
</Tab>
<Tab value="Python">
```python
analytics = client.analytics.get_analytics(
    platform="snapchat",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(analytics["posts"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics?platform=snapchat&fromDate=2024-01-01&toDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

## What You Can't Do

These features are not available through Snapchat's API:

- Use AR lenses or filters
- Create ads
- Access Snap Map features
- Use Snapchat sounds
- Create collaborative stories
- Access friend stories
- Send DMs or read comments
- Post text-only content (media required)
- Post multiple media items (single item only)

## Common Errors

| Error | Meaning | Fix |
|-------|---------|-----|
| "Public Profile required" | Account does not have a Public Profile set up | Ensure the Snapchat account has a Public Profile (Person, Business, or Official) and select it during the connection flow. |
| "Media is required" | Post was submitted without any media | Add an image or video. Snapchat does not support text-only posts. |
| "Only one media item supported" | Multiple media items were included | Remove extra media items. Snapchat only supports a single image or video per post. |
| Video rejected | Video does not meet Snapchat's requirements | Check duration (5-60 sec), format (MP4 only), minimum resolution (540 x 960 px), and file size (under 500 MB). |
| "Title too long" (Saved Stories) | Title exceeds 45 characters | Shorten the `content` field to 45 characters or fewer. |
| "Description too long" (Spotlight) | Description exceeds 160 characters | Shorten the `content` field to 160 characters or fewer, including hashtags. |

## Inbox

Snapchat does not have inbox features available via API.

- **No DMs** - Snapchat's messaging API is not available for third-party apps
- **No comments** - Snap comments are not accessible via API

## Related Endpoints

- [Connect Snapchat Account](/guides/connecting-accounts) - OAuth connection flow
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Image and video uploads
- [Analytics](/analytics/get-analytics) - Fetch post analytics

---

# Telegram

Schedule and automate Telegram channel and group posts with Zernio API - Text, images, videos, media albums, silent messages, and bot management

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Reference

| Property | Value |
|----------|-------|
| Text limit | 4,096 characters (text messages) |
| Caption limit | 1,024 characters (media captions) |
| Images per album | 10 |
| Videos per album | 10 |
| Mixed media | Yes (images + videos in same album) |
| Image formats | JPEG, PNG, GIF, WebP |
| Image max size | 10 MB (auto-compressed) |
| Video formats | MP4, MOV |
| Video max size | 50 MB (auto-compressed) |
| Scheduling | Yes |
| Inbox (DMs) | Yes (full featured) |
| Inbox (Comments) | No |
| Analytics | No (Telegram limitation) |

## Before You Start

<Callout type="warn">
Telegram requires **@ZernioScheduleBot** to be an administrator in your channel or group with **post permissions**. This is the number one setup failure. Also: posts in groups show as sent by "ZernioScheduleBot", not by you. In channels, posts show as the channel name.

Additional requirements:
- Bot-based integration (not OAuth). Uses `@ZernioScheduleBot`
- The bot must be added as an admin with post permissions before you can publish
- **Channels:** posts appear as the channel name and logo (correct behavior)
- **Groups:** posts appear as "ZernioScheduleBot" (cannot be changed)
</Callout>

## Quick Start

Post to a Telegram channel or group:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Hello from Zernio API! Check out our latest update.',
  platforms: [
    { platform: 'telegram', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to Telegram!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Hello from Zernio API! Check out our latest update.",
    platforms=[
        {"platform": "telegram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to Telegram! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from Zernio API! Check out our latest update.",
    "platforms": [
      {"platform": "telegram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

### Text Message

Send a formatted text message with HTML, Markdown, or MarkdownV2:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: '<b>Important Update!</b>\n\nCheck out our <a href="https://example.com">new feature</a>.',
  platforms: [{
    platform: 'telegram',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      parseMode: 'HTML'
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content='<b>Important Update!</b>\n\nCheck out our <a href="https://example.com">new feature</a>.',
    platforms=[{
        "platform": "telegram",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "parseMode": "HTML"
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<b>Important Update!</b>\n\nCheck out our <a href=\"https://example.com\">new feature</a>.",
    "platforms": [{
      "platform": "telegram",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "parseMode": "HTML"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Photo Message

Send a single image with an optional caption:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Check out this photo!',
  mediaItems: [
    { type: 'image', url: 'https://example.com/image.jpg' }
  ],
  platforms: [
    { platform: 'telegram', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Check out this photo!",
    media_items=[
        {"type": "image", "url": "https://example.com/image.jpg"}
    ],
    platforms=[
        {"platform": "telegram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out this photo!",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/image.jpg"}
    ],
    "platforms": [
      {"platform": "telegram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Video Message

Send a single video with an optional caption:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Watch our latest video!',
  mediaItems: [
    { type: 'video', url: 'https://example.com/video.mp4' }
  ],
  platforms: [
    { platform: 'telegram', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Watch our latest video!",
    media_items=[
        {"type": "video", "url": "https://example.com/video.mp4"}
    ],
    platforms=[
        {"platform": "telegram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Watch our latest video!",
    "mediaItems": [
      {"type": "video", "url": "https://example.com/video.mp4"}
    ],
    "platforms": [
      {"platform": "telegram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Document Message

Send any file type as a document:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Here is the report.',
  mediaItems: [
    { type: 'document', url: 'https://example.com/report.pdf' }
  ],
  platforms: [
    { platform: 'telegram', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Here is the report.",
    media_items=[
        {"type": "document", "url": "https://example.com/report.pdf"}
    ],
    platforms=[
        {"platform": "telegram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Here is the report.",
    "mediaItems": [
      {"type": "document", "url": "https://example.com/report.pdf"}
    ],
    "platforms": [
      {"platform": "telegram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Media Album

Send up to 10 items in a single album. Images and videos can be mixed:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Our latest product gallery!',
  mediaItems: [
    { type: 'image', url: 'https://example.com/image1.jpg' },
    { type: 'image', url: 'https://example.com/image2.jpg' },
    { type: 'video', url: 'https://example.com/video.mp4' },
    { type: 'image', url: 'https://example.com/image3.jpg' }
  ],
  platforms: [
    { platform: 'telegram', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Our latest product gallery!",
    media_items=[
        {"type": "image", "url": "https://example.com/image1.jpg"},
        {"type": "image", "url": "https://example.com/image2.jpg"},
        {"type": "video", "url": "https://example.com/video.mp4"},
        {"type": "image", "url": "https://example.com/image3.jpg"}
    ],
    platforms=[
        {"platform": "telegram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Our latest product gallery!",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/image1.jpg"},
      {"type": "image", "url": "https://example.com/image2.jpg"},
      {"type": "video", "url": "https://example.com/video.mp4"},
      {"type": "image", "url": "https://example.com/image3.jpg"}
    ],
    "platforms": [
      {"platform": "telegram", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Media Requirements

### Images

| Property | Requirement |
|----------|-------------|
| **Max per album** | 10 |
| **Formats** | JPEG, PNG, GIF, WebP |
| **Max file size** | 10 MB (auto-compressed) |
| **Max resolution** | 10,000 x 10,000 px |

### Videos

| Property | Requirement |
|----------|-------------|
| **Max per album** | 10 |
| **Formats** | MP4, MOV |
| **Max file size** | 50 MB (auto-compressed) |
| **Max duration** | No limit |
| **Codec** | H.264 recommended |

## Platform-Specific Fields

All fields go inside `platformSpecificData` for the Telegram platform entry:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `parseMode` | string | `"HTML"` | Text formatting mode: `"HTML"`, `"Markdown"`, or `"MarkdownV2"` |
| `disableWebPagePreview` | boolean | `false` | Prevents link preview generation for URLs in the message |
| `disableNotification` | boolean | `false` | Sends the message silently (recipients get no notification sound) |
| `protectContent` | boolean | `false` | Prevents the message from being forwarded or saved by recipients |

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: '<b>Important Update!</b>\n\nCheck out our <a href="https://example.com">new feature</a>.',
  platforms: [{
    platform: 'telegram',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      parseMode: 'HTML',
      disableWebPagePreview: false,
      disableNotification: true,
      protectContent: true
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content='<b>Important Update!</b>\n\nCheck out our <a href="https://example.com">new feature</a>.',
    platforms=[{
        "platform": "telegram",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "parseMode": "HTML",
            "disableWebPagePreview": False,
            "disableNotification": True,
            "protectContent": True
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<b>Important Update!</b>\n\nCheck out our <a href=\"https://example.com\">new feature</a>.",
    "platforms": [{
      "platform": "telegram",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "parseMode": "HTML",
        "disableWebPagePreview": false,
        "disableNotification": true,
        "protectContent": true
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Connection

Zernio provides a managed bot (`@ZernioScheduleBot`) for Telegram integration. No need to create your own bot -- just add Zernio's bot to your channel or group.

### Option 1: Access Code Flow (Recommended)

This is the easiest way to connect a Telegram channel or group.

#### Step 1: Generate an Access Code

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { code, botUsername, instructions } = await zernio.connect.getConnectUrl({
  platform: 'telegram',
  profileId: 'YOUR_PROFILE_ID'
});
console.log(`Your access code: ${code}`);
console.log(`Bot to message: @${botUsername}`);
```
</Tab>
<Tab value="Python">
```python
result = client.connect.get_connect_url(
    platform="telegram",
    profile_id="YOUR_PROFILE_ID"
)
print(f"Your access code: {result.code}")
print(f"Bot to message: @{result.bot_username}")
```
</Tab>
<Tab value="curl">
```bash
curl -X GET "https://zernio.com/api/v1/connect/telegram?profileId=YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

**Response:**
```json
{
  "code": "ZERNIO-ABC123",
  "expiresAt": "2025-01-15T12:30:00.000Z",
  "expiresIn": 900,
  "botUsername": "ZernioScheduleBot",
  "instructions": [
    "1. Add @ZernioScheduleBot as an administrator in your channel/group",
    "2. Open a private chat with @ZernioScheduleBot",
    "3. Send: ZERNIO-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"
  ]
}
```

#### Step 2: Add the Bot to Your Channel/Group

**For Channels:**
1. Go to your channel settings
2. Add `@ZernioScheduleBot` as an **Administrator**
3. Grant permission to **Post Messages**

**For Groups:**
1. Add `@ZernioScheduleBot` to the group
2. Make the bot an **Administrator** (required for posting)

#### Step 3: Send the Access Code

1. Open a private chat with [@ZernioScheduleBot](https://t.me/ZernioScheduleBot)
2. Send your access code with your channel: `ZERNIO-ABC123 @yourchannel`
3. For private channels without a username, forward any message from the channel to the bot along with the code

#### Step 4: Poll for Connection Status

<Tabs items={['curl']}>
<Tab value="curl">
```bash
curl -X PATCH "https://zernio.com/api/v1/connect/telegram?code=ZERNIO-ABC123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

<Callout type="info">
The published Node and Python SDKs auto-generate signatures for these Telegram connect-status endpoints that don't match the actual request shape (the endpoint takes `code` as a query param). Until the next regen catches up, hit the endpoint directly via fetch / requests.
</Callout>

**Status Response (Pending):**
```json
{
  "status": "pending",
  "expiresAt": "2025-01-15T12:30:00.000Z",
  "expiresIn": 542
}
```

**Status Response (Connected):**
```json
{
  "status": "connected",
  "chatId": "-1001234567890",
  "chatTitle": "My Channel",
  "chatType": "channel",
  "account": {
    "_id": "64e1f0a9e2b5af0012ab34cd",
    "platform": "telegram",
    "username": "mychannel",
    "displayName": "My Channel"
  }
}
```

### Option 2: Direct Connection (Power Users)

If you already know your chat ID and the Zernio bot is already an administrator in your channel/group:

<Callout type="info">
The published Node and Python SDKs auto-generate signatures for these Telegram connect endpoints that don't match the actual request shape. Until the next regen catches up, hit the endpoint directly.
</Callout>

<Tabs items={['curl']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/connect/telegram \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "YOUR_PROFILE_ID",
    "chatId": "-1001234567890"
  }'
```
</Tab>
</Tabs>

**Response:**
```json
{
  "message": "Telegram channel connected successfully",
  "account": {
    "_id": "64e1f0a9e2b5af0012ab34cd",
    "platform": "telegram",
    "username": "mychannel",
    "displayName": "My Channel",
    "isActive": true,
    "chatType": "channel"
  }
}
```

### Finding Your Chat ID

**For Public Channels:**
- Use the channel username with `@` prefix: `@mychannel`

**For Private Channels:**
- Forward a message from the channel to [@userinfobot](https://t.me/userinfobot)
- The bot will reply with the numeric chat ID (starts with `-100`)

**For Groups:**
- Add [@userinfobot](https://t.me/userinfobot) to your group temporarily
- It will display the group's chat ID (negative number)
- Remove the bot after getting the ID

## Text Formatting

### HTML Mode (Default)

```html
<b>bold</b>
<i>italic</i>
<u>underline</u>
<s>strikethrough</s>
<code>inline code</code>
<pre>code block</pre>
<a href="https://example.com">link</a>
```

### Markdown Mode

```markdown
*bold*
_italic_
[link](https://example.com)
`inline code`
```

### MarkdownV2 Mode

```markdown
*bold*
_italic_
__underline__
~strikethrough~
||spoiler||
`inline code`
```

> **Note:** MarkdownV2 requires escaping special characters: `_`, `*`, `[`, `]`, `(`, `)`, `~`, `` ` ``, `>`, `#`, `+`, `-`, `=`, `|`, `{`, `}`, `.`, `!`

## Channel vs Group Posts

| Destination | Author Display |
|-------------|----------------|
| **Channel** | Channel name and logo |
| **Group** | Bot name (ZernioScheduleBot) |

When posting to a **channel**, the post appears as if sent by the channel itself. When posting to a **group**, the post shows as sent by the Zernio bot.

## Analytics

Telegram does not provide analytics through its Bot API. View counts for channel posts are only visible within the Telegram app. For messaging metrics, use Telegram's native channel statistics (available for channels with 500+ subscribers).

## What You Can't Do

- Create polls or quizzes via Zernio
- Schedule messages natively through Telegram (use Zernio scheduling instead)
- Manage channel administrators
- See message analytics (Telegram platform limitation)
- Pin messages
- Create channel invite links

## Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| "Bot is not a member of the channel" | `@ZernioScheduleBot` is not added to the channel/group or is not an admin | Add the bot as an administrator and grant post permissions |
| "Message is too long" | Text exceeds 4,096 characters or caption exceeds 1,024 characters | Shorten the content or split into multiple messages |
| "Wrong file identifier/HTTP URL specified" | Media URL is inaccessible, uses HTTP, or redirects | Use a direct HTTPS URL that is publicly accessible with no redirects |
| "Can't parse entities" | Invalid HTML/Markdown syntax or unescaped special characters | Check tag closure in HTML mode; escape special characters in MarkdownV2 |
| Media not displaying | Unsupported format or file exceeds size limit | Verify format is supported and size is within limits (10 MB images, 50 MB videos) |
| "Access code expired" | Code was not used within 15 minutes | Generate a new access code with `GET /v1/connect/telegram` |

## Inbox

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

Telegram supports DMs with full attachment support.

### Direct Messages

| Feature | Supported |
|---------|-----------|
| List conversations | Yes |
| Fetch messages | Yes |
| Send text messages | Yes |
| Send attachments | Yes (images, videos, documents) |
| Edit messages | Yes (text and inline keyboard) |
| Inline keyboards | Yes (buttons with callback data or URLs) |
| Reply keyboards | Yes (one-time custom keyboards) |
| Reply to message | Yes (via `replyTo` message ID) |
| Archive/unarchive | Yes |

### Attachment Support

| Type | Supported | Max Size |
|------|-----------|----------|
| Images | Yes | 10 MB |
| Videos | Yes | 50 MB |
| Documents | Yes | 50 MB |

### Bot Commands

Manage the bot command menu shown in Telegram chats. Commands appear in the "/" menu when users interact with the bot.

See [Account Settings](/account-settings/get-telegram-commands) for the `GET/PUT/DELETE /v1/accounts/{accountId}/telegram-commands` endpoints.

### Webhooks

| Event | When it fires |
|-------|---------------|
| `message.received` | New incoming message to the bot |
| `message.sent` | Outgoing message is sent |
| `message.edited` | The user edits a previously-sent message (also fires for `edited_channel_post` in channels where the bot is admin) |
| `reaction.received` | A participant adds or removes an emoji reaction. The bot must be an administrator in the chat; reactions in private chats are not delivered |

Messages are stored locally via webhooks. See the [Webhooks](/webhooks) page for payload details.

**Note:** Telegram's Bot API does not expose deletion or read receipt events for regular bot chats. Delivery and read tracking is available only through the separate Telegram Business integration, which Zernio does not currently use.

### Notes

- **Bot-based** - Uses bot tokens, not OAuth
- Messages are stored locally when received via webhooks
- Incoming callback data from inline keyboard taps is available in message `metadata.callbackData`

See [Messages API Reference](/messages/list-inbox-conversations) for endpoint details.

## Related Endpoints

- [Connect Telegram Account](/guides/connecting-accounts) - Access code connection flow
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Image and video uploads
- [Messages](/messages/list-inbox-conversations) - Inbox conversations and DMs
- [Account Settings](/account-settings/get-telegram-commands) - Bot commands configuration

---

# Threads

Schedule and automate Threads posts with Zernio API - Text, images, videos, carousels, and thread sequences

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Reference

| Property | Value |
|----------|-------|
| Character limit | 500 |
| Images per post | 10 (carousel) |
| Videos per post | 1 |
| Image formats | JPEG, PNG, WebP, GIF |
| Image max size | 8 MB (auto-compressed) |
| Video formats | MP4, MOV |
| Video max size | 1 GB |
| Video max duration | 5 minutes |
| Post types | Text, Image, Video, Carousel, Thread sequence |
| Scheduling | Yes |
| Inbox (Comments) | Reply + delete + hide only |
| Inbox (DMs) | No |
| Analytics | Limited |

## Before You Start

<Callout type="warn">
Threads has a **500 character limit**. This is the #1 failure -- users cross-posting from LinkedIn (3,000), Facebook (63,000), or even Instagram (2,200) captions will fail. Use `customContent` to provide a shorter Threads version.

Threads is connected to your Instagram account. You **must** have an Instagram Business or Creator account with Threads enabled. Losing Instagram access means losing Threads.

Additional requirements:
- Connected via Instagram authentication (same Facebook app)
- If your Instagram account is restricted, Threads posting fails too
- Rate limit: 250 API-published posts per 24-hour window
</Callout>

## Quick Start

Post to Threads in under 60 seconds:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Sharing some thoughts on building in public',
  platforms: [
    { platform: 'threads', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to Threads!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Sharing some thoughts on building in public",
    platforms=[
        {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to Threads! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Sharing some thoughts on building in public",
    "platforms": [
      {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

### Text Post

Threads is one of the few platforms that supports text-only posts -- no media required. Up to 500 characters.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Hot take: the best API is the one with the best docs.',
  platforms: [
    { platform: 'threads', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Text post created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Hot take: the best API is the one with the best docs.",
    platforms=[
        {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Text post created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hot take: the best API is the one with the best docs.",
    "platforms": [
      {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Image Post

A single image with an optional caption.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'New office setup is looking great',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/office.jpg' }
  ],
  platforms: [
    { platform: 'threads', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Image post created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="New office setup is looking great",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/office.jpg"}
    ],
    platforms=[
        {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Image post created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New office setup is looking great",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/office.jpg"}
    ],
    "platforms": [
      {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Video Post

A single video with an optional caption. Max 1 GB, up to 5 minutes long.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Behind the scenes of our latest product launch',
  mediaItems: [
    { type: 'video', url: 'https://cdn.example.com/launch.mp4' }
  ],
  platforms: [
    { platform: 'threads', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Video post created!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Behind the scenes of our latest product launch",
    media_items=[
        {"type": "video", "url": "https://cdn.example.com/launch.mp4"}
    ],
    platforms=[
        {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Video post created! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Behind the scenes of our latest product launch",
    "mediaItems": [
      {"type": "video", "url": "https://cdn.example.com/launch.mp4"}
    ],
    "platforms": [
      {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Carousel

Up to 10 images in a single swipeable post.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Product launch day! Here are all the new features:',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/feature1.jpg' },
    { type: 'image', url: 'https://cdn.example.com/feature2.jpg' },
    { type: 'image', url: 'https://cdn.example.com/feature3.jpg' }
  ],
  platforms: [
    { platform: 'threads', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Carousel posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Product launch day! Here are all the new features:",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/feature1.jpg"},
        {"type": "image", "url": "https://cdn.example.com/feature2.jpg"},
        {"type": "image", "url": "https://cdn.example.com/feature3.jpg"}
    ],
    platforms=[
        {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Carousel posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Product launch day! Here are all the new features:",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/feature1.jpg"},
      {"type": "image", "url": "https://cdn.example.com/feature2.jpg"},
      {"type": "image", "url": "https://cdn.example.com/feature3.jpg"}
    ],
    "platforms": [
      {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Thread Sequence

Create connected posts (root + replies) using `threadItems`. The first item is the root post and subsequent items become replies in order. Each item can have its own text and media.

> **Note:** 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]`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  platforms: [{
    platform: 'threads',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      threadItems: [
        {
          content: 'Here is a thread about API design',
          mediaItems: [{ type: 'image', url: 'https://cdn.example.com/cover.jpg' }]
        },
        { content: '1/ First, let us talk about REST principles...' },
        {
          content: '2/ Authentication is crucial. Here is what we recommend...',
          mediaItems: [{ type: 'image', url: 'https://cdn.example.com/auth-diagram.jpg' }]
        },
        { content: '3/ Finally, always version your API! /end' }
      ]
    }
  }],
  publishNow: true
});
console.log('Thread posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    platforms=[{
        "platform": "threads",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "threadItems": [
                {
                    "content": "Here is a thread about API design",
                    "mediaItems": [{"type": "image", "url": "https://cdn.example.com/cover.jpg"}]
                },
                {"content": "1/ First, let us talk about REST principles..."},
                {
                    "content": "2/ Authentication is crucial. Here is what we recommend...",
                    "mediaItems": [{"type": "image", "url": "https://cdn.example.com/auth-diagram.jpg"}]
                },
                {"content": "3/ Finally, always version your API! /end"}
            ]
        }
    }],
    publish_now=True
)
post = result.post
print(f"Thread posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": [{
      "platform": "threads",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "threadItems": [
          {
            "content": "Here is a thread about API design",
            "mediaItems": [{"type": "image", "url": "https://cdn.example.com/cover.jpg"}]
          },
          {
            "content": "1/ First, let us talk about REST principles..."
          },
          {
            "content": "2/ Authentication is crucial. Here is what we recommend...",
            "mediaItems": [{"type": "image", "url": "https://cdn.example.com/auth-diagram.jpg"}]
          },
          {
            "content": "3/ Finally, always version your API! /end"
          }
        ]
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Media Requirements

### Images

| Property | Requirement |
|----------|-------------|
| **Max images** | 10 per post (carousel) |
| **Formats** | JPEG, PNG, WebP, GIF |
| **Max file size** | 8 MB per image (auto-compressed) |
| **Recommended** | 1080 x 1350 px (4:5 portrait) |

#### Aspect Ratios

| Ratio | Dimensions | Notes |
|-------|------------|-------|
| 4:5 | 1080 x 1350 px | Portrait, recommended |
| 1:1 | 1080 x 1080 px | Square |
| 16:9 | 1080 x 608 px | Landscape |

### Videos

| Property | Requirement |
|----------|-------------|
| **Max videos** | 1 per post |
| **Formats** | MP4, MOV |
| **Max file size** | 1 GB |
| **Max duration** | 5 minutes |
| **Aspect ratio** | 9:16 (vertical), 16:9 (landscape), 1:1 (square) |
| **Resolution** | 1080p recommended |
| **Codec** | H.264 |
| **Frame rate** | 30 fps recommended |
| **Audio** | AAC, 128 kbps |

## Platform-Specific Fields

All fields go inside `platformSpecificData` on the Threads platform entry.

| Field | Type | Description |
|-------|------|-------------|
| `topic_tag` | string | Topic tag for categorization/discoverability. 1-50 characters, cannot contain periods (`.`) or ampersands (`&`). When provided, overrides auto-extraction from content hashtags. |
| `threadItems` | Array\<\{content, mediaItems?\}\> | Complete sequence of posts in a Threads thread. The first item becomes the root post and must be provided as `threadItems[0]`. When `threadItems` is provided, top-level `content` is for display/search only and is NOT published. |

## Topic Tags

Use `platformSpecificData.topic_tag` to explicitly set the Threads topic tag for a post.

> **Note:** If you set `topic_tag`, it overrides any topic tag that Threads might auto-extract from hashtags in your content.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Building better APIs starts with better docs.",
    "platforms": [{
      "platform": "threads",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "topic_tag": "APIDesign"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Building better APIs starts with better docs.',
  platforms: [{
    platform: 'threads',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      topic_tag: 'APIDesign'
    }
  }],
  publishNow: true
});
console.log('Posted to Threads!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Building better APIs starts with better docs.",
    platforms=[{
        "platform": "threads",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "topic_tag": "APIDesign"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Posted to Threads! {post['_id']}")
```
</Tab>
</Tabs>

## Media URL Requirements

<Callout type="error">
**These do not work as media URLs:**
- **Google Drive** -- returns an HTML download page, not the file
- **Dropbox** -- returns an HTML preview page
- **OneDrive / SharePoint** -- returns HTML
- **iCloud** -- returns HTML

Test your URL in an incognito browser window. If you see a webpage instead of the raw image or video, it will not work.
</Callout>

Threads uses the same media infrastructure as Instagram. Media URLs must be:
- Publicly accessible (no authentication required)
- Returning actual media bytes with the correct `Content-Type` header
- Not behind redirects that resolve to HTML pages

**WebP images may fail** -- use JPEG or PNG for the most reliable results.

Images above 8 MB are auto-compressed. Original files are preserved.

## Analytics

> **Included** — Analytics is bundled with every paid account on the [Usage plan](/pricing).

Available metrics via the [Analytics API](/analytics/get-analytics):

| Metric | Available |
|--------|-----------|
| Impressions | ✅ |
| Likes | ✅ |
| Comments | ✅ |
| Shares | ✅ |
| Views | ✅ |

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const analytics = await zernio.analytics.getAnalytics({
  platform: 'threads',
  fromDate: '2024-01-01',
  toDate: '2024-01-31'
});
console.log(analytics.posts);
```
</Tab>
<Tab value="Python">
```python
analytics = client.analytics.get_analytics(
    platform="threads",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(analytics["posts"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics?platform=threads&fromDate=2024-01-01&toDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

## What You Can't Do

These features are not available through the Threads API:

- Create polls
- Use GIF search
- Edit posts after publishing
- See who liked or reposted
- Create quote posts
- Post new top-level comments (reply-only)
- Like or unlike comments
- Send DMs

## Common Errors

Threads has a **14.5% failure rate** across Zernio's platform (7,705 failures out of 53,014 attempts). Here are the most frequent errors and how to fix them:

| Error | Meaning | Fix |
|-------|---------|-----|
| "Param text must be at most 500 characters long." | Post exceeds the 500 character limit | Shorten to 500 characters. Use `customContent` for cross-platform posts so each platform gets its own version. |
| "Media download has failed. The media URI doesn't meet our requirements." (2207052) | Threads cannot fetch media from the provided URL | URL must return actual media bytes, not an HTML page. WebP may fail -- use JPEG or PNG instead. |
| "Instagram account is restricted." (2207050) | The linked Instagram account is restricted | Check your account status on Instagram. Resolve any policy violations before retrying. |
| "Publishing failed due to max retries reached" | All publishing retries were exhausted | This is usually temporary. Wait a few minutes and retry manually. |

## Inbox

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

Threads supports comment management through the unified Inbox API. Threads does not have direct messaging.

### Comments

| Feature | Supported |
|---------|-----------|
| List comments on posts | ✅ |
| Post new comment | ❌ |
| Reply to comments | ✅ |
| Delete comments | ✅ |
| Like/unlike comments | ❌ |
| Hide/unhide comments | ✅ |

### Limitations

- **No DMs** - Threads API does not support direct messages
- **No comment likes** - Threads API does not support liking comments
- **Reply-only** - Cannot post new top-level comments, only replies

See [Comments API Reference](/comments/list-inbox-comments) for endpoint details.

## Related Endpoints

- [Connect Threads Account](/guides/connecting-accounts) - Via Instagram authentication
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Image and video uploads
- [Analytics](/analytics/get-analytics) - Performance metrics
- [Comments](/comments/list-inbox-comments) - Reply to comments

---

# TikTok Ads

Create campaigns and Spark Ads via Zernio API - No TikTok Business Center developer onboarding required

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

<Callout type="info">
**Included with the [Usage plan](/pricing).** No TikTok Business Center developer onboarding needed. Connect via OAuth and start building.
</Callout>

## What's Supported

| Feature | Status |
|---------|--------|
| Standalone campaigns (Campaign > Ad Group > Ad) | Yes |
| Website conversion ads (TikTok Pixel optimization) | Yes |
| Spark Ads (boost organic videos) | Yes |
| Spark Ad custom destination URL + CTA | Yes |
| Spark Code (cross-creator boosts via `auth_code`) | Yes |
| Bid strategy (Cost Cap, ROAS floor) | Yes |
| Campaign duplication (manual graph copy) | Yes |
| Attach-to-existing-adset on `/v1/ads/create` | Yes |
| Creative swap on `PUT /v1/ads/{adId}` | Yes |
| Targeting updates after creation | Yes |
| Agency Business Centers (multi-advertiser + BC list endpoint) | Yes |
| Custom Audiences (customer list) | Yes |
| Age, gender, location, interest targeting | Yes |
| Video creative from URL | Yes |
| Real-time analytics (spend, views, CTR, CPM) | Yes |
| Catalog / TikTok Shop ads | Roadmap |
| Chunked video upload + async transcode | Roadmap |

## Create a Spark Ad (Boost)

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.boostPost({ body: {
  postId: "POST_ID",
  accountId: "ACCOUNT_ID",
  adAccountId: "7123456789012345678",
  name: "Boost viral video",
  goal: "traffic",
  budget: { amount: 50, type: "daily" },
  schedule: { startDate: "2026-04-20", endDate: "2026-04-27" },
  // TikTok-only Spark Ad creative overrides. Required for traffic /
  // conversion campaigns — without linkUrl the Spark Ad has no clickable
  // destination. CTA is the button label (e.g. SHOP_NOW, LEARN_MORE).
  linkUrl: "https://example.com/landing",
  callToAction: "SHOP_NOW",
  // Optional: Cost Cap bidding. bidStrategy is the cross-platform Meta enum;
  // we map it to TikTok's bid_type / bid_price automatically.
  bidStrategy: "COST_CAP",
  bidAmount: 0.50,
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.boost_post(
    post_id="POST_ID",
    account_id="ACCOUNT_ID",
    ad_account_id="7123456789012345678",
    name="Boost viral video",
    goal="traffic",
    budget={"amount": 50, "type": "daily"},
    schedule={"startDate": "2026-04-20", "endDate": "2026-04-27"},
    link_url="https://example.com/landing",
    call_to_action="SHOP_NOW",
    bid_strategy="COST_CAP",
    bid_amount=0.50,
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/boost" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postId": "POST_ID",
    "accountId": "ACCOUNT_ID",
    "adAccountId": "7123456789012345678",
    "name": "Boost viral video",
    "goal": "traffic",
    "budget": { "amount": 50, "type": "daily" },
    "schedule": { "startDate": "2026-04-20", "endDate": "2026-04-27" },
    "linkUrl": "https://example.com/landing",
    "callToAction": "SHOP_NOW",
    "bidStrategy": "COST_CAP",
    "bidAmount": 0.50
  }'
```
</Tab>
</Tabs>

Spark Ads retain the creator's identity, organic engagement signals, and follower handle. `linkUrl` and `callToAction` map to `landing_page_url` and `call_to_action` on TikTok's `/v2/ad/create/` creative — pass them when boosting for traffic/conversion goals so the ad has a clickable destination distinct from the original organic post.

## Create a Standalone Campaign

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.createStandaloneAd({ body: {
  accountId: "acc_tiktokads_123",
  adAccountId: "7123456789012345678",
  name: "Spring launch",
  goal: "traffic",
  budgetAmount: 100,
  budgetType: "daily",
  body: "Spring drop is live",
  linkUrl: "https://example.com/spring",
  imageUrl: "https://cdn.example.com/launch.mp4",
  callToAction: "SHOP_NOW",
  countries: ["US"],
  ageMin: 18,
  ageMax: 34,
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.create_standalone_ad(
    account_id="acc_tiktokads_123",
    ad_account_id="7123456789012345678",
    name="Spring launch",
    goal="traffic",
    budget_amount=100,
    budget_type="daily",
    body="Spring drop is live",
    link_url="https://example.com/spring",
    image_url="https://cdn.example.com/launch.mp4",
    call_to_action="SHOP_NOW",
    countries=["US"],
    age_min=18,
    age_max=34,
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_tiktokads_123",
    "adAccountId": "7123456789012345678",
    "name": "Spring launch",
    "goal": "traffic",
    "budgetAmount": 100,
    "budgetType": "daily",
    "body": "Spring drop is live",
    "linkUrl": "https://example.com/spring",
    "imageUrl": "https://cdn.example.com/launch.mp4",
    "callToAction": "SHOP_NOW",
    "countries": ["US"],
    "ageMin": 18,
    "ageMax": 34
  }'
```
</Tab>
</Tabs>

<Callout type="info">
TikTok's ads endpoint is **video-only**. Pass the video URL as `imageUrl`, the field name is kept for cross-platform consistency. `headline` is ignored on TikTok (no headline slot in TikTok creatives); `body` is the video caption. `callToAction` is supported and maps to the in-feed CTA button. Valid `goal` values: `engagement`, `traffic`, `awareness`, `video_views`, `lead_generation`, `conversions`, `app_promotion`. For `goal: "conversions"` you must also pass `promotedObject.pixelId` (see [Conversion campaigns](#conversion-campaigns) below).
</Callout>

## Conversion campaigns

A TikTok website-conversion campaign (`goal: "conversions"`, which Zernio maps to a `CONVERSIONS` objective with a `WEBSITE` / `CONVERT` ad group) needs a TikTok Pixel. Without one, TikTok rejects the ad group with `40002: Please select a pixel`. Pass the pixel via `promotedObject` (the same cross-platform field Meta uses):

| `promotedObject` field | Maps to TikTok | Required |
|---|---|---|
| `pixelId` | ad group `pixel_id` (**numeric** — see note) | **Yes** |
| `customEventType` | ad group `optimization_event` (the pixel event to optimise for) | No (auto-bid CONVERT works without it) |

`customEventType` takes a TikTok `optimization_event` code (TikTok's own UPPER_SNAKE codes, **not** Meta's `PURCHASE`/`LEAD` vocabulary and **not** PascalCase). The value must be one of the events your pixel is configured to track. Common website codes:

| Code | Pixel event |
|---|---|
| `ON_WEB_ORDER` | Complete Payment |
| `INITIATE_ORDER` | Place an Order |
| `ON_WEB_CART` | Add to Cart |
| `ON_WEB_REGISTER` | Complete Registration |
| `ON_WEB_DETAIL` | View Content |
| `FORM` | Submit Form |
| `ON_WEB_SEARCH` | Search |
| `ON_WEB_ADD_TO_WISHLIST` | Add to Wishlist |
| `LANDING_PAGE_VIEW` | Landing Page View |

<Callout type="warn">
`pixelId` must be the **numeric** TikTok Pixel ID, not the alphanumeric Pixel Code shown in Events Manager (e.g. `D00IKHRC77UE0J0RTNHG`). TikTok's ad-group API rejects the alphanumeric code with `40002: pixel_id ... is not a valid integer string`. The numeric ID is the value `/pixel/list/` returns as `pixel_id`; if TikTok Ads Manager only surfaces the alphanumeric code for your pixel, retrieve the numeric ID via the TikTok Marketing API (`GET /pixel/list/`, filter by `code`).
</Callout>

Find your pixel and the events it tracks in TikTok Ads Manager → Assets → Events.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.createStandaloneAd({ body: {
  accountId: "acc_tiktokads_123",
  adAccountId: "7123456789012345678",
  name: "Spring launch - purchases",
  goal: "conversions",
  budgetAmount: 100,
  budgetType: "daily",
  body: "Spring drop is live",
  linkUrl: "https://example.com/spring",
  imageUrl: "https://cdn.example.com/launch.mp4",
  callToAction: "SHOP_NOW",
  countries: ["US"],
  ageMin: 18,
  ageMax: 34,
  // Required for goal: "conversions" on TikTok. customEventType is optional.
  promotedObject: { pixelId: "7987654321098765432", customEventType: "ON_WEB_ORDER" },
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.create_standalone_ad(
    account_id="acc_tiktokads_123",
    ad_account_id="7123456789012345678",
    name="Spring launch - purchases",
    goal="conversions",
    budget_amount=100,
    budget_type="daily",
    body="Spring drop is live",
    link_url="https://example.com/spring",
    image_url="https://cdn.example.com/launch.mp4",
    call_to_action="SHOP_NOW",
    countries=["US"],
    age_min=18,
    age_max=34,
    promoted_object={"pixelId": "7987654321098765432", "customEventType": "ON_WEB_ORDER"},
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_tiktokads_123",
    "adAccountId": "7123456789012345678",
    "name": "Spring launch - purchases",
    "goal": "conversions",
    "budgetAmount": 100,
    "budgetType": "daily",
    "body": "Spring drop is live",
    "linkUrl": "https://example.com/spring",
    "imageUrl": "https://cdn.example.com/launch.mp4",
    "callToAction": "SHOP_NOW",
    "countries": ["US"],
    "ageMin": 18,
    "ageMax": 34,
    "promotedObject": { "pixelId": "7987654321098765432", "customEventType": "ON_WEB_ORDER" }
  }'
```
</Tab>
</Tabs>

<Callout type="info">
Already set up a conversion ad group in TikTok Ads Manager (with the pixel + event configured)? Pass its ID as `adSetId` on `POST /v1/ads/create` instead. The new creative inherits the pixel and `optimization_event` from the parent ad group, so `promotedObject` isn't needed. See [Attach to existing ad group](#attach-to-existing-ad-group).
</Callout>

## Custom Audiences

Create a customer-file Custom Audience and upload members. `adAccountId` is the TikTok advertiser ID. Email only (any `phone` is ignored); values are SHA256-hashed server-side.

TikTok needs the member file at creation time, so the audience is **created lazily on the first member upload**: `POST /v1/ads/audiences` records it with status `pending` (no platform ID yet), and the first `users` call provisions it on TikTok. Newly created audiences take up to 48 hours to finish processing before they're targetable.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// 1. Register the audience (status: pending until the first upload)
await zernio.adaudiences.createAdAudience({
  body: {
    accountId: 'acc_tiktokads_123',
    adAccountId: '7330955083452284929', // TikTok advertiser ID
    type: 'customer_list',
    name: 'Cart abandoners',
  },
});

// 2. Upload members — this provisions the audience on TikTok
await zernio.adaudiences.addUsersToAdAudience({
  path: { audienceId: 'aud_abc123' }, // id from the create response
  body: { users: [{ email: 'jane@example.com' }, { email: 'sam@example.com' }] },
});
```
</Tab>
<Tab value="Python">
```python
# 1. Register the audience (status: pending until the first upload)
client.ad_audiences.create_ad_audience(
    account_id="acc_tiktokads_123",
    ad_account_id="7330955083452284929",  # TikTok advertiser ID
    type="customer_list",
    name="Cart abandoners",
)

# 2. Upload members — this provisions the audience on TikTok
client.ad_audiences.add_users_to_ad_audience(
    audience_id="aud_abc123",  # id from the create response
    users=[{"email": "jane@example.com"}, {"email": "sam@example.com"}],
)
```
</Tab>
<Tab value="curl">
```bash
# 1. Register the audience (status: pending)
curl -X POST "https://zernio.com/api/v1/ads/audiences" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "accountId": "acc_tiktokads_123", "adAccountId": "7330955083452284929", "type": "customer_list", "name": "Cart abandoners" }'

# 2. Upload members — provisions the audience on TikTok (use the id from the create response)
curl -X POST "https://zernio.com/api/v1/ads/audiences/AUDIENCE_ID/users" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "users": [{ "email": "jane@example.com" }, { "email": "sam@example.com" }] }'
```
</Tab>
</Tabs>

## Media Requirements

| Type | Format | Max Size | Notes |
|------|--------|----------|-------|
| Video | MP4, MOV, MPEG | 500 MB | 9:16 vertical, 720p+, 5-60 sec |
| Image | JPEG, PNG | 30 MB | 1080x1920 for full-screen |

## Agency Business Centers

Connecting a TikTok account that owns one or more Business Centers automatically enumerates **every advertiser** under those BCs. There's no per-call cap — `GET /v1/ads/accounts` walks `/v2/bc/asset/get/` (paginated server-side) and returns the full roster. Solo advertisers without a BC fall back to the OAuth-time advertiser list (a single token can typically reach a handful of advertisers without BC).

The advertiser list is cached on your connection for **1 hour** and lazy-refreshed on the next call after expiry.

If you previously hit `502 Bad Gateway` with a "advertiser_ids: Length must be between 1 and 100" message on agency tokens, that's resolved — the lookup now chunks `/v2/advertiser/info/` calls underneath.

## Bid Strategy

Pass `bidStrategy` (cross-platform Meta enum) on `POST /v1/ads/boost`, `POST /v1/ads/create`, or `PUT /v1/ads/ad-sets/{adSetId}`. Zernio maps it to TikTok's `bid_type` / `bid_price` / `deep_bid_type` automatically:

| `bidStrategy` | Maps to TikTok | Required field |
|---|---|---|
| `LOWEST_COST_WITHOUT_CAP` (default) | `bid_type: BID_TYPE_NO_BID` | — |
| `LOWEST_COST_WITH_BID_CAP` | `bid_type: BID_TYPE_CUSTOM` + `bid_price` | `bidAmount` |
| `COST_CAP` | `bid_type: BID_TYPE_CUSTOM` + `bid_price` | `bidAmount` |
| `LOWEST_COST_WITH_MIN_ROAS` | `bid_type: BID_TYPE_NO_BID` + `deep_bid_type: MIN_ROAS` | `roasAverageFloor` (account must be value-optimization-enabled) |

`bidAmount` is in whole currency units of the ad account (USD: `5` = $5.00). On reads (`GET /v1/ads/tree`, `GET /v1/ads/campaigns`), TikTok's native `bid_type` is normalized back to the same Meta enum so cross-platform consumers see one shape regardless of source platform.

## Spark Code (cross-creator Spark Ads)

To boost a creator's organic video from a different TikTok account than the one running the ads, the creator generates a Spark Code in their TikTok app's Promote settings and shares it with the advertiser. Pass it on `POST /v1/ads/boost`:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.boostPost({
  body: {
    platformPostId: 'CREATORS_VIDEO_ID',
    accountId: 'ACCOUNT_ID',
    adAccountId: '7123456789012345678',
    name: 'Cross-creator boost',
    goal: 'traffic',
    budget: { amount: 50, type: 'daily' },
    linkUrl: 'https://example.com',
    callToAction: 'SHOP_NOW',
    sparkAuthCode: 'BCAQAAAA...',
  },
});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.boost_post(
    platform_post_id="CREATORS_VIDEO_ID",
    account_id="ACCOUNT_ID",
    ad_account_id="7123456789012345678",
    name="Cross-creator boost",
    goal="traffic",
    budget={"amount": 50, "type": "daily"},
    link_url="https://example.com",
    call_to_action="SHOP_NOW",
    spark_auth_code="BCAQAAAA...",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/boost" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platformPostId": "CREATORS_VIDEO_ID",
    "accountId": "ACCOUNT_ID",
    "adAccountId": "7123456789012345678",
    "name": "Cross-creator boost",
    "goal": "traffic",
    "budget": { "amount": 50, "type": "daily" },
    "linkUrl": "https://example.com",
    "callToAction": "SHOP_NOW",
    "sparkAuthCode": "BCAQAAAA..."
  }'
```
</Tab>
</Tabs>

Without `sparkAuthCode`, boosts are limited to videos owned by the same TikTok account that's running the ads. Maps to `auth_code` on TikTok's `AdcreateCreatives`.

## Attach to existing ad group

`POST /v1/ads/create` with `adSetId` set creates a new ad inside an existing TikTok ad group, skipping the campaign + ad-group create. Bid strategy, budget, targeting, and goal are inherited from the existing ad group. Use this when you've configured one ad group manually in TikTok Ads Manager and just want to add Zernio-managed creatives to it.

## Creative swap

`PUT /v1/ads/{adId}` accepts a `creative` object to replace the live creative on an existing TikTok ad. Patch-style — only fields you supply are touched. `headline` is ignored (no slot on TikTok); `body` becomes `ad_text`; `linkUrl` becomes `landing_page_url`; `videoUrl` triggers a fresh upload.

## Targeting update after creation

`PUT /v1/ads/{adId}` accepts `targeting` for TikTok ads — Zernio forwards it to `/v2/adgroup/update/` with the same field set as create. (Pinterest / X / LinkedIn / Google return 501; those platforms force re-creation for targeting changes.)

## Campaign duplication

`POST /v1/ads/campaigns/{campaignId}/duplicate` works on TikTok via a manual graph walk: Zernio reads the source campaign + ad groups + ads, then recreates each entity with their bid configuration, targeting, schedule, and creative fields preserved. Spark Ad linkage (`tiktok_item_id`) carries over. Everything is created paused so you can review before launching.

---

# TikTok

Schedule and automate TikTok posts with Zernio API - Videos, photo carousels, privacy settings, and AI disclosure

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Reference

| Property | Value |
|----------|-------|
| Character limit | 2,200 (video caption), 4,000 (photo desc) |
| Photo title | 90 chars (auto-truncated, hashtags stripped) |
| Photos per post | 35 (carousel) |
| Videos per post | 1 |
| Photo formats | JPEG, PNG, WebP |
| Photo max size | 20 MB |
| Video formats | MP4, MOV, WebM |
| Video max size | 4 GB |
| Video duration | 3 sec - 10 min |
| Post types | Video, Photo Carousel |
| Scheduling | Yes |
| Inbox (Comments) | No |
| Inbox (DMs) | No |
| Analytics | Limited |

## Before You Start

<Callout type="warn">
TikTok has a strict daily posting limit for posts created via third-party APIs. This limit is separate from the native app and is account-specific. When you hit it, the only options are to wait or post directly in TikTok. Also: the privacy levels available via API depend on each creator's TikTok account settings. You must fetch the creator's allowed levels and only use those, or the post will fail.

Additional requirements:
- Each creator has account-specific privacy level options
- Content moderation is more aggressive via API than native app
- All posts require consent flags (legal requirement from TikTok)
- No text-only posts (media required)
</Callout>

## Quick Start

Post a video to TikTok in under 60 seconds:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Check out this amazing sunset! #sunset #nature',
  mediaItems: [
    { type: 'video', url: 'https://cdn.example.com/sunset-video.mp4' }
  ],
  platforms: [
    { platform: 'tiktok', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  tiktokSettings: {
    privacy_level: 'PUBLIC_TO_EVERYONE',
    allow_comment: true,
    allow_duet: true,
    allow_stitch: true,
    content_preview_confirmed: true,
    express_consent_given: true
  },
  publishNow: true
});
console.log('Posted to TikTok!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Check out this amazing sunset! #sunset #nature",
    media_items=[
        {"type": "video", "url": "https://cdn.example.com/sunset-video.mp4"}
    ],
    platforms=[
        {"platform": "tiktok", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    tiktok_settings={
        "privacy_level": "PUBLIC_TO_EVERYONE",
        "allow_comment": True,
        "allow_duet": True,
        "allow_stitch": True,
        "content_preview_confirmed": True,
        "express_consent_given": True
    },
    publish_now=True
)
post = result.post
print(f"Posted to TikTok! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out this amazing sunset! #sunset #nature",
    "mediaItems": [
      {"type": "video", "url": "https://cdn.example.com/sunset-video.mp4"}
    ],
    "platforms": [
      {"platform": "tiktok", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "tiktokSettings": {
      "privacy_level": "PUBLIC_TO_EVERYONE",
      "allow_comment": true,
      "allow_duet": true,
      "allow_stitch": true,
      "content_preview_confirmed": true,
      "express_consent_given": true
    },
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

### Video Post

A single video post. Videos must be between 3 seconds and 10 minutes long. Vertical 9:16 aspect ratio is the only format that works well on TikTok.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'New cooking tutorial #recipe #foodtok',
  mediaItems: [
    { type: 'video', url: 'https://cdn.example.com/cooking-tutorial.mp4' }
  ],
  platforms: [
    { platform: 'tiktok', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  tiktokSettings: {
    privacy_level: 'PUBLIC_TO_EVERYONE',
    allow_comment: true,
    allow_duet: true,
    allow_stitch: true,
    video_cover_timestamp_ms: 3000,
    content_preview_confirmed: true,
    express_consent_given: true
  },
  publishNow: true
});
console.log('Video posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="New cooking tutorial #recipe #foodtok",
    media_items=[
        {"type": "video", "url": "https://cdn.example.com/cooking-tutorial.mp4"}
    ],
    platforms=[
        {"platform": "tiktok", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    tiktok_settings={
        "privacy_level": "PUBLIC_TO_EVERYONE",
        "allow_comment": True,
        "allow_duet": True,
        "allow_stitch": True,
        "video_cover_timestamp_ms": 3000,
        "content_preview_confirmed": True,
        "express_consent_given": True
    },
    publish_now=True
)
post = result.post
print(f"Video posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New cooking tutorial #recipe #foodtok",
    "mediaItems": [
      {"type": "video", "url": "https://cdn.example.com/cooking-tutorial.mp4"}
    ],
    "platforms": [
      {"platform": "tiktok", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "tiktokSettings": {
      "privacy_level": "PUBLIC_TO_EVERYONE",
      "allow_comment": true,
      "allow_duet": true,
      "allow_stitch": true,
      "video_cover_timestamp_ms": 3000,
      "content_preview_confirmed": true,
      "express_consent_given": true
    },
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Custom Video Thumbnail

For video posts, you can set a custom cover image using `video_cover_image_url`. When provided, it overrides `video_cover_timestamp_ms`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'New product teaser #launch',
  mediaItems: [
    { type: 'video', url: 'https://cdn.example.com/teaser.mp4' }
  ],
  platforms: [
    { platform: 'tiktok', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  tiktokSettings: {
    privacy_level: 'PUBLIC_TO_EVERYONE',
    allow_comment: true,
    allow_duet: true,
    allow_stitch: true,
    video_cover_image_url: 'https://cdn.example.com/teaser-cover.jpg',
    content_preview_confirmed: true,
    express_consent_given: true
  },
  publishNow: true
});
console.log('Video posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="New product teaser #launch",
    media_items=[
        {"type": "video", "url": "https://cdn.example.com/teaser.mp4"}
    ],
    platforms=[
        {"platform": "tiktok", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    tiktok_settings={
        "privacy_level": "PUBLIC_TO_EVERYONE",
        "allow_comment": True,
        "allow_duet": True,
        "allow_stitch": True,
        "video_cover_image_url": "https://cdn.example.com/teaser-cover.jpg",
        "content_preview_confirmed": True,
        "express_consent_given": True
    },
    publish_now=True
)
post = result.post
print(f"Video posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New product teaser #launch",
    "mediaItems": [
      {"type": "video", "url": "https://cdn.example.com/teaser.mp4"}
    ],
    "platforms": [
      {"platform": "tiktok", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "tiktokSettings": {
      "privacy_level": "PUBLIC_TO_EVERYONE",
      "allow_comment": true,
      "allow_duet": true,
      "allow_stitch": true,
      "video_cover_image_url": "https://cdn.example.com/teaser-cover.jpg",
      "content_preview_confirmed": true,
      "express_consent_given": true
    },
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Photo Carousel

Up to 35 images in a single post. Photos are auto-resized to 1080x1920. The `content` field becomes the photo title (90 chars max, hashtags and URLs are auto-stripped). Use the `description` field inside `tiktokSettings` for a full caption up to 4,000 characters.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'My travel highlights',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/photo1.jpg' },
    { type: 'image', url: 'https://cdn.example.com/photo2.jpg' },
    { type: 'image', url: 'https://cdn.example.com/photo3.jpg' }
  ],
  platforms: [
    { platform: 'tiktok', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  tiktokSettings: {
    privacy_level: 'PUBLIC_TO_EVERYONE',
    allow_comment: true,
    media_type: 'photo',
    photo_cover_index: 0,
    description: 'Full trip recap from our weekend adventure across the coast. These are the best moments we captured along the way! #travel #roadtrip #adventure',
    auto_add_music: true,
    content_preview_confirmed: true,
    express_consent_given: true
  },
  publishNow: true
});
console.log('Photo carousel posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="My travel highlights",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/photo1.jpg"},
        {"type": "image", "url": "https://cdn.example.com/photo2.jpg"},
        {"type": "image", "url": "https://cdn.example.com/photo3.jpg"}
    ],
    platforms=[
        {"platform": "tiktok", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    tiktok_settings={
        "privacy_level": "PUBLIC_TO_EVERYONE",
        "allow_comment": True,
        "media_type": "photo",
        "photo_cover_index": 0,
        "description": "Full trip recap from our weekend adventure across the coast. These are the best moments we captured along the way! #travel #roadtrip #adventure",
        "auto_add_music": True,
        "content_preview_confirmed": True,
        "express_consent_given": True
    },
    publish_now=True
)
post = result.post
print(f"Photo carousel posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "My travel highlights",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/photo1.jpg"},
      {"type": "image", "url": "https://cdn.example.com/photo2.jpg"},
      {"type": "image", "url": "https://cdn.example.com/photo3.jpg"}
    ],
    "platforms": [
      {"platform": "tiktok", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "tiktokSettings": {
      "privacy_level": "PUBLIC_TO_EVERYONE",
      "allow_comment": true,
      "media_type": "photo",
      "photo_cover_index": 0,
      "description": "Full trip recap from our weekend adventure across the coast. These are the best moments we captured along the way! #travel #roadtrip #adventure",
      "auto_add_music": true,
      "content_preview_confirmed": true,
      "express_consent_given": true
    },
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Media Requirements

### Images

| Property | Requirement |
|----------|-------------|
| **Max photos** | 35 per carousel |
| **Formats** | JPEG, PNG, WebP |
| **Max file size** | 20 MB per image |
| **Aspect ratio** | 9:16 recommended |
| **Resolution** | Auto-resized to 1080 x 1920 px |

### Videos

| Property | Requirement |
|----------|-------------|
| **Max videos** | 1 per post |
| **Formats** | MP4, MOV, WebM |
| **Max file size** | 4 GB |
| **Max duration** | 10 minutes |
| **Min duration** | 3 seconds |
| **Aspect ratio** | 9:16 vertical (only format that works well) |
| **Resolution** | 1080 x 1920 px recommended |
| **Codec** | H.264 |
| **Frame rate** | 30 fps recommended |

You cannot mix photos and videos in the same post. Use either all photos (carousel) or one video.

## Platform-Specific Fields

TikTok settings go in `tiktokSettings` at the **top level** of the request body, not inside `platformSpecificData`. This is a special case unique to TikTok.

## TikTok Creator Info

Use this endpoint to fetch the creator's allowed `privacyLevels`, current `postingLimits` (including interaction defaults), and available `commercialContentTypes` before creating a post.

> **Note:** This endpoint only works for TikTok accounts. If you pass a non-TikTok `accountId`, you'll get a 400 error.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/tiktok/creator-info?mediaType=video" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
<Tab value="JavaScript">
```typescript
const info = await zernio.accounts.getTikTokCreatorInfo({
  accountId: 'YOUR_ACCOUNT_ID',
  mediaType: 'video'
});

console.log(info.creator);
console.log(info.privacyLevels);
console.log(info.postingLimits);
console.log(info.commercialContentTypes);
```
</Tab>
<Tab value="Python">
```python
info = client.accounts.get_tik_tok_creator_info(
    account_id="YOUR_ACCOUNT_ID",
    media_type="video"
)

print(info["creator"])
print(info["privacyLevels"])
print(info["postingLimits"])
print(info["commercialContentTypes"])
```
</Tab>
</Tabs>

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `privacy_level` | string | Yes | Must match creator's allowed values. Options: `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY` |
| `allow_comment` | boolean | Yes | Enable or disable comments on the post |
| `allow_duet` | boolean | Yes (videos) | Enable or disable duets. Only applies to video posts. |
| `allow_stitch` | boolean | Yes (videos) | Enable or disable stitches. Only applies to video posts. |
| `content_preview_confirmed` | boolean | Yes | Must be `true`. Legal requirement from TikTok. |
| `express_consent_given` | boolean | Yes | Must be `true`. Legal requirement from TikTok. |
| `video_cover_timestamp_ms` | number | No | Thumbnail frame position in milliseconds. Default: `1000`. Ignored when `video_cover_image_url` is provided. |
| `video_cover_image_url` | string | No | Custom thumbnail image URL (JPG, PNG, or WebP, max 20MB). Overrides `video_cover_timestamp_ms`. |
| `media_type` | `"photo"` | No | Set to `"photo"` for photo carousels. |
| `photo_cover_index` | number | No | Which image to use as cover (0-indexed). |
| `description` | string | No | Long-form caption for photo carousels, up to 4,000 characters. |
| `auto_add_music` | boolean | No | Let TikTok add recommended music. Photo carousels only. |
| `video_made_with_ai` | boolean | No | AI-generated content disclosure flag. |
| `draft` | boolean | No | Send to Creator Inbox for review instead of publishing. |
| `commercialContentType` | string | No | `"none"`, `"brand_organic"`, or `"brand_content"`. |

### Photo Carousel Caption Behavior

The `content` field and `description` field serve different purposes for photo carousels:

- **`content`** (top-level) -- becomes the photo **title**. Limited to 90 characters. Hashtags and URLs are auto-stripped.
- **`description`** (inside `tiktokSettings`) -- becomes the full **caption** shown below the carousel. Up to 4,000 characters.

## Media URL Requirements

<Callout type="error">
**These do not work as media URLs:**
- **Google Drive** -- returns an HTML download page, not the file
- **Dropbox** -- returns an HTML preview page
- **OneDrive / SharePoint** -- returns HTML
- **iCloud** -- returns HTML

Test your URL in an incognito browser window. If you see a webpage instead of the raw video or image, it will not work.
</Callout>

Media URLs must be:
- Publicly accessible (no authentication required)
- Returning actual media bytes with the correct `Content-Type` header
- Not behind redirects that resolve to HTML pages
- Hosted on a fast, reliable CDN

Large videos are auto-chunked during upload (5-64 MB per chunk). Photos are auto-resized to 1080x1920.

## Analytics

> **Included** — Analytics is bundled with every paid account on the [Usage plan](/pricing).

Available metrics via the [Analytics API](/analytics/get-analytics):

| Metric | Available |
|--------|-----------|
| Likes | ✅ |
| Comments | ✅ |
| Shares | ✅ |
| Views | ✅ |

TikTok also provides a dedicated [Account Insights API](/analytics/get-tiktok-account-insights) for account-level counters (follower_count, following_count, likes_count, video_count) plus Zernio-synthesized followers_gained and followers_lost deltas. Live values come from TikTok's user.info.stats scope; historical time series is joined from Zernio's daily snapshotter.

Deep metrics from TikTok Studio (profile views, account-level impressions and reach, per-video watch time and average watch time, full-watched rate, impression sources like FYP / Following / Hashtag / Search) are not available on any TikTok public API. TikTok's Research API does not expose these either and is restricted to non-commercial academic use per TikTok's eligibility policy. There is no public API workaround.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const analytics = await zernio.analytics.getAnalytics({
  platform: 'tiktok',
  fromDate: '2024-01-01',
  toDate: '2024-01-31'
});
console.log(analytics.posts);
```
</Tab>
<Tab value="Python">
```python
analytics = client.analytics.get_analytics(
    platform="tiktok",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(analytics["posts"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics?platform=tiktok&fromDate=2024-01-01&toDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

## What You Can't Do

These features are not available through TikTok's API:

- Use TikTok's sound/music library (except `auto_add_music` for photo carousels)
- Create duets or stitches
- Go Live
- Add effects or filters
- Edit posts after publishing
- View For You Page analytics
- Create playlists
- Read or write comments
- Send or read DMs
- Create text-only posts (media required)

## Common Errors

TikTok has a **13.1% failure rate** across Zernio's platform (30,746 failures out of 235,045 attempts). Here are the most frequent errors and how to fix them:

| Error | Meaning | Fix |
|-------|---------|-----|
| "You have created too many posts in the last 24 hours via the API." | TikTok's daily API posting limit hit | Wait until limit resets (24h rolling) or post directly in TikTok app. |
| "Publishing failed during platform API call (timeout waiting for platform response)" | TikTok's servers took too long to process | For large videos this can be normal. Check post status after a few minutes. |
| "Selected privacy level 'X' is not available for this creator. Available options: ..." | Privacy level does not match creator's account settings | Fetch creator info to get allowed privacy levels and use one of those. |
| "TikTok flagged this post as potentially risky (spam_risk)" | Content moderation flagged the post | Review content. TikTok's API moderation is stricter than the native app. |
| "Duplicate content detected." | Same content was already posted recently | Modify the caption or media before retrying. |
| "TikTok video upload failed: Your video URL returned an error (download failed)" | TikTok could not download the video from the URL | Ensure the URL is a direct download link, not a cloud storage sharing page. |
| "Missing required TikTok permissions. Please reconnect with all required scopes." | OAuth token is missing required scopes | Reconnect the TikTok account with all required permissions. |

## Inbox

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

TikTok has no inbox support.

### Comments

| Feature | Supported |
|---------|-----------|
| List comments on posts | ❌ |
| Post new comment | ❌ |
| Reply to comments | ❌ |
| Delete comments | ❌ |

### Limitations

- **No comments support** - Zernio does not currently support TikTok comments
- **No DMs** - Zernio does not currently support TikTok DMs

## Related Endpoints

- [Connect TikTok Account](/guides/connecting-accounts) - OAuth flow
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Image and video uploads
- [Analytics](/analytics/get-analytics) - Performance metrics
- [Comments](/comments/list-inbox-comments) - Comments API Reference

---

# X Ads

Create campaigns and promote tweets via Zernio API - OAuth 1.0a and approval handled for you

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

<Callout type="info">
**Included with the [Usage plan](/pricing).** No X Ads API approval application needed. OAuth 1.0a request signing is handled server-side.
</Callout>

<Callout type="info">
**`accountId` accepts either shape.** Pass the posting X/Twitter account ID or the X Ads credential account ID, Zernio resolves the sibling internally so either value works. If no X Ads credential is connected for the resolved profile, the API returns `code: "ads_connection_required"`.
</Callout>

## What's Supported

| Feature | Status |
|---------|--------|
| Standalone campaigns (Campaign > Line Item > Promoted Tweet) | Yes |
| Promote existing tweets | Yes |
| Location + language targeting | Yes |
| Real-time analytics (spend, CPE, CPM, link clicks) | Yes |
| OAuth 1.0a signing handled | Yes |
| Keyword targeting | Roadmap |
| Follower look-alike targeting | Roadmap |
| Tailored Audiences (read, create, member upload) | Yes |

## Promote an Existing Tweet

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.boostPost({ body: {
  postId: "POST_ID",
  accountId: "ACCOUNT_ID",
  adAccountId: "18ce54d4x5t",
  name: "Boost launch tweet",
  goal: "engagement",
  budget: { amount: 50, type: "daily" },
  schedule: { startDate: "2026-04-20", endDate: "2026-04-27" },
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.boost_post(
    post_id="POST_ID",
    account_id="ACCOUNT_ID",
    ad_account_id="18ce54d4x5t",
    name="Boost launch tweet",
    goal="engagement",
    budget={"amount": 50, "type": "daily"},
    schedule={"startDate": "2026-04-20", "endDate": "2026-04-27"},
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/boost" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postId": "POST_ID",
    "accountId": "ACCOUNT_ID",
    "adAccountId": "18ce54d4x5t",
    "name": "Boost launch tweet",
    "goal": "engagement",
    "budget": { "amount": 50, "type": "daily" },
    "schedule": { "startDate": "2026-04-20", "endDate": "2026-04-27" }
  }'
```
</Tab>
</Tabs>

## Create a Standalone Campaign

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.createStandaloneAd({ body: {
  accountId: "acc_xads_123",
  adAccountId: "18ce54d4x5t",
  name: "Q2 Product Awareness",
  goal: "awareness",
  budgetAmount: 75,
  budgetType: "daily",
  body: "Ship faster with platform engineering done right.",
  linkUrl: "https://example.com/platform",
  countries: ["US"],
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.create_standalone_ad(
    account_id="acc_xads_123",
    ad_account_id="18ce54d4x5t",
    name="Q2 Product Awareness",
    goal="awareness",
    budget_amount=75,
    budget_type="daily",
    body="Ship faster with platform engineering done right.",
    link_url="https://example.com/platform",
    countries=["US"],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_xads_123",
    "adAccountId": "18ce54d4x5t",
    "name": "Q2 Product Awareness",
    "goal": "awareness",
    "budgetAmount": 75,
    "budgetType": "daily",
    "body": "Ship faster with platform engineering done right.",
    "linkUrl": "https://example.com/platform",
    "countries": ["US"]
  }'
```
</Tab>
</Tabs>

<Callout type="info">
For X, `body` is the tweet text (max 280 chars; X shortens `linkUrl` to ~24 chars against that limit). `headline`, `imageUrl`, and `callToAction` are ignored on X. Valid `goal` values: `engagement`, `traffic`, `awareness`, `video_views`, `app_promotion`.
</Callout>

## OAuth 1.0a

The X Ads API uses OAuth 1.0a request signing (not OAuth 2.0 Bearer tokens). Zernio computes HMAC-SHA1 signatures server-side, so your integration uses a standard Bearer token like every other platform.

## Tailored Audiences

Create a Tailored (custom) Audience and upload members. `adAccountId` is the X Ads account ID. Email only (any `phone` is ignored); values are SHA256-hashed server-side. An audience must match at least 100 recently-active users before X will let you target it, so the size stays `0`/`-` until then.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// 1. Create the (empty) tailored audience
await zernio.adaudiences.createAdAudience({
  body: {
    accountId: 'acc_xads_123',
    adAccountId: '18ce55abc12', // X Ads account ID
    type: 'customer_list',
    name: 'Trial signups',
  },
});

// 2. Upload members to the returned audience id
await zernio.adaudiences.addUsersToAdAudience({
  path: { audienceId: 'aud_abc123' }, // id from the create response
  body: { users: [{ email: 'jane@example.com' }, { email: 'sam@example.com' }] },
});
```
</Tab>
<Tab value="Python">
```python
# 1. Create the (empty) tailored audience
client.ad_audiences.create_ad_audience(
    account_id="acc_xads_123",
    ad_account_id="18ce55abc12",  # X Ads account ID
    type="customer_list",
    name="Trial signups",
)

# 2. Upload members to the returned audience id
client.ad_audiences.add_users_to_ad_audience(
    audience_id="aud_abc123",  # id from the create response
    users=[{"email": "jane@example.com"}, {"email": "sam@example.com"}],
)
```
</Tab>
<Tab value="curl">
```bash
# 1. Create
curl -X POST "https://zernio.com/api/v1/ads/audiences" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "accountId": "acc_xads_123", "adAccountId": "18ce55abc12", "type": "customer_list", "name": "Trial signups" }'

# 2. Upload members (use the audience id from the create response)
curl -X POST "https://zernio.com/api/v1/ads/audiences/AUDIENCE_ID/users" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "users": [{ "email": "jane@example.com" }, { "email": "sam@example.com" }] }'
```
</Tab>
</Tabs>

## Media Requirements

| Type | Format | Max Size | Notes |
|------|--------|----------|-------|
| Image | JPEG, PNG, GIF, WebP | 5 MB | 1200x675 (16:9) recommended |
| Video | MP4, MOV | 1 GB | 0.5-140 sec, H.264+AAC |
| Tweet text | UTF-8 | 280 chars | Standard limit |
| Website Card | URL + text | 70 char title | Landing page card |

---

# YouTube

Schedule and automate YouTube video uploads with Zernio API - Videos, Shorts, thumbnails, visibility, and COPPA settings

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Reference

| Property | Value |
|----------|-------|
| Title limit | 100 characters |
| Description limit | 5,000 characters |
| Tags limit | 500 characters total (all tags combined) |
| Videos per post | 1 |
| Video formats | MP4, MOV, AVI, WMV, FLV, 3GP, WebM |
| Video max size | 256 GB |
| Video max duration | 15 min (unverified), 12 hours (verified) |
| Thumbnail formats | JPEG, PNG, GIF |
| Thumbnail max size | 2 MB |
| Post types | Video, Shorts |
| Scheduling | Yes (uploads as private, goes public at scheduled time) |
| Inbox (Comments) | Yes |
| Inbox (DMs) | No (YouTube has no DM system) |
| Analytics | Yes |

## Before You Start

<Callout type="warn">
YouTube is video-only. Every post requires exactly one video file. Unverified channels are limited to 15-minute videos -- verify your channel via phone number to unlock longer uploads. If a YouTube channel is suspended, ALL uploads fail with a 403 error. Use the account health endpoint to check status before scheduling posts.
</Callout>

- One video per post (no image-only or text-only posts)
- Unverified channels have a 15-minute maximum video duration
- YouTube has daily upload quotas that vary by channel
- Shorts are auto-detected from duration and aspect ratio (not a separate post type)

## Quick Start

Upload a video to YouTube:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Video description here',
  mediaItems: [
    { type: 'video', url: 'https://example.com/video.mp4' }
  ],
  platforms: [{
    platform: 'youtube',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      title: 'My Video Title',
      visibility: 'public'
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Video description here",
    media_items=[
        {"type": "video", "url": "https://example.com/video.mp4"}
    ],
    platforms=[{
        "platform": "youtube",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "title": "My Video Title",
            "visibility": "public"
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Video description here",
    "mediaItems": [
      {"type": "video", "url": "https://example.com/video.mp4"}
    ],
    "platforms": [{
      "platform": "youtube",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "title": "My Video Title",
        "visibility": "public"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

### Regular Videos

Long-form content with a duration greater than 3 minutes or a horizontal aspect ratio. Regular videos support custom thumbnails and 16:9 is the recommended aspect ratio.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'In this tutorial, I walk through building a REST API from scratch.\n\n#programming #tutorial',
  mediaItems: [{
    type: 'video',
    url: 'https://example.com/long-form-video.mp4',
    thumbnail: 'https://example.com/thumbnail.jpg'
  }],
  platforms: [{
    platform: 'youtube',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      title: 'Build a REST API from Scratch',
      visibility: 'public',
      categoryId: '27',
      madeForKids: false
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="In this tutorial, I walk through building a REST API from scratch.\n\n#programming #tutorial",
    media_items=[{
        "type": "video",
        "url": "https://example.com/long-form-video.mp4",
        "thumbnail": "https://example.com/thumbnail.jpg"
    }],
    platforms=[{
        "platform": "youtube",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "title": "Build a REST API from Scratch",
            "visibility": "public",
            "categoryId": "27",
            "madeForKids": False
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "In this tutorial, I walk through building a REST API from scratch.\n\n#programming #tutorial",
    "mediaItems": [{
      "type": "video",
      "url": "https://example.com/long-form-video.mp4",
      "thumbnail": "https://example.com/thumbnail.jpg"
    }],
    "platforms": [{
      "platform": "youtube",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "title": "Build a REST API from Scratch",
        "visibility": "public",
        "categoryId": "27",
        "madeForKids": false
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### YouTube Shorts

YouTube automatically detects Shorts based on duration and aspect ratio. A video that is 3 minutes or shorter AND has a vertical (9:16) aspect ratio is classified as a Short. There is no separate post type or flag to set -- just upload a short vertical video and YouTube handles the rest.

- Videos under 15 seconds loop automatically
- Custom thumbnails are **not** supported for Shorts via the API
- No code changes are needed compared to regular videos; the detection is entirely automatic

## Media Requirements

### Video Requirements

| Property | Shorts | Regular Video |
|----------|--------|---------------|
| **Max Duration** | 3 minutes | 12 hours (verified), 15 min (unverified) |
| **Min Duration** | 1 second | 1 second |
| **Max File Size** | 256 GB | 256 GB |
| **Formats** | MP4, MOV, AVI, WMV, FLV, 3GP, WebM | MP4, MOV, AVI, WMV, FLV, 3GP, WebM |
| **Aspect Ratio** | 9:16 (vertical) | 16:9 (horizontal) |
| **Resolution** | 1080 x 1920 px | 1920 x 1080 px (1080p) |

### Recommended Specs

| Property | Shorts | Regular Video |
|----------|--------|---------------|
| Resolution | 1080 x 1920 px | 3840 x 2160 px (4K) |
| Frame Rate | 30 fps | 24-60 fps |
| Codec | H.264 | H.264 or H.265 |
| Audio | AAC, 128 kbps | AAC, 384 kbps |
| Bitrate | 10 Mbps | 35-68 Mbps (4K) |

### Custom Thumbnails

Custom thumbnails are supported for regular videos only (not Shorts).

| Property | Requirement |
|----------|-------------|
| Format | JPEG, PNG, GIF |
| Max Size | 2 MB |
| Recommended Resolution | 1280 x 720 px (16:9) |
| Min Width | 640 px |

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'My Video Description',
  mediaItems: [{
    type: 'video',
    url: 'https://example.com/video.mp4',
    thumbnail: 'https://example.com/thumbnail.jpg'
  }],
  platforms: [{
    platform: 'youtube',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      title: 'My Video Title',
      visibility: 'public'
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="My Video Description",
    media_items=[{
        "type": "video",
        "url": "https://example.com/video.mp4",
        "thumbnail": "https://example.com/thumbnail.jpg"
    }],
    platforms=[{
        "platform": "youtube",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "title": "My Video Title",
            "visibility": "public"
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "My Video Description",
    "mediaItems": [{
      "type": "video",
      "url": "https://example.com/video.mp4",
      "thumbnail": "https://example.com/thumbnail.jpg"
    }],
    "platforms": [{
      "platform": "youtube",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "title": "My Video Title",
        "visibility": "public"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Platform-Specific Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `title` | string | First line of `content`, or `"Untitled Video"` | Video title. Maximum 100 characters. |
| `visibility` | `"public"` \| `"private"` \| `"unlisted"` | `"public"` | Controls who can see the video. |
| `madeForKids` | boolean | `false` | COPPA compliance flag. Setting to `true` **permanently** disables comments, notification bell, personalized ads, end screens, and cards on the video. COPPA violations carry fines of $42,000 or more. |
| `containsSyntheticMedia` | boolean | `false` | AI-generated content disclosure. YouTube is increasingly enforcing this requirement. |
| `categoryId` | string | `"22"` (People & Blogs) | Video category. Common values: `"1"` Film, `"10"` Music, `"20"` Gaming, `"22"` People & Blogs, `"27"` Education, `"28"` Science & Technology. |
| `playlistId` | string | -- | Optional YouTube playlist ID to add the video to after upload (e.g. `"PLxxxxxxxxxxxxx"`). Use `GET /v1/accounts/{accountId}/youtube-playlists` to list available playlists. |
| `firstComment` | string | -- | Auto-posted and pinned comment. Maximum 10,000 characters. For `publishNow`: posted immediately. For scheduled posts: posted when the video goes live. |

## YouTube Playlists

Use playlists to automatically add an uploaded video to a specific YouTube playlist.

> **Note:** `playlistId` is optional. If omitted, the video is uploaded normally and is not added to any playlist.

### 1) List available playlists

Fetch playlists for a connected YouTube account to get a `playlistId`.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/youtube-playlists" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
<Tab value="JavaScript">
```typescript
const result = await zernio.request({
  method: 'GET',
  path: `/v1/accounts/${accountId}/youtube-playlists`
});

console.log(result.playlists);
```
</Tab>
<Tab value="Python">
```python
result = client.request(
    method="GET",
    path=f"/v1/accounts/{account_id}/youtube-playlists"
)

print(result["playlists"])
```
</Tab>
</Tabs>

### 2) Create a post with `playlistId`

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Video description here",
    "mediaItems": [
      {"type": "video", "url": "https://example.com/video.mp4"}
    ],
    "platforms": [{
      "platform": "youtube",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "title": "My Video Title",
        "visibility": "public",
        "playlistId": "PLxxxxxxxxxxxxx"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Video description here',
  mediaItems: [
    { type: 'video', url: 'https://example.com/video.mp4' }
  ],
  platforms: [{
    platform: 'youtube',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      title: 'My Video Title',
      visibility: 'public',
      playlistId: 'PLxxxxxxxxxxxxx'
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Video description here",
    media_items=[
        {"type": "video", "url": "https://example.com/video.mp4"}
    ],
    platforms=[{
        "platform": "youtube",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "title": "My Video Title",
            "visibility": "public",
            "playlistId": "PLxxxxxxxxxxxxx"
        }
    }],
    publish_now=True
)
```
</Tab>
</Tabs>

### 3) (Optional) Store a default playlist (client-side convenience)

You can store a default playlist for an account to prefill UI selections. This does not automatically apply to posts that omit `playlistId`.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X PUT https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/youtube-playlists \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultPlaylistId": "PLxxxxxxxxxxxxx",
    "defaultPlaylistName": "Tutorials"
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const result = await zernio.request({
  method: 'PUT',
  path: `/v1/accounts/${accountId}/youtube-playlists`,
  body: {
    defaultPlaylistId: 'PLxxxxxxxxxxxxx',
    defaultPlaylistName: 'Tutorials'
  }
});

console.log(result.success);
```
</Tab>
<Tab value="Python">
```python
result = client.request(
    method="PUT",
    path=f"/v1/accounts/{account_id}/youtube-playlists",
    body={
        "defaultPlaylistId": "PLxxxxxxxxxxxxx",
        "defaultPlaylistName": "Tutorials"
    }
)

print(result["success"])
```
</Tab>
</Tabs>

### Scheduling Behavior

When you schedule a YouTube video for a future time, the following sequence occurs:

1. The video uploads **immediately** as `"private"` regardless of your target visibility
2. A video URL exists right away, but the video is not publicly accessible
3. At the scheduled time, visibility changes to your target setting (usually `"public"`)
4. The `firstComment` is posted at the scheduled time, not at upload time

## Media URL Requirements

- The URL must return actual video bytes (not an HTML page)
- No authentication or expired links -- the URL must be publicly accessible
- Large videos (1 GB or more) can take 30-60+ minutes to process on YouTube's side
- During processing, the video shows a "processing" state -- do not retry the upload

## Analytics

> **Included** — Analytics is bundled with every paid account on the [Usage plan](/pricing).

Available metrics via the [Analytics API](/analytics/get-analytics):

| Metric | Available |
|--------|-----------|
| Likes | ✅ |
| Comments | ✅ |
| Shares | ✅ (via Daily Views only) |
| Views | ✅ |

YouTube also provides a dedicated [Daily Views API](/analytics/get-youtube-daily-views) with detailed daily breakdowns including watch time, subscriber changes, and per-day likes/comments/shares. Data has a 2-3 day delay.

For channel-level aggregates (views, watch time, average view duration, subscribers gained/lost) without looping through every video, see the [Channel Insights API](/analytics/get-youtube-channel-insights). Impressions and impressions click-through rate (the thumbnail metrics from YouTube Studio) are not exposed by YouTube's Analytics API v2 for any principal type; the only way to get those is manual Studio CSV export.

The [Demographics API](/analytics/get-youtube-demographics) returns audience breakdowns by age, gender, and country. Age and gender values are viewer percentages (0-100), country values are view counts. Data is based on signed-in viewers only, with a 2-3 day delay.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const analytics = await zernio.analytics.getAnalytics({
  platform: 'youtube',
  fromDate: '2024-01-01',
  toDate: '2024-01-31'
});
console.log(analytics.posts);
```
</Tab>
<Tab value="Python">
```python
analytics = client.analytics.get_analytics(
    platform="youtube",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(analytics["posts"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics?platform=youtube&fromDate=2024-01-01&toDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

## What You Can't Do

- Create Community posts
- Go Live or schedule Premieres
- Add end screens, cards, or chapters (timestamps in the description do work)
- Manage monetization settings
- Create or delete playlists (you can list playlists and add videos to an existing playlist)
- Like or dislike videos
- Upload captions or subtitles

## Common Errors

| Error | Meaning | Fix |
|-------|---------|-----|
| `"The YouTube account of the authenticated user is suspended."` (403) | YouTube channel is suspended by YouTube | Check channel status on YouTube. Use the account health endpoint. |
| `"Social account not found"` | Connected account was disconnected or deleted from Zernio | Reconnect the YouTube account. Subscribe to the `account.disconnected` webhook. |
| `"Account was deleted"` | User deleted the social account | Reconnect the account. |
| `"Failed to fetch video from URL: 404"` | Video URL returned a 404 | Verify the URL is still valid and publicly accessible. Links expire on some hosting services. |
| `"YouTube permission error: Ensure the channel has required scopes and features enabled."` | Missing OAuth scopes | Reconnect the YouTube account with all required permissions. |
| `"YouTube upload initialization failed: 403"` | Upload rejected before file transfer began | Check whether the channel is suspended, the upload quota has been hit, or permissions are missing. |

## Inbox

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

YouTube supports comments only (no DMs available on the platform).

### Comments

| Feature | Supported |
|---------|-----------|
| List comments on videos | ✅ |
| Reply to comments | ✅ |
| Delete comments | ✅ |
| Like comments | ❌ (no API available) |

### Limitations

- **No DMs** - YouTube does not have a direct messaging system
- **No comment likes** - No public API endpoint available for liking comments

See [Comments API Reference](/comments/list-inbox-comments) for endpoint details.

## Related Endpoints

- [Connect YouTube Account](/guides/connecting-accounts) - OAuth flow
- [List YouTube Playlists](/connect/get-youtube-playlists) - Get playlist IDs for `playlistId`
- [Set Default YouTube Playlist](/connect/update-youtube-default-playlist) - Store a default playlist selection
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Video uploads
- [Analytics](/analytics/get-analytics) - Performance metrics
- [YouTube Daily Views](/analytics/get-youtube-daily-views) - Daily view statistics
- [YouTube Demographics](/analytics/get-youtube-demographics) - Audience age, gender, and country breakdowns
- [Comments](/comments/list-inbox-comments) - Read and reply to comments

---

# Open Source

Open-source projects and OpenAPI specifications built with and for the Zernio API

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

## Projects

<Cards>
  <Card
    icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>}
    title="Latewiz"
    description="Your social media scheduling wizard - Open source scheduler powered by Zernio API"
    href="https://github.com/zernio-dev/latewiz"
  />
  <Card
    icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>}
    title="Zernflow"
    description="Open-source ManyChat alternative. Visual chatbot builder for Instagram, Facebook, Telegram, Twitter/X, Bluesky & Reddit."
    href="https://github.com/zernio-dev/zernflow"
  />
</Cards>

## OpenAPI Specs

Free, downloadable OpenAPI specifications for all major social media platforms. Use these specs to generate SDKs, build API clients, or explore API capabilities in tools like Swagger UI or Postman.

All specs are maintained in our [public GitHub repository](https://github.com/zernio-dev/openapi-specs).

### Platform API Specifications

<Cards>
  <Card
    title="Twitter / X API"
    description="OpenAPI spec for Twitter API v2 - tweets, users, spaces, lists, and more"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/twitter.yaml"
  />
  <Card
    title="Instagram Graph API"
    description="OpenAPI spec for Instagram Graph API - media, comments, insights, and stories"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/instagram.yaml"
  />
  <Card
    title="Facebook Graph API"
    description="OpenAPI spec for Facebook Graph API - pages, posts, comments, and ads"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/facebook.yaml"
  />
  <Card
    title="LinkedIn API"
    description="OpenAPI spec for LinkedIn Marketing & Community APIs - posts, organizations, and analytics"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/linkedin.yaml"
  />
  <Card
    title="TikTok API"
    description="OpenAPI spec for TikTok Content Posting API - videos, sounds, and user info"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/tiktok.yaml"
  />
  <Card
    title="YouTube Data API"
    description="OpenAPI spec for YouTube Data API v3 - videos, channels, playlists, and comments"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/youtube.yaml"
  />
  <Card
    title="Pinterest API"
    description="OpenAPI spec for Pinterest API v5 - pins, boards, and analytics"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/pinterest.yaml"
  />
  <Card
    title="Reddit API"
    description="OpenAPI spec for Reddit API - posts, comments, subreddits, and users"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/reddit.yaml"
  />
  <Card
    title="Threads API"
    description="OpenAPI spec for Threads API - posts, replies, and user profiles"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/threads.yaml"
  />
  <Card
    title="Bluesky API (AT Protocol)"
    description="OpenAPI spec for Bluesky AT Protocol - posts, follows, and feeds"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/bluesky.yaml"
  />
  <Card
    title="Google Business Profile API"
    description="OpenAPI spec for Google Business Profile API - reviews, posts, and locations"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/googlebusiness.yaml"
  />
  <Card
    title="Telegram Bot API"
    description="OpenAPI spec for Telegram Bot API - messages, updates, and inline queries"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/telegram.yaml"
  />
  <Card
    title="Snapchat Marketing API"
    description="OpenAPI spec for Snapchat Marketing API - ads, campaigns, and analytics"
    href="https://github.com/zernio-dev/openapi-specs/blob/main/snapchat.yaml"
  />
</Cards>

### Direct Download Links

| Platform | Download | Size |
|----------|----------|------|
| Twitter / X | [twitter.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/twitter.yaml) | 478 KB |
| Pinterest | [pinterest.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/pinterest.yaml) | 1.5 MB |
| Telegram | [telegram.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/telegram.yaml) | 111 KB |
| YouTube | [youtube.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/youtube.yaml) | 96 KB |
| Reddit | [reddit.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/reddit.yaml) | 71 KB |
| Google Business | [googlebusiness.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/googlebusiness.yaml) | 59 KB |
| LinkedIn | [linkedin.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/linkedin.yaml) | 54 KB |
| Snapchat | [snapchat.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/snapchat.yaml) | 51 KB |
| Threads | [threads.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/threads.yaml) | 50 KB |
| Bluesky | [bluesky.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/bluesky.yaml) | 45 KB |
| TikTok | [tiktok.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/tiktok.yaml) | 43 KB |
| Instagram | [instagram.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/instagram.yaml) | 39 KB |
| Facebook | [facebook.yaml](https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/facebook.yaml) | 38 KB |

### Using These Specs

**Import into Postman:**

1. Copy the raw URL for your platform (e.g., `https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/twitter.yaml`)
2. Open Postman and go to **File → Import**
3. Paste the URL or download and select the file

**Generate an SDK:**

```bash
# Download the spec
curl -O https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/twitter.yaml

# Generate TypeScript SDK
openapi-generator-cli generate -i twitter.yaml -g typescript-fetch -o ./twitter-sdk
```

**View in Swagger UI:**

```bash
docker run -p 8080:8080 -e SWAGGER_JSON_URL=https://raw.githubusercontent.com/zernio-dev/openapi-specs/main/twitter.yaml swaggerapi/swagger-ui
```

Found an issue or want to improve a spec? Contributions are welcome on [GitHub](https://github.com/zernio-dev/openapi-specs).

---

# Create group API Reference

Creates a new account group with a name and a list of social account IDs.
Accounts can belong to different profiles; the caller must have access to
every account's profile. Group names must be unique per user.


## GET /v1/account-groups

**List groups**

Returns all account groups visible to the authenticated user. Groups can
contain accounts from multiple profiles. For API keys scoped to specific
profiles, only groups whose accounts all live in allowed profiles are
returned.


### Responses

#### 200: Groups

**Response Body:**

- **groups** `array[object]`: 
  - **_id** `string`: No description
  - **name** `string`: No description
  - **accountIds** `array[string]`: 
  - **createdBy** `string`: No description
  - **profileId** `string`: Legacy field. Present only on groups created before
cross-profile groups were supported. New groups omit it.


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/account-groups

**Create group**

Creates a new account group with a name and a list of social account IDs.
Accounts can belong to different profiles; the caller must have access to
every account's profile. Group names must be unique per user.


### Request Body

- **name** (required) `string`: No description
- **accountIds** (required) `array`: No description
- **profileId** `string`: Deprecated. Accepted for backward compatibility but ignored.
Groups are no longer scoped to a single profile.


### Responses

#### 201: Created

**Response Body:**

- **message** `string`: No description
- **group** `object`: 
  - **_id** `string`: No description
  - **name** `string`: No description
  - **accountIds** `array[string]`: 

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 409: Group name already exists

---

---

# Delete group API Reference

Permanently deletes an account group. The accounts themselves are not affected.

## PUT /v1/account-groups/{groupId}

**Update group**

Updates the name or account list of an existing group. You can rename the group, change its accounts, or both.

### Parameters

- **groupId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **accountIds** `array`: No description

### Responses

#### 200: Updated

**Response Body:**

- **message** `string`: No description
- **group** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 409: Group name already exists

---

## DELETE /v1/account-groups/{groupId}

**Delete group**

Permanently deletes an account group. The accounts themselves are not affected.

### Parameters

- **groupId** (required) in path: No description

### Responses

#### 200: Deleted

**Response Body:**

- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List groups API Reference

Returns all account groups visible to the authenticated user. Groups can
contain accounts from multiple profiles. For API keys scoped to specific
profiles, only groups whose accounts all live in allowed profiles are
returned.


## GET /v1/account-groups

**List groups**

Returns all account groups visible to the authenticated user. Groups can
contain accounts from multiple profiles. For API keys scoped to specific
profiles, only groups whose accounts all live in allowed profiles are
returned.


### Responses

#### 200: Groups

**Response Body:**

- **groups** `array[object]`: 
  - **_id** `string`: No description
  - **name** `string`: No description
  - **accountIds** `array[string]`: 
  - **createdBy** `string`: No description
  - **profileId** `string`: Legacy field. Present only on groups created before
cross-profile groups were supported. New groups omit it.


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/account-groups

**Create group**

Creates a new account group with a name and a list of social account IDs.
Accounts can belong to different profiles; the caller must have access to
every account's profile. Group names must be unique per user.


### Request Body

- **name** (required) `string`: No description
- **accountIds** (required) `array`: No description
- **profileId** `string`: Deprecated. Accepted for backward compatibility but ignored.
Groups are no longer scoped to a single profile.


### Responses

#### 201: Created

**Response Body:**

- **message** `string`: No description
- **group** `object`: 
  - **_id** `string`: No description
  - **name** `string`: No description
  - **accountIds** `array[string]`: 

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 409: Group name already exists

---

---

# Update group API Reference

Updates the name or account list of an existing group. You can rename the group, change its accounts, or both.

## PUT /v1/account-groups/{groupId}

**Update group**

Updates the name or account list of an existing group. You can rename the group, change its accounts, or both.

### Parameters

- **groupId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **accountIds** `array`: No description

### Responses

#### 200: Updated

**Response Body:**

- **message** `string`: No description
- **group** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 409: Group name already exists

---

## DELETE /v1/account-groups/{groupId}

**Delete group**

Permanently deletes an account group. The accounts themselves are not affected.

### Parameters

- **groupId** (required) in path: No description

### Responses

#### 200: Deleted

**Response Body:**

- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Delete IG ice breakers API Reference

Removes the ice breaker questions from an Instagram account's Messenger experience.

## GET /v1/accounts/{accountId}/instagram-ice-breakers

**Get IG ice breakers**

Get the ice breaker configuration for an Instagram account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Ice breaker configuration

**Response Body:**

- **data** `array[object]`: 
  Type: `object`

#### 400: Not an Instagram account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/accounts/{accountId}/instagram-ice-breakers

**Set IG ice breakers**

Set ice breakers for an Instagram account. Max 4 ice breakers, question max 80 chars.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **ice_breakers** (required) `array`: No description

### Responses

#### 200: Ice breakers set successfully

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/accounts/{accountId}/instagram-ice-breakers

**Delete IG ice breakers**

Removes the ice breaker questions from an Instagram account's Messenger experience.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Ice breakers deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Delete FB persistent menu API Reference

Removes the persistent menu from Facebook Messenger conversations for this account.

## GET /v1/accounts/{accountId}/messenger-menu

**Get FB persistent menu**

Get the persistent menu configuration for a Facebook Messenger account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Persistent menu configuration

**Response Body:**

- **data** `array[object]`: 
  Type: `object`

#### 400: Not a Facebook account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/accounts/{accountId}/messenger-menu

**Set FB persistent menu**

Set the persistent menu for a Facebook Messenger account. Max 3 top-level items, max 5 nested items.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **persistent_menu** (required) `array`: Persistent menu configuration array (Meta format)

### Responses

#### 200: Menu set successfully

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/accounts/{accountId}/messenger-menu

**Delete FB persistent menu**

Removes the persistent menu from Facebook Messenger conversations for this account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Menu deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Delete TG bot commands API Reference

Clears all bot commands configured for a Telegram bot account.

## GET /v1/accounts/{accountId}/telegram-commands

**Get TG bot commands**

Get the bot commands configuration for a Telegram account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Bot commands list

**Response Body:**

- **data** `array[object]`: 
  - **command** `string`: No description
  - **description** `string`: No description

#### 400: Not a Telegram account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/accounts/{accountId}/telegram-commands

**Set TG bot commands**

Set bot commands for a Telegram account.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **commands** (required) `array`: No description

### Responses

#### 200: Commands set successfully

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/accounts/{accountId}/telegram-commands

**Delete TG bot commands**

Clears all bot commands configured for a Telegram bot account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Commands deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Get IG ice breakers API Reference

Get the ice breaker configuration for an Instagram account.

## GET /v1/accounts/{accountId}/instagram-ice-breakers

**Get IG ice breakers**

Get the ice breaker configuration for an Instagram account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Ice breaker configuration

**Response Body:**

- **data** `array[object]`: 
  Type: `object`

#### 400: Not an Instagram account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/accounts/{accountId}/instagram-ice-breakers

**Set IG ice breakers**

Set ice breakers for an Instagram account. Max 4 ice breakers, question max 80 chars.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **ice_breakers** (required) `array`: No description

### Responses

#### 200: Ice breakers set successfully

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/accounts/{accountId}/instagram-ice-breakers

**Delete IG ice breakers**

Removes the ice breaker questions from an Instagram account's Messenger experience.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Ice breakers deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Get FB persistent menu API Reference

Get the persistent menu configuration for a Facebook Messenger account.

## GET /v1/accounts/{accountId}/messenger-menu

**Get FB persistent menu**

Get the persistent menu configuration for a Facebook Messenger account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Persistent menu configuration

**Response Body:**

- **data** `array[object]`: 
  Type: `object`

#### 400: Not a Facebook account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/accounts/{accountId}/messenger-menu

**Set FB persistent menu**

Set the persistent menu for a Facebook Messenger account. Max 3 top-level items, max 5 nested items.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **persistent_menu** (required) `array`: Persistent menu configuration array (Meta format)

### Responses

#### 200: Menu set successfully

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/accounts/{accountId}/messenger-menu

**Delete FB persistent menu**

Removes the persistent menu from Facebook Messenger conversations for this account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Menu deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Get TG bot commands API Reference

Get the bot commands configuration for a Telegram account.

## GET /v1/accounts/{accountId}/telegram-commands

**Get TG bot commands**

Get the bot commands configuration for a Telegram account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Bot commands list

**Response Body:**

- **data** `array[object]`: 
  - **command** `string`: No description
  - **description** `string`: No description

#### 400: Not a Telegram account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/accounts/{accountId}/telegram-commands

**Set TG bot commands**

Set bot commands for a Telegram account.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **commands** (required) `array`: No description

### Responses

#### 200: Commands set successfully

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/accounts/{accountId}/telegram-commands

**Delete TG bot commands**

Clears all bot commands configured for a Telegram bot account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Commands deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Set IG ice breakers API Reference

Set ice breakers for an Instagram account. Max 4 ice breakers, question max 80 chars.

## GET /v1/accounts/{accountId}/instagram-ice-breakers

**Get IG ice breakers**

Get the ice breaker configuration for an Instagram account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Ice breaker configuration

**Response Body:**

- **data** `array[object]`: 
  Type: `object`

#### 400: Not an Instagram account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/accounts/{accountId}/instagram-ice-breakers

**Set IG ice breakers**

Set ice breakers for an Instagram account. Max 4 ice breakers, question max 80 chars.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **ice_breakers** (required) `array`: No description

### Responses

#### 200: Ice breakers set successfully

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/accounts/{accountId}/instagram-ice-breakers

**Delete IG ice breakers**

Removes the ice breaker questions from an Instagram account's Messenger experience.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Ice breakers deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Set FB persistent menu API Reference

Set the persistent menu for a Facebook Messenger account. Max 3 top-level items, max 5 nested items.

## GET /v1/accounts/{accountId}/messenger-menu

**Get FB persistent menu**

Get the persistent menu configuration for a Facebook Messenger account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Persistent menu configuration

**Response Body:**

- **data** `array[object]`: 
  Type: `object`

#### 400: Not a Facebook account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/accounts/{accountId}/messenger-menu

**Set FB persistent menu**

Set the persistent menu for a Facebook Messenger account. Max 3 top-level items, max 5 nested items.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **persistent_menu** (required) `array`: Persistent menu configuration array (Meta format)

### Responses

#### 200: Menu set successfully

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/accounts/{accountId}/messenger-menu

**Delete FB persistent menu**

Removes the persistent menu from Facebook Messenger conversations for this account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Menu deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Set TG bot commands API Reference

Set bot commands for a Telegram account.

## GET /v1/accounts/{accountId}/telegram-commands

**Get TG bot commands**

Get the bot commands configuration for a Telegram account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Bot commands list

**Response Body:**

- **data** `array[object]`: 
  - **command** `string`: No description
  - **description** `string`: No description

#### 400: Not a Telegram account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/accounts/{accountId}/telegram-commands

**Set TG bot commands**

Set bot commands for a Telegram account.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **commands** (required) `array`: No description

### Responses

#### 200: Commands set successfully

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/accounts/{accountId}/telegram-commands

**Delete TG bot commands**

Clears all bot commands configured for a Telegram bot account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Commands deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Disconnect account API Reference

Disconnects and removes a connected social account.

## PUT /v1/accounts/{accountId}

**Update account**

Updates a connected social account's display name or username override.

For X/Twitter accounts on usage-based billing, also accepts an `xCapabilities`
object to toggle background API operations that incur X API pass-through costs.
Both fields are opt-in (default `false`) — when off, no analytics syncs or DM
polling are performed for that account, and no API call is metered for those
operations. Publishing and deleting posts are always available regardless of
these toggles. Setting `xCapabilities` on a non-X account returns 400.


### Parameters

- **accountId** (required) in path: No description

### Request Body

- **username** `string`: No description
- **displayName** `string`: No description
- **xCapabilities** `object`: X/Twitter only. Per-account opt-in toggles for background API
operations that incur X API pass-through costs. Each call is
billed via Metronome at the X tier rate. Either field can be
sent independently; omitted fields are unchanged.


### Responses

#### 200: Updated

**Response Body:**

- **message** `string`: No description
- **username** `string`: No description
- **displayName** `string`: No description
- **xCapabilities** `object`: Echo of the resulting `xCapabilities` state, returned only
when the request body included an `xCapabilities` object.

  - **analytics** `boolean`: No description
  - **inbox** `boolean`: No description

#### 400: Invalid request (e.g. xCapabilities on a non-X account)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/accounts/{accountId}

**Move account to a different profile**

Moves a connected social account to a different profile owned by the same
user. The target profile must belong to the same user as the account.

For API keys restricted to specific profiles, BOTH the source account's
current profile AND the target profile must be in the key's allowed set.
Calls with a target profile outside the key's scope return 403.


### Parameters

- **accountId** (required) in path: No description

### Request Body

- **profileId** (required) `string`: Target profile ID (must be a valid ObjectId and owned by the same user as the account).

### Responses

#### 200: Account moved

**Response Body:**

- **message** `string`: No description
- **profileId** `string`: No description

#### 400: Missing or invalid profileId

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: API key does not have access to the source account or target profile

#### 404: Account or target profile not found

---

## DELETE /v1/accounts/{accountId}

**Disconnect account**

Disconnects and removes a connected social account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Disconnected

**Response Body:**

- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Check account health API Reference

Returns detailed health info for a specific account including token status, permissions, and recommendations.

## GET /v1/accounts/{accountId}/health

**Check account health**

Returns detailed health info for a specific account including token status, permissions, and recommendations.

### Parameters

- **accountId** (required) in path: The account ID to check

### Responses

#### 200: Account health details

**Response Body:**

- **accountId** `string`: No description
- **platform** `string`: No description
- **username** `string`: No description
- **displayName** `string`: No description
- **status** `string`: Overall health status - one of: healthy, warning, error
- **tokenStatus** `object`: 
  - **valid** `boolean`: Whether the token is valid
  - **expiresAt** `string` (date-time): No description
  - **expiresIn** `string`: Human-readable time until expiry
  - **needsRefresh** `boolean`: Whether token expires within 24 hours
- **permissions** `object`: 
  - **posting** `array[object]`: 
    - **scope** `string`: No description
    - **granted** `boolean`: No description
    - **required** `boolean`: No description
  - **analytics** `array[object]`: 
    - **scope** `string`: No description
    - **granted** `boolean`: No description
    - **required** `boolean`: No description
  - **optional** `array[object]`: 
    - **scope** `string`: No description
    - **granted** `boolean`: No description
    - **required** `boolean`: No description
  - **canPost** `boolean`: No description
  - **canFetchAnalytics** `boolean`: No description
  - **missingRequired** `array[string]`: 
- **issues** `array[string]`: List of issues found
- **recommendations** `array[string]`: Actionable recommendations to fix issues

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Check accounts health API Reference

Returns health status of all connected accounts including token validity, permissions, and issues needing attention.

## GET /v1/accounts/health

**Check accounts health**

Returns health status of all connected accounts including token validity, permissions, and issues needing attention.

### Parameters

- **profileId** (optional) in query: Filter by profile ID
- **platform** (optional) in query: Filter by platform
- **status** (optional) in query: Filter by health status

### Responses

#### 200: Account health summary

**Response Body:**

- **summary** `object`: 
  - **total** `integer`: Total number of accounts
  - **healthy** `integer`: Number of healthy accounts
  - **warning** `integer`: Number of accounts with warnings
  - **error** `integer`: Number of accounts with errors
  - **needsReconnect** `integer`: Number of accounts needing reconnection
- **accounts** `array[object]`: 
  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **profileId** `string`: No description
  - **status** `string`: No description - one of: healthy, warning, error
  - **canPost** `boolean`: No description
  - **canFetchAnalytics** `boolean`: No description
  - **tokenValid** `boolean`: No description
  - **tokenExpiresAt** `string` (date-time): No description
  - **needsReconnect** `boolean`: No description
  - **issues** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Get follower stats API Reference

Returns follower count history and growth metrics for connected social accounts.
Requires analytics add-on subscription. Follower counts are refreshed once per day.


## GET /v1/accounts/follower-stats

**Get follower stats**

Returns follower count history and growth metrics for connected social accounts.
Requires analytics add-on subscription. Follower counts are refreshed once per day.


### Parameters

- **accountIds** (optional) in query: Comma-separated list of account IDs (optional, defaults to all user's accounts)
- **profileId** (optional) in query: Filter by profile ID
- **fromDate** (optional) in query: Start date in YYYY-MM-DD format (defaults to 30 days ago)
- **toDate** (optional) in query: End date in YYYY-MM-DD format (defaults to today)
- **granularity** (optional) in query: Data aggregation level

### Responses

#### 200: Follower stats

**Response Body:**

- **accounts** `array[AccountWithFollowerStats]`: 
- **stats** `object`: No description
- **dateRange** `object`: 
  - **from** `string` (date-time): No description
  - **to** `string` (date-time): No description
- **granularity** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **message** `string`: No description (example: "Follower stats tracking requires the Analytics add-on. Please upgrade to access this feature.")
- **requiresAddon** `boolean`: No description (example: true)

---


# Related Schema Definitions

## AccountWithFollowerStats

---

# Get TikTok creator info API Reference

Returns TikTok creator details, available privacy levels, posting limits, and commercial content options for a specific TikTok account. Only works with TikTok accounts.

## GET /v1/accounts/{accountId}/tiktok/creator-info

**Get TikTok creator info**

Returns TikTok creator details, available privacy levels, posting limits, and commercial content options for a specific TikTok account. Only works with TikTok accounts.

### Parameters

- **accountId** (required) in path: The TikTok account ID
- **mediaType** (optional) in query: The media type to get creator info for (affects available interaction settings)

### Responses

#### 200: TikTok creator info and posting options

**Response Body:**

- **creator** `object`: 
  - **nickname** `string`: Creator display name
  - **avatarUrl** `string`: Creator avatar URL
  - **isVerified** `boolean`: Whether the creator is verified
  - **canPostMore** `boolean`: Whether the creator can publish more posts right now
- **privacyLevels** `array[object]`: Available privacy level options for this creator
  - **value** `string`: Privacy level value to use when creating posts (e.g. PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY)
  - **label** `string`: Human-readable label
- **postingLimits** `object`: 
  - **maxVideoDurationSec** `integer`: Maximum video duration in seconds
  - **interactionSettings** `object`: Available interaction toggles (comment, duet, stitch) and their defaults
- **commercialContentTypes** `array[object]`: Available commercial content disclosure options
  - **value** `string`: No description
  - **label** `string`: No description
  - **requires** `array[string]`: 

#### 400: Account is not a TikTok account

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 429: Creator has reached TikTok daily posting limit

**Response Body:**

- **error** `string`: No description

---

---

# List accounts API Reference

Returns connected social accounts. Only includes accounts within the plan limit by default. Follower data requires analytics add-on.
Supports optional server-side pagination via page/limit params. When omitted, returns all accounts (backward-compatible).


## GET /v1/accounts

**List accounts**

Returns connected social accounts. Only includes accounts within the plan limit by default. Follower data requires analytics add-on.
Supports optional server-side pagination via page/limit params. When omitted, returns all accounts (backward-compatible).


### Parameters

- **profileId** (optional) in query: Filter accounts by profile ID
- **platform** (optional) in query: Filter accounts by platform (e.g. "instagram", "twitter").
- **status** (optional) in query: 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.

- **includeOverLimit** (optional) in query: When true, includes accounts from over-limit profiles.
- **page** (optional) in query: Page number (1-based). When provided with limit, enables server-side pagination. Omit for all accounts.
- **limit** (optional) in query: Page size. Required alongside page for pagination.

### Responses

#### 200: Accounts (with optional pagination)

**Response Body:**

- **accounts** (required) `array[SocialAccount]`: 
- **hasAnalyticsAccess** (required) `boolean`: Whether user has analytics add-on access
- **pagination**: `Pagination` - Only present when page/limit params are provided

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## SocialAccount

### Properties

- **_id** (required) `string`: No description
- **platform** (required) `string`: No description - one of: tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, discord, whatsapp, linkedinads, metaads, pinterestads, tiktokads, xads, googleads
- **profileId** (required): No description
- **username** `string`: No description
- **displayName** `string`: No description
- **profilePicture** `string`: URL to the account's profile picture on the platform. May be null if the platform does not provide one.
- **profileUrl** `string`: Full profile URL for the connected account on its platform.
- **isActive** (required) `boolean`: No description
- **followersCount** `number`: Follower count (only included if user has analytics add-on)
- **followersLastUpdated** `string`: Last time follower count was updated (only included if user has analytics add-on)
- **parentAccountId** `string`: Reference to the parent posting SocialAccount. Set for ads accounts that share
or derive from a posting account's OAuth token. null for standalone ads (Google Ads)
and all posting accounts.

- **enabled** `boolean`: Whether the user explicitly activated this account. false means the account was
created as a side effect (e.g., posting account auto-created when user connected
ads first). Posting UI and scheduler ignore accounts with enabled: false.

- **metadata** `object`: Platform-specific metadata. Fields vary by platform. For WhatsApp accounts, includes:
- qualityRating: Phone number quality rating from Meta (GREEN, YELLOW, RED, or UNKNOWN)
- nameStatus: Display name review status (APPROVED, PENDING_REVIEW, DECLINED, or NONE). Messages cannot be sent until the display name is approved by Meta.
- messagingLimitTier: Maximum unique business-initiated conversations per 24h rolling window (TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED). Scales automatically as quality rating improves.
- verifiedName: Meta-verified business display name
- displayPhoneNumber: Formatted phone number (e.g., "+1 555-123-4567")
- wabaId: WhatsApp Business Account ID
- phoneNumberId: Meta phone number ID


## Pagination

### Properties

- **page** `integer`: No description
- **limit** `integer`: No description
- **total** `integer`: No description
- **pages** `integer`: No description

---

# Move account to a different profile API Reference

Moves a connected social account to a different profile owned by the same
user. The target profile must belong to the same user as the account.

For API keys restricted to specific profiles, BOTH the source account's
current profile AND the target profile must be in the key's allowed set.
Calls with a target profile outside the key's scope return 403.


## PUT /v1/accounts/{accountId}

**Update account**

Updates a connected social account's display name or username override.

For X/Twitter accounts on usage-based billing, also accepts an `xCapabilities`
object to toggle background API operations that incur X API pass-through costs.
Both fields are opt-in (default `false`) — when off, no analytics syncs or DM
polling are performed for that account, and no API call is metered for those
operations. Publishing and deleting posts are always available regardless of
these toggles. Setting `xCapabilities` on a non-X account returns 400.


### Parameters

- **accountId** (required) in path: No description

### Request Body

- **username** `string`: No description
- **displayName** `string`: No description
- **xCapabilities** `object`: X/Twitter only. Per-account opt-in toggles for background API
operations that incur X API pass-through costs. Each call is
billed via Metronome at the X tier rate. Either field can be
sent independently; omitted fields are unchanged.


### Responses

#### 200: Updated

**Response Body:**

- **message** `string`: No description
- **username** `string`: No description
- **displayName** `string`: No description
- **xCapabilities** `object`: Echo of the resulting `xCapabilities` state, returned only
when the request body included an `xCapabilities` object.

  - **analytics** `boolean`: No description
  - **inbox** `boolean`: No description

#### 400: Invalid request (e.g. xCapabilities on a non-X account)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/accounts/{accountId}

**Move account to a different profile**

Moves a connected social account to a different profile owned by the same
user. The target profile must belong to the same user as the account.

For API keys restricted to specific profiles, BOTH the source account's
current profile AND the target profile must be in the key's allowed set.
Calls with a target profile outside the key's scope return 403.


### Parameters

- **accountId** (required) in path: No description

### Request Body

- **profileId** (required) `string`: Target profile ID (must be a valid ObjectId and owned by the same user as the account).

### Responses

#### 200: Account moved

**Response Body:**

- **message** `string`: No description
- **profileId** `string`: No description

#### 400: Missing or invalid profileId

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: API key does not have access to the source account or target profile

#### 404: Account or target profile not found

---

## DELETE /v1/accounts/{accountId}

**Disconnect account**

Disconnects and removes a connected social account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Disconnected

**Response Body:**

- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Update account API Reference

Updates a connected social account's display name or username override.

For X/Twitter accounts on usage-based billing, also accepts an `xCapabilities`
object to toggle background API operations that incur X API pass-through costs.
Both fields are opt-in (default `false`) — when off, no analytics syncs or DM
polling are performed for that account, and no API call is metered for those
operations. Publishing and deleting posts are always available regardless of
these toggles. Setting `xCapabilities` on a non-X account returns 400.


## PUT /v1/accounts/{accountId}

**Update account**

Updates a connected social account's display name or username override.

For X/Twitter accounts on usage-based billing, also accepts an `xCapabilities`
object to toggle background API operations that incur X API pass-through costs.
Both fields are opt-in (default `false`) — when off, no analytics syncs or DM
polling are performed for that account, and no API call is metered for those
operations. Publishing and deleting posts are always available regardless of
these toggles. Setting `xCapabilities` on a non-X account returns 400.


### Parameters

- **accountId** (required) in path: No description

### Request Body

- **username** `string`: No description
- **displayName** `string`: No description
- **xCapabilities** `object`: X/Twitter only. Per-account opt-in toggles for background API
operations that incur X API pass-through costs. Each call is
billed via Metronome at the X tier rate. Either field can be
sent independently; omitted fields are unchanged.


### Responses

#### 200: Updated

**Response Body:**

- **message** `string`: No description
- **username** `string`: No description
- **displayName** `string`: No description
- **xCapabilities** `object`: Echo of the resulting `xCapabilities` state, returned only
when the request body included an `xCapabilities` object.

  - **analytics** `boolean`: No description
  - **inbox** `boolean`: No description

#### 400: Invalid request (e.g. xCapabilities on a non-X account)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/accounts/{accountId}

**Move account to a different profile**

Moves a connected social account to a different profile owned by the same
user. The target profile must belong to the same user as the account.

For API keys restricted to specific profiles, BOTH the source account's
current profile AND the target profile must be in the key's allowed set.
Calls with a target profile outside the key's scope return 403.


### Parameters

- **accountId** (required) in path: No description

### Request Body

- **profileId** (required) `string`: Target profile ID (must be a valid ObjectId and owned by the same user as the account).

### Responses

#### 200: Account moved

**Response Body:**

- **message** `string`: No description
- **profileId** `string`: No description

#### 400: Missing or invalid profileId

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: API key does not have access to the source account or target profile

#### 404: Account or target profile not found

---

## DELETE /v1/accounts/{accountId}

**Disconnect account**

Disconnects and removes a connected social account.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Disconnected

**Response Body:**

- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Add users to audience API Reference

Upload user data to a customer_list audience. Data is SHA256-hashed server-side before sending to the platform.
Email is used on every platform; phone is used on Meta only (other platforms ignore it). On TikTok and Pinterest,
the first upload also provisions the audience (deferred create). LinkedIn uploads are full-replace. Max 10,000 users per request.


## POST /v1/ads/audiences/{audienceId}/users

**Add users to audience**

Upload user data to a customer_list audience. Data is SHA256-hashed server-side before sending to the platform.
Email is used on every platform; phone is used on Meta only (other platforms ignore it). On TikTok and Pinterest,
the first upload also provisions the audience (deferred create). LinkedIn uploads are full-replace. Max 10,000 users per request.


### Parameters

- **audienceId** (required) in path: No description

### Request Body

- **users** (required) `array`: No description

### Responses

#### 200: Users added

**Response Body:**

- **message** `string`: No description
- **numReceived** `integer`: No description
- **numInvalid** `integer`: No description

#### 400: Invalid input (empty users array, missing email/phone)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 422: Audience is not a customer_list type or has no platform ID yet

---

---

# Create custom audience API Reference

Create a custom audience. `customer_list` is supported on Meta, Google, X, LinkedIn, TikTok, and Pinterest;
`website` and `lookalike` are Meta-only. `saved_targeting` stores a reusable TargetingSpec (no member upload,
no adAccountId) that you reference later via `savedTargetingId` on `POST /v1/ads/create`. Upload-backed audiences
are created empty, add members via `POST /v1/ads/audiences/{audienceId}/users`. On TikTok and Pinterest the
audience is provisioned lazily on the first member upload (until then its status is `pending`). Create is not
idempotent, never auto-retry.


## GET /v1/ads/audiences

**List custom audiences**

Returns custom audiences for the given ad account. Supports Meta, Google, TikTok, Pinterest, LinkedIn, and X (Twitter).

### Parameters

- **accountId** (required) in query: Social account ID
- **adAccountId** (required) in query: Platform ad account ID
- **platform** (optional) in query: No description
- **type** (optional) in query: Filter to one audience type. `saved_targeting` returns stored TargetingSpec audiences (each item carries a `spec`); the other types return uploaded/derived audiences.

### Responses

#### 200: Audiences

**Response Body:**

- **audiences** `array[object]`: 
  - **id** `string`: No description
  - **platformAudienceId** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **type** `string`: No description - one of: customer_list, website, lookalike, saved_targeting
  - **spec**: Present (and the only meaningful payload) when `type` is `saved_targeting`. Null for uploaded/derived audience types.
  - **platform** `string`: No description
  - **size** `integer`: No description
  - **status** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

---

## POST /v1/ads/audiences

**Create custom audience**

Create a custom audience. `customer_list` is supported on Meta, Google, X, LinkedIn, TikTok, and Pinterest;
`website` and `lookalike` are Meta-only. `saved_targeting` stores a reusable TargetingSpec (no member upload,
no adAccountId) that you reference later via `savedTargetingId` on `POST /v1/ads/create`. Upload-backed audiences
are created empty, add members via `POST /v1/ads/audiences/{audienceId}/users`. On TikTok and Pinterest the
audience is provisioned lazily on the first member upload (until then its status is `pending`). Create is not
idempotent, never auto-retry.


### Request Body

- **platformSpecificData**: Platform-specific settings (see schema definitions below)

### Responses

#### 201: Audience created

**Response Body:**

- **audience** `object`: No description
- **message** `string`: No description

#### 400: Missing required fields

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

---

---

# Delete custom audience API Reference

Deletes the audience from both Meta and the local database.

## GET /v1/ads/audiences/{audienceId}

**Get audience details**

Returns the local audience record and fresh data from Meta (if available).

### Parameters

- **audienceId** (required) in path: No description

### Responses

#### 200: Audience details

**Response Body:**

- **audience** `object`: No description
- **metaData** `object`: Fresh data from Meta API

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/ads/audiences/{audienceId}

**Delete custom audience**

Deletes the audience from both Meta and the local database.

### Parameters

- **audienceId** (required) in path: No description

### Responses

#### 200: Audience deleted

**Response Body:**

- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Get audience details API Reference

Returns the local audience record and fresh data from Meta (if available).

## GET /v1/ads/audiences/{audienceId}

**Get audience details**

Returns the local audience record and fresh data from Meta (if available).

### Parameters

- **audienceId** (required) in path: No description

### Responses

#### 200: Audience details

**Response Body:**

- **audience** `object`: No description
- **metaData** `object`: Fresh data from Meta API

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/ads/audiences/{audienceId}

**Delete custom audience**

Deletes the audience from both Meta and the local database.

### Parameters

- **audienceId** (required) in path: No description

### Responses

#### 200: Audience deleted

**Response Body:**

- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List custom audiences API Reference

Returns custom audiences for the given ad account. Supports Meta, Google, TikTok, Pinterest, LinkedIn, and X (Twitter).

## GET /v1/ads/audiences

**List custom audiences**

Returns custom audiences for the given ad account. Supports Meta, Google, TikTok, Pinterest, LinkedIn, and X (Twitter).

### Parameters

- **accountId** (required) in query: Social account ID
- **adAccountId** (required) in query: Platform ad account ID
- **platform** (optional) in query: No description
- **type** (optional) in query: Filter to one audience type. `saved_targeting` returns stored TargetingSpec audiences (each item carries a `spec`); the other types return uploaded/derived audiences.

### Responses

#### 200: Audiences

**Response Body:**

- **audiences** `array[object]`: 
  - **id** `string`: No description
  - **platformAudienceId** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **type** `string`: No description - one of: customer_list, website, lookalike, saved_targeting
  - **spec**: Present (and the only meaningful payload) when `type` is `saved_targeting`. Null for uploaded/derived audience types.
  - **platform** `string`: No description
  - **size** `integer`: No description
  - **status** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

---

## POST /v1/ads/audiences

**Create custom audience**

Create a custom audience. `customer_list` is supported on Meta, Google, X, LinkedIn, TikTok, and Pinterest;
`website` and `lookalike` are Meta-only. `saved_targeting` stores a reusable TargetingSpec (no member upload,
no adAccountId) that you reference later via `savedTargetingId` on `POST /v1/ads/create`. Upload-backed audiences
are created empty, add members via `POST /v1/ads/audiences/{audienceId}/users`. On TikTok and Pinterest the
audience is provisioned lazily on the first member upload (until then its status is `pending`). Create is not
idempotent, never auto-retry.


### Request Body

- **platformSpecificData**: Platform-specific settings (see schema definitions below)

### Responses

#### 201: Audience created

**Response Body:**

- **audience** `object`: No description
- **message** `string`: No description

#### 400: Missing required fields

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

---

---

# Pause or resume many campaigns API Reference

Process up to 50 campaigns in one call. Each campaign is updated
concurrently and the response contains a per-campaign result so a
single bad row does not fail the whole batch.


## POST /v1/ads/campaigns/bulk-status

**Pause or resume many campaigns**

Process up to 50 campaigns in one call. Each campaign is updated
concurrently and the response contains a per-campaign result so a
single bad row does not fail the whole batch.


### Request Body

- **status** (required) `string`: No description - one of: active, paused
- **campaigns** (required) `array`: No description

### Responses

#### 200: Per-campaign results

**Response Body:**

- **status** `string`: No description - one of: active, paused
- **totals** `object`: 
  - **updated** `integer`: No description
  - **skipped** `integer`: No description
  - **failed** `integer`: No description
- **results** `array[object]`: 
  - **platformCampaignId** `string`: No description
  - **platform** `string`: No description
  - **updated** `integer`: No description
  - **skipped** `integer`: No description
  - **error** `string`: No description

#### 400: Invalid input

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Delete a campaign API Reference

Deletes the whole campaign on the platform, cascading to its ad sets
and ads. Locally, all Ad documents for this campaign are marked
`status: cancelled`.

Meta-only for now. Other platforms return 501 Not Implemented — fall
back to DELETE /v1/ads/{adId} per ad in the meantime.


## PUT /v1/ads/campaigns/{campaignId}

**Update a campaign (budget and/or bid strategy)**

Campaign-level edits. At least one of `budget` or `bidStrategy` is required.

- `budget` updates the CBO (Campaign Budget Optimization) budget. For ABO campaigns
  (where the budget lives on the ad set), use PUT /v1/ads/ad-sets/{adSetId} instead — this endpoint
  will return 409 with code BUDGET_LEVEL_MISMATCH.
- `bidStrategy` sets the campaign-level default bid strategy. Per Meta's spec, `bid_amount` and
  `bid_constraints` do NOT exist at the campaign level — pass them via PUT /v1/ads/ad-sets/{adSetId}.

Meta-only for now. Other platforms return 501 Not Implemented.


### Parameters

- **campaignId** (required) in path: Platform campaign ID

### Request Body

- **platform** (required) `string`: No description - one of: facebook, instagram
- **budget** `object`: No description
- **bidStrategy**: Campaign-level default. Ad sets inherit this unless they override.
- **name** `string`: Rename the campaign (Meta only; other platforms return 501). At least one of budget/bidStrategy/name is required.

### Responses

#### 200: Campaign updated

**Response Body:**

- **updated** `integer`: No description
- **budget**: `AdBudget` - See schema definition
- **budgetLevel** `string`: No description - one of: campaign
- **bidStrategy**: `BidStrategy` - See schema definition

#### 400: Invalid input

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Campaign not found

#### 409: Campaign is ABO — route to /v1/ads/ad-sets/{adSetId} instead

#### 501: Operation not supported on this platform

---

## DELETE /v1/ads/campaigns/{campaignId}

**Delete a campaign**

Deletes the whole campaign on the platform, cascading to its ad sets
and ads. Locally, all Ad documents for this campaign are marked
`status: cancelled`.

Meta-only for now. Other platforms return 501 Not Implemented — fall
back to DELETE /v1/ads/{adId} per ad in the meantime.


### Parameters

- **campaignId** (required) in path: Platform campaign ID

### Request Body

- **platform** (required) `string`: No description - one of: facebook, instagram

### Responses

#### 200: Campaign deleted

**Response Body:**

- **deleted** `boolean`: No description
- **adCount** `integer`: Number of local Ad docs marked cancelled

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Campaign not found

#### 501: Operation not supported on this platform

---


# Related Schema Definitions

## AdBudget

Budget amount in the ad account's native currency (see the campaign's `currency` field for the code).

### Properties

- **amount** (required) `number`: No description
- **type** (required) `string`: No description - one of: daily, lifetime

## BidStrategy

Meta bid strategy. Same enum applies at campaign and ad-set level; ad-set value (when set)
overrides campaign-level. Cross-field rules:
  - `LOWEST_COST_WITHOUT_CAP` (default): auto-bid, forbids `bidAmount` and `roasAverageFloor`.
  - `LOWEST_COST_WITH_BID_CAP` / `COST_CAP`: require `bidAmount` (whole currency units).
  - `LOWEST_COST_WITH_MIN_ROAS`: requires `roasAverageFloor` (decimal multiplier, 2.0 = 2.0x).
Source: facebook-business-sdk-codegen api_specs/specs/enum_types.json (`AdSet_bid_strategy`,
`Campaign_bid_strategy`).

---

# Duplicate a campaign API Reference

Duplicates a campaign, including its ad sets, ads, creatives, and
targeting by default (`deepCopy: true`). The copy is created paused
so callers can review before launching.

Per-platform implementation:
- **Meta** uses the native `POST /{campaign-id}/copies` endpoint.
- **TikTok** has no native copy primitive; Zernio walks the source
  graph (`/v2/campaign/get/`, `/v2/adgroup/get/`, `/v2/ad/get/`) and
  recreates each entity via the corresponding `/create/` endpoints,
  carrying over budget / targeting / bid_type / bid_price /
  deep_bid_type / creative fields. Spark Ad linkage (`tiktok_item_id`)
  is preserved.

The new hierarchy is asynchronous to materialize in our DB — we
trigger sync discovery automatically. Set `syncAfter: false` to
skip and poll `/v1/ads/tree` on your own cadence.

Other platforms return 501 Not Implemented.


## POST /v1/ads/campaigns/{campaignId}/duplicate

**Duplicate a campaign**

Duplicates a campaign, including its ad sets, ads, creatives, and
targeting by default (`deepCopy: true`). The copy is created paused
so callers can review before launching.

Per-platform implementation:
- **Meta** uses the native `POST /{campaign-id}/copies` endpoint.
- **TikTok** has no native copy primitive; Zernio walks the source
  graph (`/v2/campaign/get/`, `/v2/adgroup/get/`, `/v2/ad/get/`) and
  recreates each entity via the corresponding `/create/` endpoints,
  carrying over budget / targeting / bid_type / bid_price /
  deep_bid_type / creative fields. Spark Ad linkage (`tiktok_item_id`)
  is preserved.

The new hierarchy is asynchronous to materialize in our DB — we
trigger sync discovery automatically. Set `syncAfter: false` to
skip and poll `/v1/ads/tree` on your own cadence.

Other platforms return 501 Not Implemented.


### Parameters

- **campaignId** (required) in path: Source platform campaign ID

### Request Body

- **platform** (required) `string`: No description - one of: facebook, instagram, tiktok
- **deepCopy** `boolean`: Copy child ad sets + ads + creatives + targeting
- **statusOption** `string`: No description - one of: ACTIVE, PAUSED, INHERITED_FROM_SOURCE
- **startTime** `string`: Reschedule the copied hierarchy's start time
- **endTime** `string`: No description
- **renameStrategy** `string`: No description - one of: DEEP_RENAME, ONLY_TOP_LEVEL_RENAME, NO_RENAME
- **renamePrefix** `string`: No description
- **renameSuffix** `string`: No description
- **syncAfter** `boolean`: Trigger ads discovery on the owning account after the copy succeeds

### Responses

#### 200: Campaign duplicated

**Response Body:**

- **copiedCampaignId** `string`: Platform ID of the new campaign
- **discovery** `string`: No description - one of: triggered, skipped, failed
- **raw** `object`: Platform-native response from the copy endpoint (Meta includes ad_object_ids for child copies)

#### 400: Invalid input

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Source campaign not found

#### 501: Operation not supported on this platform

---

---

# Get campaign tree API Reference

Returns a nested Campaign > Ad Set > Ad hierarchy with rolled-up metrics at each level.
Uses 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. Pagination is at the campaign level. Ads without a campaign or ad set
ID are grouped into synthetic "Ungrouped" buckets.
If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max.


## GET /v1/ads/tree

**Get campaign tree**

Returns a nested Campaign > Ad Set > Ad hierarchy with rolled-up metrics at each level.
Uses 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. Pagination is at the campaign level. Ads without a campaign or ad set
ID are grouped into synthetic "Ungrouped" buckets.
If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max.


### Parameters

- **undefined** (optional): No description
- **limit** (optional) in query: Campaigns per page
- **source** (optional) in query: `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.
- **platform** (optional) in query: No description
- **status** (optional) in query: Filter by derived campaign status (post-aggregation)
- **adAccountId** (optional) in query: Platform ad account ID
- **accountId** (optional) in query: Social account ID
- **profileId** (optional) in query: Profile ID
- **fromDate** (optional) in query: Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.
- **toDate** (optional) in query: End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range.
- **sort** (optional) in query: 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.

### Responses

#### 200: Nested campaign tree with pagination

**Response Body:**

- **campaigns** `array[AdTreeCampaign]`: 
- **pagination**: `Pagination` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

---


# Related Schema Definitions

## AdTreeCampaign

Campaign with nested ad sets and rolled-up metrics

### Properties

- **platformCampaignId** `string`: No description
- **platform** `string`: No description - one of: facebook, instagram, tiktok, linkedin, pinterest, google, twitter
- **campaignName** `string`: No description
- **status**: Delivery status derived from child ad statuses. Distinct from `reviewStatus`, which reflects the platform-side review state.
- **reviewStatus** `string`: Platform-side review state of the campaign. Independent of the
children-derived delivery `status`: a campaign can have ads
already active (status=active) while the campaign itself is
still being reviewed by the platform (reviewStatus=in_review).
For Meta, derived from `effective_status` + `issues_info` on
the Campaign, plus ad-level PENDING_REVIEW rollup.
 - one of: in_review, approved, rejected, with_issues
- **platformCampaignStatus** `string`: Raw platform-level campaign status (Meta `effective_status`: ACTIVE, PAUSED, DELETED, ARCHIVED, IN_PROCESS, WITH_ISSUES). Distinct from per-ad `platformStatus`.
- **campaignIssuesInfo** `array`: Platform-reported campaign issues (Meta `issues_info[]`). Populated only when the platform has delivery issues to report; contains the specific error codes and messages.
- **adCount** `integer`: Total ads across all ad sets
- **adSetCount** `integer`: No description
- **budget** `object`: Effective budget (back-compat). For CBO this mirrors `campaignBudget`, for ABO this mirrors the child ad-set budget. Use `budgetLevel` to disambiguate.
  - **amount** `number`: 
  - **type** `string`:  - one of: daily, lifetime
- **campaignBudget** `object`: 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.
  - **amount** `number`: 
  - **type** `string`:  - one of: daily, lifetime
- **budgetLevel** `string`: 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. - one of: campaign, adset
- **isBudgetScheduleEnabled** `boolean`: Meta-only. Mirrors Campaign.is_budget_schedule_enabled — true when the campaign uses budget scheduling (time-based budget changes). Independent of CBO/ABO. (default: false)
- **currency** `string`: 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**: No description
- **platformAdAccountId** `string`: No description
- **platformAdAccountName** `string`: Human-readable advertiser/account name from the platform. Refreshed on every sync.
- **accountId** `string`: No description
- **profileId** `string`: No description
- **advertisingChannelType** `string`: Google-only. Raw campaign.advertising_channel_type (SEARCH, PERFORMANCE_MAX, VIDEO, DEMAND_GEN, DISPLAY, SHOPPING, ...). Serving surface, distinct from platformObjective (advertiser intent). Null/absent for non-Google platforms.
- **platformObjective** `string`: Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC)
- **optimizationGoal** `string`: Meta optimization goal shared across ad sets, or comma-separated values when ad sets differ (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION)
- **bidStrategy**: Campaign-level bid strategy. Ad sets inherit this unless they override.
- **bidAmount** `number`: Representative bid cap for the campaign — bubbled up from the top-spending ad set's `bid_amount` (whole currency units). Populated when the ad-set bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP.
- **roasAverageFloor** `number`: Representative ROAS floor for the campaign — bubbled up from the top-spending ad set. Decimal multiplier (2.0 = 2.0x).
- **promotedObject** `object`: Meta promoted object at campaign level (conversion event details)
  - **custom_event_type** `string`: 
  - **pixel_id** `string`: 
  - **page_id** `string`: 
- **adSets** `array`: No description

## Pagination

### Properties

- **page** `integer`: No description
- **limit** `integer`: No description
- **total** `integer`: No description
- **pages** `integer`: No description

---

# Get daily aggregate ad metrics for an account API Reference

Returns daily aggregate metrics across all ads in a SocialAccount as a single
time series — one row per calendar day in the requested range. Use this for
dashboards that draw a daily-spend or daily-conversions chart, instead of
calling `/v1/ads/tree` once per day.

`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) — same convention as `/v1/ads/tree` and `/v1/ads`.

Date range defaults to the last 90 days. Capped at 730 days. Ranges older
than the 90-day cache window trigger an on-demand backfill from the platform
before returning.


## GET /v1/ads/timeline

**Get daily aggregate ad metrics for an account**

Returns daily aggregate metrics across all ads in a SocialAccount as a single
time series — one row per calendar day in the requested range. Use this for
dashboards that draw a daily-spend or daily-conversions chart, instead of
calling `/v1/ads/tree` once per day.

`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) — same convention as `/v1/ads/tree` and `/v1/ads`.

Date range defaults to the last 90 days. Capped at 730 days. Ranges older
than the 90-day cache window trigger an on-demand backfill from the platform
before returning.


### Parameters

- **accountId** (required) in query: Social account ID. Sibling-expanded to its linked posting↔ads pair.
- **adAccountId** (optional) in query: 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.
- **fromDate** (optional) in query: Inclusive start of metrics range (YYYY-MM-DD). Defaults to 90 days ago.
- **toDate** (optional) in query: Inclusive end of metrics range (YYYY-MM-DD). Defaults to today. Max 730-day range.
- **platform** (optional) in query: Restrict to one platform.

### Responses

#### 200: Daily time series of aggregate metrics. Empty `rows` means the account has no ad activity in the range.

**Response Body:**

- **rows** `array[object]`: 
  - **date** `string` (date): No description
  - **spend** `number`: Native currency units (matches /ads/tree convention).
  - **impressions** `integer`: No description
  - **reach** `integer`: No description
  - **clicks** `integer`: No description
  - **engagement** `integer`: No description
  - **ctr** `number`: Click-through rate as a percentage (0–100).
  - **cpc** `number`: Cost per click in native currency.
  - **cpm** `number`: Cost per 1000 impressions in native currency.
  - **conversions** `integer`: Sum of conversion events matching the campaign optimization goal. Meta-only at time of writing.
  - **costPerConversion** `number`: No description
  - **actions** `object`: Per-action-type counts merged across all ads on this day. Keys are platform-native action types.
  - **actionValues** `object`: Monetary mirror of `actions` in native currency.
  - **purchaseValue** `number`: Sum of purchase-type action values on this day, native currency.
  - **roas** `number`: Derived purchaseValue / spend.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

---

---

# List campaigns API Reference

Returns campaigns as virtual aggregations over ad documents grouped by platform campaign ID.
Metrics (spend, impressions, clicks, etc.) are summed across all ads in each campaign.
Campaign status is derived from child ad statuses (active > pending_review > paused > error > completed > cancelled > rejected).


## GET /v1/ads/campaigns

**List campaigns**

Returns campaigns as virtual aggregations over ad documents grouped by platform campaign ID.
Metrics (spend, impressions, clicks, etc.) are summed across all ads in each campaign.
Campaign status is derived from child ad statuses (active > pending_review > paused > error > completed > cancelled > rejected).


### Parameters

- **undefined** (optional): No description
- **limit** (optional) in query: No description
- **source** (optional) in query: `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.
- **platform** (optional) in query: No description
- **status** (optional) in query: Filter by derived campaign status (post-aggregation)
- **adAccountId** (optional) in query: Platform ad account ID (e.g. act_123 for Meta)
- **accountId** (optional) in query: Social account ID
- **profileId** (optional) in query: Profile ID
- **fromDate** (optional) in query: Start of metrics date range (YYYY-MM-DD, inclusive). Defaults to 90 days ago when both date params are omitted.
- **toDate** (optional) in query: End of metrics date range (YYYY-MM-DD, inclusive). Defaults to today. Max 730-day range.

### Responses

#### 200: Paginated campaigns

**Response Body:**

- **campaigns** `array[AdCampaign]`: 
- **pagination**: `Pagination` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

---


# Related Schema Definitions

## AdCampaign

### Properties

- **platformCampaignId** `string`: No description
- **platform** `string`: No description - one of: facebook, instagram, tiktok, linkedin, pinterest, google, twitter
- **campaignName** `string`: No description
- **status**: Delivery status derived from child ad statuses. Distinct from `reviewStatus`.
- **reviewStatus** `string`: Platform-side review state of the campaign. See AdTreeCampaign.reviewStatus for the full description. - one of: in_review, approved, rejected, with_issues
- **platformCampaignStatus** `string`: Raw platform-level campaign status (Meta `effective_status`).
- **campaignIssuesInfo** `array`: Platform-reported campaign issues (Meta `issues_info[]`).
- **adCount** `integer`: No description
- **budget** `object`: Effective budget (back-compat). Use `budgetLevel` to disambiguate CBO vs ABO.
  - **amount** `number`: 
  - **type** `string`:  - one of: daily, lifetime
- **campaignBudget** `object`: Campaign-level budget (CBO). Null for ABO campaigns.
  - **amount** `number`: 
  - **type** `string`:  - one of: daily, lifetime
- **budgetLevel** `string`: Canonical CBO/ABO indicator. See AdTreeCampaign.budgetLevel. - one of: campaign, adset
- **isBudgetScheduleEnabled** `boolean`: Meta-only. Mirrors Campaign.is_budget_schedule_enabled. (default: false)
- **currency** `string`: ISO 4217 currency code for all budget amounts. Budgets are NOT normalized to USD.
- **metrics**: No description
- **platformAdAccountId** `string`: No description
- **platformAdAccountName** `string`: Human-readable advertiser/account name from the platform. Refreshed on every sync.
- **accountId** `string`: No description
- **profileId** `string`: No description
- **advertisingChannelType** `string`: Google-only. Raw campaign.advertising_channel_type. See AdTreeCampaign.advertisingChannelType.
- **platformObjective** `string`: Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC)
- **optimizationGoal** `string`: Meta optimization goal shared across ad sets, or comma-separated values when ad sets differ (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION)
- **bidStrategy**: Campaign-level bid strategy. Ad sets inherit this unless they override.
- **bidAmount** `number`: Representative bid cap from the top-spending ad set (whole currency units). Populated when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP.
- **roasAverageFloor** `number`: Representative ROAS floor from the top-spending ad set. Decimal multiplier (2.0 = 2.0x).
- **promotedObject** `object`: Meta promoted object at campaign level (conversion event details)
  - **custom_event_type** `string`: 
  - **pixel_id** `string`: 
  - **page_id** `string`: 
- **earliestAd** `string`: No description
- **latestAd** `string`: No description

## Pagination

### Properties

- **page** `integer`: No description
- **limit** `integer`: No description
- **total** `integer`: No description
- **pages** `integer`: No description

---

# Pause or resume a campaign API Reference

Updates the status of all ads in a campaign. Makes one platform API call (not per-ad) since status cascades through the campaign hierarchy.
Ads in terminal statuses (rejected, completed, cancelled) are automatically skipped.


## PUT /v1/ads/campaigns/{campaignId}/status

**Pause or resume a campaign**

Updates the status of all ads in a campaign. Makes one platform API call (not per-ad) since status cascades through the campaign hierarchy.
Ads in terminal statuses (rejected, completed, cancelled) are automatically skipped.


### Parameters

- **campaignId** (required) in path: Platform campaign ID

### Request Body

- **status** (required) `string`: No description - one of: active, paused
- **platform** (required) `string`: No description - one of: facebook, instagram, tiktok, linkedin, pinterest, google, twitter

### Responses

#### 200: Campaign status updated

**Response Body:**

- **updated** `integer`: Number of ads updated
- **skipped** `integer`: Number of ads skipped
- **skippedReasons** `array[string]`: 
- **message** `string`: Human-readable summary (present when no ads were actionable)

#### 400: Invalid input or campaign spans multiple social accounts

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: No ads found for this campaign

---

---

# Update a campaign (budget and/or bid strategy) API Reference

Campaign-level edits. At least one of `budget` or `bidStrategy` is required.

- `budget` updates the CBO (Campaign Budget Optimization) budget. For ABO campaigns
  (where the budget lives on the ad set), use PUT /v1/ads/ad-sets/{adSetId} instead — this endpoint
  will return 409 with code BUDGET_LEVEL_MISMATCH.
- `bidStrategy` sets the campaign-level default bid strategy. Per Meta's spec, `bid_amount` and
  `bid_constraints` do NOT exist at the campaign level — pass them via PUT /v1/ads/ad-sets/{adSetId}.

Meta-only for now. Other platforms return 501 Not Implemented.


## PUT /v1/ads/campaigns/{campaignId}

**Update a campaign (budget and/or bid strategy)**

Campaign-level edits. At least one of `budget` or `bidStrategy` is required.

- `budget` updates the CBO (Campaign Budget Optimization) budget. For ABO campaigns
  (where the budget lives on the ad set), use PUT /v1/ads/ad-sets/{adSetId} instead — this endpoint
  will return 409 with code BUDGET_LEVEL_MISMATCH.
- `bidStrategy` sets the campaign-level default bid strategy. Per Meta's spec, `bid_amount` and
  `bid_constraints` do NOT exist at the campaign level — pass them via PUT /v1/ads/ad-sets/{adSetId}.

Meta-only for now. Other platforms return 501 Not Implemented.


### Parameters

- **campaignId** (required) in path: Platform campaign ID

### Request Body

- **platform** (required) `string`: No description - one of: facebook, instagram
- **budget** `object`: No description
- **bidStrategy**: Campaign-level default. Ad sets inherit this unless they override.
- **name** `string`: Rename the campaign (Meta only; other platforms return 501). At least one of budget/bidStrategy/name is required.

### Responses

#### 200: Campaign updated

**Response Body:**

- **updated** `integer`: No description
- **budget**: `AdBudget` - See schema definition
- **budgetLevel** `string`: No description - one of: campaign
- **bidStrategy**: `BidStrategy` - See schema definition

#### 400: Invalid input

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Campaign not found

#### 409: Campaign is ABO — route to /v1/ads/ad-sets/{adSetId} instead

#### 501: Operation not supported on this platform

---

## DELETE /v1/ads/campaigns/{campaignId}

**Delete a campaign**

Deletes the whole campaign on the platform, cascading to its ad sets
and ads. Locally, all Ad documents for this campaign are marked
`status: cancelled`.

Meta-only for now. Other platforms return 501 Not Implemented — fall
back to DELETE /v1/ads/{adId} per ad in the meantime.


### Parameters

- **campaignId** (required) in path: Platform campaign ID

### Request Body

- **platform** (required) `string`: No description - one of: facebook, instagram

### Responses

#### 200: Campaign deleted

**Response Body:**

- **deleted** `boolean`: No description
- **adCount** `integer`: Number of local Ad docs marked cancelled

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Campaign not found

#### 501: Operation not supported on this platform

---


# Related Schema Definitions

## AdBudget

Budget amount in the ad account's native currency (see the campaign's `currency` field for the code).

### Properties

- **amount** (required) `number`: No description
- **type** (required) `string`: No description - one of: daily, lifetime

## BidStrategy

Meta bid strategy. Same enum applies at campaign and ad-set level; ad-set value (when set)
overrides campaign-level. Cross-field rules:
  - `LOWEST_COST_WITHOUT_CAP` (default): auto-bid, forbids `bidAmount` and `roasAverageFloor`.
  - `LOWEST_COST_WITH_BID_CAP` / `COST_CAP`: require `bidAmount` (whole currency units).
  - `LOWEST_COST_WITH_MIN_ROAS`: requires `roasAverageFloor` (decimal multiplier, 2.0 = 2.0x).
Source: facebook-business-sdk-codegen api_specs/specs/enum_types.json (`AdSet_bid_strategy`,
`Campaign_bid_strategy`).

---

# Pause or resume a single ad set API Reference

Ad-set-scoped pause/resume (doesn't touch sibling ad sets). 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.


## PUT /v1/ads/ad-sets/{adSetId}/status

**Pause or resume a single ad set**

Ad-set-scoped pause/resume (doesn't touch sibling ad sets). 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.


### Parameters

- **adSetId** (required) in path: Platform ad set ID

### Request Body

- **status** (required) `string`: No description - one of: active, paused
- **platform** (required) `string`: No description - one of: facebook, instagram, tiktok, linkedin, pinterest, google, twitter

### Responses

#### 200: Ad set status updated

**Response Body:**

- **updated** `integer`: No description
- **skipped** `integer`: No description

#### 400: Invalid input

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Ad set not found

---

---

# Update an ad set (budget, status, and/or bid strategy) API Reference

Ad-set-level writes. Use this for ABO budget updates, ad-set-scoped
pause/resume, and bid-strategy edits. At least one of `budget`,
`status`, or `bidStrategy` is required.

Bid strategy compatibility (per Meta's spec):
- `LOWEST_COST_WITHOUT_CAP`: no `bidAmount`, no `roasAverageFloor`.
- `LOWEST_COST_WITH_BID_CAP` / `COST_CAP`: `bidAmount` REQUIRED (whole currency units).
- `LOWEST_COST_WITH_MIN_ROAS`: `roasAverageFloor` REQUIRED (decimal multiplier, e.g. 2.0 = 2.0x ROAS).

When updating `budget` on an ABO campaign: if the parent campaign is
CBO, the response is 409 with code BUDGET_LEVEL_MISMATCH — route to
PUT /v1/ads/campaigns/{campaignId} instead.


## PUT /v1/ads/ad-sets/{adSetId}

**Update an ad set (budget, status, and/or bid strategy)**

Ad-set-level writes. Use this for ABO budget updates, ad-set-scoped
pause/resume, and bid-strategy edits. At least one of `budget`,
`status`, or `bidStrategy` is required.

Bid strategy compatibility (per Meta's spec):
- `LOWEST_COST_WITHOUT_CAP`: no `bidAmount`, no `roasAverageFloor`.
- `LOWEST_COST_WITH_BID_CAP` / `COST_CAP`: `bidAmount` REQUIRED (whole currency units).
- `LOWEST_COST_WITH_MIN_ROAS`: `roasAverageFloor` REQUIRED (decimal multiplier, e.g. 2.0 = 2.0x ROAS).

When updating `budget` on an ABO campaign: if the parent campaign is
CBO, the response is 409 with code BUDGET_LEVEL_MISMATCH — route to
PUT /v1/ads/campaigns/{campaignId} instead.


### Parameters

- **adSetId** (required) in path: Platform ad set ID

### Request Body

- **platform** (required) `string`: No description - one of: facebook, instagram, tiktok, linkedin, pinterest, google, twitter
- **budget** `object`: Omit if not updating budget
- **status** `string`: Omit if not toggling delivery state - one of: active, paused
- **name** `string`: Rename the ad set (Meta only; other platforms return 501). At least one of budget/status/bidStrategy/name is required.
- **bidStrategy**: Ad-set-level bid strategy. Overrides the campaign-level default.
Supported on Meta (facebook, instagram) and TikTok. On TikTok the
Meta-style enum is mapped to bid_type / bid_price / deep_bid_type
automatically. Other platforms (linkedin, pinterest, google, twitter)
return 501 Not Implemented when bidStrategy is set.

- **bidAmount** `number`: 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. Internally converted to Meta's
smallest-denomination integer.

- **roasAverageFloor** `number`: 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.


### Responses

#### 200: Ad set updated

**Response Body:**

- **budget**: `AdBudget` - See schema definition
- **budgetLevel** `string`: No description - one of: adset
- **status** `string`: No description - one of: active, paused
- **statusUpdated** `integer`: No description
- **statusSkipped** `integer`: No description
- **bidStrategy**: `BidStrategy` - See schema definition
- **bidAmount** `number`: No description
- **roasAverageFloor** `number`: No description

#### 400: Invalid input

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Ad set not found

#### 409: Campaign is CBO — route to /v1/ads/campaigns/{campaignId} instead

#### 501: bidStrategy not supported on the platform (Meta + TikTok only)

---


# Related Schema Definitions

## AdBudget

Budget amount in the ad account's native currency (see the campaign's `currency` field for the code).

### Properties

- **amount** (required) `number`: No description
- **type** (required) `string`: No description - one of: daily, lifetime

## BidStrategy

Meta bid strategy. Same enum applies at campaign and ad-set level; ad-set value (when set)
overrides campaign-level. Cross-field rules:
  - `LOWEST_COST_WITHOUT_CAP` (default): auto-bid, forbids `bidAmount` and `roasAverageFloor`.
  - `LOWEST_COST_WITH_BID_CAP` / `COST_CAP`: require `bidAmount` (whole currency units).
  - `LOWEST_COST_WITH_MIN_ROAS`: requires `roasAverageFloor` (decimal multiplier, 2.0 = 2.0x).
Source: facebook-business-sdk-codegen api_specs/specs/enum_types.json (`AdSet_bid_strategy`,
`Campaign_bid_strategy`).

---

# Associate campaigns with a conversion destination API Reference

Associate one or more campaigns with this conversion rule. Returns a
per-campaign success/failure result so callers can retry only the
rows that failed (e.g. wrong campaign type for the rule's objective).


## GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations

**List campaigns associated with a conversion destination**

LinkedIn-only today. Returns the campaigns currently associated with
this conversion rule. Note that auto-association on rule creation
runs once at create time; campaigns created after the rule still need
explicit association.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (required) in query: No description

### Responses

#### 200: Associations listed

**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **associations** `array[object]`: 
  - **campaignId** `string`: No description
  - **conversionId** `string`: No description
  - **associatedAt** `integer`: Epoch ms.

#### 400: Validation error.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support associations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## POST /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations

**Associate campaigns with a conversion destination**

Associate one or more campaigns with this conversion rule. Returns a
per-campaign success/failure result so callers can retry only the
rows that failed (e.g. wrong campaign type for the rule's objective).


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description

### Request Body

- **adAccountId** (required) `string`: No description
- **campaignIds** (required) `array`: No description

### Responses

#### 200: Per-campaign batch result. Status is 200 even when some rows
failed — inspect `failed[]` for details. Inputs that fail local
URN validation are bucketed into `failed` without ever hitting
LinkedIn.


**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **succeeded** `array[string]`: Numeric campaign IDs that were successfully associated.
- **failed** `array[object]`: 
  - **campaignId** `string`: No description
  - **reason** `string`: No description

#### 400: Invalid body.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support associations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations

**Remove campaign↔conversion associations**

Remove one or more campaign associations from this conversion rule.
Pass `adAccountId` and `campaignIds` as query parameters
(`campaignIds` is comma-separated). The route also accepts a JSON
body with the same fields for clients that prefer DELETE-with-body,
but 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.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (required) in query: No description
- **campaignIds** (required) in query: Comma-separated list of campaign IDs.

### Responses

#### 200: Per-campaign batch result. Status is 200 even when some rows
failed — inspect `failed[]` for details.


**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **succeeded** `array[string]`: Numeric campaign IDs that were successfully removed.
- **failed** `array[object]`: 
  - **campaignId** `string`: No description
  - **reason** `string`: No description

#### 400: Validation error: missing `adAccountId` or `campaignIds`, or
campaignIds exceeds 100 entries per request.


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support associations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

---

# Adjust already-uploaded conversions (Google only) API Reference

Adjust conversions that were previously uploaded via `POST /v1/ads/conversions` —
retract them, restate their value, or enhance them with first-party data. Requires
the Ads add-on.

**Google Ads only.** Google 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.

Adjustment types:

- `RETRACTION` — remove the conversion entirely (refund, chargeback, cancelled order, churn).
- `RESTATEMENT` — change the conversion's value (upgrade / downgrade / partial refund). Send the corrected **total** value in `restatementValue` (not a delta).
- `ENHANCEMENT` — attach first-party identifiers (hashed email / phone) to an existing conversion (enhanced conversions applied after the fact).

Identifying the original conversion (per adjustment):

- `orderId` — the transaction ID you sent as `eventId` on the original conversion. Recommended, and **required** for `ENHANCEMENT`.
- or `gclid` + `conversionTime` — the click ID and the original conversion's time (unix seconds). Not available for `ENHANCEMENT`.

`destinationId` is the conversion action resource name, e.g.
`customers/1234567890/conversionActions/987654321` (same value you send to
`POST /v1/ads/conversions`). PII in `user` is hashed with SHA-256 server-side
(Gmail-specific normalization included). Send plaintext.

Times are unix seconds; we convert to Google's required
`yyyy-MM-dd HH:mm:ss+00:00` format. Up to 2000 adjustments per request; partial
failure is supported (inspect `adjustmentsFailed` / `failures[]`).


## POST /v1/ads/conversions/adjustments

**Adjust already-uploaded conversions (Google only)**

Adjust conversions that were previously uploaded via `POST /v1/ads/conversions` —
retract them, restate their value, or enhance them with first-party data. Requires
the Ads add-on.

**Google Ads only.** Google 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.

Adjustment types:

- `RETRACTION` — remove the conversion entirely (refund, chargeback, cancelled order, churn).
- `RESTATEMENT` — change the conversion's value (upgrade / downgrade / partial refund). Send the corrected **total** value in `restatementValue` (not a delta).
- `ENHANCEMENT` — attach first-party identifiers (hashed email / phone) to an existing conversion (enhanced conversions applied after the fact).

Identifying the original conversion (per adjustment):

- `orderId` — the transaction ID you sent as `eventId` on the original conversion. Recommended, and **required** for `ENHANCEMENT`.
- or `gclid` + `conversionTime` — the click ID and the original conversion's time (unix seconds). Not available for `ENHANCEMENT`.

`destinationId` is the conversion action resource name, e.g.
`customers/1234567890/conversionActions/987654321` (same value you send to
`POST /v1/ads/conversions`). PII in `user` is hashed with SHA-256 server-side
(Gmail-specific normalization included). Send plaintext.

Times are unix seconds; we convert to Google's required
`yyyy-MM-dd HH:mm:ss+00:00` format. Up to 2000 adjustments per request; partial
failure is supported (inspect `adjustmentsFailed` / `failures[]`).


### Request Body

- **accountId** (required) `string`: SocialAccount ID. Must be a `googleads` account.
- **destinationId** (required) `string`: Conversion action resource name, e.g. `customers/1234567890/conversionActions/987654321`.
- **adjustments** (required) `array`: No description

### Responses

#### 200: Adjustments processed. Inspect `adjustmentsFailed` and `failures[]` for
partial failure (Google reports per-row errors via partial failure).


**Response Body:**

- **platform** `string`: No description - one of: googleads
- **adjustmentsReceived** `integer`: Adjustments accepted by Google.
- **adjustmentsFailed** `integer`: Adjustments rejected (see failures).
- **failures** `array[object]`: 
  - **adjustmentIndex** `integer`: Index into the submitted adjustments array.
  - **message** `string`: No description
  - **code**: One of multiple types
- **traceId** `string`: No description

#### 400: Invalid body, or a malformed adjustment (missing key, missing restatementValue for RESTATEMENT, missing identifiers for ENHANCEMENT).

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans).

#### 404: Account not found or not accessible.

#### 405: Conversion adjustments are only available for Google Ads (the account's platform is not `googleads`).

---

---

# Archive a Lead Gen form API Reference

Meta has no hard delete for forms; this archives the form (status=ARCHIVED).

## GET /v1/ads/lead-forms/{formId}

**Get a single Lead Gen form**

### Parameters

- **formId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Form metadata.

**Response Body:**

- **status** `string`: No description
- **form** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/ads/lead-forms/{formId}

**Archive a Lead Gen form**

Meta has no hard delete for forms; this archives the form (status=ARCHIVED).

### Parameters

- **formId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Archived.

**Response Body:**

- **status** `string`: No description
- **formId** `string`: No description
- **archived** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Boost post as ad API Reference

Creates a paid ad campaign from an existing published post. Creates the full platform campaign hierarchy (campaign, ad set, ad).

## POST /v1/ads/boost

**Boost post as ad**

Creates a paid ad campaign from an existing published post. Creates the full platform campaign hierarchy (campaign, ad set, ad).

### Request Body

- **postId** `string`: Zernio post ID (provide this or platformPostId)
- **platformPostId** `string`: Platform post ID (alternative to postId)
- **accountId** (required) `string`: Social account ID
- **adAccountId** (required) `string`: Platform ad account ID
- **name** (required) `string`: No description
- **goal** (required) `string`: Available goals vary by platform. Meta (Facebook/Instagram) and TikTok support all 7. LinkedIn supports all except app_promotion. Twitter/X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views. - one of: engagement, traffic, awareness, video_views, lead_generation, conversions, app_promotion
- **budget** (required) `object`: No description
- **currency** `string`: No description
- **schedule** `object`: No description
- **targeting** `object`: No description
- **bidStrategy**: Meta bid strategy applied to the ad set. On TikTok, mapped to
`bid_type` / `bid_price` / `deep_bid_type` automatically.

- **bidAmount** `number`: 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`. Backward-compat: providing
`bidAmount` without `bidStrategy` is treated as `LOWEST_COST_WITH_BID_CAP`.

- **roasAverageFloor** `number`: Minimum ROAS as a decimal multiplier (e.g. 2.0 = 2.0x ROAS). Required when
`bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`. Sent to Meta as
`bid_constraints.roas_average_floor` × 10000 (Meta uses fixed-point integers).

- **tracking** `object`: Meta only. Tracking specs (pixel, URL tags).
- **specialAdCategories** `array`: Meta only. Required for housing, employment, credit, or political ads.
- **linkUrl** `string`: TikTok-only. Custom destination URL for the Spark Ad. Without this, TikTok
Spark Ads have no clickable destination — required for traffic / conversion
objectives. Maps to `landing_page_url` on the creative entry of /v2/ad/create/
(TikTok SDK `AdcreateCreatives.landing_page_url`). Ignored on Meta / LinkedIn /
Pinterest / X / Google (those infer the destination from the boosted post).

- **callToAction** `string`: TikTok-only. Call-to-action button label on the Spark Ad creative (e.g.
`LEARN_MORE`, `SHOP_NOW`, `DOWNLOAD_NOW`, `SIGN_UP`, `WATCH_NOW`). Maps to
`call_to_action` on the creative entry of /v2/ad/create/. Pass-through —
the platform validates the value. See TikTok's "Enumeration - Call-to-Action"
reference for the full list.

- **sparkAuthCode** `string`: TikTok-only. Spark Code (creator's `auth_code`) authorizing cross-creator
Spark Ads — the advertiser can boost a video owned by a DIFFERENT TikTok
account. Without this, 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. Maps to `auth_code` on the creative entry of /v2/ad/create/.

- **dsaBeneficiary** `string`: Name of the legal entity benefiting from the ad.
Required by Meta when targeting EU users (DSA Article 26).
Not enforced at schema level; enforced server-side when targeting intersects EU member states.

- **dsaPayor** `string`: Name of the legal entity paying for the ad.
Required by Meta when targeting EU users (DSA Article 26).
Note Meta API spelling: dsa_payor (not dsa_payer).


### Responses

#### 201: Ad created

**Response Body:**

- **ad**: `Ad` - See schema definition
- **message** `string`: No description

#### 400: Missing required fields or invalid values

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

#### 422: 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. Returned with code
`ads_connection_required`; the message includes the actionable
"TikTok Ads Manager → Assets → Identity" remediation step.


---


# Related Schema Definitions

## Ad

### Properties

- **_id** `string`: No description
- **name** `string`: No description
- **platform** `string`: No description - one of: facebook, instagram, tiktok, linkedin, pinterest, google, twitter
- **status**: No description
- **adType** `string`: No description - one of: boost, standalone
- **goal** `string`: Available goals vary by platform. Meta (Facebook/Instagram) supports all 9 (incl. `lead_conversion` = website pixel lead optimization and `catalog_sales` = Advantage+ catalog ads). TikTok supports the 7 non-`lead_conversion` goals. LinkedIn supports all except app_promotion / lead_conversion. Twitter/X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views. - one of: engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales
- **isExternal** `boolean`: True for ads synced from platform ad managers
- **budget** `object`: 
  - **amount** `number`: 
  - **type** `string`:  - one of: daily, lifetime
- **metrics**: No description
- **platformAdId** `string`: No description
- **platformAdAccountId** `string`: No description
- **platformCampaignId** `string`: No description
- **platformAdSetId** `string`: No description
- **campaignName** `string`: No description
- **adSetName** `string`: No description
- **platformObjective** `string`: Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC). Only present for Meta ads.
- **optimizationGoal** `string`: Meta ad set optimization goal (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION, LINK_CLICKS). Only present for Meta ads.
- **platformAdAccountName** `string`: Human-readable advertiser/account name (Meta `AdAccount.name`, TikTok
`advertiser_name`, LinkedIn / X / Pinterest equivalents). Refreshed every
sync so platform-side renames propagate within one cycle. `null` when the
platform doesn't return a name or the sync hasn't run yet.

- **platformCreatedAt** `string`: Platform-reported creation timestamp (Meta `created_time`, TikTok `create_time`).
Distinct from `createdAt` which reflects when Zernio first synced the doc — for
sort/filter by "when the ad was actually created on the platform", read this field.
`null` for legacy ads synced before this field was added; aggregations fall back
to `createdAt` in that case.

- **bidStrategy**: Ad-set bid strategy (overrides campaign level on Meta). Populated for Meta and
TikTok. TikTok's native `bid_type` is normalized to the cross-platform Meta enum:
`BID_TYPE_NO_BID` -> `LOWEST_COST_WITHOUT_CAP`, `BID_TYPE_CUSTOM` ->
`LOWEST_COST_WITH_BID_CAP`, deep_bid_type=MIN_ROAS or roas_bid>0 ->
`LOWEST_COST_WITH_MIN_ROAS`, `BID_TYPE_MAX_CONVERSION` -> `LOWEST_COST_WITHOUT_CAP`.

- **bidAmount** `number`: Bid cap in WHOLE currency units of the ad account (USD: 5 = $5.00; JPY: 100 = ¥100).
Populated when bidStrategy is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`. `null` for
auto-bid (`LOWEST_COST_WITHOUT_CAP`).

- Meta source: `bid_amount` on the ad set (smallest-denomination int, decoded here).
- TikTok source: priority order `bid_price` -> `conversion_bid_price` -> `deep_cpa_bid`
  (whichever is set on the ad group). TikTok stores all three in whole currency units.

Source: facebook-business-sdk-codegen api_specs/specs/AdSet.json (`bid_amount`).

- **roasAverageFloor** `number`: Minimum ROAS as a decimal multiplier (2.0 = 2.0x ROAS). Populated when bidStrategy
is `LOWEST_COST_WITH_MIN_ROAS`.

- Meta source: decoded from `bid_constraints.roas_average_floor` (Meta stores as
  fixed-point int × 10000; we return the decimal).
- TikTok source: `roas_bid` on the ad group (already a decimal).

Source: facebook-business-sdk-codegen api_specs/specs/AdCampaignBidConstraint.json.

- **promotedObject** `object`: Meta promoted object containing conversion event details. Structure varies by objective. Only present for Meta ads.
  - **custom_event_type** `string`: Conversion event type (e.g. PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART)
  - **pixel_id** `string`: Meta pixel ID
  - **page_id** `string`: Facebook page ID
  - **application_id** `string`: Facebook app ID
  - **product_set_id** `string`: Product catalog set ID
- **creative** `object`: Platform-specific creative data. Fields vary by platform.
  - **thumbnailUrl** `string`: Primary thumbnail/image URL
  - **imageUrl** `string`: Alternative image URL
  - **videoId** `string`: Meta video ID for VIDEO-type ads. Null for non-video ads. Callers that need an embeddable MP4 can call GET /{videoId}?fields=source with the page access token.
  - **videoUrl** `string`: Public Facebook watch URL for VIDEO-type ads (https://www.facebook.com/watch/?v={videoId}). Null for non-video ads.
  - **objectType** `string`: 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** `string`: Meta creative `object_story_id` (the SHARE reference). Frequently absent — Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead.
  - **effectiveObjectStoryId** `string`: Meta `effective_object_story_id` — `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. Pass to GET /v1/ads?effectiveObjectStoryId= to map a Business-Manager-visible post back to this ad; GET /v1/ads/{adId}/comments resolves comments against it.
  - **effectiveInstagramMediaId** `string`: 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** `string`: Meta `instagram_user_id` — the Instagram-scoped business ID that owns the boosted media.
  - **instagramPermalinkUrl** `string`: Meta `instagram_permalink_url` — public Instagram post URL of the boosted media.
  - **mediaUrls** `array`: 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).
  - **body** `string`: Ad copy/text
  - **googleHeadline** `string`: Google Ads headline
  - **googleDescription** `string`: Google Ads description
  - **linkUrl** `string`: Destination URL
  - **pinterestImageUrl** `string`: 
  - **pinterestTitle** `string`: 
  - **pinterestDescription** `string`: 
- **targeting** `object`: The ad set's targeting (age, gender, geo, interests, placements, audience inclusions/exclusions).
For ads created through Zernio this is the spec you supplied. For external ads (synced from
Meta Ads Manager, `isExternal: true`) targeting lives at the ad set and isn't stored at ingest,
so on the first `GET /v1/ads/{adId}` Zernio resolves it live from Meta and caches it on the ad;
the value is then Meta's raw `targeting` shape (snake_case, e.g. `geo_locations`, `age_min`),
the same object Ads Manager shows. May be absent if the ad set exposes no targeting or the lookup fails.

- **schedule** `object`: 
  - **startDate** `string`: 
  - **endDate** `string`: 
- **rejectionReason** `string`: No description
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

---

# Create a conversion destination (LinkedIn, Google Ads) API Reference

Create a new conversion destination on the platform. Supported for
LinkedIn (conversion rule) and Google Ads (conversion action). Meta
manages destinations in its own UI and returns 405.

**LinkedIn:** creation is NOT idempotent. A retry creates a second
destination. Deduplicate before retrying.

**Google Ads:** calling 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.

**LinkedIn:** the 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.

365-day attribution windows are only valid for `SUBMIT_APPLICATION`,
`PURCHASE`, `ADD_TO_CART`, `QUALIFIED_LEAD`, and `LEAD` rule types;
the API rejects other combinations locally.

**Google Ads:** the conversion action is created with
`type=UPLOAD_CLICKS` (required for API-uploaded offline conversions,
immutable after creation). The `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. The action defaults to
secondary (non-primary) to avoid immediately steering Smart Bidding;
pass `primaryForGoal: true` to opt in.


## GET /v1/accounts/{accountId}/conversion-destinations

**List destinations for the Conversions API**

Returns the list of pixels (Meta), conversion actions (Google), or
conversion rules (LinkedIn) accessible to the connected ads account.
Use the returned `id` as `destinationId` when posting to
`POST /v1/ads/conversions`.

For Google and LinkedIn, each destination's `type` reflects the
conversion type (PURCHASE, LEAD, SIGN_UP, etc.) — the event type is
locked to the destination. For Meta, `type` is absent: pixels accept
any event name per request.

For LinkedIn, destinations are returned across every sponsored ad
account the connected token can access; the `adAccountId` field on
each destination identifies the parent ad account and is required for
subsequent CRUD calls (update, delete, associations, metrics).


### Parameters

- **accountId** (required) in path: SocialAccount ID (metaads, googleads, or linkedinads).

### Responses

#### 200: Destinations listed

**Response Body:**

- **platform** `string`: No description - one of: metaads, googleads, linkedinads
- **destinations** `array[object]`: 
  - **id** `string`: Destination identifier. Meta: pixel ID. Google:
conversion action resource name. LinkedIn:
numeric conversion rule ID.

  - **name** `string`: No description
  - **type** `string`: Present when the platform locks event type to the
destination (Google conversion actions, LinkedIn
conversion rules).

  - **status** `string`: No description - one of: active, inactive
  - **adAccountId** `string`: Set by adapters whose destinations are scoped to a
specific ad account (LinkedIn). Pass back on
subsequent CRUD calls.


#### 400: Account's platform is not supported by the Conversions API.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans),
OR (for LinkedIn) the connected account lacks the `rw_conversions` scope and must be reconnected.


#### 404: Account not found or not accessible.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## POST /v1/accounts/{accountId}/conversion-destinations

**Create a conversion destination (LinkedIn, Google Ads)**

Create a new conversion destination on the platform. Supported for
LinkedIn (conversion rule) and Google Ads (conversion action). Meta
manages destinations in its own UI and returns 405.

**LinkedIn:** creation is NOT idempotent. A retry creates a second
destination. Deduplicate before retrying.

**Google Ads:** calling 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.

**LinkedIn:** the 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.

365-day attribution windows are only valid for `SUBMIT_APPLICATION`,
`PURCHASE`, `ADD_TO_CART`, `QUALIFIED_LEAD`, and `LEAD` rule types;
the API rejects other combinations locally.

**Google Ads:** the conversion action is created with
`type=UPLOAD_CLICKS` (required for API-uploaded offline conversions,
immutable after creation). The `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. The action defaults to
secondary (non-primary) to avoid immediately steering Smart Bidding;
pass `primaryForGoal: true` to opt in.


### Parameters

- **accountId** (required) in path: SocialAccount ID (linkedinads or googleads).

### Request Body

- **adAccountId** (required) `string`: Ad account ID. For LinkedIn: numeric (e.g. "5123456") or
full `urn:li:sponsoredAccount:{id}` URN. For Google: numeric
customer ID (e.g. "1234567890") or `customers/{id}` form.

- **name** (required) `string`: No description
- **type** (required) `string`: Conversion type. For LinkedIn: a unified standard event name
(e.g. "Purchase", "Lead", "AddToCart") or a LinkedIn rule
type enum (e.g. "PURCHASE", "QUALIFIED_LEAD"). For 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"). Unknown values pass through to the
platform.

- **attributionType** `string`: LinkedIn only. - one of: LAST_TOUCH_BY_CAMPAIGN, LAST_TOUCH_BY_CONVERSION
- **postClickAttributionWindowSize** `integer`: LinkedIn only. Default 30. 365 only allowed for LEAD,
PURCHASE, ADD_TO_CART, QUALIFIED_LEAD, SUBMIT_APPLICATION
rule types; the API rejects other combinations locally.
 - one of: 1, 7, 30, 90, 365
- **viewThroughAttributionWindowSize** `integer`: LinkedIn only. Default 7. Same 365-day-window type
restriction applies as `postClickAttributionWindowSize`.
 - one of: 1, 7, 30, 90, 365
- **valueType** `string`: LinkedIn only. DYNAMIC (default) uses the per-event `value`
from `sendConversions`. FIXED uses the rule's `value` field.
NO_VALUE drops monetary value entirely.
 - one of: DYNAMIC, FIXED, NO_VALUE
- **value** `object`: LinkedIn only. Static conversion value. Used when
`valueType=FIXED`. The currency should match the ad
account's currency.

- **autoAssociationType** `string`: LinkedIn only. Controls campaign association at rule-creation
time:
- ALL_CAMPAIGNS: associate the rule with every active,
  paused, and draft campaign in the ad account
- OBJECTIVE_BASED: associate only campaigns whose
  objective matches the rule's type
- NONE: don't auto-associate. Manage associations via
  the `/associations` endpoints below.
Note: auto-association runs once at create time; new
campaigns added after the rule still need explicit
association.
 - one of: ALL_CAMPAIGNS, OBJECTIVE_BASED, NONE
- **countingType** `string`: Google Ads only. Whether to count multiple conversions from
the same click (MANY_PER_CLICK) or at most one
(ONE_PER_CLICK). Defaults to MANY_PER_CLICK if omitted.
 - one of: MANY_PER_CLICK, ONE_PER_CLICK
- **primaryForGoal** `boolean`: Google Ads only. When true, the conversion action is marked
as primary and immediately influences Smart Bidding. Defaults
to false (secondary, record-only) to avoid unintentionally
steering the customer's campaigns on creation.


### Responses

#### 201: Destination created

**Response Body:**

- **platform** `string`: No description - one of: linkedinads, googleads
- **destination**: `ConversionDestination` - See schema definition

#### 400: Invalid body or platform validation failure.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: 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).


#### 404: Account not found or not accessible.

#### 405: Platform does not support destination creation.

#### 409: Google Ads only. A conversion action with the given name already
exists but has a different category. Use a different name or use
the existing destination. Error code: `IDEMPOTENCY_CONFLICT`.


#### 429: Rate limit hit. Retry with backoff.

---


# Related Schema Definitions

## ConversionDestination

A discoverable conversion destination on an ad platform — a Meta pixel,
Google conversion action, or LinkedIn conversion rule. Returned by
`listConversionDestinations`, `getConversionDestination`,
`createConversionDestination`, and `updateConversionDestination`.


### Properties

- **id** (required) `string`: Platform-native identifier. Pass back as `destinationId` on event
send and as the path segment on CRUD endpoints.

- **name** (required) `string`: No description
- **type** `string`: Present when the platform locks the event type/category to the
destination (Google conversion actions, LinkedIn conversion rules).
Absent for Meta pixels (which accept any event name per request).

- **status** `string`: For LinkedIn, `inactive` means the rule is soft-deleted (`enabled: false`).
 - one of: active, inactive
- **adAccountId** `string`: Set by adapters whose destinations are scoped to a specific ad
account (LinkedIn). Pass back on subsequent CRUD calls to
identify the parent ad account.

---

# Create Click-to-WhatsApp ad(s) API Reference

Creates 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. The 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.

Supports two mutually-exclusive shapes:

- **Single-creative**: supply top-level `headline`, `body`, and one of
  `imageUrl` / `video`. Creates 1 campaign + 1 ad set + 1 ad.

- **Multi-creative**: supply a `creatives[]` array with N entries
  (each carrying its own headline, body, and image/video). Creates
  1 campaign + 1 ad set + N ads sharing budget and targeting so Meta
  A/Bs the creatives inside a single auction instead of fragmenting
  budget across N parallel campaigns. Recommended when launching
  multiple creative variants for the same campaign.


Prerequisites enforced by Meta (surfaced as platform_error on failure): the Facebook Page must be paired with a verified WhatsApp Business number, the WhatsApp Business Account must be business-verified, and the Meta access token must carry ads_management.


## POST /v1/ads/ctwa

**Create Click-to-WhatsApp ad(s)**

Creates 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. The 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.

Supports two mutually-exclusive shapes:

- **Single-creative**: supply top-level `headline`, `body`, and one of
  `imageUrl` / `video`. Creates 1 campaign + 1 ad set + 1 ad.

- **Multi-creative**: supply a `creatives[]` array with N entries
  (each carrying its own headline, body, and image/video). Creates
  1 campaign + 1 ad set + N ads sharing budget and targeting so Meta
  A/Bs the creatives inside a single auction instead of fragmenting
  budget across N parallel campaigns. Recommended when launching
  multiple creative variants for the same campaign.


Prerequisites enforced by Meta (surfaced as platform_error on failure): the Facebook Page must be paired with a verified WhatsApp Business number, the WhatsApp Business Account must be business-verified, and the Meta access token must carry ads_management.

### Request Body

- **accountId** (required) `string`: Facebook or Instagram SocialAccount ID.
- **adAccountId** (required) `string`: Meta ad account ID, e.g. `act_123456789`.
- **name** (required) `string`: Ad display name. Used to derive campaign / ad set names.
On the multi-creative shape, each ad's Meta name gets a
" #N" suffix (1-indexed) so Ads Manager shows them as a
numbered batch.

- **headline** `string`: Single-creative shape only. Mutually exclusive with
`creatives[]`.

- **body** `string`: Primary text shown above the image / video. Single-creative
shape only. Mutually exclusive with `creatives[]`.

- **imageUrl** `string`: Image asset for single-creative shape. Mutually exclusive
with `video` and with `creatives[]`. Required on the
single-creative shape if `video` is not supplied.

- **video** `object`: Video creative for single-creative shape. Mutually
exclusive with `imageUrl` and with `creatives[]`. Required
on the single-creative shape if `imageUrl` is not supplied.

- **creatives** `array`: Multi-creative shape: N CTWA ads under one campaign + one
ad set, sharing budget and targeting. Mutually exclusive
with the top-level single-creative fields (`headline` /
`body` / `imageUrl` / `video`). Each entry must supply its
own headline, body, and exactly one of `imageUrl` /
`video`.

- **budgetAmount** (required) `number`: Budget amount in the ad account's currency major units
(e.g. dollars for USD, not cents). Must be > 0.

- **budgetType** (required) `string`: No description - one of: daily, lifetime
- **currency** `string`: ISO 4217 currency code matching the ad account's currency
(e.g. `USD`). Optional; Meta infers from the ad account
when omitted.

- **endDate** `string`: ISO 8601 datetime. Required when `budgetType` is `lifetime`.

- **countries** `array`: ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only
when no other geo (`cities`, `regions`, `zips`, `metros`,
`customLocations`) is supplied.

- **cities** `array`: City-level geo targeting for local CTWA campaigns (e.g.
25km radius around Milan). Each entry maps to Meta's
TargetingGeoLocationCity. `key` is Meta's city ID
(lookupable via GET /v1/ads/targeting/search). `radius`
and `distance_unit` are coupled: set both or neither.

- **regions** `array`: Region / state-level geo targeting. `key` is Meta's region
ID (lookupable via GET /v1/ads/targeting/search?type=region).

- **zips** `array`: ZIP / postal-code geo targeting. `key` is the platform's
postal id resolved via /v1/ads/targeting/search.

- **metros** `array`: DMA / metro-area geo targeting. `key` is Meta's metro id
(e.g. `DMA:807`).

- **customLocations** `array`: Point-radius geo (Meta `geo_locations.custom_locations`).
Use for targeting a radius around a specific lat/long when
no Meta city/region key fits. `distanceUnit` is required.

- **ageMin** `integer`: No description
- **ageMax** `integer`: No description
- **interests** `array`: No description
- **audienceId** `string`: Custom audience ID to target.
- **advantageAudience** `integer`: Meta's Advantage+ audience expansion. `0` (default) keeps
targeting strict; `1` lets Meta expand beyond the supplied
targeting when its delivery system finds better matches.
Always sent on CREATE (Meta requires it).
 - one of: 0, 1
- **objective** `string`: Defaults to `OUTCOME_ENGAGEMENT` (the broadly-supported CTWA
objective). `OUTCOME_SALES` and `OUTCOME_LEADS` require
additional account configuration (Dataset linked to the WABA
for sales) and may be rejected by Meta if missing.
 - one of: OUTCOME_ENGAGEMENT, OUTCOME_SALES, OUTCOME_LEADS
- **bidStrategy** `string`: Meta bid strategy applied to the shared ad set. Defaults to
`LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted.
`LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require
`bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires
`roasAverageFloor`. CTWA's `optimization_goal` is fixed to
`CONVERSATIONS`, but the bid strategy is independent.
 - one of: LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS
- **bidAmount** `number`: Whole currency units (e.g. `5` = $5.00 on a USD account).
Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP`
or `COST_CAP`; rejected otherwise.

- **roasAverageFloor** `number`: Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor).
Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`;
rejected otherwise. Meta enforces its own upper bound
server-side.

- **dsaBeneficiary** `string`: Name of the legal entity benefiting from the ad.
Required by Meta when targeting EU users (DSA Article 26).
Not enforced at schema level; enforced server-side when targeting intersects EU member states.

- **dsaPayor** `string`: Name of the legal entity paying for the ad.
Required by Meta when targeting EU users (DSA Article 26).
Note Meta API spelling: dsa_payor (not dsa_payer).


### Responses

#### 201: CTWA ad(s) created and submitted to Meta for review. Response is a
tagged union discriminated by `adType`:

- `adType: "single"` → single-creative request: `{ adType, ad,
  message }` where `ad` is the persisted Ad document.
- `adType: "multi"` → multi-creative request: `{ adType, ads,
  platformCampaignId, platformAdSetId, message }` where `ads` is
  the array of N persisted Ad documents all sharing the returned
  campaign and ad set IDs.

Generated SDK clients can narrow on `adType` instead of sniffing
for field presence.


**Response Body:**

*One of the following:*
- `CtwaSingleResponse`
- `CtwaMultiResponse`

#### 400: Invalid body.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

#### 404: SocialAccount not found.

#### 422: Page is not connected to a verified WhatsApp number.

#### 502: Meta rejected the request (e.g. WABA business verification
missing). Inspect `platformError` for the upstream Meta payload.


---


# Related Schema Definitions

## CtwaSingleResponse

Response returned by `POST /v1/ads/ctwa` when the request used the
single-creative shape (top-level headline / body / imageUrl|video).
`adType` is the union discriminator.


### Properties

- **adType** (required) `string`: No description - one of: single
- **ad** (required) `object`: The persisted Ad document.
- **message** (required) `string`: No description

## CtwaMultiResponse

Response returned by `POST /v1/ads/ctwa` when the request used the
multi-creative shape (`creatives[]`). N persisted Ad documents share
the returned `platformCampaignId` and `platformAdSetId`. `adType` is
the union discriminator.


### Properties

- **adType** (required) `string`: No description - one of: multi
- **ads** (required) `array`: The persisted Ad documents (one per creative), all sharing the same
`platformCampaignId` and `platformAdSetId`.

- **platformCampaignId** (required) `string`: No description
- **platformAdSetId** (required) `string`: No description
- **message** (required) `string`: No description

---

# Create a Lead Gen (Instant) form API Reference

Creates a Lead Gen form on the connected Facebook Page (POST /{page-id}/leadgen_forms). NOT idempotent — a retry creates a second form. Prefilled question types (EMAIL, PHONE, FULL_NAME, …) must omit label/key; CUSTOM questions require both. Requires the Ads add-on.


## GET /v1/ads/lead-forms

**List Lead Gen (Instant) forms**

Lists the Lead Gen forms owned by the connected Facebook Page. Requires the Ads add-on.

### Parameters

- **accountId** (required) in query: Connected facebook account id.
- **limit** (optional) in query: No description
- **cursor** (optional) in query: No description

### Responses

#### 200: Forms list.

**Response Body:**

- **status** `string`: No description (example: "success")
- **forms** `array[object]`: 
  Type: `object`
- **pagination** `object`: 
  - **hasMore** `boolean`: No description
  - **cursor** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on required.

---

## POST /v1/ads/lead-forms

**Create a Lead Gen (Instant) form**

Creates a Lead Gen form on the connected Facebook Page (POST /{page-id}/leadgen_forms). NOT idempotent — a retry creates a second form. Prefilled question types (EMAIL, PHONE, FULL_NAME, …) must omit label/key; CUSTOM questions require both. Requires the Ads add-on.


### Request Body

- **accountId** (required) `string`: No description
- **name** (required) `string`: No description
- **questions** (required) `array`: No description
- **privacyPolicyUrl** (required) `string`: No description
- **privacyPolicyLinkText** `string`: No description
- **followUpActionUrl** `string`: No description
- **locale** `string`: No description
- **thankYouTitle** `string`: No description
- **thankYouBody** `string`: No description
- **thankYouButtonText** `string`: No description
- **thankYouButtonType** `string`: No description
- **thankYouWebsiteUrl** `string`: No description
- **isOptimizedForQuality** `boolean`: No description

### Responses

#### 200: Created form.

**Response Body:**

- **status** `string`: No description (example: "success")
- **form** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on required.

---

---

# Create standalone ad API Reference

Creates a paid ad with custom creative across Meta, Google Ads, Pinterest, TikTok, X/Twitter, and LinkedIn. Supports three mutually-exclusive request shapes selected by the body, a legacy single-creative shape (all platforms, default), a Meta-only multi-creative shape via the creatives array (one ad set with N ads sharing budget and targeting), and a Meta-only attach shape via adSetId (adds one new ad to an existing ad set). Per-platform required fields, budget minimums, and video-ad rules are documented on each property below. LinkedIn creates a Single Image or Single Video Ad backed by a Direct Sponsored Content "dark post" authored by a Company Page (see `organizationId`); supported goals are engagement, traffic, awareness, and video_views (video ads use the `video` field; video_views requires a video), and traffic ads require `linkUrl`.

**Idempotency:** this 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: the 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. Reusing a key with a different body returns 422; a key whose first request is still in flight returns 409 (retry after a short backoff). Keys are scoped to your credential and expire after 24h.

## POST /v1/ads/create

**Create standalone ad**

Creates a paid ad with custom creative across Meta, Google Ads, Pinterest, TikTok, X/Twitter, and LinkedIn. Supports three mutually-exclusive request shapes selected by the body, a legacy single-creative shape (all platforms, default), a Meta-only multi-creative shape via the creatives array (one ad set with N ads sharing budget and targeting), and a Meta-only attach shape via adSetId (adds one new ad to an existing ad set). Per-platform required fields, budget minimums, and video-ad rules are documented on each property below. LinkedIn creates a Single Image or Single Video Ad backed by a Direct Sponsored Content "dark post" authored by a Company Page (see `organizationId`); supported goals are engagement, traffic, awareness, and video_views (video ads use the `video` field; video_views requires a video), and traffic ads require `linkUrl`.

**Idempotency:** this 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: the 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. Reusing a key with a different body returns 422; a key whose first request is still in flight returns 409 (retry after a short backoff). Keys are scoped to your credential and expire after 24h.

### Parameters

- **Idempotency-Key** (optional) in header: Optional client-generated unique key (e.g. a UUID) that makes create retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409.

### Request Body

- **accountId** (required) `string`: No description
- **adAccountId** (required) `string`: No description
- **name** (required) `string`: No description
- **campaignName** `string`: Meta only. Exact campaign name. Overrides the default `<name> - Campaign`.
- **adSetName** `string`: Meta only. Exact ad set name. Overrides the default `<name> - Ad Set`. (For per-ad names on the multi-creative shape, set `name` on each `creatives[]` entry.)
- **adName** `string`: Meta only. Exact ad name (the single-creative ad object's name). Overrides the default, which is `name`. (For per-ad names on the multi-creative shape, set `name` on each `creatives[]` entry instead.)
- **tracking** `object`: Meta only. Attaches pixel measurement to the ad regardless of the optimization goal (the "Website events" tracking row in Ads Manager). `pixelId` becomes the ad's `tracking_specs` (offsite_conversion + fb_pixel); `urlTags` becomes the ad's `url_tags` (click-tracking query params). Applied on the legacy single-creative shape, every ad of the multi-creative shape, and the attach shape. NOTE: 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.
- **goal** `string`: Required on legacy + multi-creative shapes. Inherited from the ad set on the attach shape. Available goals vary by platform. Meta-specific: `conversions` (OUTCOME_SALES) requires `promotedObject.pixelId` + `promotedObject.customEventType` (use a commerce event, e.g. PURCHASE, START_TRIAL); `lead_conversion` (OUTCOME_LEADS, website pixel leads) requires the same pixel + event but with a leads-class event (e.g. LEAD, SUBMIT_APPLICATION, SCHEDULE, CONTACT) — these are rejected under `conversions` because Meta gates conversion events by objective; `lead_generation` is OUTCOME_LEADS with instant forms (`leadGenFormId`), distinct from `lead_conversion`'s website pixel optimization; `app_promotion` requires `promotedObject.applicationId` + `promotedObject.objectStoreUrl`; `catalog_sales` (Advantage+ catalog ads, e.g. vehicle inventory) requires `promotedObject.productSetId` + `promotedObject.pixelId` + `promotedObject.customEventType` and builds a catalog TEMPLATE creative from the copy fields (headline/body/description/linkUrl/callToAction, which may carry catalog template tags like {{product.name}} or {{vehicle.make}}) — no imageUrl/video is sent, Meta renders the visuals per catalog item; discover catalogs via GET /v1/ads/catalogs and product sets via GET /v1/ads/catalogs/{catalogId}/product-sets; single shape only (no creatives[]/adSetId/dynamicCreative/placementAssets); `lead_generation` accepts an optional `promotedObject.pageId` (auto-filled from the connected Page when omitted). TikTok-specific: `conversions` (website-conversion ad group) requires `promotedObject.pixelId` (your TikTok Pixel ID) and accepts an optional `promotedObject.customEventType` (a TikTok `optimization_event` code like `ON_WEB_ORDER`, `INITIATE_ORDER`, `ON_WEB_REGISTER`, `FORM`); to inherit a pixel + event from an existing ad group, pass `adSetId` instead. LinkedIn-specific: `engagement`, `traffic`, `awareness`, and `video_views` are supported for standalone ads (creates a Direct Sponsored Content single image or single video ad). `traffic` requires `linkUrl`; `video_views` requires the `video` field. For `lead_generation` / `conversions` on LinkedIn — or to promote an existing post — use `POST /v1/ads/boost`. - one of: engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales
- **optimizationGoal** `string`: Meta only. Explicit ad-set `optimization_goal` (e.g. `LANDING_PAGE_VIEWS`, `LINK_CLICKS`, `REACH`, `IMPRESSIONS`, `OFFSITE_CONVERSIONS`, `THRUPLAY`, `LEAD_GENERATION`). Overrides the default derived from `goal` (e.g. `traffic` defaults to `LINK_CLICKS`). Forwarded verbatim to Meta, which validates compatibility with the campaign objective and rejects incompatible combinations.
- **budgetAmount** `number`: Required on legacy + multi-creative shapes. Inherited on attach.
- **budgetType** `string`: Required on legacy + multi-creative shapes. Inherited on attach. - one of: daily, lifetime
- **budgetLevel** `string`: Meta only. Where the budget lives, which selects the Meta budget model:
  - `adset` (default): ABO (Ad-set Budget Optimization). The budget is set on the
    ad set. This is the back-compatible behaviour — omit this field to keep it.
  - `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.
Meta requires the budget at exactly one level, never both. Non-Meta platforms ignore
this field. Ignored on the attach shape (`adSetId`), which inherits the existing budget.
 - one of: adset, campaign
- **currency** `string`: No description
- **headline** `string`: Required for Meta, Google, Pinterest, and LinkedIn on legacy + attach shapes (skip for multi-creative — use `creatives[].headline`). Ignored for TikTok and X/Twitter. Max: Meta=255, Google=30, Pinterest=100, LinkedIn=400. On LinkedIn this is the ad's headline (the bold text on the creative); for traffic ads it's the link card title.
- **longHeadline** `string`: 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** `string`: Required on legacy + attach shapes. For X/Twitter this is the tweet text (max 280 chars including a ~24-char URL when `linkUrl` is set). On LinkedIn this is the post commentary (the intro text shown above the ad). Max: Google=90, Pinterest=500.
- **description** `string`: 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. Applies on legacy, attach, and placementAssets shapes; for multi-creative use creatives[].description (this field is the shared fallback). For multi-text variations use dynamicCreative.descriptions instead.
- **callToAction** `string`: Required on legacy + attach shapes for Meta. Honoured on TikTok (passes through to the Spark Ad creative's `call_to_action`) and on LinkedIn (the CTA button on the ad; defaults to LEARN_MORE when `linkUrl` is set). LinkedIn accepts: LEARN_MORE, SIGN_UP, DOWNLOAD, SUBSCRIBE, REGISTER, JOIN, ATTEND, REQUEST_DEMO, VIEW_QUOTE, APPLY, SEE_MORE, SHOP_NOW, BUY_NOW. Ignored by Google, Pinterest, and X/Twitter. - one of: LEARN_MORE, SHOP_NOW, SIGN_UP, BOOK_TRAVEL, CONTACT_US, DOWNLOAD, GET_OFFER, GET_QUOTE, SUBSCRIBE, WATCH_MORE, REGISTER, JOIN, ATTEND, REQUEST_DEMO, VIEW_QUOTE, APPLY, SEE_MORE, BUY_NOW
- **linkUrl** `string`: Required on legacy + attach shapes (skip for multi-creative). On LinkedIn it's the ad's destination URL; required for `traffic` ads, optional for `engagement` / `awareness`. NOT required when `goal` is `lead_generation` (the ad opens a Lead Gen form instead of a destination).
- **leadGenFormId** `string`: Meta Lead Gen forms only (facebook/instagram). The leadgen_forms ID to attach to the ad's creative — create one via POST /v1/ads/lead-forms. REQUIRED when `goal` is `lead_generation`, and on every ATTACH (`adSetId`) call that targets a lead ad set (the form attaches per-ad; Meta rejects a formless ad in a lead ad set). Ignored otherwise. The ad set's promoted_object.page_id + LEAD_GENERATION optimization + destination_type ON_AD are derived automatically from the goal. Both `placementAssets` (per-placement creative) and `dynamicCreative` (multi-text / multi-asset pool, e.g. multiple headlines and primary texts) ARE supported on instant-form lead ads — the form is attached for you, and for `dynamicCreative` the ad set is created as a Dynamic Creative ad set automatically (Meta requires that for any multi-text feed; there is no non-DCO multi-text path). Send a single `imageUrls` entry plus your text variations to get Meta's "Multiple Text Options" behavior on a lead ad.
- **imageUrl** `string`: Image creative for Meta/Google/Pinterest/LinkedIn on legacy + attach shapes (mutually exclusive with `video`). Required for LinkedIn ads unless `video` is set. Not required for Google Search campaigns. For TikTok, this field carries the VIDEO URL (the TikTok ads endpoint is video-only; the field retains the `imageUrl` name for cross-platform consistency). Ignored for X/Twitter. For Google Display, treated as the landscape image (alias of `images.landscape`); supply `images.square` alongside or the request is rejected. For LinkedIn the image is uploaded to LinkedIn under the authoring Company Page (see `organizationId`); recommended ratio 1.91:1 (e.g. 1200×627).
- **images** `object`: 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. Either this field or the legacy `imageUrl` can provide the landscape, but `square` has no legacy counterpart so it must be set here for Display.
- **video** `object`: Meta (facebook, instagram) and LinkedIn. When set, creates a VIDEO ad on the legacy (or, for Meta, attach) shape. Mutually exclusive with `imageUrl`. For Meta multi-creative, set `video` per entry inside `creatives[]` instead. For LinkedIn the video is uploaded to LinkedIn 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) — supply MP4 H.264/AAC, 3s-30min, 75KB-500MB.
- **creatives** `array`: Meta-only. When present, switches to the multi-creative shape:
creates 1 campaign + 1 ad set + N ads (one per entry here).
Top-level `headline` / `body` / `imageUrl` / `linkUrl` /
`callToAction` are ignored in this mode. Mutually exclusive with `adSetId`.

- **adSetId** `string`: Meta-only. When present, switches to the attach shape: adds
one new ad to this existing ad set without creating a new
campaign. Budget, targeting, goal, schedule, AND bid strategy
are inherited from the ad set on Meta — passing `bidStrategy`
in attach mode returns 400. To change an existing ad set's
bid, use `PUT /v1/ads/ad-sets/{adSetId}`. Mutually exclusive
with `creatives[]`.

The attached ad takes the full single-creative surface:
`headline`/`body`/`description`/`callToAction` plus either
`imageUrl`/`video` OR `placementAssets` (its own per-placement
Feed/Story assets), and `leadGenFormId` when the target is a
lead ad set (the parent must be ON_AD — true for ad sets
created via goal `lead_generation`; Meta rejects a formless ad
there, so pass the form on EVERY attached ad). This is the way
to build N full ads sharing one ad set: create the first ad
via the normal shape, then attach the rest one call each.

Supported on Meta (facebook, instagram) and TikTok. On TikTok
the `adSetId` is the ad group ID; the new ad inherits the
ad group's bid + budget + targeting.

- **businessName** `string`: Google Display only
- **boardId** `string`: Pinterest only. Board ID (auto-creates if not provided).
- **organizationId** `string`: LinkedIn only. 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. Required unless the resolved `accountId` is a connected LinkedIn Company-Page account (defaults to that page) or the LinkedIn ad account is org-owned (defaults to the account's owning organization). The 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. Ignored by every other platform.
- **countries** `array`: ISO 3166-1 alpha-2 country codes (e.g. ['NL']). Defaults to ['US'] when no `cities` or `regions` are provided. (LinkedIn currently honours country-level targeting only.)
- **cities** `array`: Meta-only. City-level geo targeting. Each city is targeted by Meta's opaque `key` (the city ID) which can be looked up via `GET /v1/ads/targeting/search?type=city&q=<name>&country_code=<ISO>`. Optional `radius` + `distance_unit` extend the targeting beyond the city limits (e.g. radius 25 km around the city center). Both must be set together, or both omitted (Meta defaults to ~16 km when omitted).

Cannot overlap with the same country in `countries` (Meta returns a "locations overlap" error). Either drop the country or scope it to a different country.

- **regions** `array`: Meta-only. Region-level (state/province) geo targeting. Each region is targeted by Meta's opaque `key` (the region ID) which can be looked up via `GET /v1/ads/targeting/search?type=region&q=<name>&country_code=<ISO>`.

- **ageMin** `integer`: No description
- **ageMax** `integer`: No description
- **interests** `array`: Interest objects from /v1/ads/interests. Each must include id and name.
- **zips** `array`: 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.
- **metros** `array`: DMA / metro-area geo targeting. `key` is the platform's metro ID from /v1/ads/targeting/search?dimension=geo&geoType=metro.
- **customLocations** `array`: Point-radius (lat/lng) geo targeting. Meta only (custom_locations). Rejected on platforms without radius support.
- **behaviors** `array`: Behaviour entities from /v1/ads/targeting/search?dimension=behavior. Supported on Meta and TikTok. Each must include id.
- **incomeTier** `string`: Normalized household-income tier. Meta and TikTok express all four; Google maps only
`top_10`; rejected on LinkedIn, X, and Pinterest. On Meta, income targeting is incompatible
with housing/employment/credit `specialAdCategories`.
 - one of: top_5, top_10, top_10_25, top_25_50
- **languages** `array`: Language codes (e.g. ['en']). Restricts the audience by language.
- **placements** `object`: Meta only. Manual ad placements. Omit for automatic placements (Meta's default,
recommended for most cases — Meta optimises delivery across all eligible surfaces).
When set, restricts delivery to the chosen surfaces, mapped onto the ad set's
`targeting.{publisher_platforms, facebook_positions, instagram_positions,
messenger_positions, audience_network_positions, threads_positions,
whatsapp_positions, device_platforms}`. Enum membership is validated here; Meta
additionally enforces co-selection rules (e.g. some positions require their parent
publisher platform) and returns an actionable error which we surface. Non-Meta
platforms reject this field.

- **savedTargetingId** `string`: ID of a `saved_targeting` audience (created via POST /v1/ads/audiences). When set, its stored
TargetingSpec is expanded as the base targeting; inline fields on this body merge on top. Lets you
reuse a named targeting preset without re-sending every field.

- **rawTargeting** `object`: Meta only. A raw Meta-native targeting spec passed to the ad set VERBATIM (snake_case:
`geo_locations`, `age_min`, `excluded_custom_audiences`, `flexible_spec`, `targeting_automation`,
business places, etc.) — exactly the shape `GET /v1/ads/{adId}` returns for external ads. Use it to
clone a campaign's targeting EXACTLY, preserving advanced fields the camelCase targeting fields can't
model. Mutually exclusive with the camelCase targeting fields (countries/regions/cities/interests/
ageMin/...), `audienceId`, and `savedTargetingId` (sending both → 422). Sent as-is; Meta validates and
surfaces any errors. If cloning an EU campaign, also pass `dsaBeneficiary` / `dsaPayor` (those are
separate fields, not part of targeting).

- **specialAdCategories** `array`: Meta only. Declares the ad's special category, required for housing, employment, credit, or
political/social-issue ads (Meta enforces restricted targeting for these). Note: setting a special
category disables income/zip targeting on Meta.

- **endDate** `string`: Required for lifetime budgets
- **startDate** `string`: Meta only. 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. For lifetime
budgets Meta also requires `endDate`. (Same `schedule.startDate` semantics already
available on `POST /v1/ads/boost`.)

- **instagramAccountId** `string`: Meta only. Override 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`.
When omitted we auto-resolve the IG account linked to the connected Facebook Page
(the existing default). Useful when a Page has more than one eligible IG account.

- **dynamicCreative** `object`: 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`). When set, the top-level single-creative fields
(`imageUrl`, `headline`, `body`, `linkUrl`, `callToAction`) are ignored. Mutually
exclusive with the `creatives[]` multi-creative shape. Meta limits: ≤10 images,
≤5 bodies / titles / descriptions.

- **placementAssets** `object`: Meta only. Placement asset customization: pin 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 Meta Ads Manager produces with "different creative per placement",
mapped to the creative's `asset_feed_spec` + `asset_customization_rules`. Deterministic
pinning, NOT the auto-optimizing pool of `dynamicCreative` (mutually exclusive). Works
on the legacy single shape AND the attach shape (`adSetId` + placementAssets adds one
placement-customized ad to an existing ad set — the way to build N per-placement ads
sharing one ad set: create the first normally, attach the rest). Cannot be combined
with `creatives[]`. Shared copy (headline, body, link,
CTA) comes from the top-level single-creative fields since only the asset varies by
placement. Each rule's `placements` accepts the same fields as the top-level
`placements` object; Meta enforces co-selection rules and returns an actionable error.

A block is all-image OR all-video, never mixed (Meta's asset_feed_spec carries one ad
format). Image mode: `defaultImageUrl` + `rules[].imageUrl`. Video mode:
`defaultVideoUrl` + `rules[].videoUrl` (optional `thumbnailUrl`/`defaultThumbnailUrl`
posters; Meta auto-generates when omitted). Exactly one catch-all default is required.

- **audienceId** `string`: Custom audience ID for targeting
- **campaignType** `string`: Google only - one of: display, search
- **keywords** `array`: Google Search only
- **additionalHeadlines** `array`: Google Search RSA only. Extra headlines.
- **additionalDescriptions** `array`: Google Search RSA only. Extra descriptions.
- **advantageAudience** `integer`: 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. - one of: 0, 1
- **attributionSpec** `array`: Meta only. Conversion attribution window for the ad set — maps 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`). Meta enforces the
valid combinations: `VIEW_THROUGH` only allows `windowDays: 1` (7d/28d view
windows were removed Jan 2026); `ENGAGED_VIDEO_VIEW` only `1` and only alongside
`VIEW_THROUGH: 1`; `CLICK_THROUGH: 28` only on certain objectives. Invalid combos
surface as a Meta 400.
Example: `[{ "eventType": "CLICK_THROUGH", "windowDays": 7 }, { "eventType": "VIEW_THROUGH", "windowDays": 1 }]`

- **gender** `string`: Meta only. Restrict the audience by gender. 'male' targets men only, 'female' targets women only, 'all' (default) targets everyone. Ignored by non-Meta platforms. - one of: all, male, female
- **bidStrategy**: Meta bid strategy applied to the ad set.
- **bidAmount** `number`: 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`.

- **roasAverageFloor** `number`: Minimum ROAS as a decimal multiplier (e.g. 2.0 = 2.0x ROAS). Required when
`bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`. Sent to Meta as
`bid_constraints.roas_average_floor` × 10000.

- **dsaBeneficiary** `string`: Name of the legal entity benefiting from the ad.
Required by Meta when targeting EU users (DSA Article 26).
Not enforced at schema level; enforced server-side when targeting intersects EU member states.

- **dsaPayor** `string`: Name of the legal entity paying for the ad.
Required by Meta when targeting EU users (DSA Article 26).
Note Meta API spelling: dsa_payor (not dsa_payer).

- **brandIdentity** `object`: TikTok only. Synthetic Brand Identity used when the ad
attributes to a CUSTOMIZED_USER (instead of a real TT_USER
@username). Required on the FIRST CUSTOMIZED_USER ad on a
`tiktokads` SocialAccount with no cached identity; omit on
subsequent ads (the identity is cached on the account after
first creation). Non-TikTok platforms ignore this field.

Alternative: configure once via `PATCH /v1/connect/tiktok-ads`,
then create ads without this field.

- **identityType** `string`: TikTok only. Forces the identity attribution on the ad:

  - `TT_USER`: the posting account's open_id (real @username
    branding). Requires a connected TikTok posting account
    on the same profile.
  - `CUSTOMIZED_USER`: synthetic Brand Identity (display
    name + avatar). Requires a configured Brand Identity
    (cached on the `tiktokads` SocialAccount via
    `PATCH /v1/connect/tiktok-ads`) or an inline
    `brandIdentity` to create one on the fly.

When omitted, defaults to `TT_USER` if a posting account is
connected on this profile, else `CUSTOMIZED_USER`. Spark
Ads (`POST /v1/ads/boost`) always use `TT_USER` regardless
of this field — TikTok requires the original organic
post's author identity for Spark.
 - one of: TT_USER, CUSTOMIZED_USER
- **promotedObject** `object`: What the ad optimises against. Behaviour depends on the platform.

**Meta**: forwarded to the ad set's `promoted_object` (snake-cased).
Required for goals whose ad-set optimization_goal points at a specific
event/page/app (without it Meta rejects the ad-set create with
`error_subcode: 1815430` "Please select a promoted object for your ad set"):
  - `goal: conversions` (OFFSITE_CONVERSIONS): requires `pixelId` + `customEventType`
  - `goal: app_promotion` (APP_INSTALLS): requires `applicationId` + `objectStoreUrl`
  - `goal: lead_generation` (LEAD_GENERATION): `pageId` is auto-filled from the connected Page when omitted

Other Meta goals (engagement, traffic, awareness, video_views) ignore this field.

**TikTok**: only `goal: conversions` uses it.
  - `pixelId` maps to the ad group's `pixel_id`. Required: a TikTok website-conversion
    ad group without a pixel is rejected with `40002: Please select a pixel`.
  - `customEventType` maps to the ad group's `optimization_event` (the pixel event to
    optimise for). Optional: TikTok accepts a pixel-only auto-bid conversion ad group.
    See the `customEventType` field below for the valid TikTok codes.

The remaining `promotedObject.*` fields are Meta-only. Platforms other than
Meta and TikTok ignore `promotedObject` entirely.


### Responses

#### 201: Ad(s) created

**Response Body:**

*One of the following:*
  - **ad**: `Ad` - See schema definition
  - **message** `string`: No description
  - **ads** `array[Ad]`: 
  - **platformCampaignId** `string`: No description
  - **platformAdSetId** `string`: No description
  - **message** `string`: No description

#### 400: Missing required fields, invalid values, or non-Meta platform used with creatives[] / adSetId

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

#### 422: Platform ads connection required (TikTok Ads, X Ads) or missing linked account

---


# Related Schema Definitions

## Ad

### Properties

- **_id** `string`: No description
- **name** `string`: No description
- **platform** `string`: No description - one of: facebook, instagram, tiktok, linkedin, pinterest, google, twitter
- **status**: No description
- **adType** `string`: No description - one of: boost, standalone
- **goal** `string`: Available goals vary by platform. Meta (Facebook/Instagram) supports all 9 (incl. `lead_conversion` = website pixel lead optimization and `catalog_sales` = Advantage+ catalog ads). TikTok supports the 7 non-`lead_conversion` goals. LinkedIn supports all except app_promotion / lead_conversion. Twitter/X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views. - one of: engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales
- **isExternal** `boolean`: True for ads synced from platform ad managers
- **budget** `object`: 
  - **amount** `number`: 
  - **type** `string`:  - one of: daily, lifetime
- **metrics**: No description
- **platformAdId** `string`: No description
- **platformAdAccountId** `string`: No description
- **platformCampaignId** `string`: No description
- **platformAdSetId** `string`: No description
- **campaignName** `string`: No description
- **adSetName** `string`: No description
- **platformObjective** `string`: Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC). Only present for Meta ads.
- **optimizationGoal** `string`: Meta ad set optimization goal (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION, LINK_CLICKS). Only present for Meta ads.
- **platformAdAccountName** `string`: Human-readable advertiser/account name (Meta `AdAccount.name`, TikTok
`advertiser_name`, LinkedIn / X / Pinterest equivalents). Refreshed every
sync so platform-side renames propagate within one cycle. `null` when the
platform doesn't return a name or the sync hasn't run yet.

- **platformCreatedAt** `string`: Platform-reported creation timestamp (Meta `created_time`, TikTok `create_time`).
Distinct from `createdAt` which reflects when Zernio first synced the doc — for
sort/filter by "when the ad was actually created on the platform", read this field.
`null` for legacy ads synced before this field was added; aggregations fall back
to `createdAt` in that case.

- **bidStrategy**: Ad-set bid strategy (overrides campaign level on Meta). Populated for Meta and
TikTok. TikTok's native `bid_type` is normalized to the cross-platform Meta enum:
`BID_TYPE_NO_BID` -> `LOWEST_COST_WITHOUT_CAP`, `BID_TYPE_CUSTOM` ->
`LOWEST_COST_WITH_BID_CAP`, deep_bid_type=MIN_ROAS or roas_bid>0 ->
`LOWEST_COST_WITH_MIN_ROAS`, `BID_TYPE_MAX_CONVERSION` -> `LOWEST_COST_WITHOUT_CAP`.

- **bidAmount** `number`: Bid cap in WHOLE currency units of the ad account (USD: 5 = $5.00; JPY: 100 = ¥100).
Populated when bidStrategy is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`. `null` for
auto-bid (`LOWEST_COST_WITHOUT_CAP`).

- Meta source: `bid_amount` on the ad set (smallest-denomination int, decoded here).
- TikTok source: priority order `bid_price` -> `conversion_bid_price` -> `deep_cpa_bid`
  (whichever is set on the ad group). TikTok stores all three in whole currency units.

Source: facebook-business-sdk-codegen api_specs/specs/AdSet.json (`bid_amount`).

- **roasAverageFloor** `number`: Minimum ROAS as a decimal multiplier (2.0 = 2.0x ROAS). Populated when bidStrategy
is `LOWEST_COST_WITH_MIN_ROAS`.

- Meta source: decoded from `bid_constraints.roas_average_floor` (Meta stores as
  fixed-point int × 10000; we return the decimal).
- TikTok source: `roas_bid` on the ad group (already a decimal).

Source: facebook-business-sdk-codegen api_specs/specs/AdCampaignBidConstraint.json.

- **promotedObject** `object`: Meta promoted object containing conversion event details. Structure varies by objective. Only present for Meta ads.
  - **custom_event_type** `string`: Conversion event type (e.g. PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART)
  - **pixel_id** `string`: Meta pixel ID
  - **page_id** `string`: Facebook page ID
  - **application_id** `string`: Facebook app ID
  - **product_set_id** `string`: Product catalog set ID
- **creative** `object`: Platform-specific creative data. Fields vary by platform.
  - **thumbnailUrl** `string`: Primary thumbnail/image URL
  - **imageUrl** `string`: Alternative image URL
  - **videoId** `string`: Meta video ID for VIDEO-type ads. Null for non-video ads. Callers that need an embeddable MP4 can call GET /{videoId}?fields=source with the page access token.
  - **videoUrl** `string`: Public Facebook watch URL for VIDEO-type ads (https://www.facebook.com/watch/?v={videoId}). Null for non-video ads.
  - **objectType** `string`: 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** `string`: Meta creative `object_story_id` (the SHARE reference). Frequently absent — Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead.
  - **effectiveObjectStoryId** `string`: Meta `effective_object_story_id` — `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. Pass to GET /v1/ads?effectiveObjectStoryId= to map a Business-Manager-visible post back to this ad; GET /v1/ads/{adId}/comments resolves comments against it.
  - **effectiveInstagramMediaId** `string`: 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** `string`: Meta `instagram_user_id` — the Instagram-scoped business ID that owns the boosted media.
  - **instagramPermalinkUrl** `string`: Meta `instagram_permalink_url` — public Instagram post URL of the boosted media.
  - **mediaUrls** `array`: 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).
  - **body** `string`: Ad copy/text
  - **googleHeadline** `string`: Google Ads headline
  - **googleDescription** `string`: Google Ads description
  - **linkUrl** `string`: Destination URL
  - **pinterestImageUrl** `string`: 
  - **pinterestTitle** `string`: 
  - **pinterestDescription** `string`: 
- **targeting** `object`: The ad set's targeting (age, gender, geo, interests, placements, audience inclusions/exclusions).
For ads created through Zernio this is the spec you supplied. For external ads (synced from
Meta Ads Manager, `isExternal: true`) targeting lives at the ad set and isn't stored at ingest,
so on the first `GET /v1/ads/{adId}` Zernio resolves it live from Meta and caches it on the ad;
the value is then Meta's raw `targeting` shape (snake_case, e.g. `geo_locations`, `age_min`),
the same object Ads Manager shows. May be absent if the ad set exposes no targeting or the lookup fails.

- **schedule** `object`: 
  - **startDate** `string`: 
  - **endDate** `string`: 
- **rejectionReason** `string`: No description
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

---

# Create a synthetic test lead API Reference

Submits 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.


## POST /v1/ads/lead-forms/{formId}/test-leads

**Create a synthetic test lead**

Submits 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.


### Parameters

- **formId** (required) in path: No description

### Request Body

- **accountId** (required) `string`: No description
- **fieldData** (required) `array`: No description

### Responses

#### 200: Test lead created.

**Response Body:**

- **status** `string`: No description
- **testLead** `object`: 
  - **id** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Cancel an ad API Reference

Cancels the ad on the platform and marks it as cancelled in the database. The ad is preserved for history.

## GET /v1/ads/{adId}

**Get ad details**

Returns an ad with its creative, targeting, status, and performance metrics.

The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad:
- the Zernio internal `_id` (24-char hex)
- Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`)
- the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side)
- the creative's `effective_instagram_media_id` (Instagram side)

Any of the four resolve to the same ad. Caller doesn't need a translation step.


### Parameters

- **adId** (required) in path: Zernio `_id` (hex), Meta `platformAdId` (numeric), or one of the creative's effective story/media IDs. See description for details.


### Responses

#### 200: Ad details

**Response Body:**

- **ad**: `Ad` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PUT /v1/ads/{adId}

**Update ad**

Patch one or more fields on an ad. Status, budget, targeting, and creative changes
are propagated to the platform.

Per-platform support:
- **Meta** (Facebook + Instagram): all fields supported.
- **TikTok**: status, budget, targeting (via `/v2/adgroup/update/`), and creative
  (via `/v2/ad/update/` patch-style — `headline` is ignored, `body` becomes `ad_text`).
- **Pinterest / X / LinkedIn / Google**: status + budget only. Sending `targeting`
  or `creative` returns 501 with code `unsupported_platform_operation`.


### Parameters

- **adId** (required) in path: No description

### Request Body

- **status** `string`: No description - one of: active, paused
- **budget** `object`: No description
- **targeting** `object`: Meta + TikTok only. Pinterest / X / LinkedIn / Google return 501.

- **creative** `object`: Replace the ad's creative. Meta + TikTok only.

- **Meta**: requires `headline`, `body`, `callToAction`, `linkUrl`, `imageUrl`. The
  ad's existing creative is replaced via a new `/act_X/adcreatives` upload + ad
  update. The old creative is retained on the ad account for historical reporting.
- **TikTok**: patch-style. Pass any subset; `headline` is ignored (TikTok creatives
  have no headline slot). `body` becomes the in-feed `ad_text`; `linkUrl` becomes
  `landing_page_url`; `videoUrl` triggers a fresh upload.

- **name** `string`: Rename the ad. Now propagated to Meta (POST /{ad-id}); non-Meta platforms return 501.

### Responses

#### 200: Ad updated

**Response Body:**

- **ad**: `Ad` - See schema definition
- **message** `string`: No description

#### 400: Invalid status transition or budget below minimum

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 501: targeting or creative not supported on the platform (Meta + TikTok only)

---

## DELETE /v1/ads/{adId}

**Cancel an ad**

Cancels the ad on the platform and marks it as cancelled in the database. The ad is preserved for history.

### Parameters

- **adId** (required) in path: No description

### Responses

#### 200: Ad cancelled

**Response Body:**

- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## Ad

### Properties

- **_id** `string`: No description
- **name** `string`: No description
- **platform** `string`: No description - one of: facebook, instagram, tiktok, linkedin, pinterest, google, twitter
- **status**: No description
- **adType** `string`: No description - one of: boost, standalone
- **goal** `string`: Available goals vary by platform. Meta (Facebook/Instagram) supports all 9 (incl. `lead_conversion` = website pixel lead optimization and `catalog_sales` = Advantage+ catalog ads). TikTok supports the 7 non-`lead_conversion` goals. LinkedIn supports all except app_promotion / lead_conversion. Twitter/X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views. - one of: engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales
- **isExternal** `boolean`: True for ads synced from platform ad managers
- **budget** `object`: 
  - **amount** `number`: 
  - **type** `string`:  - one of: daily, lifetime
- **metrics**: No description
- **platformAdId** `string`: No description
- **platformAdAccountId** `string`: No description
- **platformCampaignId** `string`: No description
- **platformAdSetId** `string`: No description
- **campaignName** `string`: No description
- **adSetName** `string`: No description
- **platformObjective** `string`: Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC). Only present for Meta ads.
- **optimizationGoal** `string`: Meta ad set optimization goal (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION, LINK_CLICKS). Only present for Meta ads.
- **platformAdAccountName** `string`: Human-readable advertiser/account name (Meta `AdAccount.name`, TikTok
`advertiser_name`, LinkedIn / X / Pinterest equivalents). Refreshed every
sync so platform-side renames propagate within one cycle. `null` when the
platform doesn't return a name or the sync hasn't run yet.

- **platformCreatedAt** `string`: Platform-reported creation timestamp (Meta `created_time`, TikTok `create_time`).
Distinct from `createdAt` which reflects when Zernio first synced the doc — for
sort/filter by "when the ad was actually created on the platform", read this field.
`null` for legacy ads synced before this field was added; aggregations fall back
to `createdAt` in that case.

- **bidStrategy**: Ad-set bid strategy (overrides campaign level on Meta). Populated for Meta and
TikTok. TikTok's native `bid_type` is normalized to the cross-platform Meta enum:
`BID_TYPE_NO_BID` -> `LOWEST_COST_WITHOUT_CAP`, `BID_TYPE_CUSTOM` ->
`LOWEST_COST_WITH_BID_CAP`, deep_bid_type=MIN_ROAS or roas_bid>0 ->
`LOWEST_COST_WITH_MIN_ROAS`, `BID_TYPE_MAX_CONVERSION` -> `LOWEST_COST_WITHOUT_CAP`.

- **bidAmount** `number`: Bid cap in WHOLE currency units of the ad account (USD: 5 = $5.00; JPY: 100 = ¥100).
Populated when bidStrategy is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`. `null` for
auto-bid (`LOWEST_COST_WITHOUT_CAP`).

- Meta source: `bid_amount` on the ad set (smallest-denomination int, decoded here).
- TikTok source: priority order `bid_price` -> `conversion_bid_price` -> `deep_cpa_bid`
  (whichever is set on the ad group). TikTok stores all three in whole currency units.

Source: facebook-business-sdk-codegen api_specs/specs/AdSet.json (`bid_amount`).

- **roasAverageFloor** `number`: Minimum ROAS as a decimal multiplier (2.0 = 2.0x ROAS). Populated when bidStrategy
is `LOWEST_COST_WITH_MIN_ROAS`.

- Meta source: decoded from `bid_constraints.roas_average_floor` (Meta stores as
  fixed-point int × 10000; we return the decimal).
- TikTok source: `roas_bid` on the ad group (already a decimal).

Source: facebook-business-sdk-codegen api_specs/specs/AdCampaignBidConstraint.json.

- **promotedObject** `object`: Meta promoted object containing conversion event details. Structure varies by objective. Only present for Meta ads.
  - **custom_event_type** `string`: Conversion event type (e.g. PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART)
  - **pixel_id** `string`: Meta pixel ID
  - **page_id** `string`: Facebook page ID
  - **application_id** `string`: Facebook app ID
  - **product_set_id** `string`: Product catalog set ID
- **creative** `object`: Platform-specific creative data. Fields vary by platform.
  - **thumbnailUrl** `string`: Primary thumbnail/image URL
  - **imageUrl** `string`: Alternative image URL
  - **videoId** `string`: Meta video ID for VIDEO-type ads. Null for non-video ads. Callers that need an embeddable MP4 can call GET /{videoId}?fields=source with the page access token.
  - **videoUrl** `string`: Public Facebook watch URL for VIDEO-type ads (https://www.facebook.com/watch/?v={videoId}). Null for non-video ads.
  - **objectType** `string`: 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** `string`: Meta creative `object_story_id` (the SHARE reference). Frequently absent — Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead.
  - **effectiveObjectStoryId** `string`: Meta `effective_object_story_id` — `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. Pass to GET /v1/ads?effectiveObjectStoryId= to map a Business-Manager-visible post back to this ad; GET /v1/ads/{adId}/comments resolves comments against it.
  - **effectiveInstagramMediaId** `string`: 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** `string`: Meta `instagram_user_id` — the Instagram-scoped business ID that owns the boosted media.
  - **instagramPermalinkUrl** `string`: Meta `instagram_permalink_url` — public Instagram post URL of the boosted media.
  - **mediaUrls** `array`: 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).
  - **body** `string`: Ad copy/text
  - **googleHeadline** `string`: Google Ads headline
  - **googleDescription** `string`: Google Ads description
  - **linkUrl** `string`: Destination URL
  - **pinterestImageUrl** `string`: 
  - **pinterestTitle** `string`: 
  - **pinterestDescription** `string`: 
- **targeting** `object`: The ad set's targeting (age, gender, geo, interests, placements, audience inclusions/exclusions).
For ads created through Zernio this is the spec you supplied. For external ads (synced from
Meta Ads Manager, `isExternal: true`) targeting lives at the ad set and isn't stored at ingest,
so on the first `GET /v1/ads/{adId}` Zernio resolves it live from Meta and caches it on the ad;
the value is then Meta's raw `targeting` shape (snake_case, e.g. `geo_locations`, `age_min`),
the same object Ads Manager shows. May be absent if the ad set exposes no targeting or the lookup fails.

- **schedule** `object`: 
  - **startDate** `string`: 
  - **endDate** `string`: 
- **rejectionReason** `string`: No description
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

---

# Soft-delete a conversion destination API Reference

LinkedIn-only today. LinkedIn does not expose hard-delete on conversion
rules — what their UI calls "delete" is the same `enabled: false` flip
we apply here. The rule remains fetchable via GET with
`status: 'inactive'`; the unified discovery endpoint hides it by
default.

`adAccountId` may be passed as a query parameter (recommended) or as
a JSON body field for clients that can send DELETE bodies.


## GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}

**Fetch a single conversion destination**

LinkedIn-only today. Returns the full destination record for one
conversion rule. The `adAccountId` query parameter is required because
LinkedIn rules are scoped to a sponsored ad account.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (required) in query: Numeric ID or full `urn:li:sponsoredAccount:{id}` URN.

### Responses

#### 200: Destination fetched

**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **destination**: `ConversionDestination` - See schema definition

#### 400: Validation error.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support fetching a single destination.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## PATCH /v1/accounts/{accountId}/conversion-destinations/{destinationId}

**Update a conversion destination**

Partial-update a conversion rule. LinkedIn-only today. Whitelisted
fields: `name`, `enabled`, attribution windows, `valueType`, `value`,
`attributionType`. The rule's `type` and parent ad account are
intentionally not exposed for update — recreate the rule if those
need to change.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description

### Request Body

- **adAccountId** (required) `string`: No description
- **name** `string`: No description
- **enabled** `boolean`: Setting `false` is equivalent to calling DELETE — the
rule will appear as `inactive` afterwards.

- **attributionType** `string`: No description - one of: LAST_TOUCH_BY_CAMPAIGN, LAST_TOUCH_BY_CONVERSION
- **postClickAttributionWindowSize** `integer`: 365 only allowed for LEAD, PURCHASE, ADD_TO_CART,
QUALIFIED_LEAD, SUBMIT_APPLICATION rule types.
 - one of: 1, 7, 30, 90, 365
- **viewThroughAttributionWindowSize** `integer`: 365 only allowed for LEAD, PURCHASE, ADD_TO_CART,
QUALIFIED_LEAD, SUBMIT_APPLICATION rule types.
 - one of: 1, 7, 30, 90, 365
- **valueType** `string`: No description - one of: DYNAMIC, FIXED, NO_VALUE
- **value** `object`: Used when `valueType=FIXED`.

### Responses

#### 200: Destination updated (re-fetched canonical state)

**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **destination**: `ConversionDestination` - See schema definition

#### 400: Invalid body or LinkedIn validation failure.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support updating destinations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}

**Soft-delete a conversion destination**

LinkedIn-only today. LinkedIn does not expose hard-delete on conversion
rules — what their UI calls "delete" is the same `enabled: false` flip
we apply here. The rule remains fetchable via GET with
`status: 'inactive'`; the unified discovery endpoint hides it by
default.

`adAccountId` may be passed as a query parameter (recommended) or as
a JSON body field for clients that can send DELETE bodies.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (optional) in query: Required as query OR in JSON body.

### Responses

#### 204: Soft-deleted.

#### 400: adAccountId missing.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support deleting destinations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---


# Related Schema Definitions

## ConversionDestination

A discoverable conversion destination on an ad platform — a Meta pixel,
Google conversion action, or LinkedIn conversion rule. Returned by
`listConversionDestinations`, `getConversionDestination`,
`createConversionDestination`, and `updateConversionDestination`.


### Properties

- **id** (required) `string`: Platform-native identifier. Pass back as `destinationId` on event
send and as the path segment on CRUD endpoints.

- **name** (required) `string`: No description
- **type** `string`: Present when the platform locks the event type/category to the
destination (Google conversion actions, LinkedIn conversion rules).
Absent for Meta pixels (which accept any event name per request).

- **status** `string`: For LinkedIn, `inactive` means the rule is soft-deleted (`enabled: false`).
 - one of: active, inactive
- **adAccountId** `string`: Set by adapters whose destinations are scoped to a specific ad
account (LinkedIn). Pass back on subsequent CRUD calls to
identify the parent ad account.

---

# Estimate audience reach API Reference

Returns a normalized pre-flight audience-size estimate for a targeting spec,
before any campaign is created. Backed by each platform's native reach API
(Meta `delivery_estimate`, LinkedIn `audienceCounts`, X `audience_summary`,
Pinterest `audience_sizing`).

Platforms without a usable pre-flight reach API (Google Search/Display, TikTok)
return `available: false` with no bounds, so clients can hide or grey out the
estimate rather than treat the absence as an error.


## POST /v1/ads/targeting/reach-estimate

**Estimate audience reach**

Returns a normalized pre-flight audience-size estimate for a targeting spec,
before any campaign is created. Backed by each platform's native reach API
(Meta `delivery_estimate`, LinkedIn `audienceCounts`, X `audience_summary`,
Pinterest `audience_sizing`).

Platforms without a usable pre-flight reach API (Google Search/Display, TikTok)
return `available: false` with no bounds, so clients can hide or grey out the
estimate rather than treat the absence as an error.


### Request Body

- **accountId** (required) `string`: Zernio social account ID on the target ad platform (the estimate runs against its platform).
- **adAccountId** (required) `string`: 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** (required): The targeting spec to estimate. Same shape used by POST /v1/ads/create.
- **optimizationGoal** `string`: Optional. The optimization goal the estimate should assume (platform's
own vocabulary, e.g. Meta `REACH`, `LINK_CLICKS`, `OFFSITE_CONVERSIONS`).
Some platforms vary the estimate by goal; omit to use the platform default.


### Responses

#### 200: Normalized reach estimate

**Response Body:**

- **available** (required) `boolean`: Whether a pre-flight estimate is available on this platform. False for Google and TikTok.
- **lower** `integer`: Lower bound of the estimated reachable audience. Present only when available.
- **upper** `integer`: Upper bound of the estimated reachable audience. Present only when available.
- **daily** `integer`: Optional estimated daily reach/results at the given budget, when the platform returns it.
- **currency** `string`: Currency of any monetary fields in the estimate, when applicable.
- **estimateReady** `boolean`: Meta only. False when Meta is still computing the estimate (the audience is too new); retry shortly.

#### 400: Missing required fields or a targeting field the platform cannot honour

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Get ad analytics API Reference

Returns detailed performance analytics for an ad. Includes summary metrics, a daily timeline
over the requested date range, and optional demographic breakdowns (Meta and TikTok only).
If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max.


## GET /v1/ads/{adId}/analytics

**Get ad analytics**

Returns detailed performance analytics for an ad. Includes summary metrics, a daily timeline
over the requested date range, and optional demographic breakdowns (Meta and TikTok only).
If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max.


### Parameters

- **adId** (required) in path: No description
- **fromDate** (optional) in query: Start of date range (YYYY-MM-DD). Defaults to 90 days ago.
- **toDate** (optional) in query: End of date range (YYYY-MM-DD). Defaults to today. Max 730-day range.
- **breakdowns** (optional) in query: Comma-separated breakdown dimensions. Meta: age, gender, country, publisher_platform, device_platform, region. TikTok: gender, age, country_code, platform, ac, language.

### Responses

#### 200: Ad analytics

**Response Body:**

- **ad** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **platform** `string`: No description
  - **trigger** `string`: No description - one of: comment, story_reply
  - **status** `string`: No description
  - **currency** `string`: 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** `object`: 
  - **summary**: `AdMetrics` - See schema definition
  - **daily** `array[items]`: 
  - **breakdowns** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## AdMetrics

### Properties

- **spend** `number`: No description
- **impressions** `integer`: No description
- **reach** `integer`: No description
- **clicks** `integer`: No description
- **ctr** `number`: Click-through rate (%)
- **cpc** `number`: Cost per click
- **cpm** `number`: Cost per 1000 impressions
- **engagement** `integer`: No description
- **conversions** `integer`: Count of conversion events matching the campaign's promoted_object.custom_event_type (PURCHASE, LEAD, etc.) over the requested date range. 0 for non-conversion campaigns or when no events have fired. Meta-only at time of writing; other platforms return 0.
- **costPerConversion** `number`: Derived spend / conversions in the same currency as spend. 0 when conversions is 0.
- **actions** `object`: Raw per-action-type counts from Meta's Insights actions[] array, summed over the date range. Keys are Meta action_type strings (e.g. link_click, offsite_conversion.fb_pixel_purchase, onsite_conversion.lead_grouped). Use this to extract any conversion event (purchases, leads, add_to_cart, etc.) without relying on the derived conversions field. Empty object when no actions are reported.
- **actionValues** `object`: Monetary mirror of `actions`, from Meta's Insights `action_values[]` array. Same keying — values are the revenue attributed to each action_type, in ad-account native currency (same unit as `spend`; see the campaign node's `currency` field). Use this to compute revenue-per-event (e.g. avg purchase value). Meta-only; other platforms return {}.
- **purchaseValue** `number`: Convenience sum of purchase-type action values — picked from `actionValues` via the same priority list as `conversions` so both fields describe the same events. In ad-account native currency. 0 when the campaign has no purchase event configured. Meta-only.
- **roas** `number`: 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.
- **lastSyncedAt** `string`: Present on individual ads only, not on campaign aggregations

---

# List comments on an ad API Reference

Returns comments on an ad's underlying creative post. Useful for moderating or analyzing
engagement on dark posts (ad creatives that never went live organically), which the
regular GET /v1/inbox/comments/{postId} endpoint cannot serve because dark posts are
not in Zernio's post database.

An 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). Use 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.

For Instagram-placed comments, the Instagram account that runs the ad must be connected
to Zernio — those comments are read through that account's token. If 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).

Meta-only. Other ad platforms (TikTok, LinkedIn, Pinterest, Google, X) do not
expose a public per-ad comments API and return feature_not_available.

Requires the Ads add-on. Response shape matches GET /v1/inbox/comments/{postId}.

The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad:
Zernio internal `_id` (24-char hex), Meta's numeric `platformAdId` (the value shipped in
`comment.received` webhooks as `comment.ad.id`), or the creative's
`effective_object_story_id` / `effective_instagram_media_id`. Caller doesn't need a
translation step.


## GET /v1/ads/{adId}/comments

**List comments on an ad**

Returns comments on an ad's underlying creative post. Useful for moderating or analyzing
engagement on dark posts (ad creatives that never went live organically), which the
regular GET /v1/inbox/comments/{postId} endpoint cannot serve because dark posts are
not in Zernio's post database.

An 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). Use 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.

For Instagram-placed comments, the Instagram account that runs the ad must be connected
to Zernio — those comments are read through that account's token. If 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).

Meta-only. Other ad platforms (TikTok, LinkedIn, Pinterest, Google, X) do not
expose a public per-ad comments API and return feature_not_available.

Requires the Ads add-on. Response shape matches GET /v1/inbox/comments/{postId}.

The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad:
Zernio internal `_id` (24-char hex), Meta's numeric `platformAdId` (the value shipped in
`comment.received` webhooks as `comment.ad.id`), or the creative's
`effective_object_story_id` / `effective_instagram_media_id`. Caller doesn't need a
translation step.


### Parameters

- **adId** (required) in path: Internal Zernio ad ID (ObjectId).
- **placement** (optional) in query: 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.
- **limit** (optional) in query: No description
- **cursor** (optional) in query: Pagination cursor from a previous response.

### Responses

#### 200: Comments on the ad

**Response Body:**

- **status** (required) `string`: No description - one of: success
- **comments** (required) `array[object]`: 
  Type: `object`
- **pagination** (required) `object`: 
  - **hasMore** `boolean`: No description
  - **cursor** `string`: No description
- **meta** (required) `object`: 
  - **platform** (required) `string`: Which side these comments are on (same as `placement`). - one of: facebook, instagram
  - **placement** (required) `string`: The placement these comments are for — useful when you didn't pass ?placement= and want to know which one you got. - one of: facebook, instagram
  - **adId** (required) `string`: Internal Zernio ad ID.
  - **platformAdId** (required) `string`: Meta ad ID.
  - **effectiveStoryId** (required) `string`: Underlying post ID the comments belong to. effective_object_story_id for the Facebook side, effective_instagram_media_id for the Instagram side.
  - **facebookAccountId** `string`: 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** `string`: Instagram-only. The Instagram-scoped business ID that owns the boosted media (creative.instagram_user_id).
  - **instagramPermalink** `string`: Instagram-only. Public permalink of the boosted IG post (creative.instagram_permalink_url).
  - **instagramAccountId** `string`: 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** (required) `string`: Social account ID (ads SocialAccount).
  - **lastUpdated** (required) `string` (date-time): No description

#### 400: Invalid ad ID format, or the ad's creative format does not expose a commentable
underlying post (code ad_not_commentable).


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (legacy plans need the Ads add-on; included by default on usage-based plans), or ad platform is not Meta (code feature_not_available).

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 422: Ads account token unavailable, or (for Instagram-placed ads) no connected
Instagram account on the profile can read the ad's media (code ads_connection_required).


---

---

# Read an ad's click-URL tracking tags API Reference

Unified read of the platform's native click-URL tracking params.
- Meta (facebook/instagram): the creative's `url_tags` (and template_url_spec).
- Google (googleads): the campaign's `trackingUrlTemplate` + `finalUrlSuffix`.
  Subject to the Google Ads API access-tier daily quota; bulk audits need Standard access.
- LinkedIn (linkedinads): the campaign's Dynamic UTM `dynamicValueParameters` + `customValueParameters`.
Returns 405 for platforms without a click-URL tracking surface (TikTok, X, Pinterest).


## GET /v1/ads/{adId}/tracking-tags

**Read an ad's click-URL tracking tags**

Unified read of the platform's native click-URL tracking params.
- Meta (facebook/instagram): the creative's `url_tags` (and template_url_spec).
- Google (googleads): the campaign's `trackingUrlTemplate` + `finalUrlSuffix`.
  Subject to the Google Ads API access-tier daily quota; bulk audits need Standard access.
- LinkedIn (linkedinads): the campaign's Dynamic UTM `dynamicValueParameters` + `customValueParameters`.
Returns 405 for platforms without a click-URL tracking surface (TikTok, X, Pinterest).


### Parameters

- **adId** (required) in path: Ad id (hex _id, platformAdId, or effective story/media id).

### Responses

#### 200: Tracking tags for the ad's platform (shape varies by platform).

**Response Body:**

- **platform** `string`: No description
- **level** `string`: No description - one of: creative, campaign
- **urlTags** `string`: Meta: &-joined click-URL params.
- **templateUrlSpec** `object`: Meta: third-party click-tracking template (Dynamic Ads).
- **trackingUrlTemplate** `string`: Google.
- **finalUrlSuffix** `string`: Google.
- **dynamicValueParameters** `object`: LinkedIn.
- **customValueParameters** `object`: LinkedIn.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Ad not found

#### 405: Platform has no click-URL tracking surface

---

## PATCH /v1/ads/{adId}/tracking-tags

**Set/update an ad's click-URL tracking tags**

Unified update. Send only the fields for the ad's platform:
- Meta: `urlTags` (array of {key,value}). Meta creatives are immutable, so this rebuilds the
  creative and repoints the ad. By 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 — no need to read back headline/body/CTA. `creative` (headline, body, callToAction,
  linkUrl, imageUrl) is OPTIONAL and 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`).
- Google: `trackingUrlTemplate` and/or `finalUrlSuffix` (full template strings; account quota applies).
- LinkedIn: `dynamicValueParameters` and/or `customValueParameters` (campaign-level Dynamic UTM).


### Parameters

- **adId** (required) in path: No description

### Request Body

- **urlTags** `array`: Meta only. Click-URL params appended to a freshly-rebuilt creative.
- **creative** `object`: 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.
- **trackingUrlTemplate** `string`: Google only. Full tracking template (must contain {lpurl}).
- **finalUrlSuffix** `string`: Google only. Parse-only key=value params.
- **dynamicValueParameters** `object`: LinkedIn only. key -> dynamic value enum (CAMPAIGN_ID, CAMPAIGN_NAME, CREATIVE_ID, ...).
- **customValueParameters** `object`: LinkedIn only. key -> static value.

### Responses

#### 200: Updated

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Ad not found

#### 405: Platform has no click-URL tracking surface

#### 422: Meta creative cannot be rebuilt (e.g. placement-customized/asset-feed/dark creative)

---

---

# Get ad details API Reference

Returns an ad with its creative, targeting, status, and performance metrics.

The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad:
- the Zernio internal `_id` (24-char hex)
- Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`)
- the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side)
- the creative's `effective_instagram_media_id` (Instagram side)

Any of the four resolve to the same ad. Caller doesn't need a translation step.


## GET /v1/ads/{adId}

**Get ad details**

Returns an ad with its creative, targeting, status, and performance metrics.

The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad:
- the Zernio internal `_id` (24-char hex)
- Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`)
- the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side)
- the creative's `effective_instagram_media_id` (Instagram side)

Any of the four resolve to the same ad. Caller doesn't need a translation step.


### Parameters

- **adId** (required) in path: Zernio `_id` (hex), Meta `platformAdId` (numeric), or one of the creative's effective story/media IDs. See description for details.


### Responses

#### 200: Ad details

**Response Body:**

- **ad**: `Ad` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PUT /v1/ads/{adId}

**Update ad**

Patch one or more fields on an ad. Status, budget, targeting, and creative changes
are propagated to the platform.

Per-platform support:
- **Meta** (Facebook + Instagram): all fields supported.
- **TikTok**: status, budget, targeting (via `/v2/adgroup/update/`), and creative
  (via `/v2/ad/update/` patch-style — `headline` is ignored, `body` becomes `ad_text`).
- **Pinterest / X / LinkedIn / Google**: status + budget only. Sending `targeting`
  or `creative` returns 501 with code `unsupported_platform_operation`.


### Parameters

- **adId** (required) in path: No description

### Request Body

- **status** `string`: No description - one of: active, paused
- **budget** `object`: No description
- **targeting** `object`: Meta + TikTok only. Pinterest / X / LinkedIn / Google return 501.

- **creative** `object`: Replace the ad's creative. Meta + TikTok only.

- **Meta**: requires `headline`, `body`, `callToAction`, `linkUrl`, `imageUrl`. The
  ad's existing creative is replaced via a new `/act_X/adcreatives` upload + ad
  update. The old creative is retained on the ad account for historical reporting.
- **TikTok**: patch-style. Pass any subset; `headline` is ignored (TikTok creatives
  have no headline slot). `body` becomes the in-feed `ad_text`; `linkUrl` becomes
  `landing_page_url`; `videoUrl` triggers a fresh upload.

- **name** `string`: Rename the ad. Now propagated to Meta (POST /{ad-id}); non-Meta platforms return 501.

### Responses

#### 200: Ad updated

**Response Body:**

- **ad**: `Ad` - See schema definition
- **message** `string`: No description

#### 400: Invalid status transition or budget below minimum

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 501: targeting or creative not supported on the platform (Meta + TikTok only)

---

## DELETE /v1/ads/{adId}

**Cancel an ad**

Cancels the ad on the platform and marks it as cancelled in the database. The ad is preserved for history.

### Parameters

- **adId** (required) in path: No description

### Responses

#### 200: Ad cancelled

**Response Body:**

- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## Ad

### Properties

- **_id** `string`: No description
- **name** `string`: No description
- **platform** `string`: No description - one of: facebook, instagram, tiktok, linkedin, pinterest, google, twitter
- **status**: No description
- **adType** `string`: No description - one of: boost, standalone
- **goal** `string`: Available goals vary by platform. Meta (Facebook/Instagram) supports all 9 (incl. `lead_conversion` = website pixel lead optimization and `catalog_sales` = Advantage+ catalog ads). TikTok supports the 7 non-`lead_conversion` goals. LinkedIn supports all except app_promotion / lead_conversion. Twitter/X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views. - one of: engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales
- **isExternal** `boolean`: True for ads synced from platform ad managers
- **budget** `object`: 
  - **amount** `number`: 
  - **type** `string`:  - one of: daily, lifetime
- **metrics**: No description
- **platformAdId** `string`: No description
- **platformAdAccountId** `string`: No description
- **platformCampaignId** `string`: No description
- **platformAdSetId** `string`: No description
- **campaignName** `string`: No description
- **adSetName** `string`: No description
- **platformObjective** `string`: Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC). Only present for Meta ads.
- **optimizationGoal** `string`: Meta ad set optimization goal (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION, LINK_CLICKS). Only present for Meta ads.
- **platformAdAccountName** `string`: Human-readable advertiser/account name (Meta `AdAccount.name`, TikTok
`advertiser_name`, LinkedIn / X / Pinterest equivalents). Refreshed every
sync so platform-side renames propagate within one cycle. `null` when the
platform doesn't return a name or the sync hasn't run yet.

- **platformCreatedAt** `string`: Platform-reported creation timestamp (Meta `created_time`, TikTok `create_time`).
Distinct from `createdAt` which reflects when Zernio first synced the doc — for
sort/filter by "when the ad was actually created on the platform", read this field.
`null` for legacy ads synced before this field was added; aggregations fall back
to `createdAt` in that case.

- **bidStrategy**: Ad-set bid strategy (overrides campaign level on Meta). Populated for Meta and
TikTok. TikTok's native `bid_type` is normalized to the cross-platform Meta enum:
`BID_TYPE_NO_BID` -> `LOWEST_COST_WITHOUT_CAP`, `BID_TYPE_CUSTOM` ->
`LOWEST_COST_WITH_BID_CAP`, deep_bid_type=MIN_ROAS or roas_bid>0 ->
`LOWEST_COST_WITH_MIN_ROAS`, `BID_TYPE_MAX_CONVERSION` -> `LOWEST_COST_WITHOUT_CAP`.

- **bidAmount** `number`: Bid cap in WHOLE currency units of the ad account (USD: 5 = $5.00; JPY: 100 = ¥100).
Populated when bidStrategy is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`. `null` for
auto-bid (`LOWEST_COST_WITHOUT_CAP`).

- Meta source: `bid_amount` on the ad set (smallest-denomination int, decoded here).
- TikTok source: priority order `bid_price` -> `conversion_bid_price` -> `deep_cpa_bid`
  (whichever is set on the ad group). TikTok stores all three in whole currency units.

Source: facebook-business-sdk-codegen api_specs/specs/AdSet.json (`bid_amount`).

- **roasAverageFloor** `number`: Minimum ROAS as a decimal multiplier (2.0 = 2.0x ROAS). Populated when bidStrategy
is `LOWEST_COST_WITH_MIN_ROAS`.

- Meta source: decoded from `bid_constraints.roas_average_floor` (Meta stores as
  fixed-point int × 10000; we return the decimal).
- TikTok source: `roas_bid` on the ad group (already a decimal).

Source: facebook-business-sdk-codegen api_specs/specs/AdCampaignBidConstraint.json.

- **promotedObject** `object`: Meta promoted object containing conversion event details. Structure varies by objective. Only present for Meta ads.
  - **custom_event_type** `string`: Conversion event type (e.g. PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART)
  - **pixel_id** `string`: Meta pixel ID
  - **page_id** `string`: Facebook page ID
  - **application_id** `string`: Facebook app ID
  - **product_set_id** `string`: Product catalog set ID
- **creative** `object`: Platform-specific creative data. Fields vary by platform.
  - **thumbnailUrl** `string`: Primary thumbnail/image URL
  - **imageUrl** `string`: Alternative image URL
  - **videoId** `string`: Meta video ID for VIDEO-type ads. Null for non-video ads. Callers that need an embeddable MP4 can call GET /{videoId}?fields=source with the page access token.
  - **videoUrl** `string`: Public Facebook watch URL for VIDEO-type ads (https://www.facebook.com/watch/?v={videoId}). Null for non-video ads.
  - **objectType** `string`: 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** `string`: Meta creative `object_story_id` (the SHARE reference). Frequently absent — Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead.
  - **effectiveObjectStoryId** `string`: Meta `effective_object_story_id` — `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. Pass to GET /v1/ads?effectiveObjectStoryId= to map a Business-Manager-visible post back to this ad; GET /v1/ads/{adId}/comments resolves comments against it.
  - **effectiveInstagramMediaId** `string`: 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** `string`: Meta `instagram_user_id` — the Instagram-scoped business ID that owns the boosted media.
  - **instagramPermalinkUrl** `string`: Meta `instagram_permalink_url` — public Instagram post URL of the boosted media.
  - **mediaUrls** `array`: 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).
  - **body** `string`: Ad copy/text
  - **googleHeadline** `string`: Google Ads headline
  - **googleDescription** `string`: Google Ads description
  - **linkUrl** `string`: Destination URL
  - **pinterestImageUrl** `string`: 
  - **pinterestTitle** `string`: 
  - **pinterestDescription** `string`: 
- **targeting** `object`: The ad set's targeting (age, gender, geo, interests, placements, audience inclusions/exclusions).
For ads created through Zernio this is the spec you supplied. For external ads (synced from
Meta Ads Manager, `isExternal: true`) targeting lives at the ad set and isn't stored at ingest,
so on the first `GET /v1/ads/{adId}` Zernio resolves it live from Meta and caches it on the ad;
the value is then Meta's raw `targeting` shape (snake_case, e.g. `geo_locations`, `age_min`),
the same object Ads Manager shows. May be absent if the ad set exposes no targeting or the lookup fails.

- **schedule** `object`: 
  - **startDate** `string`: 
  - **endDate** `string`: 
- **rejectionReason** `string`: No description
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

---

# Fetch a single conversion destination API Reference

LinkedIn-only today. Returns the full destination record for one
conversion rule. The `adAccountId` query parameter is required because
LinkedIn rules are scoped to a sponsored ad account.


## GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}

**Fetch a single conversion destination**

LinkedIn-only today. Returns the full destination record for one
conversion rule. The `adAccountId` query parameter is required because
LinkedIn rules are scoped to a sponsored ad account.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (required) in query: Numeric ID or full `urn:li:sponsoredAccount:{id}` URN.

### Responses

#### 200: Destination fetched

**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **destination**: `ConversionDestination` - See schema definition

#### 400: Validation error.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support fetching a single destination.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## PATCH /v1/accounts/{accountId}/conversion-destinations/{destinationId}

**Update a conversion destination**

Partial-update a conversion rule. LinkedIn-only today. Whitelisted
fields: `name`, `enabled`, attribution windows, `valueType`, `value`,
`attributionType`. The rule's `type` and parent ad account are
intentionally not exposed for update — recreate the rule if those
need to change.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description

### Request Body

- **adAccountId** (required) `string`: No description
- **name** `string`: No description
- **enabled** `boolean`: Setting `false` is equivalent to calling DELETE — the
rule will appear as `inactive` afterwards.

- **attributionType** `string`: No description - one of: LAST_TOUCH_BY_CAMPAIGN, LAST_TOUCH_BY_CONVERSION
- **postClickAttributionWindowSize** `integer`: 365 only allowed for LEAD, PURCHASE, ADD_TO_CART,
QUALIFIED_LEAD, SUBMIT_APPLICATION rule types.
 - one of: 1, 7, 30, 90, 365
- **viewThroughAttributionWindowSize** `integer`: 365 only allowed for LEAD, PURCHASE, ADD_TO_CART,
QUALIFIED_LEAD, SUBMIT_APPLICATION rule types.
 - one of: 1, 7, 30, 90, 365
- **valueType** `string`: No description - one of: DYNAMIC, FIXED, NO_VALUE
- **value** `object`: Used when `valueType=FIXED`.

### Responses

#### 200: Destination updated (re-fetched canonical state)

**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **destination**: `ConversionDestination` - See schema definition

#### 400: Invalid body or LinkedIn validation failure.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support updating destinations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}

**Soft-delete a conversion destination**

LinkedIn-only today. LinkedIn does not expose hard-delete on conversion
rules — what their UI calls "delete" is the same `enabled: false` flip
we apply here. The rule remains fetchable via GET with
`status: 'inactive'`; the unified discovery endpoint hides it by
default.

`adAccountId` may be passed as a query parameter (recommended) or as
a JSON body field for clients that can send DELETE bodies.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (optional) in query: Required as query OR in JSON body.

### Responses

#### 204: Soft-deleted.

#### 400: adAccountId missing.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support deleting destinations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---


# Related Schema Definitions

## ConversionDestination

A discoverable conversion destination on an ad platform — a Meta pixel,
Google conversion action, or LinkedIn conversion rule. Returned by
`listConversionDestinations`, `getConversionDestination`,
`createConversionDestination`, and `updateConversionDestination`.


### Properties

- **id** (required) `string`: Platform-native identifier. Pass back as `destinationId` on event
send and as the path segment on CRUD endpoints.

- **name** (required) `string`: No description
- **type** `string`: Present when the platform locks the event type/category to the
destination (Google conversion actions, LinkedIn conversion rules).
Absent for Meta pixels (which accept any event name per request).

- **status** `string`: For LinkedIn, `inactive` means the rule is soft-deleted (`enabled: false`).
 - one of: active, inactive
- **adAccountId** `string`: Set by adapters whose destinations are scoped to a specific ad
account (LinkedIn). Pass back on subsequent CRUD calls to
identify the parent ad account.

---

# Fetch attribution metrics for a conversion destination API Reference

LinkedIn-only today. Returns conversion-attribution metrics
(`externalWebsiteConversions`, `externalWebsitePostClickConversions`,
`externalWebsitePostViewConversions`, `conversionValueInLocalCurrency`,
`qualifiedLeads`, `costInLocalCurrency`) bucketed by date.

Date-range constraints (passed through from LinkedIn):
- `granularity=DAILY` is retained for ~6 months only
- `granularity=ALL` with a range > 6 months auto-rounds to month boundaries
- `granularity=MONTHLY`/`YEARLY` retains 24 months

Throttle: LinkedIn caps adAnalytics at 45M metric values per 5-minute
window across the calling token. Single-rule queries are well within
that limit; surfaces as 429 if hit.


## GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}/metrics

**Fetch attribution metrics for a conversion destination**

LinkedIn-only today. Returns conversion-attribution metrics
(`externalWebsiteConversions`, `externalWebsitePostClickConversions`,
`externalWebsitePostViewConversions`, `conversionValueInLocalCurrency`,
`qualifiedLeads`, `costInLocalCurrency`) bucketed by date.

Date-range constraints (passed through from LinkedIn):
- `granularity=DAILY` is retained for ~6 months only
- `granularity=ALL` with a range > 6 months auto-rounds to month boundaries
- `granularity=MONTHLY`/`YEARLY` retains 24 months

Throttle: LinkedIn caps adAnalytics at 45M metric values per 5-minute
window across the calling token. Single-rule queries are well within
that limit; surfaces as 429 if hit.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (required) in query: No description
- **startDate** (required) in query: No description
- **endDate** (optional) in query: No description
- **granularity** (optional) in query: No description

### Responses

#### 200: Metrics rows

**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **granularity** `string`: No description - one of: ALL, DAILY, MONTHLY, YEARLY
- **rows** `array[object]`: 
  - **start** `string`: YYYY-MM-DD
  - **end** `string`: YYYY-MM-DD (inclusive)
  - **metrics** `object`: No description

#### 400: Validation error or invalid date range.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support metrics readback.

#### 429: LinkedIn analytics rate limit hit.

---

---

# Read Event Match Quality + coverage for a Meta pixel API Reference

Reads Meta Event Match Quality (EMQ) and pixel↔CAPI event coverage for a
pixel/dataset, live from Meta's Dataset Quality API. Web events only (a
Meta limitation). Meta-only; other platforms return 405. Requires the Ads add-on.


## GET /v1/ads/conversions/quality

**Read Event Match Quality + coverage for a Meta pixel**

Reads Meta Event Match Quality (EMQ) and pixel↔CAPI event coverage for a
pixel/dataset, live from Meta's Dataset Quality API. Web events only (a
Meta limitation). Meta-only; other platforms return 405. Requires the Ads add-on.


### Parameters

- **accountId** (required) in query: SocialAccount _id (must be a metaads account).
- **destinationId** (required) in query: Meta pixel/dataset ID.

### Responses

#### 200: Match-quality rows, one per event name.

**Response Body:**

- **platform** `string`: No description (example: "metaads")
- **rows** `array[object]`: 
  - **eventName** `string`: No description
  - **compositeScore** `number`: Composite EMQ score, 0-10.
  - **matchKeys** `array[object]`: 
    - **identifier** `string`: No description
    - **coveragePercentage** `number`: No description
  - **eventCoveragePercentage** `number`: Pixel↔CAPI coverage rate for this event.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 405: Platform does not expose Event Match Quality (non-Meta).

---

---

# Get a single Lead Gen form API Reference



## GET /v1/ads/lead-forms/{formId}

**Get a single Lead Gen form**

### Parameters

- **formId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Form metadata.

**Response Body:**

- **status** `string`: No description
- **form** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/ads/lead-forms/{formId}

**Archive a Lead Gen form**

Meta has no hard delete for forms; this archives the form (status=ARCHIVED).

### Parameters

- **formId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Archived.

**Response Body:**

- **status** `string`: No description
- **formId** `string`: No description
- **archived** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# List ad accounts API Reference

Returns the platform ad accounts available for the given social account (e.g. Meta ad
accounts, TikTok advertiser IDs, Google Ads customer IDs).

For TikTok agencies: enumerates every advertiser under every Business Center the token
can read (paginated server-side), then chunks the lookup against TikTok's
`/advertiser/info/` endpoint (which has a per-call cap of ≤100 IDs). Solo advertisers
without a BC fall back to the OAuth-time `advertiser_ids` list. Cached for 1h on the
SocialAccount; lazy-refreshed on first call after expiry.


## GET /v1/ads/accounts

**List ad accounts**

Returns the platform ad accounts available for the given social account (e.g. Meta ad
accounts, TikTok advertiser IDs, Google Ads customer IDs).

For TikTok agencies: enumerates every advertiser under every Business Center the token
can read (paginated server-side), then chunks the lookup against TikTok's
`/advertiser/info/` endpoint (which has a per-call cap of ≤100 IDs). Solo advertisers
without a BC fall back to the OAuth-time `advertiser_ids` list. Cached for 1h on the
SocialAccount; lazy-refreshed on first call after expiry.


### Parameters

- **accountId** (required) in query: Social account ID
- **adAccountId** (optional) in query: Filter response to a single platform ad account ID (e.g. `act_123` for Meta, advertiser_id for TikTok). Returns at most one item.
- **limit** (optional) in query: Clamp the returned `accounts[]` length. Useful for typeahead pickers on agency tokens with hundreds of advertisers.

### Responses

#### 200: Ad accounts

**Response Body:**

- **accounts** `array[object]`: 
  - **id** `string`: Platform ad account ID (e.g. act_123)
  - **name** `string`: No description
  - **currency** `string`: No description
  - **status** `string`: No description
  - **timezoneName** `string`: IANA timezone of the ad account (Meta only). Drives daily-budget reset and Insights day boundaries.
  - **timezoneOffsetHoursUtc** `number`: Signed UTC offset in hours, reflecting current DST (Meta only).

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 422: Platform ads connection required (TikTok Ads, X Ads) or Instagram missing linked Facebook account

---

---

# List a catalog's product sets API Reference

Lists a Meta product catalog's product sets — the unit a catalog ad promotes. Pass the chosen set as `promotedObject.productSetId` on POST /v1/ads/create with `goal: catalog_sales`.

## GET /v1/ads/catalogs/{catalogId}/product-sets

**List a catalog's product sets**

Lists a Meta product catalog's product sets — the unit a catalog ad promotes. Pass the chosen set as `promotedObject.productSetId` on POST /v1/ads/create with `goal: catalog_sales`.

### Parameters

- **catalogId** (required) in path: Meta product catalog ID (from GET /v1/ads/catalogs)
- **accountId** (required) in query: A facebook, instagram, or metaads social account ID

### Responses

#### 200: Product sets

**Response Body:**

- **productSets** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **productCount** `integer`: No description

---

---

# List Meta product catalogs API Reference

Lists the Meta product catalogs reachable from an ad account (owned + agency-shared catalogs of the ad account's business), for Advantage+ catalog ads (`goal: catalog_sales` on POST /v1/ads/create — e.g. vehicle inventory catalogs). Read-only; uses scopes customers already granted (no reconnect needed). Catalog contents (items, feeds) are managed in Meta Commerce Manager, not through this API.

## GET /v1/ads/catalogs

**List Meta product catalogs**

Lists the Meta product catalogs reachable from an ad account (owned + agency-shared catalogs of the ad account's business), for Advantage+ catalog ads (`goal: catalog_sales` on POST /v1/ads/create — e.g. vehicle inventory catalogs). Read-only; uses scopes customers already granted (no reconnect needed). Catalog contents (items, feeds) are managed in Meta Commerce Manager, not through this API.

### Parameters

- **accountId** (required) in query: A facebook, instagram, or metaads social account ID
- **adAccountId** (required) in query: Meta ad account ID (act_...)

### Responses

#### 200: Catalogs

**Response Body:**

- **catalogs** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **vertical** `string`: Catalog vertical (e.g. commerce, vehicles, hotels)
  - **productCount** `integer`: No description

---

---

# List TikTok Business Centers API Reference

Returns the TikTok Business Centers (BCs) the connected `tiktokads` account can read.
Each BC reports its advertiser count so callers can build agency-style pickers
without re-walking `/v1/ads/accounts` per BC.

TikTok-only. Solo advertisers (non-agency tokens) return an empty array.


## GET /v1/ads/business-centers

**List TikTok Business Centers**

Returns the TikTok Business Centers (BCs) the connected `tiktokads` account can read.
Each BC reports its advertiser count so callers can build agency-style pickers
without re-walking `/v1/ads/accounts` per BC.

TikTok-only. Solo advertisers (non-agency tokens) return an empty array.


### Parameters

- **accountId** (required) in query: ID of the `tiktokads` (or parent `tiktok` posting) SocialAccount

### Responses

#### 200: Business centers

**Response Body:**

- **businessCenters** `array[BusinessCenter]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: TikTok account not found

#### 422: TikTok Ads not connected

---


# Related Schema Definitions

## BusinessCenter

TikTok Business Center entity. Returned by `GET /v1/ads/business-centers`. BCs are
TikTok's agency container — one BC owns N advertisers (ad accounts). Most solo
advertisers don't have one; the agency token uses BCs to roll up multi-client access.


### Properties

- **bcId** `string`: Business Center ID
- **name** `string`: Display name set by the BC owner
- **advertiserCount** `integer`: Number of advertisers reachable under this BC for the calling token.
`null` when the BC asset walk returned empty or failed (typical for
agency apps without full BC asset read scope) — distinct from `0`,
which would imply the BC genuinely has no advertisers.

---

# List ads API Reference

Returns 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.
If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max.

To find the Zernio ad behind a comment you see in Meta Business Manager, 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. Then call
GET /v1/ads/{adId}/comments with the returned ad id.


## GET /v1/ads

**List ads**

Returns 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.
If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max.

To find the Zernio ad behind a comment you see in Meta Business Manager, 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. Then call
GET /v1/ads/{adId}/comments with the returned ad id.


### Parameters

- **undefined** (optional): No description
- **limit** (optional) in query: No description
- **source** (optional) in query: all (default) = Zernio-created + platform-discovered ads. zernio = restrict to Zernio-created only.
- **status** (optional) in query: No description
- **platform** (optional) in query: No description
- **accountId** (optional) in query: Social account ID
- **adAccountId** (optional) in query: Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree.
- **profileId** (optional) in query: Profile ID
- **campaignId** (optional) in query: Platform campaign ID (filter ads within a campaign)
- **platformAdId** (optional) in query: Meta ad ID. Returns the ad with this platform-side ad ID.
- **effectiveObjectStoryId** (optional) in query: 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.
- **effectiveInstagramMediaId** (optional) in query: 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.
- **fromDate** (optional) in query: Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.
- **toDate** (optional) in query: End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range.

### Responses

#### 200: Paginated ads

**Response Body:**

- **ads** `array[Ad]`: 
- **pagination**: `Pagination` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

---


# Related Schema Definitions

## Ad

### Properties

- **_id** `string`: No description
- **name** `string`: No description
- **platform** `string`: No description - one of: facebook, instagram, tiktok, linkedin, pinterest, google, twitter
- **status**: No description
- **adType** `string`: No description - one of: boost, standalone
- **goal** `string`: Available goals vary by platform. Meta (Facebook/Instagram) supports all 9 (incl. `lead_conversion` = website pixel lead optimization and `catalog_sales` = Advantage+ catalog ads). TikTok supports the 7 non-`lead_conversion` goals. LinkedIn supports all except app_promotion / lead_conversion. Twitter/X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views. - one of: engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales
- **isExternal** `boolean`: True for ads synced from platform ad managers
- **budget** `object`: 
  - **amount** `number`: 
  - **type** `string`:  - one of: daily, lifetime
- **metrics**: No description
- **platformAdId** `string`: No description
- **platformAdAccountId** `string`: No description
- **platformCampaignId** `string`: No description
- **platformAdSetId** `string`: No description
- **campaignName** `string`: No description
- **adSetName** `string`: No description
- **platformObjective** `string`: Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC). Only present for Meta ads.
- **optimizationGoal** `string`: Meta ad set optimization goal (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION, LINK_CLICKS). Only present for Meta ads.
- **platformAdAccountName** `string`: Human-readable advertiser/account name (Meta `AdAccount.name`, TikTok
`advertiser_name`, LinkedIn / X / Pinterest equivalents). Refreshed every
sync so platform-side renames propagate within one cycle. `null` when the
platform doesn't return a name or the sync hasn't run yet.

- **platformCreatedAt** `string`: Platform-reported creation timestamp (Meta `created_time`, TikTok `create_time`).
Distinct from `createdAt` which reflects when Zernio first synced the doc — for
sort/filter by "when the ad was actually created on the platform", read this field.
`null` for legacy ads synced before this field was added; aggregations fall back
to `createdAt` in that case.

- **bidStrategy**: Ad-set bid strategy (overrides campaign level on Meta). Populated for Meta and
TikTok. TikTok's native `bid_type` is normalized to the cross-platform Meta enum:
`BID_TYPE_NO_BID` -> `LOWEST_COST_WITHOUT_CAP`, `BID_TYPE_CUSTOM` ->
`LOWEST_COST_WITH_BID_CAP`, deep_bid_type=MIN_ROAS or roas_bid>0 ->
`LOWEST_COST_WITH_MIN_ROAS`, `BID_TYPE_MAX_CONVERSION` -> `LOWEST_COST_WITHOUT_CAP`.

- **bidAmount** `number`: Bid cap in WHOLE currency units of the ad account (USD: 5 = $5.00; JPY: 100 = ¥100).
Populated when bidStrategy is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`. `null` for
auto-bid (`LOWEST_COST_WITHOUT_CAP`).

- Meta source: `bid_amount` on the ad set (smallest-denomination int, decoded here).
- TikTok source: priority order `bid_price` -> `conversion_bid_price` -> `deep_cpa_bid`
  (whichever is set on the ad group). TikTok stores all three in whole currency units.

Source: facebook-business-sdk-codegen api_specs/specs/AdSet.json (`bid_amount`).

- **roasAverageFloor** `number`: Minimum ROAS as a decimal multiplier (2.0 = 2.0x ROAS). Populated when bidStrategy
is `LOWEST_COST_WITH_MIN_ROAS`.

- Meta source: decoded from `bid_constraints.roas_average_floor` (Meta stores as
  fixed-point int × 10000; we return the decimal).
- TikTok source: `roas_bid` on the ad group (already a decimal).

Source: facebook-business-sdk-codegen api_specs/specs/AdCampaignBidConstraint.json.

- **promotedObject** `object`: Meta promoted object containing conversion event details. Structure varies by objective. Only present for Meta ads.
  - **custom_event_type** `string`: Conversion event type (e.g. PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART)
  - **pixel_id** `string`: Meta pixel ID
  - **page_id** `string`: Facebook page ID
  - **application_id** `string`: Facebook app ID
  - **product_set_id** `string`: Product catalog set ID
- **creative** `object`: Platform-specific creative data. Fields vary by platform.
  - **thumbnailUrl** `string`: Primary thumbnail/image URL
  - **imageUrl** `string`: Alternative image URL
  - **videoId** `string`: Meta video ID for VIDEO-type ads. Null for non-video ads. Callers that need an embeddable MP4 can call GET /{videoId}?fields=source with the page access token.
  - **videoUrl** `string`: Public Facebook watch URL for VIDEO-type ads (https://www.facebook.com/watch/?v={videoId}). Null for non-video ads.
  - **objectType** `string`: 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** `string`: Meta creative `object_story_id` (the SHARE reference). Frequently absent — Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead.
  - **effectiveObjectStoryId** `string`: Meta `effective_object_story_id` — `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. Pass to GET /v1/ads?effectiveObjectStoryId= to map a Business-Manager-visible post back to this ad; GET /v1/ads/{adId}/comments resolves comments against it.
  - **effectiveInstagramMediaId** `string`: 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** `string`: Meta `instagram_user_id` — the Instagram-scoped business ID that owns the boosted media.
  - **instagramPermalinkUrl** `string`: Meta `instagram_permalink_url` — public Instagram post URL of the boosted media.
  - **mediaUrls** `array`: 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).
  - **body** `string`: Ad copy/text
  - **googleHeadline** `string`: Google Ads headline
  - **googleDescription** `string`: Google Ads description
  - **linkUrl** `string`: Destination URL
  - **pinterestImageUrl** `string`: 
  - **pinterestTitle** `string`: 
  - **pinterestDescription** `string`: 
- **targeting** `object`: The ad set's targeting (age, gender, geo, interests, placements, audience inclusions/exclusions).
For ads created through Zernio this is the spec you supplied. For external ads (synced from
Meta Ads Manager, `isExternal: true`) targeting lives at the ad set and isn't stored at ingest,
so on the first `GET /v1/ads/{adId}` Zernio resolves it live from Meta and caches it on the ad;
the value is then Meta's raw `targeting` shape (snake_case, e.g. `geo_locations`, `age_min`),
the same object Ads Manager shows. May be absent if the ad set exposes no targeting or the lookup fails.

- **schedule** `object`: 
  - **startDate** `string`: 
  - **endDate** `string`: 
- **rejectionReason** `string`: No description
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

## Pagination

### Properties

- **page** `integer`: No description
- **limit** `integer`: No description
- **total** `integer`: No description
- **pages** `integer`: No description

---

# List campaigns associated with a conversion destination API Reference

LinkedIn-only today. Returns the campaigns currently associated with
this conversion rule. Note that auto-association on rule creation
runs once at create time; campaigns created after the rule still need
explicit association.


## GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations

**List campaigns associated with a conversion destination**

LinkedIn-only today. Returns the campaigns currently associated with
this conversion rule. Note that auto-association on rule creation
runs once at create time; campaigns created after the rule still need
explicit association.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (required) in query: No description

### Responses

#### 200: Associations listed

**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **associations** `array[object]`: 
  - **campaignId** `string`: No description
  - **conversionId** `string`: No description
  - **associatedAt** `integer`: Epoch ms.

#### 400: Validation error.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support associations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## POST /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations

**Associate campaigns with a conversion destination**

Associate one or more campaigns with this conversion rule. Returns a
per-campaign success/failure result so callers can retry only the
rows that failed (e.g. wrong campaign type for the rule's objective).


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description

### Request Body

- **adAccountId** (required) `string`: No description
- **campaignIds** (required) `array`: No description

### Responses

#### 200: Per-campaign batch result. Status is 200 even when some rows
failed — inspect `failed[]` for details. Inputs that fail local
URN validation are bucketed into `failed` without ever hitting
LinkedIn.


**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **succeeded** `array[string]`: Numeric campaign IDs that were successfully associated.
- **failed** `array[object]`: 
  - **campaignId** `string`: No description
  - **reason** `string`: No description

#### 400: Invalid body.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support associations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations

**Remove campaign↔conversion associations**

Remove one or more campaign associations from this conversion rule.
Pass `adAccountId` and `campaignIds` as query parameters
(`campaignIds` is comma-separated). The route also accepts a JSON
body with the same fields for clients that prefer DELETE-with-body,
but 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.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (required) in query: No description
- **campaignIds** (required) in query: Comma-separated list of campaign IDs.

### Responses

#### 200: Per-campaign batch result. Status is 200 even when some rows
failed — inspect `failed[]` for details.


**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **succeeded** `array[string]`: Numeric campaign IDs that were successfully removed.
- **failed** `array[object]`: 
  - **campaignId** `string`: No description
  - **reason** `string`: No description

#### 400: Validation error: missing `adAccountId` or `campaignIds`, or
campaignIds exceeds 100 entries per request.


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support associations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

---

# List destinations for the Conversions API API Reference

Returns the list of pixels (Meta), conversion actions (Google), or
conversion rules (LinkedIn) accessible to the connected ads account.
Use the returned `id` as `destinationId` when posting to
`POST /v1/ads/conversions`.

For Google and LinkedIn, each destination's `type` reflects the
conversion type (PURCHASE, LEAD, SIGN_UP, etc.) — the event type is
locked to the destination. For Meta, `type` is absent: pixels accept
any event name per request.

For LinkedIn, destinations are returned across every sponsored ad
account the connected token can access; the `adAccountId` field on
each destination identifies the parent ad account and is required for
subsequent CRUD calls (update, delete, associations, metrics).


## GET /v1/accounts/{accountId}/conversion-destinations

**List destinations for the Conversions API**

Returns the list of pixels (Meta), conversion actions (Google), or
conversion rules (LinkedIn) accessible to the connected ads account.
Use the returned `id` as `destinationId` when posting to
`POST /v1/ads/conversions`.

For Google and LinkedIn, each destination's `type` reflects the
conversion type (PURCHASE, LEAD, SIGN_UP, etc.) — the event type is
locked to the destination. For Meta, `type` is absent: pixels accept
any event name per request.

For LinkedIn, destinations are returned across every sponsored ad
account the connected token can access; the `adAccountId` field on
each destination identifies the parent ad account and is required for
subsequent CRUD calls (update, delete, associations, metrics).


### Parameters

- **accountId** (required) in path: SocialAccount ID (metaads, googleads, or linkedinads).

### Responses

#### 200: Destinations listed

**Response Body:**

- **platform** `string`: No description - one of: metaads, googleads, linkedinads
- **destinations** `array[object]`: 
  - **id** `string`: Destination identifier. Meta: pixel ID. Google:
conversion action resource name. LinkedIn:
numeric conversion rule ID.

  - **name** `string`: No description
  - **type** `string`: Present when the platform locks event type to the
destination (Google conversion actions, LinkedIn
conversion rules).

  - **status** `string`: No description - one of: active, inactive
  - **adAccountId** `string`: Set by adapters whose destinations are scoped to a
specific ad account (LinkedIn). Pass back on
subsequent CRUD calls.


#### 400: Account's platform is not supported by the Conversions API.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans),
OR (for LinkedIn) the connected account lacks the `rw_conversions` scope and must be reconnected.


#### 404: Account not found or not accessible.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## POST /v1/accounts/{accountId}/conversion-destinations

**Create a conversion destination (LinkedIn, Google Ads)**

Create a new conversion destination on the platform. Supported for
LinkedIn (conversion rule) and Google Ads (conversion action). Meta
manages destinations in its own UI and returns 405.

**LinkedIn:** creation is NOT idempotent. A retry creates a second
destination. Deduplicate before retrying.

**Google Ads:** calling 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.

**LinkedIn:** the 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.

365-day attribution windows are only valid for `SUBMIT_APPLICATION`,
`PURCHASE`, `ADD_TO_CART`, `QUALIFIED_LEAD`, and `LEAD` rule types;
the API rejects other combinations locally.

**Google Ads:** the conversion action is created with
`type=UPLOAD_CLICKS` (required for API-uploaded offline conversions,
immutable after creation). The `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. The action defaults to
secondary (non-primary) to avoid immediately steering Smart Bidding;
pass `primaryForGoal: true` to opt in.


### Parameters

- **accountId** (required) in path: SocialAccount ID (linkedinads or googleads).

### Request Body

- **adAccountId** (required) `string`: Ad account ID. For LinkedIn: numeric (e.g. "5123456") or
full `urn:li:sponsoredAccount:{id}` URN. For Google: numeric
customer ID (e.g. "1234567890") or `customers/{id}` form.

- **name** (required) `string`: No description
- **type** (required) `string`: Conversion type. For LinkedIn: a unified standard event name
(e.g. "Purchase", "Lead", "AddToCart") or a LinkedIn rule
type enum (e.g. "PURCHASE", "QUALIFIED_LEAD"). For 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"). Unknown values pass through to the
platform.

- **attributionType** `string`: LinkedIn only. - one of: LAST_TOUCH_BY_CAMPAIGN, LAST_TOUCH_BY_CONVERSION
- **postClickAttributionWindowSize** `integer`: LinkedIn only. Default 30. 365 only allowed for LEAD,
PURCHASE, ADD_TO_CART, QUALIFIED_LEAD, SUBMIT_APPLICATION
rule types; the API rejects other combinations locally.
 - one of: 1, 7, 30, 90, 365
- **viewThroughAttributionWindowSize** `integer`: LinkedIn only. Default 7. Same 365-day-window type
restriction applies as `postClickAttributionWindowSize`.
 - one of: 1, 7, 30, 90, 365
- **valueType** `string`: LinkedIn only. DYNAMIC (default) uses the per-event `value`
from `sendConversions`. FIXED uses the rule's `value` field.
NO_VALUE drops monetary value entirely.
 - one of: DYNAMIC, FIXED, NO_VALUE
- **value** `object`: LinkedIn only. Static conversion value. Used when
`valueType=FIXED`. The currency should match the ad
account's currency.

- **autoAssociationType** `string`: LinkedIn only. Controls campaign association at rule-creation
time:
- ALL_CAMPAIGNS: associate the rule with every active,
  paused, and draft campaign in the ad account
- OBJECTIVE_BASED: associate only campaigns whose
  objective matches the rule's type
- NONE: don't auto-associate. Manage associations via
  the `/associations` endpoints below.
Note: auto-association runs once at create time; new
campaigns added after the rule still need explicit
association.
 - one of: ALL_CAMPAIGNS, OBJECTIVE_BASED, NONE
- **countingType** `string`: Google Ads only. Whether to count multiple conversions from
the same click (MANY_PER_CLICK) or at most one
(ONE_PER_CLICK). Defaults to MANY_PER_CLICK if omitted.
 - one of: MANY_PER_CLICK, ONE_PER_CLICK
- **primaryForGoal** `boolean`: Google Ads only. When true, the conversion action is marked
as primary and immediately influences Smart Bidding. Defaults
to false (secondary, record-only) to avoid unintentionally
steering the customer's campaigns on creation.


### Responses

#### 201: Destination created

**Response Body:**

- **platform** `string`: No description - one of: linkedinads, googleads
- **destination**: `ConversionDestination` - See schema definition

#### 400: Invalid body or platform validation failure.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: 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).


#### 404: Account not found or not accessible.

#### 405: Platform does not support destination creation.

#### 409: Google Ads only. A conversion action with the given name already
exists but has a different category. Use a different name or use
the existing destination. Error code: `IDEMPOTENCY_CONFLICT`.


#### 429: Rate limit hit. Retry with backoff.

---


# Related Schema Definitions

## ConversionDestination

A discoverable conversion destination on an ad platform — a Meta pixel,
Google conversion action, or LinkedIn conversion rule. Returned by
`listConversionDestinations`, `getConversionDestination`,
`createConversionDestination`, and `updateConversionDestination`.


### Properties

- **id** (required) `string`: Platform-native identifier. Pass back as `destinationId` on event
send and as the path segment on CRUD endpoints.

- **name** (required) `string`: No description
- **type** `string`: Present when the platform locks the event type/category to the
destination (Google conversion actions, LinkedIn conversion rules).
Absent for Meta pixels (which accept any event name per request).

- **status** `string`: For LinkedIn, `inactive` means the rule is soft-deleted (`enabled: false`).
 - one of: active, inactive
- **adAccountId** `string`: Set by adapters whose destinations are scoped to a specific ad
account (LinkedIn). Pass back on subsequent CRUD calls to
identify the parent ad account.

---

# List leads for a single form API Reference

Returns leads for one form. Serves persisted leads (ingested via the leadgen webhook) when available, falling back to a live Graph read.


## GET /v1/ads/lead-forms/{formId}/leads

**List leads for a single form**

Returns leads for one form. Serves persisted leads (ingested via the leadgen webhook) when available, falling back to a live Graph read.


### Parameters

- **formId** (required) in path: No description
- **accountId** (required) in query: No description
- **limit** (optional) in query: No description
- **cursor** (optional) in query: No description
- **since** (optional) in query: Unix seconds.

### Responses

#### 200: Leads for the form.

**Response Body:**

- **status** `string`: No description (example: "success")
- **leads** `array[object]`: 
  - **id** `string`: No description
  - **createdTime** `string`: No description
  - **adId** `string`: No description
  - **formId** `string`: No description
  - **fields** `object`: No description
  - **fieldData** `array[object]`: 
    Type: `object`
- **pagination** `object`: 
  - **hasMore** `boolean`: No description
  - **cursor** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# List Lead Gen (Instant) forms API Reference

Lists the Lead Gen forms owned by the connected Facebook Page. Requires the Ads add-on.

## GET /v1/ads/lead-forms

**List Lead Gen (Instant) forms**

Lists the Lead Gen forms owned by the connected Facebook Page. Requires the Ads add-on.

### Parameters

- **accountId** (required) in query: Connected facebook account id.
- **limit** (optional) in query: No description
- **cursor** (optional) in query: No description

### Responses

#### 200: Forms list.

**Response Body:**

- **status** `string`: No description (example: "success")
- **forms** `array[object]`: 
  Type: `object`
- **pagination** `object`: 
  - **hasMore** `boolean`: No description
  - **cursor** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on required.

---

## POST /v1/ads/lead-forms

**Create a Lead Gen (Instant) form**

Creates a Lead Gen form on the connected Facebook Page (POST /{page-id}/leadgen_forms). NOT idempotent — a retry creates a second form. Prefilled question types (EMAIL, PHONE, FULL_NAME, …) must omit label/key; CUSTOM questions require both. Requires the Ads add-on.


### Request Body

- **accountId** (required) `string`: No description
- **name** (required) `string`: No description
- **questions** (required) `array`: No description
- **privacyPolicyUrl** (required) `string`: No description
- **privacyPolicyLinkText** `string`: No description
- **followUpActionUrl** `string`: No description
- **locale** `string`: No description
- **thankYouTitle** `string`: No description
- **thankYouBody** `string`: No description
- **thankYouButtonText** `string`: No description
- **thankYouButtonType** `string`: No description
- **thankYouWebsiteUrl** `string`: No description
- **isOptimizedForQuality** `boolean`: No description

### Responses

#### 200: Created form.

**Response Body:**

- **status** `string`: No description (example: "success")
- **form** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on required.

---

---

# List submitted leads (cross-form CRM view) API Reference

Returns persisted Meta Lead Gen leads for your team, newest-first, with keyset pagination on `cursor`. Leads are ingested in real time from the `leadgen` webhook. Requires the Ads add-on.


## GET /v1/ads/leads

**List submitted leads (cross-form CRM view)**

Returns persisted Meta Lead Gen leads for your team, newest-first, with keyset pagination on `cursor`. Leads are ingested in real time from the `leadgen` webhook. Requires the Ads add-on.


### Parameters

- **formId** (optional) in query: Filter to a single lead form.
- **accountId** (optional) in query: Filter to a single connected account.
- **limit** (optional) in query: No description
- **since** (optional) in query: Unix seconds; only leads created at/after this Meta timestamp.
- **cursor** (optional) in query: Keyset cursor from a previous response's pagination.cursor.

### Responses

#### 200: Lead list.

**Response Body:**

- **status** `string`: No description (example: "success")
- **leads** `array[object]`: 
  - **id** `string`: Zernio lead id.
  - **leadgenId** `string`: Meta lead id.
  - **formId** `string`: No description
  - **formName** `string`: No description
  - **accountId** `string`: No description
  - **adId** `string`: No description
  - **adsetId** `string`: No description
  - **campaignId** `string`: No description
  - **isOrganic** `boolean`: No description
  - **createdTime** `string`: ISO 8601.
  - **fields** `object`: Question key → answer.
  - **fieldData** `array[object]`: Raw Meta field_data.
    Type: `object`
- **pagination** `object`: 
  - **hasMore** `boolean`: No description
  - **cursor** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on required.

---

---

# List recent WhatsApp conversion events API Reference

Returns the most recent conversion events sent through
`POST /v1/whatsapp/conversions` for the given WhatsApp account.
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.

Per-event payload mirrors the structured log we write on every
successful send: `eventName`, `conversationId`, `eventsReceived`,
`eventsFailed`, `traceId`, `durationMs`, and the wall-clock
`timestamp`.


## GET /v1/whatsapp/conversions

**List recent WhatsApp conversion events**

Returns the most recent conversion events sent through
`POST /v1/whatsapp/conversions` for the given WhatsApp account.
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.

Per-event payload mirrors the structured log we write on every
successful send: `eventName`, `conversationId`, `eventsReceived`,
`eventsFailed`, `traceId`, `durationMs`, and the wall-clock
`timestamp`.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID
- **limit** (optional) in query: Max events to return (1-200, default 50).

### Responses

#### 200: Recent conversion events

**Response Body:**

- **events** `array[object]`: 
  - **timestamp** `string` (date-time): When the event was sent to Meta.
  - **eventName** `string`: One of LeadSubmitted, Purchase, AddToCart, InitiateCheckout, ViewContent.
  - **conversationId** `string`: No description
  - **eventsReceived** `integer`: Number of events Meta accepted on this send (usually 1).
  - **eventsFailed** `integer`: Number of events Meta rejected (usually 0).
  - **traceId** `string`: Meta fbtrace_id for cross-referencing in Events Manager.
  - **durationMs** `integer`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/conversions

**Send WhatsApp conversion event**

Forward a WhatsApp Business Messaging conversion event (`LeadSubmitted`,
`Purchase`, `AddToCart`, `InitiateCheckout`, `ViewContent`) to Meta's
Conversions API with `action_source = business_messaging` and
`messaging_channel = whatsapp`. The endpoint looks up the originating
CTWA click ID (`ctwa_clid`) captured on the first inbound message of
the conversation and replays it on every event so Meta can attribute
the conversion back to the Click-to-WhatsApp ad that drove the chat.

Configuration prerequisite on the WhatsApp account metadata:
  - `metaCapiDatasetId`: the Meta dataset ID linked to the WABA.
    Provision one with `POST /v1/whatsapp/dataset`.

The WABA ID (already set automatically at connect time) is forwarded as
`user_data.whatsapp_business_account_id`, which is the per-channel
attribution identifier Meta requires for WhatsApp events. No Facebook
Page ID is needed (that field is the Messenger-branch identifier).

Identify the conversation by either `conversationId` (preferred) or
`phoneE164` (digits only, no `+`). At least one is required. If the
conversation has no captured `ctwa_clid`, the request returns 422
because there is nothing to attribute.

Token and dataset coupling: the 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. Either share the dataset with the WhatsApp
app's Business in BM, or use a dataset already in the same Business
as the WABA.


### Request Body

- **accountId** (required) `string`: WhatsApp SocialAccount ID.
- **eventName** (required) `string`: Live-verified allowlist of event names accepted by Meta's
CAPI for Business Messaging (Graph API v25.0). Other
standard pixel events including `Lead`,
`CompleteRegistration`, `Subscribe`, `Schedule`, `Contact`,
`StartTrial`, `AddPaymentInfo`, `Search`, and
`SubmitApplication` are rejected with subcode 2804066
("Messaging Event Invalid Event Type") on
`action_source = business_messaging` events. Custom event
names are also rejected.

Use `LeadSubmitted` (NOT `Lead`) for lead-style conversions.
 - one of: LeadSubmitted, Purchase, AddToCart, InitiateCheckout, ViewContent
- **eventTime** `number`: Unix seconds. Defaults to the time of the request when
omitted. Meta's attribution window is 7 days from click;
events older than that lose attribution.

- **eventId** (required) `string`: Stable dedup key. Reuse to suppress duplicate events
(Meta dedupes against pixel events with the same id).

- **conversationId** `string`: Zernio Conversation `_id` (preferred lookup). The
conversation must have a captured `ctwa_clid` in metadata
(set automatically by the WhatsApp webhook on the first
inbound message after a CTWA ad click).

- **phoneE164** `string`: Contact phone number, digits only with no '+'. When used
in lieu of `conversationId`, the handler resolves to the
most recent CTWA-attributed conversation for this phone
on the supplied account.

- **value** `number`: Conversion value (e.g. order total).
- **currency** `string`: ISO 4217 currency code (e.g. `USD`).
- **contentIds** `array`: Optional product / content identifiers.
- **email** `string`: User email. Normalized + SHA-256 hashed before sending to Meta.
- **externalId** `string`: Stable customer identifier. Lowercased + SHA-256 hashed
before sending to Meta.

- **testCode** `string`: Meta `test_event_code` passthrough. Routes the event to
the Test Events tab in Events Manager instead of the
production dataset, useful for development.


### Responses

#### 200: Event submitted to Meta. Inspect `eventsFailed` and `failures[]`
to detect partial failures. A 200 does not mean Meta accepted the
event; the status reflects "request reached Meta" only.


**Response Body:**

- **platform** `string`: No description - one of: metaads
- **eventsReceived** `integer`: Events accepted by Meta.
- **eventsFailed** `integer`: Events rejected by Meta (see failures).
- **failures** `array[object]`: Per-event failure detail. Empty when all events were
accepted.

  - **eventIndex** `integer`: Index into the submitted events array.
  - **eventId** `string`: Echoes back the eventId of the failed event.
  - **message** `string`: No description
  - **code**: One of multiple types
- **traceId** `string`: Meta `fbtrace_id` for debugging. Surface in support
tickets.


#### 400: Invalid body.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Conversation not found.

#### 422: Configuration missing (no `metaCapiDatasetId` on the account, set
it via POST /v1/whatsapp/dataset) OR the resolved conversation has
no captured `ctwa_clid`.


---

---

# Remove campaign↔conversion associations API Reference

Remove one or more campaign associations from this conversion rule.
Pass `adAccountId` and `campaignIds` as query parameters
(`campaignIds` is comma-separated). The route also accepts a JSON
body with the same fields for clients that prefer DELETE-with-body,
but 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.


## GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations

**List campaigns associated with a conversion destination**

LinkedIn-only today. Returns the campaigns currently associated with
this conversion rule. Note that auto-association on rule creation
runs once at create time; campaigns created after the rule still need
explicit association.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (required) in query: No description

### Responses

#### 200: Associations listed

**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **associations** `array[object]`: 
  - **campaignId** `string`: No description
  - **conversionId** `string`: No description
  - **associatedAt** `integer`: Epoch ms.

#### 400: Validation error.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support associations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## POST /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations

**Associate campaigns with a conversion destination**

Associate one or more campaigns with this conversion rule. Returns a
per-campaign success/failure result so callers can retry only the
rows that failed (e.g. wrong campaign type for the rule's objective).


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description

### Request Body

- **adAccountId** (required) `string`: No description
- **campaignIds** (required) `array`: No description

### Responses

#### 200: Per-campaign batch result. Status is 200 even when some rows
failed — inspect `failed[]` for details. Inputs that fail local
URN validation are bucketed into `failed` without ever hitting
LinkedIn.


**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **succeeded** `array[string]`: Numeric campaign IDs that were successfully associated.
- **failed** `array[object]`: 
  - **campaignId** `string`: No description
  - **reason** `string`: No description

#### 400: Invalid body.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support associations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations

**Remove campaign↔conversion associations**

Remove one or more campaign associations from this conversion rule.
Pass `adAccountId` and `campaignIds` as query parameters
(`campaignIds` is comma-separated). The route also accepts a JSON
body with the same fields for clients that prefer DELETE-with-body,
but 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.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (required) in query: No description
- **campaignIds** (required) in query: Comma-separated list of campaign IDs.

### Responses

#### 200: Per-campaign batch result. Status is 200 even when some rows
failed — inspect `failed[]` for details.


**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **succeeded** `array[string]`: Numeric campaign IDs that were successfully removed.
- **failed** `array[object]`: 
  - **campaignId** `string`: No description
  - **reason** `string`: No description

#### 400: Validation error: missing `adAccountId` or `campaignIds`, or
campaignIds exceeds 100 entries per request.


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support associations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

---

# Search targeting interests (deprecated) API Reference

Deprecated alias for `GET /v1/ads/targeting/search?dimension=interest`. Kept for
backward compatibility, it returns the legacy `{ interests: [...] }` shape rather
than the normalized `{ results: [...] }`. New integrations should use
`GET /v1/ads/targeting/search` with `dimension=interest`.


## GET /v1/ads/interests

**Search targeting interests (deprecated)**

Deprecated alias for `GET /v1/ads/targeting/search?dimension=interest`. Kept for
backward compatibility, it returns the legacy `{ interests: [...] }` shape rather
than the normalized `{ results: [...] }`. New integrations should use
`GET /v1/ads/targeting/search` with `dimension=interest`.


### Parameters

- **q** (required) in query: Search query
- **accountId** (required) in query: Social account ID

### Responses

#### 200: Matching interests

**Response Body:**

- **interests** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **category** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

---

---

# Search targeting options API Reference

Resolve a human-readable query into the platform's opaque targeting ids used in
the `TargetingSpec` (`countries`/`regions`/`cities`/`zips`/`metros` geo keys, and
`interests`/`behaviors` entity ids) on `POST /v1/ads/create`,
`POST /v1/ads/targeting/reach-estimate`, and `saved_targeting` audiences.

The `dimension` param selects what is searched, `geo` (locations, further scoped
by `geoType`), `interest`, `behavior`, or `income`. Availability of each dimension
varies by platform (e.g. behaviours are Meta/TikTok only). Results are normalized
across platforms into a single shape, so the same client code consumes Meta,
TikTok, LinkedIn, X, Pinterest, and Google results.

For geo queries, `q` should contain only the locality name (e.g. `"Amsterdam"`,
not `"Amsterdam, NL"`). Use `countryCode` to disambiguate.


## GET /v1/ads/targeting/search

**Search targeting options**

Resolve a human-readable query into the platform's opaque targeting ids used in
the `TargetingSpec` (`countries`/`regions`/`cities`/`zips`/`metros` geo keys, and
`interests`/`behaviors` entity ids) on `POST /v1/ads/create`,
`POST /v1/ads/targeting/reach-estimate`, and `saved_targeting` audiences.

The `dimension` param selects what is searched, `geo` (locations, further scoped
by `geoType`), `interest`, `behavior`, or `income`. Availability of each dimension
varies by platform (e.g. behaviours are Meta/TikTok only). Results are normalized
across platforms into a single shape, so the same client code consumes Meta,
TikTok, LinkedIn, X, Pinterest, and Google results.

For geo queries, `q` should contain only the locality name (e.g. `"Amsterdam"`,
not `"Amsterdam, NL"`). Use `countryCode` to disambiguate.


### Parameters

- **accountId** (required) in query: Social account ID (a connected account on the target ad platform).
- **q** (required) in query: Search query. For geo, the locality name only (no region/country suffix).
- **dimension** (optional) in query: What to search. `geo` resolves locations (scope further with `geoType`), `interest`/`behavior` resolve audience entities, `income` resolves income-tier options. Defaults to `interest` for backward compatibility with the deprecated /v1/ads/interests alias.
- **geoType** (optional) in query: Only used when `dimension=geo`. The kind of location to resolve. Defaults to `city`.
- **countryCode** (optional) in query: ISO 3166-1 alpha-2 country code (e.g. NL) to scope a geo search.
- **limit** (optional) in query: Maximum results to return.

### Responses

#### 200: Matching targeting options (normalized)

**Response Body:**

- **results** `array[object]`: 
  - **id** (required) `string`: The platform's opaque id. Use as a geo `key` (regions/cities/zips/metros) or an entity `id` (interests/behaviors) in TargetingSpec.
  - **name** (required) `string`: Human-readable label.
  - **type** (required) `string`: What the result is (e.g. city, region, country, zip, metro, interest, behavior, income).
  - **path** `array[string]`: Optional breadcrumb of parent labels (e.g. ['United States', 'California', 'Los Angeles']). Disambiguates same-named results.
  - **audienceSize** `integer`: Optional estimated reachable users for this option, when the platform returns it.

#### 400: Missing or invalid query parameters

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.

#### 404: Account not found, or the platform does not support the requested dimension

---

---

# Send conversion events to an ad platform API Reference

Relay one or more conversion events to the target ad platform's native Conversions API.
Platform is inferred from the provided `accountId`. Requires the Ads add-on.

Supported platforms:

- Meta (`metaads`) via Graph API
- Google Ads (`googleads`) via Data Manager API `ingestEvents`
- LinkedIn (`linkedinads`) via `/rest/conversionEvents`

`destinationId` semantics differ per platform:

- Meta: pixel (dataset) ID, e.g. `123456789012345`
- Google: conversion action resource name, e.g. `customers/1234567890/conversionActions/987654321`
- LinkedIn: conversion rule ID or URN, e.g. `104012` or `urn:lla:llaPartnerConversion:104012`

Callers can list valid destinations via `GET /v1/accounts/{accountId}/conversion-destinations`.

All 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. LinkedIn `externalIds` are passed through as plaintext per LinkedIn's spec;
only emails and phones are hashed.

For LinkedIn, the connected account must have been authorized after the Conversions API
rollout (i.e. the OAuth grant must include `rw_conversions`). Older accounts must reconnect.

Batching is handled automatically. Meta caps at 1000 events per request and rejects the
entire batch if any event is malformed. Google caps at 2000. LinkedIn caps at 5000 and is
also all-or-nothing per chunk.

Dedup: pass a stable `eventId` on every event. Meta and LinkedIn use it to dedupe against
browser-side pixel/Insight Tag events; Google maps it to `transactionId`.

Per-platform `eventName` semantics:

- Meta: free-form. Standard names (Purchase, Lead, ...) match Meta's built-in events; custom strings are accepted.
- 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.
- 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.


## POST /v1/ads/conversions

**Send conversion events to an ad platform**

Relay one or more conversion events to the target ad platform's native Conversions API.
Platform is inferred from the provided `accountId`. Requires the Ads add-on.

Supported platforms:

- Meta (`metaads`) via Graph API
- Google Ads (`googleads`) via Data Manager API `ingestEvents`
- LinkedIn (`linkedinads`) via `/rest/conversionEvents`

`destinationId` semantics differ per platform:

- Meta: pixel (dataset) ID, e.g. `123456789012345`
- Google: conversion action resource name, e.g. `customers/1234567890/conversionActions/987654321`
- LinkedIn: conversion rule ID or URN, e.g. `104012` or `urn:lla:llaPartnerConversion:104012`

Callers can list valid destinations via `GET /v1/accounts/{accountId}/conversion-destinations`.

All 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. LinkedIn `externalIds` are passed through as plaintext per LinkedIn's spec;
only emails and phones are hashed.

For LinkedIn, the connected account must have been authorized after the Conversions API
rollout (i.e. the OAuth grant must include `rw_conversions`). Older accounts must reconnect.

Batching is handled automatically. Meta caps at 1000 events per request and rejects the
entire batch if any event is malformed. Google caps at 2000. LinkedIn caps at 5000 and is
also all-or-nothing per chunk.

Dedup: pass a stable `eventId` on every event. Meta and LinkedIn use it to dedupe against
browser-side pixel/Insight Tag events; Google maps it to `transactionId`.

Per-platform `eventName` semantics:

- Meta: free-form. Standard names (Purchase, Lead, ...) match Meta's built-in events; custom strings are accepted.
- 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.
- 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.


### Request Body

- **accountId** (required) `string`: SocialAccount ID (metaads, googleads, or linkedinads).
- **destinationId** (required) `string`: Platform destination identifier. For Meta, the pixel/dataset
ID. For Google, the conversion action resource name. For
LinkedIn, the conversion rule ID or full
`urn:lla:llaPartnerConversion:{id}` URN.

- **events** (required) `array`: No description
- **testCode** `string`: Meta `test_event_code` passthrough. Ignored by Google and LinkedIn.
- **consent** `object`: Batch-level user consent. Required by Google for EEA/UK
events under the Feb 2026 restrictions. Ignored by Meta
and LinkedIn.


### Responses

#### 200: Events processed. Inspect `eventsFailed` and `failures[]` to detect
partial failure. For Meta, a batch is all-or-nothing (either every
event in a chunk succeeds, or every event in the chunk is listed
in failures). For Google, the API returns success/failure at the
request level only.


**Response Body:**

- **platform** `string`: No description - one of: metaads, googleads, linkedinads
- **eventsReceived** `integer`: Events accepted by the platform.
- **eventsFailed** `integer`: Events rejected (see failures).
- **failures** `array[object]`: 
  - **eventIndex** `integer`: Index into the submitted events array.
  - **eventId** `string`: Echoes back the eventId of the failed event.
  - **message** `string`: No description
  - **code**: One of multiple types
- **traceId** `string`: Platform trace ID for debugging. fbtrace_id for Meta,
requestId for Google. Absent for LinkedIn (LinkedIn's
conversionEvents endpoint does not surface a trace ID).


#### 400: Invalid body (missing accountId/destinationId/events, malformed event shape).

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans),
OR (for LinkedIn) the connected account lacks the `rw_conversions` scope and must be reconnected.


#### 404: Account not found or not accessible.

#### 429: LinkedIn token-level rate limit hit (600 requests/min, 300k/day
per token). Retry with backoff. Meta and Google have their own
rate-limit semantics surfaced via platform-specific 4xx responses.


---

---

# Send WhatsApp conversion event API Reference

Forward a WhatsApp Business Messaging conversion event (`LeadSubmitted`,
`Purchase`, `AddToCart`, `InitiateCheckout`, `ViewContent`) to Meta's
Conversions API with `action_source = business_messaging` and
`messaging_channel = whatsapp`. The endpoint looks up the originating
CTWA click ID (`ctwa_clid`) captured on the first inbound message of
the conversation and replays it on every event so Meta can attribute
the conversion back to the Click-to-WhatsApp ad that drove the chat.

Configuration prerequisite on the WhatsApp account metadata:
  - `metaCapiDatasetId`: the Meta dataset ID linked to the WABA.
    Provision one with `POST /v1/whatsapp/dataset`.

The WABA ID (already set automatically at connect time) is forwarded as
`user_data.whatsapp_business_account_id`, which is the per-channel
attribution identifier Meta requires for WhatsApp events. No Facebook
Page ID is needed (that field is the Messenger-branch identifier).

Identify the conversation by either `conversationId` (preferred) or
`phoneE164` (digits only, no `+`). At least one is required. If the
conversation has no captured `ctwa_clid`, the request returns 422
because there is nothing to attribute.

Token and dataset coupling: the 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. Either share the dataset with the WhatsApp
app's Business in BM, or use a dataset already in the same Business
as the WABA.


## GET /v1/whatsapp/conversions

**List recent WhatsApp conversion events**

Returns the most recent conversion events sent through
`POST /v1/whatsapp/conversions` for the given WhatsApp account.
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.

Per-event payload mirrors the structured log we write on every
successful send: `eventName`, `conversationId`, `eventsReceived`,
`eventsFailed`, `traceId`, `durationMs`, and the wall-clock
`timestamp`.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID
- **limit** (optional) in query: Max events to return (1-200, default 50).

### Responses

#### 200: Recent conversion events

**Response Body:**

- **events** `array[object]`: 
  - **timestamp** `string` (date-time): When the event was sent to Meta.
  - **eventName** `string`: One of LeadSubmitted, Purchase, AddToCart, InitiateCheckout, ViewContent.
  - **conversationId** `string`: No description
  - **eventsReceived** `integer`: Number of events Meta accepted on this send (usually 1).
  - **eventsFailed** `integer`: Number of events Meta rejected (usually 0).
  - **traceId** `string`: Meta fbtrace_id for cross-referencing in Events Manager.
  - **durationMs** `integer`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/conversions

**Send WhatsApp conversion event**

Forward a WhatsApp Business Messaging conversion event (`LeadSubmitted`,
`Purchase`, `AddToCart`, `InitiateCheckout`, `ViewContent`) to Meta's
Conversions API with `action_source = business_messaging` and
`messaging_channel = whatsapp`. The endpoint looks up the originating
CTWA click ID (`ctwa_clid`) captured on the first inbound message of
the conversation and replays it on every event so Meta can attribute
the conversion back to the Click-to-WhatsApp ad that drove the chat.

Configuration prerequisite on the WhatsApp account metadata:
  - `metaCapiDatasetId`: the Meta dataset ID linked to the WABA.
    Provision one with `POST /v1/whatsapp/dataset`.

The WABA ID (already set automatically at connect time) is forwarded as
`user_data.whatsapp_business_account_id`, which is the per-channel
attribution identifier Meta requires for WhatsApp events. No Facebook
Page ID is needed (that field is the Messenger-branch identifier).

Identify the conversation by either `conversationId` (preferred) or
`phoneE164` (digits only, no `+`). At least one is required. If the
conversation has no captured `ctwa_clid`, the request returns 422
because there is nothing to attribute.

Token and dataset coupling: the 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. Either share the dataset with the WhatsApp
app's Business in BM, or use a dataset already in the same Business
as the WABA.


### Request Body

- **accountId** (required) `string`: WhatsApp SocialAccount ID.
- **eventName** (required) `string`: Live-verified allowlist of event names accepted by Meta's
CAPI for Business Messaging (Graph API v25.0). Other
standard pixel events including `Lead`,
`CompleteRegistration`, `Subscribe`, `Schedule`, `Contact`,
`StartTrial`, `AddPaymentInfo`, `Search`, and
`SubmitApplication` are rejected with subcode 2804066
("Messaging Event Invalid Event Type") on
`action_source = business_messaging` events. Custom event
names are also rejected.

Use `LeadSubmitted` (NOT `Lead`) for lead-style conversions.
 - one of: LeadSubmitted, Purchase, AddToCart, InitiateCheckout, ViewContent
- **eventTime** `number`: Unix seconds. Defaults to the time of the request when
omitted. Meta's attribution window is 7 days from click;
events older than that lose attribution.

- **eventId** (required) `string`: Stable dedup key. Reuse to suppress duplicate events
(Meta dedupes against pixel events with the same id).

- **conversationId** `string`: Zernio Conversation `_id` (preferred lookup). The
conversation must have a captured `ctwa_clid` in metadata
(set automatically by the WhatsApp webhook on the first
inbound message after a CTWA ad click).

- **phoneE164** `string`: Contact phone number, digits only with no '+'. When used
in lieu of `conversationId`, the handler resolves to the
most recent CTWA-attributed conversation for this phone
on the supplied account.

- **value** `number`: Conversion value (e.g. order total).
- **currency** `string`: ISO 4217 currency code (e.g. `USD`).
- **contentIds** `array`: Optional product / content identifiers.
- **email** `string`: User email. Normalized + SHA-256 hashed before sending to Meta.
- **externalId** `string`: Stable customer identifier. Lowercased + SHA-256 hashed
before sending to Meta.

- **testCode** `string`: Meta `test_event_code` passthrough. Routes the event to
the Test Events tab in Events Manager instead of the
production dataset, useful for development.


### Responses

#### 200: Event submitted to Meta. Inspect `eventsFailed` and `failures[]`
to detect partial failures. A 200 does not mean Meta accepted the
event; the status reflects "request reached Meta" only.


**Response Body:**

- **platform** `string`: No description - one of: metaads
- **eventsReceived** `integer`: Events accepted by Meta.
- **eventsFailed** `integer`: Events rejected by Meta (see failures).
- **failures** `array[object]`: Per-event failure detail. Empty when all events were
accepted.

  - **eventIndex** `integer`: Index into the submitted events array.
  - **eventId** `string`: Echoes back the eventId of the failed event.
  - **message** `string`: No description
  - **code**: One of multiple types
- **traceId** `string`: Meta `fbtrace_id` for debugging. Surface in support
tickets.


#### 400: Invalid body.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Conversation not found.

#### 422: Configuration missing (no `metaCapiDatasetId` on the account, set
it via POST /v1/whatsapp/dataset) OR the resolved conversation has
no captured `ctwa_clid`.


---

---

# Set/update an ad's click-URL tracking tags API Reference

Unified update. Send only the fields for the ad's platform:
- Meta: `urlTags` (array of {key,value}). Meta creatives are immutable, so this rebuilds the
  creative and repoints the ad. By 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 — no need to read back headline/body/CTA. `creative` (headline, body, callToAction,
  linkUrl, imageUrl) is OPTIONAL and 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`).
- Google: `trackingUrlTemplate` and/or `finalUrlSuffix` (full template strings; account quota applies).
- LinkedIn: `dynamicValueParameters` and/or `customValueParameters` (campaign-level Dynamic UTM).


## GET /v1/ads/{adId}/tracking-tags

**Read an ad's click-URL tracking tags**

Unified read of the platform's native click-URL tracking params.
- Meta (facebook/instagram): the creative's `url_tags` (and template_url_spec).
- Google (googleads): the campaign's `trackingUrlTemplate` + `finalUrlSuffix`.
  Subject to the Google Ads API access-tier daily quota; bulk audits need Standard access.
- LinkedIn (linkedinads): the campaign's Dynamic UTM `dynamicValueParameters` + `customValueParameters`.
Returns 405 for platforms without a click-URL tracking surface (TikTok, X, Pinterest).


### Parameters

- **adId** (required) in path: Ad id (hex _id, platformAdId, or effective story/media id).

### Responses

#### 200: Tracking tags for the ad's platform (shape varies by platform).

**Response Body:**

- **platform** `string`: No description
- **level** `string`: No description - one of: creative, campaign
- **urlTags** `string`: Meta: &-joined click-URL params.
- **templateUrlSpec** `object`: Meta: third-party click-tracking template (Dynamic Ads).
- **trackingUrlTemplate** `string`: Google.
- **finalUrlSuffix** `string`: Google.
- **dynamicValueParameters** `object`: LinkedIn.
- **customValueParameters** `object`: LinkedIn.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Ad not found

#### 405: Platform has no click-URL tracking surface

---

## PATCH /v1/ads/{adId}/tracking-tags

**Set/update an ad's click-URL tracking tags**

Unified update. Send only the fields for the ad's platform:
- Meta: `urlTags` (array of {key,value}). Meta creatives are immutable, so this rebuilds the
  creative and repoints the ad. By 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 — no need to read back headline/body/CTA. `creative` (headline, body, callToAction,
  linkUrl, imageUrl) is OPTIONAL and 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`).
- Google: `trackingUrlTemplate` and/or `finalUrlSuffix` (full template strings; account quota applies).
- LinkedIn: `dynamicValueParameters` and/or `customValueParameters` (campaign-level Dynamic UTM).


### Parameters

- **adId** (required) in path: No description

### Request Body

- **urlTags** `array`: Meta only. Click-URL params appended to a freshly-rebuilt creative.
- **creative** `object`: 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.
- **trackingUrlTemplate** `string`: Google only. Full tracking template (must contain {lpurl}).
- **finalUrlSuffix** `string`: Google only. Parse-only key=value params.
- **dynamicValueParameters** `object`: LinkedIn only. key -> dynamic value enum (CAMPAIGN_ID, CAMPAIGN_NAME, CREATIVE_ID, ...).
- **customValueParameters** `object`: LinkedIn only. key -> static value.

### Responses

#### 200: Updated

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Ad not found

#### 405: Platform has no click-URL tracking surface

#### 422: Meta creative cannot be rebuilt (e.g. placement-customized/asset-feed/dark creative)

---

---

# Update ad API Reference

Patch one or more fields on an ad. Status, budget, targeting, and creative changes
are propagated to the platform.

Per-platform support:
- **Meta** (Facebook + Instagram): all fields supported.
- **TikTok**: status, budget, targeting (via `/v2/adgroup/update/`), and creative
  (via `/v2/ad/update/` patch-style — `headline` is ignored, `body` becomes `ad_text`).
- **Pinterest / X / LinkedIn / Google**: status + budget only. Sending `targeting`
  or `creative` returns 501 with code `unsupported_platform_operation`.


## GET /v1/ads/{adId}

**Get ad details**

Returns an ad with its creative, targeting, status, and performance metrics.

The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad:
- the Zernio internal `_id` (24-char hex)
- Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`)
- the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side)
- the creative's `effective_instagram_media_id` (Instagram side)

Any of the four resolve to the same ad. Caller doesn't need a translation step.


### Parameters

- **adId** (required) in path: Zernio `_id` (hex), Meta `platformAdId` (numeric), or one of the creative's effective story/media IDs. See description for details.


### Responses

#### 200: Ad details

**Response Body:**

- **ad**: `Ad` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PUT /v1/ads/{adId}

**Update ad**

Patch one or more fields on an ad. Status, budget, targeting, and creative changes
are propagated to the platform.

Per-platform support:
- **Meta** (Facebook + Instagram): all fields supported.
- **TikTok**: status, budget, targeting (via `/v2/adgroup/update/`), and creative
  (via `/v2/ad/update/` patch-style — `headline` is ignored, `body` becomes `ad_text`).
- **Pinterest / X / LinkedIn / Google**: status + budget only. Sending `targeting`
  or `creative` returns 501 with code `unsupported_platform_operation`.


### Parameters

- **adId** (required) in path: No description

### Request Body

- **status** `string`: No description - one of: active, paused
- **budget** `object`: No description
- **targeting** `object`: Meta + TikTok only. Pinterest / X / LinkedIn / Google return 501.

- **creative** `object`: Replace the ad's creative. Meta + TikTok only.

- **Meta**: requires `headline`, `body`, `callToAction`, `linkUrl`, `imageUrl`. The
  ad's existing creative is replaced via a new `/act_X/adcreatives` upload + ad
  update. The old creative is retained on the ad account for historical reporting.
- **TikTok**: patch-style. Pass any subset; `headline` is ignored (TikTok creatives
  have no headline slot). `body` becomes the in-feed `ad_text`; `linkUrl` becomes
  `landing_page_url`; `videoUrl` triggers a fresh upload.

- **name** `string`: Rename the ad. Now propagated to Meta (POST /{ad-id}); non-Meta platforms return 501.

### Responses

#### 200: Ad updated

**Response Body:**

- **ad**: `Ad` - See schema definition
- **message** `string`: No description

#### 400: Invalid status transition or budget below minimum

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 501: targeting or creative not supported on the platform (Meta + TikTok only)

---

## DELETE /v1/ads/{adId}

**Cancel an ad**

Cancels the ad on the platform and marks it as cancelled in the database. The ad is preserved for history.

### Parameters

- **adId** (required) in path: No description

### Responses

#### 200: Ad cancelled

**Response Body:**

- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## Ad

### Properties

- **_id** `string`: No description
- **name** `string`: No description
- **platform** `string`: No description - one of: facebook, instagram, tiktok, linkedin, pinterest, google, twitter
- **status**: No description
- **adType** `string`: No description - one of: boost, standalone
- **goal** `string`: Available goals vary by platform. Meta (Facebook/Instagram) supports all 9 (incl. `lead_conversion` = website pixel lead optimization and `catalog_sales` = Advantage+ catalog ads). TikTok supports the 7 non-`lead_conversion` goals. LinkedIn supports all except app_promotion / lead_conversion. Twitter/X supports engagement, traffic, awareness, video_views, app_promotion. Pinterest and Google Ads support only engagement, traffic, awareness, video_views. - one of: engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales
- **isExternal** `boolean`: True for ads synced from platform ad managers
- **budget** `object`: 
  - **amount** `number`: 
  - **type** `string`:  - one of: daily, lifetime
- **metrics**: No description
- **platformAdId** `string`: No description
- **platformAdAccountId** `string`: No description
- **platformCampaignId** `string`: No description
- **platformAdSetId** `string`: No description
- **campaignName** `string`: No description
- **adSetName** `string`: No description
- **platformObjective** `string`: Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC). Only present for Meta ads.
- **optimizationGoal** `string`: Meta ad set optimization goal (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION, LINK_CLICKS). Only present for Meta ads.
- **platformAdAccountName** `string`: Human-readable advertiser/account name (Meta `AdAccount.name`, TikTok
`advertiser_name`, LinkedIn / X / Pinterest equivalents). Refreshed every
sync so platform-side renames propagate within one cycle. `null` when the
platform doesn't return a name or the sync hasn't run yet.

- **platformCreatedAt** `string`: Platform-reported creation timestamp (Meta `created_time`, TikTok `create_time`).
Distinct from `createdAt` which reflects when Zernio first synced the doc — for
sort/filter by "when the ad was actually created on the platform", read this field.
`null` for legacy ads synced before this field was added; aggregations fall back
to `createdAt` in that case.

- **bidStrategy**: Ad-set bid strategy (overrides campaign level on Meta). Populated for Meta and
TikTok. TikTok's native `bid_type` is normalized to the cross-platform Meta enum:
`BID_TYPE_NO_BID` -> `LOWEST_COST_WITHOUT_CAP`, `BID_TYPE_CUSTOM` ->
`LOWEST_COST_WITH_BID_CAP`, deep_bid_type=MIN_ROAS or roas_bid>0 ->
`LOWEST_COST_WITH_MIN_ROAS`, `BID_TYPE_MAX_CONVERSION` -> `LOWEST_COST_WITHOUT_CAP`.

- **bidAmount** `number`: Bid cap in WHOLE currency units of the ad account (USD: 5 = $5.00; JPY: 100 = ¥100).
Populated when bidStrategy is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`. `null` for
auto-bid (`LOWEST_COST_WITHOUT_CAP`).

- Meta source: `bid_amount` on the ad set (smallest-denomination int, decoded here).
- TikTok source: priority order `bid_price` -> `conversion_bid_price` -> `deep_cpa_bid`
  (whichever is set on the ad group). TikTok stores all three in whole currency units.

Source: facebook-business-sdk-codegen api_specs/specs/AdSet.json (`bid_amount`).

- **roasAverageFloor** `number`: Minimum ROAS as a decimal multiplier (2.0 = 2.0x ROAS). Populated when bidStrategy
is `LOWEST_COST_WITH_MIN_ROAS`.

- Meta source: decoded from `bid_constraints.roas_average_floor` (Meta stores as
  fixed-point int × 10000; we return the decimal).
- TikTok source: `roas_bid` on the ad group (already a decimal).

Source: facebook-business-sdk-codegen api_specs/specs/AdCampaignBidConstraint.json.

- **promotedObject** `object`: Meta promoted object containing conversion event details. Structure varies by objective. Only present for Meta ads.
  - **custom_event_type** `string`: Conversion event type (e.g. PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART)
  - **pixel_id** `string`: Meta pixel ID
  - **page_id** `string`: Facebook page ID
  - **application_id** `string`: Facebook app ID
  - **product_set_id** `string`: Product catalog set ID
- **creative** `object`: Platform-specific creative data. Fields vary by platform.
  - **thumbnailUrl** `string`: Primary thumbnail/image URL
  - **imageUrl** `string`: Alternative image URL
  - **videoId** `string`: Meta video ID for VIDEO-type ads. Null for non-video ads. Callers that need an embeddable MP4 can call GET /{videoId}?fields=source with the page access token.
  - **videoUrl** `string`: Public Facebook watch URL for VIDEO-type ads (https://www.facebook.com/watch/?v={videoId}). Null for non-video ads.
  - **objectType** `string`: 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** `string`: Meta creative `object_story_id` (the SHARE reference). Frequently absent — Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead.
  - **effectiveObjectStoryId** `string`: Meta `effective_object_story_id` — `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. Pass to GET /v1/ads?effectiveObjectStoryId= to map a Business-Manager-visible post back to this ad; GET /v1/ads/{adId}/comments resolves comments against it.
  - **effectiveInstagramMediaId** `string`: 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** `string`: Meta `instagram_user_id` — the Instagram-scoped business ID that owns the boosted media.
  - **instagramPermalinkUrl** `string`: Meta `instagram_permalink_url` — public Instagram post URL of the boosted media.
  - **mediaUrls** `array`: 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).
  - **body** `string`: Ad copy/text
  - **googleHeadline** `string`: Google Ads headline
  - **googleDescription** `string`: Google Ads description
  - **linkUrl** `string`: Destination URL
  - **pinterestImageUrl** `string`: 
  - **pinterestTitle** `string`: 
  - **pinterestDescription** `string`: 
- **targeting** `object`: The ad set's targeting (age, gender, geo, interests, placements, audience inclusions/exclusions).
For ads created through Zernio this is the spec you supplied. For external ads (synced from
Meta Ads Manager, `isExternal: true`) targeting lives at the ad set and isn't stored at ingest,
so on the first `GET /v1/ads/{adId}` Zernio resolves it live from Meta and caches it on the ad;
the value is then Meta's raw `targeting` shape (snake_case, e.g. `geo_locations`, `age_min`),
the same object Ads Manager shows. May be absent if the ad set exposes no targeting or the lookup fails.

- **schedule** `object`: 
  - **startDate** `string`: 
  - **endDate** `string`: 
- **rejectionReason** `string`: No description
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

---

# Update a conversion destination API Reference

Partial-update a conversion rule. LinkedIn-only today. Whitelisted
fields: `name`, `enabled`, attribution windows, `valueType`, `value`,
`attributionType`. The rule's `type` and parent ad account are
intentionally not exposed for update — recreate the rule if those
need to change.


## GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}

**Fetch a single conversion destination**

LinkedIn-only today. Returns the full destination record for one
conversion rule. The `adAccountId` query parameter is required because
LinkedIn rules are scoped to a sponsored ad account.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (required) in query: Numeric ID or full `urn:li:sponsoredAccount:{id}` URN.

### Responses

#### 200: Destination fetched

**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **destination**: `ConversionDestination` - See schema definition

#### 400: Validation error.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support fetching a single destination.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## PATCH /v1/accounts/{accountId}/conversion-destinations/{destinationId}

**Update a conversion destination**

Partial-update a conversion rule. LinkedIn-only today. Whitelisted
fields: `name`, `enabled`, attribution windows, `valueType`, `value`,
`attributionType`. The rule's `type` and parent ad account are
intentionally not exposed for update — recreate the rule if those
need to change.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description

### Request Body

- **adAccountId** (required) `string`: No description
- **name** `string`: No description
- **enabled** `boolean`: Setting `false` is equivalent to calling DELETE — the
rule will appear as `inactive` afterwards.

- **attributionType** `string`: No description - one of: LAST_TOUCH_BY_CAMPAIGN, LAST_TOUCH_BY_CONVERSION
- **postClickAttributionWindowSize** `integer`: 365 only allowed for LEAD, PURCHASE, ADD_TO_CART,
QUALIFIED_LEAD, SUBMIT_APPLICATION rule types.
 - one of: 1, 7, 30, 90, 365
- **viewThroughAttributionWindowSize** `integer`: 365 only allowed for LEAD, PURCHASE, ADD_TO_CART,
QUALIFIED_LEAD, SUBMIT_APPLICATION rule types.
 - one of: 1, 7, 30, 90, 365
- **valueType** `string`: No description - one of: DYNAMIC, FIXED, NO_VALUE
- **value** `object`: Used when `valueType=FIXED`.

### Responses

#### 200: Destination updated (re-fetched canonical state)

**Response Body:**

- **platform** `string`: No description - one of: linkedinads
- **destination**: `ConversionDestination` - See schema definition

#### 400: Invalid body or LinkedIn validation failure.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support updating destinations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---

## DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}

**Soft-delete a conversion destination**

LinkedIn-only today. LinkedIn does not expose hard-delete on conversion
rules — what their UI calls "delete" is the same `enabled: false` flip
we apply here. The rule remains fetchable via GET with
`status: 'inactive'`; the unified discovery endpoint hides it by
default.

`adAccountId` may be passed as a query parameter (recommended) or as
a JSON body field for clients that can send DELETE bodies.


### Parameters

- **accountId** (required) in path: No description
- **destinationId** (required) in path: No description
- **adAccountId** (optional) in query: Required as query OR in JSON body.

### Responses

#### 204: Soft-deleted.

#### 400: adAccountId missing.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads add-on or LinkedIn reconnect required.

#### 404: Account or destination not found.

#### 405: Platform does not support deleting destinations.

#### 429: LinkedIn rate limit hit. Retry with backoff.

---


# Related Schema Definitions

## ConversionDestination

A discoverable conversion destination on an ad platform — a Meta pixel,
Google conversion action, or LinkedIn conversion rule. Returned by
`listConversionDestinations`, `getConversionDestination`,
`createConversionDestination`, and `updateConversionDestination`.


### Properties

- **id** (required) `string`: Platform-native identifier. Pass back as `destinationId` on event
send and as the path segment on CRUD endpoints.

- **name** (required) `string`: No description
- **type** `string`: Present when the platform locks the event type/category to the
destination (Google conversion actions, LinkedIn conversion rules).
Absent for Meta pixels (which accept any event name per request).

- **status** `string`: For LinkedIn, `inactive` means the rule is soft-deleted (`enabled: false`).
 - one of: active, inactive
- **adAccountId** `string`: Set by adapters whose destinations are scoped to a specific ad
account (LinkedIn). Pass back on subsequent CRUD calls to
identify the parent ad account.

---

# Get post analytics API Reference

Returns analytics for posts. With postId, returns a single post. Without it, returns a paginated list with overview stats.
Accepts both Zernio Post IDs and External Post IDs (auto-resolved). fromDate defaults to 90 days ago if omitted, max range 366 days.
Single post lookups may return 202 (sync pending) or 424 (all platforms failed). For follower stats, use /v1/accounts/follower-stats.

LinkedIn personal accounts: Analytics 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.


## GET /v1/analytics

**Get post analytics**

Returns analytics for posts. With postId, returns a single post. Without it, returns a paginated list with overview stats.
Accepts both Zernio Post IDs and External Post IDs (auto-resolved). fromDate defaults to 90 days ago if omitted, max range 366 days.
Single post lookups may return 202 (sync pending) or 424 (all platforms failed). For follower stats, use /v1/accounts/follower-stats.

LinkedIn personal accounts: Analytics 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.


### Parameters

- **postId** (optional) in query: Returns analytics for a single post. Accepts both Zernio Post IDs and External Post IDs. Zernio IDs are auto-resolved to External Post analytics.
- **platform** (optional) in query: Filter by platform (default "all")
- **profileId** (optional) in query: Filter by profile ID (default "all")
- **accountId** (optional) in query: Filter by social account ID
- **source** (optional) in query: Filter by post source: late (posted via Zernio API), external (synced from platform), all (default)
- **fromDate** (optional) in query: Inclusive lower bound (YYYY-MM-DD). Defaults to 90 days ago if omitted. Max range is 366 days.
- **toDate** (optional) in query: Inclusive upper bound (YYYY-MM-DD). Defaults to today if omitted.
- **limit** (optional) in query: Page size (default 50)
- **page** (optional) in query: Page number (default 1)
- **sortBy** (optional) in query: Sort by date, engagement, or a specific metric
- **order** (optional) in query: Sort order

### Responses

#### 200: Analytics result

**Response Body:**

*One of the following:*
- `AnalyticsSinglePostResponse`
- `AnalyticsListResponse`

#### 202: Analytics are being synced from the platform (single post lookup only). The response body matches AnalyticsSinglePostResponse with syncStatus "pending" and a message.

**Response Body:**

- **postId** `string`: No description
- **latePostId** `string`: Original Zernio post ID if scheduled via Zernio
- **status** `string`: Overall post status. "partial" when some platforms published and others failed. - one of: published, failed, partial
- **content** `string`: No description
- **scheduledFor** `string` (date-time): No description
- **publishedAt** `string` (date-time): No description
- **analytics**: `PostAnalytics` - See schema definition
- **platformAnalytics** `array[PlatformAnalytics]`: 
- **platform** `string`: No description
- **platformPostUrl** `string` (uri): No description
- **isExternal** `boolean`: No description
- **syncStatus** `string`: Overall sync state across all platforms - one of: synced, pending, partial, unavailable
- **message** `string`: Human-readable status message for pending, partial, or failed states
- **thumbnailUrl** `string` (uri): No description
- **mediaType** `string`: No description - one of: image, video, carousel, text
- **mediaItems** `array[object]`: All media items for this post. Carousel posts contain one entry per slide.
  - **type** `string`: No description - one of: image, video
  - **url** `string` (uri): Direct URL to the media
  - **thumbnail** `string` (uri): Thumbnail URL (same as url for images)

#### 400: Validation error

**Response Body:**

- **error** `string`: No description (example: "Invalid query parameters")
- **details** `object`: Detailed validation errors

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **code** `string`: No description (example: "analytics_addon_required")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 424: Post failed to publish on all platforms. Analytics are unavailable. (single post lookup only)

**Response Body:**

- **postId** `string`: No description
- **latePostId** `string`: Original Zernio post ID if scheduled via Zernio
- **status** `string`: Overall post status. "partial" when some platforms published and others failed. - one of: published, failed, partial
- **content** `string`: No description
- **scheduledFor** `string` (date-time): No description
- **publishedAt** `string` (date-time): No description
- **analytics**: `PostAnalytics` - See schema definition
- **platformAnalytics** `array[PlatformAnalytics]`: 
- **platform** `string`: No description
- **platformPostUrl** `string` (uri): No description
- **isExternal** `boolean`: No description
- **syncStatus** `string`: Overall sync state across all platforms - one of: synced, pending, partial, unavailable
- **message** `string`: Human-readable status message for pending, partial, or failed states
- **thumbnailUrl** `string` (uri): No description
- **mediaType** `string`: No description - one of: image, video, carousel, text
- **mediaItems** `array[object]`: All media items for this post. Carousel posts contain one entry per slide.
  - **type** `string`: No description - one of: image, video
  - **url** `string` (uri): Direct URL to the media
  - **thumbnail** `string` (uri): Thumbnail URL (same as url for images)

#### 500: Internal server error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## AnalyticsSinglePostResponse

### Properties

- **postId** `string`: No description
- **latePostId** `string`: Original Zernio post ID if scheduled via Zernio
- **status** `string`: Overall post status. "partial" when some platforms published and others failed. - one of: published, failed, partial
- **content** `string`: No description
- **scheduledFor** `string`: No description
- **publishedAt** `string`: No description
- **analytics**: No description
- **platformAnalytics** `array`: No description
- **platform** `string`: No description
- **platformPostUrl** `string`: No description
- **isExternal** `boolean`: No description
- **syncStatus** `string`: Overall sync state across all platforms - one of: synced, pending, partial, unavailable
- **message** `string`: Human-readable status message for pending, partial, or failed states
- **thumbnailUrl** `string`: No description
- **mediaType** `string`: No description - one of: image, video, carousel, text
- **mediaItems** `array`: All media items for this post. Carousel posts contain one entry per slide.

## AnalyticsListResponse

### Properties

- **overview**: No description
- **posts** `array`: No description
- **pagination**: No description
- **accounts** `array`: Connected social accounts (followerCount and followersLastUpdated only included if user has analytics add-on)
- **hasAnalyticsAccess** `boolean`: Whether user has analytics add-on access

## PostAnalytics

### Properties

- **impressions** `integer`: No description
- **reach** `integer`: No description
- **likes** `integer`: No description
- **comments** `integer`: No description
- **shares** `integer`: No description
- **saves** `integer`: Number of saves/bookmarks (Instagram, Pinterest)
- **clicks** `integer`: No description
- **views** `integer`: No description
- **igReelsAvgWatchTime** `integer`: Instagram Reels only: average watch time per play, in milliseconds. 0 for non-Reels media and other platforms.
- **igReelsVideoViewTotalTime** `integer`: Instagram Reels only: total watch time including replays, in milliseconds. 0 for non-Reels media and other platforms.
- **engagementRate** `number`: No description
- **lastUpdated** `string`: No description

## PlatformAnalytics

### Properties

- **platform** `string`: No description
- **status** `string`: No description - one of: published, failed
- **platformPostId** `string`: The native post ID on the platform (e.g. Instagram media ID, tweet ID)
- **accountId** `string`: No description
- **accountUsername** `string`: No description
- **analytics**: No description
- **syncStatus** `string`: Sync state of analytics for this platform - one of: synced, pending, unavailable
- **platformPostUrl** `string`: No description
- **errorMessage** `string`: Error details when status is failed

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get best times to post API Reference

Returns the best times to post based on historical engagement data.
Groups all published posts by day of week and hour (UTC), calculating average engagement per slot.
Use this to auto-schedule posts at optimal times. Requires the Analytics add-on.


## GET /v1/analytics/best-time

**Get best times to post**

Returns the best times to post based on historical engagement data.
Groups all published posts by day of week and hour (UTC), calculating average engagement per slot.
Use this to auto-schedule posts at optimal times. Requires the Analytics add-on.


### Parameters

- **platform** (optional) in query: Filter by platform (e.g. "instagram", "tiktok"). Omit for all platforms.
- **profileId** (optional) in query: Filter by profile ID. Omit for all profiles.
- **accountId** (optional) in query: Filter by social account ID. Omit for all accounts.
- **source** (optional) in query: Filter by post origin. "late" for posts published via Zernio, "external" for posts imported from platforms.

### Responses

#### 200: Best time slots

**Response Body:**

- **slots** `array[object]`: 
  - **day_of_week** `integer`: 0=Monday, 6=Sunday
  - **hour** `integer`: Hour in UTC (0-23)
  - **avg_engagement** `number`: Average engagement (likes + comments + shares + saves)
  - **post_count** `integer`: Number of posts in this slot

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **requiresAddon** `boolean`: No description (example: true)

---

---

# Get content performance decay API Reference

Returns how engagement accumulates over time after a post is published.
Each bucket shows what percentage of the post's total engagement had been reached by that time window.
Useful for understanding content lifespan (e.g. "posts reach 78% of total engagement within 24 hours").
Requires the Analytics add-on.


## GET /v1/analytics/content-decay

**Get content performance decay**

Returns how engagement accumulates over time after a post is published.
Each bucket shows what percentage of the post's total engagement had been reached by that time window.
Useful for understanding content lifespan (e.g. "posts reach 78% of total engagement within 24 hours").
Requires the Analytics add-on.


### Parameters

- **platform** (optional) in query: Filter by platform (e.g. "instagram", "tiktok"). Omit for all platforms.
- **profileId** (optional) in query: Filter by profile ID. Omit for all profiles.
- **accountId** (optional) in query: Filter by social account ID. Omit for all accounts.
- **source** (optional) in query: Filter by post origin. "late" for posts published via Zernio, "external" for posts imported from platforms.

### Responses

#### 200: Content decay buckets

**Response Body:**

- **buckets** `array[object]`: 
  - **bucket_order** `integer`: Sort order (0 = earliest, 6 = latest)
  - **bucket_label** `string`: Human-readable label
  - **avg_pct_of_final** `number`: Average % of final engagement reached (0-100)
  - **post_count** `integer`: Number of posts with data in this bucket

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **requiresAddon** `boolean`: No description (example: true)

---

---

# Get daily aggregated metrics API Reference

Returns daily aggregated analytics metrics and a per-platform breakdown.
Each day includes post count, platform distribution, and summed metrics (impressions, reach, likes, comments, shares, saves, clicks, views).
Defaults to the last 180 days. Requires the Analytics add-on.


## GET /v1/analytics/daily-metrics

**Get daily aggregated metrics**

Returns daily aggregated analytics metrics and a per-platform breakdown.
Each day includes post count, platform distribution, and summed metrics (impressions, reach, likes, comments, shares, saves, clicks, views).
Defaults to the last 180 days. Requires the Analytics add-on.


### Parameters

- **platform** (optional) in query: Filter by platform (e.g. "instagram", "tiktok"). Omit for all platforms.
- **profileId** (optional) in query: Filter by profile ID. Omit for all profiles.
- **accountId** (optional) in query: Filter by social account ID
- **fromDate** (optional) in query: Inclusive start date (ISO 8601). Defaults to 180 days ago.
- **toDate** (optional) in query: Inclusive end date (ISO 8601). Defaults to now.
- **source** (optional) in query: Filter by post origin. "late" for posts published via Zernio, "external" for posts imported from platforms.
- **attribution** (optional) in query: How each post's engagement is attributed to a day.
"publish" (default) sums each post's lifetime total on its publish date.
"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.


### Responses

#### 200: Daily metrics and platform breakdown

**Response Body:**

- **dailyData** `array[object]`: 
  - **date** `string`: No description (example: "2025-12-01")
  - **postCount** `integer`: No description (example: 3)
  - **platforms** `object`: No description (example: {"instagram":2,"twitter":1})
  - **metrics** `object`: 
    - **impressions** `integer`: No description
    - **reach** `integer`: No description
    - **likes** `integer`: No description
    - **comments** `integer`: No description
    - **shares** `integer`: No description
    - **saves** `integer`: No description
    - **clicks** `integer`: No description
    - **views** `integer`: No description
- **platformBreakdown** `array[object]`: 
  - **platform** `string`: No description (example: "instagram")
  - **postCount** `integer`: No description (example: 142)
  - **impressions** `integer`: No description
  - **reach** `integer`: No description
  - **likes** `integer`: No description
  - **comments** `integer`: No description
  - **shares** `integer`: No description
  - **saves** `integer`: No description
  - **clicks** `integer`: No description
  - **views** `integer`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **code** `string`: No description (example: "analytics_addon_required")

---

---

# Get Facebook Page insights API Reference

Returns page-level Facebook insights (media views, views, post engagements, video metrics,
follower counts). Response shape matches /v1/analytics/instagram/account-insights so the
same client handling works across platforms.

Metric names track the current (post-November 2025) Meta Graph API. The legacy
page_impressions / page_fans / page_fan_adds / page_fan_removes metrics were deprecated
by Meta on November 15, 2025 and are NOT accepted by this endpoint. Use the replacements
below. Because Meta did not provide direct adds/removes replacements, Zernio synthesizes
followers_gained / followers_lost from the daily follower snapshotter.

Max 89 days, defaults to last 30 days. Requires the Analytics add-on.


## GET /v1/analytics/facebook/page-insights

**Get Facebook Page insights**

Returns page-level Facebook insights (media views, views, post engagements, video metrics,
follower counts). Response shape matches /v1/analytics/instagram/account-insights so the
same client handling works across platforms.

Metric names track the current (post-November 2025) Meta Graph API. The legacy
page_impressions / page_fans / page_fan_adds / page_fan_removes metrics were deprecated
by Meta on November 15, 2025 and are NOT accepted by this endpoint. Use the replacements
below. Because Meta did not provide direct adds/removes replacements, Zernio synthesizes
followers_gained / followers_lost from the daily follower snapshotter.

Max 89 days, defaults to last 30 days. Requires the Analytics add-on.


### Parameters

- **accountId** (required) in query: The Zernio SocialAccount ID for the connected Facebook Page.
- **metrics** (optional) in query: Comma-separated list of metrics. Defaults to
"page_media_view,page_post_engagements,page_follows,followers_gained,followers_lost".

Live Meta metrics (current names, post-Nov-2025):
  - page_media_view       (replaces deprecated page_impressions)
  - page_views_total
  - page_post_engagements
  - page_video_views
  - page_video_view_time
  - page_follows          (replaces deprecated page_fans)

Zernio-synthesized from daily follower snapshots (filling the Nov-2025 gap
left by the page_fan_adds / page_fan_removes deprecation):
  - followers_gained
  - followers_lost

- **since** (optional) in query: Start date (YYYY-MM-DD). Defaults to 30 days ago.
- **until** (optional) in query: End date (YYYY-MM-DD). Defaults to today.
- **metricType** (optional) in query: "total_value" (default) returns aggregated totals only.
"time_series" returns daily values in the "values" array.


### Responses

#### 200: Page insights data

**Response Body:**

- **success** `boolean`: No description (example: true)
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: Platform that served this response. - one of: facebook, instagram, youtube, linkedin, tiktok
- **dateRange** `object`: 
  - **since** `string` (date): No description
  - **until** `string` (date): No description
- **metricType** `string`: No description - one of: time_series, total_value
- **breakdown** `string`: Breakdown dimension used (only present when breakdown was requested)
- **metrics** `object`: Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).

- **dataDelay** `string`: No description (example: "Data may be delayed up to 48 hours")

#### 400: Bad request. Common cases:
  - Requested a deprecated metric (page_impressions, page_fans, page_fan_adds, page_fan_removes) - use current names instead
  - Account has no Page selected (metadata.pageAccessToken missing)
  - Invalid accountId / metrics / metricType / date range
  - Account is not a Facebook account


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

#### 404: Account not found

---


# Related Schema Definitions

## InstagramAccountInsightsResponse

Shared account-insights response envelope used by every platform-level
analytics endpoint (/v1/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).
The name is historical - the shape was first shipped for Instagram and every
new platform endpoint reuses it for response-shape consistency. The platform
field echoes back which platform served the response.


### Properties

- **success** `boolean`: No description
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: Platform that served this response. - one of: facebook, instagram, youtube, linkedin, tiktok
- **dateRange** `object`: 
  - **since** `string`: 
  - **until** `string`: 
- **metricType** `string`: No description - one of: time_series, total_value
- **breakdown** `string`: Breakdown dimension used (only present when breakdown was requested)
- **metrics** `object`: Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).

- **dataDelay** `string`: No description

---

# Get follower stats API Reference

Returns follower count history and growth metrics for connected social accounts.
Requires analytics add-on subscription. Follower counts are refreshed once per day.


## GET /v1/accounts/follower-stats

**Get follower stats**

Returns follower count history and growth metrics for connected social accounts.
Requires analytics add-on subscription. Follower counts are refreshed once per day.


### Parameters

- **accountIds** (optional) in query: Comma-separated list of account IDs (optional, defaults to all user's accounts)
- **profileId** (optional) in query: Filter by profile ID
- **fromDate** (optional) in query: Start date in YYYY-MM-DD format (defaults to 30 days ago)
- **toDate** (optional) in query: End date in YYYY-MM-DD format (defaults to today)
- **granularity** (optional) in query: Data aggregation level

### Responses

#### 200: Follower stats

**Response Body:**

- **accounts** `array[AccountWithFollowerStats]`: 
- **stats** `object`: No description
- **dateRange** `object`: 
  - **from** `string` (date-time): No description
  - **to** `string` (date-time): No description
- **granularity** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **message** `string`: No description (example: "Follower stats tracking requires the Analytics add-on. Please upgrade to access this feature.")
- **requiresAddon** `boolean`: No description (example: true)

---


# Related Schema Definitions

## AccountWithFollowerStats

---

# Get GBP performance metrics API Reference

Returns daily performance metrics for a Google Business Profile location.
Metrics include impressions (Maps/Search, desktop/mobile), website clicks,
call clicks, direction requests, conversations, bookings, and food orders.
Data may be delayed 2-3 days. Max 18 months of historical data.
Requires the Analytics add-on.


## GET /v1/analytics/googlebusiness/performance

**Get GBP performance metrics**

Returns daily performance metrics for a Google Business Profile location.
Metrics include impressions (Maps/Search, desktop/mobile), website clicks,
call clicks, direction requests, conversations, bookings, and food orders.
Data may be delayed 2-3 days. Max 18 months of historical data.
Requires the Analytics add-on.


### Parameters

- **accountId** (required) in query: The Zernio SocialAccount ID for the Google Business Profile account.
- **metrics** (optional) in query: Comma-separated metric names. Defaults to all available metrics.
Valid values: BUSINESS_IMPRESSIONS_DESKTOP_MAPS, BUSINESS_IMPRESSIONS_DESKTOP_SEARCH,
BUSINESS_IMPRESSIONS_MOBILE_MAPS, BUSINESS_IMPRESSIONS_MOBILE_SEARCH,
BUSINESS_CONVERSATIONS, BUSINESS_DIRECTION_REQUESTS, CALL_CLICKS, WEBSITE_CLICKS,
BUSINESS_BOOKINGS, BUSINESS_FOOD_ORDERS, BUSINESS_FOOD_MENU_CLICKS

- **startDate** (optional) in query: Start date (YYYY-MM-DD). Defaults to 30 days ago. Max 18 months back.
- **endDate** (optional) in query: End date (YYYY-MM-DD). Defaults to today.

### Responses

#### 200: Performance metrics with daily time series

**Response Body:**

- **success** `boolean`: No description (example: true)
- **accountId** `string`: No description
- **platform** `string`: No description (example: "googlebusiness")
- **dateRange** `object`: 
  - **startDate** `string` (date): No description (example: "2026-03-01")
  - **endDate** `string` (date): No description (example: "2026-03-31")
- **metrics** `object`: Each key is a metric name containing total and daily values.
- **dataDelay** `string`: No description (example: "Data may be delayed 2-3 days")

#### 400: Invalid parameters

**Response Body:**

- **error** `string`: No description (example: "Invalid metrics: INVALID_METRIC")
- **validMetrics** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **code** `string`: No description (example: "analytics_addon_required")

#### 403: Access denied

**Response Body:**

- **error** `string`: No description (example: "Access denied to this account")

---

---

# Get GBP search keywords API Reference

Returns search keywords that triggered impressions for a Google Business Profile location.
Data is aggregated monthly. Keywords below a minimum impression threshold set by Google are excluded.
Max 18 months of historical data. Requires the Analytics add-on.


## GET /v1/analytics/googlebusiness/search-keywords

**Get GBP search keywords**

Returns search keywords that triggered impressions for a Google Business Profile location.
Data is aggregated monthly. Keywords below a minimum impression threshold set by Google are excluded.
Max 18 months of historical data. Requires the Analytics add-on.


### Parameters

- **accountId** (required) in query: The Zernio SocialAccount ID for the Google Business Profile account.
- **startMonth** (optional) in query: Start month (YYYY-MM). Defaults to 3 months ago.
- **endMonth** (optional) in query: End month (YYYY-MM). Defaults to current month.

### Responses

#### 200: Search keywords with impression counts

**Response Body:**

- **success** `boolean`: No description (example: true)
- **accountId** `string`: No description
- **platform** `string`: No description (example: "googlebusiness")
- **monthRange** `object`: 
  - **startMonth** `string`: No description (example: "2026-01")
  - **endMonth** `string`: No description (example: "2026-03")
- **keywords** `array[object]`: 
  - **keyword** `string`: No description (example: "restaurant near me")
  - **impressions** `integer`: No description (example: 245)
- **note** `string`: No description (example: "Keywords below a minimum impression threshold are excluded by Google")

#### 400: Invalid parameters

**Response Body:**

- **error** `string`: No description (example: "Invalid startMonth format. Use YYYY-MM.")

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **code** `string`: No description (example: "analytics_addon_required")

#### 403: Access denied

**Response Body:**

- **error** `string`: No description (example: "Access denied to this account")

---

---

# Get Instagram insights API Reference

Returns account-level Instagram insights such as reach, views, accounts engaged, and total interactions.
These metrics reflect the entire account's performance across all content surfaces (feed, stories, explore, profile),
and are fundamentally different from post-level metrics. Data may be delayed up to 48 hours.
Max 90 days, defaults to last 30 days. Requires the Analytics add-on.


## GET /v1/analytics/instagram/account-insights

**Get Instagram insights**

Returns account-level Instagram insights such as reach, views, accounts engaged, and total interactions.
These metrics reflect the entire account's performance across all content surfaces (feed, stories, explore, profile),
and are fundamentally different from post-level metrics. Data may be delayed up to 48 hours.
Max 90 days, defaults to last 30 days. Requires the Analytics add-on.


### Parameters

- **accountId** (required) in query: The Zernio SocialAccount ID for the Instagram account
- **metrics** (optional) in query: Comma-separated list of metrics. Defaults to "reach,views,accounts_engaged,total_interactions".
Valid metrics: reach, views, accounts_engaged, total_interactions, comments, likes, saves, shares,
replies, reposts, follows_and_unfollows, profile_links_taps.
Note: only "reach" supports metricType=time_series. All other metrics (including
follows_and_unfollows) are total_value only. This is an Instagram Graph API limitation,
not a Zernio limitation - the IG API does not return time-series data for these metrics.
For a daily running follower count, use /v1/analytics/instagram/follower-history instead.

- **since** (optional) in query: Start date (YYYY-MM-DD). Defaults to 30 days ago.
- **until** (optional) in query: End date (YYYY-MM-DD). Defaults to today.
- **metricType** (optional) in query: "total_value" (default) returns aggregated totals and supports breakdowns.
"time_series" returns daily values but only works with the "reach" metric.

- **breakdown** (optional) in query: Breakdown dimension (only valid with metricType=total_value).
Valid values depend on the metric: media_product_type, follow_type, follower_type, contact_button_type.


### Responses

#### 200: Account insights data

**Response Body:**

- **success** `boolean`: No description (example: true)
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: Platform that served this response. - one of: facebook, instagram, youtube, linkedin, tiktok
- **dateRange** `object`: 
  - **since** `string` (date): No description
  - **until** `string` (date): No description
- **metricType** `string`: No description - one of: time_series, total_value
- **breakdown** `string`: Breakdown dimension used (only present when breakdown was requested)
- **metrics** `object`: Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).

- **dataDelay** `string`: No description (example: "Data may be delayed up to 48 hours")

#### 400: Bad request (invalid parameters)

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **code** `string`: No description (example: "analytics_addon_required")

#### 403: Access denied to this account

**Response Body:**

- **error** `string`: No description (example: "Access denied to this account")

#### 404: Account not found

**Response Body:**

- **error** `string`: No description (example: "Account not found")

---


# Related Schema Definitions

## InstagramAccountInsightsResponse

Shared account-insights response envelope used by every platform-level
analytics endpoint (/v1/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).
The name is historical - the shape was first shipped for Instagram and every
new platform endpoint reuses it for response-shape consistency. The platform
field echoes back which platform served the response.


### Properties

- **success** `boolean`: No description
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: Platform that served this response. - one of: facebook, instagram, youtube, linkedin, tiktok
- **dateRange** `object`: 
  - **since** `string`: 
  - **until** `string`: 
- **metricType** `string`: No description - one of: time_series, total_value
- **breakdown** `string`: Breakdown dimension used (only present when breakdown was requested)
- **metrics** `object`: Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).

- **dataDelay** `string`: No description

---

# Get Instagram demographics API Reference

Returns audience demographic insights for an Instagram account, broken down by age, city, country, and/or gender.
Requires at least 100 followers. Returns top 45 entries per dimension.
Data may be delayed up to 48 hours. Requires the Analytics add-on.


## GET /v1/analytics/instagram/demographics

**Get Instagram demographics**

Returns audience demographic insights for an Instagram account, broken down by age, city, country, and/or gender.
Requires at least 100 followers. Returns top 45 entries per dimension.
Data may be delayed up to 48 hours. Requires the Analytics add-on.


### Parameters

- **accountId** (required) in query: The Zernio SocialAccount ID for the Instagram account
- **metric** (optional) in query: "follower_demographics" for follower audience data, or "engaged_audience_demographics" for engaged viewers.

- **breakdown** (optional) in query: Comma-separated list of demographic dimensions: age, city, country, gender.
Defaults to all four if omitted.

- **timeframe** (optional) in query: Time period for demographic data. Defaults to "this_month".


### Responses

#### 200: Demographic insights data

**Response Body:**

- **success** `boolean`: No description (example: true)
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: No description (example: "instagram")
- **metric** `string`: No description - one of: follower_demographics, engaged_audience_demographics
- **timeframe** `string`: The timeframe used for demographic data - one of: this_week, this_month
- **demographics** `object`: Object keyed by breakdown dimension (age, city, country, gender)
- **note** `string`: No description (example: "Demographics show top 45 entries per dimension. Requires 100+ followers.")

#### 400: Bad request (invalid parameters)

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **code** `string`: No description (example: "analytics_addon_required")

#### 403: Access denied to this account

**Response Body:**

- **error** `string`: No description (example: "Access denied to this account")

#### 404: Account not found

**Response Body:**

- **error** `string`: No description (example: "Account not found")

---


# Related Schema Definitions

## InstagramDemographicsResponse

### Properties

- **success** `boolean`: No description
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: No description
- **metric** `string`: No description - one of: follower_demographics, engaged_audience_demographics
- **timeframe** `string`: The timeframe used for demographic data - one of: this_week, this_month
- **demographics** `object`: Object keyed by breakdown dimension (age, city, country, gender)
- **note** `string`: No description

---

# Get Instagram follower history API Reference

Returns a daily running Instagram follower count time series, served from Zernio's
cross-platform daily snapshotter. Exists because Meta removed follower_count from
the /insights endpoint in Graph API v22+ and never exposed a historical daily series
via any public API.

Response envelope matches /v1/analytics/instagram/account-insights so the same client
handling works. Max 89 days, defaults to last 30 days. Requires the Analytics add-on.


## GET /v1/analytics/instagram/follower-history

**Get Instagram follower history**

Returns a daily running Instagram follower count time series, served from Zernio's
cross-platform daily snapshotter. Exists because Meta removed follower_count from
the /insights endpoint in Graph API v22+ and never exposed a historical daily series
via any public API.

Response envelope matches /v1/analytics/instagram/account-insights so the same client
handling works. Max 89 days, defaults to last 30 days. Requires the Analytics add-on.


### Parameters

- **accountId** (required) in query: The Zernio SocialAccount ID for the Instagram account.
- **metrics** (optional) in query: Comma-separated list. Defaults to "follower_count,followers_gained,followers_lost".
  - follower_count   : per-day raw follower count
  - followers_gained : sum of positive daily deltas
  - followers_lost   : sum of absolute negative daily deltas

- **since** (optional) in query: Start date (YYYY-MM-DD). Defaults to 30 days ago.
- **until** (optional) in query: End date (YYYY-MM-DD). Defaults to today.
- **metricType** (optional) in query: "total_value" returns aggregated totals (latest for follower_count, sum for gained/lost).
"time_series" returns per-day values in the "values" array.


### Responses

#### 200: Follower history data

**Response Body:**

- **success** `boolean`: No description (example: true)
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: Platform that served this response. - one of: facebook, instagram, youtube, linkedin, tiktok
- **dateRange** `object`: 
  - **since** `string` (date): No description
  - **until** `string` (date): No description
- **metricType** `string`: No description - one of: time_series, total_value
- **breakdown** `string`: Breakdown dimension used (only present when breakdown was requested)
- **metrics** `object`: Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).

- **dataDelay** `string`: No description (example: "Data may be delayed up to 48 hours")

#### 400: Bad request (invalid accountId / metrics / date range, or account is not an Instagram account)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

#### 404: Account not found

---


# Related Schema Definitions

## InstagramAccountInsightsResponse

Shared account-insights response envelope used by every platform-level
analytics endpoint (/v1/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).
The name is historical - the shape was first shipped for Instagram and every
new platform endpoint reuses it for response-shape consistency. The platform
field echoes back which platform served the response.


### Properties

- **success** `boolean`: No description
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: Platform that served this response. - one of: facebook, instagram, youtube, linkedin, tiktok
- **dateRange** `object`: 
  - **since** `string`: 
  - **until** `string`: 
- **metricType** `string`: No description - one of: time_series, total_value
- **breakdown** `string`: Breakdown dimension used (only present when breakdown was requested)
- **metrics** `object`: Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).

- **dataDelay** `string`: No description

---

# Get LinkedIn aggregate stats API Reference

Returns aggregate analytics across all posts for a LinkedIn personal account. Only includes posts published through Zernio (LinkedIn API limitation). Org accounts should use /v1/analytics instead. Requires r_member_postAnalytics scope. Saves (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.

## GET /v1/accounts/{accountId}/linkedin-aggregate-analytics

**Get LinkedIn aggregate stats**

Returns aggregate analytics across all posts for a LinkedIn personal account. Only includes posts published through Zernio (LinkedIn API limitation). Org accounts should use /v1/analytics instead. Requires r_member_postAnalytics scope. Saves (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.

### Parameters

- **accountId** (required) in path: The ID of the LinkedIn personal account
- **aggregation** (optional) in query: TOTAL (default, lifetime totals) or DAILY (time series). MEMBERS_REACHED not available with DAILY.
- **startDate** (optional) in query: Start date (YYYY-MM-DD). If omitted, returns lifetime analytics.
- **endDate** (optional) in query: End date (YYYY-MM-DD, exclusive). Defaults to today if omitted.
- **metrics** (optional) in query: Comma-separated metrics: IMPRESSION, MEMBERS_REACHED, REACTION, COMMENT, RESHARE, POST_SAVE, POST_SEND. Omit for all.

### Responses

#### 200: Aggregate analytics data

**Response Body:**

*One of the following:*
- `LinkedInAggregateAnalyticsTotalResponse`
- `LinkedInAggregateAnalyticsDailyResponse`

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description
- **validOptions** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description

#### 403: Missing required LinkedIn scope

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description (example: "missing_scope")
- **requiredScope** `string`: No description (example: "r_member_postAnalytics")
- **action** `string`: No description (example: "reconnect")

#### 404: Account not found

---


# Related Schema Definitions

## LinkedInAggregateAnalyticsTotalResponse

Response for TOTAL aggregation (lifetime totals)

### Properties

- **accountId** `string`: No description
- **platform** `string`: No description
- **accountType** `string`: No description
- **username** `string`: No description
- **aggregation** `string`: No description - one of: TOTAL
- **dateRange** `object`: 
  - **startDate** `string`: 
  - **endDate** `string`: 
- **analytics** `object`: 
  - **impressions** `integer`: Total impressions across all posts
  - **reach** `integer`: Unique members reached across all posts
  - **reactions** `integer`: Total reactions across all posts
  - **comments** `integer`: Total comments across all posts
  - **shares** `integer`: Total reshares across all posts
  - **saves** `integer`: Total times posts were saved (personal accounts only)
  - **sends** `integer`: Total times posts were sent via LinkedIn messaging (personal accounts only)
  - **engagementRate** `number`: Overall engagement rate as percentage
- **note** `string`: No description
- **lastUpdated** `string`: No description

## LinkedInAggregateAnalyticsDailyResponse

Response for DAILY aggregation (time series breakdown)

### Properties

- **accountId** `string`: No description
- **platform** `string`: No description
- **accountType** `string`: No description
- **username** `string`: No description
- **aggregation** `string`: No description - one of: DAILY
- **dateRange** `object`: 
  - **startDate** `string`: 
  - **endDate** `string`: 
- **analytics** `object`: Daily breakdown of each metric as date/count pairs. Reach not available with DAILY aggregation.
  - **impressions** `array`: 
  - **reactions** `array`: 
  - **comments** `array`: 
  - **shares** `array`: 
  - **saves** `array`: Daily saves (personal accounts only)
  - **sends** `array`: Daily sends via LinkedIn messaging (personal accounts only)
- **skippedMetrics** `array`: Metrics that were skipped due to API limitations
- **note** `string`: No description
- **lastUpdated** `string`: No description

---

# Get LinkedIn organization page aggregate analytics API Reference

Returns aggregate analytics for a LinkedIn organization page. Parallel to
/v1/accounts/{id}/linkedin-aggregate-analytics (which handles personal accounts only).
Backed by LinkedIn's organizationalEntityShareStatistics,
organizationalEntityFollowerStatistics, and organizationPageStatistics endpoints.

Response shape matches /v1/analytics/instagram/account-insights. Max 89 days,
defaults to last 30 days. Requires the Analytics add-on.

Scope requirements: r_organization_social, r_organization_followers, and
r_organization_admin must all be present on the account. Accounts connected before
these scopes were included in the OAuth flow will return 412 with a reauth hint.

Enforced by this endpoint:
  - Page-view metrics accept only metricType=total_value (LinkedIn omits per-day
    segmentation even when the API is called with DAY granularity, so a time-series
    response would be meaningless).
  - Date range capped at 89 days.

LinkedIn-side platform limits (not re-enforced here, but worth knowing for larger
ranges in a future release):
  - Follower stats: rolling 12-month window, end must be no later than 2 days ago.
  - Share stats: rolling 12-month window.


## GET /v1/analytics/linkedin/org-aggregate-analytics

**Get LinkedIn organization page aggregate analytics**

Returns aggregate analytics for a LinkedIn organization page. Parallel to
/v1/accounts/{id}/linkedin-aggregate-analytics (which handles personal accounts only).
Backed by LinkedIn's organizationalEntityShareStatistics,
organizationalEntityFollowerStatistics, and organizationPageStatistics endpoints.

Response shape matches /v1/analytics/instagram/account-insights. Max 89 days,
defaults to last 30 days. Requires the Analytics add-on.

Scope requirements: r_organization_social, r_organization_followers, and
r_organization_admin must all be present on the account. Accounts connected before
these scopes were included in the OAuth flow will return 412 with a reauth hint.

Enforced by this endpoint:
  - Page-view metrics accept only metricType=total_value (LinkedIn omits per-day
    segmentation even when the API is called with DAY granularity, so a time-series
    response would be meaningless).
  - Date range capped at 89 days.

LinkedIn-side platform limits (not re-enforced here, but worth knowing for larger
ranges in a future release):
  - Follower stats: rolling 12-month window, end must be no later than 2 days ago.
  - Share stats: rolling 12-month window.


### Parameters

- **accountId** (required) in query: The Zernio SocialAccount ID for the LinkedIn organization account.
- **metrics** (optional) in query: Comma-separated list. Defaults to
"impressions,clicks,engagement_rate,organic_followers_gained,followers_gained,followers_lost".

Share statistics (support both total_value and time_series):
  - impressions
  - unique_impressions
  - clicks
  - likes
  - comments
  - shares
  - engagement_rate       (0..1, LinkedIn-computed)

Follower-gain statistics (support total_value and time_series):
  - organic_followers_gained   (per-day organic gains for time_series; sum of organic gains over the range for total_value)
  - paid_followers_gained      (per-day paid gains for time_series; sum of paid gains over the range for total_value)

Page-view statistics (total_value ONLY - LinkedIn platform limit):
  - page_views_total
  - page_views_overview
  - page_views_careers
  - page_views_jobs
  - page_views_life

Zernio-synthesized from daily follower snapshots:
  - followers_gained
  - followers_lost

- **since** (optional) in query: Start date (YYYY-MM-DD). Defaults to 30 days ago.
- **until** (optional) in query: End date (YYYY-MM-DD). Defaults to today.
- **metricType** (optional) in query: No description

### Responses

#### 200: Organization analytics data

**Response Body:**

- **success** `boolean`: No description (example: true)
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: Platform that served this response. - one of: facebook, instagram, youtube, linkedin, tiktok
- **dateRange** `object`: 
  - **since** `string` (date): No description
  - **until** `string` (date): No description
- **metricType** `string`: No description - one of: time_series, total_value
- **breakdown** `string`: Breakdown dimension used (only present when breakdown was requested)
- **metrics** `object`: Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).

- **dataDelay** `string`: No description (example: "Data may be delayed up to 48 hours")

#### 400: Bad request. Common cases:
  - Account is a personal LinkedIn account, not organization (code personal_account_not_supported, use /v1/accounts/{id}/linkedin-aggregate-analytics instead)
  - Invalid metric name, metricType, or date range


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

#### 403: Platform error. The authenticated member lacks the required
ADMINISTRATOR role on the organization. LinkedIn enforces admin-only
access for all three org statistics endpoints. The error envelope is
type platform_error, and the raw LinkedIn error is echoed in the
platformError field.


#### 404: Account not found

#### 412: Missing LinkedIn organization analytics scopes (r_organization_social + r_organization_followers + r_organization_admin)

---


# Related Schema Definitions

## InstagramAccountInsightsResponse

Shared account-insights response envelope used by every platform-level
analytics endpoint (/v1/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).
The name is historical - the shape was first shipped for Instagram and every
new platform endpoint reuses it for response-shape consistency. The platform
field echoes back which platform served the response.


### Properties

- **success** `boolean`: No description
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: Platform that served this response. - one of: facebook, instagram, youtube, linkedin, tiktok
- **dateRange** `object`: 
  - **since** `string`: 
  - **until** `string`: 
- **metricType** `string`: No description - one of: time_series, total_value
- **breakdown** `string`: Breakdown dimension used (only present when breakdown was requested)
- **metrics** `object`: Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).

- **dataDelay** `string`: No description

---

# Get LinkedIn post stats API Reference

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).

## GET /v1/accounts/{accountId}/linkedin-post-analytics

**Get LinkedIn post stats**

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

- **accountId** (required) in path: The ID of the LinkedIn account
- **urn** (required) in query: The LinkedIn post URN

### Responses

#### 200: Post analytics data

**Response Body:**

- **accountId** `string`: No description
- **platform** `string`: No description (example: "linkedin")
- **accountType** `string`: No description - one of: personal, organization
- **username** `string`: No description
- **postUrn** `string`: No description
- **analytics** `object`: 
  - **impressions** `integer`: Times the post was shown
  - **reach** `integer`: Unique members who saw the post
  - **likes** `integer`: Reactions on the post
  - **comments** `integer`: Comments on the post
  - **shares** `integer`: Reshares of the post
  - **saves** `integer`: Times the post was saved (personal accounts only; 0 for organization accounts)
  - **sends** `integer`: Times the post was sent via LinkedIn messaging (personal accounts only; 0 for organization accounts)
  - **clicks** `integer`: Clicks on the post (organization accounts only)
  - **views** `integer`: Video views (video posts only)
  - **engagementRate** `number`: Engagement rate as percentage
- **lastUpdated** `string` (date-time): No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description - one of: missing_urn, invalid_urn, invalid_platform

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

#### 403: Missing required LinkedIn scope

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description (example: "missing_scope")
- **requiredScope** `string`: No description
- **action** `string`: No description (example: "reconnect")

#### 404: Account or post not found

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description

---

---

# Get LinkedIn post reactions API Reference

Returns individual reactions for a specific LinkedIn post, including reactor profiles
(name, headline/job title, profile picture, profile URL, reaction type).
Only works for organization/company page accounts. LinkedIn restricts reaction
data for personal profiles (r_member_social_feed is a closed permission).


## GET /v1/accounts/{accountId}/linkedin-post-reactions

**Get LinkedIn post reactions**

Returns individual reactions for a specific LinkedIn post, including reactor profiles
(name, headline/job title, profile picture, profile URL, reaction type).
Only works for organization/company page accounts. LinkedIn restricts reaction
data for personal profiles (r_member_social_feed is a closed permission).


### Parameters

- **accountId** (required) in path: The ID of the LinkedIn organization account
- **urn** (required) in query: The LinkedIn post URN
- **limit** (optional) in query: Maximum number of reactions to return per page
- **cursor** (optional) in query: Offset-based pagination start index

### Responses

#### 200: Reactions with reactor profiles

**Response Body:**

- **accountId** `string`: No description
- **platform** `string`: No description (example: "linkedin")
- **accountType** `string`: No description (example: "organization")
- **username** `string`: No description
- **postUrn** `string`: No description
- **reactions** `array[object]`: 
  - **reactionType** `string`: LinkedIn reaction enum (LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, ENTERTAINMENT)
  - **reactionLabel** `string`: User-friendly label (Like, Celebrate, Love, Insightful, Support, Funny)
  - **reactedAt** `string` (date-time): No description
  - **from** `object`: 
    - **urn** `string`: LinkedIn person or organization URN
    - **name** `string`: Reactor's display name
    - **headline** `string`: Reactor's headline/job title
    - **username** `string`: LinkedIn vanity name
    - **profilePicture** `string`: Profile picture URL
    - **profileUrl** `string`: Direct link to LinkedIn profile
- **pagination** `object`: 
  - **hasMore** `boolean`: No description
  - **cursor** `string`: Offset for next page
  - **total** `integer`: Total number of reactions (when available)
- **lastUpdated** `string` (date-time): No description

#### 400: Invalid request or platform limitation

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description - one of: missing_urn, invalid_urn, invalid_platform, PLATFORM_LIMITATION

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

#### 403: Missing required LinkedIn scope

#### 404: Account or post not found

---

---

# Get post analytics timeline API Reference

Returns a daily timeline of analytics metrics for a specific post, showing how impressions, likes,
and other metrics evolved day-by-day since publishing. Each row represents one day of data per platform.
For multi-platform Zernio posts, returns separate rows for each platform. Requires the Analytics add-on.


## GET /v1/analytics/post-timeline

**Get post analytics timeline**

Returns a daily timeline of analytics metrics for a specific post, showing how impressions, likes,
and other metrics evolved day-by-day since publishing. Each row represents one day of data per platform.
For multi-platform Zernio posts, returns separate rows for each platform. Requires the Analytics add-on.


### Parameters

- **postId** (required) in query: The post to fetch timeline for. Accepts an ExternalPost ID, a platformPostId, or a Zernio Post ID.

- **fromDate** (optional) in query: Start of date range (ISO 8601). Defaults to 90 days ago.
- **toDate** (optional) in query: End of date range (ISO 8601). Defaults to now.

### Responses

#### 200: Daily analytics timeline

**Response Body:**

- **postId** `string`: The postId that was requested
- **timeline** `array[object]`: 
  - **date** `string` (date): Date in YYYY-MM-DD format
  - **platform** `string`: Platform name (e.g. instagram, tiktok)
  - **platformPostId** `string`: Platform-specific post ID
  - **impressions** `integer`: Total impressions on this date
  - **reach** `integer`: Total reach on this date
  - **likes** `integer`: Total likes on this date
  - **comments** `integer`: Total comments on this date
  - **shares** `integer`: Total shares on this date
  - **saves** `integer`: Total saves on this date
  - **clicks** `integer`: Total clicks on this date
  - **views** `integer`: Total views on this date

#### 400: Missing required postId parameter

**Response Body:**

- **error** `string`: No description (example: "Missing required parameter: postId")

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **code** `string`: No description (example: "analytics_addon_required")

#### 403: Forbidden (post belongs to another user or API key scope violation)

**Response Body:**

- **error** `string`: No description (example: "Forbidden")

#### 404: Post not found

**Response Body:**

- **error** `string`: No description (example: "Post not found")

---

---

# Get frequency vs engagement API Reference

Returns the correlation between posting frequency (posts per week) and engagement rate, broken down by platform.
Helps find the optimal posting cadence for each platform. Each row represents a specific (platform, posts_per_week) combination
with the average engagement rate observed across all weeks matching that frequency.
Requires the Analytics add-on.


## GET /v1/analytics/posting-frequency

**Get frequency vs engagement**

Returns the correlation between posting frequency (posts per week) and engagement rate, broken down by platform.
Helps find the optimal posting cadence for each platform. Each row represents a specific (platform, posts_per_week) combination
with the average engagement rate observed across all weeks matching that frequency.
Requires the Analytics add-on.


### Parameters

- **platform** (optional) in query: Filter by platform (e.g. "instagram", "tiktok"). Omit for all platforms.
- **profileId** (optional) in query: Filter by profile ID. Omit for all profiles.
- **accountId** (optional) in query: Filter by social account ID. Omit for all accounts.
- **source** (optional) in query: Filter by post origin. "late" for posts published via Zernio, "external" for posts imported from platforms.

### Responses

#### 200: Posting frequency data

**Response Body:**

- **frequency** `array[object]`: 
  - **platform** `string`: No description (example: "instagram")
  - **posts_per_week** `integer`: Number of posts published that week
  - **avg_engagement_rate** `number`: Average engagement rate as percentage (0-100)
  - **avg_engagement** `number`: Average raw engagement (likes+comments+shares+saves)
  - **weeks_count** `integer`: Number of calendar weeks observed at this frequency

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **requiresAddon** `boolean`: No description (example: true)

---

---

# Get TikTok account-level insights API Reference

Returns account-level TikTok insights from /v2/user/info/ (live) plus historical
time series joined from Zernio's daily snapshotter (AccountStats).

Response shape matches /v1/analytics/instagram/account-insights. Max 89 days,
defaults to last 30 days. Requires the Analytics add-on and the user.info.stats
scope on the account (412 if missing).

Scope intentionally narrow. TikTok's public API exposes only the four counter
metrics below. The deep metrics that live in TikTok Studio are NOT available on any
public TikTok API, even for Business accounts:
  - profile_views
  - account-level impressions / reach
  - follower inflow / outflow breakdown
  - video watch time, average watch time, full-watched rate
  - impression_sources (FYP / Following / Hashtag / Search / Personal profile)

TikTok's Research API doesn't expose those fields either, and is restricted to
non-commercial academic use per TikTok's eligibility policy. There is no public
API workaround. Post-level metrics (views, likes, comments, shares per video) are
available via /v1/analytics?postId=... from TikTok's /v2/video/query/.


## GET /v1/analytics/tiktok/account-insights

**Get TikTok account-level insights**

Returns account-level TikTok insights from /v2/user/info/ (live) plus historical
time series joined from Zernio's daily snapshotter (AccountStats).

Response shape matches /v1/analytics/instagram/account-insights. Max 89 days,
defaults to last 30 days. Requires the Analytics add-on and the user.info.stats
scope on the account (412 if missing).

Scope intentionally narrow. TikTok's public API exposes only the four counter
metrics below. The deep metrics that live in TikTok Studio are NOT available on any
public TikTok API, even for Business accounts:
  - profile_views
  - account-level impressions / reach
  - follower inflow / outflow breakdown
  - video watch time, average watch time, full-watched rate
  - impression_sources (FYP / Following / Hashtag / Search / Personal profile)

TikTok's Research API doesn't expose those fields either, and is restricted to
non-commercial academic use per TikTok's eligibility policy. There is no public
API workaround. Post-level metrics (views, likes, comments, shares per video) are
available via /v1/analytics?postId=... from TikTok's /v2/video/query/.


### Parameters

- **accountId** (required) in query: The Zernio SocialAccount ID for the TikTok account.
- **metrics** (optional) in query: Comma-separated list. Defaults to
"follower_count,likes_count,video_count,followers_gained,followers_lost".

Live from /v2/user/info/ (requires user.info.stats scope):
  - follower_count  (cumulative; time series joined from AccountStats)
  - following_count (cumulative; time series joined from AccountStats.metadata)
  - likes_count     (cumulative; time series joined from AccountStats.metadata)
  - video_count     (cumulative; time series joined from AccountStats.metadata)

Zernio-synthesized:
  - followers_gained  (sum of positive daily follower deltas)
  - followers_lost    (sum of absolute negative daily deltas)

- **since** (optional) in query: Start date (YYYY-MM-DD). Defaults to 30 days ago.
- **until** (optional) in query: End date (YYYY-MM-DD). Defaults to today.
- **metricType** (optional) in query: "total_value" returns the latest cumulative counter value.
"time_series" returns daily values joined from AccountStats snapshots.


### Responses

#### 200: Account insights data

**Response Body:**

- **success** `boolean`: No description (example: true)
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: Platform that served this response. - one of: facebook, instagram, youtube, linkedin, tiktok
- **dateRange** `object`: 
  - **since** `string` (date): No description
  - **until** `string` (date): No description
- **metricType** `string`: No description - one of: time_series, total_value
- **breakdown** `string`: Breakdown dimension used (only present when breakdown was requested)
- **metrics** `object`: Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).

- **dataDelay** `string`: No description (example: "Data may be delayed up to 48 hours")

#### 400: Bad request (invalid accountId / metrics / metricType / date range, or account is not a TikTok account)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

#### 404: Account not found

#### 412: Missing user.info.stats scope

---


# Related Schema Definitions

## InstagramAccountInsightsResponse

Shared account-insights response envelope used by every platform-level
analytics endpoint (/v1/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).
The name is historical - the shape was first shipped for Instagram and every
new platform endpoint reuses it for response-shape consistency. The platform
field echoes back which platform served the response.


### Properties

- **success** `boolean`: No description
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: Platform that served this response. - one of: facebook, instagram, youtube, linkedin, tiktok
- **dateRange** `object`: 
  - **since** `string`: 
  - **until** `string`: 
- **metricType** `string`: No description - one of: time_series, total_value
- **breakdown** `string`: Breakdown dimension used (only present when breakdown was requested)
- **metrics** `object`: Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).

- **dataDelay** `string`: No description

---

# Get YouTube channel-level insights API Reference

Returns channel-scoped aggregate metrics from YouTube Analytics API v2. Saves you
from looping /v1/analytics/youtube/daily-views over every video when you only need
channel totals.

Response shape matches /v1/analytics/instagram/account-insights so the same client
handling works. Requires yt-analytics.readonly scope (412 with reauthorizeUrl if
missing). Data has a 2-3 day delay (endDate is clamped accordingly). Max 89 days,
defaults to last 30 days. Requires the Analytics add-on.

NOT exposed: impressions (Studio thumbnail impressions) and impressionsClickThroughRate.
YouTube Analytics API v2 does not expose these for any principal type, not channel
owners, not Partner Program channels, not content owners with CMS access. The only way
to get them is Studio CSV export. This is a Google-side limitation.


## GET /v1/analytics/youtube/channel-insights

**Get YouTube channel-level insights**

Returns channel-scoped aggregate metrics from YouTube Analytics API v2. Saves you
from looping /v1/analytics/youtube/daily-views over every video when you only need
channel totals.

Response shape matches /v1/analytics/instagram/account-insights so the same client
handling works. Requires yt-analytics.readonly scope (412 with reauthorizeUrl if
missing). Data has a 2-3 day delay (endDate is clamped accordingly). Max 89 days,
defaults to last 30 days. Requires the Analytics add-on.

NOT exposed: impressions (Studio thumbnail impressions) and impressionsClickThroughRate.
YouTube Analytics API v2 does not expose these for any principal type, not channel
owners, not Partner Program channels, not content owners with CMS access. The only way
to get them is Studio CSV export. This is a Google-side limitation.


### Parameters

- **accountId** (required) in query: The Zernio SocialAccount ID for the YouTube account.
- **metrics** (optional) in query: Comma-separated list. Defaults to "views,estimatedMinutesWatched,subscribersGained,subscribersLost".

Live YouTube Analytics v2 metrics:
  - views
  - estimatedMinutesWatched
  - averageViewDuration          (ratio - weighted mean computed across days)
  - subscribersGained
  - subscribersLost

Zernio-synthesized from daily follower snapshots (cross-platform parity):
  - followers_gained
  - followers_lost

- **since** (optional) in query: Start date (YYYY-MM-DD). Defaults to 30 days ago.
- **until** (optional) in query: End date (YYYY-MM-DD). Defaults to today. YouTube Analytics has a 2-3 day delay,
so the fetch is internally clamped to 3 days ago; any requested range extending
beyond that returns zero values for the tail days. The response's dateRange.until
field reflects your requested value.

- **metricType** (optional) in query: "total_value" (default) returns aggregated totals.
"time_series" returns per-day values in the "values" array.


### Responses

#### 200: Channel insights data

**Response Body:**

- **success** `boolean`: No description (example: true)
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: Platform that served this response. - one of: facebook, instagram, youtube, linkedin, tiktok
- **dateRange** `object`: 
  - **since** `string` (date): No description
  - **until** `string` (date): No description
- **metricType** `string`: No description - one of: time_series, total_value
- **breakdown** `string`: Breakdown dimension used (only present when breakdown was requested)
- **metrics** `object`: Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).

- **dataDelay** `string`: No description (example: "Data may be delayed up to 48 hours")

#### 400: Bad request (invalid accountId / metrics / metricType / date range, or account is not a YouTube account)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

#### 404: Account not found

#### 412: Missing YouTube Analytics scope

**Response Body:**

- **success** `boolean`: No description (example: false)
- **error** `string`: No description (example: "To access daily video analytics, please reconnect your YouTube account to grant the required permissions.")
- **code** `string`: No description (example: "youtube_analytics_scope_missing")
- **scopeStatus** `object`: 
  - **hasAnalyticsScope** `boolean`: No description (example: false)
  - **requiresReauthorization** `boolean`: No description (example: true)
  - **reauthorizeUrl** `string` (uri): URL to redirect user for reauthorization

---


# Related Schema Definitions

## InstagramAccountInsightsResponse

Shared account-insights response envelope used by every platform-level
analytics endpoint (/v1/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).
The name is historical - the shape was first shipped for Instagram and every
new platform endpoint reuses it for response-shape consistency. The platform
field echoes back which platform served the response.


### Properties

- **success** `boolean`: No description
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: Platform that served this response. - one of: facebook, instagram, youtube, linkedin, tiktok
- **dateRange** `object`: 
  - **since** `string`: 
  - **until** `string`: 
- **metricType** `string`: No description - one of: time_series, total_value
- **breakdown** `string`: Breakdown dimension used (only present when breakdown was requested)
- **metrics** `object`: Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).

- **dataDelay** `string`: No description

## YouTubeScopeMissingResponse

### Properties

- **success** `boolean`: No description
- **error** `string`: No description
- **code** `string`: No description
- **scopeStatus** `object`: 
  - **hasAnalyticsScope** `boolean`: 
  - **requiresReauthorization** `boolean`: 
  - **reauthorizeUrl** `string`: URL to redirect user for reauthorization

---

# Get YouTube daily views API Reference

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). Data has a 2-3 day delay. Max 90 days, defaults to last 30 days.


## GET /v1/analytics/youtube/daily-views

**Get YouTube daily views**

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). Data has a 2-3 day delay. Max 90 days, defaults to last 30 days.


### Parameters

- **videoId** (required) in query: The YouTube video ID (e.g., "dQw4w9WgXcQ")
- **accountId** (required) in query: The Zernio account ID for the YouTube account
- **startDate** (optional) in query: Start date (YYYY-MM-DD). Defaults to 30 days ago.
- **endDate** (optional) in query: End date (YYYY-MM-DD). Defaults to 3 days ago (YouTube data latency).

### Responses

#### 200: Daily views breakdown

**Response Body:**

- **success** `boolean`: No description (example: true)
- **videoId** `string`: The YouTube video ID
- **durationSeconds** `integer`: Video length in seconds (from YouTube contentDetails.duration)
- **dateRange** `object`: 
  - **startDate** `string` (date): No description
  - **endDate** `string` (date): No description
- **totalViews** `integer`: Sum of views across all days in the range
- **dailyViews** `array[object]`: 
  - **date** `string` (date): No description
  - **views** `integer`: No description
  - **estimatedMinutesWatched** `number`: No description
  - **averageViewDuration** `number`: Average view duration in seconds
  - **averageViewPercentage** `number`: Average percentage of the video watched per view. Can exceed 100 on Shorts (looping rewatches), so do not clamp it client-side.
  - **subscribersGained** `integer`: No description
  - **subscribersLost** `integer`: No description
  - **likes** `integer`: No description
  - **comments** `integer`: No description
  - **shares** `integer`: No description
- **lastSyncedAt** `string` (date-time): When the data was last synced from YouTube
- **scopeStatus** `object`: 
  - **hasAnalyticsScope** `boolean`: No description

#### 400: Bad request (missing or invalid parameters)

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **code** `string`: No description (example: "analytics_addon_required")

#### 403: Access denied to this account

**Response Body:**

- **error** `string`: No description (example: "Access denied to this account")

#### 412: Missing YouTube Analytics scope

**Response Body:**

- **success** `boolean`: No description (example: false)
- **error** `string`: No description (example: "To access daily video analytics, please reconnect your YouTube account to grant the required permissions.")
- **code** `string`: No description (example: "youtube_analytics_scope_missing")
- **scopeStatus** `object`: 
  - **hasAnalyticsScope** `boolean`: No description (example: false)
  - **requiresReauthorization** `boolean`: No description (example: true)
  - **reauthorizeUrl** `string` (uri): URL to redirect user for reauthorization

#### 500: Internal server error

**Response Body:**

- **success** `boolean`: No description (example: false)
- **error** `string`: No description

---


# Related Schema Definitions

## YouTubeDailyViewsResponse

### Properties

- **success** `boolean`: No description
- **videoId** `string`: The YouTube video ID
- **durationSeconds** `integer`: Video length in seconds (from YouTube contentDetails.duration)
- **dateRange** `object`: 
  - **startDate** `string`: 
  - **endDate** `string`: 
- **totalViews** `integer`: Sum of views across all days in the range
- **dailyViews** `array`: No description
- **lastSyncedAt** `string`: When the data was last synced from YouTube
- **scopeStatus** `object`: 
  - **hasAnalyticsScope** `boolean`: 

## YouTubeScopeMissingResponse

### Properties

- **success** `boolean`: No description
- **error** `string`: No description
- **code** `string`: No description
- **scopeStatus** `object`: 
  - **hasAnalyticsScope** `boolean`: 
  - **requiresReauthorization** `boolean`: 
  - **reauthorizeUrl** `string`: URL to redirect user for reauthorization

---

# Get YouTube demographics API Reference

Returns audience demographic insights for a YouTube channel, broken down by age, gender, and/or country.
Age and gender values are viewer percentages (0-100). Country values are view counts.
Data is based on signed-in viewers only, with a 2-3 day delay. Requires the Analytics add-on.


## GET /v1/analytics/youtube/demographics

**Get YouTube demographics**

Returns audience demographic insights for a YouTube channel, broken down by age, gender, and/or country.
Age and gender values are viewer percentages (0-100). Country values are view counts.
Data is based on signed-in viewers only, with a 2-3 day delay. Requires the Analytics add-on.


### Parameters

- **accountId** (required) in query: The Zernio SocialAccount ID for the YouTube account
- **breakdown** (optional) in query: Comma-separated list of demographic dimensions: age, gender, country.
Defaults to all three if omitted.

- **startDate** (optional) in query: Start date in YYYY-MM-DD format. Defaults to 90 days ago.

- **endDate** (optional) in query: End date in YYYY-MM-DD format. Defaults to 3 days ago (YouTube data latency).


### Responses

#### 200: Demographic insights data

**Response Body:**

- **success** `boolean`: No description (example: true)
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: No description (example: "youtube")
- **demographics** `object`: Object keyed by breakdown dimension (age, gender, country)
- **dateRange** `object`: 
  - **startDate** `string`: No description (example: "2026-01-01")
  - **endDate** `string`: No description (example: "2026-03-31")
- **note** `string`: No description (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.")

#### 400: Bad request (invalid parameters or not a YouTube account)

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **code** `string`: No description (example: "analytics_addon_required")

#### 403: Access denied to this account

**Response Body:**

- **error** `string`: No description (example: "Access denied to this account")

#### 404: Account not found

**Response Body:**

- **error** `string`: No description (example: "Account not found")

#### 412: YouTube Analytics scope not granted

**Response Body:**

- **success** `boolean`: No description (example: false)
- **error** `string`: No description
- **code** `string`: No description (example: "youtube_analytics_scope_missing")
- **scopeStatus** `object`: 
  - **hasAnalyticsScope** `boolean`: No description (example: false)
  - **requiresReauthorization** `boolean`: No description (example: true)
  - **reauthorizeUrl** `string`: No description

---


# Related Schema Definitions

## YouTubeDemographicsResponse

### Properties

- **success** `boolean`: No description
- **accountId** `string`: The Zernio SocialAccount ID
- **platform** `string`: No description
- **demographics** `object`: Object keyed by breakdown dimension (age, gender, country)
- **dateRange** `object`: 
  - **startDate** `string`: 
  - **endDate** `string`: 
- **note** `string`: No description

---

# Get YouTube video retention curve API Reference

Returns the audience retention curve for a single YouTube video, plus the video's
duration for rendering the curve on a time axis. The curve has up to 100 points
(elapsedVideoTimeRatio 0.01-1.0) aggregated over the whole date range; YouTube does
not support per-day retention breakdowns.

audienceWatchRatio is the absolute share of viewers watching at that point in the
video and can exceed 1 (rewinds and looping, common on Shorts). relativeRetentionPerformance
compares against videos of similar length (0 = worst, 0.5 = median, 1 = best).
YouTube returns an empty curve for videos with very few views or before analytics
processing completes (2-3 day delay).

Requires yt-analytics.readonly scope (re-authorization may be needed).


## GET /v1/analytics/youtube/video-retention

**Get YouTube video retention curve**

Returns the audience retention curve for a single YouTube video, plus the video's
duration for rendering the curve on a time axis. The curve has up to 100 points
(elapsedVideoTimeRatio 0.01-1.0) aggregated over the whole date range; YouTube does
not support per-day retention breakdowns.

audienceWatchRatio is the absolute share of viewers watching at that point in the
video and can exceed 1 (rewinds and looping, common on Shorts). relativeRetentionPerformance
compares against videos of similar length (0 = worst, 0.5 = median, 1 = best).
YouTube returns an empty curve for videos with very few views or before analytics
processing completes (2-3 day delay).

Requires yt-analytics.readonly scope (re-authorization may be needed).


### Parameters

- **videoId** (required) in query: The YouTube video ID (e.g., "dQw4w9WgXcQ")
- **accountId** (required) in query: The Zernio account ID for the YouTube account
- **startDate** (optional) in query: Start date (YYYY-MM-DD). Defaults to the video's publish date (lifetime curve).
- **endDate** (optional) in query: End date (YYYY-MM-DD). Defaults to 3 days ago (YouTube data latency).

### Responses

#### 200: Audience retention curve

**Response Body:**

- **success** `boolean`: No description (example: true)
- **accountId** `string`: The Zernio account ID for the YouTube account
- **videoId** `string`: The YouTube video ID
- **title** `string`: Video title
- **publishedAt** `string` (date-time): When the video was published on YouTube
- **durationSeconds** `integer`: Video length in seconds (from YouTube contentDetails.duration)
- **dateRange** `object`: 
  - **startDate** `string` (date): No description
  - **endDate** `string` (date): No description
- **retentionCurve** `array[object]`: Up to 100 points covering the video timeline, aggregated over the date range. Empty for videos with very few views.
  - **elapsedVideoTimeRatio** `number`: Position in the video as a ratio (0.01-1.0, exclusive end of each interval)
  - **audienceWatchRatio** `number`: Absolute share of viewers watching at this point. Can exceed 1 (rewinds/looping, common on Shorts).
  - **relativeRetentionPerformance** `number`: Retention vs videos of similar length (0 = worst, 0.5 = median, 1 = best)
  - **startedWatching** `integer`: Viewers who started watching in this segment
  - **stoppedWatching** `integer`: Viewers who stopped watching in this segment
  - **totalSegmentImpressions** `integer`: Total views of this segment, including rewatches
- **note** `string`: Present only when the curve is empty, explaining why
- **scopeStatus** `object`: 
  - **hasAnalyticsScope** `boolean`: No description

#### 400: Bad request (missing or invalid parameters)

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.

**Response Body:**

- **error** `string`: No description (example: "Analytics add-on required")
- **code** `string`: No description (example: "analytics_addon_required")

#### 403: Access denied to this account

**Response Body:**

- **error** `string`: No description (example: "Access denied to this account")

#### 404: Video not found, or it does not belong to this YouTube channel

**Response Body:**

- **error** `string`: No description (example: "Video not found on this YouTube channel")
- **type** `string`: No description (example: "not_found")
- **code** `string`: No description (example: "video_not_found")
- **param** `string`: No description (example: "videoId")

#### 412: Missing YouTube Analytics scope

**Response Body:**

- **success** `boolean`: No description (example: false)
- **error** `string`: No description (example: "To access daily video analytics, please reconnect your YouTube account to grant the required permissions.")
- **code** `string`: No description (example: "youtube_analytics_scope_missing")
- **scopeStatus** `object`: 
  - **hasAnalyticsScope** `boolean`: No description (example: false)
  - **requiresReauthorization** `boolean`: No description (example: true)
  - **reauthorizeUrl** `string` (uri): URL to redirect user for reauthorization

#### 500: Internal server error

**Response Body:**

- **success** `boolean`: No description (example: false)
- **error** `string`: No description

---


# Related Schema Definitions

## YouTubeVideoRetentionResponse

### Properties

- **success** `boolean`: No description
- **accountId** `string`: The Zernio account ID for the YouTube account
- **videoId** `string`: The YouTube video ID
- **title** `string`: Video title
- **publishedAt** `string`: When the video was published on YouTube
- **durationSeconds** `integer`: Video length in seconds (from YouTube contentDetails.duration)
- **dateRange** `object`: 
  - **startDate** `string`: 
  - **endDate** `string`: 
- **retentionCurve** `array`: Up to 100 points covering the video timeline, aggregated over the date range. Empty for videos with very few views.
- **note** `string`: Present only when the curve is empty, explaining why
- **scopeStatus** `object`: 
  - **hasAnalyticsScope** `boolean`: 

## YouTubeScopeMissingResponse

### Properties

- **success** `boolean`: No description
- **error** `string`: No description
- **code** `string`: No description
- **scopeStatus** `object`: 
  - **hasAnalyticsScope** `boolean`: 
  - **requiresReauthorization** `boolean`: 
  - **reauthorizeUrl** `string`: URL to redirect user for reauthorization

---

# Create key API Reference

Creates a new API key with an optional expiry. The full key value is only returned once in the response.

## GET /v1/api-keys

**List keys**

Returns all API keys for the authenticated user. Keys are returned with a preview only, not the full key value.

### Responses

#### 200: API keys

**Response Body:**

- **apiKeys** `array[ApiKey]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/api-keys

**Create key**

Creates a new API key with an optional expiry. The full key value is only returned once in the response.

### Request Body

- **name** (required) `string`: No description
- **expiresIn** `integer`: Days until expiry
- **scope** `string`: 'full' grants access to all profiles (default), 'profiles' restricts to specific profiles - one of: full, profiles
- **profileIds** `array`: Profile IDs this key can access. Required when scope is 'profiles'.
- **permission** `string`: 'read-write' allows all operations (default), 'read' restricts to GET requests only - one of: read-write, read

### Responses

#### 201: Created

**Response Body:**

- **message** `string`: No description
- **apiKey**: `ApiKey` - See schema definition

#### 400: Invalid request (missing name

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## ApiKey

### Properties

- **id** `string`: No description
- **name** `string`: No description
- **keyPreview** `string`: No description
- **expiresAt** `string`: No description
- **createdAt** `string`: No description
- **key** `string`: Returned only once, on creation
- **scope** `string`: 'full' grants access to all profiles, 'profiles' restricts to specific profiles - one of: full, profiles (default: full)
- **profileIds** `array`: Profiles this key can access (populated with name and color). Only present when scope is 'profiles'.
- **permission** `string`: 'read-write' allows all operations, 'read' restricts to GET requests only - one of: read-write, read (default: read-write)

---

# Delete key API Reference

Permanently revokes and deletes an API key.

## DELETE /v1/api-keys/{keyId}

**Delete key**

Permanently revokes and deletes an API key.

### Parameters

- **keyId** (required) in path: No description

### Responses

#### 200: Deleted

**Response Body:**

- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List keys API Reference

Returns all API keys for the authenticated user. Keys are returned with a preview only, not the full key value.

## GET /v1/api-keys

**List keys**

Returns all API keys for the authenticated user. Keys are returned with a preview only, not the full key value.

### Responses

#### 200: API keys

**Response Body:**

- **apiKeys** `array[ApiKey]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/api-keys

**Create key**

Creates a new API key with an optional expiry. The full key value is only returned once in the response.

### Request Body

- **name** (required) `string`: No description
- **expiresIn** `integer`: Days until expiry
- **scope** `string`: 'full' grants access to all profiles (default), 'profiles' restricts to specific profiles - one of: full, profiles
- **profileIds** `array`: Profile IDs this key can access. Required when scope is 'profiles'.
- **permission** `string`: 'read-write' allows all operations (default), 'read' restricts to GET requests only - one of: read-write, read

### Responses

#### 201: Created

**Response Body:**

- **message** `string`: No description
- **apiKey**: `ApiKey` - See schema definition

#### 400: Invalid request (missing name

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## ApiKey

### Properties

- **id** `string`: No description
- **name** `string`: No description
- **keyPreview** `string`: No description
- **expiresAt** `string`: No description
- **createdAt** `string`: No description
- **key** `string`: Returned only once, on creation
- **scope** `string`: 'full' grants access to all profiles, 'profiles' restricts to specific profiles - one of: full, profiles (default: full)
- **profileIds** `array`: Profiles this key can access (populated with name and color). Only present when scope is 'profiles'.
- **permission** `string`: 'read-write' allows all operations, 'read' restricts to GET requests only - one of: read-write, read (default: read-write)

---

# Add recipients to a broadcast API Reference

Add recipients by contact IDs, raw phone numbers, or from the broadcast's segment filters.

## GET /v1/broadcasts/{broadcastId}/recipients

**List broadcast recipients**

Returns recipients for a broadcast with individual delivery status. Filter by status.

### Parameters

- **broadcastId** (required) in path: No description
- **status** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Recipients list with delivery status

**Response Body:**

- **success** `boolean`: No description
- **recipients** `array[object]`: 
  - **id** `string`: No description
  - **contactId** `string`: No description
  - **channelId** `string`: No description
  - **platformIdentifier** `string`: No description
  - **contactName** `string`: No description
  - **status** `string`: No description - one of: pending, sent, delivered, read, failed
  - **messageId** `string`: No description
  - **error** `string`: No description
  - **errorCode** `integer`: Meta WhatsApp error code (e.g. 131049 for antispam, 131021 for invalid phone, 131026 for re-engagement required). Only populated for status=failed.
  - **errorExplanation** `string`: 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.
  - **sentAt** `string` (date-time): No description
  - **deliveredAt** `string` (date-time): No description
  - **readAt** `string` (date-time): No description
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## POST /v1/broadcasts/{broadcastId}/recipients

**Add recipients to a broadcast**

Add recipients by contact IDs, raw phone numbers, or from the broadcast's segment filters.

### Parameters

- **broadcastId** (required) in path: No description

### Request Body

- **contactIds** `array`: Specific contact IDs to add
- **phones** `array`: Raw phone numbers (auto-creates contacts). Useful for WhatsApp/Telegram manual entry
- **useSegment** `boolean`: Auto-populate from broadcast segment filters

### Responses

#### 200: Recipients added

**Response Body:**

- **success** `boolean`: No description
- **added** `integer`: Number of recipients successfully added
- **skipped** `integer`: Number skipped (duplicates or missing channels)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Cancel broadcast API Reference

Cancel a scheduled or in-progress broadcast. Already-sent messages are not affected.

## POST /v1/broadcasts/{broadcastId}/cancel

**Cancel broadcast**

Cancel a scheduled or in-progress broadcast. Already-sent messages are not affected.

### Parameters

- **broadcastId** (required) in path: No description

### Responses

#### 200: Broadcast cancelled

**Response Body:**

- **success** `boolean`: No description
- **broadcast** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description

#### 400: Cannot cancel in current status

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Create broadcast draft API Reference

Create a broadcast in draft status. Add recipients and then send or schedule it.

## GET /v1/broadcasts

**List broadcasts**

Returns broadcasts with delivery stats. Filter by status, platform, or profile.

### Parameters

- **profileId** (optional) in query: Filter by profile. Omit to list across all profiles
- **status** (optional) in query: No description
- **platform** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Broadcasts list

**Response Body:**

- **success** `boolean`: No description
- **broadcasts** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **accountName** `string`: Display name of the sending account
  - **status** `string`: No description - one of: draft, scheduled, sending, completed, failed, cancelled
  - **messagePreview** `string`: Template name or message text snippet
  - **scheduledAt** `string` (date-time): No description
  - **startedAt** `string` (date-time): No description
  - **completedAt** `string` (date-time): No description
  - **recipientCount** `integer`: No description
  - **sentCount** `integer`: No description
  - **deliveredCount** `integer`: No description
  - **readCount** `integer`: No description
  - **failedCount** `integer`: No description
  - **createdAt** `string` (date-time): No description
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/broadcasts

**Create broadcast draft**

Create a broadcast in draft status. Add recipients and then send or schedule it.

### Request Body

- **profileId** (required) `string`: No description
- **accountId** (required) `string`: No description
- **platform** (required) `string`: No description - one of: instagram, facebook, telegram, twitter, bluesky, reddit, whatsapp
- **name** (required) `string`: No description
- **description** `string`: No description
- **message** `object`: No description
- **template** `object`: WhatsApp template (required when platform is whatsapp)
- **segmentFilters** `object`: No description

### Responses

#### 200: Broadcast created

**Response Body:**

- **success** `boolean`: No description
- **broadcast** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **status** `string`: No description
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Delete broadcast API Reference

Permanently delete a broadcast. Only drafts can be deleted.

## GET /v1/broadcasts/{broadcastId}

**Get broadcast details**

Returns a broadcast with its full configuration and delivery stats.

### Parameters

- **broadcastId** (required) in path: No description

### Responses

#### 200: Broadcast details with stats

**Response Body:**

- **success** `boolean`: No description
- **broadcast** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **message** `object`: 
    - **text** `string`: No description
  - **template** `object`: 
    - **name** `string`: No description
    - **language** `string`: No description
  - **segmentFilters** `object`: 
    - **tags** `array[string]`: 
  - **status** `string`: No description - one of: draft, scheduled, sending, completed, failed, cancelled
  - **scheduledAt** `string` (date-time): No description
  - **startedAt** `string` (date-time): No description
  - **completedAt** `string` (date-time): No description
  - **recipientCount** `integer`: No description
  - **sentCount** `integer`: No description
  - **deliveredCount** `integer`: No description
  - **readCount** `integer`: No description
  - **failedCount** `integer`: No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/broadcasts/{broadcastId}

**Update broadcast**

Update a broadcast's name, message, template, or segment filters. Only draft broadcasts can be updated.

### Parameters

- **broadcastId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **description** `string`: No description
- **message** `object`: Generic message payload (used for non-WhatsApp platforms).
- **template** `object`: WhatsApp template payload (used when platform is `whatsapp`).
- **segmentFilters** `object`: Recipient segment filters (tags, channels, subscription state).

### Responses

#### 200: Broadcast updated

**Response Body:**

- **success** `boolean`: No description
- **broadcast** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **status** `string`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/broadcasts/{broadcastId}

**Delete broadcast**

Permanently delete a broadcast. Only drafts can be deleted.

### Parameters

- **broadcastId** (required) in path: No description

### Responses

#### 200: Broadcast deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Get broadcast details API Reference

Returns a broadcast with its full configuration and delivery stats.

## GET /v1/broadcasts/{broadcastId}

**Get broadcast details**

Returns a broadcast with its full configuration and delivery stats.

### Parameters

- **broadcastId** (required) in path: No description

### Responses

#### 200: Broadcast details with stats

**Response Body:**

- **success** `boolean`: No description
- **broadcast** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **message** `object`: 
    - **text** `string`: No description
  - **template** `object`: 
    - **name** `string`: No description
    - **language** `string`: No description
  - **segmentFilters** `object`: 
    - **tags** `array[string]`: 
  - **status** `string`: No description - one of: draft, scheduled, sending, completed, failed, cancelled
  - **scheduledAt** `string` (date-time): No description
  - **startedAt** `string` (date-time): No description
  - **completedAt** `string` (date-time): No description
  - **recipientCount** `integer`: No description
  - **sentCount** `integer`: No description
  - **deliveredCount** `integer`: No description
  - **readCount** `integer`: No description
  - **failedCount** `integer`: No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/broadcasts/{broadcastId}

**Update broadcast**

Update a broadcast's name, message, template, or segment filters. Only draft broadcasts can be updated.

### Parameters

- **broadcastId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **description** `string`: No description
- **message** `object`: Generic message payload (used for non-WhatsApp platforms).
- **template** `object`: WhatsApp template payload (used when platform is `whatsapp`).
- **segmentFilters** `object`: Recipient segment filters (tags, channels, subscription state).

### Responses

#### 200: Broadcast updated

**Response Body:**

- **success** `boolean`: No description
- **broadcast** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **status** `string`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/broadcasts/{broadcastId}

**Delete broadcast**

Permanently delete a broadcast. Only drafts can be deleted.

### Parameters

- **broadcastId** (required) in path: No description

### Responses

#### 200: Broadcast deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List broadcast recipients API Reference

Returns recipients for a broadcast with individual delivery status. Filter by status.

## GET /v1/broadcasts/{broadcastId}/recipients

**List broadcast recipients**

Returns recipients for a broadcast with individual delivery status. Filter by status.

### Parameters

- **broadcastId** (required) in path: No description
- **status** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Recipients list with delivery status

**Response Body:**

- **success** `boolean`: No description
- **recipients** `array[object]`: 
  - **id** `string`: No description
  - **contactId** `string`: No description
  - **channelId** `string`: No description
  - **platformIdentifier** `string`: No description
  - **contactName** `string`: No description
  - **status** `string`: No description - one of: pending, sent, delivered, read, failed
  - **messageId** `string`: No description
  - **error** `string`: No description
  - **errorCode** `integer`: Meta WhatsApp error code (e.g. 131049 for antispam, 131021 for invalid phone, 131026 for re-engagement required). Only populated for status=failed.
  - **errorExplanation** `string`: 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.
  - **sentAt** `string` (date-time): No description
  - **deliveredAt** `string` (date-time): No description
  - **readAt** `string` (date-time): No description
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## POST /v1/broadcasts/{broadcastId}/recipients

**Add recipients to a broadcast**

Add recipients by contact IDs, raw phone numbers, or from the broadcast's segment filters.

### Parameters

- **broadcastId** (required) in path: No description

### Request Body

- **contactIds** `array`: Specific contact IDs to add
- **phones** `array`: Raw phone numbers (auto-creates contacts). Useful for WhatsApp/Telegram manual entry
- **useSegment** `boolean`: Auto-populate from broadcast segment filters

### Responses

#### 200: Recipients added

**Response Body:**

- **success** `boolean`: No description
- **added** `integer`: Number of recipients successfully added
- **skipped** `integer`: Number skipped (duplicates or missing channels)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List broadcasts API Reference

Returns broadcasts with delivery stats. Filter by status, platform, or profile.

## GET /v1/broadcasts

**List broadcasts**

Returns broadcasts with delivery stats. Filter by status, platform, or profile.

### Parameters

- **profileId** (optional) in query: Filter by profile. Omit to list across all profiles
- **status** (optional) in query: No description
- **platform** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Broadcasts list

**Response Body:**

- **success** `boolean`: No description
- **broadcasts** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **accountName** `string`: Display name of the sending account
  - **status** `string`: No description - one of: draft, scheduled, sending, completed, failed, cancelled
  - **messagePreview** `string`: Template name or message text snippet
  - **scheduledAt** `string` (date-time): No description
  - **startedAt** `string` (date-time): No description
  - **completedAt** `string` (date-time): No description
  - **recipientCount** `integer`: No description
  - **sentCount** `integer`: No description
  - **deliveredCount** `integer`: No description
  - **readCount** `integer`: No description
  - **failedCount** `integer`: No description
  - **createdAt** `string` (date-time): No description
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/broadcasts

**Create broadcast draft**

Create a broadcast in draft status. Add recipients and then send or schedule it.

### Request Body

- **profileId** (required) `string`: No description
- **accountId** (required) `string`: No description
- **platform** (required) `string`: No description - one of: instagram, facebook, telegram, twitter, bluesky, reddit, whatsapp
- **name** (required) `string`: No description
- **description** `string`: No description
- **message** `object`: No description
- **template** `object`: WhatsApp template (required when platform is whatsapp)
- **segmentFilters** `object`: No description

### Responses

#### 200: Broadcast created

**Response Body:**

- **success** `boolean`: No description
- **broadcast** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **status** `string`: No description
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Schedule broadcast for later API Reference

Schedule a draft broadcast to be sent at a future date and time.

## POST /v1/broadcasts/{broadcastId}/schedule

**Schedule broadcast for later**

Schedule a draft broadcast to be sent at a future date and time.

### Parameters

- **broadcastId** (required) in path: No description

### Request Body

- **scheduledAt** (required) `string`: No description

### Responses

#### 200: Broadcast scheduled

**Response Body:**

- **success** `boolean`: No description
- **broadcast** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description
  - **scheduledAt** `string` (date-time): No description

#### 400: Invalid date or status

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Send broadcast now API Reference

Immediately start sending a draft broadcast to its recipients.

## POST /v1/broadcasts/{broadcastId}/send

**Send broadcast now**

Immediately start sending a draft broadcast to its recipients.

### Parameters

- **broadcastId** (required) in path: No description

### Responses

#### 200: Broadcast sending started

**Response Body:**

- **success** `boolean`: No description
- **status** `string`: Current broadcast status after processing first batch - one of: sending, completed, failed
- **sent** `integer`: Recipients sent in this batch
- **failed** `integer`: Recipients failed in this batch
- **recipientCount** `integer`: Total recipient count

#### 400: Invalid status or no recipients

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Update broadcast API Reference

Update a broadcast's name, message, template, or segment filters. Only draft broadcasts can be updated.

## GET /v1/broadcasts/{broadcastId}

**Get broadcast details**

Returns a broadcast with its full configuration and delivery stats.

### Parameters

- **broadcastId** (required) in path: No description

### Responses

#### 200: Broadcast details with stats

**Response Body:**

- **success** `boolean`: No description
- **broadcast** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **message** `object`: 
    - **text** `string`: No description
  - **template** `object`: 
    - **name** `string`: No description
    - **language** `string`: No description
  - **segmentFilters** `object`: 
    - **tags** `array[string]`: 
  - **status** `string`: No description - one of: draft, scheduled, sending, completed, failed, cancelled
  - **scheduledAt** `string` (date-time): No description
  - **startedAt** `string` (date-time): No description
  - **completedAt** `string` (date-time): No description
  - **recipientCount** `integer`: No description
  - **sentCount** `integer`: No description
  - **deliveredCount** `integer`: No description
  - **readCount** `integer`: No description
  - **failedCount** `integer`: No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/broadcasts/{broadcastId}

**Update broadcast**

Update a broadcast's name, message, template, or segment filters. Only draft broadcasts can be updated.

### Parameters

- **broadcastId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **description** `string`: No description
- **message** `object`: Generic message payload (used for non-WhatsApp platforms).
- **template** `object`: WhatsApp template payload (used when platform is `whatsapp`).
- **segmentFilters** `object`: Recipient segment filters (tags, channels, subscription state).

### Responses

#### 200: Broadcast updated

**Response Body:**

- **success** `boolean`: No description
- **broadcast** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **status** `string`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/broadcasts/{broadcastId}

**Delete broadcast**

Permanently delete a broadcast. Only drafts can be deleted.

### Parameters

- **broadcastId** (required) in path: No description

### Responses

#### 200: Broadcast deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Create comment-to-DM automation API Reference

Create a keyword-triggered DM automation on an Instagram or Facebook account.
When someone comments a matching keyword (or, with `trigger: story_reply`, replies
to your Instagram story with one), they automatically receive a DM.

Triggers (`trigger`):
  * `comment` (default): fires on keyword comments on a post or reel.
  * `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.

Targeting (comment trigger):
  * Per-post: set `platformPostId` to scope to one specific post (only one active
    per-post automation is allowed per post).
  * Account-wide ("any post"): omit `platformPostId` (and `postId`). The automation
    evaluates every comment on every post on the account. You 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.

Links 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.


## GET /v1/comment-automations

**List comment-to-DM automations**

List all comment-to-DM automations for a profile. Returns automations with their stats.

### Parameters

- **profileId** (optional) in query: Filter by profile. Omit to list across all profiles

### Responses

#### 200: Automations list

**Response Body:**

- **success** `boolean`: No description
- **automations** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **platform** `string`: No description - one of: instagram, facebook
  - **trigger** `string`: No description - one of: comment, story_reply
  - **accountId** `string`: No description
  - **platformPostId** `string`: No description
  - **postTitle** `string`: No description
  - **keywords** `array[string]`: 
  - **matchMode** `string`: No description - one of: exact, contains
  - **dmMessage** `string`: No description
  - **buttons** `array[DmButton]`: Inline DM buttons (up to 3). Omitted when none are set.
  - **commentReply** `string`: No description
  - **linkTracking** `boolean`: Whether link buttons in the DM are wrapped in a tracked redirect to count clicks.
  - **clickTag** `string`: Tag applied to a contact when they click a tracked link.
  - **isActive** `boolean`: No description
  - **stats** `object`: 
    - **triggered** `integer`: No description
    - **dmsSent** `integer`: No description
    - **dmsFailed** `integer`: No description
    - **uniqueContacts** `integer`: No description
    - **trackedSends** `integer`: DMs sent with a trackable (wrapped) link. CTR denominator: divide clicks by this, not dmsSent. Lags dmsSent for campaigns that predate click tracking.
    - **linkClicks** `integer`: Total clicks on tracked links (bots/prefetch excluded).
    - **uniqueClicks** `integer`: Distinct people who clicked a tracked link.
    - **delivered** `integer`: DMs confirmed delivered (Messenger; IG emits no delivery receipt).
    - **read** `integer`: DMs confirmed read (IG messaging_seen / Messenger message_reads).
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/comment-automations

**Create comment-to-DM automation**

Create a keyword-triggered DM automation on an Instagram or Facebook account.
When someone comments a matching keyword (or, with `trigger: story_reply`, replies
to your Instagram story with one), they automatically receive a DM.

Triggers (`trigger`):
  * `comment` (default): fires on keyword comments on a post or reel.
  * `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.

Targeting (comment trigger):
  * Per-post: set `platformPostId` to scope to one specific post (only one active
    per-post automation is allowed per post).
  * Account-wide ("any post"): omit `platformPostId` (and `postId`). The automation
    evaluates every comment on every post on the account. You 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.

Links 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.


### Request Body

- **profileId** (required) `string`: No description
- **accountId** (required) `string`: Instagram or Facebook account ID
- **trigger** `string`: What fires the automation. 'comment' (keyword comment on a post) or 'story_reply' (keyword reply to an Instagram story). For 'story_reply', platformPostId is the story media id (omit for any story). - one of: comment, story_reply
- **platformPostId** `string`: Platform media/post ID (or story media id when trigger=story_reply). Omit for an account-wide (any-post / any-story) automation.
- **postId** `string`: Zernio post ID. Required only when also targeting a specific post via platformPostId.
- **postTitle** `string`: Post content snippet for display
- **name** (required) `string`: Automation label
- **keywords** `array`: Trigger keywords (empty = any comment triggers)
- **matchMode** `string`: No description - one of: exact, contains
- **dmMessage** (required) `string`: DM text to send to commenter. Max 640 chars when buttons are set, otherwise ~1000.
- **buttons** `array`: Optional inline DM buttons (1-3). Phone buttons are Facebook-only. Omit or pass [] for a plain-text DM.
- **commentReply** `string`: Optional public reply to the comment
- **linkTracking** `boolean`: 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** `string`: Optional tag applied to a contact when they click a tracked link (requires linkTracking). Lets you segment clickers for broadcasts/sequences.

### Responses

#### 200: Automation created

**Response Body:**

- **success** `boolean`: No description
- **automation** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **platform** `string`: No description
  - **trigger** `string`: No description - one of: comment, story_reply
  - **platformPostId** `string`: No description
  - **keywords** `array[string]`: 
  - **matchMode** `string`: No description - one of: exact, contains
  - **dmMessage** `string`: No description
  - **buttons** `array[DmButton]`: Inline DM buttons (up to 3). Omitted when none are set.
  - **commentReply** `string`: No description
  - **linkTracking** `boolean`: No description
  - **clickTag** `string`: No description
  - **isActive** `boolean`: No description
  - **stats** `object`: 
    - **totalTriggered** `integer`: No description
    - **totalSent** `integer`: No description
    - **totalFailed** `integer`: No description
  - **createdAt** `string` (date-time): No description

#### 400: Validation error

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 409: Active per-post automation already exists for this platformPostId. Does not apply to account-wide automations.

---


# Related Schema Definitions

## DmButton

A single inline button rendered inside an auto-DM via Meta's button_template.
Up to 3 buttons per automation. `url` and `postback` work on Instagram and
Facebook; `phone` is Facebook-only. When buttons are set, `dmMessage` becomes
the button_template text and must be 640 characters or less.


### Properties

- **type** (required) `string`: No description - one of: url, postback, phone
- **title** (required) `string`: Button label (20 chars max) (max: 20)
- **url** `string`: Target URL (required when type is url)
- **payload** `string`: Postback payload delivered via the messaging_postbacks webhook (required when type is postback)
- **phone** `string`: Phone number, e.g. +14155551234 (required when type is phone; Facebook only)

---

# Delete automation API Reference

Permanently delete an automation and all its trigger logs.

## GET /v1/comment-automations/{automationId}

**Get automation details**

Returns an automation with its configuration, stats, and recent trigger logs.

### Parameters

- **automationId** (required) in path: No description

### Responses

#### 200: Automation details with stats and recent trigger logs

**Response Body:**

- **success** `boolean`: No description
- **automation** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **platform** `string`: No description
  - **trigger** `string`: No description - one of: comment, story_reply
  - **accountId** `string`: No description
  - **platformPostId** `string`: No description
  - **postId** `string`: No description
  - **postTitle** `string`: No description
  - **keywords** `array[string]`: 
  - **matchMode** `string`: No description - one of: exact, contains
  - **dmMessage** `string`: No description
  - **buttons** `array[DmButton]`: Inline DM buttons (up to 3). Omitted when none are set.
  - **commentReply** `string`: No description
  - **linkTracking** `boolean`: No description
  - **clickTag** `string`: No description
  - **isActive** `boolean`: No description
  - **stats** `object`: 
    - **totalTriggered** `integer`: No description
    - **totalSent** `integer`: No description
    - **totalFailed** `integer`: No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description
- **logs** `array[object]`: 
  - **id** `string`: No description
  - **commentId** `string`: No description
  - **commenterId** `string`: No description
  - **commenterName** `string`: No description
  - **commentText** `string`: No description
  - **status** `string`: DM outcome - one of: sent, failed, skipped
  - **error** `string`: DM error message if status is failed
  - **commentReplyStatus** `string`: Outcome of the optional public reply on the triggering comment. 'skipped' if no commentReply was configured or if the DM failed (the public reply is not attempted in that case). - one of: sent, failed, skipped
  - **commentReplyError** `string`: Public-reply error message if commentReplyStatus is failed
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/comment-automations/{automationId}

**Update automation settings**

Update an automation's keywords, DM message, inline buttons, comment reply, or active status.
Pass `buttons: []` to clear all buttons. When `buttons` is non-empty, `dmMessage` (the new
one if you're changing it, otherwise the stored one) must be 640 characters or less.


### Parameters

- **automationId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **keywords** `array`: No description
- **matchMode** `string`: No description - one of: exact, contains
- **dmMessage** `string`: No description
- **buttons** `array`: Inline DM buttons (1-3). Pass [] to clear all buttons.
- **commentReply** `string`: No description
- **linkTracking** `boolean`: Wrap link buttons in a tracked redirect to count clicks. Pass false to send links untouched.
- **clickTag** `string`: Tag applied to a contact when they click a tracked link (requires linkTracking). Empty string clears it.
- **isActive** `boolean`: No description

### Responses

#### 200: Automation updated

**Response Body:**

- **success** `boolean`: No description
- **automation** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **keywords** `array[string]`: 
  - **matchMode** `string`: No description - one of: exact, contains
  - **dmMessage** `string`: No description
  - **buttons** `array[DmButton]`: Inline DM buttons (up to 3). Omitted when none are set.
  - **commentReply** `string`: No description
  - **isActive** `boolean`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/comment-automations/{automationId}

**Delete automation**

Permanently delete an automation and all its trigger logs.

### Parameters

- **automationId** (required) in path: No description

### Responses

#### 200: Automation deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## DmButton

A single inline button rendered inside an auto-DM via Meta's button_template.
Up to 3 buttons per automation. `url` and `postback` work on Instagram and
Facebook; `phone` is Facebook-only. When buttons are set, `dmMessage` becomes
the button_template text and must be 640 characters or less.


### Properties

- **type** (required) `string`: No description - one of: url, postback, phone
- **title** (required) `string`: Button label (20 chars max) (max: 20)
- **url** `string`: Target URL (required when type is url)
- **payload** `string`: Postback payload delivered via the messaging_postbacks webhook (required when type is postback)
- **phone** `string`: Phone number, e.g. +14155551234 (required when type is phone; Facebook only)

---

# Get automation details API Reference

Returns an automation with its configuration, stats, and recent trigger logs.

## GET /v1/comment-automations/{automationId}

**Get automation details**

Returns an automation with its configuration, stats, and recent trigger logs.

### Parameters

- **automationId** (required) in path: No description

### Responses

#### 200: Automation details with stats and recent trigger logs

**Response Body:**

- **success** `boolean`: No description
- **automation** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **platform** `string`: No description
  - **trigger** `string`: No description - one of: comment, story_reply
  - **accountId** `string`: No description
  - **platformPostId** `string`: No description
  - **postId** `string`: No description
  - **postTitle** `string`: No description
  - **keywords** `array[string]`: 
  - **matchMode** `string`: No description - one of: exact, contains
  - **dmMessage** `string`: No description
  - **buttons** `array[DmButton]`: Inline DM buttons (up to 3). Omitted when none are set.
  - **commentReply** `string`: No description
  - **linkTracking** `boolean`: No description
  - **clickTag** `string`: No description
  - **isActive** `boolean`: No description
  - **stats** `object`: 
    - **totalTriggered** `integer`: No description
    - **totalSent** `integer`: No description
    - **totalFailed** `integer`: No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description
- **logs** `array[object]`: 
  - **id** `string`: No description
  - **commentId** `string`: No description
  - **commenterId** `string`: No description
  - **commenterName** `string`: No description
  - **commentText** `string`: No description
  - **status** `string`: DM outcome - one of: sent, failed, skipped
  - **error** `string`: DM error message if status is failed
  - **commentReplyStatus** `string`: Outcome of the optional public reply on the triggering comment. 'skipped' if no commentReply was configured or if the DM failed (the public reply is not attempted in that case). - one of: sent, failed, skipped
  - **commentReplyError** `string`: Public-reply error message if commentReplyStatus is failed
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/comment-automations/{automationId}

**Update automation settings**

Update an automation's keywords, DM message, inline buttons, comment reply, or active status.
Pass `buttons: []` to clear all buttons. When `buttons` is non-empty, `dmMessage` (the new
one if you're changing it, otherwise the stored one) must be 640 characters or less.


### Parameters

- **automationId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **keywords** `array`: No description
- **matchMode** `string`: No description - one of: exact, contains
- **dmMessage** `string`: No description
- **buttons** `array`: Inline DM buttons (1-3). Pass [] to clear all buttons.
- **commentReply** `string`: No description
- **linkTracking** `boolean`: Wrap link buttons in a tracked redirect to count clicks. Pass false to send links untouched.
- **clickTag** `string`: Tag applied to a contact when they click a tracked link (requires linkTracking). Empty string clears it.
- **isActive** `boolean`: No description

### Responses

#### 200: Automation updated

**Response Body:**

- **success** `boolean`: No description
- **automation** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **keywords** `array[string]`: 
  - **matchMode** `string`: No description - one of: exact, contains
  - **dmMessage** `string`: No description
  - **buttons** `array[DmButton]`: Inline DM buttons (up to 3). Omitted when none are set.
  - **commentReply** `string`: No description
  - **isActive** `boolean`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/comment-automations/{automationId}

**Delete automation**

Permanently delete an automation and all its trigger logs.

### Parameters

- **automationId** (required) in path: No description

### Responses

#### 200: Automation deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## DmButton

A single inline button rendered inside an auto-DM via Meta's button_template.
Up to 3 buttons per automation. `url` and `postback` work on Instagram and
Facebook; `phone` is Facebook-only. When buttons are set, `dmMessage` becomes
the button_template text and must be 640 characters or less.


### Properties

- **type** (required) `string`: No description - one of: url, postback, phone
- **title** (required) `string`: Button label (20 chars max) (max: 20)
- **url** `string`: Target URL (required when type is url)
- **payload** `string`: Postback payload delivered via the messaging_postbacks webhook (required when type is postback)
- **phone** `string`: Phone number, e.g. +14155551234 (required when type is phone; Facebook only)

---

# List automation logs API Reference

Paginated list of every comment that triggered this automation, with send status and commenter info.

## GET /v1/comment-automations/{automationId}/logs

**List automation logs**

Paginated list of every comment that triggered this automation, with send status and commenter info.

### Parameters

- **automationId** (required) in path: No description
- **status** (optional) in query: Filter by result status
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Trigger logs with pagination

**Response Body:**

- **success** `boolean`: No description
- **logs** `array[object]`: 
  - **id** `string`: No description
  - **commentId** `string`: No description
  - **commenterId** `string`: No description
  - **commenterName** `string`: No description
  - **commentText** `string`: No description
  - **status** `string`: DM outcome - one of: sent, failed, skipped
  - **error** `string`: DM error message if status is failed
  - **commentReplyStatus** `string`: Outcome of the optional public reply on the triggering comment. 'skipped' if no commentReply was configured or if the DM failed (the public reply is not attempted in that case). - one of: sent, failed, skipped
  - **commentReplyError** `string`: Public-reply error message if commentReplyStatus is failed
  - **createdAt** `string` (date-time): No description
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List comment-to-DM automations API Reference

List all comment-to-DM automations for a profile. Returns automations with their stats.

## GET /v1/comment-automations

**List comment-to-DM automations**

List all comment-to-DM automations for a profile. Returns automations with their stats.

### Parameters

- **profileId** (optional) in query: Filter by profile. Omit to list across all profiles

### Responses

#### 200: Automations list

**Response Body:**

- **success** `boolean`: No description
- **automations** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **platform** `string`: No description - one of: instagram, facebook
  - **trigger** `string`: No description - one of: comment, story_reply
  - **accountId** `string`: No description
  - **platformPostId** `string`: No description
  - **postTitle** `string`: No description
  - **keywords** `array[string]`: 
  - **matchMode** `string`: No description - one of: exact, contains
  - **dmMessage** `string`: No description
  - **buttons** `array[DmButton]`: Inline DM buttons (up to 3). Omitted when none are set.
  - **commentReply** `string`: No description
  - **linkTracking** `boolean`: Whether link buttons in the DM are wrapped in a tracked redirect to count clicks.
  - **clickTag** `string`: Tag applied to a contact when they click a tracked link.
  - **isActive** `boolean`: No description
  - **stats** `object`: 
    - **triggered** `integer`: No description
    - **dmsSent** `integer`: No description
    - **dmsFailed** `integer`: No description
    - **uniqueContacts** `integer`: No description
    - **trackedSends** `integer`: DMs sent with a trackable (wrapped) link. CTR denominator: divide clicks by this, not dmsSent. Lags dmsSent for campaigns that predate click tracking.
    - **linkClicks** `integer`: Total clicks on tracked links (bots/prefetch excluded).
    - **uniqueClicks** `integer`: Distinct people who clicked a tracked link.
    - **delivered** `integer`: DMs confirmed delivered (Messenger; IG emits no delivery receipt).
    - **read** `integer`: DMs confirmed read (IG messaging_seen / Messenger message_reads).
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/comment-automations

**Create comment-to-DM automation**

Create a keyword-triggered DM automation on an Instagram or Facebook account.
When someone comments a matching keyword (or, with `trigger: story_reply`, replies
to your Instagram story with one), they automatically receive a DM.

Triggers (`trigger`):
  * `comment` (default): fires on keyword comments on a post or reel.
  * `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.

Targeting (comment trigger):
  * Per-post: set `platformPostId` to scope to one specific post (only one active
    per-post automation is allowed per post).
  * Account-wide ("any post"): omit `platformPostId` (and `postId`). The automation
    evaluates every comment on every post on the account. You 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.

Links 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.


### Request Body

- **profileId** (required) `string`: No description
- **accountId** (required) `string`: Instagram or Facebook account ID
- **trigger** `string`: What fires the automation. 'comment' (keyword comment on a post) or 'story_reply' (keyword reply to an Instagram story). For 'story_reply', platformPostId is the story media id (omit for any story). - one of: comment, story_reply
- **platformPostId** `string`: Platform media/post ID (or story media id when trigger=story_reply). Omit for an account-wide (any-post / any-story) automation.
- **postId** `string`: Zernio post ID. Required only when also targeting a specific post via platformPostId.
- **postTitle** `string`: Post content snippet for display
- **name** (required) `string`: Automation label
- **keywords** `array`: Trigger keywords (empty = any comment triggers)
- **matchMode** `string`: No description - one of: exact, contains
- **dmMessage** (required) `string`: DM text to send to commenter. Max 640 chars when buttons are set, otherwise ~1000.
- **buttons** `array`: Optional inline DM buttons (1-3). Phone buttons are Facebook-only. Omit or pass [] for a plain-text DM.
- **commentReply** `string`: Optional public reply to the comment
- **linkTracking** `boolean`: 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** `string`: Optional tag applied to a contact when they click a tracked link (requires linkTracking). Lets you segment clickers for broadcasts/sequences.

### Responses

#### 200: Automation created

**Response Body:**

- **success** `boolean`: No description
- **automation** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **platform** `string`: No description
  - **trigger** `string`: No description - one of: comment, story_reply
  - **platformPostId** `string`: No description
  - **keywords** `array[string]`: 
  - **matchMode** `string`: No description - one of: exact, contains
  - **dmMessage** `string`: No description
  - **buttons** `array[DmButton]`: Inline DM buttons (up to 3). Omitted when none are set.
  - **commentReply** `string`: No description
  - **linkTracking** `boolean`: No description
  - **clickTag** `string`: No description
  - **isActive** `boolean`: No description
  - **stats** `object`: 
    - **totalTriggered** `integer`: No description
    - **totalSent** `integer`: No description
    - **totalFailed** `integer`: No description
  - **createdAt** `string` (date-time): No description

#### 400: Validation error

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 409: Active per-post automation already exists for this platformPostId. Does not apply to account-wide automations.

---


# Related Schema Definitions

## DmButton

A single inline button rendered inside an auto-DM via Meta's button_template.
Up to 3 buttons per automation. `url` and `postback` work on Instagram and
Facebook; `phone` is Facebook-only. When buttons are set, `dmMessage` becomes
the button_template text and must be 640 characters or less.


### Properties

- **type** (required) `string`: No description - one of: url, postback, phone
- **title** (required) `string`: Button label (20 chars max) (max: 20)
- **url** `string`: Target URL (required when type is url)
- **payload** `string`: Postback payload delivered via the messaging_postbacks webhook (required when type is postback)
- **phone** `string`: Phone number, e.g. +14155551234 (required when type is phone; Facebook only)

---

# Update automation settings API Reference

Update an automation's keywords, DM message, inline buttons, comment reply, or active status.
Pass `buttons: []` to clear all buttons. When `buttons` is non-empty, `dmMessage` (the new
one if you're changing it, otherwise the stored one) must be 640 characters or less.


## GET /v1/comment-automations/{automationId}

**Get automation details**

Returns an automation with its configuration, stats, and recent trigger logs.

### Parameters

- **automationId** (required) in path: No description

### Responses

#### 200: Automation details with stats and recent trigger logs

**Response Body:**

- **success** `boolean`: No description
- **automation** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **platform** `string`: No description
  - **trigger** `string`: No description - one of: comment, story_reply
  - **accountId** `string`: No description
  - **platformPostId** `string`: No description
  - **postId** `string`: No description
  - **postTitle** `string`: No description
  - **keywords** `array[string]`: 
  - **matchMode** `string`: No description - one of: exact, contains
  - **dmMessage** `string`: No description
  - **buttons** `array[DmButton]`: Inline DM buttons (up to 3). Omitted when none are set.
  - **commentReply** `string`: No description
  - **linkTracking** `boolean`: No description
  - **clickTag** `string`: No description
  - **isActive** `boolean`: No description
  - **stats** `object`: 
    - **totalTriggered** `integer`: No description
    - **totalSent** `integer`: No description
    - **totalFailed** `integer`: No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description
- **logs** `array[object]`: 
  - **id** `string`: No description
  - **commentId** `string`: No description
  - **commenterId** `string`: No description
  - **commenterName** `string`: No description
  - **commentText** `string`: No description
  - **status** `string`: DM outcome - one of: sent, failed, skipped
  - **error** `string`: DM error message if status is failed
  - **commentReplyStatus** `string`: Outcome of the optional public reply on the triggering comment. 'skipped' if no commentReply was configured or if the DM failed (the public reply is not attempted in that case). - one of: sent, failed, skipped
  - **commentReplyError** `string`: Public-reply error message if commentReplyStatus is failed
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/comment-automations/{automationId}

**Update automation settings**

Update an automation's keywords, DM message, inline buttons, comment reply, or active status.
Pass `buttons: []` to clear all buttons. When `buttons` is non-empty, `dmMessage` (the new
one if you're changing it, otherwise the stored one) must be 640 characters or less.


### Parameters

- **automationId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **keywords** `array`: No description
- **matchMode** `string`: No description - one of: exact, contains
- **dmMessage** `string`: No description
- **buttons** `array`: Inline DM buttons (1-3). Pass [] to clear all buttons.
- **commentReply** `string`: No description
- **linkTracking** `boolean`: Wrap link buttons in a tracked redirect to count clicks. Pass false to send links untouched.
- **clickTag** `string`: Tag applied to a contact when they click a tracked link (requires linkTracking). Empty string clears it.
- **isActive** `boolean`: No description

### Responses

#### 200: Automation updated

**Response Body:**

- **success** `boolean`: No description
- **automation** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **keywords** `array[string]`: 
  - **matchMode** `string`: No description - one of: exact, contains
  - **dmMessage** `string`: No description
  - **buttons** `array[DmButton]`: Inline DM buttons (up to 3). Omitted when none are set.
  - **commentReply** `string`: No description
  - **isActive** `boolean`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/comment-automations/{automationId}

**Delete automation**

Permanently delete an automation and all its trigger logs.

### Parameters

- **automationId** (required) in path: No description

### Responses

#### 200: Automation deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## DmButton

A single inline button rendered inside an auto-DM via Meta's button_template.
Up to 3 buttons per automation. `url` and `postback` work on Instagram and
Facebook; `phone` is Facebook-only. When buttons are set, `dmMessage` becomes
the button_template text and must be 640 characters or less.


### Properties

- **type** (required) `string`: No description - one of: url, postback, phone
- **title** (required) `string`: Button label (20 chars max) (max: 20)
- **url** `string`: Target URL (required when type is url)
- **payload** `string`: Postback payload delivered via the messaging_postbacks webhook (required when type is postback)
- **phone** `string`: Phone number, e.g. +14155551234 (required when type is phone; Facebook only)

---

# Delete comment API Reference

Delete a comment on a post. Supported by Facebook, Instagram, Bluesky, Reddit, YouTube, and LinkedIn.
Requires accountId and commentId query parameters.


## GET /v1/inbox/comments/{postId}

**Get post comments**

Fetch comments for a specific post. Requires accountId query parameter.

### Parameters

- **postId** (required) in path: Zernio post ID or platform-specific post ID. Zernio IDs are auto-resolved. LinkedIn third-party posts accept full activity URN or numeric ID.
- **accountId** (required) in query: No description
- **subreddit** (optional) in query: (Reddit only) Subreddit name
- **limit** (optional) in query: Maximum number of comments to return
- **cursor** (optional) in query: Pagination cursor
- **commentId** (optional) in query: (Reddit only) Get replies to a specific comment

### Responses

#### 200: Comments for the post

**Response Body:**

- **status** `string`: No description
- **comments** `array[object]`: 
  - **id** `string`: No description
  - **message** `string`: No description
  - **createdTime** `string` (date-time): No description
  - **from** `object`: 
    - **id** `string`: No description
    - **name** `string`: No description
    - **username** `string`: No description
    - **picture** `string`: No description
    - **isOwner** `boolean`: No description
    - **verifiedType** `string`: X/Twitter verified badge type. Only present for Twitter/X comments. - one of: blue, government, business, none
  - **likeCount** `integer`: No description
  - **replyCount** `integer`: No description
  - **platform** `string`: The platform this comment is from
  - **url** `string`: Direct link to the comment on the platform (if available)
  - **replies** `array[object]`: 
    Type: `object`
  - **canReply** `boolean`: No description
  - **canDelete** `boolean`: No description
  - **canHide** `boolean`: Whether this comment can be hidden (Facebook
  - **canLike** `boolean`: Whether this comment can be liked (Facebook
  - **isHidden** `boolean`: Whether the comment is currently hidden
  - **isLiked** `boolean`: Whether the current user has liked this comment
  - **likeUri** `string`: Bluesky like URI for unliking
  - **cid** `string`: Bluesky content identifier
  - **parentId** `string`: Parent comment ID for nested replies
  - **rootUri** `string`: Bluesky root post URI
  - **rootCid** `string`: Bluesky root post CID
- **post** `object`: (Reddit only) Metadata for the target post, returned alongside the comments in Reddit's
single round-trip. Lets integrators render a preview of the post the user is commenting on
without an additional request. Absent for non-Reddit platforms and when the upstream
response is missing the post listing (deleted post, malformed response).

  - **id** `string`: Reddit post base36 id (e.g. "1tjtj26")
  - **fullname** `string`: Fullname with type prefix (e.g. "t3_1tjtj26")
  - **title** `string`: No description
  - **selftext** `string`: Body text for self-posts (empty for link posts)
  - **author** `string`: Reddit username
  - **subreddit** `string`: Subreddit name
  - **permalink** `string`: Absolute URL to the post on reddit.com
  - **url** `string`: For link posts
  - **score** `integer`: Net upvotes (upvotes minus downvotes)
  - **numComments** `integer`: No description
  - **createdUtc** `integer`: Unix timestamp in seconds
  - **over18** `boolean`: No description
  - **stickied** `boolean`: No description
  - **flairText** `string`: Link flair text if any
  - **isGallery** `boolean`: True if the post is a Reddit gallery (multiple images)
- **pagination** `object`: 
  - **hasMore** `boolean`: No description
  - **cursor** `string`: No description
- **meta** `object`: 
  - **platform** `string`: No description
  - **postId** `string`: No description
  - **accountId** `string`: No description
  - **subreddit** `string`: (Reddit only) Subreddit name
  - **lastUpdated** `string` (date-time): No description
  - **adComments** `object`: (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.
    - **adId** `string`: Internal Zernio ad ID
    - **adCommentsUrl** `string`: Path to fetch the ad's comments (GET /v1/ads/{adId}/comments)

#### 400: Invalid request, or the postId belongs to a Meta ad creative / ad ID rather than an organic post
(code USE_AD_COMMENTS_ENDPOINT — response includes `adId` and `adCommentsUrl`).


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## POST /v1/inbox/comments/{postId}

**Reply to comment**

Post a reply to a post or specific comment. Requires accountId in request body.

### Parameters

- **postId** (required) in path: Zernio post ID or platform-specific post ID. LinkedIn third-party posts accept full activity URN or numeric ID.

### Request Body

- **accountId** (required) `string`: No description
- **message** (required) `string`: No description
- **commentId** `string`: Reply to specific comment (optional)
- **parentCid** `string`: (Bluesky only) Parent content identifier
- **rootUri** `string`: (Bluesky only) Root post URI
- **rootCid** `string`: (Bluesky only) Root post CID

### Responses

#### 200: Reply posted

**Response Body:**

- **success** `boolean`: No description
- **data** `object`: 
  - **commentId** `string`: No description
  - **isReply** `boolean`: No description
  - **cid** `string`: Bluesky CID

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## DELETE /v1/inbox/comments/{postId}

**Delete comment**

Delete a comment on a post. Supported by Facebook, Instagram, Bluesky, Reddit, YouTube, and LinkedIn.
Requires accountId and commentId query parameters.


### Parameters

- **postId** (required) in path: Zernio post ID or platform-specific post ID. LinkedIn third-party posts accept full activity URN or numeric ID.
- **accountId** (required) in query: No description
- **commentId** (required) in query: No description

### Responses

#### 200: Comment deleted

**Response Body:**

- **success** `boolean`: No description
- **data** `object`: 
  - **message** `string`: No description

#### 400: Platform rejected the operation (e.g., comment already deleted, insufficient permissions on the video)

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# Get post comments API Reference

Fetch comments for a specific post. Requires accountId query parameter.

## GET /v1/inbox/comments/{postId}

**Get post comments**

Fetch comments for a specific post. Requires accountId query parameter.

### Parameters

- **postId** (required) in path: Zernio post ID or platform-specific post ID. Zernio IDs are auto-resolved. LinkedIn third-party posts accept full activity URN or numeric ID.
- **accountId** (required) in query: No description
- **subreddit** (optional) in query: (Reddit only) Subreddit name
- **limit** (optional) in query: Maximum number of comments to return
- **cursor** (optional) in query: Pagination cursor
- **commentId** (optional) in query: (Reddit only) Get replies to a specific comment

### Responses

#### 200: Comments for the post

**Response Body:**

- **status** `string`: No description
- **comments** `array[object]`: 
  - **id** `string`: No description
  - **message** `string`: No description
  - **createdTime** `string` (date-time): No description
  - **from** `object`: 
    - **id** `string`: No description
    - **name** `string`: No description
    - **username** `string`: No description
    - **picture** `string`: No description
    - **isOwner** `boolean`: No description
    - **verifiedType** `string`: X/Twitter verified badge type. Only present for Twitter/X comments. - one of: blue, government, business, none
  - **likeCount** `integer`: No description
  - **replyCount** `integer`: No description
  - **platform** `string`: The platform this comment is from
  - **url** `string`: Direct link to the comment on the platform (if available)
  - **replies** `array[object]`: 
    Type: `object`
  - **canReply** `boolean`: No description
  - **canDelete** `boolean`: No description
  - **canHide** `boolean`: Whether this comment can be hidden (Facebook
  - **canLike** `boolean`: Whether this comment can be liked (Facebook
  - **isHidden** `boolean`: Whether the comment is currently hidden
  - **isLiked** `boolean`: Whether the current user has liked this comment
  - **likeUri** `string`: Bluesky like URI for unliking
  - **cid** `string`: Bluesky content identifier
  - **parentId** `string`: Parent comment ID for nested replies
  - **rootUri** `string`: Bluesky root post URI
  - **rootCid** `string`: Bluesky root post CID
- **post** `object`: (Reddit only) Metadata for the target post, returned alongside the comments in Reddit's
single round-trip. Lets integrators render a preview of the post the user is commenting on
without an additional request. Absent for non-Reddit platforms and when the upstream
response is missing the post listing (deleted post, malformed response).

  - **id** `string`: Reddit post base36 id (e.g. "1tjtj26")
  - **fullname** `string`: Fullname with type prefix (e.g. "t3_1tjtj26")
  - **title** `string`: No description
  - **selftext** `string`: Body text for self-posts (empty for link posts)
  - **author** `string`: Reddit username
  - **subreddit** `string`: Subreddit name
  - **permalink** `string`: Absolute URL to the post on reddit.com
  - **url** `string`: For link posts
  - **score** `integer`: Net upvotes (upvotes minus downvotes)
  - **numComments** `integer`: No description
  - **createdUtc** `integer`: Unix timestamp in seconds
  - **over18** `boolean`: No description
  - **stickied** `boolean`: No description
  - **flairText** `string`: Link flair text if any
  - **isGallery** `boolean`: True if the post is a Reddit gallery (multiple images)
- **pagination** `object`: 
  - **hasMore** `boolean`: No description
  - **cursor** `string`: No description
- **meta** `object`: 
  - **platform** `string`: No description
  - **postId** `string`: No description
  - **accountId** `string`: No description
  - **subreddit** `string`: (Reddit only) Subreddit name
  - **lastUpdated** `string` (date-time): No description
  - **adComments** `object`: (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.
    - **adId** `string`: Internal Zernio ad ID
    - **adCommentsUrl** `string`: Path to fetch the ad's comments (GET /v1/ads/{adId}/comments)

#### 400: Invalid request, or the postId belongs to a Meta ad creative / ad ID rather than an organic post
(code USE_AD_COMMENTS_ENDPOINT — response includes `adId` and `adCommentsUrl`).


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## POST /v1/inbox/comments/{postId}

**Reply to comment**

Post a reply to a post or specific comment. Requires accountId in request body.

### Parameters

- **postId** (required) in path: Zernio post ID or platform-specific post ID. LinkedIn third-party posts accept full activity URN or numeric ID.

### Request Body

- **accountId** (required) `string`: No description
- **message** (required) `string`: No description
- **commentId** `string`: Reply to specific comment (optional)
- **parentCid** `string`: (Bluesky only) Parent content identifier
- **rootUri** `string`: (Bluesky only) Root post URI
- **rootCid** `string`: (Bluesky only) Root post CID

### Responses

#### 200: Reply posted

**Response Body:**

- **success** `boolean`: No description
- **data** `object`: 
  - **commentId** `string`: No description
  - **isReply** `boolean`: No description
  - **cid** `string`: Bluesky CID

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## DELETE /v1/inbox/comments/{postId}

**Delete comment**

Delete a comment on a post. Supported by Facebook, Instagram, Bluesky, Reddit, YouTube, and LinkedIn.
Requires accountId and commentId query parameters.


### Parameters

- **postId** (required) in path: Zernio post ID or platform-specific post ID. LinkedIn third-party posts accept full activity URN or numeric ID.
- **accountId** (required) in query: No description
- **commentId** (required) in query: No description

### Responses

#### 200: Comment deleted

**Response Body:**

- **success** `boolean`: No description
- **data** `object`: 
  - **message** `string`: No description

#### 400: Platform rejected the operation (e.g., comment already deleted, insufficient permissions on the video)

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# Hide comment API Reference

Hide a comment on a post. Supported by Facebook, Instagram, Threads, and X/Twitter.
Hidden comments are only visible to the commenter and page admin.
For X/Twitter, the reply must belong to a conversation started by the authenticated user.


## POST /v1/inbox/comments/{postId}/{commentId}/hide

**Hide comment**

Hide a comment on a post. Supported by Facebook, Instagram, Threads, and X/Twitter.
Hidden comments are only visible to the commenter and page admin.
For X/Twitter, the reply must belong to a conversation started by the authenticated user.


### Parameters

- **postId** (required) in path: No description
- **commentId** (required) in path: No description

### Request Body

- **accountId** (required) `string`: The social account ID

### Responses

#### 200: Comment hidden

**Response Body:**

- **status** `string`: No description
- **commentId** `string`: No description
- **hidden** `boolean`: No description
- **platform** `string`: No description

#### 400: Platform does not support hiding comments

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## DELETE /v1/inbox/comments/{postId}/{commentId}/hide

**Unhide comment**

Unhide a previously hidden comment. Supported by Facebook, Instagram, Threads, and X/Twitter.


### Parameters

- **postId** (required) in path: No description
- **commentId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Comment unhidden

**Response Body:**

- **status** `string`: No description
- **commentId** `string`: No description
- **hidden** `boolean`: No description
- **platform** `string`: No description

#### 400: Platform does not support unhiding comments

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# Like comment API Reference

Like or upvote a comment on a post. Supported platforms: Facebook, Twitter/X, Bluesky, Reddit.
For Bluesky, the cid (content identifier) is required in the request body.


## POST /v1/inbox/comments/{postId}/{commentId}/like

**Like comment**

Like or upvote a comment on a post. Supported platforms: Facebook, Twitter/X, Bluesky, Reddit.
For Bluesky, the cid (content identifier) is required in the request body.


### Parameters

- **postId** (required) in path: No description
- **commentId** (required) in path: No description

### Request Body

- **accountId** (required) `string`: The social account ID
- **cid** `string`: (Bluesky only) Content identifier for the comment

### Responses

#### 200: Comment liked

**Response Body:**

- **status** `string`: No description
- **commentId** `string`: No description
- **liked** `boolean`: No description
- **likeUri** `string`: (Bluesky only) URI to use for unliking
- **platform** `string`: No description

#### 400: Platform does not support liking comments

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## DELETE /v1/inbox/comments/{postId}/{commentId}/like

**Unlike comment**

Remove a like from a comment. Supported platforms: Facebook, Twitter/X, Bluesky, Reddit.
For Bluesky, the likeUri query parameter is required.


### Parameters

- **postId** (required) in path: No description
- **commentId** (required) in path: No description
- **accountId** (required) in query: No description
- **likeUri** (optional) in query: (Bluesky only) The like URI returned when liking

### Responses

#### 200: Comment unliked

**Response Body:**

- **status** `string`: No description
- **commentId** `string`: No description
- **liked** `boolean`: No description
- **platform** `string`: No description

#### 400: Platform does not support unliking comments

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# List commented posts API Reference

Returns posts with comment counts from all connected accounts. Aggregates data across multiple accounts.

For users with the Ads add-on (Metronome plans always qualify), the user's Meta ads
(boosted/dark posts) are included too. There's one row per (ad, placement-with-comments):
an ad that runs on both Facebook feed and Instagram feed produces up to two rows (the
Page dark post and the IG media have separate comment threads), each flagged
`isAd: true` with `adId` and `placement` (`id` is `{adId}:{placement}`). Use
`?platform=metaads` to return *only* ad rows; passing `facebook`/`instagram` returns
*organic* posts only (no ads); omitting `platform` returns both. Fetch a row's thread
from GET /v1/ads/{adId}/comments?placement={placement}. Ad 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.


## GET /v1/inbox/comments

**List commented posts**

Returns posts with comment counts from all connected accounts. Aggregates data across multiple accounts.

For users with the Ads add-on (Metronome plans always qualify), the user's Meta ads
(boosted/dark posts) are included too. There's one row per (ad, placement-with-comments):
an ad that runs on both Facebook feed and Instagram feed produces up to two rows (the
Page dark post and the IG media have separate comment threads), each flagged
`isAd: true` with `adId` and `placement` (`id` is `{adId}:{placement}`). Use
`?platform=metaads` to return *only* ad rows; passing `facebook`/`instagram` returns
*organic* posts only (no ads); omitting `platform` returns both. Fetch a row's thread
from GET /v1/ads/{adId}/comments?placement={placement}. Ad 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.


### Parameters

- **profileId** (optional) in query: Filter by profile ID
- **platform** (optional) in query: Filter by platform. `metaads` is a synthetic value meaning the user's ads (boosted/dark posts) only; `facebook`/`instagram` return organic posts only.
- **minComments** (optional) in query: Minimum comment count
- **since** (optional) in query: Posts created after this date
- **sortBy** (optional) in query: Sort field
- **sortOrder** (optional) in query: Sort order
- **limit** (optional) in query: No description
- **cursor** (optional) in query: No description
- **accountId** (optional) in query: Filter by specific social account ID

### Responses

#### 200: Aggregated posts with comments

**Response Body:**

- **data** `array[object]`: 
  - **id** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **accountUsername** `string`: No description
  - **content** `string`: No description
  - **picture** `string`: No description
  - **permalink** `string`: No description
  - **createdTime** `string` (date-time): No description
  - **commentCount** `integer`: No description
  - **likeCount** `integer`: No description
  - **cid** `string`: Bluesky content identifier
  - **subreddit** `string`: Reddit subreddit name
  - **isAd** `boolean`: 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** `string`: Internal Zernio ad id — only on ad rows.
  - **placement** `string`: Which side of the ad this row's comments are on — only on ad rows. - one of: facebook, instagram
- **pagination** `object`: 
  - **hasMore** `boolean`: No description
  - **nextCursor** `string`: No description
- **meta** `object`: 
  - **accountsQueried** `integer`: No description
  - **accountsFailed** `integer`: No description
  - **failedAccounts** `array[object]`: 
    - **accountId** `string`: No description
    - **accountUsername** `string`: No description
    - **platform** `string`: No description
    - **error** `string`: No description
    - **code** `string`: Error code if available
    - **retryAfter** `integer`: Seconds to wait before retry (rate limits)
  - **lastUpdated** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# Reply to comment API Reference

Post a reply to a post or specific comment. Requires accountId in request body.

## GET /v1/inbox/comments/{postId}

**Get post comments**

Fetch comments for a specific post. Requires accountId query parameter.

### Parameters

- **postId** (required) in path: Zernio post ID or platform-specific post ID. Zernio IDs are auto-resolved. LinkedIn third-party posts accept full activity URN or numeric ID.
- **accountId** (required) in query: No description
- **subreddit** (optional) in query: (Reddit only) Subreddit name
- **limit** (optional) in query: Maximum number of comments to return
- **cursor** (optional) in query: Pagination cursor
- **commentId** (optional) in query: (Reddit only) Get replies to a specific comment

### Responses

#### 200: Comments for the post

**Response Body:**

- **status** `string`: No description
- **comments** `array[object]`: 
  - **id** `string`: No description
  - **message** `string`: No description
  - **createdTime** `string` (date-time): No description
  - **from** `object`: 
    - **id** `string`: No description
    - **name** `string`: No description
    - **username** `string`: No description
    - **picture** `string`: No description
    - **isOwner** `boolean`: No description
    - **verifiedType** `string`: X/Twitter verified badge type. Only present for Twitter/X comments. - one of: blue, government, business, none
  - **likeCount** `integer`: No description
  - **replyCount** `integer`: No description
  - **platform** `string`: The platform this comment is from
  - **url** `string`: Direct link to the comment on the platform (if available)
  - **replies** `array[object]`: 
    Type: `object`
  - **canReply** `boolean`: No description
  - **canDelete** `boolean`: No description
  - **canHide** `boolean`: Whether this comment can be hidden (Facebook
  - **canLike** `boolean`: Whether this comment can be liked (Facebook
  - **isHidden** `boolean`: Whether the comment is currently hidden
  - **isLiked** `boolean`: Whether the current user has liked this comment
  - **likeUri** `string`: Bluesky like URI for unliking
  - **cid** `string`: Bluesky content identifier
  - **parentId** `string`: Parent comment ID for nested replies
  - **rootUri** `string`: Bluesky root post URI
  - **rootCid** `string`: Bluesky root post CID
- **post** `object`: (Reddit only) Metadata for the target post, returned alongside the comments in Reddit's
single round-trip. Lets integrators render a preview of the post the user is commenting on
without an additional request. Absent for non-Reddit platforms and when the upstream
response is missing the post listing (deleted post, malformed response).

  - **id** `string`: Reddit post base36 id (e.g. "1tjtj26")
  - **fullname** `string`: Fullname with type prefix (e.g. "t3_1tjtj26")
  - **title** `string`: No description
  - **selftext** `string`: Body text for self-posts (empty for link posts)
  - **author** `string`: Reddit username
  - **subreddit** `string`: Subreddit name
  - **permalink** `string`: Absolute URL to the post on reddit.com
  - **url** `string`: For link posts
  - **score** `integer`: Net upvotes (upvotes minus downvotes)
  - **numComments** `integer`: No description
  - **createdUtc** `integer`: Unix timestamp in seconds
  - **over18** `boolean`: No description
  - **stickied** `boolean`: No description
  - **flairText** `string`: Link flair text if any
  - **isGallery** `boolean`: True if the post is a Reddit gallery (multiple images)
- **pagination** `object`: 
  - **hasMore** `boolean`: No description
  - **cursor** `string`: No description
- **meta** `object`: 
  - **platform** `string`: No description
  - **postId** `string`: No description
  - **accountId** `string`: No description
  - **subreddit** `string`: (Reddit only) Subreddit name
  - **lastUpdated** `string` (date-time): No description
  - **adComments** `object`: (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.
    - **adId** `string`: Internal Zernio ad ID
    - **adCommentsUrl** `string`: Path to fetch the ad's comments (GET /v1/ads/{adId}/comments)

#### 400: Invalid request, or the postId belongs to a Meta ad creative / ad ID rather than an organic post
(code USE_AD_COMMENTS_ENDPOINT — response includes `adId` and `adCommentsUrl`).


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## POST /v1/inbox/comments/{postId}

**Reply to comment**

Post a reply to a post or specific comment. Requires accountId in request body.

### Parameters

- **postId** (required) in path: Zernio post ID or platform-specific post ID. LinkedIn third-party posts accept full activity URN or numeric ID.

### Request Body

- **accountId** (required) `string`: No description
- **message** (required) `string`: No description
- **commentId** `string`: Reply to specific comment (optional)
- **parentCid** `string`: (Bluesky only) Parent content identifier
- **rootUri** `string`: (Bluesky only) Root post URI
- **rootCid** `string`: (Bluesky only) Root post CID

### Responses

#### 200: Reply posted

**Response Body:**

- **success** `boolean`: No description
- **data** `object`: 
  - **commentId** `string`: No description
  - **isReply** `boolean`: No description
  - **cid** `string`: Bluesky CID

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## DELETE /v1/inbox/comments/{postId}

**Delete comment**

Delete a comment on a post. Supported by Facebook, Instagram, Bluesky, Reddit, YouTube, and LinkedIn.
Requires accountId and commentId query parameters.


### Parameters

- **postId** (required) in path: Zernio post ID or platform-specific post ID. LinkedIn third-party posts accept full activity URN or numeric ID.
- **accountId** (required) in query: No description
- **commentId** (required) in query: No description

### Responses

#### 200: Comment deleted

**Response Body:**

- **success** `boolean`: No description
- **data** `object`: 
  - **message** `string`: No description

#### 400: Platform rejected the operation (e.g., comment already deleted, insufficient permissions on the video)

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# Send private reply API Reference

Send a private message to the author of a comment. Supported on Instagram and Facebook only.
One reply per comment, must be sent within 7 days. Optionally attach interactive elements:
`quickReplies` (chips above the keyboard, max 13) or `buttons` (1-3 inline postback/url
buttons rendered in the same bubble via Meta's button_template). Buttons are recommended
for cold reach since chips do not render in the Instagram Message Requests folder.
`quickReplies` and `buttons` are mutually exclusive.


## POST /v1/inbox/comments/{postId}/{commentId}/private-reply

**Send private reply**

Send a private message to the author of a comment. Supported on Instagram and Facebook only.
One reply per comment, must be sent within 7 days. Optionally attach interactive elements:
`quickReplies` (chips above the keyboard, max 13) or `buttons` (1-3 inline postback/url
buttons rendered in the same bubble via Meta's button_template). Buttons are recommended
for cold reach since chips do not render in the Instagram Message Requests folder.
`quickReplies` and `buttons` are mutually exclusive.


### Parameters

- **postId** (required) in path: The media/post ID (Instagram media ID or Facebook post ID)
- **commentId** (required) in path: The comment ID to send a private reply to

### Request Body

- **accountId** (required) `string`: The social account ID (Instagram or Facebook)
- **message** (required) `string`: The message text to send as a private DM
- **quickReplies** `array`: Optional quick-reply chips appended to the message. Visible only in the
Instagram and Messenger apps (not on web). Maximum 13 entries. Mutually
exclusive with `buttons`. Note: chips do NOT render in the Instagram
Message Requests folder where DMs from non-followers land — use `buttons`
instead for cold reach.

- **buttons** `array`: Optional 1-3 inline buttons rendered as part of the same message bubble
via Meta's button_template. Visible in the Instagram Message Requests
folder (unlike quick replies). Mutually exclusive with `quickReplies`.


### Responses

#### 200: Private reply sent successfully

**Response Body:**

- **status** `string`: No description (example: "success")
- **messageId** `string`: The ID of the sent message
- **commentId** `string`: The comment ID that was replied to
- **platform** `string`: No description - one of: instagram, facebook (example: "instagram")

#### 400: Bad request

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description - one of: PLATFORM_LIMITATION

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Account not found

---

---

# Unhide comment API Reference

Unhide a previously hidden comment. Supported by Facebook, Instagram, Threads, and X/Twitter.


## POST /v1/inbox/comments/{postId}/{commentId}/hide

**Hide comment**

Hide a comment on a post. Supported by Facebook, Instagram, Threads, and X/Twitter.
Hidden comments are only visible to the commenter and page admin.
For X/Twitter, the reply must belong to a conversation started by the authenticated user.


### Parameters

- **postId** (required) in path: No description
- **commentId** (required) in path: No description

### Request Body

- **accountId** (required) `string`: The social account ID

### Responses

#### 200: Comment hidden

**Response Body:**

- **status** `string`: No description
- **commentId** `string`: No description
- **hidden** `boolean`: No description
- **platform** `string`: No description

#### 400: Platform does not support hiding comments

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## DELETE /v1/inbox/comments/{postId}/{commentId}/hide

**Unhide comment**

Unhide a previously hidden comment. Supported by Facebook, Instagram, Threads, and X/Twitter.


### Parameters

- **postId** (required) in path: No description
- **commentId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Comment unhidden

**Response Body:**

- **status** `string`: No description
- **commentId** `string`: No description
- **hidden** `boolean`: No description
- **platform** `string`: No description

#### 400: Platform does not support unhiding comments

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# Unlike comment API Reference

Remove a like from a comment. Supported platforms: Facebook, Twitter/X, Bluesky, Reddit.
For Bluesky, the likeUri query parameter is required.


## POST /v1/inbox/comments/{postId}/{commentId}/like

**Like comment**

Like or upvote a comment on a post. Supported platforms: Facebook, Twitter/X, Bluesky, Reddit.
For Bluesky, the cid (content identifier) is required in the request body.


### Parameters

- **postId** (required) in path: No description
- **commentId** (required) in path: No description

### Request Body

- **accountId** (required) `string`: The social account ID
- **cid** `string`: (Bluesky only) Content identifier for the comment

### Responses

#### 200: Comment liked

**Response Body:**

- **status** `string`: No description
- **commentId** `string`: No description
- **liked** `boolean`: No description
- **likeUri** `string`: (Bluesky only) URI to use for unliking
- **platform** `string`: No description

#### 400: Platform does not support liking comments

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## DELETE /v1/inbox/comments/{postId}/{commentId}/like

**Unlike comment**

Remove a like from a comment. Supported platforms: Facebook, Twitter/X, Bluesky, Reddit.
For Bluesky, the likeUri query parameter is required.


### Parameters

- **postId** (required) in path: No description
- **commentId** (required) in path: No description
- **accountId** (required) in query: No description
- **likeUri** (optional) in query: (Bluesky only) The like URI returned when liking

### Responses

#### 200: Comment unliked

**Response Body:**

- **status** `string`: No description
- **commentId** `string`: No description
- **liked** `boolean`: No description
- **platform** `string`: No description

#### 400: Platform does not support unliking comments

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# Bulk create contacts API Reference

Import up to 1000 contacts at a time. Skips duplicates.

## POST /v1/contacts/bulk

**Bulk create contacts**

Import up to 1000 contacts at a time. Skips duplicates.

### Request Body

- **profileId** (required) `string`: No description
- **accountId** (required) `string`: No description
- **platform** (required) `string`: No description
- **contacts** (required) `array`: No description

### Responses

#### 200: Bulk import results

**Response Body:**

- **success** `boolean`: No description
- **created** `integer`: No description
- **skipped** `integer`: No description
- **errors** `array[object]`: 
  Type: `object`
- **total** `integer`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Create contact API Reference

Create a new contact. Optionally create a platform channel in the same request by providing accountId, platform, and platformIdentifier.

## GET /v1/contacts

**List contacts**

List and search contacts for a profile. Supports filtering by tags, platform, subscription status, and full-text search.

### Parameters

- **profileId** (optional) in query: Filter by profile. Omit to list across all profiles
- **search** (optional) in query: No description
- **tag** (optional) in query: No description
- **platform** (optional) in query: No description
- **isSubscribed** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Contacts list with pagination and filter metadata

**Response Body:**

- **success** `boolean`: No description
- **contacts** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **email** `string`: No description
  - **company** `string`: No description
  - **avatarUrl** `string`: No description
  - **tags** `array[string]`: 
  - **isSubscribed** `boolean`: No description
  - **isBlocked** `boolean`: No description
  - **lastMessageSentAt** `string` (date-time): No description
  - **lastMessageReceivedAt** `string` (date-time): No description
  - **messagesSentCount** `integer`: No description
  - **messagesReceivedCount** `integer`: No description
  - **customFields** `object`: No description
  - **notes** `string`: No description
  - **createdAt** `string` (date-time): No description
  - **platform** `string`: No description
  - **platformIdentifier** `string`: No description
  - **displayIdentifier** `string`: No description
- **filters** `object`: 
  - **tags** `array[string]`: 
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/contacts

**Create contact**

Create a new contact. Optionally create a platform channel in the same request by providing accountId, platform, and platformIdentifier.

### Request Body

- **profileId** (required) `string`: No description
- **name** (required) `string`: No description
- **email** `string`: No description
- **company** `string`: No description
- **tags** `array`: No description
- **isSubscribed** `boolean`: No description
- **notes** `string`: No description
- **accountId** `string`: Optional. Creates a channel if provided with platform + platformIdentifier
- **platform** `string`: No description
- **platformIdentifier** `string`: No description
- **displayIdentifier** `string`: No description

### Responses

#### 200: Contact created

**Response Body:**

- **success** `boolean`: No description
- **contact** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **email** `string`: No description
  - **company** `string`: No description
  - **tags** `array[string]`: 
  - **isSubscribed** `boolean`: No description
  - **isBlocked** `boolean`: No description
  - **customFields** `object`: No description
  - **notes** `string`: No description
  - **createdAt** `string` (date-time): No description
- **channel** `object`: Created when accountId, platform, and platformIdentifier are provided
  - **id** `string`: No description
  - **platform** `string`: No description
  - **platformIdentifier** `string`: No description
  - **displayIdentifier** `string`: No description
- **warning** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 409: Duplicate contact

---

---

# Delete contact API Reference

Permanently deletes a contact and all associated channels.

## GET /v1/contacts/{contactId}

**Get contact**

Returns a contact with all associated messaging channels.

### Parameters

- **contactId** (required) in path: No description

### Responses

#### 200: Contact with channels

**Response Body:**

- **success** `boolean`: No description
- **contact** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **email** `string`: No description
  - **company** `string`: No description
  - **avatarUrl** `string`: No description
  - **tags** `array[string]`: 
  - **isSubscribed** `boolean`: No description
  - **isBlocked** `boolean`: No description
  - **messagesSentCount** `integer`: Messages sent to the contact, derived live from message history across all linked conversations.
  - **messagesReceivedCount** `integer`: Messages received from the contact, derived live from message history across all linked conversations.
  - **lastMessageSentAt** `string` (date-time): Timestamp of the most recent outgoing message, or null if none.
  - **lastMessageReceivedAt** `string` (date-time): Timestamp of the most recent incoming message, or null if none.
  - **customFields** `object`: No description
  - **notes** `string`: No description
  - **conversationIds** `array[string]`: 
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description
- **channels** `array[object]`: 
  - **id** `string`: No description
  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **platformIdentifier** `string`: No description
  - **displayIdentifier** `string`: No description
  - **isSubscribed** `boolean`: No description
  - **conversationId** `string`: No description
  - **lastActiveAt** `string` (date-time): Most recent message (either direction) in this channel's conversation, or null if none.
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/contacts/{contactId}

**Update contact**

Update one or more fields on a contact. Only provided fields are changed.

### Parameters

- **contactId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **email** `string`: No description
- **company** `string`: No description
- **avatarUrl** `string`: No description
- **tags** `array`: No description
- **isSubscribed** `boolean`: No description
- **isBlocked** `boolean`: No description
- **notes** `string`: No description

### Responses

#### 200: Contact updated

**Response Body:**

- **success** `boolean`: No description
- **contact** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **email** `string`: No description
  - **company** `string`: No description
  - **avatarUrl** `string`: No description
  - **tags** `array[string]`: 
  - **isSubscribed** `boolean`: No description
  - **isBlocked** `boolean`: No description
  - **notes** `string`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/contacts/{contactId}

**Delete contact**

Permanently deletes a contact and all associated channels.

### Parameters

- **contactId** (required) in path: No description

### Responses

#### 200: Contact deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List channels for a contact API Reference

Returns all messaging channels linked to a contact (e.g. Instagram DM, Telegram, WhatsApp).

## GET /v1/contacts/{contactId}/channels

**List channels for a contact**

Returns all messaging channels linked to a contact (e.g. Instagram DM, Telegram, WhatsApp).

### Parameters

- **contactId** (required) in path: No description

### Responses

#### 200: List of contact channels

**Response Body:**

- **success** `boolean`: No description
- **channels** `array[object]`: 
  - **id** `string`: No description
  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **platformIdentifier** `string`: No description
  - **displayIdentifier** `string`: No description
  - **isSubscribed** `boolean`: No description
  - **conversationId** `string`: No description
  - **metadata** `object`: No description
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Get contact API Reference

Returns a contact with all associated messaging channels.

## GET /v1/contacts/{contactId}

**Get contact**

Returns a contact with all associated messaging channels.

### Parameters

- **contactId** (required) in path: No description

### Responses

#### 200: Contact with channels

**Response Body:**

- **success** `boolean`: No description
- **contact** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **email** `string`: No description
  - **company** `string`: No description
  - **avatarUrl** `string`: No description
  - **tags** `array[string]`: 
  - **isSubscribed** `boolean`: No description
  - **isBlocked** `boolean`: No description
  - **messagesSentCount** `integer`: Messages sent to the contact, derived live from message history across all linked conversations.
  - **messagesReceivedCount** `integer`: Messages received from the contact, derived live from message history across all linked conversations.
  - **lastMessageSentAt** `string` (date-time): Timestamp of the most recent outgoing message, or null if none.
  - **lastMessageReceivedAt** `string` (date-time): Timestamp of the most recent incoming message, or null if none.
  - **customFields** `object`: No description
  - **notes** `string`: No description
  - **conversationIds** `array[string]`: 
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description
- **channels** `array[object]`: 
  - **id** `string`: No description
  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **platformIdentifier** `string`: No description
  - **displayIdentifier** `string`: No description
  - **isSubscribed** `boolean`: No description
  - **conversationId** `string`: No description
  - **lastActiveAt** `string` (date-time): Most recent message (either direction) in this channel's conversation, or null if none.
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/contacts/{contactId}

**Update contact**

Update one or more fields on a contact. Only provided fields are changed.

### Parameters

- **contactId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **email** `string`: No description
- **company** `string`: No description
- **avatarUrl** `string`: No description
- **tags** `array`: No description
- **isSubscribed** `boolean`: No description
- **isBlocked** `boolean`: No description
- **notes** `string`: No description

### Responses

#### 200: Contact updated

**Response Body:**

- **success** `boolean`: No description
- **contact** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **email** `string`: No description
  - **company** `string`: No description
  - **avatarUrl** `string`: No description
  - **tags** `array[string]`: 
  - **isSubscribed** `boolean`: No description
  - **isBlocked** `boolean`: No description
  - **notes** `string`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/contacts/{contactId}

**Delete contact**

Permanently deletes a contact and all associated channels.

### Parameters

- **contactId** (required) in path: No description

### Responses

#### 200: Contact deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List contacts API Reference

List and search contacts for a profile. Supports filtering by tags, platform, subscription status, and full-text search.

## GET /v1/contacts

**List contacts**

List and search contacts for a profile. Supports filtering by tags, platform, subscription status, and full-text search.

### Parameters

- **profileId** (optional) in query: Filter by profile. Omit to list across all profiles
- **search** (optional) in query: No description
- **tag** (optional) in query: No description
- **platform** (optional) in query: No description
- **isSubscribed** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Contacts list with pagination and filter metadata

**Response Body:**

- **success** `boolean`: No description
- **contacts** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **email** `string`: No description
  - **company** `string`: No description
  - **avatarUrl** `string`: No description
  - **tags** `array[string]`: 
  - **isSubscribed** `boolean`: No description
  - **isBlocked** `boolean`: No description
  - **lastMessageSentAt** `string` (date-time): No description
  - **lastMessageReceivedAt** `string` (date-time): No description
  - **messagesSentCount** `integer`: No description
  - **messagesReceivedCount** `integer`: No description
  - **customFields** `object`: No description
  - **notes** `string`: No description
  - **createdAt** `string` (date-time): No description
  - **platform** `string`: No description
  - **platformIdentifier** `string`: No description
  - **displayIdentifier** `string`: No description
- **filters** `object`: 
  - **tags** `array[string]`: 
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/contacts

**Create contact**

Create a new contact. Optionally create a platform channel in the same request by providing accountId, platform, and platformIdentifier.

### Request Body

- **profileId** (required) `string`: No description
- **name** (required) `string`: No description
- **email** `string`: No description
- **company** `string`: No description
- **tags** `array`: No description
- **isSubscribed** `boolean`: No description
- **notes** `string`: No description
- **accountId** `string`: Optional. Creates a channel if provided with platform + platformIdentifier
- **platform** `string`: No description
- **platformIdentifier** `string`: No description
- **displayIdentifier** `string`: No description

### Responses

#### 200: Contact created

**Response Body:**

- **success** `boolean`: No description
- **contact** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **email** `string`: No description
  - **company** `string`: No description
  - **tags** `array[string]`: 
  - **isSubscribed** `boolean`: No description
  - **isBlocked** `boolean`: No description
  - **customFields** `object`: No description
  - **notes** `string`: No description
  - **createdAt** `string` (date-time): No description
- **channel** `object`: Created when accountId, platform, and platformIdentifier are provided
  - **id** `string`: No description
  - **platform** `string`: No description
  - **platformIdentifier** `string`: No description
  - **displayIdentifier** `string`: No description
- **warning** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 409: Duplicate contact

---

---

# Update contact API Reference

Update one or more fields on a contact. Only provided fields are changed.

## GET /v1/contacts/{contactId}

**Get contact**

Returns a contact with all associated messaging channels.

### Parameters

- **contactId** (required) in path: No description

### Responses

#### 200: Contact with channels

**Response Body:**

- **success** `boolean`: No description
- **contact** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **email** `string`: No description
  - **company** `string`: No description
  - **avatarUrl** `string`: No description
  - **tags** `array[string]`: 
  - **isSubscribed** `boolean`: No description
  - **isBlocked** `boolean`: No description
  - **messagesSentCount** `integer`: Messages sent to the contact, derived live from message history across all linked conversations.
  - **messagesReceivedCount** `integer`: Messages received from the contact, derived live from message history across all linked conversations.
  - **lastMessageSentAt** `string` (date-time): Timestamp of the most recent outgoing message, or null if none.
  - **lastMessageReceivedAt** `string` (date-time): Timestamp of the most recent incoming message, or null if none.
  - **customFields** `object`: No description
  - **notes** `string`: No description
  - **conversationIds** `array[string]`: 
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description
- **channels** `array[object]`: 
  - **id** `string`: No description
  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **platformIdentifier** `string`: No description
  - **displayIdentifier** `string`: No description
  - **isSubscribed** `boolean`: No description
  - **conversationId** `string`: No description
  - **lastActiveAt** `string` (date-time): Most recent message (either direction) in this channel's conversation, or null if none.
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/contacts/{contactId}

**Update contact**

Update one or more fields on a contact. Only provided fields are changed.

### Parameters

- **contactId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **email** `string`: No description
- **company** `string`: No description
- **avatarUrl** `string`: No description
- **tags** `array`: No description
- **isSubscribed** `boolean`: No description
- **isBlocked** `boolean`: No description
- **notes** `string`: No description

### Responses

#### 200: Contact updated

**Response Body:**

- **success** `boolean`: No description
- **contact** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **email** `string`: No description
  - **company** `string`: No description
  - **avatarUrl** `string`: No description
  - **tags** `array[string]`: 
  - **isSubscribed** `boolean`: No description
  - **isBlocked** `boolean`: No description
  - **notes** `string`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/contacts/{contactId}

**Delete contact**

Permanently deletes a contact and all associated channels.

### Parameters

- **contactId** (required) in path: No description

### Responses

#### 200: Contact deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Check Telegram status API Reference

Poll this endpoint to check if a Telegram access code has been used to connect a channel/group. Recommended polling interval: 3 seconds.
Status values: pending (waiting for user), connected (channel/group linked), expired (generate a new code).


## GET /v1/connect/telegram

**Generate Telegram code**

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

- **profileId** (required) in query: The profile ID to connect the Telegram account to

### Responses

#### 200: Access code generated

**Response Body:**

- **code** `string`: The access code to send to the Telegram bot (example: "ZRN-ABC123")
- **expiresAt** `string` (date-time): When the code expires
- **expiresIn** `integer`: Seconds until expiration (example: 900)
- **botUsername** `string`: The Telegram bot username to message (example: "LateScheduleBot")
- **instructions** `array[string]`: Step-by-step connection instructions

#### 400: Profile ID required or invalid format

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to this profile

#### 404: Profile not found

#### 500: Internal error

---

## POST /v1/connect/telegram

**Connect Telegram directly**

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.

### Request Body

- **chatId** (required) `string`: The Telegram chat ID. Numeric ID (e.g. "-1001234567890") or username with @ prefix (e.g. "@mychannel").
- **profileId** (required) `string`: The profile ID to connect the account to

### Responses

#### 200: Telegram channel connected successfully

**Response Body:**

- **message** `string`: No description
- **account** `object`: 
  - **_id** `string`: No description
  - **platform** `string`: No description - one of: telegram
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **isActive** `boolean`: No description
  - **chatType** `string`: No description - one of: channel, group, supergroup, private

#### 400: Chat ID required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to this profile

#### 404: Profile not found

#### 500: Internal error

---

## PATCH /v1/connect/telegram

**Check Telegram status**

Poll this endpoint to check if a Telegram access code has been used to connect a channel/group. Recommended polling interval: 3 seconds.
Status values: pending (waiting for user), connected (channel/group linked), expired (generate a new code).


### Parameters

- **code** (required) in query: The access code to check status for

### Responses

#### 200: Connection status

**Response Body:**

*One of the following:*
  - **status** `string`: No description - one of: pending
  - **expiresAt** `string` (date-time): No description
  - **expiresIn** `integer`: Seconds until expiration
  - **status** `string`: No description - one of: connected
  - **chatId** `string`: No description
  - **chatTitle** `string`: No description
  - **chatType** `string`: No description - one of: channel, group, supergroup
  - **account** `object`: 
    - **_id** `string`: No description
    - **platform** `string`: No description
    - **username** `string`: No description
    - **displayName** `string`: No description
  - **status** `string`: No description - one of: expired
  - **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Code not found

#### 500: Internal error

---

---

# Complete WhatsApp phone number selection API Reference

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.


## GET /v1/connect/whatsapp/select-phone-number

**List WhatsApp phone numbers for selection**

Fetch the WhatsApp phone numbers available across the user's WhatsApp Business Accounts (WABAs) after a headless OAuth flow.

WhatsApp 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.

Use the `profileId` and `tempToken` returned in the headless redirect (`step=select_phone_number`).

Alternative: if you already know `wabaId` and `phoneNumberId` (e.g. from Meta Business Suite), use `connectWhatsAppCredentials` instead, which skips this two-step flow.


### Parameters

- **profileId** (required) in query: The Zernio profile ID from the headless redirect
- **tempToken** (required) in query: The temporary access token from the headless redirect
- **X-Connect-Token** (optional) in header: Alternative auth for API users' end customers (used when the bearer token is scoped to a different user)

### Responses

#### 200: Phone numbers fetched successfully

**Response Body:**

- **phoneNumbers** `array[object]`: 
  - **id** `string`: Phone Number ID (Meta)
  - **display_phone_number** `string`: E.164-formatted display number
  - **verified_name** `string`: Meta-verified business name
  - **quality_rating** `string`: GREEN, YELLOW, RED, or UNKNOWN
  - **name_status** `string`: APPROVED, PENDING_REVIEW, DECLINED, or NONE
  - **messaging_limit_tier** `string`: TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED
  - **wabaId** `string`: WhatsApp Business Account ID (Zernio enrichment)
  - **wabaName** `string`: WABA display name (Zernio enrichment)

#### 400: Missing profileId or tempToken

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Failed to fetch phone numbers (Meta API error, expired token, or insufficient permissions)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## POST /v1/connect/whatsapp/select-phone-number

**Complete WhatsApp phone number selection**

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.


### Parameters

- **X-Connect-Token** (optional) in header: Alternative auth for API users' end customers

### Request Body

- **profileId** (required) `string`: The Zernio profile ID
- **phoneNumberId** (required) `string`: The selected phone number ID (from listWhatsAppPhoneNumbers)
- **wabaId** (required) `string`: The WABA ID containing the selected phone
- **tempToken** (required) `string`: The temporary access token from the headless redirect
- **userProfile** `object`: Optional user profile data (passthrough)
- **redirect_url** `string`: Optional URL to receive the post-connection redirect target

### Responses

#### 200: Phone number connected successfully

**Response Body:**

- **message** `string`: No description
- **redirect_url** `string`: Present only if redirect_url was provided in the request
- **account** `object`: 
  - **accountId** `string`: No description
  - **platform** `string`: No description - one of: whatsapp
  - **username** `string`: Display phone number
  - **displayName** `string`: Meta-verified business name
  - **isActive** `boolean`: No description
  - **selectedPhoneNumber** `string`: No description

#### 400: Missing required fields (profileId, phoneNumberId, wabaId, or tempToken)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Profile limit exceeded for the user's plan (PROFILE_LIMIT_EXCEEDED)

#### 404: Selected phone number not found in the specified WABA

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 500: Failed to bind phone number

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Configure TikTok Ads Brand Identity API Reference

Set or update the Brand Identity (display name + avatar) for a
`tiktokads` SocialAccount. TikTok 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). This route uploads the supplied image to TikTok, creates
the identity via `/v2/identity/create/`, and caches the resulting
`identity_id` on the account so subsequent `POST /v1/ads/create`
calls can opt into it via `identityType: 'CUSTOMIZED_USER'`.

Configurable on every `tiktokads` account, including linked-mode ones
(those with a posting account on the same profile). Configuration 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.

TikTok 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).

Alternative: pass `brandIdentity` directly on `POST /v1/ads/create` to
configure on first ad creation in a single round-trip.


## PATCH /v1/connect/tiktok-ads

**Configure TikTok Ads Brand Identity**

Set or update the Brand Identity (display name + avatar) for a
`tiktokads` SocialAccount. TikTok 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). This route uploads the supplied image to TikTok, creates
the identity via `/v2/identity/create/`, and caches the resulting
`identity_id` on the account so subsequent `POST /v1/ads/create`
calls can opt into it via `identityType: 'CUSTOMIZED_USER'`.

Configurable on every `tiktokads` account, including linked-mode ones
(those with a posting account on the same profile). Configuration 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.

TikTok 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).

Alternative: pass `brandIdentity` directly on `POST /v1/ads/create` to
configure on first ad creation in a single round-trip.


### Request Body

- **accountId** (required) `string`: SocialAccount ID of the `tiktokads` account.
- **displayName** (required) `string`: Brand name shown above the ad on TikTok.
- **imageUrl** (required) `string`: 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: Brand identity configured (or updated)

**Response Body:**

- **success** `boolean`: No description (example: true)
- **identityId** `string`: The TikTok-assigned identity_id
- **displayName** `string`: No description

#### 400: Missing fields, invalid lengths, account is in linked mode, or no advertiser found on the account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: TikTok Ads account not found

#### 500: Failed to create the TikTok identity (TikTok API error)

---

---

# Connect ads for a platform API Reference

Unified ads connection endpoint. Creates a dedicated ads SocialAccount for the specified platform.

Same-token platforms (facebook, instagram, linkedin, pinterest): Creates an ads SocialAccount (metaads, linkedinads, pinterestads) with a copied OAuth token from the parent posting account. If the ads account already exists, returns alreadyConnected: true. No extra OAuth needed.

Separate-token platforms (tiktok, twitter): Starts 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.
  - tiktok: accountId is OPTIONAL. With accountId, the new tiktokads account links to that posting account (parentAccountId set) — Spark Ads + standalone ads using the posting TT_USER identity become available. 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. The Brand Identity is configured separately via PATCH /v1/connect/tiktok-ads (or inline on POST /v1/ads/create via the brandIdentity field).
  - twitter (X Ads): accountId is REQUIRED. There's no ads-only mode — tweets need to be authored by a real X user.

Standalone platforms (googleads): Starts the Google Ads OAuth flow and creates a standalone ads SocialAccount (googleads) with no parent. If the account already exists, returns alreadyConnected: true.

Ads accounts appear as regular SocialAccount documents with ads platform values (e.g., metaads, tiktokads) in GET /v1/accounts.


## GET /v1/connect/{platform}/ads

**Connect ads for a platform**

Unified ads connection endpoint. Creates a dedicated ads SocialAccount for the specified platform.

Same-token platforms (facebook, instagram, linkedin, pinterest): Creates an ads SocialAccount (metaads, linkedinads, pinterestads) with a copied OAuth token from the parent posting account. If the ads account already exists, returns alreadyConnected: true. No extra OAuth needed.

Separate-token platforms (tiktok, twitter): Starts 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.
  - tiktok: accountId is OPTIONAL. With accountId, the new tiktokads account links to that posting account (parentAccountId set) — Spark Ads + standalone ads using the posting TT_USER identity become available. 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. The Brand Identity is configured separately via PATCH /v1/connect/tiktok-ads (or inline on POST /v1/ads/create via the brandIdentity field).
  - twitter (X Ads): accountId is REQUIRED. There's no ads-only mode — tweets need to be authored by a real X user.

Standalone platforms (googleads): Starts the Google Ads OAuth flow and creates a standalone ads SocialAccount (googleads) with no parent. If the account already exists, returns alreadyConnected: true.

Ads accounts appear as regular SocialAccount documents with ads platform values (e.g., metaads, tiktokads) in GET /v1/accounts.


### Parameters

- **platform** (required) in path: Platform to connect ads for. Only platforms with ads support are accepted.
- **profileId** (required) in query: Your Zernio profile ID
- **accountId** (optional) in query: Existing SocialAccount ID. Required for `twitter` (X Ads). Optional for `tiktok` —
omit to enter ads-only mode (no TikTok posting account linked; ad creation uses
a Brand Identity instead of a TT_USER). Ignored for same-token (`facebook`,
`instagram`, `linkedin`, `pinterest`) and standalone (`googleads`) platforms.

- **redirect_url** (optional) in query: Custom redirect URL after OAuth completes (same-token platforms only)
- **headless** (optional) in query: Enable headless mode (same-token platforms only)
- **adAccountId** (optional) in query: Scope ad sync to a single platform ad account. Without this param,
sync covers every ad account the connected token can see. Supported
on `facebook`/`instagram` (Meta, `act_<digits>`), `linkedin` (bare
numeric sponsored-account id), `googleads` (bare customer id digits)
and `twitter` (X Ads, base36 account id). `tiktok` scopes advertisers
at OAuth and `pinterest` has no ads discovery, so both ignore it.
Meta ids are additionally validated against the connected token;
unreachable IDs return 400. Setting a scope also removes already
synced ads from de-scoped ad accounts. For multiple accounts use
`adAccountIds` instead.

- **adAccountIds** (optional) in query: 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`). Persisted server-side; latest call
wins, and de-scoped ad accounts have their synced ads removed.
Omitting both `adAccountId` and `adAccountIds` keeps any previously
persisted scope unchanged.


### Responses

#### 200: Either an OAuth URL to redirect to, or confirmation that ads are already connected

**Response Body:**

*One of the following:*
  - **alreadyConnected** `boolean`: No description (example: true)
  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **scopedAdAccountIds** `array[string]`: Echo of the persisted ad-account scope when the caller passed
`adAccountId` / `adAccountIds`. Omitted when no scope is set.

  - **authUrl** `string` (uri): No description
  - **state** `string`: No description

#### 400: Platform doesn't support ads, or missing accountId for X Ads

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or no access to profile

#### 404: Profile or posting account not found

---

---

# Connect Bluesky account API Reference

Connect a Bluesky account using identifier (handle or email) and an app password.
To get your userId for the state parameter, call GET /v1/users which includes a currentUserId field.


## POST /v1/connect/bluesky/credentials

**Connect Bluesky account**

Connect a Bluesky account using identifier (handle or email) and an app password.
To get your userId for the state parameter, call GET /v1/users which includes a currentUserId field.


### Request Body

- **identifier** (required) `string`: Your Bluesky handle (e.g. user.bsky.social) or email address
- **appPassword** (required) `string`: App password generated from Bluesky Settings > App Passwords
- **state** (required) `string`: Required state formatted as {userId}-{profileId}. Get userId from GET /v1/users and profileId from GET /v1/profiles.
- **redirectUri** `string`: Optional URL to redirect to after successful connection

### Responses

#### 200: Bluesky connected successfully

**Response Body:**

- **message** `string`: No description
- **account**: `SocialAccount` - See schema definition

#### 400: Invalid request - missing fields or invalid state format

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Internal error

---


# Related Schema Definitions

## SocialAccount

### Properties

- **_id** (required) `string`: No description
- **platform** (required) `string`: No description - one of: tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, discord, whatsapp, linkedinads, metaads, pinterestads, tiktokads, xads, googleads
- **profileId** (required): No description
- **username** `string`: No description
- **displayName** `string`: No description
- **profilePicture** `string`: URL to the account's profile picture on the platform. May be null if the platform does not provide one.
- **profileUrl** `string`: Full profile URL for the connected account on its platform.
- **isActive** (required) `boolean`: No description
- **followersCount** `number`: Follower count (only included if user has analytics add-on)
- **followersLastUpdated** `string`: Last time follower count was updated (only included if user has analytics add-on)
- **parentAccountId** `string`: Reference to the parent posting SocialAccount. Set for ads accounts that share
or derive from a posting account's OAuth token. null for standalone ads (Google Ads)
and all posting accounts.

- **enabled** `boolean`: Whether the user explicitly activated this account. false means the account was
created as a side effect (e.g., posting account auto-created when user connected
ads first). Posting UI and scheduler ignore accounts with enabled: false.

- **metadata** `object`: Platform-specific metadata. Fields vary by platform. For WhatsApp accounts, includes:
- qualityRating: Phone number quality rating from Meta (GREEN, YELLOW, RED, or UNKNOWN)
- nameStatus: Display name review status (APPROVED, PENDING_REVIEW, DECLINED, or NONE). Messages cannot be sent until the display name is approved by Meta.
- messagingLimitTier: Maximum unique business-initiated conversations per 24h rolling window (TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED). Scales automatically as quality rating improves.
- verifiedName: Meta-verified business display name
- displayPhoneNumber: Formatted phone number (e.g., "+1 555-123-4567")
- wabaId: WhatsApp Business Account ID
- phoneNumberId: Meta phone number ID

---

# Connect WhatsApp via credentials API Reference

Connect a WhatsApp Business Account by providing Meta credentials directly.
This is the headless alternative to the Embedded Signup browser flow.

To get the required credentials:
1. Go to Meta Business Suite (business.facebook.com)
2. Create or select a WhatsApp Business Account
3. In Business Settings > System Users, create a System User
4. Assign it the whatsapp_business_management and whatsapp_business_messaging permissions
5. Generate a permanent access token
6. Get the WABA ID from WhatsApp Manager > Account Tools > Phone Numbers
7. Get the Phone Number ID from the same page (click on the number)


## POST /v1/connect/whatsapp/credentials

**Connect WhatsApp via credentials**

Connect a WhatsApp Business Account by providing Meta credentials directly.
This is the headless alternative to the Embedded Signup browser flow.

To get the required credentials:
1. Go to Meta Business Suite (business.facebook.com)
2. Create or select a WhatsApp Business Account
3. In Business Settings > System Users, create a System User
4. Assign it the whatsapp_business_management and whatsapp_business_messaging permissions
5. Generate a permanent access token
6. Get the WABA ID from WhatsApp Manager > Account Tools > Phone Numbers
7. Get the Phone Number ID from the same page (click on the number)


### Request Body

- **profileId** (required) `string`: Your Zernio profile ID
- **accessToken** (required) `string`: Permanent System User access token from Meta Business Suite
- **wabaId** (required) `string`: WhatsApp Business Account ID from Meta
- **phoneNumberId** (required) `string`: Phone Number ID from Meta WhatsApp Manager

### Responses

#### 200: WhatsApp connected successfully

**Response Body:**

- **message** `string`: No description
- **account** `object`: 
  - **accountId** `string`: No description
  - **platform** `string`: No description - one of: whatsapp
  - **username** `string`: Display phone number
  - **displayName** `string`: Meta-verified business name
  - **isActive** `boolean`: No description
  - **selectedPhoneNumber** `string`: The connected phone number

#### 400: Invalid request. Either missing fields or the phoneNumberId was not found
in the specified WABA. If the phone was not found, the response includes
availablePhoneNumbers to help identify the correct ID.


#### 401: Invalid or expired access token

#### 403: Profile limit exceeded for this plan

---

---

# Get OAuth connect URL API Reference

Initiate an OAuth connection flow. Returns an authUrl to redirect the user to.
Standard flow: Zernio hosts the selection UI, then redirects to your redirect_url. 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.


## GET /v1/connect/{platform}

**Get OAuth connect URL**

Initiate an OAuth connection flow. Returns an authUrl to redirect the user to.
Standard flow: Zernio hosts the selection UI, then redirects to your redirect_url. 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.


### Parameters

- **platform** (required) in path: Social media platform to connect
- **profileId** (required) in query: Your Zernio profile ID (get from /v1/profiles)
- **redirect_url** (optional) in query: Your custom redirect URL after connection completes. Standard mode appends ?connected={platform}&profileId=X&accountId=Y&username=Z. Headless mode appends 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.
- **headless** (optional) in query: 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.

### Responses

#### 200: OAuth authorization URL to redirect user to

**Response Body:**

- **authUrl** `string` (uri): URL to redirect your user to for OAuth authorization
- **state** `string`: State parameter for security (handled automatically)

#### 400: Missing/invalid parameters (e.g., invalid profileId format)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Payment method or enterprise contract required. The authenticated
account hit a billing gate before the connection could proceed.
Three reasons:

  - `free_tier_exceeded`: the team has connected more accounts
    than the free tier allows. Add a payment method on the
    dashboard to continue (the user will be billed per
    additional connected account).

  - `twitter_passthrough`: connecting an X (Twitter) account
    requires a card on file from day one because X API calls
    incur real per-call pass-through costs. Applies to the 1st
    X account, not just the 3rd+.

  - `enterprise_required`: the team has reached the public
    pricing ceiling (2,000 connected accounts). Beyond that
    requires a custom enterprise contract negotiated directly.
    `dashboard_url` deep-links to the enterprise contact page
    rather than the billing tab. The end-user already has a
    card on file; this gate is about contract terms, not card
    collection.

SDK consumers should switch on `reason` to render the right
prompt. For `free_tier_exceeded` and `twitter_passthrough`,
redirect the end-user to `dashboard_url` to add a payment method
via Zernio's hosted Stripe Setup Checkout. For
`enterprise_required`, redirect to `dashboard_url` (the
enterprise contact form) so they can talk to sales.


**Response Body:**

- **error** (required) `string`: 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** (required) `string`: Machine-readable error code. Stable across versions. - one of: PAYMENT_REQUIRED
- **reason** (required) `string`: Discriminator for which gate fired. - one of: free_tier_exceeded, twitter_passthrough, enterprise_required
- **documentation_url** `string` (uri): Link to the relevant documentation page. (example: "https://docs.zernio.com/billing/payment-method-required")
- **dashboard_url** `string` (uri): Deep-link to send the end-user to. For
`free_tier_exceeded` and `twitter_passthrough` this is
the Zernio billing tab. For `enterprise_required` this
is the Zernio enterprise contact page.
 (example: "https://zernio.com/dashboard?tab=billing")
- **details** `object`: Structured context for SDK clients that want to render their own UX. Keys vary by `reason`.
  - **free_tier_account_limit** `integer`: How many accounts the free tier allows. Only set when reason=free_tier_exceeded. (example: 2)
  - **current_account_count** `integer`: How many accounts the team currently has connected. Set when reason=free_tier_exceeded or reason=enterprise_required. (example: 5)
  - **has_payment_method** `boolean`: Whether the team currently has a card on file in Stripe. Set when reason=free_tier_exceeded or reason=twitter_passthrough.
  - **public_account_limit** `integer`: Public pricing ceiling (the published cap beyond which an enterprise contract is required). Only set when reason=enterprise_required. (example: 2000)
  - **effective_account_limit** `integer`: The cap actually applied to this team. Equals
`public_account_limit` for organic teams; for teams
with a per-customer override (grandfathered legacy
customers, signed enterprise contracts) this can
be higher. Only set when reason=enterprise_required.
 (example: 2000)

#### 403: No access to profile, or BYOK required for AppSumo Twitter

#### 404: Profile not found

---

## POST /v1/connect/{platform}

**Complete OAuth callback**

Exchange the OAuth authorization code for tokens and connect the account to the specified profile.

### Parameters

- **platform** (required) in path: No description

### Request Body

- **code** (required) `string`: No description
- **state** (required) `string`: No description
- **profileId** (required) `string`: No description

### Responses

#### 200: Account connected

#### 400: Invalid params

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: BYOK required for AppSumo Twitter

#### 500: Failed to connect account

---

---

# List Facebook pages API Reference

Returns all Facebook pages the connected account has access to, including the currently selected page.

## GET /v1/accounts/{accountId}/facebook-page

**List Facebook pages**

Returns all Facebook pages the connected account has access to, including the currently selected page.

### Parameters

- **accountId** (required) in path: No description
- **refresh** (optional) in query: 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.


### Responses

#### 200: Pages list

**Response Body:**

- **pages** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **username** `string`: No description
  - **category** `string`: No description
  - **fan_count** `integer`: No description
- **selectedPageId** `string`: No description
- **cached** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## PUT /v1/accounts/{accountId}/facebook-page

**Update Facebook page**

Switch which Facebook Page is active for a connected account.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **selectedPageId** (required) `string`: No description

### Responses

#### 200: Page updated

**Response Body:**

- **message** `string`: No description
- **selectedPage** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description

#### 400: Page not in available pages

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# List GBP locations API Reference

Returns Google Business Profile locations the connected account can access, plus the currently selected location. The list is bounded (see hasMore); for accounts that own many locations, use the search or filter query params to find a specific one instead of loading them all.


## GET /v1/accounts/{accountId}/gmb-locations

**List GBP locations**

Returns Google Business Profile locations the connected account can access, plus the currently selected location. The list is bounded (see hasMore); for accounts that own many locations, use the search or filter query params to find a specific one instead of loading them all.


### Parameters

- **accountId** (required) in path: No description
- **search** (optional) in query: Free-text search on the business name, applied server-side by Google. Use for accounts with many locations.
- **filter** (optional) in query: Raw Google Business Information API filter expression (advanced; takes precedence over search), e.g. storeCode="LH279411".

### Responses

#### 200: Locations list

**Response Body:**

- **locations** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **accountId** `string`: No description
  - **accountName** `string`: No description
  - **address** `string`: No description
  - **category** `string`: No description
  - **websiteUrl** `string`: No description
  - **storeCode** `string`: No description
- **hasMore** `boolean`: True when more locations exist than were returned (use search to narrow down).
- **selectedLocationId** `string`: No description
- **cached** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## PUT /v1/accounts/{accountId}/gmb-locations

**Update GBP location**

Switch which GBP location is active for a connected account.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **selectedLocationId** (required) `string`: No description
- **googleAccountId** `string`: Optional but recommended. The Google Business Account resource name ("accounts/123") that owns the new location (from GET gmb-locations). When provided, the location is resolved directly instead of by enumerating the account, which is required for accounts with many locations. Named `googleAccountId` to disambiguate from the path `accountId` (the Zernio account). The legacy field name `accountId` is still accepted for backwards compatibility.


### Responses

#### 200: Location updated

**Response Body:**

- **message** `string`: No description
- **selectedLocation** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description

#### 400: Location not in available locations

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# List LinkedIn orgs API Reference

Returns LinkedIn organizations (company pages) the connected account has admin access to.

## GET /v1/accounts/{accountId}/linkedin-organizations

**List LinkedIn orgs**

Returns LinkedIn organizations (company pages) the connected account has admin access to.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Organizations list

**Response Body:**

- **organizations** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **vanityName** `string`: No description
  - **localizedName** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Get pending OAuth data API Reference

Fetch pending OAuth data for headless mode using the pendingDataToken from the redirect URL.

**Scope**: This endpoint is used only for LinkedIn organizations and Snapchat profiles, where the selection list is too large to fit in URL params. WhatsApp, Facebook, Pinterest, Google Business and other platforms pass selection state directly via URL query params on the redirect (`profileId`, `tempToken`, `step`), 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`).

Token is one-time use and expires after 10 minutes. No authentication required.


## GET /v1/connect/pending-data

**Get pending OAuth data**

Fetch pending OAuth data for headless mode using the pendingDataToken from the redirect URL.

**Scope**: This endpoint is used only for LinkedIn organizations and Snapchat profiles, where the selection list is too large to fit in URL params. WhatsApp, Facebook, Pinterest, Google Business and other platforms pass selection state directly via URL query params on the redirect (`profileId`, `tempToken`, `step`), 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`).

Token is one-time use and expires after 10 minutes. No authentication required.


### Parameters

- **token** (required) in query: The pending data token from the OAuth redirect URL (pendingDataToken parameter)

### Responses

#### 200: OAuth data fetched successfully

**Response Body:**

- **platform** `string`: The platform (e.g., "linkedin")
- **profileId** `string`: The Zernio profile ID
- **tempToken** `string`: Temporary access token for the platform
- **refreshToken** `string`: Refresh token (if available)
- **expiresIn** `number`: Token expiry in seconds
- **userProfile** `object`: User profile data (id, username, displayName, profilePicture)
- **selectionType** `string`: Type of selection data - one of: organizations, pages, boards, locations, profiles
- **organizations** `array[object]`: LinkedIn organizations (when selectionType is "organizations")
  - **id** `string`: No description
  - **urn** `string`: No description
  - **name** `string`: No description
  - **vanityName** `string`: No description

#### 400: Missing token parameter

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Token not found or expired

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# List Pinterest boards API Reference

Returns the boards available for a connected Pinterest account. Use this to get a board ID when creating a Pinterest post.

## GET /v1/accounts/{accountId}/pinterest-boards

**List Pinterest boards**

Returns the boards available for a connected Pinterest account. Use this to get a board ID when creating a Pinterest post.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Boards list

**Response Body:**

- **boards** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **privacy** `string`: No description

#### 400: Not a Pinterest account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## PUT /v1/accounts/{accountId}/pinterest-boards

**Set default Pinterest board**

Sets the default board used when publishing pins for this account.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **defaultBoardId** (required) `string`: No description
- **defaultBoardName** `string`: No description

### Responses

#### 200: Default board set

**Response Body:**

- **message** `string`: No description
- **account**: `SocialAccount` - See schema definition

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---


# Related Schema Definitions

## SocialAccount

### Properties

- **_id** (required) `string`: No description
- **platform** (required) `string`: No description - one of: tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, discord, whatsapp, linkedinads, metaads, pinterestads, tiktokads, xads, googleads
- **profileId** (required): No description
- **username** `string`: No description
- **displayName** `string`: No description
- **profilePicture** `string`: URL to the account's profile picture on the platform. May be null if the platform does not provide one.
- **profileUrl** `string`: Full profile URL for the connected account on its platform.
- **isActive** (required) `boolean`: No description
- **followersCount** `number`: Follower count (only included if user has analytics add-on)
- **followersLastUpdated** `string`: Last time follower count was updated (only included if user has analytics add-on)
- **parentAccountId** `string`: Reference to the parent posting SocialAccount. Set for ads accounts that share
or derive from a posting account's OAuth token. null for standalone ads (Google Ads)
and all posting accounts.

- **enabled** `boolean`: Whether the user explicitly activated this account. false means the account was
created as a side effect (e.g., posting account auto-created when user connected
ads first). Posting UI and scheduler ignore accounts with enabled: false.

- **metadata** `object`: Platform-specific metadata. Fields vary by platform. For WhatsApp accounts, includes:
- qualityRating: Phone number quality rating from Meta (GREEN, YELLOW, RED, or UNKNOWN)
- nameStatus: Display name review status (APPROVED, PENDING_REVIEW, DECLINED, or NONE). Messages cannot be sent until the display name is approved by Meta.
- messagingLimitTier: Maximum unique business-initiated conversations per 24h rolling window (TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED). Scales automatically as quality rating improves.
- verifiedName: Meta-verified business display name
- displayPhoneNumber: Formatted phone number (e.g., "+1 555-123-4567")
- wabaId: WhatsApp Business Account ID
- phoneNumberId: Meta phone number ID

---

# List subreddit flairs API Reference

Returns available post flairs for a subreddit. Some subreddits require a flair when posting.

## GET /v1/accounts/{accountId}/reddit-flairs

**List subreddit flairs**

Returns available post flairs for a subreddit. Some subreddits require a flair when posting.

### Parameters

- **accountId** (required) in path: No description
- **subreddit** (required) in query: Subreddit name (without "r/" prefix) to fetch flairs for

### Responses

#### 200: Flairs list

**Response Body:**

- **flairs** `array[object]`: 
  - **id** `string`: Flair ID to pass as flairId in platformSpecificData
  - **text** `string`: Flair display text
  - **textColor** `string`: Text color: 'dark' or 'light'
  - **backgroundColor** `string`: Background hex color (e.g. '#ff4500')

#### 400: Not a Reddit account or missing subreddit parameter

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# List Reddit subreddits API Reference

Returns the subreddits the connected Reddit account can post to. Use this to get a subreddit name when creating a Reddit post.

## GET /v1/accounts/{accountId}/reddit-subreddits

**List Reddit subreddits**

Returns the subreddits the connected Reddit account can post to. Use this to get a subreddit name when creating a Reddit post.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Subreddits list

**Response Body:**

- **subreddits** `array[object]`: 
  - **id** `string`: Reddit subreddit ID
  - **name** `string`: Subreddit name without r/ prefix
  - **title** `string`: Subreddit title
  - **url** `string`: Subreddit URL path
  - **over18** `boolean`: Whether the subreddit is NSFW
- **defaultSubreddit** `string`: Currently set default subreddit for posting

#### 400: Not a Reddit account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## PUT /v1/accounts/{accountId}/reddit-subreddits

**Set default subreddit**

Sets the default subreddit used when publishing posts for this Reddit account.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **defaultSubreddit** (required) `string`: No description

### Responses

#### 200: Default subreddit set

**Response Body:**

- **success** `boolean`: No description

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Generate Telegram code API Reference

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.

## GET /v1/connect/telegram

**Generate Telegram code**

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

- **profileId** (required) in query: The profile ID to connect the Telegram account to

### Responses

#### 200: Access code generated

**Response Body:**

- **code** `string`: The access code to send to the Telegram bot (example: "ZRN-ABC123")
- **expiresAt** `string` (date-time): When the code expires
- **expiresIn** `integer`: Seconds until expiration (example: 900)
- **botUsername** `string`: The Telegram bot username to message (example: "LateScheduleBot")
- **instructions** `array[string]`: Step-by-step connection instructions

#### 400: Profile ID required or invalid format

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to this profile

#### 404: Profile not found

#### 500: Internal error

---

## POST /v1/connect/telegram

**Connect Telegram directly**

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.

### Request Body

- **chatId** (required) `string`: The Telegram chat ID. Numeric ID (e.g. "-1001234567890") or username with @ prefix (e.g. "@mychannel").
- **profileId** (required) `string`: The profile ID to connect the account to

### Responses

#### 200: Telegram channel connected successfully

**Response Body:**

- **message** `string`: No description
- **account** `object`: 
  - **_id** `string`: No description
  - **platform** `string`: No description - one of: telegram
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **isActive** `boolean`: No description
  - **chatType** `string`: No description - one of: channel, group, supergroup, private

#### 400: Chat ID required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to this profile

#### 404: Profile not found

#### 500: Internal error

---

## PATCH /v1/connect/telegram

**Check Telegram status**

Poll this endpoint to check if a Telegram access code has been used to connect a channel/group. Recommended polling interval: 3 seconds.
Status values: pending (waiting for user), connected (channel/group linked), expired (generate a new code).


### Parameters

- **code** (required) in query: The access code to check status for

### Responses

#### 200: Connection status

**Response Body:**

*One of the following:*
  - **status** `string`: No description - one of: pending
  - **expiresAt** `string` (date-time): No description
  - **expiresIn** `integer`: Seconds until expiration
  - **status** `string`: No description - one of: connected
  - **chatId** `string`: No description
  - **chatTitle** `string`: No description
  - **chatType** `string`: No description - one of: channel, group, supergroup
  - **account** `object`: 
    - **_id** `string`: No description
    - **platform** `string`: No description
    - **username** `string`: No description
    - **displayName** `string`: No description
  - **status** `string`: No description - one of: expired
  - **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Code not found

#### 500: Internal error

---

---

# List YouTube playlists API Reference

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.

## GET /v1/accounts/{accountId}/youtube-playlists

**List YouTube playlists**

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

- **accountId** (required) in path: No description

### Responses

#### 200: Playlists list

**Response Body:**

- **playlists** `array[object]`: 
  - **id** `string`: No description
  - **title** `string`: No description
  - **description** `string`: No description
  - **privacy** `string`: No description - one of: public, private, unlisted
  - **itemCount** `integer`: No description
  - **thumbnailUrl** `string`: No description
- **defaultPlaylistId** `string`: No description

#### 400: Not a YouTube account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## PUT /v1/accounts/{accountId}/youtube-playlists

**Set default YouTube playlist**

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

- **accountId** (required) in path: No description

### Request Body

- **defaultPlaylistId** (required) `string`: No description
- **defaultPlaylistName** `string`: No description

### Responses

#### 200: Default playlist set

**Response Body:**

- **success** `boolean`: No description

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Complete OAuth callback API Reference

Exchange the OAuth authorization code for tokens and connect the account to the specified profile.

## GET /v1/connect/{platform}

**Get OAuth connect URL**

Initiate an OAuth connection flow. Returns an authUrl to redirect the user to.
Standard flow: Zernio hosts the selection UI, then redirects to your redirect_url. 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.


### Parameters

- **platform** (required) in path: Social media platform to connect
- **profileId** (required) in query: Your Zernio profile ID (get from /v1/profiles)
- **redirect_url** (optional) in query: Your custom redirect URL after connection completes. Standard mode appends ?connected={platform}&profileId=X&accountId=Y&username=Z. Headless mode appends 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.
- **headless** (optional) in query: 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.

### Responses

#### 200: OAuth authorization URL to redirect user to

**Response Body:**

- **authUrl** `string` (uri): URL to redirect your user to for OAuth authorization
- **state** `string`: State parameter for security (handled automatically)

#### 400: Missing/invalid parameters (e.g., invalid profileId format)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Payment method or enterprise contract required. The authenticated
account hit a billing gate before the connection could proceed.
Three reasons:

  - `free_tier_exceeded`: the team has connected more accounts
    than the free tier allows. Add a payment method on the
    dashboard to continue (the user will be billed per
    additional connected account).

  - `twitter_passthrough`: connecting an X (Twitter) account
    requires a card on file from day one because X API calls
    incur real per-call pass-through costs. Applies to the 1st
    X account, not just the 3rd+.

  - `enterprise_required`: the team has reached the public
    pricing ceiling (2,000 connected accounts). Beyond that
    requires a custom enterprise contract negotiated directly.
    `dashboard_url` deep-links to the enterprise contact page
    rather than the billing tab. The end-user already has a
    card on file; this gate is about contract terms, not card
    collection.

SDK consumers should switch on `reason` to render the right
prompt. For `free_tier_exceeded` and `twitter_passthrough`,
redirect the end-user to `dashboard_url` to add a payment method
via Zernio's hosted Stripe Setup Checkout. For
`enterprise_required`, redirect to `dashboard_url` (the
enterprise contact form) so they can talk to sales.


**Response Body:**

- **error** (required) `string`: 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** (required) `string`: Machine-readable error code. Stable across versions. - one of: PAYMENT_REQUIRED
- **reason** (required) `string`: Discriminator for which gate fired. - one of: free_tier_exceeded, twitter_passthrough, enterprise_required
- **documentation_url** `string` (uri): Link to the relevant documentation page. (example: "https://docs.zernio.com/billing/payment-method-required")
- **dashboard_url** `string` (uri): Deep-link to send the end-user to. For
`free_tier_exceeded` and `twitter_passthrough` this is
the Zernio billing tab. For `enterprise_required` this
is the Zernio enterprise contact page.
 (example: "https://zernio.com/dashboard?tab=billing")
- **details** `object`: Structured context for SDK clients that want to render their own UX. Keys vary by `reason`.
  - **free_tier_account_limit** `integer`: How many accounts the free tier allows. Only set when reason=free_tier_exceeded. (example: 2)
  - **current_account_count** `integer`: How many accounts the team currently has connected. Set when reason=free_tier_exceeded or reason=enterprise_required. (example: 5)
  - **has_payment_method** `boolean`: Whether the team currently has a card on file in Stripe. Set when reason=free_tier_exceeded or reason=twitter_passthrough.
  - **public_account_limit** `integer`: Public pricing ceiling (the published cap beyond which an enterprise contract is required). Only set when reason=enterprise_required. (example: 2000)
  - **effective_account_limit** `integer`: The cap actually applied to this team. Equals
`public_account_limit` for organic teams; for teams
with a per-customer override (grandfathered legacy
customers, signed enterprise contracts) this can
be higher. Only set when reason=enterprise_required.
 (example: 2000)

#### 403: No access to profile, or BYOK required for AppSumo Twitter

#### 404: Profile not found

---

## POST /v1/connect/{platform}

**Complete OAuth callback**

Exchange the OAuth authorization code for tokens and connect the account to the specified profile.

### Parameters

- **platform** (required) in path: No description

### Request Body

- **code** (required) `string`: No description
- **state** (required) `string`: No description
- **profileId** (required) `string`: No description

### Responses

#### 200: Account connected

#### 400: Invalid params

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: BYOK required for AppSumo Twitter

#### 500: Failed to connect account

---

---

# Connect Telegram directly API Reference

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.

## GET /v1/connect/telegram

**Generate Telegram code**

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

- **profileId** (required) in query: The profile ID to connect the Telegram account to

### Responses

#### 200: Access code generated

**Response Body:**

- **code** `string`: The access code to send to the Telegram bot (example: "ZRN-ABC123")
- **expiresAt** `string` (date-time): When the code expires
- **expiresIn** `integer`: Seconds until expiration (example: 900)
- **botUsername** `string`: The Telegram bot username to message (example: "LateScheduleBot")
- **instructions** `array[string]`: Step-by-step connection instructions

#### 400: Profile ID required or invalid format

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to this profile

#### 404: Profile not found

#### 500: Internal error

---

## POST /v1/connect/telegram

**Connect Telegram directly**

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.

### Request Body

- **chatId** (required) `string`: The Telegram chat ID. Numeric ID (e.g. "-1001234567890") or username with @ prefix (e.g. "@mychannel").
- **profileId** (required) `string`: The profile ID to connect the account to

### Responses

#### 200: Telegram channel connected successfully

**Response Body:**

- **message** `string`: No description
- **account** `object`: 
  - **_id** `string`: No description
  - **platform** `string`: No description - one of: telegram
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **isActive** `boolean`: No description
  - **chatType** `string`: No description - one of: channel, group, supergroup, private

#### 400: Chat ID required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to this profile

#### 404: Profile not found

#### 500: Internal error

---

## PATCH /v1/connect/telegram

**Check Telegram status**

Poll this endpoint to check if a Telegram access code has been used to connect a channel/group. Recommended polling interval: 3 seconds.
Status values: pending (waiting for user), connected (channel/group linked), expired (generate a new code).


### Parameters

- **code** (required) in query: The access code to check status for

### Responses

#### 200: Connection status

**Response Body:**

*One of the following:*
  - **status** `string`: No description - one of: pending
  - **expiresAt** `string` (date-time): No description
  - **expiresIn** `integer`: Seconds until expiration
  - **status** `string`: No description - one of: connected
  - **chatId** `string`: No description
  - **chatTitle** `string`: No description
  - **chatType** `string`: No description - one of: channel, group, supergroup
  - **account** `object`: 
    - **_id** `string`: No description
    - **platform** `string`: No description
    - **username** `string`: No description
    - **displayName** `string`: No description
  - **status** `string`: No description - one of: expired
  - **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Code not found

#### 500: Internal error

---

---

# List Facebook pages API Reference

Returns the list of Facebook Pages the user can manage after OAuth. Extract tempToken and userProfile from the OAuth redirect params and pass them here. Use the X-Connect-Token header if connecting via API key.

## GET /v1/connect/facebook/select-page

**List Facebook pages**

Returns the list of Facebook Pages the user can manage after OAuth. Extract tempToken and userProfile from the OAuth redirect params and pass them here. Use the X-Connect-Token header if connecting via API key.

### Parameters

- **profileId** (required) in query: Profile ID from your connection flow
- **tempToken** (required) in query: Temporary Facebook access token from the OAuth callback redirect

### Responses

#### 200: List of Facebook Pages available for connection

**Response Body:**

- **pages** `array[object]`: 
  - **id** `string`: Facebook Page ID
  - **name** `string`: Page name
  - **username** `string`: Page username/handle (may be null)
  - **access_token** `string`: Page-specific access token
  - **category** `string`: Page category
  - **tasks** `array[string]`: User permissions for this page

#### 400: Missing required parameters (profileId or tempToken)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Failed to fetch pages (e.g., invalid token, insufficient permissions)

**Response Body:**

- **error** `string`: No description

---

## POST /v1/connect/facebook/select-page

**Select Facebook page**

Complete the headless flow by saving the user's selected Facebook page. Pass the userProfile from the OAuth redirect and use X-Connect-Token if connecting via API key.

### Request Body

- **profileId** (required) `string`: Profile ID from your connection flow
- **pageId** (required) `string`: The Facebook Page ID selected by the user
- **tempToken** (required) `string`: Temporary Facebook access token from OAuth
- **userProfile** (required) `object`: Decoded user profile object from the OAuth callback
- **redirect_url** `string`: Optional custom redirect URL to return to after selection

### Responses

#### 200: Facebook Page connected successfully

**Response Body:**

- **message** `string`: No description
- **redirect_url** `string`: Redirect URL if custom redirect_url was provided
- **account** `object`: 
  - **accountId** `string`: ID of the created SocialAccount
  - **platform** `string`: No description - one of: facebook
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **profilePicture** `string`: No description
  - **isActive** `boolean`: No description
  - **selectedPageName** `string`: No description

#### 400: Missing required fields (profileId, pageId, tempToken, or userProfile)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: User does not have access to the specified profile

#### 404: Selected page not found in available pages

#### 500: Failed to save Facebook connection

---

---

# List GBP locations API Reference

For headless flows. Returns the list of GBP 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.


## GET /v1/connect/googlebusiness/locations

**List GBP locations**

For headless flows. Returns the list of GBP 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.


### Parameters

- **profileId** (optional) in query: Profile ID from your connection flow. Required for auth validation when provided.
- **pendingDataToken** (optional) in query: Token from the OAuth callback redirect. Preferred over tempToken because it preserves server-side token storage. One of pendingDataToken or tempToken is required.
- **tempToken** (optional) in query: Legacy. Direct Google access token. Use pendingDataToken instead when available.
- **search** (optional) in query: 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.

- **filter** (optional) in query: 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.


### Responses

#### 200: List of Google Business locations available for connection

**Response Body:**

- **locations** `array[object]`: 
  - **id** `string`: Location ID
  - **name** `string`: Business name
  - **accountId** `string`: Google Business Account ID
  - **accountName** `string`: Account name
  - **address** `string`: Business address
  - **category** `string`: Business category
  - **storeCode** `string`: Store code set on the location in Google Business Profile (if any)
- **hasMore** `boolean`: True when more locations exist than were returned (the list is bounded). Prompt the user to narrow the result set with search.


#### 400: Missing required parameters (profileId or tempToken)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Failed to fetch locations (e.g., invalid token, insufficient permissions)

**Response Body:**

- **error** `string`: No description

---

---

# List LinkedIn orgs API Reference

Fetch full LinkedIn organization details (logos, vanity names, websites) for custom UI. No authentication required, just the tempToken from OAuth.

## GET /v1/connect/linkedin/organizations

**List LinkedIn orgs**

Fetch full LinkedIn organization details (logos, vanity names, websites) for custom UI. No authentication required, just the tempToken from OAuth.

### Parameters

- **tempToken** (required) in query: The temporary LinkedIn access token from the OAuth redirect
- **orgIds** (required) in query: Comma-separated list of organization IDs to fetch details for (max 100)

### Responses

#### 200: Organization details fetched successfully

**Response Body:**

- **organizations** `array[object]`: 
  - **id** `string`: Organization ID
  - **logoUrl** `string` (uri): Logo URL (may be absent if no logo)
  - **vanityName** `string`: Organization's vanity name/slug
  - **website** `string` (uri): Organization's website URL
  - **industry** `string`: Organization's primary industry
  - **description** `string`: Organization's description

#### 400: Missing required parameters or too many organization IDs

**Response Body:**

- **error** `string`: No description

#### 500: Failed to fetch organization details

---

---

# List Pinterest boards API Reference

For headless flows. Returns Pinterest boards the user can post to. Use X-Connect-Token from the redirect URL.

## GET /v1/connect/pinterest/select-board

**List Pinterest boards**

For headless flows. Returns Pinterest boards the user can post to. Use X-Connect-Token from the redirect URL.

### Parameters

- **X-Connect-Token** (required) in header: Short-lived connect token from the OAuth redirect
- **profileId** (required) in query: Your Zernio profile ID
- **tempToken** (required) in query: Temporary Pinterest access token from the OAuth callback redirect

### Responses

#### 200: List of Pinterest Boards available for connection

**Response Body:**

- **boards** `array[object]`: 
  - **id** `string`: Pinterest Board ID
  - **name** `string`: Board name
  - **description** `string`: Board description
  - **privacy** `string`: Board privacy setting

#### 400: Missing required parameters

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to profile

#### 500: Failed to fetch boards

---

## POST /v1/connect/pinterest/select-board

**Select Pinterest board**

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.


### Request Body

- **profileId** (required) `string`: Your Zernio profile ID
- **boardId** (required) `string`: The Pinterest Board ID selected by the user
- **boardName** `string`: The board name (for display purposes)
- **tempToken** (required) `string`: Temporary Pinterest access token from OAuth
- **userProfile** `object`: User profile data from OAuth redirect
- **refreshToken** `string`: Pinterest refresh token (if available)
- **expiresIn** `integer`: Token expiration time in seconds
- **redirect_url** `string`: Custom redirect URL after connection completes

### Responses

#### 200: Pinterest Board connected successfully

**Response Body:**

- **message** `string`: No description
- **redirect_url** `string`: Redirect URL with connection params (if provided)
- **account** `object`: 
  - **accountId** `string`: ID of the created SocialAccount
  - **platform** `string`: No description - one of: pinterest
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **profilePicture** `string`: No description
  - **isActive** `boolean`: No description
  - **defaultBoardName** `string`: No description

#### 400: Missing required fields

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to profile or profile limit exceeded

#### 500: Failed to save Pinterest connection

---

---

# List Snapchat profiles API Reference

For headless flows. Returns Snapchat Public Profiles the user can post to. Use X-Connect-Token from the redirect URL.

## GET /v1/connect/snapchat/select-profile

**List Snapchat profiles**

For headless flows. Returns Snapchat Public Profiles the user can post to. Use X-Connect-Token from the redirect URL.

### Parameters

- **X-Connect-Token** (required) in header: Short-lived connect token from the OAuth redirect
- **profileId** (required) in query: Your Zernio profile ID
- **tempToken** (required) in query: Temporary Snapchat access token from the OAuth callback redirect

### Responses

#### 200: List of Snapchat Public Profiles available for connection

**Response Body:**

- **publicProfiles** `array[object]`: 
  - **id** `string`: Snapchat Public Profile ID
  - **display_name** `string`: Public profile display name
  - **username** `string`: Public profile username/handle
  - **profile_image_url** `string`: Profile image URL
  - **subscriber_count** `integer`: Number of subscribers

#### 400: Missing required parameters (profileId or tempToken)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to profile

#### 500: Failed to fetch public profiles

---

## POST /v1/connect/snapchat/select-profile

**Select Snapchat profile**

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

- **X-Connect-Token** (optional) in header: Short-lived connect token from the OAuth redirect (for API users)

### Request Body

- **profileId** (required) `string`: Your Zernio profile ID
- **selectedPublicProfile** (required) `object`: The selected Snapchat Public Profile
- **tempToken** (required) `string`: Temporary Snapchat access token from OAuth
- **userProfile** (required) `object`: User profile data from OAuth redirect
- **refreshToken** `string`: Snapchat refresh token (if available)
- **expiresIn** `integer`: Token expiration time in seconds
- **redirect_url** `string`: Custom redirect URL after connection completes

### Responses

#### 200: Snapchat Public Profile connected successfully

**Response Body:**

- **message** `string`: No description
- **redirect_url** `string`: Redirect URL with connection params (if provided in request)
- **account** `object`: 
  - **accountId** `string`: ID of the created SocialAccount
  - **platform** `string`: No description - one of: snapchat
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **profilePicture** `string`: No description
  - **isActive** `boolean`: No description
  - **publicProfileName** `string`: No description

#### 400: Missing required fields

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to profile or profile limit exceeded

#### 500: Failed to connect Snapchat account

---

---

# List WhatsApp phone numbers for selection API Reference

Fetch the WhatsApp phone numbers available across the user's WhatsApp Business Accounts (WABAs) after a headless OAuth flow.

WhatsApp 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.

Use the `profileId` and `tempToken` returned in the headless redirect (`step=select_phone_number`).

Alternative: if you already know `wabaId` and `phoneNumberId` (e.g. from Meta Business Suite), use `connectWhatsAppCredentials` instead, which skips this two-step flow.


## GET /v1/connect/whatsapp/select-phone-number

**List WhatsApp phone numbers for selection**

Fetch the WhatsApp phone numbers available across the user's WhatsApp Business Accounts (WABAs) after a headless OAuth flow.

WhatsApp 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.

Use the `profileId` and `tempToken` returned in the headless redirect (`step=select_phone_number`).

Alternative: if you already know `wabaId` and `phoneNumberId` (e.g. from Meta Business Suite), use `connectWhatsAppCredentials` instead, which skips this two-step flow.


### Parameters

- **profileId** (required) in query: The Zernio profile ID from the headless redirect
- **tempToken** (required) in query: The temporary access token from the headless redirect
- **X-Connect-Token** (optional) in header: Alternative auth for API users' end customers (used when the bearer token is scoped to a different user)

### Responses

#### 200: Phone numbers fetched successfully

**Response Body:**

- **phoneNumbers** `array[object]`: 
  - **id** `string`: Phone Number ID (Meta)
  - **display_phone_number** `string`: E.164-formatted display number
  - **verified_name** `string`: Meta-verified business name
  - **quality_rating** `string`: GREEN, YELLOW, RED, or UNKNOWN
  - **name_status** `string`: APPROVED, PENDING_REVIEW, DECLINED, or NONE
  - **messaging_limit_tier** `string`: TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED
  - **wabaId** `string`: WhatsApp Business Account ID (Zernio enrichment)
  - **wabaName** `string`: WABA display name (Zernio enrichment)

#### 400: Missing profileId or tempToken

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Failed to fetch phone numbers (Meta API error, expired token, or insufficient permissions)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## POST /v1/connect/whatsapp/select-phone-number

**Complete WhatsApp phone number selection**

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.


### Parameters

- **X-Connect-Token** (optional) in header: Alternative auth for API users' end customers

### Request Body

- **profileId** (required) `string`: The Zernio profile ID
- **phoneNumberId** (required) `string`: The selected phone number ID (from listWhatsAppPhoneNumbers)
- **wabaId** (required) `string`: The WABA ID containing the selected phone
- **tempToken** (required) `string`: The temporary access token from the headless redirect
- **userProfile** `object`: Optional user profile data (passthrough)
- **redirect_url** `string`: Optional URL to receive the post-connection redirect target

### Responses

#### 200: Phone number connected successfully

**Response Body:**

- **message** `string`: No description
- **redirect_url** `string`: Present only if redirect_url was provided in the request
- **account** `object`: 
  - **accountId** `string`: No description
  - **platform** `string`: No description - one of: whatsapp
  - **username** `string`: Display phone number
  - **displayName** `string`: Meta-verified business name
  - **isActive** `boolean`: No description
  - **selectedPhoneNumber** `string`: No description

#### 400: Missing required fields (profileId, phoneNumberId, wabaId, or tempToken)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Profile limit exceeded for the user's plan (PROFILE_LIMIT_EXCEEDED)

#### 404: Selected phone number not found in the specified WABA

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 500: Failed to bind phone number

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Select Facebook page API Reference

Complete the headless flow by saving the user's selected Facebook page. Pass the userProfile from the OAuth redirect and use X-Connect-Token if connecting via API key.

## GET /v1/connect/facebook/select-page

**List Facebook pages**

Returns the list of Facebook Pages the user can manage after OAuth. Extract tempToken and userProfile from the OAuth redirect params and pass them here. Use the X-Connect-Token header if connecting via API key.

### Parameters

- **profileId** (required) in query: Profile ID from your connection flow
- **tempToken** (required) in query: Temporary Facebook access token from the OAuth callback redirect

### Responses

#### 200: List of Facebook Pages available for connection

**Response Body:**

- **pages** `array[object]`: 
  - **id** `string`: Facebook Page ID
  - **name** `string`: Page name
  - **username** `string`: Page username/handle (may be null)
  - **access_token** `string`: Page-specific access token
  - **category** `string`: Page category
  - **tasks** `array[string]`: User permissions for this page

#### 400: Missing required parameters (profileId or tempToken)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Failed to fetch pages (e.g., invalid token, insufficient permissions)

**Response Body:**

- **error** `string`: No description

---

## POST /v1/connect/facebook/select-page

**Select Facebook page**

Complete the headless flow by saving the user's selected Facebook page. Pass the userProfile from the OAuth redirect and use X-Connect-Token if connecting via API key.

### Request Body

- **profileId** (required) `string`: Profile ID from your connection flow
- **pageId** (required) `string`: The Facebook Page ID selected by the user
- **tempToken** (required) `string`: Temporary Facebook access token from OAuth
- **userProfile** (required) `object`: Decoded user profile object from the OAuth callback
- **redirect_url** `string`: Optional custom redirect URL to return to after selection

### Responses

#### 200: Facebook Page connected successfully

**Response Body:**

- **message** `string`: No description
- **redirect_url** `string`: Redirect URL if custom redirect_url was provided
- **account** `object`: 
  - **accountId** `string`: ID of the created SocialAccount
  - **platform** `string`: No description - one of: facebook
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **profilePicture** `string`: No description
  - **isActive** `boolean`: No description
  - **selectedPageName** `string`: No description

#### 400: Missing required fields (profileId, pageId, tempToken, or userProfile)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: User does not have access to the specified profile

#### 404: Selected page not found in available pages

#### 500: Failed to save Facebook connection

---

---

# Select GBP location API Reference

Complete the headless GBP 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.


## POST /v1/connect/googlebusiness/select-location

**Select GBP location**

Complete the headless GBP 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.


### Request Body

- **profileId** (required) `string`: Profile ID from your connection flow
- **locationId** (required) `string`: The Google Business location ID selected by the user
- **accountId** `string`: Optional but recommended. The Google Business 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.

- **pendingDataToken** (required) `string`: Token from the OAuth callback redirect (pendingDataToken query param). Tokens and profile data are retrieved server-side from this token.
- **redirect_url** `string`: Optional custom redirect URL to return to after selection

### Responses

#### 200: Google Business location connected successfully

**Response Body:**

- **message** `string`: No description
- **redirect_url** `string`: Redirect URL if custom redirect_url was provided
- **account** `object`: 
  - **accountId** `string`: ID of the created SocialAccount
  - **platform** `string`: No description - one of: googlebusiness
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **isActive** `boolean`: No description
  - **selectedLocationName** `string`: No description
  - **selectedLocationId** `string`: No description

#### 400: Missing required fields (profileId, locationId, or tempToken)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: User does not have access to the specified profile

#### 404: Selected location not found in available locations

#### 500: Failed to save Google Business connection

---

---

# Select LinkedIn org API Reference

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.

## POST /v1/connect/linkedin/select-organization

**Select LinkedIn org**

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.

### Request Body

- **profileId** (required) `string`: No description
- **tempToken** (required) `string`: No description
- **userProfile** (required) `object`: No description
- **accountType** (required) `string`: No description - one of: personal, organization
- **selectedOrganization** `object`: No description
- **redirect_url** `string`: No description

### Responses

#### 200: LinkedIn account connected

**Response Body:**

- **message** `string`: No description
- **redirect_url** `string`: The redirect URL with connection params appended (only if redirect_url was provided in request)
- **account** `object`: 
  - **accountId** `string`: ID of the created SocialAccount
  - **platform** `string`: No description - one of: linkedin
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **profilePicture** `string`: No description
  - **isActive** `boolean`: No description
  - **accountType** `string`: No description - one of: personal, organization
- **bulkRefresh** `object`: 
  - **updatedCount** `integer`: No description
  - **errors** `integer`: No description

#### 400: Missing required fields

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Failed to connect LinkedIn account

---

---

# Select Pinterest board API Reference

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.


## GET /v1/connect/pinterest/select-board

**List Pinterest boards**

For headless flows. Returns Pinterest boards the user can post to. Use X-Connect-Token from the redirect URL.

### Parameters

- **X-Connect-Token** (required) in header: Short-lived connect token from the OAuth redirect
- **profileId** (required) in query: Your Zernio profile ID
- **tempToken** (required) in query: Temporary Pinterest access token from the OAuth callback redirect

### Responses

#### 200: List of Pinterest Boards available for connection

**Response Body:**

- **boards** `array[object]`: 
  - **id** `string`: Pinterest Board ID
  - **name** `string`: Board name
  - **description** `string`: Board description
  - **privacy** `string`: Board privacy setting

#### 400: Missing required parameters

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to profile

#### 500: Failed to fetch boards

---

## POST /v1/connect/pinterest/select-board

**Select Pinterest board**

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.


### Request Body

- **profileId** (required) `string`: Your Zernio profile ID
- **boardId** (required) `string`: The Pinterest Board ID selected by the user
- **boardName** `string`: The board name (for display purposes)
- **tempToken** (required) `string`: Temporary Pinterest access token from OAuth
- **userProfile** `object`: User profile data from OAuth redirect
- **refreshToken** `string`: Pinterest refresh token (if available)
- **expiresIn** `integer`: Token expiration time in seconds
- **redirect_url** `string`: Custom redirect URL after connection completes

### Responses

#### 200: Pinterest Board connected successfully

**Response Body:**

- **message** `string`: No description
- **redirect_url** `string`: Redirect URL with connection params (if provided)
- **account** `object`: 
  - **accountId** `string`: ID of the created SocialAccount
  - **platform** `string`: No description - one of: pinterest
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **profilePicture** `string`: No description
  - **isActive** `boolean`: No description
  - **defaultBoardName** `string`: No description

#### 400: Missing required fields

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to profile or profile limit exceeded

#### 500: Failed to save Pinterest connection

---

---

# Select Snapchat profile API Reference

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.

## GET /v1/connect/snapchat/select-profile

**List Snapchat profiles**

For headless flows. Returns Snapchat Public Profiles the user can post to. Use X-Connect-Token from the redirect URL.

### Parameters

- **X-Connect-Token** (required) in header: Short-lived connect token from the OAuth redirect
- **profileId** (required) in query: Your Zernio profile ID
- **tempToken** (required) in query: Temporary Snapchat access token from the OAuth callback redirect

### Responses

#### 200: List of Snapchat Public Profiles available for connection

**Response Body:**

- **publicProfiles** `array[object]`: 
  - **id** `string`: Snapchat Public Profile ID
  - **display_name** `string`: Public profile display name
  - **username** `string`: Public profile username/handle
  - **profile_image_url** `string`: Profile image URL
  - **subscriber_count** `integer`: Number of subscribers

#### 400: Missing required parameters (profileId or tempToken)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to profile

#### 500: Failed to fetch public profiles

---

## POST /v1/connect/snapchat/select-profile

**Select Snapchat profile**

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

- **X-Connect-Token** (optional) in header: Short-lived connect token from the OAuth redirect (for API users)

### Request Body

- **profileId** (required) `string`: Your Zernio profile ID
- **selectedPublicProfile** (required) `object`: The selected Snapchat Public Profile
- **tempToken** (required) `string`: Temporary Snapchat access token from OAuth
- **userProfile** (required) `object`: User profile data from OAuth redirect
- **refreshToken** `string`: Snapchat refresh token (if available)
- **expiresIn** `integer`: Token expiration time in seconds
- **redirect_url** `string`: Custom redirect URL after connection completes

### Responses

#### 200: Snapchat Public Profile connected successfully

**Response Body:**

- **message** `string`: No description
- **redirect_url** `string`: Redirect URL with connection params (if provided in request)
- **account** `object`: 
  - **accountId** `string`: ID of the created SocialAccount
  - **platform** `string`: No description - one of: snapchat
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **profilePicture** `string`: No description
  - **isActive** `boolean`: No description
  - **publicProfileName** `string`: No description

#### 400: Missing required fields

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: No access to profile or profile limit exceeded

#### 500: Failed to connect Snapchat account

---

---

# Update Facebook page API Reference

Switch which Facebook Page is active for a connected account.

## GET /v1/accounts/{accountId}/facebook-page

**List Facebook pages**

Returns all Facebook pages the connected account has access to, including the currently selected page.

### Parameters

- **accountId** (required) in path: No description
- **refresh** (optional) in query: 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.


### Responses

#### 200: Pages list

**Response Body:**

- **pages** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **username** `string`: No description
  - **category** `string`: No description
  - **fan_count** `integer`: No description
- **selectedPageId** `string`: No description
- **cached** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## PUT /v1/accounts/{accountId}/facebook-page

**Update Facebook page**

Switch which Facebook Page is active for a connected account.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **selectedPageId** (required) `string`: No description

### Responses

#### 200: Page updated

**Response Body:**

- **message** `string`: No description
- **selectedPage** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description

#### 400: Page not in available pages

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Update GBP location API Reference

Switch which GBP location is active for a connected account.

## GET /v1/accounts/{accountId}/gmb-locations

**List GBP locations**

Returns Google Business Profile locations the connected account can access, plus the currently selected location. The list is bounded (see hasMore); for accounts that own many locations, use the search or filter query params to find a specific one instead of loading them all.


### Parameters

- **accountId** (required) in path: No description
- **search** (optional) in query: Free-text search on the business name, applied server-side by Google. Use for accounts with many locations.
- **filter** (optional) in query: Raw Google Business Information API filter expression (advanced; takes precedence over search), e.g. storeCode="LH279411".

### Responses

#### 200: Locations list

**Response Body:**

- **locations** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **accountId** `string`: No description
  - **accountName** `string`: No description
  - **address** `string`: No description
  - **category** `string`: No description
  - **websiteUrl** `string`: No description
  - **storeCode** `string`: No description
- **hasMore** `boolean`: True when more locations exist than were returned (use search to narrow down).
- **selectedLocationId** `string`: No description
- **cached** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## PUT /v1/accounts/{accountId}/gmb-locations

**Update GBP location**

Switch which GBP location is active for a connected account.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **selectedLocationId** (required) `string`: No description
- **googleAccountId** `string`: Optional but recommended. The Google Business Account resource name ("accounts/123") that owns the new location (from GET gmb-locations). When provided, the location is resolved directly instead of by enumerating the account, which is required for accounts with many locations. Named `googleAccountId` to disambiguate from the path `accountId` (the Zernio account). The legacy field name `accountId` is still accepted for backwards compatibility.


### Responses

#### 200: Location updated

**Response Body:**

- **message** `string`: No description
- **selectedLocation** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description

#### 400: Location not in available locations

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Switch LinkedIn account type API Reference

Switch a LinkedIn account between personal profile and organization (company page) posting.

## PUT /v1/accounts/{accountId}/linkedin-organization

**Switch LinkedIn account type**

Switch a LinkedIn account between personal profile and organization (company page) posting.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **accountType** (required) `string`: No description - one of: personal, organization
- **selectedOrganization** `object`: No description

### Responses

#### 200: Account updated

**Response Body:**

- **message** `string`: No description
- **account**: `SocialAccount` - See schema definition

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---


# Related Schema Definitions

## SocialAccount

### Properties

- **_id** (required) `string`: No description
- **platform** (required) `string`: No description - one of: tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, discord, whatsapp, linkedinads, metaads, pinterestads, tiktokads, xads, googleads
- **profileId** (required): No description
- **username** `string`: No description
- **displayName** `string`: No description
- **profilePicture** `string`: URL to the account's profile picture on the platform. May be null if the platform does not provide one.
- **profileUrl** `string`: Full profile URL for the connected account on its platform.
- **isActive** (required) `boolean`: No description
- **followersCount** `number`: Follower count (only included if user has analytics add-on)
- **followersLastUpdated** `string`: Last time follower count was updated (only included if user has analytics add-on)
- **parentAccountId** `string`: Reference to the parent posting SocialAccount. Set for ads accounts that share
or derive from a posting account's OAuth token. null for standalone ads (Google Ads)
and all posting accounts.

- **enabled** `boolean`: Whether the user explicitly activated this account. false means the account was
created as a side effect (e.g., posting account auto-created when user connected
ads first). Posting UI and scheduler ignore accounts with enabled: false.

- **metadata** `object`: Platform-specific metadata. Fields vary by platform. For WhatsApp accounts, includes:
- qualityRating: Phone number quality rating from Meta (GREEN, YELLOW, RED, or UNKNOWN)
- nameStatus: Display name review status (APPROVED, PENDING_REVIEW, DECLINED, or NONE). Messages cannot be sent until the display name is approved by Meta.
- messagingLimitTier: Maximum unique business-initiated conversations per 24h rolling window (TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED). Scales automatically as quality rating improves.
- verifiedName: Meta-verified business display name
- displayPhoneNumber: Formatted phone number (e.g., "+1 555-123-4567")
- wabaId: WhatsApp Business Account ID
- phoneNumberId: Meta phone number ID

---

# Set default Pinterest board API Reference

Sets the default board used when publishing pins for this account.

## GET /v1/accounts/{accountId}/pinterest-boards

**List Pinterest boards**

Returns the boards available for a connected Pinterest account. Use this to get a board ID when creating a Pinterest post.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Boards list

**Response Body:**

- **boards** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **privacy** `string`: No description

#### 400: Not a Pinterest account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## PUT /v1/accounts/{accountId}/pinterest-boards

**Set default Pinterest board**

Sets the default board used when publishing pins for this account.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **defaultBoardId** (required) `string`: No description
- **defaultBoardName** `string`: No description

### Responses

#### 200: Default board set

**Response Body:**

- **message** `string`: No description
- **account**: `SocialAccount` - See schema definition

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---


# Related Schema Definitions

## SocialAccount

### Properties

- **_id** (required) `string`: No description
- **platform** (required) `string`: No description - one of: tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, discord, whatsapp, linkedinads, metaads, pinterestads, tiktokads, xads, googleads
- **profileId** (required): No description
- **username** `string`: No description
- **displayName** `string`: No description
- **profilePicture** `string`: URL to the account's profile picture on the platform. May be null if the platform does not provide one.
- **profileUrl** `string`: Full profile URL for the connected account on its platform.
- **isActive** (required) `boolean`: No description
- **followersCount** `number`: Follower count (only included if user has analytics add-on)
- **followersLastUpdated** `string`: Last time follower count was updated (only included if user has analytics add-on)
- **parentAccountId** `string`: Reference to the parent posting SocialAccount. Set for ads accounts that share
or derive from a posting account's OAuth token. null for standalone ads (Google Ads)
and all posting accounts.

- **enabled** `boolean`: Whether the user explicitly activated this account. false means the account was
created as a side effect (e.g., posting account auto-created when user connected
ads first). Posting UI and scheduler ignore accounts with enabled: false.

- **metadata** `object`: Platform-specific metadata. Fields vary by platform. For WhatsApp accounts, includes:
- qualityRating: Phone number quality rating from Meta (GREEN, YELLOW, RED, or UNKNOWN)
- nameStatus: Display name review status (APPROVED, PENDING_REVIEW, DECLINED, or NONE). Messages cannot be sent until the display name is approved by Meta.
- messagingLimitTier: Maximum unique business-initiated conversations per 24h rolling window (TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED). Scales automatically as quality rating improves.
- verifiedName: Meta-verified business display name
- displayPhoneNumber: Formatted phone number (e.g., "+1 555-123-4567")
- wabaId: WhatsApp Business Account ID
- phoneNumberId: Meta phone number ID

---

# Set default subreddit API Reference

Sets the default subreddit used when publishing posts for this Reddit account.

## GET /v1/accounts/{accountId}/reddit-subreddits

**List Reddit subreddits**

Returns the subreddits the connected Reddit account can post to. Use this to get a subreddit name when creating a Reddit post.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Subreddits list

**Response Body:**

- **subreddits** `array[object]`: 
  - **id** `string`: Reddit subreddit ID
  - **name** `string`: Subreddit name without r/ prefix
  - **title** `string`: Subreddit title
  - **url** `string`: Subreddit URL path
  - **over18** `boolean`: Whether the subreddit is NSFW
- **defaultSubreddit** `string`: Currently set default subreddit for posting

#### 400: Not a Reddit account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## PUT /v1/accounts/{accountId}/reddit-subreddits

**Set default subreddit**

Sets the default subreddit used when publishing posts for this Reddit account.

### Parameters

- **accountId** (required) in path: No description

### Request Body

- **defaultSubreddit** (required) `string`: No description

### Responses

#### 200: Default subreddit set

**Response Body:**

- **success** `boolean`: No description

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Set default YouTube playlist API Reference

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).

## GET /v1/accounts/{accountId}/youtube-playlists

**List YouTube playlists**

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

- **accountId** (required) in path: No description

### Responses

#### 200: Playlists list

**Response Body:**

- **playlists** `array[object]`: 
  - **id** `string`: No description
  - **title** `string`: No description
  - **description** `string`: No description
  - **privacy** `string`: No description - one of: public, private, unlisted
  - **itemCount** `integer`: No description
  - **thumbnailUrl** `string`: No description
- **defaultPlaylistId** `string`: No description

#### 400: Not a YouTube account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## PUT /v1/accounts/{accountId}/youtube-playlists

**Set default YouTube playlist**

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

- **accountId** (required) in path: No description

### Request Body

- **defaultPlaylistId** (required) `string`: No description
- **defaultPlaylistName** `string`: No description

### Responses

#### 200: Default playlist set

**Response Body:**

- **success** `boolean`: No description

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Clear custom field value API Reference

Remove a custom field value from a contact. The field definition is not affected.

## PUT /v1/contacts/{contactId}/fields/{slug}

**Set custom field value**

Set or overwrite a custom field value on a contact. The value type must match the field definition.

### Parameters

- **contactId** (required) in path: No description
- **slug** (required) in path: No description

### Request Body

- **value** (required): Field value (type depends on field definition)

### Responses

#### 200: Field value set

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/contacts/{contactId}/fields/{slug}

**Clear custom field value**

Remove a custom field value from a contact. The field definition is not affected.

### Parameters

- **contactId** (required) in path: No description
- **slug** (required) in path: No description

### Responses

#### 200: Field value cleared

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Create custom field API Reference

Create a new custom field definition. Supported types are text, number, date, boolean, and select.

## GET /v1/custom-fields

**List custom field definitions**

Returns all custom field definitions. Optionally filter by profile.

### Parameters

- **profileId** (optional) in query: Filter by profile. Omit to list across all profiles

### Responses

#### 200: List of custom field definitions

**Response Body:**

- **success** `boolean`: No description
- **fields** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **slug** `string`: No description
  - **type** `string`: No description - one of: text, number, date, boolean, select
  - **options** `array[string]`: 
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/custom-fields

**Create custom field**

Create a new custom field definition. Supported types are text, number, date, boolean, and select.

### Request Body

- **profileId** (required) `string`: No description
- **name** (required) `string`: No description
- **slug** `string`: Auto-generated from name if not provided
- **type** (required) `string`: No description - one of: text, number, date, boolean, select
- **options** `array`: Required for select type

### Responses

#### 200: Custom field created

**Response Body:**

- **success** `boolean`: No description
- **field** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **slug** `string`: No description
  - **type** `string`: No description - one of: text, number, date, boolean, select
  - **options** `array[string]`: 
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 409: Duplicate slug

---

---

# Delete custom field API Reference

Delete a custom field definition and remove its values from all contacts.

## PATCH /v1/custom-fields/{fieldId}

**Update custom field**

Update a custom field definition. The field type cannot be changed after creation.

### Parameters

- **fieldId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **options** `array`: No description

### Responses

#### 200: Custom field updated

**Response Body:**

- **success** `boolean`: No description
- **field** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **slug** `string`: No description
  - **type** `string`: No description
  - **options** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/custom-fields/{fieldId}

**Delete custom field**

Delete a custom field definition and remove its values from all contacts.

### Parameters

- **fieldId** (required) in path: No description

### Responses

#### 200: Custom field deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List custom field definitions API Reference

Returns all custom field definitions. Optionally filter by profile.

## GET /v1/custom-fields

**List custom field definitions**

Returns all custom field definitions. Optionally filter by profile.

### Parameters

- **profileId** (optional) in query: Filter by profile. Omit to list across all profiles

### Responses

#### 200: List of custom field definitions

**Response Body:**

- **success** `boolean`: No description
- **fields** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **slug** `string`: No description
  - **type** `string`: No description - one of: text, number, date, boolean, select
  - **options** `array[string]`: 
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/custom-fields

**Create custom field**

Create a new custom field definition. Supported types are text, number, date, boolean, and select.

### Request Body

- **profileId** (required) `string`: No description
- **name** (required) `string`: No description
- **slug** `string`: Auto-generated from name if not provided
- **type** (required) `string`: No description - one of: text, number, date, boolean, select
- **options** `array`: Required for select type

### Responses

#### 200: Custom field created

**Response Body:**

- **success** `boolean`: No description
- **field** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **slug** `string`: No description
  - **type** `string`: No description - one of: text, number, date, boolean, select
  - **options** `array[string]`: 
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 409: Duplicate slug

---

---

# Set custom field value API Reference

Set or overwrite a custom field value on a contact. The value type must match the field definition.

## PUT /v1/contacts/{contactId}/fields/{slug}

**Set custom field value**

Set or overwrite a custom field value on a contact. The value type must match the field definition.

### Parameters

- **contactId** (required) in path: No description
- **slug** (required) in path: No description

### Request Body

- **value** (required): Field value (type depends on field definition)

### Responses

#### 200: Field value set

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/contacts/{contactId}/fields/{slug}

**Clear custom field value**

Remove a custom field value from a contact. The field definition is not affected.

### Parameters

- **contactId** (required) in path: No description
- **slug** (required) in path: No description

### Responses

#### 200: Field value cleared

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Update custom field API Reference

Update a custom field definition. The field type cannot be changed after creation.

## PATCH /v1/custom-fields/{fieldId}

**Update custom field**

Update a custom field definition. The field type cannot be changed after creation.

### Parameters

- **fieldId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **options** `array`: No description

### Responses

#### 200: Custom field updated

**Response Body:**

- **success** `boolean`: No description
- **field** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **slug** `string`: No description
  - **type** `string`: No description
  - **options** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/custom-fields/{fieldId}

**Delete custom field**

Delete a custom field definition and remove its values from all contacts.

### Parameters

- **fieldId** (required) in path: No description

### Responses

#### 200: Custom field deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Assign a role to a guild member API Reference

Assign one role to one member. Idempotent on Discord's side — re-running
on a member who already has the role is a 204 no-op.

Path shape mirrors Discord's own API (`PUT /guilds/{guild}/members/{user}/roles/{role}`)
for zero-translation mental mapping.

Bot needs MANAGE_ROLES permission in the guild AND its highest role
must be above the target role (Discord hierarchy rule). The
`@everyone` role (where roleId == guildId) cannot be assigned.


## PUT /v1/discord/guilds/{guildId}/members/{userId}/roles/{roleId}

**Assign a role to a guild member**

Assign one role to one member. Idempotent on Discord's side — re-running
on a member who already has the role is a 204 no-op.

Path shape mirrors Discord's own API (`PUT /guilds/{guild}/members/{user}/roles/{role}`)
for zero-translation mental mapping.

Bot needs MANAGE_ROLES permission in the guild AND its highest role
must be above the target role (Discord hierarchy rule). The
`@everyone` role (where roleId == guildId) cannot be assigned.


### Parameters

- **guildId** (required) in path: No description
- **userId** (required) in path: Discord user snowflake to assign the role to.
- **roleId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Role assigned (or already present — idempotent).

**Response Body:**

- **success** `boolean`: No description
- **operation** `string`: No description - one of: role_assigned
- **guildId** `string`: No description
- **userId** `string`: No description
- **roleId** `string`: No description

#### 400: Validation error (malformed snowflake) or @everyone manipulation attempt.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found or not in this guild.

#### 502: Discord rejected the request: bot lacks MANAGE_ROLES, or target role is above the bot's highest role.

---

## DELETE /v1/discord/guilds/{guildId}/members/{userId}/roles/{roleId}

**Remove a role from a guild member**

Remove one role from one member. Idempotent — removing a role the
member doesn't have returns 204 no-op.

Same permission + hierarchy constraints as the PUT counterpart.


### Parameters

- **guildId** (required) in path: No description
- **userId** (required) in path: No description
- **roleId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Role removed (or was already absent — idempotent).

**Response Body:**

- **success** `boolean`: No description
- **operation** `string`: No description - one of: role_removed
- **guildId** `string`: No description
- **userId** `string`: No description
- **roleId** `string`: No description

#### 400: Validation error.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found or not in this guild.

#### 502: Discord rejected the request (permission or hierarchy issue).

---

---

# Create a Discord scheduled event API Reference

Create a guild scheduled event. Three event types, selected via the
discriminator on `entity.type`:

  - `external` — off-platform (Zoom, in-person, livestream). Requires
    both `location` and `endsAt`. Most common type for scheduler
    integrations.
  - `voice` — hosted in a Discord voice channel. Requires `channelId`.
  - `stage` — hosted in a Discord stage channel. Requires `channelId`.

Bot needs MANAGE_EVENTS in the guild. Existing installs (pre-events
PR) need a re-invite OR a server admin manually granting the
permission — see route header for details.


## GET /v1/discord/guilds/{guildId}/events

**List Discord scheduled events**

Return all scheduled events in the guild. Events are distinct from
messages — they appear in the server's Events panel and Discord
auto-notifies interested members ahead of start time.

Pass `withUserCount=true` to include `user_count` (number of members
who RSVP'd) on each event. Useful for surfacing engagement.


### Parameters

- **guildId** (required) in path: No description
- **accountId** (required) in query: No description
- **withUserCount** (optional) in query: Include user_count on each event.

### Responses

#### 200: List of scheduled events.

**Response Body:**

- **data** `array[DiscordScheduledEvent]`: 

#### 400: Invalid params.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found or not in this guild.

#### 502: Bot lacks access to the guild's events.

---

## POST /v1/discord/guilds/{guildId}/events

**Create a Discord scheduled event**

Create a guild scheduled event. Three event types, selected via the
discriminator on `entity.type`:

  - `external` — off-platform (Zoom, in-person, livestream). Requires
    both `location` and `endsAt`. Most common type for scheduler
    integrations.
  - `voice` — hosted in a Discord voice channel. Requires `channelId`.
  - `stage` — hosted in a Discord stage channel. Requires `channelId`.

Bot needs MANAGE_EVENTS in the guild. Existing installs (pre-events
PR) need a re-invite OR a server admin manually granting the
permission — see route header for details.


### Parameters

- **guildId** (required) in path: No description

### Request Body

- **accountId** (required) `string`: No description
- **name** (required) `string`: No description
- **description** `string`: No description
- **startsAt** (required) `string`: ISO 8601 start time. Must be in the future.
- **entity**: Platform-specific settings (see schema definitions below)
- **imageDataUri** `string`: Optional cover image as a base64 data URI.

### Responses

#### 200: Event created.

**Response Body:**

- **data**: `DiscordScheduledEvent` - See schema definition

#### 400: Validation error (missing required fields for the chosen entity type, malformed snowflake, past startsAt, etc.).

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found.

#### 502: Bot lacks MANAGE_EVENTS in the guild.

---


# Related Schema Definitions

## DiscordScheduledEvent

Discord guild scheduled event. Returned by /v1/discord/guilds/{guildId}/events endpoints.
Fields below are the subset Zernio consumes — Discord may return more (e.g. creator,
image hash) which we pass through verbatim.


### Properties

- **id** `string`: Event snowflake ID
- **guild_id** `string`: No description
- **channel_id** `string`: Voice/stage channel ID; null for external events.
- **creator_id** `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **scheduled_start_time** `string`: No description
- **scheduled_end_time** `string`: Required for external events; optional for voice/stage.
- **privacy_level** `integer`: Always 2 (GUILD_ONLY) — Discord deprecated PUBLIC events. - one of: 2
- **status** `integer`: 1=SCHEDULED, 2=ACTIVE, 3=COMPLETED, 4=CANCELED - one of: 1, 2, 3, 4
- **entity_type** `integer`: 1=STAGE_INSTANCE, 2=VOICE, 3=EXTERNAL - one of: 1, 2, 3
- **entity_id** `string`: No description
- **entity_metadata** `object`: 
  - **location** `string`: External event location string.
- **user_count** `integer`: Number of members who RSVP'd. Only present when withUserCount=true on list.
- **image** `string`: Cover image hash; build URL via cdn.discordapp.com.

---

# Delete a Discord scheduled event API Reference

Hard-delete an event. Use PATCH with `status: 'cancelled'` instead
if you want the event preserved in the guild's history.


## GET /v1/discord/guilds/{guildId}/events/{eventId}

**Get a Discord scheduled event**

### Parameters

- **guildId** (required) in path: No description
- **eventId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Event.

**Response Body:**

- **data**: `DiscordScheduledEvent` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Event or Discord account not found.

---

## PATCH /v1/discord/guilds/{guildId}/events/{eventId}

**Update a Discord scheduled event**

Patch any subset of fields. Passing `status: 'cancelled'` is how you
cancel an event — Discord doesn't have a dedicated cancel endpoint,
it's a status transition.

Most status transitions Discord enforces (you can't go SCHEDULED →
COMPLETED directly). The common consumer case is SCHEDULED → CANCELED.


### Parameters

- **guildId** (required) in path: No description
- **eventId** (required) in path: No description

### Request Body

- **accountId** (required) `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **startsAt** `string`: No description
- **endsAt** `string`: No description
- **location** `string`: For external events.
- **status** `string`: Status transition. Most common: 'cancelled' to cancel an event. - one of: scheduled, active, completed, cancelled
- **imageDataUri** `string`: No description

### Responses

#### 200: Event updated.

**Response Body:**

- **data**: `DiscordScheduledEvent` - See schema definition

#### 400: Validation error, OR no updatable fields beyond accountId provided.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Event or Discord account not found.

#### 502: Discord rejected the update (invalid status transition

---

## DELETE /v1/discord/guilds/{guildId}/events/{eventId}

**Delete a Discord scheduled event**

Hard-delete an event. Use PATCH with `status: 'cancelled'` instead
if you want the event preserved in the guild's history.


### Parameters

- **guildId** (required) in path: No description
- **eventId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Event deleted.

**Response Body:**

- **success** `boolean`: No description
- **deleted** `string`: The deleted event's snowflake.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Event or Discord account not found.

#### 502: Bot lacks MANAGE_EVENTS in the guild.

---


# Related Schema Definitions

## DiscordScheduledEvent

Discord guild scheduled event. Returned by /v1/discord/guilds/{guildId}/events endpoints.
Fields below are the subset Zernio consumes — Discord may return more (e.g. creator,
image hash) which we pass through verbatim.


### Properties

- **id** `string`: Event snowflake ID
- **guild_id** `string`: No description
- **channel_id** `string`: Voice/stage channel ID; null for external events.
- **creator_id** `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **scheduled_start_time** `string`: No description
- **scheduled_end_time** `string`: Required for external events; optional for voice/stage.
- **privacy_level** `integer`: Always 2 (GUILD_ONLY) — Discord deprecated PUBLIC events. - one of: 2
- **status** `integer`: 1=SCHEDULED, 2=ACTIVE, 3=COMPLETED, 4=CANCELED - one of: 1, 2, 3, 4
- **entity_type** `integer`: 1=STAGE_INSTANCE, 2=VOICE, 3=EXTERNAL - one of: 1, 2, 3
- **entity_id** `string`: No description
- **entity_metadata** `object`: 
  - **location** `string`: External event location string.
- **user_count** `integer`: Number of members who RSVP'd. Only present when withUserCount=true on list.
- **image** `string`: Cover image hash; build URL via cdn.discordapp.com.

---

# List Discord guild channels API Reference

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.

## GET /v1/accounts/{accountId}/discord-channels

**List Discord guild channels**

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

- **accountId** (required) in path: No description

### Responses

#### 200: Channel list

**Response Body:**

- **channels** `array[object]`: 
  - **id** `string`: Channel snowflake ID
  - **name** `string`: Channel name
  - **type** `integer`: Channel type: 0 (text), 5 (announcement), 15 (forum)

#### 400: Not a Discord account or missing guild info

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Get a Discord scheduled event API Reference



## GET /v1/discord/guilds/{guildId}/events/{eventId}

**Get a Discord scheduled event**

### Parameters

- **guildId** (required) in path: No description
- **eventId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Event.

**Response Body:**

- **data**: `DiscordScheduledEvent` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Event or Discord account not found.

---

## PATCH /v1/discord/guilds/{guildId}/events/{eventId}

**Update a Discord scheduled event**

Patch any subset of fields. Passing `status: 'cancelled'` is how you
cancel an event — Discord doesn't have a dedicated cancel endpoint,
it's a status transition.

Most status transitions Discord enforces (you can't go SCHEDULED →
COMPLETED directly). The common consumer case is SCHEDULED → CANCELED.


### Parameters

- **guildId** (required) in path: No description
- **eventId** (required) in path: No description

### Request Body

- **accountId** (required) `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **startsAt** `string`: No description
- **endsAt** `string`: No description
- **location** `string`: For external events.
- **status** `string`: Status transition. Most common: 'cancelled' to cancel an event. - one of: scheduled, active, completed, cancelled
- **imageDataUri** `string`: No description

### Responses

#### 200: Event updated.

**Response Body:**

- **data**: `DiscordScheduledEvent` - See schema definition

#### 400: Validation error, OR no updatable fields beyond accountId provided.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Event or Discord account not found.

#### 502: Discord rejected the update (invalid status transition

---

## DELETE /v1/discord/guilds/{guildId}/events/{eventId}

**Delete a Discord scheduled event**

Hard-delete an event. Use PATCH with `status: 'cancelled'` instead
if you want the event preserved in the guild's history.


### Parameters

- **guildId** (required) in path: No description
- **eventId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Event deleted.

**Response Body:**

- **success** `boolean`: No description
- **deleted** `string`: The deleted event's snowflake.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Event or Discord account not found.

#### 502: Bot lacks MANAGE_EVENTS in the guild.

---


# Related Schema Definitions

## DiscordScheduledEvent

Discord guild scheduled event. Returned by /v1/discord/guilds/{guildId}/events endpoints.
Fields below are the subset Zernio consumes — Discord may return more (e.g. creator,
image hash) which we pass through verbatim.


### Properties

- **id** `string`: Event snowflake ID
- **guild_id** `string`: No description
- **channel_id** `string`: Voice/stage channel ID; null for external events.
- **creator_id** `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **scheduled_start_time** `string`: No description
- **scheduled_end_time** `string`: Required for external events; optional for voice/stage.
- **privacy_level** `integer`: Always 2 (GUILD_ONLY) — Discord deprecated PUBLIC events. - one of: 2
- **status** `integer`: 1=SCHEDULED, 2=ACTIVE, 3=COMPLETED, 4=CANCELED - one of: 1, 2, 3, 4
- **entity_type** `integer`: 1=STAGE_INSTANCE, 2=VOICE, 3=EXTERNAL - one of: 1, 2, 3
- **entity_id** `string`: No description
- **entity_metadata** `object`: 
  - **location** `string`: External event location string.
- **user_count** `integer`: Number of members who RSVP'd. Only present when withUserCount=true on list.
- **image** `string`: Cover image hash; build URL via cdn.discordapp.com.

---

# Get Discord account settings API Reference

Returns the current Discord account settings including webhook identity (display name and avatar), connected channel, and guild information.

## GET /v1/accounts/{accountId}/discord-settings

**Get Discord account settings**

Returns the current Discord account settings including webhook identity (display name and avatar), connected channel, and guild information.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Discord account settings

**Response Body:**

- **account** `object`: 
  - **_id** `string`: No description
  - **platform** `string`: No description (example: "discord")
  - **username** `string`: Channel name
  - **displayName** `string`: Guild - #channel display name
  - **profilePicture** `string`: Guild icon URL
  - **channelId** `string`: Connected channel snowflake ID
  - **channelName** `string`: Channel name
  - **channelType** `string`: Channel type (0 = text, 5 = announcement, 15 = forum)
  - **guildId** `string`: Guild (server) snowflake ID
  - **webhookUsername** `string`: Custom webhook display name (null = default "Zernio")
  - **webhookAvatarUrl** `string`: Custom webhook avatar URL (null = default bot avatar)

#### 400: Not a Discord account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## PATCH /v1/accounts/{accountId}/discord-settings

**Update Discord settings**

Update Discord account settings. Supports two operations (can be combined):

1. **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.

2. **Switch channel** - Move the connection to a different channel in the same guild. A new webhook is automatically created in the target channel.


### Parameters

- **accountId** (required) in path: No description

### Request Body

- **webhookUsername** `string`: Custom display name for the webhook (1-80 chars). Empty string resets to default ("Zernio"). Cannot contain "clyde" or "discord".
- **webhookAvatarUrl** `string`: Custom avatar URL. Empty string resets to default bot avatar.
- **channelId** `string`: Switch to a different channel in the same guild. Must be a text (0), announcement (5), or forum (15) channel.

### Responses

#### 200: Settings updated

**Response Body:**

- **message** `string`: No description (example: "Discord settings updated")
- **account** `object`: 
  - **_id** `string`: No description
  - **platform** `string`: No description
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **profilePicture** `string`: No description
  - **channelId** `string`: No description
  - **channelName** `string`: No description
  - **channelType** `string`: No description
  - **guildId** `string`: No description
  - **webhookUsername** `string`: No description
  - **webhookAvatarUrl** `string`: No description

#### 400: Invalid request (no changes

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found

---

---

# List Discord guild members API Reference

Cursor-paginated list of guild members. Returns Discord's raw member
objects so callers can build community-ops automation (e.g. "add role
to all members joined in the last 7 days") on the actual platform shape.

**Important:** this endpoint requires the privileged "Server Members
Intent" enabled on the Discord app (Developer Portal → Bot tab → toggle
"Server Members Intent" ON, then Save). Without it, Discord returns an
empty array with no error. Verify the intent is enabled before relying
on this endpoint.

Pagination: pass `after` = the last `user.id` from the previous page.
Omit on the first call. Response includes a `nextCursor` and `hasMore`
flag so callers don't need to know Discord's pagination shape.


## GET /v1/discord/guilds/{guildId}/members

**List Discord guild members**

Cursor-paginated list of guild members. Returns Discord's raw member
objects so callers can build community-ops automation (e.g. "add role
to all members joined in the last 7 days") on the actual platform shape.

**Important:** this endpoint requires the privileged "Server Members
Intent" enabled on the Discord app (Developer Portal → Bot tab → toggle
"Server Members Intent" ON, then Save). Without it, Discord returns an
empty array with no error. Verify the intent is enabled before relying
on this endpoint.

Pagination: pass `after` = the last `user.id` from the previous page.
Omit on the first call. Response includes a `nextCursor` and `hasMore`
flag so callers don't need to know Discord's pagination shape.


### Parameters

- **guildId** (required) in path: No description
- **accountId** (required) in query: No description
- **limit** (optional) in query: Page size (1-1000).
- **after** (optional) in query: Snowflake of the last member from the previous page.

### Responses

#### 200: List of guild members.

**Response Body:**

- **data** `array[object]`: 
  - **user** `object`: 
    - **id** `string`: User snowflake
    - **username** `string`: No description
    - **discriminator** `string`: No description
    - **avatar** `string`: No description
    - **global_name** `string`: User's display name (post-2023 Discord rebrand)
  - **nick** `string`: Guild-specific nickname
  - **roles** `array[string]`: Snowflake IDs of roles assigned to this member
  - **joined_at** `string` (date-time): No description
  - **premium_since** `string` (date-time): When the user started boosting the server
- **pagination** `object`: 
  - **nextCursor** `string`: Pass as `after` on the next call. Null when there are no more pages.
  - **hasMore** `boolean`: No description

#### 400: Invalid query params.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found or not in this guild.

---

---

# List Discord guild roles API Reference

Returns all roles in a Discord guild. Useful for building role-mention
pickers, role-permission UIs, or finding the role ID before calling
the role-assign endpoint.

Roles are returned unordered — sort client-side by `position` if you
need Discord's UI ordering.

Caller must pass `accountId` of a Discord SocialAccount bound to this
guild (route verifies team access + guild match).


## GET /v1/discord/guilds/{guildId}/roles

**List Discord guild roles**

Returns all roles in a Discord guild. Useful for building role-mention
pickers, role-permission UIs, or finding the role ID before calling
the role-assign endpoint.

Roles are returned unordered — sort client-side by `position` if you
need Discord's UI ordering.

Caller must pass `accountId` of a Discord SocialAccount bound to this
guild (route verifies team access + guild match).


### Parameters

- **guildId** (required) in path: Discord guild snowflake ID
- **accountId** (required) in query: SocialAccount _id of the Discord account bound to this guild

### Responses

#### 200: List of guild roles.

**Response Body:**

- **data** `array[object]`: 
  - **id** `string`: Role snowflake ID
  - **name** `string`: No description
  - **color** `integer`: Decimal color (0 = no color). Convert to hex via .toString(16).
  - **position** `integer`: Position in role hierarchy (higher = more authority)
  - **permissions** `string`: Permissions bitfield as a stringified integer
  - **managed** `boolean`: True for integration-managed roles (bot roles)
  - **mentionable** `boolean`: No description
  - **hoist** `boolean`: True if role is displayed separately in member list

#### 400: Invalid accountId or guildId format.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found

#### 502: Discord rejected the request (bot lacks View Channels permission in the guild).

---

---

# List pinned messages in a Discord channel API Reference

Returns the channel's pinned messages, sorted most-recently-pinned
first. Discord caps a channel at 50 pinned messages and returns the
full list unpaginated.

Bot needs READ_MESSAGE_HISTORY in the channel (granted by default
BOT_PERMISSIONS).


## GET /v1/discord/channels/{channelId}/pins

**List pinned messages in a Discord channel**

Returns the channel's pinned messages, sorted most-recently-pinned
first. Discord caps a channel at 50 pinned messages and returns the
full list unpaginated.

Bot needs READ_MESSAGE_HISTORY in the channel (granted by default
BOT_PERMISSIONS).


### Parameters

- **channelId** (required) in path: Discord channel snowflake.
- **accountId** (required) in query: SocialAccount _id of any Discord account in the same guild.

### Responses

#### 200: Pinned messages.

**Response Body:**

- **data** `array[object]`: 
  - **id** `string`: No description
  - **channel_id** `string`: No description
  - **content** `string`: No description
  - **timestamp** `string` (date-time): No description
  - **author** `object`: No description
  - **attachments** `array[object]`: 
    Type: `object`
  - **embeds** `array[object]`: 
    Type: `object`

#### 400: Invalid channelId or accountId format.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found or not accessible.

#### 502: Bot lacks access to the channel.

---

---

# List Discord scheduled events API Reference

Return all scheduled events in the guild. Events are distinct from
messages — they appear in the server's Events panel and Discord
auto-notifies interested members ahead of start time.

Pass `withUserCount=true` to include `user_count` (number of members
who RSVP'd) on each event. Useful for surfacing engagement.


## GET /v1/discord/guilds/{guildId}/events

**List Discord scheduled events**

Return all scheduled events in the guild. Events are distinct from
messages — they appear in the server's Events panel and Discord
auto-notifies interested members ahead of start time.

Pass `withUserCount=true` to include `user_count` (number of members
who RSVP'd) on each event. Useful for surfacing engagement.


### Parameters

- **guildId** (required) in path: No description
- **accountId** (required) in query: No description
- **withUserCount** (optional) in query: Include user_count on each event.

### Responses

#### 200: List of scheduled events.

**Response Body:**

- **data** `array[DiscordScheduledEvent]`: 

#### 400: Invalid params.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found or not in this guild.

#### 502: Bot lacks access to the guild's events.

---

## POST /v1/discord/guilds/{guildId}/events

**Create a Discord scheduled event**

Create a guild scheduled event. Three event types, selected via the
discriminator on `entity.type`:

  - `external` — off-platform (Zoom, in-person, livestream). Requires
    both `location` and `endsAt`. Most common type for scheduler
    integrations.
  - `voice` — hosted in a Discord voice channel. Requires `channelId`.
  - `stage` — hosted in a Discord stage channel. Requires `channelId`.

Bot needs MANAGE_EVENTS in the guild. Existing installs (pre-events
PR) need a re-invite OR a server admin manually granting the
permission — see route header for details.


### Parameters

- **guildId** (required) in path: No description

### Request Body

- **accountId** (required) `string`: No description
- **name** (required) `string`: No description
- **description** `string`: No description
- **startsAt** (required) `string`: ISO 8601 start time. Must be in the future.
- **entity**: Platform-specific settings (see schema definitions below)
- **imageDataUri** `string`: Optional cover image as a base64 data URI.

### Responses

#### 200: Event created.

**Response Body:**

- **data**: `DiscordScheduledEvent` - See schema definition

#### 400: Validation error (missing required fields for the chosen entity type, malformed snowflake, past startsAt, etc.).

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found.

#### 502: Bot lacks MANAGE_EVENTS in the guild.

---


# Related Schema Definitions

## DiscordScheduledEvent

Discord guild scheduled event. Returned by /v1/discord/guilds/{guildId}/events endpoints.
Fields below are the subset Zernio consumes — Discord may return more (e.g. creator,
image hash) which we pass through verbatim.


### Properties

- **id** `string`: Event snowflake ID
- **guild_id** `string`: No description
- **channel_id** `string`: Voice/stage channel ID; null for external events.
- **creator_id** `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **scheduled_start_time** `string`: No description
- **scheduled_end_time** `string`: Required for external events; optional for voice/stage.
- **privacy_level** `integer`: Always 2 (GUILD_ONLY) — Discord deprecated PUBLIC events. - one of: 2
- **status** `integer`: 1=SCHEDULED, 2=ACTIVE, 3=COMPLETED, 4=CANCELED - one of: 1, 2, 3, 4
- **entity_type** `integer`: 1=STAGE_INSTANCE, 2=VOICE, 3=EXTERNAL - one of: 1, 2, 3
- **entity_id** `string`: No description
- **entity_metadata** `object`: 
  - **location** `string`: External event location string.
- **user_count** `integer`: Number of members who RSVP'd. Only present when withUserCount=true on list.
- **image** `string`: Cover image hash; build URL via cdn.discordapp.com.

---

# Pin a Discord message API Reference

Pin a specific message in a channel. Path shape mirrors Discord's own
API (`PUT /channels/{cid}/pins/{mid}`).

Idempotent — re-pinning an already-pinned message is a 204 no-op.

Constraints:
  - Bot needs MANAGE_MESSAGES in the channel.
  - 50-pin cap per channel — hitting it returns 400 (Discord-side).
    Caller should unpin one first.


## PUT /v1/discord/channels/{channelId}/pins/{messageId}

**Pin a Discord message**

Pin a specific message in a channel. Path shape mirrors Discord's own
API (`PUT /channels/{cid}/pins/{mid}`).

Idempotent — re-pinning an already-pinned message is a 204 no-op.

Constraints:
  - Bot needs MANAGE_MESSAGES in the channel.
  - 50-pin cap per channel — hitting it returns 400 (Discord-side).
    Caller should unpin one first.


### Parameters

- **channelId** (required) in path: No description
- **messageId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Message pinned (or was already pinned — idempotent).

**Response Body:**

- **success** `boolean`: No description
- **operation** `string`: No description - one of: message_pinned
- **channelId** `string`: No description
- **messageId** `string`: No description

#### 400: Validation error or pin cap (50) reached.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found.

#### 502: Bot lacks MANAGE_MESSAGES in the channel.

---

## DELETE /v1/discord/channels/{channelId}/pins/{messageId}

**Unpin a Discord message**

Unpin a message. Same MANAGE_MESSAGES permission requirement as pin.
Idempotent — unpinning a non-pinned message is a 204 no-op.


### Parameters

- **channelId** (required) in path: No description
- **messageId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Message unpinned (or was not pinned — idempotent).

**Response Body:**

- **success** `boolean`: No description
- **operation** `string`: No description - one of: message_unpinned
- **channelId** `string`: No description
- **messageId** `string`: No description

#### 400: Validation error.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found.

#### 502: Bot lacks MANAGE_MESSAGES in the channel.

---

---

# Remove a role from a guild member API Reference

Remove one role from one member. Idempotent — removing a role the
member doesn't have returns 204 no-op.

Same permission + hierarchy constraints as the PUT counterpart.


## PUT /v1/discord/guilds/{guildId}/members/{userId}/roles/{roleId}

**Assign a role to a guild member**

Assign one role to one member. Idempotent on Discord's side — re-running
on a member who already has the role is a 204 no-op.

Path shape mirrors Discord's own API (`PUT /guilds/{guild}/members/{user}/roles/{role}`)
for zero-translation mental mapping.

Bot needs MANAGE_ROLES permission in the guild AND its highest role
must be above the target role (Discord hierarchy rule). The
`@everyone` role (where roleId == guildId) cannot be assigned.


### Parameters

- **guildId** (required) in path: No description
- **userId** (required) in path: Discord user snowflake to assign the role to.
- **roleId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Role assigned (or already present — idempotent).

**Response Body:**

- **success** `boolean`: No description
- **operation** `string`: No description - one of: role_assigned
- **guildId** `string`: No description
- **userId** `string`: No description
- **roleId** `string`: No description

#### 400: Validation error (malformed snowflake) or @everyone manipulation attempt.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found or not in this guild.

#### 502: Discord rejected the request: bot lacks MANAGE_ROLES, or target role is above the bot's highest role.

---

## DELETE /v1/discord/guilds/{guildId}/members/{userId}/roles/{roleId}

**Remove a role from a guild member**

Remove one role from one member. Idempotent — removing a role the
member doesn't have returns 204 no-op.

Same permission + hierarchy constraints as the PUT counterpart.


### Parameters

- **guildId** (required) in path: No description
- **userId** (required) in path: No description
- **roleId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Role removed (or was already absent — idempotent).

**Response Body:**

- **success** `boolean`: No description
- **operation** `string`: No description - one of: role_removed
- **guildId** `string`: No description
- **userId** `string`: No description
- **roleId** `string`: No description

#### 400: Validation error.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found or not in this guild.

#### 502: Discord rejected the request (permission or hierarchy issue).

---

---

# Send a Discord Direct Message API Reference

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.

Constraints (Discord platform limits):
  - The bot can only DM users it shares at least one guild with.
  - If the recipient has DMs disabled for non-friends, Discord returns 403
    (surfaces as a 502 platform error).
  - `content` capped at 2,000 chars.
  - At least one of `content`, `embeds`, or `attachments` is required.
  - The recipient must be identified by Discord snowflake ID (not username).

This 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. DMs are
not persisted to `Post` / `ExternalPost` and are always sent immediately.


## POST /v1/discord/dms

**Send a Discord Direct Message**

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.

Constraints (Discord platform limits):
  - The bot can only DM users it shares at least one guild with.
  - If the recipient has DMs disabled for non-friends, Discord returns 403
    (surfaces as a 502 platform error).
  - `content` capped at 2,000 chars.
  - At least one of `content`, `embeds`, or `attachments` is required.
  - The recipient must be identified by Discord snowflake ID (not username).

This 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. DMs are
not persisted to `Post` / `ExternalPost` and are always sent immediately.


### Request Body

- **accountId** (required) `string`: SocialAccount _id of the connected Discord account the bot speaks as. Caller must own the account (directly or via team membership).
- **userId** (required) `string`: Discord snowflake ID of the recipient (15-21 digits).
- **content** `string`: Message text, up to 2,000 characters.
- **embeds** `array`: Up to 10 Discord embeds. Same shape as channel-post embeds (title, description, color, fields, etc.). See DiscordPlatformData.embeds for the embed object schema.
- **attachments** `array`: Up to 10 media attachments. Each is `{ type: image|video|gif|document, url, filename?, mimeType?, size? }`.
- **tts** `boolean`: Send as text-to-speech message.

### Responses

#### 200: DM sent successfully.

**Response Body:**

- **messageId** `string`: Discord message snowflake ID
- **channelId** `string`: DM channel snowflake (Discord auto-creates one per recipient pair)
- **url** `string`: Direct link to the message — uses Discord's @me path for DMs
- **timestamp** `string` (date-time): No description
- **recipient** `object`: 
  - **userId** `string`: No description
  - **platform** `string`: No description (example: "discord")
- **account** `object`: 
  - **id** `string`: No description
  - **username** `string`: No description
  - **displayName** `string`: No description

#### 400: Validation error (missing required fields, content > 2000 chars, malformed snowflake, or all of content/embeds/attachments missing).

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found or not accessible to this user.

#### 502: Discord rejected 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.

---

---

# Unpin a Discord message API Reference

Unpin a message. Same MANAGE_MESSAGES permission requirement as pin.
Idempotent — unpinning a non-pinned message is a 204 no-op.


## PUT /v1/discord/channels/{channelId}/pins/{messageId}

**Pin a Discord message**

Pin a specific message in a channel. Path shape mirrors Discord's own
API (`PUT /channels/{cid}/pins/{mid}`).

Idempotent — re-pinning an already-pinned message is a 204 no-op.

Constraints:
  - Bot needs MANAGE_MESSAGES in the channel.
  - 50-pin cap per channel — hitting it returns 400 (Discord-side).
    Caller should unpin one first.


### Parameters

- **channelId** (required) in path: No description
- **messageId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Message pinned (or was already pinned — idempotent).

**Response Body:**

- **success** `boolean`: No description
- **operation** `string`: No description - one of: message_pinned
- **channelId** `string`: No description
- **messageId** `string`: No description

#### 400: Validation error or pin cap (50) reached.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found.

#### 502: Bot lacks MANAGE_MESSAGES in the channel.

---

## DELETE /v1/discord/channels/{channelId}/pins/{messageId}

**Unpin a Discord message**

Unpin a message. Same MANAGE_MESSAGES permission requirement as pin.
Idempotent — unpinning a non-pinned message is a 204 no-op.


### Parameters

- **channelId** (required) in path: No description
- **messageId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Message unpinned (or was not pinned — idempotent).

**Response Body:**

- **success** `boolean`: No description
- **operation** `string`: No description - one of: message_unpinned
- **channelId** `string`: No description
- **messageId** `string`: No description

#### 400: Validation error.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found.

#### 502: Bot lacks MANAGE_MESSAGES in the channel.

---

---

# Update a Discord scheduled event API Reference

Patch any subset of fields. Passing `status: 'cancelled'` is how you
cancel an event — Discord doesn't have a dedicated cancel endpoint,
it's a status transition.

Most status transitions Discord enforces (you can't go SCHEDULED →
COMPLETED directly). The common consumer case is SCHEDULED → CANCELED.


## GET /v1/discord/guilds/{guildId}/events/{eventId}

**Get a Discord scheduled event**

### Parameters

- **guildId** (required) in path: No description
- **eventId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Event.

**Response Body:**

- **data**: `DiscordScheduledEvent` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Event or Discord account not found.

---

## PATCH /v1/discord/guilds/{guildId}/events/{eventId}

**Update a Discord scheduled event**

Patch any subset of fields. Passing `status: 'cancelled'` is how you
cancel an event — Discord doesn't have a dedicated cancel endpoint,
it's a status transition.

Most status transitions Discord enforces (you can't go SCHEDULED →
COMPLETED directly). The common consumer case is SCHEDULED → CANCELED.


### Parameters

- **guildId** (required) in path: No description
- **eventId** (required) in path: No description

### Request Body

- **accountId** (required) `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **startsAt** `string`: No description
- **endsAt** `string`: No description
- **location** `string`: For external events.
- **status** `string`: Status transition. Most common: 'cancelled' to cancel an event. - one of: scheduled, active, completed, cancelled
- **imageDataUri** `string`: No description

### Responses

#### 200: Event updated.

**Response Body:**

- **data**: `DiscordScheduledEvent` - See schema definition

#### 400: Validation error, OR no updatable fields beyond accountId provided.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Event or Discord account not found.

#### 502: Discord rejected the update (invalid status transition

---

## DELETE /v1/discord/guilds/{guildId}/events/{eventId}

**Delete a Discord scheduled event**

Hard-delete an event. Use PATCH with `status: 'cancelled'` instead
if you want the event preserved in the guild's history.


### Parameters

- **guildId** (required) in path: No description
- **eventId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Event deleted.

**Response Body:**

- **success** `boolean`: No description
- **deleted** `string`: The deleted event's snowflake.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Event or Discord account not found.

#### 502: Bot lacks MANAGE_EVENTS in the guild.

---


# Related Schema Definitions

## DiscordScheduledEvent

Discord guild scheduled event. Returned by /v1/discord/guilds/{guildId}/events endpoints.
Fields below are the subset Zernio consumes — Discord may return more (e.g. creator,
image hash) which we pass through verbatim.


### Properties

- **id** `string`: Event snowflake ID
- **guild_id** `string`: No description
- **channel_id** `string`: Voice/stage channel ID; null for external events.
- **creator_id** `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **scheduled_start_time** `string`: No description
- **scheduled_end_time** `string`: Required for external events; optional for voice/stage.
- **privacy_level** `integer`: Always 2 (GUILD_ONLY) — Discord deprecated PUBLIC events. - one of: 2
- **status** `integer`: 1=SCHEDULED, 2=ACTIVE, 3=COMPLETED, 4=CANCELED - one of: 1, 2, 3, 4
- **entity_type** `integer`: 1=STAGE_INSTANCE, 2=VOICE, 3=EXTERNAL - one of: 1, 2, 3
- **entity_id** `string`: No description
- **entity_metadata** `object`: 
  - **location** `string`: External event location string.
- **user_count** `integer`: Number of members who RSVP'd. Only present when withUserCount=true on list.
- **image** `string`: Cover image hash; build URL via cdn.discordapp.com.

---

# Update Discord settings API Reference

Update Discord account settings. Supports two operations (can be combined):

1. **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.

2. **Switch channel** - Move the connection to a different channel in the same guild. A new webhook is automatically created in the target channel.


## GET /v1/accounts/{accountId}/discord-settings

**Get Discord account settings**

Returns the current Discord account settings including webhook identity (display name and avatar), connected channel, and guild information.

### Parameters

- **accountId** (required) in path: No description

### Responses

#### 200: Discord account settings

**Response Body:**

- **account** `object`: 
  - **_id** `string`: No description
  - **platform** `string`: No description (example: "discord")
  - **username** `string`: Channel name
  - **displayName** `string`: Guild - #channel display name
  - **profilePicture** `string`: Guild icon URL
  - **channelId** `string`: Connected channel snowflake ID
  - **channelName** `string`: Channel name
  - **channelType** `string`: Channel type (0 = text, 5 = announcement, 15 = forum)
  - **guildId** `string`: Guild (server) snowflake ID
  - **webhookUsername** `string`: Custom webhook display name (null = default "Zernio")
  - **webhookAvatarUrl** `string`: Custom webhook avatar URL (null = default bot avatar)

#### 400: Not a Discord account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## PATCH /v1/accounts/{accountId}/discord-settings

**Update Discord settings**

Update Discord account settings. Supports two operations (can be combined):

1. **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.

2. **Switch channel** - Move the connection to a different channel in the same guild. A new webhook is automatically created in the target channel.


### Parameters

- **accountId** (required) in path: No description

### Request Body

- **webhookUsername** `string`: Custom display name for the webhook (1-80 chars). Empty string resets to default ("Zernio"). Cannot contain "clyde" or "discord".
- **webhookAvatarUrl** `string`: Custom avatar URL. Empty string resets to default bot avatar.
- **channelId** `string`: Switch to a different channel in the same guild. Must be a text (0), announcement (5), or forum (15) channel.

### Responses

#### 200: Settings updated

**Response Body:**

- **message** `string`: No description (example: "Discord settings updated")
- **account** `object`: 
  - **_id** `string`: No description
  - **platform** `string`: No description
  - **username** `string`: No description
  - **displayName** `string`: No description
  - **profilePicture** `string`: No description
  - **channelId** `string`: No description
  - **channelName** `string`: No description
  - **channelType** `string`: No description
  - **guildId** `string`: No description
  - **webhookUsername** `string`: No description
  - **webhookAvatarUrl** `string`: No description

#### 400: Invalid request (no changes

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Discord account not found

---

---

# Batch get reviews API Reference

Fetches reviews across multiple locations in a single request.
More efficient than calling GET /gmb-reviews per location for multi-location businesses.
Returns a flat list of individual reviews, each tagged with its review resource name.
Note: this endpoint does not return aggregate metrics (averageRating / totalReviewCount).
For those, use the single-location GET /gmb-reviews endpoint.


## POST /v1/accounts/{accountId}/gmb-reviews/batch

**Batch get reviews**

Fetches reviews across multiple locations in a single request.
More efficient than calling GET /gmb-reviews per location for multi-location businesses.
Returns a flat list of individual reviews, each tagged with its review resource name.
Note: this endpoint does not return aggregate metrics (averageRating / totalReviewCount).
For those, use the single-location GET /gmb-reviews endpoint.


### Parameters

- **accountId** (required) in path: No description

### Request Body

- **locationNames** (required) `array`: Array of full location resource names (e.g. ['accounts/123/locations/456'])
- **pageSize** `integer`: Number of reviews per page (max 50)
- **pageToken** `string`: Pagination token from previous response

### Responses

#### 200: Batch reviews fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationReviews** `array[object]`: 
  - **name** `string`: Full review resource name (accounts/*/locations/*/reviews/*)
  - **review** `object`: The review object (reviewId
- **nextPageToken** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Complete a verification API Reference

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.

## POST /v1/accounts/{accountId}/gmb-verifications/{verificationId}/complete

**Complete a verification**

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

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **verificationId** (required) in path: The last segment of a verification `name` from GET /gmb-verifications.
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location.

### Request Body

- **pin** (required) `string`: The code Google sent to the business.

### Responses

#### 200: Verification completed

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **verification** `object`: 
  - **name** `string`: No description
  - **method** `string`: No description - one of: ADDRESS, EMAIL, PHONE_CALL, SMS, AUTO, VETTED_PARTNER
  - **state** `string`: No description - one of: PENDING, COMPLETED, FAILED
  - **createTime** `string` (date-time): No description

#### 400: Invalid request (e.g. wrong PIN or verification not pending)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Upload photo API Reference

Creates a media item (photo) for a location from a publicly accessible URL.

Categories determine where the photo appears: COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, FOOD_AND_DRINK, MENU, PRODUCT, TEAMS, ADDITIONAL.


## GET /v1/accounts/{accountId}/gmb-media

**List media**

Lists media items (photos) for a Google Business Profile location.
Returns photo URLs, descriptions, categories, and metadata.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **pageSize** (optional) in query: Number of items to return (max 100)
- **pageToken** (optional) in query: Pagination token from previous response

### Responses

#### 200: Media items fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **mediaItems** `array[object]`: 
  - **name** `string`: Resource name
  - **mediaFormat** `string`: No description - one of: PHOTO, VIDEO
  - **sourceUrl** `string`: No description
  - **googleUrl** `string`: Google-hosted URL
  - **thumbnailUrl** `string`: No description
  - **description** `string`: No description
  - **createTime** `string` (date-time): No description
  - **locationAssociation** `object`: 
    - **category** `string`: No description
- **nextPageToken** `string`: No description
- **totalMediaItemsCount** `integer`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## POST /v1/accounts/{accountId}/gmb-media

**Upload photo**

Creates a media item (photo) for a location from a publicly accessible URL.

Categories determine where the photo appears: COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, FOOD_AND_DRINK, MENU, PRODUCT, TEAMS, ADDITIONAL.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **sourceUrl** (required) `string`: Publicly accessible image URL
- **mediaFormat** `string`: No description - one of: PHOTO, VIDEO
- **description** `string`: Photo description
- **category** `string`: Where the photo appears on the listing - one of: COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, FOOD_AND_DRINK, MENU, PRODUCT, TEAMS, ADDITIONAL

### Responses

#### 200: Media created successfully

**Response Body:**

- **success** `boolean`: No description
- **name** `string`: No description
- **mediaFormat** `string`: No description
- **googleUrl** `string`: No description

#### 400: Invalid request or unsupported media format

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## DELETE /v1/accounts/{accountId}/gmb-media

**Delete photo**

Deletes a photo or media item from a GBP location.

### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **mediaId** (required) in query: The media item ID to delete

### Responses

#### 200: Media deleted successfully

**Response Body:**

- **success** `boolean`: No description
- **deleted** `boolean`: No description
- **mediaId** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Create action link API Reference

Creates a place action link for a location.

Available action types: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE.


## GET /v1/accounts/{accountId}/gmb-place-actions

**List action links**

Lists place action links for a Google Business Profile location.

Place actions are the booking, ordering, and reservation buttons that appear on your listing.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **pageSize** (optional) in query: No description
- **pageToken** (optional) in query: No description

### Responses

#### 200: Place actions fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **placeActionLinks** `array[object]`: 
  - **name** `string`: Resource name
  - **uri** `string`: Action URL
  - **placeActionType** `string`: No description
  - **createTime** `string` (date-time): No description
  - **updateTime** `string` (date-time): No description
- **nextPageToken** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## POST /v1/accounts/{accountId}/gmb-place-actions

**Create action link**

Creates a place action link for a location.

Available action types: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **uri** (required) `string`: The action URL
- **placeActionType** (required) `string`: Type of action - one of: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE

### Responses

#### 200: Place action created successfully

**Response Body:**

- **success** `boolean`: No description
- **name** `string`: Resource name of the created link
- **uri** `string`: No description
- **placeActionType** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## DELETE /v1/accounts/{accountId}/gmb-place-actions

**Delete action link**

Deletes a place action link (e.g. booking or ordering URL) from a GBP location.

### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **name** (required) in query: The resource name of the place action link (e.g. locations/123/placeActionLinks/456)

### Responses

#### 200: Place action deleted successfully

**Response Body:**

- **success** `boolean`: No description
- **deleted** `boolean`: No description
- **name** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## PATCH /v1/accounts/{accountId}/gmb-place-actions

**Update action link**

Updates a place action link (change URL or action type).
Only the fields included in the request body will be updated.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location.

### Request Body

- **name** (required) `string`: Resource name of the place action link (e.g. locations/123/placeActionLinks/456)
- **uri** `string`: New action URL
- **placeActionType** `string`: New action type - one of: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE

### Responses

#### 200: Place action updated successfully

**Response Body:**

- **success** `boolean`: No description
- **name** `string`: No description
- **uri** `string`: No description
- **placeActionType** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Delete photo API Reference

Deletes a photo or media item from a GBP location.

## GET /v1/accounts/{accountId}/gmb-media

**List media**

Lists media items (photos) for a Google Business Profile location.
Returns photo URLs, descriptions, categories, and metadata.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **pageSize** (optional) in query: Number of items to return (max 100)
- **pageToken** (optional) in query: Pagination token from previous response

### Responses

#### 200: Media items fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **mediaItems** `array[object]`: 
  - **name** `string`: Resource name
  - **mediaFormat** `string`: No description - one of: PHOTO, VIDEO
  - **sourceUrl** `string`: No description
  - **googleUrl** `string`: Google-hosted URL
  - **thumbnailUrl** `string`: No description
  - **description** `string`: No description
  - **createTime** `string` (date-time): No description
  - **locationAssociation** `object`: 
    - **category** `string`: No description
- **nextPageToken** `string`: No description
- **totalMediaItemsCount** `integer`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## POST /v1/accounts/{accountId}/gmb-media

**Upload photo**

Creates a media item (photo) for a location from a publicly accessible URL.

Categories determine where the photo appears: COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, FOOD_AND_DRINK, MENU, PRODUCT, TEAMS, ADDITIONAL.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **sourceUrl** (required) `string`: Publicly accessible image URL
- **mediaFormat** `string`: No description - one of: PHOTO, VIDEO
- **description** `string`: Photo description
- **category** `string`: Where the photo appears on the listing - one of: COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, FOOD_AND_DRINK, MENU, PRODUCT, TEAMS, ADDITIONAL

### Responses

#### 200: Media created successfully

**Response Body:**

- **success** `boolean`: No description
- **name** `string`: No description
- **mediaFormat** `string`: No description
- **googleUrl** `string`: No description

#### 400: Invalid request or unsupported media format

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## DELETE /v1/accounts/{accountId}/gmb-media

**Delete photo**

Deletes a photo or media item from a GBP location.

### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **mediaId** (required) in query: The media item ID to delete

### Responses

#### 200: Media deleted successfully

**Response Body:**

- **success** `boolean`: No description
- **deleted** `boolean`: No description
- **mediaId** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Delete action link API Reference

Deletes a place action link (e.g. booking or ordering URL) from a GBP location.

## GET /v1/accounts/{accountId}/gmb-place-actions

**List action links**

Lists place action links for a Google Business Profile location.

Place actions are the booking, ordering, and reservation buttons that appear on your listing.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **pageSize** (optional) in query: No description
- **pageToken** (optional) in query: No description

### Responses

#### 200: Place actions fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **placeActionLinks** `array[object]`: 
  - **name** `string`: Resource name
  - **uri** `string`: Action URL
  - **placeActionType** `string`: No description
  - **createTime** `string` (date-time): No description
  - **updateTime** `string` (date-time): No description
- **nextPageToken** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## POST /v1/accounts/{accountId}/gmb-place-actions

**Create action link**

Creates a place action link for a location.

Available action types: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **uri** (required) `string`: The action URL
- **placeActionType** (required) `string`: Type of action - one of: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE

### Responses

#### 200: Place action created successfully

**Response Body:**

- **success** `boolean`: No description
- **name** `string`: Resource name of the created link
- **uri** `string`: No description
- **placeActionType** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## DELETE /v1/accounts/{accountId}/gmb-place-actions

**Delete action link**

Deletes a place action link (e.g. booking or ordering URL) from a GBP location.

### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **name** (required) in query: The resource name of the place action link (e.g. locations/123/placeActionLinks/456)

### Responses

#### 200: Place action deleted successfully

**Response Body:**

- **success** `boolean`: No description
- **deleted** `boolean`: No description
- **name** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## PATCH /v1/accounts/{accountId}/gmb-place-actions

**Update action link**

Updates a place action link (change URL or action type).
Only the fields included in the request body will be updated.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location.

### Request Body

- **name** (required) `string`: Resource name of the place action link (e.g. locations/123/placeActionLinks/456)
- **uri** `string`: New action URL
- **placeActionType** `string`: New action type - one of: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE

### Responses

#### 200: Place action updated successfully

**Response Body:**

- **success** `boolean`: No description
- **name** `string`: No description
- **uri** `string`: No description
- **placeActionType** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Delete a review reply API Reference

Removes the business owner reply from a Google Business review. The review itself remains.

## POST /v1/accounts/{accountId}/gmb-reviews/{reviewId}/reply

**Reply to a review**

Posts (or updates) the business owner reply to a Google Business review.
The reply is associated with the account's currently selected location (set via /v1/accounts/{accountId}/gmb-locations).
Calling this endpoint a second time on the same review overwrites the previous reply (PUT semantics on Google's side).


### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **reviewId** (required) in path: The review ID portion (e.g. "AIe9_BGx1234567890"), not the full resource name

### Request Body

- **comment** (required) `string`: The reply text to post on the review. Must be non-empty.

### Responses

#### 200: Reply posted successfully

**Response Body:**

- **success** `boolean`: No description
- **reviewId** `string`: No description
- **platform** `string`: No description (example: "googlebusiness")

#### 400: Invalid request, missing comment, non-GBP account, or account missing location metadata

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid (account must be reconnected)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 500: Failed to post reply

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## DELETE /v1/accounts/{accountId}/gmb-reviews/{reviewId}/reply

**Delete a review reply**

Removes the business owner reply from a Google Business review. The review itself remains.

### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **reviewId** (required) in path: The review ID portion (e.g. "AIe9_BGx1234567890"), not the full resource name

### Responses

#### 200: Reply deleted successfully

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description
- **platform** `string`: No description (example: "googlebusiness")

#### 400: Invalid request, non-GBP account, or account missing location metadata

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid (account must be reconnected)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 500: Failed to delete reply

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Fetch verification options API Reference

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.

## POST /v1/accounts/{accountId}/gmb-verifications/options

**Fetch verification options**

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

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location.

### Request Body

- **languageCode** (required) `string`: No description
- **context** `object`: ServiceBusinessContext. Required for service-area businesses (must include the service address).

### Responses

#### 200: Verification options fetched

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **options** `array[object]`: 
  - **verificationMethod** `string`: No description - one of: ADDRESS, EMAIL, PHONE_CALL, SMS, AUTO, VETTED_PARTNER
  - **phoneNumber** `string`: Present for PHONE_CALL / SMS.

#### 400: Invalid request (e.g. missing service business context, or missing languageCode)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get attribute metadata API Reference

Returns metadata about which Google Business Profile attributes are available for
a location or business category. Use this endpoint to discover valid attribute names,
value types, and allowed enum values before reading or writing via gmb-attributes.

Two mutually exclusive query modes:

**Location mode**: pass `locationId` (or rely on the account's stored `selectedLocationId`).
Google returns attributes valid for that specific location.

**Category mode**: pass `categoryName` (must start with `categories/`) and `regionCode`.
Google returns attributes valid for that category across the given region.
`languageCode` is optional in category mode.

Both modes support `pageSize` and `pageToken` for pagination.


## GET /v1/accounts/{accountId}/gmb-attribute-metadata

**Get attribute metadata**

Returns metadata about which Google Business Profile attributes are available for
a location or business category. Use this endpoint to discover valid attribute names,
value types, and allowed enum values before reading or writing via gmb-attributes.

Two mutually exclusive query modes:

**Location mode**: pass `locationId` (or rely on the account's stored `selectedLocationId`).
Google returns attributes valid for that specific location.

**Category mode**: pass `categoryName` (must start with `categories/`) and `regionCode`.
Google returns attributes valid for that category across the given region.
`languageCode` is optional in category mode.

Both modes support `pageSize` and `pageToken` for pagination.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: GBP location ID (e.g. "6257659026299438786"). If omitted, uses the account's stored selectedLocationId. Mutually exclusive with categoryName.

- **categoryName** (optional) in query: Category resource name, must start with "categories/" (e.g. "categories/gcid:plumber"). Required together with regionCode. Mutually exclusive with locationId.

- **regionCode** (optional) in query: BCP-47 region code (e.g. "US", "ES"). Required when categoryName is provided.

- **languageCode** (optional) in query: BCP-47 language code for display names (e.g. "en", "es"). Optional when categoryName is provided. Omitted from the Google call when not supplied.

- **pageSize** (optional) in query: Maximum number of attribute metadata items to return. Google defaults to 200.
- **pageToken** (optional) in query: Pagination token from a previous response's nextPageToken field.

### Responses

#### 200: Attribute metadata fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: Only present in location mode.
- **attributeMetadata** `array[object]`: 
  - **parent** `string`: Resource name of the attribute (e.g. "attributes/has_delivery").
  - **valueType** `string`: Value type (e.g. BOOL, ENUM, URL, REPEATED_ENUM).
  - **displayName** `string`: Localized human-readable attribute name.
  - **groupDisplayName** `string`: Display name of the attribute group.
  - **repeatable** `boolean`: True if multiple values can be set simultaneously.
  - **deprecated** `boolean`: True if this attribute should no longer be used.
  - **valueMetadata** `array[object]`: Possible enum values (for ENUM / REPEATED_ENUM types).
    - **value** `string`: No description
    - **displayName** `string`: No description
- **nextPageToken** `string`: Present when additional pages of results are available.

#### 400: Invalid request (mixed modes, missing required params, wrong platform, or Google returned 4xx)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Access token is invalid or revoked. Reconnect the Google Business Profile account.

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Account not found

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get attributes API Reference

Returns GBP location attributes (amenities, services, accessibility, payment types). Available attributes vary by business category.

## GET /v1/accounts/{accountId}/gmb-attributes

**Get attributes**

Returns GBP location attributes (amenities, services, accessibility, payment types). Available attributes vary by business category.

### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Responses

#### 200: Attributes fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **attributes** `array[object]`: 
  - **name** `string`: Attribute identifier (e.g. has_delivery)
  - **valueType** `string`: Value type (BOOL, ENUM, URL, REPEATED_ENUM)
  - **values** `array[items]`: 
  - **repeatedEnumValue** `object`: 
    - **setValues** `array[string]`: 
    - **unsetValues** `array[string]`: 

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## PUT /v1/accounts/{accountId}/gmb-attributes

**Update attributes**

Updates location attributes (amenities, services, etc.).

The attributeMask specifies which attributes to update (comma-separated).


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **attributes** (required) `array`: No description
- **attributeMask** (required) `string`: Comma-separated attribute names to update (e.g. 'has_delivery,has_takeout')

### Responses

#### 200: Attributes updated successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **attributes** `array[object]`: 
  Type: `object`

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get food menus API Reference

Returns food menus for a GBP location including sections, items, pricing, and dietary info. Only for locations with food menu support.

## GET /v1/accounts/{accountId}/gmb-food-menus

**Get food menus**

Returns food menus for a GBP location including sections, items, pricing, and dietary info. Only for locations with food menu support.

### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Responses

#### 200: Food menus fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **name** `string`: Resource name of the food menus
- **menus** `array[FoodMenu]`: 

#### 400: Invalid request - not a Google Business account or missing location

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 403: Permission denied for this location

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 500: Failed to fetch food menus

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## PUT /v1/accounts/{accountId}/gmb-food-menus

**Update food menus**

Updates food menus for a GBP location. Send the full menus array. Use updateMask for partial updates.

### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **menus** (required) `array`: Array of food menus to set
- **updateMask** `string`: Field mask for partial updates (e.g. "menus")

### Responses

#### 200: Food menus updated successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **name** `string`: No description
- **menus** `array[FoodMenu]`: 

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token expired

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 403: Permission denied for this location

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 500: Failed to update food menus

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## FoodMenu

### Properties

- **labels** (required) `array`: No description
- **sections** `array`: No description
- **cuisines** `array`: Cuisine types (e.g. AMERICAN, ITALIAN, JAPANESE)
- **sourceUrl** `string`: URL of the original menu source

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get location details API Reference

Returns detailed GBP location info (hours, description, phone, website, categories, services). Use readMask to request specific fields.

## GET /v1/accounts/{accountId}/gmb-location-details

**Get location details**

Returns detailed GBP location info (hours, description, phone, website, categories, services). Use readMask to request specific fields.

### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **readMask** (optional) in query: Comma-separated fields to return. Available: name, title, phoneNumbers, categories, storefrontAddress, websiteUri, regularHours, specialHours, serviceArea, serviceItems, profile, openInfo, metadata, moreHours.
`title` and `metadata` are always included in the response so the `location` summary block can be populated, even if you omit them here.
Note: `location` is a derived response field, not a Google readMask value, passing it returns 400.


### Responses

#### 200: Location details fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **location** `object`: Compact public-facing summary derived from Google's `metadata`. Useful
for surfacing the "leave a review" URL (e.g. behind a QR code) without
parsing the raw block. Always populated regardless of readMask.
For unverified or new locations Google omits placeId/reviewUrl/mapsUri,
so those return as null and `isVerified` is false.

  - **name** `string`: Business name as set in GBP
  - **placeId** `string`: Google Maps Place ID for this location
  - **reviewUrl** `string`: Public "write a review" URL Google generates for this place
  - **mapsUri** `string`: Public Google Maps URL for this location
  - **isVerified** `boolean`: True when the location has Voice of Merchant (verified + live on Google)
- **title** `string`: Business name
- **regularHours** `object`: 
  - **periods** `array[object]`: 
    - **openDay** `string`: No description - one of: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
    - **openTime** `string`: Opening time in HH:MM format
    - **closeDay** `string`: No description
    - **closeTime** `string`: No description
- **specialHours** `object`: 
  - **specialHourPeriods** `array[object]`: 
    - **startDate** `object`: 
      - **year** `integer`: No description
      - **month** `integer`: No description
      - **day** `integer`: No description
    - **endDate** `object`: 
      - **year** `integer`: No description
      - **month** `integer`: No description
      - **day** `integer`: No description
    - **openTime** `string`: No description
    - **closeTime** `string`: No description
    - **closed** `boolean`: No description
- **profile** `object`: 
  - **description** `string`: Business description
- **websiteUri** `string`: No description
- **phoneNumbers** `object`: 
  - **primaryPhone** `string`: No description
  - **additionalPhones** `array[string]`: 
- **categories** `object`: Business categories (returned when readMask includes 'categories')
  - **primaryCategory** `object`: 
    - **name** `string`: Category resource name
    - **displayName** `string`: Human-readable category name
  - **additionalCategories** `array[object]`: 
    - **name** `string`: No description
    - **displayName** `string`: No description
- **serviceItems** `array[object]`: Services offered (returned when readMask includes 'serviceItems')
  - **structuredServiceItem** `object`: 
    - **serviceTypeId** `string`: No description
    - **description** `string`: No description
  - **freeFormServiceItem** `object`: 
    - **category** `string`: No description
    - **label** `object`: 
      - **displayName** `string`: No description
      - **languageCode** `string`: No description
  - **price** `object`: 
    - **currencyCode** `string`: No description
    - **units** `string`: No description
    - **nanos** `integer`: No description

#### 400: Invalid request. Most commonly raised when the readMask query
includes a value that is not a valid Google Business Information
field (e.g. `location`, which is a response-only derived field).


**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token expired

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PUT /v1/accounts/{accountId}/gmb-location-details

**Update location details**

Updates GBP location details. The updateMask field is required and specifies which fields to update.
This endpoint proxies Google's Business Information API locations.patch, so any valid updateMask field is supported.
Common fields: regularHours, specialHours, profile.description, websiteUri, phoneNumbers, categories, serviceItems.


### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **updateMask** (required) `string`: 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** `object`: No description
- **specialHours** `object`: No description
- **profile** `object`: No description
- **websiteUri** `string`: No description
- **phoneNumbers** `object`: No description
- **categories** `object`: Primary and additional business categories. Use updateMask='categories' to update.
- **serviceItems** `array`: Services offered by the business. Use updateMask='serviceItems' to update.

### Responses

#### 200: Location updated successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description

#### 400: Invalid request or missing updateMask

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token expired

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get reviews API Reference

Returns reviews for a GBP account including ratings, comments, and owner replies. Use nextPageToken for pagination.

## GET /v1/accounts/{accountId}/gmb-reviews

**Get reviews**

Returns reviews for a GBP account including ratings, comments, and owner replies. Use nextPageToken for pagination.

### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **pageSize** (optional) in query: Number of reviews to fetch per page (max 50)
- **pageToken** (optional) in query: Pagination token from previous response

### Responses

#### 200: Reviews fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **reviews** `array[object]`: 
  - **id** `string`: Review ID
  - **name** `string`: Full resource name
  - **reviewer** `object`: 
    - **displayName** `string`: No description
    - **profilePhotoUrl** `string`: No description
    - **isAnonymous** `boolean`: No description
  - **rating** `integer`: Numeric star rating
  - **starRating** `string`: Google's string rating - one of: ONE, TWO, THREE, FOUR, FIVE
  - **comment** `string`: Review text
  - **createTime** `string` (date-time): No description
  - **updateTime** `string` (date-time): No description
  - **reviewReply** `object`: 
    - **comment** `string`: Business owner reply
    - **updateTime** `string` (date-time): No description
- **averageRating** `number`: Overall average rating
- **totalReviewCount** `integer`: Total number of reviews
- **nextPageToken** `string`: Token for next page

#### 400: Invalid request - not a Google Business account or missing location

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 403: Permission denied for this location

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 500: Failed to fetch reviews

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get services API Reference

Gets the services offered by a Google Business Profile location.
Returns an array of service items (structured or free-form with optional price).


## GET /v1/accounts/{accountId}/gmb-services

**Get services**

Gets the services offered by a Google Business Profile location.
Returns an array of service items (structured or free-form with optional price).


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location.

### Responses

#### 200: Services fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **services** `array[object]`: 
  - **structuredServiceItem** `object`: 
    - **serviceTypeId** `string`: No description
    - **description** `string`: No description
  - **freeFormServiceItem** `object`: 
    - **category** `string`: No description
    - **label** `object`: 
      - **displayName** `string`: No description
      - **description** `string`: No description
  - **price** `object`: 
    - **currencyCode** `string`: No description (example: "USD")
    - **units** `string`: No description (example: "50")
    - **nanos** `integer`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## PUT /v1/accounts/{accountId}/gmb-services

**Replace services**

Replaces the entire service list for a location.
Google's API requires full replacement; individual item updates are not supported.
Each service can be structured (using a predefined serviceTypeId) or free-form (custom label).


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location.

### Request Body

- **serviceItems** (required) `array`: No description

### Responses

#### 200: Services updated successfully

**Response Body:**

- **success** `boolean`: No description
- **services** `array[object]`: 
  Type: `object`

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get verification state API Reference

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.

## GET /v1/accounts/{accountId}/gmb-verifications

**Get verification state**

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

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Responses

#### 200: Verification state fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **voiceOfMerchantState** `object`: Raw Voice of Merchant state from Google.
  - **hasVoiceOfMerchant** `boolean`: True when the listing is verified and published (eligible to surface reviews
  - **hasBusinessAuthority** `boolean`: True when the authenticated user has owner/manager authority over the listing.
  - **verify** `object`: Present when verification is the path to Voice of Merchant.
    - **hasPendingVerification** `boolean`: True when a verification is already in progress.
- **verifications** `array[object]`: Verification history, newest first. Empty when none exist.
  - **name** `string`: Resource name, e.g. "locations/123/verifications/0T1776879124712". The last segment is the verificationId.
  - **method** `string`: Method used (omitted on some entries). - one of: ADDRESS, EMAIL, PHONE_CALL, SMS, AUTO, VETTED_PARTNER
  - **state** `string`: No description - one of: PENDING, COMPLETED, FAILED
  - **createTime** `string` (date-time): No description

#### 400: Not a Google Business account or missing location

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## POST /v1/accounts/{accountId}/gmb-verifications

**Start a verification**

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

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location.

### Request Body

- **method** (required) `string`: The verification method. Selects which method-specific field below is required. - one of: ADDRESS, EMAIL, PHONE_CALL, SMS, AUTO, VETTED_PARTNER
- **languageCode** `string`: No description
- **phoneNumber** `string`: For PHONE_CALL / SMS.
- **emailAddress** `string`: For EMAIL.
- **mailerContact** `object`: For ADDRESS (postcard) verification.
- **context** `object`: ServiceBusinessContext (e.g. service address). Required for service-area businesses.

### Responses

#### 200: Verification started

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **verification** `object`: 
  - **name** `string`: No description
  - **method** `string`: No description - one of: ADDRESS, EMAIL, PHONE_CALL, SMS, AUTO, VETTED_PARTNER
  - **state** `string`: No description - one of: PENDING, COMPLETED, FAILED
  - **createTime** `string` (date-time): No description

#### 400: Invalid request (e.g. wrong field for the chosen method, or Google rejected it)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# List media API Reference

Lists media items (photos) for a Google Business Profile location.
Returns photo URLs, descriptions, categories, and metadata.


## GET /v1/accounts/{accountId}/gmb-media

**List media**

Lists media items (photos) for a Google Business Profile location.
Returns photo URLs, descriptions, categories, and metadata.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **pageSize** (optional) in query: Number of items to return (max 100)
- **pageToken** (optional) in query: Pagination token from previous response

### Responses

#### 200: Media items fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **mediaItems** `array[object]`: 
  - **name** `string`: Resource name
  - **mediaFormat** `string`: No description - one of: PHOTO, VIDEO
  - **sourceUrl** `string`: No description
  - **googleUrl** `string`: Google-hosted URL
  - **thumbnailUrl** `string`: No description
  - **description** `string`: No description
  - **createTime** `string` (date-time): No description
  - **locationAssociation** `object`: 
    - **category** `string`: No description
- **nextPageToken** `string`: No description
- **totalMediaItemsCount** `integer`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## POST /v1/accounts/{accountId}/gmb-media

**Upload photo**

Creates a media item (photo) for a location from a publicly accessible URL.

Categories determine where the photo appears: COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, FOOD_AND_DRINK, MENU, PRODUCT, TEAMS, ADDITIONAL.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **sourceUrl** (required) `string`: Publicly accessible image URL
- **mediaFormat** `string`: No description - one of: PHOTO, VIDEO
- **description** `string`: Photo description
- **category** `string`: Where the photo appears on the listing - one of: COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, FOOD_AND_DRINK, MENU, PRODUCT, TEAMS, ADDITIONAL

### Responses

#### 200: Media created successfully

**Response Body:**

- **success** `boolean`: No description
- **name** `string`: No description
- **mediaFormat** `string`: No description
- **googleUrl** `string`: No description

#### 400: Invalid request or unsupported media format

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## DELETE /v1/accounts/{accountId}/gmb-media

**Delete photo**

Deletes a photo or media item from a GBP location.

### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **mediaId** (required) in query: The media item ID to delete

### Responses

#### 200: Media deleted successfully

**Response Body:**

- **success** `boolean`: No description
- **deleted** `boolean`: No description
- **mediaId** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# List action links API Reference

Lists place action links for a Google Business Profile location.

Place actions are the booking, ordering, and reservation buttons that appear on your listing.


## GET /v1/accounts/{accountId}/gmb-place-actions

**List action links**

Lists place action links for a Google Business Profile location.

Place actions are the booking, ordering, and reservation buttons that appear on your listing.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **pageSize** (optional) in query: No description
- **pageToken** (optional) in query: No description

### Responses

#### 200: Place actions fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **placeActionLinks** `array[object]`: 
  - **name** `string`: Resource name
  - **uri** `string`: Action URL
  - **placeActionType** `string`: No description
  - **createTime** `string` (date-time): No description
  - **updateTime** `string` (date-time): No description
- **nextPageToken** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## POST /v1/accounts/{accountId}/gmb-place-actions

**Create action link**

Creates a place action link for a location.

Available action types: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **uri** (required) `string`: The action URL
- **placeActionType** (required) `string`: Type of action - one of: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE

### Responses

#### 200: Place action created successfully

**Response Body:**

- **success** `boolean`: No description
- **name** `string`: Resource name of the created link
- **uri** `string`: No description
- **placeActionType** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## DELETE /v1/accounts/{accountId}/gmb-place-actions

**Delete action link**

Deletes a place action link (e.g. booking or ordering URL) from a GBP location.

### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **name** (required) in query: The resource name of the place action link (e.g. locations/123/placeActionLinks/456)

### Responses

#### 200: Place action deleted successfully

**Response Body:**

- **success** `boolean`: No description
- **deleted** `boolean`: No description
- **name** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## PATCH /v1/accounts/{accountId}/gmb-place-actions

**Update action link**

Updates a place action link (change URL or action type).
Only the fields included in the request body will be updated.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location.

### Request Body

- **name** (required) `string`: Resource name of the place action link (e.g. locations/123/placeActionLinks/456)
- **uri** `string`: New action URL
- **placeActionType** `string`: New action type - one of: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE

### Responses

#### 200: Place action updated successfully

**Response Body:**

- **success** `boolean`: No description
- **name** `string`: No description
- **uri** `string`: No description
- **placeActionType** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Reply to a review API Reference

Posts (or updates) the business owner reply to a Google Business review.
The reply is associated with the account's currently selected location (set via /v1/accounts/{accountId}/gmb-locations).
Calling this endpoint a second time on the same review overwrites the previous reply (PUT semantics on Google's side).


## POST /v1/accounts/{accountId}/gmb-reviews/{reviewId}/reply

**Reply to a review**

Posts (or updates) the business owner reply to a Google Business review.
The reply is associated with the account's currently selected location (set via /v1/accounts/{accountId}/gmb-locations).
Calling this endpoint a second time on the same review overwrites the previous reply (PUT semantics on Google's side).


### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **reviewId** (required) in path: The review ID portion (e.g. "AIe9_BGx1234567890"), not the full resource name

### Request Body

- **comment** (required) `string`: The reply text to post on the review. Must be non-empty.

### Responses

#### 200: Reply posted successfully

**Response Body:**

- **success** `boolean`: No description
- **reviewId** `string`: No description
- **platform** `string`: No description (example: "googlebusiness")

#### 400: Invalid request, missing comment, non-GBP account, or account missing location metadata

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid (account must be reconnected)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 500: Failed to post reply

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## DELETE /v1/accounts/{accountId}/gmb-reviews/{reviewId}/reply

**Delete a review reply**

Removes the business owner reply from a Google Business review. The review itself remains.

### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **reviewId** (required) in path: The review ID portion (e.g. "AIe9_BGx1234567890"), not the full resource name

### Responses

#### 200: Reply deleted successfully

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description
- **platform** `string`: No description (example: "googlebusiness")

#### 400: Invalid request, non-GBP account, or account missing location metadata

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid (account must be reconnected)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 500: Failed to delete reply

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Start a verification API Reference

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.

## GET /v1/accounts/{accountId}/gmb-verifications

**Get verification state**

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

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Responses

#### 200: Verification state fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **voiceOfMerchantState** `object`: Raw Voice of Merchant state from Google.
  - **hasVoiceOfMerchant** `boolean`: True when the listing is verified and published (eligible to surface reviews
  - **hasBusinessAuthority** `boolean`: True when the authenticated user has owner/manager authority over the listing.
  - **verify** `object`: Present when verification is the path to Voice of Merchant.
    - **hasPendingVerification** `boolean`: True when a verification is already in progress.
- **verifications** `array[object]`: Verification history, newest first. Empty when none exist.
  - **name** `string`: Resource name, e.g. "locations/123/verifications/0T1776879124712". The last segment is the verificationId.
  - **method** `string`: Method used (omitted on some entries). - one of: ADDRESS, EMAIL, PHONE_CALL, SMS, AUTO, VETTED_PARTNER
  - **state** `string`: No description - one of: PENDING, COMPLETED, FAILED
  - **createTime** `string` (date-time): No description

#### 400: Not a Google Business account or missing location

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## POST /v1/accounts/{accountId}/gmb-verifications

**Start a verification**

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

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location.

### Request Body

- **method** (required) `string`: The verification method. Selects which method-specific field below is required. - one of: ADDRESS, EMAIL, PHONE_CALL, SMS, AUTO, VETTED_PARTNER
- **languageCode** `string`: No description
- **phoneNumber** `string`: For PHONE_CALL / SMS.
- **emailAddress** `string`: For EMAIL.
- **mailerContact** `object`: For ADDRESS (postcard) verification.
- **context** `object`: ServiceBusinessContext (e.g. service address). Required for service-area businesses.

### Responses

#### 200: Verification started

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **verification** `object`: 
  - **name** `string`: No description
  - **method** `string`: No description - one of: ADDRESS, EMAIL, PHONE_CALL, SMS, AUTO, VETTED_PARTNER
  - **state** `string`: No description - one of: PENDING, COMPLETED, FAILED
  - **createTime** `string` (date-time): No description

#### 400: Invalid request (e.g. wrong field for the chosen method, or Google rejected it)

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Update attributes API Reference

Updates location attributes (amenities, services, etc.).

The attributeMask specifies which attributes to update (comma-separated).


## GET /v1/accounts/{accountId}/gmb-attributes

**Get attributes**

Returns GBP location attributes (amenities, services, accessibility, payment types). Available attributes vary by business category.

### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Responses

#### 200: Attributes fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **attributes** `array[object]`: 
  - **name** `string`: Attribute identifier (e.g. has_delivery)
  - **valueType** `string`: Value type (BOOL, ENUM, URL, REPEATED_ENUM)
  - **values** `array[items]`: 
  - **repeatedEnumValue** `object`: 
    - **setValues** `array[string]`: 
    - **unsetValues** `array[string]`: 

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## PUT /v1/accounts/{accountId}/gmb-attributes

**Update attributes**

Updates location attributes (amenities, services, etc.).

The attributeMask specifies which attributes to update (comma-separated).


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **attributes** (required) `array`: No description
- **attributeMask** (required) `string`: Comma-separated attribute names to update (e.g. 'has_delivery,has_takeout')

### Responses

#### 200: Attributes updated successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **attributes** `array[object]`: 
  Type: `object`

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Update food menus API Reference

Updates food menus for a GBP location. Send the full menus array. Use updateMask for partial updates.

## GET /v1/accounts/{accountId}/gmb-food-menus

**Get food menus**

Returns food menus for a GBP location including sections, items, pricing, and dietary info. Only for locations with food menu support.

### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Responses

#### 200: Food menus fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **name** `string`: Resource name of the food menus
- **menus** `array[FoodMenu]`: 

#### 400: Invalid request - not a Google Business account or missing location

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token invalid

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 403: Permission denied for this location

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 500: Failed to fetch food menus

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## PUT /v1/accounts/{accountId}/gmb-food-menus

**Update food menus**

Updates food menus for a GBP location. Send the full menus array. Use updateMask for partial updates.

### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **menus** (required) `array`: Array of food menus to set
- **updateMask** `string`: Field mask for partial updates (e.g. "menus")

### Responses

#### 200: Food menus updated successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **name** `string`: No description
- **menus** `array[FoodMenu]`: 

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token expired

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 403: Permission denied for this location

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 500: Failed to update food menus

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## FoodMenu

### Properties

- **labels** (required) `array`: No description
- **sections** `array`: No description
- **cuisines** `array`: Cuisine types (e.g. AMERICAN, ITALIAN, JAPANESE)
- **sourceUrl** `string`: URL of the original menu source

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Update location details API Reference

Updates GBP location details. The updateMask field is required and specifies which fields to update.
This endpoint proxies Google's Business Information API locations.patch, so any valid updateMask field is supported.
Common fields: regularHours, specialHours, profile.description, websiteUri, phoneNumbers, categories, serviceItems.


## GET /v1/accounts/{accountId}/gmb-location-details

**Get location details**

Returns detailed GBP location info (hours, description, phone, website, categories, services). Use readMask to request specific fields.

### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **readMask** (optional) in query: Comma-separated fields to return. Available: name, title, phoneNumbers, categories, storefrontAddress, websiteUri, regularHours, specialHours, serviceArea, serviceItems, profile, openInfo, metadata, moreHours.
`title` and `metadata` are always included in the response so the `location` summary block can be populated, even if you omit them here.
Note: `location` is a derived response field, not a Google readMask value, passing it returns 400.


### Responses

#### 200: Location details fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **location** `object`: Compact public-facing summary derived from Google's `metadata`. Useful
for surfacing the "leave a review" URL (e.g. behind a QR code) without
parsing the raw block. Always populated regardless of readMask.
For unverified or new locations Google omits placeId/reviewUrl/mapsUri,
so those return as null and `isVerified` is false.

  - **name** `string`: Business name as set in GBP
  - **placeId** `string`: Google Maps Place ID for this location
  - **reviewUrl** `string`: Public "write a review" URL Google generates for this place
  - **mapsUri** `string`: Public Google Maps URL for this location
  - **isVerified** `boolean`: True when the location has Voice of Merchant (verified + live on Google)
- **title** `string`: Business name
- **regularHours** `object`: 
  - **periods** `array[object]`: 
    - **openDay** `string`: No description - one of: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
    - **openTime** `string`: Opening time in HH:MM format
    - **closeDay** `string`: No description
    - **closeTime** `string`: No description
- **specialHours** `object`: 
  - **specialHourPeriods** `array[object]`: 
    - **startDate** `object`: 
      - **year** `integer`: No description
      - **month** `integer`: No description
      - **day** `integer`: No description
    - **endDate** `object`: 
      - **year** `integer`: No description
      - **month** `integer`: No description
      - **day** `integer`: No description
    - **openTime** `string`: No description
    - **closeTime** `string`: No description
    - **closed** `boolean`: No description
- **profile** `object`: 
  - **description** `string`: Business description
- **websiteUri** `string`: No description
- **phoneNumbers** `object`: 
  - **primaryPhone** `string`: No description
  - **additionalPhones** `array[string]`: 
- **categories** `object`: Business categories (returned when readMask includes 'categories')
  - **primaryCategory** `object`: 
    - **name** `string`: Category resource name
    - **displayName** `string`: Human-readable category name
  - **additionalCategories** `array[object]`: 
    - **name** `string`: No description
    - **displayName** `string`: No description
- **serviceItems** `array[object]`: Services offered (returned when readMask includes 'serviceItems')
  - **structuredServiceItem** `object`: 
    - **serviceTypeId** `string`: No description
    - **description** `string`: No description
  - **freeFormServiceItem** `object`: 
    - **category** `string`: No description
    - **label** `object`: 
      - **displayName** `string`: No description
      - **languageCode** `string`: No description
  - **price** `object`: 
    - **currencyCode** `string`: No description
    - **units** `string`: No description
    - **nanos** `integer`: No description

#### 400: Invalid request. Most commonly raised when the readMask query
includes a value that is not a valid Google Business Information
field (e.g. `location`, which is a response-only derived field).


**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token expired

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PUT /v1/accounts/{accountId}/gmb-location-details

**Update location details**

Updates GBP location details. The updateMask field is required and specifies which fields to update.
This endpoint proxies Google's Business Information API locations.patch, so any valid updateMask field is supported.
Common fields: regularHours, specialHours, profile.description, websiteUri, phoneNumbers, categories, serviceItems.


### Parameters

- **accountId** (required) in path: The Zernio account ID (from /v1/accounts)
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **updateMask** (required) `string`: 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** `object`: No description
- **specialHours** `object`: No description
- **profile** `object`: No description
- **websiteUri** `string`: No description
- **phoneNumbers** `object`: No description
- **categories** `object`: Primary and additional business categories. Use updateMask='categories' to update.
- **serviceItems** `array`: Services offered by the business. Use updateMask='serviceItems' to update.

### Responses

#### 200: Location updated successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description

#### 400: Invalid request or missing updateMask

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized or token expired

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Update action link API Reference

Updates a place action link (change URL or action type).
Only the fields included in the request body will be updated.


## GET /v1/accounts/{accountId}/gmb-place-actions

**List action links**

Lists place action links for a Google Business Profile location.

Place actions are the booking, ordering, and reservation buttons that appear on your listing.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **pageSize** (optional) in query: No description
- **pageToken** (optional) in query: No description

### Responses

#### 200: Place actions fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **placeActionLinks** `array[object]`: 
  - **name** `string`: Resource name
  - **uri** `string`: Action URL
  - **placeActionType** `string`: No description
  - **createTime** `string` (date-time): No description
  - **updateTime** `string` (date-time): No description
- **nextPageToken** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## POST /v1/accounts/{accountId}/gmb-place-actions

**Create action link**

Creates a place action link for a location.

Available action types: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.

### Request Body

- **uri** (required) `string`: The action URL
- **placeActionType** (required) `string`: Type of action - one of: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE

### Responses

#### 200: Place action created successfully

**Response Body:**

- **success** `boolean`: No description
- **name** `string`: Resource name of the created link
- **uri** `string`: No description
- **placeActionType** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## DELETE /v1/accounts/{accountId}/gmb-place-actions

**Delete action link**

Deletes a place action link (e.g. booking or ordering URL) from a GBP location.

### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
- **name** (required) in query: The resource name of the place action link (e.g. locations/123/placeActionLinks/456)

### Responses

#### 200: Place action deleted successfully

**Response Body:**

- **success** `boolean`: No description
- **deleted** `boolean`: No description
- **name** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## PATCH /v1/accounts/{accountId}/gmb-place-actions

**Update action link**

Updates a place action link (change URL or action type).
Only the fields included in the request body will be updated.


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location.

### Request Body

- **name** (required) `string`: Resource name of the place action link (e.g. locations/123/placeActionLinks/456)
- **uri** `string`: New action URL
- **placeActionType** `string`: New action type - one of: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE

### Responses

#### 200: Place action updated successfully

**Response Body:**

- **success** `boolean`: No description
- **name** `string`: No description
- **uri** `string`: No description
- **placeActionType** `string`: No description

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Replace services API Reference

Replaces the entire service list for a location.
Google's API requires full replacement; individual item updates are not supported.
Each service can be structured (using a predefined serviceTypeId) or free-form (custom label).


## GET /v1/accounts/{accountId}/gmb-services

**Get services**

Gets the services offered by a Google Business Profile location.
Returns an array of service items (structured or free-form with optional price).


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location.

### Responses

#### 200: Services fetched successfully

**Response Body:**

- **success** `boolean`: No description
- **accountId** `string`: No description
- **locationId** `string`: No description
- **services** `array[object]`: 
  - **structuredServiceItem** `object`: 
    - **serviceTypeId** `string`: No description
    - **description** `string`: No description
  - **freeFormServiceItem** `object`: 
    - **category** `string`: No description
    - **label** `object`: 
      - **displayName** `string`: No description
      - **description** `string`: No description
  - **price** `object`: 
    - **currencyCode** `string`: No description (example: "USD")
    - **units** `string`: No description (example: "50")
    - **nanos** `integer`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---

## PUT /v1/accounts/{accountId}/gmb-services

**Replace services**

Replaces the entire service list for a location.
Google's API requires full replacement; individual item updates are not supported.
Each service can be structured (using a predefined serviceTypeId) or free-form (custom label).


### Parameters

- **accountId** (required) in path: No description
- **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location.

### Request Body

- **serviceItems** (required) `array`: No description

### Responses

#### 200: Services updated successfully

**Response Body:**

- **success** `boolean`: No description
- **services** `array[object]`: 
  Type: `object`

#### 400: Invalid request

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get analytics for a single conversation API Reference

Per-conversation inbox analytics. The inbox analog of
/v1/analytics/post-timeline — one conversation, daily totals,
source mix.

The {conversationId} path param accepts EITHER the Mongo `_id` of
the Conversation document OR its `platformConversationId` (the
same identity used by metadata.conversationId at ingest time).
Ownership is verified in MongoDB against the caller's team
before the Tinybird query fires.

Max date range is 365 days.


## GET /v1/analytics/inbox/conversations/{conversationId}

**Get analytics for a single conversation**

Per-conversation inbox analytics. The inbox analog of
/v1/analytics/post-timeline — one conversation, daily totals,
source mix.

The {conversationId} path param accepts EITHER the Mongo `_id` of
the Conversation document OR its `platformConversationId` (the
same identity used by metadata.conversationId at ingest time).
Ownership is verified in MongoDB against the caller's team
before the Tinybird query fires.

Max date range is 365 days.


### Parameters

- **conversationId** (required) in path: Mongo _id or platformConversationId.
- **fromDate** (required) in query: No description
- **toDate** (optional) in query: No description

### Responses

#### 200: Per-conversation analytics

**Response Body:**

- **success** `boolean`: No description
- **conversationId** `string`: The platformConversationId
- **mongoId** `string`: No description
- **platform** `string`: No description
- **from** `string` (date): No description
- **to** `string` (date): No description
- **summary** `object`: 
  - **received** `integer`: No description
  - **sent** `integer`: No description
  - **read** `integer`: No description
  - **failed** `integer`: No description
  - **totalMessages** `integer`: No description
  - **firstMessageAt** `string` (date-time): No description
  - **lastMessageAt** `string` (date-time): No description
- **timeseries** `array[object]`: 
  - **date** `string` (date): No description
  - **sent** `integer`: No description
  - **received** `integer`: No description
  - **read** `integer`: No description
  - **failed** `integer`: No description
- **bySource** `array[object]`: 
  - **source** `string`: (unspecified) for legacy rows with no metadata.source
  - **count** `integer`: No description

#### 400: Validation error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Conversation not found or not owned by the caller's team

**Response Body:**

- **error** `string`: No description (example: "Conversation not found.")
- **code** `string`: No description (example: "conversation_not_found")

#### 500: Internal server error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get inbox day-of-week × hour-of-day heatmap API Reference

Day-of-week × hour-of-day breakdown of inbox messages. Buckets are
sparse — only cells with at least one event are returned; clients
zero-fill the rest to render the full 7×24 grid. The `dow` field
follows ClickHouse's `toDayOfWeek` convention (1 = Monday … 7 =
Sunday). Max date range is 365 days.


## GET /v1/analytics/inbox/heatmap

**Get inbox day-of-week × hour-of-day heatmap**

Day-of-week × hour-of-day breakdown of inbox messages. Buckets are
sparse — only cells with at least one event are returned; clients
zero-fill the rest to render the full 7×24 grid. The `dow` field
follows ClickHouse's `toDayOfWeek` convention (1 = Monday … 7 =
Sunday). Max date range is 365 days.


### Parameters

- **fromDate** (required) in query: No description
- **toDate** (optional) in query: No description
- **profileId** (optional) in query: No description
- **platform** (optional) in query: No description
- **accountId** (optional) in query: No description
- **source** (optional) in query: No description
- **action** (optional) in query: Narrow to a single event type. "all" or omitted means no filter.

### Responses

#### 200: Heatmap buckets

**Response Body:**

- **success** `boolean`: No description
- **from** `string` (date): No description
- **to** `string` (date): No description
- **buckets** `array[object]`: 
  - **dow** `integer`: 1 = Monday, 7 = Sunday
  - **hour** `integer`: No description
  - **received** `integer`: No description
  - **sent** `integer`: No description
  - **read** `integer`: No description

#### 400: Validation error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Internal server error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get inbox response-time stats API Reference

Time-to-first-response stats. Pairs each received message with the
next sent message in the same conversation and reports the delta
as both summary statistics and a fixed-bucket histogram suited
for the analytics page's TTR chart.

`sampleSize` reflects only conversations that received AND got a
reply in the window — received-but-never-answered conversations
are excluded. Compare against /v1/analytics/inbox/volume's
`summary.received` to compute reply rate.

Max date range is 365 days.


## GET /v1/analytics/inbox/response-time

**Get inbox response-time stats**

Time-to-first-response stats. Pairs each received message with the
next sent message in the same conversation and reports the delta
as both summary statistics and a fixed-bucket histogram suited
for the analytics page's TTR chart.

`sampleSize` reflects only conversations that received AND got a
reply in the window — received-but-never-answered conversations
are excluded. Compare against /v1/analytics/inbox/volume's
`summary.received` to compute reply rate.

Max date range is 365 days.


### Parameters

- **fromDate** (required) in query: No description
- **toDate** (optional) in query: No description
- **profileId** (optional) in query: No description
- **platform** (optional) in query: No description
- **accountId** (optional) in query: No description

### Responses

#### 200: Response-time summary + histogram

**Response Body:**

- **success** `boolean`: No description
- **from** `string` (date): No description
- **to** `string` (date): No description
- **summary** `object`: 
  - **sampleSize** `integer`: No description
  - **medianSeconds** `integer`: No description
  - **p90Seconds** `integer`: No description
  - **p99Seconds** `integer`: No description
  - **meanSeconds** `integer`: No description
  - **fastestSeconds** `integer`: No description
  - **slowestSeconds** `integer`: No description
- **histogram** `array[object]`: 
  - **bucket** `string`: Human label (0-1m, 1-5m, 5-15m, 15-60m, 1-4h, 4-24h, 1d+)
  - **lowerSeconds** `integer`: No description
  - **upperSeconds** `integer`: null on the open-ended last bucket
  - **count** `integer`: No description

#### 400: Validation error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Internal server error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get inbox source breakdown API Reference

Breakdown of inbox messages by their lineage source (the
`metadata.source` field set at ingest time: human / workflow /
sequence / broadcast / comment_automation / api / contact /
platform). Each source row also carries a per-platform sub-split.
Max date range is 365 days.


## GET /v1/analytics/inbox/source-breakdown

**Get inbox source breakdown**

Breakdown of inbox messages by their lineage source (the
`metadata.source` field set at ingest time: human / workflow /
sequence / broadcast / comment_automation / api / contact /
platform). Each source row also carries a per-platform sub-split.
Max date range is 365 days.


### Parameters

- **fromDate** (required) in query: No description
- **toDate** (optional) in query: No description
- **profileId** (optional) in query: No description
- **platform** (optional) in query: No description
- **accountId** (optional) in query: No description

### Responses

#### 200: Source breakdown

**Response Body:**

- **success** `boolean`: No description
- **from** `string` (date): No description
- **to** `string` (date): No description
- **sources** `array[object]`: 
  - **source** `string`: No description
  - **received** `integer`: No description
  - **sent** `integer`: No description
  - **read** `integer`: No description
  - **byPlatform** `array[object]`: 
    - **platform** `string`: No description
    - **received** `integer`: No description
    - **sent** `integer`: No description
    - **read** `integer`: No description

#### 400: Validation error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Internal server error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get top accounts by inbox volume API Reference

Leaderboard of social accounts by inbox message volume. Decorates
each row with display labels from the live SocialAccount record
(so the UI shows username + displayName, not just an ID). Accounts
that no longer map to a SocialAccount surface as "(disconnected)"
so the row stays visible. Max date range is 365 days.


## GET /v1/analytics/inbox/top-accounts

**Get top accounts by inbox volume**

Leaderboard of social accounts by inbox message volume. Decorates
each row with display labels from the live SocialAccount record
(so the UI shows username + displayName, not just an ID). Accounts
that no longer map to a SocialAccount surface as "(disconnected)"
so the row stays visible. Max date range is 365 days.


### Parameters

- **fromDate** (required) in query: No description
- **toDate** (optional) in query: No description
- **profileId** (optional) in query: No description
- **platform** (optional) in query: No description
- **source** (optional) in query: No description
- **limit** (optional) in query: Cap on returned rows. Lower than the posting listing's 100 because each row triggers a SocialAccount Mongo lookup.

### Responses

#### 200: Top accounts leaderboard

**Response Body:**

- **success** `boolean`: No description
- **from** `string` (date): No description
- **to** `string` (date): No description
- **accounts** `array[object]`: 
  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **displayName** `string`: (disconnected) when the SocialAccount no longer exists
  - **username** `string`: No description
  - **received** `integer`: No description
  - **sent** `integer`: No description
  - **total** `integer`: No description
  - **conversations** `integer`: No description
  - **medianResponseSeconds** `integer`: No description
  - **repliedCount** `integer`: Distinguishes 'instant replies' from 'no replies at all' so a zero medianResponseSeconds with repliedCount=0 renders as '—' instead of '0s'

#### 400: Validation error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Internal server error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get inbox messaging volume API Reference

Daily inbox messaging volume + breakdowns. Folds the raw messaging
events into three projections so the client can render the volume
chart, KPI strip, and per-platform stacked bar from a single call.
Max date range is 365 days.


## GET /v1/analytics/inbox/volume

**Get inbox messaging volume**

Daily inbox messaging volume + breakdowns. Folds the raw messaging
events into three projections so the client can render the volume
chart, KPI strip, and per-platform stacked bar from a single call.
Max date range is 365 days.


### Parameters

- **fromDate** (required) in query: Inclusive lower bound (YYYY-MM-DD). Required.
- **toDate** (optional) in query: Inclusive upper bound (YYYY-MM-DD). Defaults to today.
- **profileId** (optional) in query: No description
- **platform** (optional) in query: Filter by single platform (facebook, instagram, twitter, etc.).
- **accountId** (optional) in query: No description
- **source** (optional) in query: Filter by metadata.source lineage (human, workflow, sequence, broadcast, comment_automation, api, contact, platform).

### Responses

#### 200: Volume breakdown

**Response Body:**

- **success** `boolean`: No description
- **from** `string` (date): No description
- **to** `string` (date): No description
- **summary** `object`: 
  - **received** `integer`: No description
  - **sent** `integer`: No description
  - **read** `integer`: No description
  - **failed** `integer`: No description
  - **uniqueConversations** `integer`: No description
- **timeseries** `array[object]`: 
  - **date** `string` (date): No description
  - **sent** `integer`: No description
  - **received** `integer`: No description
  - **read** `integer`: No description
  - **failed** `integer`: No description
- **byPlatform** `array[object]`: 
  - **platform** `string`: No description
  - **sent** `integer`: No description
  - **received** `integer`: No description
  - **read** `integer`: No description
  - **failed** `integer`: No description

#### 400: Validation error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Internal server error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# List conversations with inbox analytics API Reference

Per-conversation listing with per-row totals + first/last message
timestamps. The inbox analog of GET /v1/analytics (posts listing) —
same filter shape, same pagination, same sort/order semantics.
Use as the entry point for the per-conversation analytics drawer
at /v1/analytics/inbox/conversations/{conversationId}.

Rows are enriched with the conversation's participant info
(`participantName`, `participantUsername`, `participantPicture`)
and last-message preview by joining the Conversation document
scoped to the caller's team. Max date range is 365 days.


## GET /v1/analytics/inbox/conversations

**List conversations with inbox analytics**

Per-conversation listing with per-row totals + first/last message
timestamps. The inbox analog of GET /v1/analytics (posts listing) —
same filter shape, same pagination, same sort/order semantics.
Use as the entry point for the per-conversation analytics drawer
at /v1/analytics/inbox/conversations/{conversationId}.

Rows are enriched with the conversation's participant info
(`participantName`, `participantUsername`, `participantPicture`)
and last-message preview by joining the Conversation document
scoped to the caller's team. Max date range is 365 days.


### Parameters

- **fromDate** (required) in query: No description
- **toDate** (optional) in query: No description
- **profileId** (optional) in query: No description
- **platform** (optional) in query: No description
- **accountId** (optional) in query: No description
- **source** (optional) in query: No description
- **limit** (optional) in query: No description
- **page** (optional) in query: No description
- **sortBy** (optional) in query: No description
- **order** (optional) in query: No description

### Responses

#### 200: Paginated conversation analytics list

**Response Body:**

- **success** `boolean`: No description
- **from** `string` (date): No description
- **to** `string` (date): No description
- **items** `array[object]`: 
  - **conversationId** `string`: The platformConversationId (the same identity used by metadata.conversationId)
  - **mongoId** `string`: The Conversation document _id, when a matching doc exists
  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **participantName** `string`: No description
  - **participantUsername** `string`: No description
  - **participantPicture** `string`: No description
  - **lastMessage** `string`: Cached preview from the Conversation doc
  - **totalMessages** `integer`: No description
  - **received** `integer`: No description
  - **sent** `integer`: No description
  - **read** `integer`: No description
  - **failed** `integer`: No description
  - **firstMessageAt** `string` (date-time): No description
  - **lastMessageAt** `string` (date-time): No description
- **pagination** `object`: 
  - **page** `integer`: No description
  - **limit** `integer`: No description
  - **total** `integer`: No description
  - **totalPages** `integer`: No description
  - **hasMore** `boolean`: No description

#### 400: Validation error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Internal server error

**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## ErrorResponse

### Properties

- **error** `string`: No description
- **details** `object`: No description

---

# Get Instagram story insights API Reference

Returns metrics for a single story. The `source` field discriminates
between three states:

- `live` — fetched from Meta in real time (story is still active)
- `cached` — fetched from a persisted `story_insights` webhook payload
  (story has expired but we received its final-state metrics from Meta)
- `unavailable` — story has expired and we never received its webhook
  payload (for example, the account connected after the story expired)

Field semantics follow Meta's API. Counts below 5 may be returned as 0
due to Meta's privacy floor on small audiences. The `navigation` field
is the sum of `tapsForward + tapsBack + exits + swipesForward`.


## GET /v1/accounts/{accountId}/instagram/stories/{storyId}/insights

**Get Instagram story insights**

Returns metrics for a single story. The `source` field discriminates
between three states:

- `live` — fetched from Meta in real time (story is still active)
- `cached` — fetched from a persisted `story_insights` webhook payload
  (story has expired but we received its final-state metrics from Meta)
- `unavailable` — story has expired and we never received its webhook
  payload (for example, the account connected after the story expired)

Field semantics follow Meta's API. Counts below 5 may be returned as 0
due to Meta's privacy floor on small audiences. The `navigation` field
is the sum of `tapsForward + tapsBack + exits + swipesForward`.


### Parameters

- **accountId** (required) in path: The Instagram account ID
- **storyId** (required) in path: The Instagram media ID of the story.

### Responses

#### 200: Story insights

**Response Body:**

- **data** (required) `object`: 
  - **source** (required) `string`: No description - one of: live, cached, unavailable
  - **metrics** (required) `object`: 
    - **views** (required) `integer`: Total story plays. Replaces deprecated 'impressions' for media created after 2024-07-02.
    - **reach** (required) `integer`: Unique accounts that saw the story.
    - **replies** (required) `integer`: DMs sent in reply to the story.
    - **shares** (required) `integer`: No description
    - **navigation** (required) `integer`: Total nav actions (tapsForward + tapsBack + exits + swipesForward).
    - **tapsForward** (required) `integer`: Tapped right to next slide of SAME story.
    - **tapsBack** (required) `integer`: Tapped left to previous slide.
    - **exits** (required) `integer`: Closed Stories interface entirely.
    - **swipesForward** (required) `integer`: Swiped left to next account's story.
    - **profileVisits** (required) `integer`: No description
    - **follows** (required) `integer`: No description
    - **reposts** (required) `integer`: No description
    - **totalInteractions** (required) `integer`: No description

#### 400: Invalid request.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Instagram account not found.

---

---

# List active Instagram stories API Reference

Returns the IG Business/Creator account's currently-active stories.
Meta keeps stories live for 24h; expired stories are not returned.

Limitations propagated from Meta (these are NOT bugs):
- 24h window only
- Live videos excluded
- Reshared stories not returned
- `mediaUrl` may be null if Meta flagged the story for copyright
- `caption`, `likeCount`, `commentsCount` do not apply to story media


## GET /v1/accounts/{accountId}/instagram/stories

**List active Instagram stories**

Returns the IG Business/Creator account's currently-active stories.
Meta keeps stories live for 24h; expired stories are not returned.

Limitations propagated from Meta (these are NOT bugs):
- 24h window only
- Live videos excluded
- Reshared stories not returned
- `mediaUrl` may be null if Meta flagged the story for copyright
- `caption`, `likeCount`, `commentsCount` do not apply to story media


### Parameters

- **accountId** (required) in path: The Instagram account ID

### Responses

#### 200: Active stories

**Response Body:**

- **data** (required) `array[object]`: 
  - **id** (required) `string`: Instagram media ID of the story.
  - **mediaType** `string`: IMAGE / VIDEO / CAROUSEL_ALBUM
  - **mediaProductType** `string`: Always 'STORY' for this endpoint.
  - **mediaUrl** `string`: Direct media URL. Null if Meta flagged the story for copyright. URL expires when the story expires.
  - **permalink** `string`: Public Instagram permalink to the story (only viewable while live).
  - **thumbnailUrl** `string`: Thumbnail URL for video stories.
  - **timestamp** `string` (date-time): When the story was posted.

#### 400: Invalid request.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Instagram account not found.

---

---

# Create invite token API Reference

Generate a secure invite link to grant team members access to your profiles.
Invites expire after 7 days and are single-use.


## POST /v1/invite/tokens

**Create invite token**

Generate a secure invite link to grant team members access to your profiles.
Invites expire after 7 days and are single-use.


### Request Body

- **scope** (required) `string`: 'all' grants access to all profiles, 'profiles' restricts to specific profiles - one of: all, profiles
- **profileIds** `array`: Required if scope is 'profiles'. Array of profile IDs to grant access to.
- **role** `string`: Org role granted to the invitee. Defaults to 'member'. 'viewer' creates a read-only member who can view everything in their profile scope but cannot perform any content mutation (publish, edit, delete, connect accounts). - one of: member, billing_admin, viewer
- **readOnly** `boolean`: Deprecated. Use role 'viewer' instead. When true, the invite is created with role 'viewer'. Cannot be combined with role 'billing_admin'.

### Responses

#### 201: Invite token created

**Response Body:**

- **token** `string`: No description
- **scope** `string`: No description
- **invitedProfileIds** `array[string]`: 
- **expiresAt** `string` (date-time): No description
- **inviteUrl** `string` (uri): No description

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: One or more profiles not found or not owned

---

---

# Resolve LinkedIn mention API Reference

Converts a LinkedIn profile or company URL to a URN for @mentions in posts.

How to use LinkedIn @mentions (2-step workflow):

1. Call this endpoint with the LinkedIn profile/company URL to get the mention URN and format.
2. Embed the returned mentionFormat (e.g. @[Vincent Jong](urn:li:person:xxx)) directly in your post's content field.

Example:
- Resolve: GET /v1/accounts/{id}/linkedin-mentions?url=linkedin.com/in/vincentjong&displayName=Vincent Jong
- Returns: mentionFormat: "@[Vincent Jong](urn:li:person:xxx)"
- Use in post content: "Great talk with @[Vincent Jong](urn:li:person:xxx) today!"

Important: The mentions array field in POST /v1/posts is stored for reference only and does NOT trigger @mentions on LinkedIn. You must embed the mention format directly in the content text.

Requirements:
- Person mentions require the LinkedIn account to be admin of at least one organization. This is a LinkedIn API limitation: the only endpoints that resolve profile URLs to member URNs (vanityUrl, peopleTypeahead) are scoped to organization followers. There is no public LinkedIn API to resolve a vanity URL without organization context.
- Organization mentions (e.g. @Microsoft) work without this requirement.
- For person mentions to be clickable, the displayName parameter must exactly match the name shown on their LinkedIn profile.
- Person mentions DO work when published from personal profiles (the URN just needs to be valid). The limitation is only in the resolution step (URL to URN), not in publishing.


## GET /v1/accounts/{accountId}/linkedin-mentions

**Resolve LinkedIn mention**

Converts a LinkedIn profile or company URL to a URN for @mentions in posts.

How to use LinkedIn @mentions (2-step workflow):

1. Call this endpoint with the LinkedIn profile/company URL to get the mention URN and format.
2. Embed the returned mentionFormat (e.g. @[Vincent Jong](urn:li:person:xxx)) directly in your post's content field.

Example:
- Resolve: GET /v1/accounts/{id}/linkedin-mentions?url=linkedin.com/in/vincentjong&displayName=Vincent Jong
- Returns: mentionFormat: "@[Vincent Jong](urn:li:person:xxx)"
- Use in post content: "Great talk with @[Vincent Jong](urn:li:person:xxx) today!"

Important: The mentions array field in POST /v1/posts is stored for reference only and does NOT trigger @mentions on LinkedIn. You must embed the mention format directly in the content text.

Requirements:
- Person mentions require the LinkedIn account to be admin of at least one organization. This is a LinkedIn API limitation: the only endpoints that resolve profile URLs to member URNs (vanityUrl, peopleTypeahead) are scoped to organization followers. There is no public LinkedIn API to resolve a vanity URL without organization context.
- Organization mentions (e.g. @Microsoft) work without this requirement.
- For person mentions to be clickable, the displayName parameter must exactly match the name shown on their LinkedIn profile.
- Person mentions DO work when published from personal profiles (the URN just needs to be valid). The limitation is only in the resolution step (URL to URN), not in publishing.


### Parameters

- **accountId** (required) in path: The LinkedIn account ID
- **url** (required) in query: LinkedIn profile URL, company URL, or vanity name.
- **displayName** (optional) in query: Exact display name as shown on LinkedIn. Required for person mentions to be clickable. Optional for org mentions.

### Responses

#### 200: URN resolved successfully

**Response Body:**

- **urn** `string`: The LinkedIn URN (person or organization) (example: "urn:li:person:4qj5ox-agD")
- **type** `string`: The type of entity (person or organization) - one of: person, organization (example: "person")
- **displayName** `string`: Display name (provided, from API, or derived from vanity URL) (example: "Miquel Palet")
- **mentionFormat** `string`: Ready-to-use mention format for post content (example: "@[Miquel Palet](urn:li:person:4qj5ox-agD)")
- **vanityName** `string`: The vanity name/slug (only for organization mentions) (example: "microsoft")
- **warning** `string`: Warning about clickable mentions (only present for person mentions if displayName was not provided) (example: "For clickable person mentions, provide the displayName parameter with the exact name as shown on their LinkedIn profile.")

#### 400: Invalid request or no organization found (for person mentions)

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Person or organization not found

**Response Body:**

- **error** `string`: No description

---

---

# List activity logs API Reference

Unified logs endpoint. Returns logs for publishing, connections, webhooks, and messaging.
Filter by type, platform, status, and time range. Logs are retained for 90 days.


## GET /v1/logs

**List activity logs**

Unified logs endpoint. Returns logs for publishing, connections, webhooks, and messaging.
Filter by type, platform, status, and time range. Logs are retained for 90 days.


### Parameters

- **type** (optional) in query: Log category to query
- **status** (optional) in query: Filter by status
- **platform** (optional) in query: Filter by platform
- **action** (optional) in query: Filter by action (e.g., post.published, message.sent, account.connected, webhook.delivered)
- **search** (optional) in query: Free-text search across log fields
- **days** (optional) in query: Number of days to look back (max 90)
- **limit** (optional) in query: Maximum number of logs to return (max 100)
- **skip** (optional) in query: Number of logs to skip (for pagination)

### Responses

#### 200: Logs retrieved successfully

**Response Body:**

- **logs** `array[object]`: 
  - **type** `string`: Log category (publishing, connections, webhooks, messaging)
  - **action** `string`: Specific action (post.published, message.sent, account.connected, etc.)
  - **user_id** `string`: No description
  - **platform** `string`: No description
  - **account_id** `string`: No description
  - **status** `string`: No description - one of: success, failed, pending, skipped
  - **status_code** `integer`: No description
  - **error_message** `string`: No description
  - **error_code** `string`: No description
  - **duration_ms** `integer`: No description
  - **endpoint** `string`: The API endpoint that triggered this log
  - **request_body** `string`: Request JSON (truncated to 5KB)
  - **response_body** `string`: Response JSON (truncated to 10KB)
  - **created_at** `string` (date-time): No description
  - **metadata** `string`: Additional context as JSON string
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **pages** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Get upload URL API Reference

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.

## POST /v1/media/presign

**Get upload URL**

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.

### Request Body

- **filename** (required) `string`: Name of the file to upload
- **contentType** (required) `string`: MIME type of the file - one of: 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
- **size** `integer`: Optional file size in bytes for pre-validation (max 5GB)

### Responses

#### 200: Presigned URL generated successfully

**Response Body:**

- **uploadUrl** `string` (uri): Presigned URL to PUT your file to (expires in 1 hour)
- **publicUrl** `string` (uri): Public URL where the file will be accessible after upload
- **key** `string`: Storage key/path of the file
- **expiresIn** `integer`: Seconds until the presigned uploadUrl expires (always 3600)

#### 400: Invalid request (missing filename, contentType, or unsupported content type)

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Add reaction API Reference

Add an emoji reaction to a message. Platform support:
- Telegram: Supports a subset of Unicode emoji reactions
- WhatsApp: Supports any standard emoji (one reaction per message per sender)
- All others: Returns 400 (not supported)


## POST /v1/inbox/conversations/{conversationId}/messages/{messageId}/reactions

**Add reaction**

Add an emoji reaction to a message. Platform support:
- Telegram: Supports a subset of Unicode emoji reactions
- WhatsApp: Supports any standard emoji (one reaction per message per sender)
- All others: Returns 400 (not supported)


### Parameters

- **conversationId** (required) in path: The conversation ID
- **messageId** (required) in path: The platform message ID to react to

### Request Body

- **accountId** (required) `string`: Social account ID
- **emoji** (required) `string`: Emoji character (e.g. "👍", "❤️")

### Responses

#### 200: Reaction added

**Response Body:**

- **success** `boolean`: No description

#### 400: Platform does not support reactions or invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Account or conversation not found

---

## DELETE /v1/inbox/conversations/{conversationId}/messages/{messageId}/reactions

**Remove reaction**

Remove a reaction from a message. Platform support:
- Telegram: Send empty reaction array to clear
- WhatsApp: Send empty emoji to remove
- All others: Returns 400 (not supported)


### Parameters

- **conversationId** (required) in path: The conversation ID
- **messageId** (required) in path: The platform message ID
- **accountId** (required) in query: Social account ID

### Responses

#### 200: Reaction removed

**Response Body:**

- **success** `boolean`: No description

#### 400: Platform does not support reactions or invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Account or conversation not found

---

---

# Create conversation (send a WhatsApp template) API Reference

Initiate a new direct message conversation with a specified user. If a conversation already exists with the recipient, the message is added to the existing thread.

Supported platforms: X/Twitter, Bluesky, Reddit, and WhatsApp. Other platforms return PLATFORM_NOT_SUPPORTED.

WhatsApp: this is the endpoint for sending an approved template message to a phone number. Provide templateName, templateLanguage, and templateParams (body variable values), with the recipient phone in participantId. A template is required because WhatsApp does not permit freeform messages to open a conversation; a missing template returns TEMPLATE_REQUIRED. Templates with media headers (image, video, document) are handled automatically: Zernio reads the approved template definition and fills the header at send time. Calling this for a number you already have a thread with simply sends the template into that thread, which also 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). Template fields are accepted on the JSON body only, not on multipart requests.

DM eligibility (X/Twitter): Before 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. You can skip this check with skipDmCheck: true if you have already verified eligibility.

X API tier requirement: DM 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.

Rate limits: 200 requests per 15 minutes, 1,000 per 24 hours per user, 15,000 per 24 hours per app (shared across all DM endpoints).


## GET /v1/inbox/conversations

**List conversations**

Fetch conversations (DMs) from all connected messaging accounts in a single API call. Supports filtering by profile and platform. Results are aggregated and deduplicated.
Supported platforms: Facebook, Instagram, Twitter/X, Bluesky, Reddit, Telegram.

Twitter/X limitation: X 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). This means some Twitter/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.


### Parameters

- **profileId** (optional) in query: Filter by profile ID
- **platform** (optional) in query: Filter by platform
- **status** (optional) in query: Filter by conversation status
- **sortOrder** (optional) in query: Sort order by updated time
- **limit** (optional) in query: Maximum number of conversations to return
- **cursor** (optional) in query: Pagination cursor for next page
- **accountId** (optional) in query: Filter by specific social account ID

### Responses

#### 200: Aggregated conversations

**Response Body:**

- **data** `array[object]`: 
  - **id** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **accountUsername** `string`: No description
  - **participantId** `string`: No description
  - **participantName** `string`: No description
  - **participantPicture** `string`: No description
  - **participantVerifiedType** `string`: X/Twitter verified badge type. Only present for Twitter/X conversations. - one of: blue, government, business, none
  - **lastMessage** `string`: No description
  - **updatedTime** `string` (date-time): No description
  - **status** `string`: No description - one of: active, archived
  - **unreadCount** `integer`: Number of unread messages
  - **url** `string`: Direct link to open the conversation on the platform (if available)
  - **instagramProfile** `object`: Instagram profile data for the participant. Only present for Instagram conversations.
    - **isFollower** `boolean`: Whether the participant follows your Instagram business account
    - **isFollowing** `boolean`: Whether your Instagram business account follows the participant
    - **followerCount** `integer`: The participant's follower count on Instagram
    - **isVerified** `boolean`: Whether the participant is a verified Instagram user
    - **fetchedAt** `string` (date-time): When this profile data was last fetched from Instagram
- **pagination** `object`: 
  - **hasMore** `boolean`: No description
  - **nextCursor** `string`: No description
- **meta** `object`: 
  - **accountsQueried** `integer`: No description
  - **accountsFailed** `integer`: No description
  - **failedAccounts** `array[object]`: 
    - **accountId** `string`: No description
    - **accountUsername** `string`: No description
    - **platform** `string`: No description
    - **error** `string`: No description
    - **code** `string`: Error code if available
    - **retryAfter** `integer`: Seconds to wait before retry (rate limits)
  - **lastUpdated** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## POST /v1/inbox/conversations

**Create conversation (send a WhatsApp template)**

Initiate a new direct message conversation with a specified user. If a conversation already exists with the recipient, the message is added to the existing thread.

Supported platforms: X/Twitter, Bluesky, Reddit, and WhatsApp. Other platforms return PLATFORM_NOT_SUPPORTED.

WhatsApp: this is the endpoint for sending an approved template message to a phone number. Provide templateName, templateLanguage, and templateParams (body variable values), with the recipient phone in participantId. A template is required because WhatsApp does not permit freeform messages to open a conversation; a missing template returns TEMPLATE_REQUIRED. Templates with media headers (image, video, document) are handled automatically: Zernio reads the approved template definition and fills the header at send time. Calling this for a number you already have a thread with simply sends the template into that thread, which also 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). Template fields are accepted on the JSON body only, not on multipart requests.

DM eligibility (X/Twitter): Before 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. You can skip this check with skipDmCheck: true if you have already verified eligibility.

X API tier requirement: DM 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.

Rate limits: 200 requests per 15 minutes, 1,000 per 24 hours per user, 15,000 per 24 hours per app (shared across all DM endpoints).


### Request Body

- **accountId** (required) `string`: The social account ID to send from
- **participantId** `string`: Recipient identifier. For X this is the numeric user ID; for WhatsApp, the recipient phone number in international format (digits, country code included). Provide either this or participantUsername.
- **participantUsername** `string`: 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** `string`: Text content of the message. At least one of message, attachment, or (for WhatsApp) templateName is required.
- **skipDmCheck** `boolean`: X/Twitter only. Skip the receives_your_dm eligibility check before sending. Use if you have already verified the recipient accepts DMs.
- **templateName** `string`: WhatsApp only. Name of the approved template to start the conversation with (required for WhatsApp).
- **templateLanguage** `string`: WhatsApp only. Template language code (e.g. en_US).
- **templateParams** `array`: WhatsApp only. Body variable values, in order. Works with positional placeholders ({{1}}, {{2}}, ...) and with named placeholders ({{name}}, {{company}} - how Meta Business Manager creates templates), where values fill the named slots in order of appearance.

### Responses

#### 201: Conversation created successfully

**Response Body:**

- **success** `boolean`: No description (example: true)
- **data** `object`: 
  - **messageId** `string`: Platform message ID (dm_event_id)
  - **conversationId** `string`: Platform conversation ID (dm_conversation_id)
  - **participantId** `string`: Twitter numeric user ID of the recipient
  - **participantName** `string`: Display name of the recipient
  - **participantUsername** `string`: Twitter username of the recipient

#### 400: Validation error or platform not supported

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description - one of: PLATFORM_NOT_SUPPORTED

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required or profile limit reached

#### 404: Account or recipient user not found

#### 422: Recipient does not accept DMs from this account

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description - one of: DM_NOT_ALLOWED

#### 429: X API rate limit exceeded

---

---

# Delete message API Reference

Delete a message from a conversation. Platform support varies:
- Telegram: Full delete (bot's own messages anytime, others if admin)
- X/Twitter: Full delete (own DM events only)
- Bluesky: Delete for self only (recipient still sees it)
- Reddit: Delete from sender's view only
- Facebook, Instagram, WhatsApp: Not supported (returns 400)


## PATCH /v1/inbox/conversations/{conversationId}/messages/{messageId}

**Edit message**

Edit the text and/or reply markup of a previously sent Telegram message.
Only supported for Telegram. Returns 400 for other platforms.


### Parameters

- **conversationId** (required) in path: The conversation ID
- **messageId** (required) in path: The Telegram message ID to edit

### Request Body

- **accountId** (required) `string`: Social account ID
- **text** `string`: New message text
- **replyMarkup** `object`: New inline keyboard markup

### Responses

#### 200: Message edited

**Response Body:**

- **success** `boolean`: No description
- **data** `object`: 
  - **messageId** `integer`: No description

#### 400: Not supported or invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## DELETE /v1/inbox/conversations/{conversationId}/messages/{messageId}

**Delete message**

Delete a message from a conversation. Platform support varies:
- Telegram: Full delete (bot's own messages anytime, others if admin)
- X/Twitter: Full delete (own DM events only)
- Bluesky: Delete for self only (recipient still sees it)
- Reddit: Delete from sender's view only
- Facebook, Instagram, WhatsApp: Not supported (returns 400)


### Parameters

- **conversationId** (required) in path: The conversation ID
- **messageId** (required) in path: The platform message ID to delete
- **accountId** (required) in query: Social account ID

### Responses

#### 200: Message deleted

**Response Body:**

- **success** `boolean`: No description

#### 400: Platform does not support deletion or invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Account or conversation not found

---

---

# Edit message API Reference

Edit the text and/or reply markup of a previously sent Telegram message.
Only supported for Telegram. Returns 400 for other platforms.


## PATCH /v1/inbox/conversations/{conversationId}/messages/{messageId}

**Edit message**

Edit the text and/or reply markup of a previously sent Telegram message.
Only supported for Telegram. Returns 400 for other platforms.


### Parameters

- **conversationId** (required) in path: The conversation ID
- **messageId** (required) in path: The Telegram message ID to edit

### Request Body

- **accountId** (required) `string`: Social account ID
- **text** `string`: New message text
- **replyMarkup** `object`: New inline keyboard markup

### Responses

#### 200: Message edited

**Response Body:**

- **success** `boolean`: No description
- **data** `object`: 
  - **messageId** `integer`: No description

#### 400: Not supported or invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## DELETE /v1/inbox/conversations/{conversationId}/messages/{messageId}

**Delete message**

Delete a message from a conversation. Platform support varies:
- Telegram: Full delete (bot's own messages anytime, others if admin)
- X/Twitter: Full delete (own DM events only)
- Bluesky: Delete for self only (recipient still sees it)
- Reddit: Delete from sender's view only
- Facebook, Instagram, WhatsApp: Not supported (returns 400)


### Parameters

- **conversationId** (required) in path: The conversation ID
- **messageId** (required) in path: The platform message ID to delete
- **accountId** (required) in query: Social account ID

### Responses

#### 200: Message deleted

**Response Body:**

- **success** `boolean`: No description

#### 400: Platform does not support deletion or invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Account or conversation not found

---

---

# List messages API Reference

Fetch messages for a specific conversation, with cursor-based pagination
and ordering control.

Pagination: pass `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.

Sort order: defaults to `asc` (oldest first, chat style). For the
"show me the latest messages" pattern, pass `?sortOrder=desc&limit=N`.
Twitter, Instagram, Telegram, WhatsApp and Reddit honor the requested
order from the local message store. For Facebook and Bluesky, the
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). The response field `sortOrderApplied`
tells you what was actually applied.

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.

Twitter/X limitation: 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.

This 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`.


## GET /v1/inbox/conversations/{conversationId}/messages

**List messages**

Fetch messages for a specific conversation, with cursor-based pagination
and ordering control.

Pagination: pass `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.

Sort order: defaults to `asc` (oldest first, chat style). For the
"show me the latest messages" pattern, pass `?sortOrder=desc&limit=N`.
Twitter, Instagram, Telegram, WhatsApp and Reddit honor the requested
order from the local message store. For Facebook and Bluesky, the
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). The response field `sortOrderApplied`
tells you what was actually applied.

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.

Twitter/X limitation: 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.

This 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`.


### Parameters

- **conversationId** (required) in path: The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.
- **accountId** (required) in query: Social account ID
- **limit** (optional) in query: Number of messages to return per page. Default 100, max 100.
- **cursor** (optional) in query: Opaque pagination cursor. Pass `pagination.nextCursor` from a prior response.
- **sortOrder** (optional) in query: Order of returned messages. Default `asc` (oldest first, chat style).
Twitter, Instagram, Telegram, WhatsApp and Reddit honor this order
across cursor pages. For Facebook and Bluesky, only intra-page
ordering is affected — pages always walk newest→oldest. See
`sortOrderApplied` in the response.


### Responses

#### 200: Messages in conversation

**Response Body:**

- **status** `string`: No description
- **pagination** `object`: 
  - **hasMore** `boolean`: Whether more messages are available beyond this page.
  - **nextCursor** `string`: Opaque cursor to fetch the next page. `null` on the last page.
- **sortOrderApplied** `string`: Sort order actually applied to the returned page. May
differ from the requested `sortOrder` for Facebook and
Bluesky (always `desc` regardless of request).
 - one of: asc, desc
- **messages** `array[object]`: 
  - **id** `string`: No description
  - **conversationId** `string`: No description
  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **message** `string`: No description
  - **senderId** `string`: No description
  - **senderName** `string`: No description
  - **senderVerifiedType** `string`: X/Twitter verified badge type. Only present for Twitter/X messages. - one of: blue, government, business, none
  - **direction** `string`: No description - one of: incoming, outgoing
  - **createdAt** `string` (date-time): No description
  - **attachments** `array[object]`: 
    - **id** `string`: No description
    - **type** `string`: No description - one of: image, video, audio, file, sticker, share
    - **url** `string`: No description
    - **filename** `string`: No description
    - **previewUrl** `string`: No description
  - **subject** `string`: Reddit message subject
  - **storyReply** `boolean`: Instagram story reply
  - **isStoryMention** `boolean`: Instagram story mention
  - **isEdited** `boolean`: True if the sender has edited this message at least once.
  - **editedAt** `string` (date-time): When the most recent edit happened.
  - **editCount** `integer`: Total number of edits applied.
  - **editHistory** `array[object]`: Every prior version of the message, oldest first.
    - **text** `string`: No description
    - **attachments** `array[object]`: 
      - **type** `string`: No description
      - **url** `string`: No description
      - **payload** `object`: No description
    - **editedAt** `string` (date-time): No description
  - **isDeleted** `boolean`: True if the sender has deleted (unsent) this message. The original message and attachments fields remain populated.
  - **deletedAt** `string` (date-time): No description
  - **deliveryStatus** `string`: Lifecycle status for outgoing messages. Not all platforms emit every state (see webhook support matrix). - one of: sent, delivered, read, failed, deleted
  - **deliveredAt** `string` (date-time): No description
  - **readAt** `string` (date-time): No description
  - **sentAt** `string` (date-time): Original send time for outgoing messages (used for Messenger watermark queries).
  - **deliveryError** `object`: Populated when deliveryStatus === "failed".
    - **code** `integer`: No description
    - **title** `string`: No description
    - **message** `string`: No description
  - **reactions** `array[object]`: Emoji reactions on this message (WhatsApp / Telegram). At most one per party in a 1:1 thread.
    - **emoji** `string`: No description
    - **fromMe** `boolean`: true if the connected account reacted
    - **reactedAt** `string` (date-time): No description
  - **metadata** `object`: Platform-specific extras. Free-form, but commonly includes:
`quotedMessageId` (platformMessageId this message replies to),
`waInteractive` (a compact descriptor of WhatsApp interactive
content sent: buttons / list / cta_url / flow / location_request),
and for inbound interactive taps `interactiveType` / `interactiveId`.

- **lastUpdated** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## POST /v1/inbox/conversations/{conversationId}/messages

**Send message**

Send a message in a conversation. Supports text, attachments, quick replies,
buttons, templates, and message tags. Attachment and interactive message
support varies by platform.

WhatsApp template messages: to 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. To send a template
to a phone number you have no conversation with yet, use the
create-conversation endpoint (POST /v1/inbox/conversations) instead.

WhatsApp rich 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`).


### Parameters

- **conversationId** (required) in path: The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.

### Request Body

- **accountId** (required) `string`: Social account ID
- **message** `string`: Message text
- **attachmentUrl** `string`: URL of the attachment to send (image, video, audio, or file). The URL must be publicly accessible. For binary file uploads, use multipart/form-data instead.
- **attachmentType** `string`: Type of attachment. Defaults to file if not specified. - one of: image, video, audio, file
- **voiceNote** `boolean`: 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. The audio file MUST be `.ogg`
encoded with the OPUS codec (mono) per Meta's voice-message contract;
other formats are rejected by WhatsApp. Ignored for non-audio attachments.

- **quickReplies** `array`: Quick reply buttons. Mutually exclusive with buttons. Max 13 items.
- **buttons** `array`: Action buttons. Mutually exclusive with quickReplies. Max 3 items.
- **template** `object`: Platform-dependent template payload. Ignored on Telegram.

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`.

WhatsApp: sends an approved WhatsApp template message, the only message
type WhatsApp accepts when the 24-hour customer-service window is closed.
Provide exactly one element carrying the template reference:
`{ "elements": [{ "name": "order_update", "language": "en_US", "components": [...] }] }`
(`type` is ignored on WhatsApp). `components` is optional and is 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" }] }]`.
Templates with media headers (image, video, document) must include the
header component with its media link here at send time. To send a template
to a phone number with no existing conversation, or to have media headers
filled in automatically from the template definition, use the
create-conversation endpoint (POST /v1/inbox/conversations) instead.

- **interactive** `object`: WhatsApp-only. Rich interactive payload for list messages, CTA URL
buttons, Flow prompts, and location requests. When set, takes
priority over `buttons` and `quickReplies`. The shape mirrors
Meta's Cloud API `interactive` object verbatim, so any payload
that works against Meta directly will also work here.

Use `buttons` / `quickReplies` for simple button replies
(WhatsApp's `interactive.type: "button"`) — the abstraction caps at
3 buttons and handles the auto-conversion for you. Use this field
only for `list`, `cta_url`, `flow`, `location_request_message`, or
`voice_call` messages.

For `voice_call`, the message renders WhatsApp's native call
button; tapping it starts a voice call to your business number.
Requires WhatsApp Business Calling to be enabled on the sending
number. The optional `parameters.payload` string is echoed back on
the `calls` webhook (as `cta_payload`) for attribution.

For `location_request_message`, `action` may be omitted (we default
it to `{ "name": "send_location" }`). WhatsApp renders a localized
"Send location" button; the user's reply arrives as a regular
location message in the conversation.

Tap events come back via the `message.received` webhook with
`metadata.interactiveType` set to `list_reply` or `nfm_reply`.

- **replyMarkup** `object`: Telegram-native keyboard markup. Ignored on other platforms.
- **messagingType** `string`: Facebook messaging type. Required when using messageTag. - one of: RESPONSE, UPDATE, MESSAGE_TAG
- **messageTag** `string`: Facebook message tag for messaging outside 24h window. Requires messagingType MESSAGE_TAG. Instagram only supports HUMAN_AGENT. - one of: CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE, HUMAN_AGENT
- **replyTo** `string`: Platform message ID to quote-reply to. For WhatsApp, pass the wamid (available in message.platformMessageId from webhooks). For Telegram, pass the Telegram message ID.
- **location** `object`: WhatsApp-only. Send a location pin.
- **contacts** `array`: WhatsApp-only. Send one or more contact cards.

### Responses

#### 200: Message sent

**Response Body:**

- **success** `boolean`: No description
- **data** `object`: 
  - **messageId** `string`: ID of the sent message (not returned for Reddit)
  - **conversationId** `string`: Twitter conversation ID
  - **sentAt** `string` (date-time): Bluesky sent timestamp
  - **message** `string`: Success message (Reddit only)

#### 400: Bad request (e.g., attachment not supported for platform, validation error)

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description - one of: PLATFORM_LIMITATION

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# Get conversation API Reference

Retrieve details and metadata for a specific conversation. Requires accountId query parameter.

## GET /v1/inbox/conversations/{conversationId}

**Get conversation**

Retrieve details and metadata for a specific conversation. Requires accountId query parameter.

### Parameters

- **conversationId** (required) in path: The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.
- **accountId** (required) in query: The social account ID

### Responses

#### 200: Conversation details

**Response Body:**

- **data** `object`: 
  - **id** `string`: No description
  - **accountId** `string`: No description
  - **accountUsername** `string`: No description
  - **platform** `string`: No description
  - **status** `string`: No description - one of: active, archived
  - **participantName** `string`: No description
  - **participantId** `string`: No description
  - **participantVerifiedType** `string`: X/Twitter verified badge type. Only present for Twitter/X conversations. - one of: blue, government, business, none
  - **lastMessage** `string`: No description
  - **lastMessageAt** `string` (date-time): No description
  - **updatedTime** `string` (date-time): No description
  - **participants** `array[object]`: 
    - **id** `string`: No description
    - **name** `string`: No description
  - **instagramProfile** `object`: Instagram profile data for the participant. Only present for Instagram conversations.
    - **isFollower** `boolean`: Whether the participant follows your Instagram business account
    - **isFollowing** `boolean`: Whether your Instagram business account follows the participant
    - **followerCount** `integer`: The participant's follower count on Instagram
    - **isVerified** `boolean`: Whether the participant is a verified Instagram user
    - **fetchedAt** `string` (date-time): When this profile data was last fetched from Instagram

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Conversation not found

---

## PUT /v1/inbox/conversations/{conversationId}

**Update conversation status**

Archive or activate a conversation. Requires accountId in request body.

### Parameters

- **conversationId** (required) in path: The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.

### Request Body

- **accountId** (required) `string`: Social account ID
- **status** (required) `string`: No description - one of: active, archived

### Responses

#### 200: Conversation updated

**Response Body:**

- **success** `boolean`: No description
- **data** `object`: 
  - **id** `string`: No description
  - **accountId** `string`: No description
  - **status** `string`: No description - one of: active, archived
  - **platform** `string`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Conversation not found (WhatsApp only; other platforms upsert)

---

---

# List conversations API Reference

Fetch conversations (DMs) from all connected messaging accounts in a single API call. Supports filtering by profile and platform. Results are aggregated and deduplicated.
Supported platforms: Facebook, Instagram, Twitter/X, Bluesky, Reddit, Telegram.

Twitter/X limitation: X 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). This means some Twitter/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.


## GET /v1/inbox/conversations

**List conversations**

Fetch conversations (DMs) from all connected messaging accounts in a single API call. Supports filtering by profile and platform. Results are aggregated and deduplicated.
Supported platforms: Facebook, Instagram, Twitter/X, Bluesky, Reddit, Telegram.

Twitter/X limitation: X 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). This means some Twitter/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.


### Parameters

- **profileId** (optional) in query: Filter by profile ID
- **platform** (optional) in query: Filter by platform
- **status** (optional) in query: Filter by conversation status
- **sortOrder** (optional) in query: Sort order by updated time
- **limit** (optional) in query: Maximum number of conversations to return
- **cursor** (optional) in query: Pagination cursor for next page
- **accountId** (optional) in query: Filter by specific social account ID

### Responses

#### 200: Aggregated conversations

**Response Body:**

- **data** `array[object]`: 
  - **id** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **accountUsername** `string`: No description
  - **participantId** `string`: No description
  - **participantName** `string`: No description
  - **participantPicture** `string`: No description
  - **participantVerifiedType** `string`: X/Twitter verified badge type. Only present for Twitter/X conversations. - one of: blue, government, business, none
  - **lastMessage** `string`: No description
  - **updatedTime** `string` (date-time): No description
  - **status** `string`: No description - one of: active, archived
  - **unreadCount** `integer`: Number of unread messages
  - **url** `string`: Direct link to open the conversation on the platform (if available)
  - **instagramProfile** `object`: Instagram profile data for the participant. Only present for Instagram conversations.
    - **isFollower** `boolean`: Whether the participant follows your Instagram business account
    - **isFollowing** `boolean`: Whether your Instagram business account follows the participant
    - **followerCount** `integer`: The participant's follower count on Instagram
    - **isVerified** `boolean`: Whether the participant is a verified Instagram user
    - **fetchedAt** `string` (date-time): When this profile data was last fetched from Instagram
- **pagination** `object`: 
  - **hasMore** `boolean`: No description
  - **nextCursor** `string`: No description
- **meta** `object`: 
  - **accountsQueried** `integer`: No description
  - **accountsFailed** `integer`: No description
  - **failedAccounts** `array[object]`: 
    - **accountId** `string`: No description
    - **accountUsername** `string`: No description
    - **platform** `string`: No description
    - **error** `string`: No description
    - **code** `string`: Error code if available
    - **retryAfter** `integer`: Seconds to wait before retry (rate limits)
  - **lastUpdated** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## POST /v1/inbox/conversations

**Create conversation (send a WhatsApp template)**

Initiate a new direct message conversation with a specified user. If a conversation already exists with the recipient, the message is added to the existing thread.

Supported platforms: X/Twitter, Bluesky, Reddit, and WhatsApp. Other platforms return PLATFORM_NOT_SUPPORTED.

WhatsApp: this is the endpoint for sending an approved template message to a phone number. Provide templateName, templateLanguage, and templateParams (body variable values), with the recipient phone in participantId. A template is required because WhatsApp does not permit freeform messages to open a conversation; a missing template returns TEMPLATE_REQUIRED. Templates with media headers (image, video, document) are handled automatically: Zernio reads the approved template definition and fills the header at send time. Calling this for a number you already have a thread with simply sends the template into that thread, which also 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). Template fields are accepted on the JSON body only, not on multipart requests.

DM eligibility (X/Twitter): Before 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. You can skip this check with skipDmCheck: true if you have already verified eligibility.

X API tier requirement: DM 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.

Rate limits: 200 requests per 15 minutes, 1,000 per 24 hours per user, 15,000 per 24 hours per app (shared across all DM endpoints).


### Request Body

- **accountId** (required) `string`: The social account ID to send from
- **participantId** `string`: Recipient identifier. For X this is the numeric user ID; for WhatsApp, the recipient phone number in international format (digits, country code included). Provide either this or participantUsername.
- **participantUsername** `string`: 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** `string`: Text content of the message. At least one of message, attachment, or (for WhatsApp) templateName is required.
- **skipDmCheck** `boolean`: X/Twitter only. Skip the receives_your_dm eligibility check before sending. Use if you have already verified the recipient accepts DMs.
- **templateName** `string`: WhatsApp only. Name of the approved template to start the conversation with (required for WhatsApp).
- **templateLanguage** `string`: WhatsApp only. Template language code (e.g. en_US).
- **templateParams** `array`: WhatsApp only. Body variable values, in order. Works with positional placeholders ({{1}}, {{2}}, ...) and with named placeholders ({{name}}, {{company}} - how Meta Business Manager creates templates), where values fill the named slots in order of appearance.

### Responses

#### 201: Conversation created successfully

**Response Body:**

- **success** `boolean`: No description (example: true)
- **data** `object`: 
  - **messageId** `string`: Platform message ID (dm_event_id)
  - **conversationId** `string`: Platform conversation ID (dm_conversation_id)
  - **participantId** `string`: Twitter numeric user ID of the recipient
  - **participantName** `string`: Display name of the recipient
  - **participantUsername** `string`: Twitter username of the recipient

#### 400: Validation error or platform not supported

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description - one of: PLATFORM_NOT_SUPPORTED

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required or profile limit reached

#### 404: Account or recipient user not found

#### 422: Recipient does not accept DMs from this account

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description - one of: DM_NOT_ALLOWED

#### 429: X API rate limit exceeded

---

---

# Mark a conversation as read API Reference

Marks all unread incoming messages in the conversation as read.

For WhatsApp, this also sends read receipts (blue ticks) to the contact,
EXCEPT on coexistence accounts (where the WhatsApp Business app on the
customer's phone owns read state and we never override it).

This is the explicit, human-driven counterpart to `GET .../messages`,
which is side-effect-free and does NOT mark anything read. Call this when
a user actually views the conversation.


## POST /v1/inbox/conversations/{conversationId}/read

**Mark a conversation as read**

Marks all unread incoming messages in the conversation as read.

For WhatsApp, this also sends read receipts (blue ticks) to the contact,
EXCEPT on coexistence accounts (where the WhatsApp Business app on the
customer's phone owns read state and we never override it).

This is the explicit, human-driven counterpart to `GET .../messages`,
which is side-effect-free and does NOT mark anything read. Call this when
a user actually views the conversation.


### Parameters

- **conversationId** (required) in path: The conversation ID

### Request Body

- **accountId** (required) `string`: Social account ID

### Responses

#### 200: Conversation marked read

**Response Body:**

- **success** `boolean`: No description
- **markedCount** `integer`: Number of messages marked read by this call

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Account or conversation not found

---

---

# Remove reaction API Reference

Remove a reaction from a message. Platform support:
- Telegram: Send empty reaction array to clear
- WhatsApp: Send empty emoji to remove
- All others: Returns 400 (not supported)


## POST /v1/inbox/conversations/{conversationId}/messages/{messageId}/reactions

**Add reaction**

Add an emoji reaction to a message. Platform support:
- Telegram: Supports a subset of Unicode emoji reactions
- WhatsApp: Supports any standard emoji (one reaction per message per sender)
- All others: Returns 400 (not supported)


### Parameters

- **conversationId** (required) in path: The conversation ID
- **messageId** (required) in path: The platform message ID to react to

### Request Body

- **accountId** (required) `string`: Social account ID
- **emoji** (required) `string`: Emoji character (e.g. "👍", "❤️")

### Responses

#### 200: Reaction added

**Response Body:**

- **success** `boolean`: No description

#### 400: Platform does not support reactions or invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Account or conversation not found

---

## DELETE /v1/inbox/conversations/{conversationId}/messages/{messageId}/reactions

**Remove reaction**

Remove a reaction from a message. Platform support:
- Telegram: Send empty reaction array to clear
- WhatsApp: Send empty emoji to remove
- All others: Returns 400 (not supported)


### Parameters

- **conversationId** (required) in path: The conversation ID
- **messageId** (required) in path: The platform message ID
- **accountId** (required) in query: Social account ID

### Responses

#### 200: Reaction removed

**Response Body:**

- **success** `boolean`: No description

#### 400: Platform does not support reactions or invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Account or conversation not found

---

---

# Send message API Reference

Send a message in a conversation. Supports text, attachments, quick replies,
buttons, templates, and message tags. Attachment and interactive message
support varies by platform.

WhatsApp template messages: to 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. To send a template
to a phone number you have no conversation with yet, use the
create-conversation endpoint (POST /v1/inbox/conversations) instead.

WhatsApp rich 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`).


## GET /v1/inbox/conversations/{conversationId}/messages

**List messages**

Fetch messages for a specific conversation, with cursor-based pagination
and ordering control.

Pagination: pass `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.

Sort order: defaults to `asc` (oldest first, chat style). For the
"show me the latest messages" pattern, pass `?sortOrder=desc&limit=N`.
Twitter, Instagram, Telegram, WhatsApp and Reddit honor the requested
order from the local message store. For Facebook and Bluesky, the
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). The response field `sortOrderApplied`
tells you what was actually applied.

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.

Twitter/X limitation: 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.

This 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`.


### Parameters

- **conversationId** (required) in path: The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.
- **accountId** (required) in query: Social account ID
- **limit** (optional) in query: Number of messages to return per page. Default 100, max 100.
- **cursor** (optional) in query: Opaque pagination cursor. Pass `pagination.nextCursor` from a prior response.
- **sortOrder** (optional) in query: Order of returned messages. Default `asc` (oldest first, chat style).
Twitter, Instagram, Telegram, WhatsApp and Reddit honor this order
across cursor pages. For Facebook and Bluesky, only intra-page
ordering is affected — pages always walk newest→oldest. See
`sortOrderApplied` in the response.


### Responses

#### 200: Messages in conversation

**Response Body:**

- **status** `string`: No description
- **pagination** `object`: 
  - **hasMore** `boolean`: Whether more messages are available beyond this page.
  - **nextCursor** `string`: Opaque cursor to fetch the next page. `null` on the last page.
- **sortOrderApplied** `string`: Sort order actually applied to the returned page. May
differ from the requested `sortOrder` for Facebook and
Bluesky (always `desc` regardless of request).
 - one of: asc, desc
- **messages** `array[object]`: 
  - **id** `string`: No description
  - **conversationId** `string`: No description
  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **message** `string`: No description
  - **senderId** `string`: No description
  - **senderName** `string`: No description
  - **senderVerifiedType** `string`: X/Twitter verified badge type. Only present for Twitter/X messages. - one of: blue, government, business, none
  - **direction** `string`: No description - one of: incoming, outgoing
  - **createdAt** `string` (date-time): No description
  - **attachments** `array[object]`: 
    - **id** `string`: No description
    - **type** `string`: No description - one of: image, video, audio, file, sticker, share
    - **url** `string`: No description
    - **filename** `string`: No description
    - **previewUrl** `string`: No description
  - **subject** `string`: Reddit message subject
  - **storyReply** `boolean`: Instagram story reply
  - **isStoryMention** `boolean`: Instagram story mention
  - **isEdited** `boolean`: True if the sender has edited this message at least once.
  - **editedAt** `string` (date-time): When the most recent edit happened.
  - **editCount** `integer`: Total number of edits applied.
  - **editHistory** `array[object]`: Every prior version of the message, oldest first.
    - **text** `string`: No description
    - **attachments** `array[object]`: 
      - **type** `string`: No description
      - **url** `string`: No description
      - **payload** `object`: No description
    - **editedAt** `string` (date-time): No description
  - **isDeleted** `boolean`: True if the sender has deleted (unsent) this message. The original message and attachments fields remain populated.
  - **deletedAt** `string` (date-time): No description
  - **deliveryStatus** `string`: Lifecycle status for outgoing messages. Not all platforms emit every state (see webhook support matrix). - one of: sent, delivered, read, failed, deleted
  - **deliveredAt** `string` (date-time): No description
  - **readAt** `string` (date-time): No description
  - **sentAt** `string` (date-time): Original send time for outgoing messages (used for Messenger watermark queries).
  - **deliveryError** `object`: Populated when deliveryStatus === "failed".
    - **code** `integer`: No description
    - **title** `string`: No description
    - **message** `string`: No description
  - **reactions** `array[object]`: Emoji reactions on this message (WhatsApp / Telegram). At most one per party in a 1:1 thread.
    - **emoji** `string`: No description
    - **fromMe** `boolean`: true if the connected account reacted
    - **reactedAt** `string` (date-time): No description
  - **metadata** `object`: Platform-specific extras. Free-form, but commonly includes:
`quotedMessageId` (platformMessageId this message replies to),
`waInteractive` (a compact descriptor of WhatsApp interactive
content sent: buttons / list / cta_url / flow / location_request),
and for inbound interactive taps `interactiveType` / `interactiveId`.

- **lastUpdated** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## POST /v1/inbox/conversations/{conversationId}/messages

**Send message**

Send a message in a conversation. Supports text, attachments, quick replies,
buttons, templates, and message tags. Attachment and interactive message
support varies by platform.

WhatsApp template messages: to 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. To send a template
to a phone number you have no conversation with yet, use the
create-conversation endpoint (POST /v1/inbox/conversations) instead.

WhatsApp rich 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`).


### Parameters

- **conversationId** (required) in path: The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.

### Request Body

- **accountId** (required) `string`: Social account ID
- **message** `string`: Message text
- **attachmentUrl** `string`: URL of the attachment to send (image, video, audio, or file). The URL must be publicly accessible. For binary file uploads, use multipart/form-data instead.
- **attachmentType** `string`: Type of attachment. Defaults to file if not specified. - one of: image, video, audio, file
- **voiceNote** `boolean`: 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. The audio file MUST be `.ogg`
encoded with the OPUS codec (mono) per Meta's voice-message contract;
other formats are rejected by WhatsApp. Ignored for non-audio attachments.

- **quickReplies** `array`: Quick reply buttons. Mutually exclusive with buttons. Max 13 items.
- **buttons** `array`: Action buttons. Mutually exclusive with quickReplies. Max 3 items.
- **template** `object`: Platform-dependent template payload. Ignored on Telegram.

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`.

WhatsApp: sends an approved WhatsApp template message, the only message
type WhatsApp accepts when the 24-hour customer-service window is closed.
Provide exactly one element carrying the template reference:
`{ "elements": [{ "name": "order_update", "language": "en_US", "components": [...] }] }`
(`type` is ignored on WhatsApp). `components` is optional and is 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" }] }]`.
Templates with media headers (image, video, document) must include the
header component with its media link here at send time. To send a template
to a phone number with no existing conversation, or to have media headers
filled in automatically from the template definition, use the
create-conversation endpoint (POST /v1/inbox/conversations) instead.

- **interactive** `object`: WhatsApp-only. Rich interactive payload for list messages, CTA URL
buttons, Flow prompts, and location requests. When set, takes
priority over `buttons` and `quickReplies`. The shape mirrors
Meta's Cloud API `interactive` object verbatim, so any payload
that works against Meta directly will also work here.

Use `buttons` / `quickReplies` for simple button replies
(WhatsApp's `interactive.type: "button"`) — the abstraction caps at
3 buttons and handles the auto-conversion for you. Use this field
only for `list`, `cta_url`, `flow`, `location_request_message`, or
`voice_call` messages.

For `voice_call`, the message renders WhatsApp's native call
button; tapping it starts a voice call to your business number.
Requires WhatsApp Business Calling to be enabled on the sending
number. The optional `parameters.payload` string is echoed back on
the `calls` webhook (as `cta_payload`) for attribution.

For `location_request_message`, `action` may be omitted (we default
it to `{ "name": "send_location" }`). WhatsApp renders a localized
"Send location" button; the user's reply arrives as a regular
location message in the conversation.

Tap events come back via the `message.received` webhook with
`metadata.interactiveType` set to `list_reply` or `nfm_reply`.

- **replyMarkup** `object`: Telegram-native keyboard markup. Ignored on other platforms.
- **messagingType** `string`: Facebook messaging type. Required when using messageTag. - one of: RESPONSE, UPDATE, MESSAGE_TAG
- **messageTag** `string`: Facebook message tag for messaging outside 24h window. Requires messagingType MESSAGE_TAG. Instagram only supports HUMAN_AGENT. - one of: CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE, HUMAN_AGENT
- **replyTo** `string`: Platform message ID to quote-reply to. For WhatsApp, pass the wamid (available in message.platformMessageId from webhooks). For Telegram, pass the Telegram message ID.
- **location** `object`: WhatsApp-only. Send a location pin.
- **contacts** `array`: WhatsApp-only. Send one or more contact cards.

### Responses

#### 200: Message sent

**Response Body:**

- **success** `boolean`: No description
- **data** `object`: 
  - **messageId** `string`: ID of the sent message (not returned for Reddit)
  - **conversationId** `string`: Twitter conversation ID
  - **sentAt** `string` (date-time): Bluesky sent timestamp
  - **message** `string`: Success message (Reddit only)

#### 400: Bad request (e.g., attachment not supported for platform, validation error)

**Response Body:**

- **error** `string`: No description
- **code** `string`: No description - one of: PLATFORM_LIMITATION

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# Send typing indicator API Reference

Show a typing indicator in a conversation. Platform support:
- Facebook Messenger: Shows "Page is typing..." for 20 seconds
- Telegram: Shows "Bot is typing..." for 5 seconds
- 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.
- All others: Returns 200 but no-op (platform doesn't support it)

Typing indicators are best-effort. The endpoint always returns 200 even if the platform call fails.


## POST /v1/inbox/conversations/{conversationId}/typing

**Send typing indicator**

Show a typing indicator in a conversation. Platform support:
- Facebook Messenger: Shows "Page is typing..." for 20 seconds
- Telegram: Shows "Bot is typing..." for 5 seconds
- 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.
- All others: Returns 200 but no-op (platform doesn't support it)

Typing indicators are best-effort. The endpoint always returns 200 even if the platform call fails.


### Parameters

- **conversationId** (required) in path: The conversation ID

### Request Body

- **accountId** (required) `string`: Social account ID

### Responses

#### 200: Typing indicator sent (or no-op on unsupported platforms)

**Response Body:**

- **success** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Account or conversation not found

---

---

# Update conversation status API Reference

Archive or activate a conversation. Requires accountId in request body.

## GET /v1/inbox/conversations/{conversationId}

**Get conversation**

Retrieve details and metadata for a specific conversation. Requires accountId query parameter.

### Parameters

- **conversationId** (required) in path: The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.
- **accountId** (required) in query: The social account ID

### Responses

#### 200: Conversation details

**Response Body:**

- **data** `object`: 
  - **id** `string`: No description
  - **accountId** `string`: No description
  - **accountUsername** `string`: No description
  - **platform** `string`: No description
  - **status** `string`: No description - one of: active, archived
  - **participantName** `string`: No description
  - **participantId** `string`: No description
  - **participantVerifiedType** `string`: X/Twitter verified badge type. Only present for Twitter/X conversations. - one of: blue, government, business, none
  - **lastMessage** `string`: No description
  - **lastMessageAt** `string` (date-time): No description
  - **updatedTime** `string` (date-time): No description
  - **participants** `array[object]`: 
    - **id** `string`: No description
    - **name** `string`: No description
  - **instagramProfile** `object`: Instagram profile data for the participant. Only present for Instagram conversations.
    - **isFollower** `boolean`: Whether the participant follows your Instagram business account
    - **isFollowing** `boolean`: Whether your Instagram business account follows the participant
    - **followerCount** `integer`: The participant's follower count on Instagram
    - **isVerified** `boolean`: Whether the participant is a verified Instagram user
    - **fetchedAt** `string` (date-time): When this profile data was last fetched from Instagram

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Conversation not found

---

## PUT /v1/inbox/conversations/{conversationId}

**Update conversation status**

Archive or activate a conversation. Requires accountId in request body.

### Parameters

- **conversationId** (required) in path: The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.

### Request Body

- **accountId** (required) `string`: Social account ID
- **status** (required) `string`: No description - one of: active, archived

### Responses

#### 200: Conversation updated

**Response Body:**

- **success** `boolean`: No description
- **data** `object`: 
  - **id** `string`: No description
  - **accountId** `string`: No description
  - **status** `string`: No description - one of: active, archived
  - **platform** `string`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

#### 404: Conversation not found (WhatsApp only; other platforms upsert)

---

---

# Upload media file API Reference

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.

Files are stored in temporary storage and auto-delete after 7 days.
Maximum file size is 25MB.

Unlike /v1/media/upload (which uses upload tokens for end-user flows),
this endpoint uses standard Bearer token authentication for programmatic use.


## POST /v1/media/upload-direct

**Upload media file**

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.

Files are stored in temporary storage and auto-delete after 7 days.
Maximum file size is 25MB.

Unlike /v1/media/upload (which uses upload tokens for end-user flows),
this endpoint uses standard Bearer token authentication for programmatic use.


### Request Body


### Responses

#### 200: File uploaded successfully

**Response Body:**

- **url** `string`: Publicly accessible URL for the uploaded file
- **filename** `string`: Generated unique filename
- **contentType** `string`: MIME type of the file
- **size** `integer`: File size in bytes

#### 400: No file provided or file too large

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Bulk upload from CSV API Reference

Create multiple posts by uploading a CSV file. Use dryRun=true to validate without creating posts.

## POST /v1/posts/bulk-upload

**Bulk upload from CSV**

Create multiple posts by uploading a CSV file. Use dryRun=true to validate without creating posts.

### Parameters

- **dryRun** (optional) in query: No description

### Request Body


### Responses

#### 200: Bulk upload results. Returned when every row succeeded (or every row failed).
A mix of successes and failures returns `207` instead, with the same body shape.


**Response Body:**

- **total** `integer`: Number of data rows processed from the CSV
- **valid** `integer`: Count of rows that succeeded (results[].ok === true)
- **invalid** `integer`: Count of rows that failed (total - valid)
- **results** `array[object]`: One entry per CSV data row, in row order.
  - **rowIndex** `integer`: 1-based index of the CSV data row (header excluded)
  - **ok** `boolean`: Whether the row was created successfully
  - **createdPostId** `string`: ID of the created post. Present only when `ok` is true and not a dry run.
  - **errors** `array[string]`: Machine-readable failure codes for this row. Present only when `ok` is false.
Examples: `unknown_profile:<id>`, `no_account_for_platform:<platform>`,
`schedule_time_missing`, `rate_limited:<platform>:@<username>:<remaining>`.

- **warnings** `array[string]`: Top-level advisory warnings (e.g. `rows_exceed_advisory_limit:500`). Empty when none.
- **rateLimitedAccounts** `array[object]`: Present only when one or more rows targeted an account currently in cooldown.
Lets callers map `rate_limited:*` row errors back to structured metadata without
parsing the error strings.

  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **username** `string`: No description
  - **rateLimitedUntil** `string` (date-time): No description

#### 207: Partial success: some rows were created and some failed. Body is identical in
shape to the `200` response. Inspect each entry in `results` (`ok` plus `errors`)
to see which rows failed and why.


**Response Body:**

- **total** `integer`: Number of data rows processed from the CSV
- **valid** `integer`: Count of rows that succeeded (results[].ok === true)
- **invalid** `integer`: Count of rows that failed (total - valid)
- **results** `array[object]`: One entry per CSV data row, in row order.
  - **rowIndex** `integer`: 1-based index of the CSV data row (header excluded)
  - **ok** `boolean`: Whether the row was created successfully
  - **createdPostId** `string`: ID of the created post. Present only when `ok` is true and not a dry run.
  - **errors** `array[string]`: Machine-readable failure codes for this row. Present only when `ok` is false.
Examples: `unknown_profile:<id>`, `no_account_for_platform:<platform>`,
`schedule_time_missing`, `rate_limited:<platform>:@<username>:<remaining>`.

- **warnings** `array[string]`: Top-level advisory warnings (e.g. `rows_exceed_advisory_limit:500`). Empty when none.
- **rateLimitedAccounts** `array[object]`: Present only when one or more rows targeted an account currently in cooldown.
Lets callers map `rate_limited:*` row errors back to structured metadata without
parsing the error strings.

  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **username** `string`: No description
  - **rateLimitedUntil** `string` (date-time): No description

#### 400: Invalid CSV or validation errors

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 429: 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).


**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## BulkUploadResult

Result of a CSV bulk upload. The same shape is returned for `200` (all rows
succeeded or all failed) and `207` (mixed). Per-row outcomes live in `results`;
the row's success is `ok`, and failures carry machine-readable codes in `errors`.


### Properties

- **total** `integer`: Number of data rows processed from the CSV
- **valid** `integer`: Count of rows that succeeded (results[].ok === true)
- **invalid** `integer`: Count of rows that failed (total - valid)
- **results** `array`: One entry per CSV data row, in row order.
- **warnings** `array`: Top-level advisory warnings (e.g. `rows_exceed_advisory_limit:500`). Empty when none.
- **rateLimitedAccounts** `array`: Present only when one or more rows targeted an account currently in cooldown.
Lets callers map `rate_limited:*` row errors back to structured metadata without
parsing the error strings.

---

# Create post API Reference

Create and optionally publish a post. Immediate posts (`publishNow: true`) include `platformPostUrl` in the response.
Content is optional when media is attached or all platforms have `customContent`. See each platform's schema for media constraints.

## Idempotency

Two layers of duplicate-protection apply, so safe-to-retry callers (network blips, n8n / Zapier retries, etc.) don't accidentally double-post.

**1. Same-request idempotency (5-minute window).**
Pass an `x-request-id` header to mark a logical request. If a second request arrives with the same `x-request-id` while the first is in-flight (or within ~5 minutes of completion), we return **HTTP 200** with the original post in the `existingPost` field — no new post is created. The official Zernio SDKs auto-generate a unique `x-request-id` per call. If you're using a generic HTTP client (curl, n8n's HTTP node, Zapier, custom code), either:
- Set a unique `x-request-id` per logical call (recommended — UUIDv4 is fine)
- Or simply omit the header — we'll treat each request as new

**Common pitfall**: if your workflow tool uses a single execution-level request ID and reuses it across multiple HTTP nodes (e.g. one ID for the whole run, shared across 6 different platform calls), every call after the first will look like a retry of the first and return its post. Generate a fresh ID per node.

**2. Content-hash dedup (24-hour window).**
Independently, 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`. Returns `error`, `accountId`, `platform`, and `existingPostId` so you can find the original. To intentionally re-post identical content within 24h, change something (the caption, the media, the account) — the dedup is keyed on the full content fingerprint.

Order: same-`x-request-id` retries (200) are checked first; if no idempotency match, the content-hash dedup (409) runs.


## GET /v1/posts

**List posts**

Returns a paginated list of posts. Published posts include platformPostUrl with the public URL on each platform.

### Parameters

- **undefined** (optional): No description
- **undefined** (optional): No description
- **status** (optional) in query: No description
- **platform** (optional) in query: No description
- **profileId** (optional) in query: No description
- **createdBy** (optional) in query: No description
- **dateFrom** (optional) in query: No description
- **dateTo** (optional) in query: No description
- **includeHidden** (optional) in query: No description
- **search** (optional) in query: Search posts by text content.
- **sortBy** (optional) in query: Sort order for results.
- **accountId** (optional) in query: Filter posts to those published via a specific social account (24-char hex ObjectId).

### Responses

#### 200: Paginated posts

**Response Body:**

- **posts** `array[Post]`: 
- **pagination**: `Pagination` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/posts

**Create post**

Create and optionally publish a post. Immediate posts (`publishNow: true`) include `platformPostUrl` in the response.
Content is optional when media is attached or all platforms have `customContent`. See each platform's schema for media constraints.

## Idempotency

Two layers of duplicate-protection apply, so safe-to-retry callers (network blips, n8n / Zapier retries, etc.) don't accidentally double-post.

**1. Same-request idempotency (5-minute window).**
Pass an `x-request-id` header to mark a logical request. If a second request arrives with the same `x-request-id` while the first is in-flight (or within ~5 minutes of completion), we return **HTTP 200** with the original post in the `existingPost` field — no new post is created. The official Zernio SDKs auto-generate a unique `x-request-id` per call. If you're using a generic HTTP client (curl, n8n's HTTP node, Zapier, custom code), either:
- Set a unique `x-request-id` per logical call (recommended — UUIDv4 is fine)
- Or simply omit the header — we'll treat each request as new

**Common pitfall**: if your workflow tool uses a single execution-level request ID and reuses it across multiple HTTP nodes (e.g. one ID for the whole run, shared across 6 different platform calls), every call after the first will look like a retry of the first and return its post. Generate a fresh ID per node.

**2. Content-hash dedup (24-hour window).**
Independently, 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`. Returns `error`, `accountId`, `platform`, and `existingPostId` so you can find the original. To intentionally re-post identical content within 24h, change something (the caption, the media, the account) — the dedup is keyed on the full content fingerprint.

Order: same-`x-request-id` retries (200) are checked first; if no idempotency match, the content-hash dedup (409) runs.


### Parameters

- **x-request-id** (optional) in header: Optional client-generated request identifier for safe retry (idempotency). When two requests carry the same value, the second is treated as a retry of the first and returns the original post (HTTP 200) instead of creating a duplicate. Window is ~5 minutes from the first request. Generate a UUID per logical call. SDKs do this automatically; HTTP clients should set it themselves or omit it. See the operation description for the full idempotency contract.


### Request Body

- **title** `string`: No description
- **content** `string`: Post caption/text. Optional when media is attached or all platforms have customContent. Required for text-only posts.
- **mediaItems** `array`: No description
- **platforms** `array`: Target platforms and accounts for this post. Required for non-draft posts (returns 400 if empty). Drafts can omit platforms.
- **scheduledFor** `string`: No description
- **publishNow** `boolean`: No description
- **isDraft** `boolean`: When true, saves the post as a draft. When none of scheduledFor, publishNow, or queuedFromProfile are provided, the post defaults to draft automatically.
- **timezone** `string`: No description
- **tags** `array`: Tags/keywords. YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates auto-removed.
- **hashtags** `array`: No description
- **mentions** `array`: Stored for reference only. This field does NOT automatically create @mentions when publishing. For LinkedIn @mentions, use the /v1/accounts/{accountId}/linkedin-mentions endpoint to resolve profile URLs to URNs, then embed the returned mentionFormat directly in the post content field.
- **crosspostingEnabled** `boolean`: No description
- **metadata** `object`: No description
- **tiktokSettings**: Root-level TikTok settings applied to all TikTok platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
- **facebookSettings**: Root-level Facebook settings applied to all Facebook platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
- **recycling**: No description
- **queuedFromProfile** `string`: 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** `string`: Specific queue ID to use when scheduling via queue.
Only used when queuedFromProfile is also provided.
If omitted, uses the profile's default queue.


### Responses

#### 201: Post created

**Response Body:**

- **message** `string`: No description
- **post**: `Post` - See schema definition

#### 400: Validation error

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

**Response Body:**

- **error** `string`: No description

#### 409: 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 of an in-flight call. Distinct from same-`x-request-id` retries (which return HTTP 200 with the original post — see operation description for the idempotency contract).

Body fields:
- `error` — human-readable message
- `details.accountId` — the account that already has this content
- `details.platform` — the platform that already has this content
- `details.existingPostId` — Zernio `_id` of the original post

To 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.


**Response Body:**

- **error** `string`: No description (example: "This exact content is already scheduled, publishing, or was posted to this account within the last 24 hours.")
- **details** `object`: 
  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **existingPostId** `string`: No description

#### 429: Rate limit exceeded. Possible causes: API rate limit, velocity limit (15 posts/hour per account), account cooldown, or daily platform limits.

**Response Body:**

- **error** `string`: No description
- **details** `object`: Additional context about the rate limit

---


# Related Schema Definitions

## PostsListResponse

### Properties

- **posts** `array`: No description
- **pagination**: No description

## Post

### Properties

- **_id** `string`: No description
- **userId**: No description
- **title** `string`: YouTube: title must be ≤ 100 characters.

- **content** `string`: No description
- **mediaItems** `array`: No description
- **platforms** `array`: No description
- **scheduledFor** `string`: No description
- **timezone** `string`: No description
- **status** `string`: No description - one of: draft, scheduled, publishing, published, failed, partial
- **tags** `array`: YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates removed.
- **hashtags** `array`: No description
- **mentions** `array`: Stored for reference only. This field does NOT automatically create @mentions when publishing. For LinkedIn @mentions, use the /v1/accounts/{accountId}/linkedin-mentions endpoint to resolve profile URLs to URNs, then embed the returned mentionFormat directly in the post content field.
- **visibility** `string`: No description - one of: public, private, unlisted
- **metadata** `object`: No description
- **recycling**: No description
- **recycledFromPostId** `string`: ID of the original post if this post was created via recycling
- **queuedFromProfile** `string`: Profile ID if the post was scheduled via the queue
- **queueId** `string`: Queue ID if the post was scheduled via a specific queue
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

## Pagination

### Properties

- **page** `integer`: No description
- **limit** `integer`: No description
- **total** `integer`: No description
- **pages** `integer`: No description

## TikTokPlatformData

Photo carousels up to 35 images. Video titles up to 2200 chars, photo titles truncated to 90 chars.
privacyLevel must match creator_info options. Both camelCase and snake_case accepted.

Creator Inbox (draft mode): Set draft: true to send content to the TikTok Creator Inbox
instead of publishing immediately. The creator receives an inbox notification and completes
the post using TikTok's editing flow. This maps to TikTok's post_mode: "MEDIA_UPLOAD" internally.

Important: The field publish_type is NOT supported. Use draft: true for Creator Inbox flow.

Photo drafts use the /v2/post/publish/content/init/ endpoint with post_mode: "MEDIA_UPLOAD".
Video drafts use the dedicated /v2/post/publish/inbox/video/init/ endpoint.

When draft: true, the video.upload scope is required. When draft is false or omitted
(direct post), the video.publish scope is required. For Creator Inbox, TikTok app version
must be 31.8 or higher.


### Properties

- **draft** `boolean`: When true, sends the post to the TikTok Creator Inbox as a draft instead of publishing
immediately. The creator receives an inbox notification to complete posting via TikTok's
editing flow. Maps to TikTok API post_mode: "MEDIA_UPLOAD" (photos) or the dedicated
inbox endpoint (videos). When false or omitted, publishes directly via post_mode: "DIRECT_POST".
Note: publish_type is not a supported field. Use this field instead.

- **privacyLevel** `string`: One of the values returned by the TikTok creator info API for the account
- **allowComment** `boolean`: Allow comments on the post
- **allowDuet** `boolean`: Allow duets (required for video posts)
- **allowStitch** `boolean`: Allow stitches (required for video posts)
- **commercialContentType** `string`: Type of commercial content disclosure - one of: none, brand_organic, brand_content
- **brandPartnerPromote** `boolean`: Whether the post promotes a brand partner
- **isBrandOrganicPost** `boolean`: Whether the post is a brand organic post
- **contentPreviewConfirmed** `boolean`: User has confirmed they previewed the content
- **expressConsentGiven** `boolean`: User has given express consent for posting
- **mediaType** `string`: Optional override. Defaults based on provided media items. - one of: video, photo
- **videoCoverTimestampMs** `integer`: 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. (min: 0)
- **videoCoverImageUrl** `string`: Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). The image is stitched as a single frame at the start of the video and used as the cover. Overrides videoCoverTimestampMs when provided.
- **photoCoverIndex** `integer`: Optional for photo carousels. Index of image to use as cover, 0-based (defaults to 0/first image). (min: 0)
- **autoAddMusic** `boolean`: When true, TikTok may add recommended music (photos only)
- **videoMadeWithAi** `boolean`: Set true to disclose AI-generated content
- **description** `string`: Optional long-form description for photo posts (max 4000 chars). Recommended when content exceeds 90 chars, as photo titles are auto-truncated. (max: 4000)

## FacebookPlatformData

Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Carousel posts (carouselCards) render a 2-5 card multi-link post, images only, mutually exclusive with story/reel. Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories.


### Properties

- **draft** `boolean`: When true, creates the post as an unpublished draft visible 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)
- **contentType** `string`: Set to 'story' for Page Stories (24h ephemeral) or 'reel' for Reels (short vertical video). Defaults to feed post if omitted. - one of: story, reel
- **title** `string`: Reel title (only for contentType=reel). Separate from the caption/content field.
- **firstComment** `string`: Optional first comment to post immediately after publishing (feed posts and reels, not stories). Skipped when draft is true.
- **pageId** `string`: 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**: No description
- **carouselCards** `array`: Renders the post as a multi-link carousel (organic Page post). When set, mediaItems must be provided with the same length and all items must be images (no videos). Each cards[i] adds the click-through link and headline for the image at mediaItems[i]. Mutually exclusive with contentType=story|reel. Facebook display truncates name at ~35 chars and description at ~30 chars; longer strings are accepted but get truncated on render.

- **carouselLink** `string`: 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.


## PostCreateResponse

### Properties

- **message** `string`: No description
- **post**: No description

---

# Delete post API Reference

Delete a draft or scheduled post from Zernio. Published posts cannot be deleted; use the Unpublish endpoint instead. Upload quota is automatically refunded.

## GET /v1/posts/{postId}

**Get post**

Fetch a single post by ID. For published posts, this returns platformPostUrl for each platform.


### Parameters

- **postId** (required) in path: No description

### Responses

#### 200: Post

**Response Body:**

- **post**: `Post` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PUT /v1/posts/{postId}

**Update post**

Update an existing post. Draft, scheduled, failed, partial, and cancelled posts can be edited.
Published posts can only have their recycling config updated.


### Parameters

- **postId** (required) in path: No description

### Request Body

- **title** `string`: No description
- **content** `string`: No description
- **mediaItems** `array`: No description
- **platforms** `array`: Target platforms and accounts for this post. Each item must include platform and accountId.
- **scheduledFor** `string`: No description
- **publishNow** `boolean`: No description
- **isDraft** `boolean`: No description
- **timezone** `string`: No description
- **visibility** `string`: No description - one of: public, private, unlisted
- **tags** `array`: No description
- **hashtags** `array`: No description
- **mentions** `array`: No description
- **crosspostingEnabled** `boolean`: No description
- **metadata** `object`: No description
- **queuedFromProfile** `string`: Profile ID to schedule via queue.
- **queueId** `string`: Specific queue ID to use when scheduling via queue.
- **tiktokSettings**: Root-level TikTok settings applied to all TikTok platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
- **facebookSettings**: Root-level Facebook settings applied to all Facebook platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
- **recycling**: No description

### Responses

#### 200: Post updated

**Response Body:**

- **message** `string`: No description
- **post**: `Post` - See schema definition

#### 207: Partial publish success

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/posts/{postId}

**Delete post**

Delete a draft or scheduled post from Zernio. Published posts cannot be deleted; use the Unpublish endpoint instead. Upload quota is automatically refunded.

### Parameters

- **postId** (required) in path: No description

### Responses

#### 200: Deleted

**Response Body:**

- **message** `string`: No description

#### 400: Cannot delete published posts

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## PostGetResponse

### Properties

- **post**: No description

## Post

### Properties

- **_id** `string`: No description
- **userId**: No description
- **title** `string`: YouTube: title must be ≤ 100 characters.

- **content** `string`: No description
- **mediaItems** `array`: No description
- **platforms** `array`: No description
- **scheduledFor** `string`: No description
- **timezone** `string`: No description
- **status** `string`: No description - one of: draft, scheduled, publishing, published, failed, partial
- **tags** `array`: YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates removed.
- **hashtags** `array`: No description
- **mentions** `array`: Stored for reference only. This field does NOT automatically create @mentions when publishing. For LinkedIn @mentions, use the /v1/accounts/{accountId}/linkedin-mentions endpoint to resolve profile URLs to URNs, then embed the returned mentionFormat directly in the post content field.
- **visibility** `string`: No description - one of: public, private, unlisted
- **metadata** `object`: No description
- **recycling**: No description
- **recycledFromPostId** `string`: ID of the original post if this post was created via recycling
- **queuedFromProfile** `string`: Profile ID if the post was scheduled via the queue
- **queueId** `string`: Queue ID if the post was scheduled via a specific queue
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

## TikTokPlatformData

Photo carousels up to 35 images. Video titles up to 2200 chars, photo titles truncated to 90 chars.
privacyLevel must match creator_info options. Both camelCase and snake_case accepted.

Creator Inbox (draft mode): Set draft: true to send content to the TikTok Creator Inbox
instead of publishing immediately. The creator receives an inbox notification and completes
the post using TikTok's editing flow. This maps to TikTok's post_mode: "MEDIA_UPLOAD" internally.

Important: The field publish_type is NOT supported. Use draft: true for Creator Inbox flow.

Photo drafts use the /v2/post/publish/content/init/ endpoint with post_mode: "MEDIA_UPLOAD".
Video drafts use the dedicated /v2/post/publish/inbox/video/init/ endpoint.

When draft: true, the video.upload scope is required. When draft is false or omitted
(direct post), the video.publish scope is required. For Creator Inbox, TikTok app version
must be 31.8 or higher.


### Properties

- **draft** `boolean`: When true, sends the post to the TikTok Creator Inbox as a draft instead of publishing
immediately. The creator receives an inbox notification to complete posting via TikTok's
editing flow. Maps to TikTok API post_mode: "MEDIA_UPLOAD" (photos) or the dedicated
inbox endpoint (videos). When false or omitted, publishes directly via post_mode: "DIRECT_POST".
Note: publish_type is not a supported field. Use this field instead.

- **privacyLevel** `string`: One of the values returned by the TikTok creator info API for the account
- **allowComment** `boolean`: Allow comments on the post
- **allowDuet** `boolean`: Allow duets (required for video posts)
- **allowStitch** `boolean`: Allow stitches (required for video posts)
- **commercialContentType** `string`: Type of commercial content disclosure - one of: none, brand_organic, brand_content
- **brandPartnerPromote** `boolean`: Whether the post promotes a brand partner
- **isBrandOrganicPost** `boolean`: Whether the post is a brand organic post
- **contentPreviewConfirmed** `boolean`: User has confirmed they previewed the content
- **expressConsentGiven** `boolean`: User has given express consent for posting
- **mediaType** `string`: Optional override. Defaults based on provided media items. - one of: video, photo
- **videoCoverTimestampMs** `integer`: 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. (min: 0)
- **videoCoverImageUrl** `string`: Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). The image is stitched as a single frame at the start of the video and used as the cover. Overrides videoCoverTimestampMs when provided.
- **photoCoverIndex** `integer`: Optional for photo carousels. Index of image to use as cover, 0-based (defaults to 0/first image). (min: 0)
- **autoAddMusic** `boolean`: When true, TikTok may add recommended music (photos only)
- **videoMadeWithAi** `boolean`: Set true to disclose AI-generated content
- **description** `string`: Optional long-form description for photo posts (max 4000 chars). Recommended when content exceeds 90 chars, as photo titles are auto-truncated. (max: 4000)

## FacebookPlatformData

Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Carousel posts (carouselCards) render a 2-5 card multi-link post, images only, mutually exclusive with story/reel. Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories.


### Properties

- **draft** `boolean`: When true, creates the post as an unpublished draft visible 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)
- **contentType** `string`: Set to 'story' for Page Stories (24h ephemeral) or 'reel' for Reels (short vertical video). Defaults to feed post if omitted. - one of: story, reel
- **title** `string`: Reel title (only for contentType=reel). Separate from the caption/content field.
- **firstComment** `string`: Optional first comment to post immediately after publishing (feed posts and reels, not stories). Skipped when draft is true.
- **pageId** `string`: 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**: No description
- **carouselCards** `array`: Renders the post as a multi-link carousel (organic Page post). When set, mediaItems must be provided with the same length and all items must be images (no videos). Each cards[i] adds the click-through link and headline for the image at mediaItems[i]. Mutually exclusive with contentType=story|reel. Facebook display truncates name at ~35 chars and description at ~30 chars; longer strings are accepted but get truncated on render.

- **carouselLink** `string`: 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.


## PostUpdateResponse

### Properties

- **message** `string`: No description
- **post**: No description

## PostDeleteResponse

### Properties

- **message** `string`: No description

---

# Edit published post API Reference

Edit a published post on a social media platform. Currently only supported for X (Twitter).

Requirements:
- Connected X account must have an active X Premium subscription
- Must be within 1 hour of original publish time
- Maximum 5 edits per tweet (enforced by X)
- Text-only edits (media changes are not supported)

The post record in Zernio is updated with the new content and edit history.


## POST /v1/posts/{postId}/edit

**Edit published post**

Edit a published post on a social media platform. Currently only supported for X (Twitter).

Requirements:
- Connected X account must have an active X Premium subscription
- Must be within 1 hour of original publish time
- Maximum 5 edits per tweet (enforced by X)
- Text-only edits (media changes are not supported)

The post record in Zernio is updated with the new content and edit history.


### Parameters

- **postId** (required) in path: No description

### Request Body

- **platform** (required) `string`: The platform to edit the post on. Currently only twitter is supported. - one of: twitter
- **content** (required) `string`: The new tweet text content

### Responses

#### 200: Post edited successfully

**Response Body:**

- **success** `boolean`: No description
- **id** `string`: New tweet ID assigned by X after edit
- **url** `string` (uri): URL of the edited tweet
- **message** `string`: No description

#### 400: Invalid request: platform not supported, post not published, edit window expired, not Premium, or missing content.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 500: Platform API edit failed

---

---

# Get post API Reference

Fetch a single post by ID. For published posts, this returns platformPostUrl for each platform.


## GET /v1/posts/{postId}

**Get post**

Fetch a single post by ID. For published posts, this returns platformPostUrl for each platform.


### Parameters

- **postId** (required) in path: No description

### Responses

#### 200: Post

**Response Body:**

- **post**: `Post` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PUT /v1/posts/{postId}

**Update post**

Update an existing post. Draft, scheduled, failed, partial, and cancelled posts can be edited.
Published posts can only have their recycling config updated.


### Parameters

- **postId** (required) in path: No description

### Request Body

- **title** `string`: No description
- **content** `string`: No description
- **mediaItems** `array`: No description
- **platforms** `array`: Target platforms and accounts for this post. Each item must include platform and accountId.
- **scheduledFor** `string`: No description
- **publishNow** `boolean`: No description
- **isDraft** `boolean`: No description
- **timezone** `string`: No description
- **visibility** `string`: No description - one of: public, private, unlisted
- **tags** `array`: No description
- **hashtags** `array`: No description
- **mentions** `array`: No description
- **crosspostingEnabled** `boolean`: No description
- **metadata** `object`: No description
- **queuedFromProfile** `string`: Profile ID to schedule via queue.
- **queueId** `string`: Specific queue ID to use when scheduling via queue.
- **tiktokSettings**: Root-level TikTok settings applied to all TikTok platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
- **facebookSettings**: Root-level Facebook settings applied to all Facebook platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
- **recycling**: No description

### Responses

#### 200: Post updated

**Response Body:**

- **message** `string`: No description
- **post**: `Post` - See schema definition

#### 207: Partial publish success

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/posts/{postId}

**Delete post**

Delete a draft or scheduled post from Zernio. Published posts cannot be deleted; use the Unpublish endpoint instead. Upload quota is automatically refunded.

### Parameters

- **postId** (required) in path: No description

### Responses

#### 200: Deleted

**Response Body:**

- **message** `string`: No description

#### 400: Cannot delete published posts

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## PostGetResponse

### Properties

- **post**: No description

## Post

### Properties

- **_id** `string`: No description
- **userId**: No description
- **title** `string`: YouTube: title must be ≤ 100 characters.

- **content** `string`: No description
- **mediaItems** `array`: No description
- **platforms** `array`: No description
- **scheduledFor** `string`: No description
- **timezone** `string`: No description
- **status** `string`: No description - one of: draft, scheduled, publishing, published, failed, partial
- **tags** `array`: YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates removed.
- **hashtags** `array`: No description
- **mentions** `array`: Stored for reference only. This field does NOT automatically create @mentions when publishing. For LinkedIn @mentions, use the /v1/accounts/{accountId}/linkedin-mentions endpoint to resolve profile URLs to URNs, then embed the returned mentionFormat directly in the post content field.
- **visibility** `string`: No description - one of: public, private, unlisted
- **metadata** `object`: No description
- **recycling**: No description
- **recycledFromPostId** `string`: ID of the original post if this post was created via recycling
- **queuedFromProfile** `string`: Profile ID if the post was scheduled via the queue
- **queueId** `string`: Queue ID if the post was scheduled via a specific queue
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

## TikTokPlatformData

Photo carousels up to 35 images. Video titles up to 2200 chars, photo titles truncated to 90 chars.
privacyLevel must match creator_info options. Both camelCase and snake_case accepted.

Creator Inbox (draft mode): Set draft: true to send content to the TikTok Creator Inbox
instead of publishing immediately. The creator receives an inbox notification and completes
the post using TikTok's editing flow. This maps to TikTok's post_mode: "MEDIA_UPLOAD" internally.

Important: The field publish_type is NOT supported. Use draft: true for Creator Inbox flow.

Photo drafts use the /v2/post/publish/content/init/ endpoint with post_mode: "MEDIA_UPLOAD".
Video drafts use the dedicated /v2/post/publish/inbox/video/init/ endpoint.

When draft: true, the video.upload scope is required. When draft is false or omitted
(direct post), the video.publish scope is required. For Creator Inbox, TikTok app version
must be 31.8 or higher.


### Properties

- **draft** `boolean`: When true, sends the post to the TikTok Creator Inbox as a draft instead of publishing
immediately. The creator receives an inbox notification to complete posting via TikTok's
editing flow. Maps to TikTok API post_mode: "MEDIA_UPLOAD" (photos) or the dedicated
inbox endpoint (videos). When false or omitted, publishes directly via post_mode: "DIRECT_POST".
Note: publish_type is not a supported field. Use this field instead.

- **privacyLevel** `string`: One of the values returned by the TikTok creator info API for the account
- **allowComment** `boolean`: Allow comments on the post
- **allowDuet** `boolean`: Allow duets (required for video posts)
- **allowStitch** `boolean`: Allow stitches (required for video posts)
- **commercialContentType** `string`: Type of commercial content disclosure - one of: none, brand_organic, brand_content
- **brandPartnerPromote** `boolean`: Whether the post promotes a brand partner
- **isBrandOrganicPost** `boolean`: Whether the post is a brand organic post
- **contentPreviewConfirmed** `boolean`: User has confirmed they previewed the content
- **expressConsentGiven** `boolean`: User has given express consent for posting
- **mediaType** `string`: Optional override. Defaults based on provided media items. - one of: video, photo
- **videoCoverTimestampMs** `integer`: 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. (min: 0)
- **videoCoverImageUrl** `string`: Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). The image is stitched as a single frame at the start of the video and used as the cover. Overrides videoCoverTimestampMs when provided.
- **photoCoverIndex** `integer`: Optional for photo carousels. Index of image to use as cover, 0-based (defaults to 0/first image). (min: 0)
- **autoAddMusic** `boolean`: When true, TikTok may add recommended music (photos only)
- **videoMadeWithAi** `boolean`: Set true to disclose AI-generated content
- **description** `string`: Optional long-form description for photo posts (max 4000 chars). Recommended when content exceeds 90 chars, as photo titles are auto-truncated. (max: 4000)

## FacebookPlatformData

Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Carousel posts (carouselCards) render a 2-5 card multi-link post, images only, mutually exclusive with story/reel. Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories.


### Properties

- **draft** `boolean`: When true, creates the post as an unpublished draft visible 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)
- **contentType** `string`: Set to 'story' for Page Stories (24h ephemeral) or 'reel' for Reels (short vertical video). Defaults to feed post if omitted. - one of: story, reel
- **title** `string`: Reel title (only for contentType=reel). Separate from the caption/content field.
- **firstComment** `string`: Optional first comment to post immediately after publishing (feed posts and reels, not stories). Skipped when draft is true.
- **pageId** `string`: 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**: No description
- **carouselCards** `array`: Renders the post as a multi-link carousel (organic Page post). When set, mediaItems must be provided with the same length and all items must be images (no videos). Each cards[i] adds the click-through link and headline for the image at mediaItems[i]. Mutually exclusive with contentType=story|reel. Facebook display truncates name at ~35 chars and description at ~30 chars; longer strings are accepted but get truncated on render.

- **carouselLink** `string`: 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.


## PostUpdateResponse

### Properties

- **message** `string`: No description
- **post**: No description

## PostDeleteResponse

### Properties

- **message** `string`: No description

---

# List posts API Reference

Returns a paginated list of posts. Published posts include platformPostUrl with the public URL on each platform.

## GET /v1/posts

**List posts**

Returns a paginated list of posts. Published posts include platformPostUrl with the public URL on each platform.

### Parameters

- **undefined** (optional): No description
- **undefined** (optional): No description
- **status** (optional) in query: No description
- **platform** (optional) in query: No description
- **profileId** (optional) in query: No description
- **createdBy** (optional) in query: No description
- **dateFrom** (optional) in query: No description
- **dateTo** (optional) in query: No description
- **includeHidden** (optional) in query: No description
- **search** (optional) in query: Search posts by text content.
- **sortBy** (optional) in query: Sort order for results.
- **accountId** (optional) in query: Filter posts to those published via a specific social account (24-char hex ObjectId).

### Responses

#### 200: Paginated posts

**Response Body:**

- **posts** `array[Post]`: 
- **pagination**: `Pagination` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/posts

**Create post**

Create and optionally publish a post. Immediate posts (`publishNow: true`) include `platformPostUrl` in the response.
Content is optional when media is attached or all platforms have `customContent`. See each platform's schema for media constraints.

## Idempotency

Two layers of duplicate-protection apply, so safe-to-retry callers (network blips, n8n / Zapier retries, etc.) don't accidentally double-post.

**1. Same-request idempotency (5-minute window).**
Pass an `x-request-id` header to mark a logical request. If a second request arrives with the same `x-request-id` while the first is in-flight (or within ~5 minutes of completion), we return **HTTP 200** with the original post in the `existingPost` field — no new post is created. The official Zernio SDKs auto-generate a unique `x-request-id` per call. If you're using a generic HTTP client (curl, n8n's HTTP node, Zapier, custom code), either:
- Set a unique `x-request-id` per logical call (recommended — UUIDv4 is fine)
- Or simply omit the header — we'll treat each request as new

**Common pitfall**: if your workflow tool uses a single execution-level request ID and reuses it across multiple HTTP nodes (e.g. one ID for the whole run, shared across 6 different platform calls), every call after the first will look like a retry of the first and return its post. Generate a fresh ID per node.

**2. Content-hash dedup (24-hour window).**
Independently, 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`. Returns `error`, `accountId`, `platform`, and `existingPostId` so you can find the original. To intentionally re-post identical content within 24h, change something (the caption, the media, the account) — the dedup is keyed on the full content fingerprint.

Order: same-`x-request-id` retries (200) are checked first; if no idempotency match, the content-hash dedup (409) runs.


### Parameters

- **x-request-id** (optional) in header: Optional client-generated request identifier for safe retry (idempotency). When two requests carry the same value, the second is treated as a retry of the first and returns the original post (HTTP 200) instead of creating a duplicate. Window is ~5 minutes from the first request. Generate a UUID per logical call. SDKs do this automatically; HTTP clients should set it themselves or omit it. See the operation description for the full idempotency contract.


### Request Body

- **title** `string`: No description
- **content** `string`: Post caption/text. Optional when media is attached or all platforms have customContent. Required for text-only posts.
- **mediaItems** `array`: No description
- **platforms** `array`: Target platforms and accounts for this post. Required for non-draft posts (returns 400 if empty). Drafts can omit platforms.
- **scheduledFor** `string`: No description
- **publishNow** `boolean`: No description
- **isDraft** `boolean`: When true, saves the post as a draft. When none of scheduledFor, publishNow, or queuedFromProfile are provided, the post defaults to draft automatically.
- **timezone** `string`: No description
- **tags** `array`: Tags/keywords. YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates auto-removed.
- **hashtags** `array`: No description
- **mentions** `array`: Stored for reference only. This field does NOT automatically create @mentions when publishing. For LinkedIn @mentions, use the /v1/accounts/{accountId}/linkedin-mentions endpoint to resolve profile URLs to URNs, then embed the returned mentionFormat directly in the post content field.
- **crosspostingEnabled** `boolean`: No description
- **metadata** `object`: No description
- **tiktokSettings**: Root-level TikTok settings applied to all TikTok platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
- **facebookSettings**: Root-level Facebook settings applied to all Facebook platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
- **recycling**: No description
- **queuedFromProfile** `string`: 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** `string`: Specific queue ID to use when scheduling via queue.
Only used when queuedFromProfile is also provided.
If omitted, uses the profile's default queue.


### Responses

#### 201: Post created

**Response Body:**

- **message** `string`: No description
- **post**: `Post` - See schema definition

#### 400: Validation error

**Response Body:**

- **error** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

**Response Body:**

- **error** `string`: No description

#### 409: 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 of an in-flight call. Distinct from same-`x-request-id` retries (which return HTTP 200 with the original post — see operation description for the idempotency contract).

Body fields:
- `error` — human-readable message
- `details.accountId` — the account that already has this content
- `details.platform` — the platform that already has this content
- `details.existingPostId` — Zernio `_id` of the original post

To 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.


**Response Body:**

- **error** `string`: No description (example: "This exact content is already scheduled, publishing, or was posted to this account within the last 24 hours.")
- **details** `object`: 
  - **accountId** `string`: No description
  - **platform** `string`: No description
  - **existingPostId** `string`: No description

#### 429: Rate limit exceeded. Possible causes: API rate limit, velocity limit (15 posts/hour per account), account cooldown, or daily platform limits.

**Response Body:**

- **error** `string`: No description
- **details** `object`: Additional context about the rate limit

---


# Related Schema Definitions

## PostsListResponse

### Properties

- **posts** `array`: No description
- **pagination**: No description

## Post

### Properties

- **_id** `string`: No description
- **userId**: No description
- **title** `string`: YouTube: title must be ≤ 100 characters.

- **content** `string`: No description
- **mediaItems** `array`: No description
- **platforms** `array`: No description
- **scheduledFor** `string`: No description
- **timezone** `string`: No description
- **status** `string`: No description - one of: draft, scheduled, publishing, published, failed, partial
- **tags** `array`: YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates removed.
- **hashtags** `array`: No description
- **mentions** `array`: Stored for reference only. This field does NOT automatically create @mentions when publishing. For LinkedIn @mentions, use the /v1/accounts/{accountId}/linkedin-mentions endpoint to resolve profile URLs to URNs, then embed the returned mentionFormat directly in the post content field.
- **visibility** `string`: No description - one of: public, private, unlisted
- **metadata** `object`: No description
- **recycling**: No description
- **recycledFromPostId** `string`: ID of the original post if this post was created via recycling
- **queuedFromProfile** `string`: Profile ID if the post was scheduled via the queue
- **queueId** `string`: Queue ID if the post was scheduled via a specific queue
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

## Pagination

### Properties

- **page** `integer`: No description
- **limit** `integer`: No description
- **total** `integer`: No description
- **pages** `integer`: No description

## TikTokPlatformData

Photo carousels up to 35 images. Video titles up to 2200 chars, photo titles truncated to 90 chars.
privacyLevel must match creator_info options. Both camelCase and snake_case accepted.

Creator Inbox (draft mode): Set draft: true to send content to the TikTok Creator Inbox
instead of publishing immediately. The creator receives an inbox notification and completes
the post using TikTok's editing flow. This maps to TikTok's post_mode: "MEDIA_UPLOAD" internally.

Important: The field publish_type is NOT supported. Use draft: true for Creator Inbox flow.

Photo drafts use the /v2/post/publish/content/init/ endpoint with post_mode: "MEDIA_UPLOAD".
Video drafts use the dedicated /v2/post/publish/inbox/video/init/ endpoint.

When draft: true, the video.upload scope is required. When draft is false or omitted
(direct post), the video.publish scope is required. For Creator Inbox, TikTok app version
must be 31.8 or higher.


### Properties

- **draft** `boolean`: When true, sends the post to the TikTok Creator Inbox as a draft instead of publishing
immediately. The creator receives an inbox notification to complete posting via TikTok's
editing flow. Maps to TikTok API post_mode: "MEDIA_UPLOAD" (photos) or the dedicated
inbox endpoint (videos). When false or omitted, publishes directly via post_mode: "DIRECT_POST".
Note: publish_type is not a supported field. Use this field instead.

- **privacyLevel** `string`: One of the values returned by the TikTok creator info API for the account
- **allowComment** `boolean`: Allow comments on the post
- **allowDuet** `boolean`: Allow duets (required for video posts)
- **allowStitch** `boolean`: Allow stitches (required for video posts)
- **commercialContentType** `string`: Type of commercial content disclosure - one of: none, brand_organic, brand_content
- **brandPartnerPromote** `boolean`: Whether the post promotes a brand partner
- **isBrandOrganicPost** `boolean`: Whether the post is a brand organic post
- **contentPreviewConfirmed** `boolean`: User has confirmed they previewed the content
- **expressConsentGiven** `boolean`: User has given express consent for posting
- **mediaType** `string`: Optional override. Defaults based on provided media items. - one of: video, photo
- **videoCoverTimestampMs** `integer`: 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. (min: 0)
- **videoCoverImageUrl** `string`: Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). The image is stitched as a single frame at the start of the video and used as the cover. Overrides videoCoverTimestampMs when provided.
- **photoCoverIndex** `integer`: Optional for photo carousels. Index of image to use as cover, 0-based (defaults to 0/first image). (min: 0)
- **autoAddMusic** `boolean`: When true, TikTok may add recommended music (photos only)
- **videoMadeWithAi** `boolean`: Set true to disclose AI-generated content
- **description** `string`: Optional long-form description for photo posts (max 4000 chars). Recommended when content exceeds 90 chars, as photo titles are auto-truncated. (max: 4000)

## FacebookPlatformData

Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Carousel posts (carouselCards) render a 2-5 card multi-link post, images only, mutually exclusive with story/reel. Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories.


### Properties

- **draft** `boolean`: When true, creates the post as an unpublished draft visible 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)
- **contentType** `string`: Set to 'story' for Page Stories (24h ephemeral) or 'reel' for Reels (short vertical video). Defaults to feed post if omitted. - one of: story, reel
- **title** `string`: Reel title (only for contentType=reel). Separate from the caption/content field.
- **firstComment** `string`: Optional first comment to post immediately after publishing (feed posts and reels, not stories). Skipped when draft is true.
- **pageId** `string`: 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**: No description
- **carouselCards** `array`: Renders the post as a multi-link carousel (organic Page post). When set, mediaItems must be provided with the same length and all items must be images (no videos). Each cards[i] adds the click-through link and headline for the image at mediaItems[i]. Mutually exclusive with contentType=story|reel. Facebook display truncates name at ~35 chars and description at ~30 chars; longer strings are accepted but get truncated on render.

- **carouselLink** `string`: 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.


## PostCreateResponse

### Properties

- **message** `string`: No description
- **post**: No description

---

# Retry failed post API Reference

Immediately retries publishing a failed post. Returns the updated post with its new status.

## POST /v1/posts/{postId}/retry

**Retry failed post**

Immediately retries publishing a failed post. Returns the updated post with its new status.

### Parameters

- **postId** (required) in path: No description

### Responses

#### 200: Retry successful

**Response Body:**

- **message** `string`: No description
- **post**: `Post` - See schema definition

#### 207: Partial success

#### 400: Invalid state

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 409: Post is currently publishing

#### 429: Rate limit exceeded. Possible causes: API rate limit (requests per minute), velocity limit (15 posts/hour per account), or account cooldown (temporarily rate-limited due to repeated errors).


**Response Body:**

- **error** `string`: No description
- **details** `object`: No description

---


# Related Schema Definitions

## PostRetryResponse

### Properties

- **message** `string`: No description
- **post**: No description

## Post

### Properties

- **_id** `string`: No description
- **userId**: No description
- **title** `string`: YouTube: title must be ≤ 100 characters.

- **content** `string`: No description
- **mediaItems** `array`: No description
- **platforms** `array`: No description
- **scheduledFor** `string`: No description
- **timezone** `string`: No description
- **status** `string`: No description - one of: draft, scheduled, publishing, published, failed, partial
- **tags** `array`: YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates removed.
- **hashtags** `array`: No description
- **mentions** `array`: Stored for reference only. This field does NOT automatically create @mentions when publishing. For LinkedIn @mentions, use the /v1/accounts/{accountId}/linkedin-mentions endpoint to resolve profile URLs to URNs, then embed the returned mentionFormat directly in the post content field.
- **visibility** `string`: No description - one of: public, private, unlisted
- **metadata** `object`: No description
- **recycling**: No description
- **recycledFromPostId** `string`: ID of the original post if this post was created via recycling
- **queuedFromProfile** `string`: Profile ID if the post was scheduled via the queue
- **queueId** `string`: Queue ID if the post was scheduled via a specific queue
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

---

# Unpublish post API Reference

Deletes a published post from the specified platform. The post record in Zernio is kept but its status is updated to cancelled.
Not supported on Instagram, TikTok, or Snapchat. Threaded posts delete all items. YouTube deletion is permanent.


## POST /v1/posts/{postId}/unpublish

**Unpublish post**

Deletes a published post from the specified platform. The post record in Zernio is kept but its status is updated to cancelled.
Not supported on Instagram, TikTok, or Snapchat. Threaded posts delete all items. YouTube deletion is permanent.


### Parameters

- **postId** (required) in path: No description

### Request Body

- **platform** (required) `string`: The platform to delete the post from - one of: threads, facebook, twitter, linkedin, youtube, pinterest, reddit, bluesky, googlebusiness, telegram

### Responses

#### 200: Post deleted from platform

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 400: Invalid request: platform not supported for deletion, post not on that platform, not published, no platform post ID, or no access token.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 500: Platform API deletion failed

---

---

# Update post metadata API Reference

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.

Two modes:

1. Post-based (video published through Zernio): pass the Zernio postId in the URL and platform in the body.
2. 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 social account ID
   for the connected YouTube channel.


## POST /v1/posts/{postId}/update-metadata

**Update post metadata**

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.

Two modes:

1. Post-based (video published through Zernio): pass the Zernio postId in the URL and platform in the body.
2. 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 social account ID
   for the connected YouTube channel.


### Parameters

- **postId** (required) in path: Zernio post ID, or "_" when using direct video ID mode

### Request Body

- **platform** (required) `string`: The platform to update metadata on - one of: youtube
- **videoId** `string`: YouTube video ID (required for direct mode, ignored for post-based mode)
- **accountId** `string`: Zernio social account ID (required for direct mode, ignored for post-based mode)
- **title** `string`: New video title (max 100 characters for YouTube)
- **description** `string`: New video description
- **tags** `array`: Array of keyword tags (max 500 characters combined for YouTube)
- **categoryId** `string`: YouTube video category ID
- **privacyStatus** `string`: Video privacy setting - one of: public, private, unlisted
- **thumbnailUrl** `string`: Public URL of a custom thumbnail image (JPEG, PNG, or GIF, max 2 MB, recommended 1280x720). Works on any video you own, including existing videos not published through Zernio. The channel must be verified (phone verification) to set custom thumbnails.
- **madeForKids** `boolean`: COPPA compliance flag. Set true for child-directed content (restricts comments, notifications, ad targeting).
- **containsSyntheticMedia** `boolean`: AI-generated content disclosure. Set true if the video contains synthetic content that could be mistaken for real. YouTube may add a label.
- **playlistId** `string`: 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.

### Responses

#### 200: Metadata updated successfully

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description
- **videoId** `string`: Only present in direct video ID mode
- **updatedFields** `array[string]`: 

#### 400: Invalid request: unsupported platform, post not published, missing fields, or validation error.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

#### 500: Platform API update failed

---

---

# Update post API Reference

Update an existing post. Draft, scheduled, failed, partial, and cancelled posts can be edited.
Published posts can only have their recycling config updated.


## GET /v1/posts/{postId}

**Get post**

Fetch a single post by ID. For published posts, this returns platformPostUrl for each platform.


### Parameters

- **postId** (required) in path: No description

### Responses

#### 200: Post

**Response Body:**

- **post**: `Post` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PUT /v1/posts/{postId}

**Update post**

Update an existing post. Draft, scheduled, failed, partial, and cancelled posts can be edited.
Published posts can only have their recycling config updated.


### Parameters

- **postId** (required) in path: No description

### Request Body

- **title** `string`: No description
- **content** `string`: No description
- **mediaItems** `array`: No description
- **platforms** `array`: Target platforms and accounts for this post. Each item must include platform and accountId.
- **scheduledFor** `string`: No description
- **publishNow** `boolean`: No description
- **isDraft** `boolean`: No description
- **timezone** `string`: No description
- **visibility** `string`: No description - one of: public, private, unlisted
- **tags** `array`: No description
- **hashtags** `array`: No description
- **mentions** `array`: No description
- **crosspostingEnabled** `boolean`: No description
- **metadata** `object`: No description
- **queuedFromProfile** `string`: Profile ID to schedule via queue.
- **queueId** `string`: Specific queue ID to use when scheduling via queue.
- **tiktokSettings**: Root-level TikTok settings applied to all TikTok platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
- **facebookSettings**: Root-level Facebook settings applied to all Facebook platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
- **recycling**: No description

### Responses

#### 200: Post updated

**Response Body:**

- **message** `string`: No description
- **post**: `Post` - See schema definition

#### 207: Partial publish success

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/posts/{postId}

**Delete post**

Delete a draft or scheduled post from Zernio. Published posts cannot be deleted; use the Unpublish endpoint instead. Upload quota is automatically refunded.

### Parameters

- **postId** (required) in path: No description

### Responses

#### 200: Deleted

**Response Body:**

- **message** `string`: No description

#### 400: Cannot delete published posts

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## PostGetResponse

### Properties

- **post**: No description

## Post

### Properties

- **_id** `string`: No description
- **userId**: No description
- **title** `string`: YouTube: title must be ≤ 100 characters.

- **content** `string`: No description
- **mediaItems** `array`: No description
- **platforms** `array`: No description
- **scheduledFor** `string`: No description
- **timezone** `string`: No description
- **status** `string`: No description - one of: draft, scheduled, publishing, published, failed, partial
- **tags** `array`: YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates removed.
- **hashtags** `array`: No description
- **mentions** `array`: Stored for reference only. This field does NOT automatically create @mentions when publishing. For LinkedIn @mentions, use the /v1/accounts/{accountId}/linkedin-mentions endpoint to resolve profile URLs to URNs, then embed the returned mentionFormat directly in the post content field.
- **visibility** `string`: No description - one of: public, private, unlisted
- **metadata** `object`: No description
- **recycling**: No description
- **recycledFromPostId** `string`: ID of the original post if this post was created via recycling
- **queuedFromProfile** `string`: Profile ID if the post was scheduled via the queue
- **queueId** `string`: Queue ID if the post was scheduled via a specific queue
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

## TikTokPlatformData

Photo carousels up to 35 images. Video titles up to 2200 chars, photo titles truncated to 90 chars.
privacyLevel must match creator_info options. Both camelCase and snake_case accepted.

Creator Inbox (draft mode): Set draft: true to send content to the TikTok Creator Inbox
instead of publishing immediately. The creator receives an inbox notification and completes
the post using TikTok's editing flow. This maps to TikTok's post_mode: "MEDIA_UPLOAD" internally.

Important: The field publish_type is NOT supported. Use draft: true for Creator Inbox flow.

Photo drafts use the /v2/post/publish/content/init/ endpoint with post_mode: "MEDIA_UPLOAD".
Video drafts use the dedicated /v2/post/publish/inbox/video/init/ endpoint.

When draft: true, the video.upload scope is required. When draft is false or omitted
(direct post), the video.publish scope is required. For Creator Inbox, TikTok app version
must be 31.8 or higher.


### Properties

- **draft** `boolean`: When true, sends the post to the TikTok Creator Inbox as a draft instead of publishing
immediately. The creator receives an inbox notification to complete posting via TikTok's
editing flow. Maps to TikTok API post_mode: "MEDIA_UPLOAD" (photos) or the dedicated
inbox endpoint (videos). When false or omitted, publishes directly via post_mode: "DIRECT_POST".
Note: publish_type is not a supported field. Use this field instead.

- **privacyLevel** `string`: One of the values returned by the TikTok creator info API for the account
- **allowComment** `boolean`: Allow comments on the post
- **allowDuet** `boolean`: Allow duets (required for video posts)
- **allowStitch** `boolean`: Allow stitches (required for video posts)
- **commercialContentType** `string`: Type of commercial content disclosure - one of: none, brand_organic, brand_content
- **brandPartnerPromote** `boolean`: Whether the post promotes a brand partner
- **isBrandOrganicPost** `boolean`: Whether the post is a brand organic post
- **contentPreviewConfirmed** `boolean`: User has confirmed they previewed the content
- **expressConsentGiven** `boolean`: User has given express consent for posting
- **mediaType** `string`: Optional override. Defaults based on provided media items. - one of: video, photo
- **videoCoverTimestampMs** `integer`: 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. (min: 0)
- **videoCoverImageUrl** `string`: Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). The image is stitched as a single frame at the start of the video and used as the cover. Overrides videoCoverTimestampMs when provided.
- **photoCoverIndex** `integer`: Optional for photo carousels. Index of image to use as cover, 0-based (defaults to 0/first image). (min: 0)
- **autoAddMusic** `boolean`: When true, TikTok may add recommended music (photos only)
- **videoMadeWithAi** `boolean`: Set true to disclose AI-generated content
- **description** `string`: Optional long-form description for photo posts (max 4000 chars). Recommended when content exceeds 90 chars, as photo titles are auto-truncated. (max: 4000)

## FacebookPlatformData

Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Carousel posts (carouselCards) render a 2-5 card multi-link post, images only, mutually exclusive with story/reel. Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories.


### Properties

- **draft** `boolean`: When true, creates the post as an unpublished draft visible 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)
- **contentType** `string`: Set to 'story' for Page Stories (24h ephemeral) or 'reel' for Reels (short vertical video). Defaults to feed post if omitted. - one of: story, reel
- **title** `string`: Reel title (only for contentType=reel). Separate from the caption/content field.
- **firstComment** `string`: Optional first comment to post immediately after publishing (feed posts and reels, not stories). Skipped when draft is true.
- **pageId** `string`: 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**: No description
- **carouselCards** `array`: Renders the post as a multi-link carousel (organic Page post). When set, mediaItems must be provided with the same length and all items must be images (no videos). Each cards[i] adds the click-through link and headline for the image at mediaItems[i]. Mutually exclusive with contentType=story|reel. Facebook display truncates name at ~35 chars and description at ~30 chars; longer strings are accepted but get truncated on render.

- **carouselLink** `string`: 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.


## PostUpdateResponse

### Properties

- **message** `string`: No description
- **post**: No description

## PostDeleteResponse

### Properties

- **message** `string`: No description

---

# Create profile API Reference

Creates a new profile with a name, optional description, and color.

## GET /v1/profiles

**List profiles**

Returns profiles sorted by creation date. Use includeOverLimit=true to include profiles that exceed the plan limit.

### Parameters

- **includeOverLimit** (optional) in query: When true, includes over-limit profiles (marked with isOverLimit: true).

### Responses

#### 200: Profiles

**Response Body:**

- **profiles** `array[Profile]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/profiles

**Create profile**

Creates a new profile with a name, optional description, and color.

### Request Body

- **name** (required) `string`: No description
- **description** `string`: No description
- **color** `string`: No description

### Responses

#### 201: Created

**Response Body:**

- **message** `string`: No description
- **profile**: `Profile` - See schema definition

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Payment method or enterprise contract required. The authenticated
account hit a billing gate before the connection could proceed.
Three reasons:

  - `free_tier_exceeded`: the team has connected more accounts
    than the free tier allows. Add a payment method on the
    dashboard to continue (the user will be billed per
    additional connected account).

  - `twitter_passthrough`: connecting an X (Twitter) account
    requires a card on file from day one because X API calls
    incur real per-call pass-through costs. Applies to the 1st
    X account, not just the 3rd+.

  - `enterprise_required`: the team has reached the public
    pricing ceiling (2,000 connected accounts). Beyond that
    requires a custom enterprise contract negotiated directly.
    `dashboard_url` deep-links to the enterprise contact page
    rather than the billing tab. The end-user already has a
    card on file; this gate is about contract terms, not card
    collection.

SDK consumers should switch on `reason` to render the right
prompt. For `free_tier_exceeded` and `twitter_passthrough`,
redirect the end-user to `dashboard_url` to add a payment method
via Zernio's hosted Stripe Setup Checkout. For
`enterprise_required`, redirect to `dashboard_url` (the
enterprise contact form) so they can talk to sales.


**Response Body:**

- **error** (required) `string`: 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** (required) `string`: Machine-readable error code. Stable across versions. - one of: PAYMENT_REQUIRED
- **reason** (required) `string`: Discriminator for which gate fired. - one of: free_tier_exceeded, twitter_passthrough, enterprise_required
- **documentation_url** `string` (uri): Link to the relevant documentation page. (example: "https://docs.zernio.com/billing/payment-method-required")
- **dashboard_url** `string` (uri): Deep-link to send the end-user to. For
`free_tier_exceeded` and `twitter_passthrough` this is
the Zernio billing tab. For `enterprise_required` this
is the Zernio enterprise contact page.
 (example: "https://zernio.com/dashboard?tab=billing")
- **details** `object`: Structured context for SDK clients that want to render their own UX. Keys vary by `reason`.
  - **free_tier_account_limit** `integer`: How many accounts the free tier allows. Only set when reason=free_tier_exceeded. (example: 2)
  - **current_account_count** `integer`: How many accounts the team currently has connected. Set when reason=free_tier_exceeded or reason=enterprise_required. (example: 5)
  - **has_payment_method** `boolean`: Whether the team currently has a card on file in Stripe. Set when reason=free_tier_exceeded or reason=twitter_passthrough.
  - **public_account_limit** `integer`: Public pricing ceiling (the published cap beyond which an enterprise contract is required). Only set when reason=enterprise_required. (example: 2000)
  - **effective_account_limit** `integer`: The cap actually applied to this team. Equals
`public_account_limit` for organic teams; for teams
with a per-customer override (grandfathered legacy
customers, signed enterprise contracts) this can
be higher. Only set when reason=enterprise_required.
 (example: 2000)

#### 403: Profile limit exceeded

---


# Related Schema Definitions

## ProfilesListResponse

### Properties

- **profiles** `array`: No description

## Profile

### Properties

- **_id** `string`: No description
- **userId** `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **color** `string`: No description
- **isDefault** `boolean`: No description
- **isOverLimit** `boolean`: Only present when includeOverLimit=true. Indicates if this profile exceeds the plan limit.
- **createdAt** `string`: No description

## ProfileCreateResponse

### Properties

- **message** `string`: No description
- **profile**: No description

---

# Delete profile API Reference

Permanently deletes a profile by ID.

## GET /v1/profiles/{profileId}

**Get profile**

Returns a single profile by ID, including its name, color, and default status.

### Parameters

- **profileId** (required) in path: No description

### Responses

#### 200: Profile

**Response Body:**

- **profile**: `Profile` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PUT /v1/profiles/{profileId}

**Update profile**

Updates a profile's name, description, color, or default status.

### Parameters

- **profileId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **description** `string`: No description
- **color** `string`: No description
- **isDefault** `boolean`: No description

### Responses

#### 200: Updated

**Response Body:**

- **message** `string`: No description
- **profile**: `Profile` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/profiles/{profileId}

**Delete profile**

Permanently deletes a profile by ID.

### Parameters

- **profileId** (required) in path: No description

### Responses

#### 200: Deleted

**Response Body:**

- **message** `string`: No description

#### 400: Has connected accounts

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## Profile

### Properties

- **_id** `string`: No description
- **userId** `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **color** `string`: No description
- **isDefault** `boolean`: No description
- **isOverLimit** `boolean`: Only present when includeOverLimit=true. Indicates if this profile exceeds the plan limit.
- **createdAt** `string`: No description

---

# Get profile API Reference

Returns a single profile by ID, including its name, color, and default status.

## GET /v1/profiles/{profileId}

**Get profile**

Returns a single profile by ID, including its name, color, and default status.

### Parameters

- **profileId** (required) in path: No description

### Responses

#### 200: Profile

**Response Body:**

- **profile**: `Profile` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PUT /v1/profiles/{profileId}

**Update profile**

Updates a profile's name, description, color, or default status.

### Parameters

- **profileId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **description** `string`: No description
- **color** `string`: No description
- **isDefault** `boolean`: No description

### Responses

#### 200: Updated

**Response Body:**

- **message** `string`: No description
- **profile**: `Profile` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/profiles/{profileId}

**Delete profile**

Permanently deletes a profile by ID.

### Parameters

- **profileId** (required) in path: No description

### Responses

#### 200: Deleted

**Response Body:**

- **message** `string`: No description

#### 400: Has connected accounts

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## Profile

### Properties

- **_id** `string`: No description
- **userId** `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **color** `string`: No description
- **isDefault** `boolean`: No description
- **isOverLimit** `boolean`: Only present when includeOverLimit=true. Indicates if this profile exceeds the plan limit.
- **createdAt** `string`: No description

---

# List profiles API Reference

Returns profiles sorted by creation date. Use includeOverLimit=true to include profiles that exceed the plan limit.

## GET /v1/profiles

**List profiles**

Returns profiles sorted by creation date. Use includeOverLimit=true to include profiles that exceed the plan limit.

### Parameters

- **includeOverLimit** (optional) in query: When true, includes over-limit profiles (marked with isOverLimit: true).

### Responses

#### 200: Profiles

**Response Body:**

- **profiles** `array[Profile]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/profiles

**Create profile**

Creates a new profile with a name, optional description, and color.

### Request Body

- **name** (required) `string`: No description
- **description** `string`: No description
- **color** `string`: No description

### Responses

#### 201: Created

**Response Body:**

- **message** `string`: No description
- **profile**: `Profile` - See schema definition

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Payment method or enterprise contract required. The authenticated
account hit a billing gate before the connection could proceed.
Three reasons:

  - `free_tier_exceeded`: the team has connected more accounts
    than the free tier allows. Add a payment method on the
    dashboard to continue (the user will be billed per
    additional connected account).

  - `twitter_passthrough`: connecting an X (Twitter) account
    requires a card on file from day one because X API calls
    incur real per-call pass-through costs. Applies to the 1st
    X account, not just the 3rd+.

  - `enterprise_required`: the team has reached the public
    pricing ceiling (2,000 connected accounts). Beyond that
    requires a custom enterprise contract negotiated directly.
    `dashboard_url` deep-links to the enterprise contact page
    rather than the billing tab. The end-user already has a
    card on file; this gate is about contract terms, not card
    collection.

SDK consumers should switch on `reason` to render the right
prompt. For `free_tier_exceeded` and `twitter_passthrough`,
redirect the end-user to `dashboard_url` to add a payment method
via Zernio's hosted Stripe Setup Checkout. For
`enterprise_required`, redirect to `dashboard_url` (the
enterprise contact form) so they can talk to sales.


**Response Body:**

- **error** (required) `string`: 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** (required) `string`: Machine-readable error code. Stable across versions. - one of: PAYMENT_REQUIRED
- **reason** (required) `string`: Discriminator for which gate fired. - one of: free_tier_exceeded, twitter_passthrough, enterprise_required
- **documentation_url** `string` (uri): Link to the relevant documentation page. (example: "https://docs.zernio.com/billing/payment-method-required")
- **dashboard_url** `string` (uri): Deep-link to send the end-user to. For
`free_tier_exceeded` and `twitter_passthrough` this is
the Zernio billing tab. For `enterprise_required` this
is the Zernio enterprise contact page.
 (example: "https://zernio.com/dashboard?tab=billing")
- **details** `object`: Structured context for SDK clients that want to render their own UX. Keys vary by `reason`.
  - **free_tier_account_limit** `integer`: How many accounts the free tier allows. Only set when reason=free_tier_exceeded. (example: 2)
  - **current_account_count** `integer`: How many accounts the team currently has connected. Set when reason=free_tier_exceeded or reason=enterprise_required. (example: 5)
  - **has_payment_method** `boolean`: Whether the team currently has a card on file in Stripe. Set when reason=free_tier_exceeded or reason=twitter_passthrough.
  - **public_account_limit** `integer`: Public pricing ceiling (the published cap beyond which an enterprise contract is required). Only set when reason=enterprise_required. (example: 2000)
  - **effective_account_limit** `integer`: The cap actually applied to this team. Equals
`public_account_limit` for organic teams; for teams
with a per-customer override (grandfathered legacy
customers, signed enterprise contracts) this can
be higher. Only set when reason=enterprise_required.
 (example: 2000)

#### 403: Profile limit exceeded

---


# Related Schema Definitions

## ProfilesListResponse

### Properties

- **profiles** `array`: No description

## Profile

### Properties

- **_id** `string`: No description
- **userId** `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **color** `string`: No description
- **isDefault** `boolean`: No description
- **isOverLimit** `boolean`: Only present when includeOverLimit=true. Indicates if this profile exceeds the plan limit.
- **createdAt** `string`: No description

## ProfileCreateResponse

### Properties

- **message** `string`: No description
- **profile**: No description

---

# Update profile API Reference

Updates a profile's name, description, color, or default status.

## GET /v1/profiles/{profileId}

**Get profile**

Returns a single profile by ID, including its name, color, and default status.

### Parameters

- **profileId** (required) in path: No description

### Responses

#### 200: Profile

**Response Body:**

- **profile**: `Profile` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PUT /v1/profiles/{profileId}

**Update profile**

Updates a profile's name, description, color, or default status.

### Parameters

- **profileId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **description** `string`: No description
- **color** `string`: No description
- **isDefault** `boolean`: No description

### Responses

#### 200: Updated

**Response Body:**

- **message** `string`: No description
- **profile**: `Profile` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/profiles/{profileId}

**Delete profile**

Permanently deletes a profile by ID.

### Parameters

- **profileId** (required) in path: No description

### Responses

#### 200: Deleted

**Response Body:**

- **message** `string`: No description

#### 400: Has connected accounts

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## Profile

### Properties

- **_id** `string`: No description
- **userId** `string`: No description
- **name** `string`: No description
- **description** `string`: No description
- **color** `string`: No description
- **isDefault** `boolean`: No description
- **isOverLimit** `boolean`: Only present when includeOverLimit=true. Indicates if this profile exceeds the plan limit.
- **createdAt** `string`: No description

---

# Create schedule API Reference

Create an additional queue for a profile. The first queue created becomes the default.
Subsequent queues are non-default unless explicitly set.


## GET /v1/queue/slots

**List schedules**

Returns queue schedules for a profile. Use all=true for all queues, or queueId for a specific one. Defaults to the default queue.

### Parameters

- **profileId** (required) in query: Profile ID to get queues for
- **queueId** (optional) in query: Specific queue ID to retrieve (optional)
- **all** (optional) in query: Set to 'true' to list all queues for the profile

### Responses

#### 200: Queue schedule(s) retrieved

**Response Body:**

*One of the following:*
  - **exists** `boolean`: No description
  - **schedule**: `QueueSchedule` - See schema definition
  - **nextSlots** `array[string]`: 
  - **queues** `array[QueueSchedule]`: 
  - **count** `integer`: No description

#### 400: Missing profileId

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile not found

---

## POST /v1/queue/slots

**Create schedule**

Create an additional queue for a profile. The first queue created becomes the default.
Subsequent queues are non-default unless explicitly set.


### Request Body

- **profileId** (required) `string`: Profile ID
- **name** (required) `string`: Queue name (e.g., Evening Posts)
- **timezone** (required) `string`: IANA timezone
- **slots** (required) `array`: No description
- **active** `boolean`: No description

### Responses

#### 201: Queue created

**Response Body:**

- **success** `boolean`: No description
- **schedule**: `QueueSchedule` - See schema definition
- **nextSlots** `array[string]`: 

#### 400: Invalid request or validation error

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile not found

---

## PUT /v1/queue/slots

**Update schedule**

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.


### Request Body

- **profileId** (required) `string`: No description
- **queueId** `string`: Queue ID to update (optional)
- **name** `string`: Queue name
- **timezone** (required) `string`: No description
- **slots** (required) `array`: No description
- **active** `boolean`: No description
- **setAsDefault** `boolean`: Make this queue the default
- **reshuffleExisting** `boolean`: Whether to reschedule existing queued posts to match new slots

### Responses

#### 200: Queue schedule updated

**Response Body:**

- **success** `boolean`: No description
- **schedule**: `QueueSchedule` - See schema definition
- **nextSlots** `array[string]`: 
- **reshuffledCount** `integer`: No description

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile not found

---

## DELETE /v1/queue/slots

**Delete schedule**

Delete a queue from a profile. Requires queueId to specify which queue to delete.
If deleting the default queue, another queue will be promoted to default.


### Parameters

- **profileId** (required) in query: No description
- **queueId** (required) in query: Queue ID to delete

### Responses

#### 200: Queue schedule deleted

**Response Body:**

- **success** `boolean`: No description
- **deleted** `boolean`: No description

#### 400: Missing profileId or queueId

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## QueueSchedule

### Properties

- **_id** `string`: Unique queue identifier
- **profileId** `string`: Profile ID this queue belongs to
- **name** `string`: Queue name (e.g., "Morning Posts", "Evening Content")
- **timezone** `string`: IANA timezone (e.g., America/New_York)
- **slots** `array`: No description
- **active** `boolean`: Whether the queue is active
- **isDefault** `boolean`: Whether this is the default queue for the profile (used when no queueId specified)
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

---

# Delete schedule API Reference

Delete a queue from a profile. Requires queueId to specify which queue to delete.
If deleting the default queue, another queue will be promoted to default.


## GET /v1/queue/slots

**List schedules**

Returns queue schedules for a profile. Use all=true for all queues, or queueId for a specific one. Defaults to the default queue.

### Parameters

- **profileId** (required) in query: Profile ID to get queues for
- **queueId** (optional) in query: Specific queue ID to retrieve (optional)
- **all** (optional) in query: Set to 'true' to list all queues for the profile

### Responses

#### 200: Queue schedule(s) retrieved

**Response Body:**

*One of the following:*
  - **exists** `boolean`: No description
  - **schedule**: `QueueSchedule` - See schema definition
  - **nextSlots** `array[string]`: 
  - **queues** `array[QueueSchedule]`: 
  - **count** `integer`: No description

#### 400: Missing profileId

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile not found

---

## POST /v1/queue/slots

**Create schedule**

Create an additional queue for a profile. The first queue created becomes the default.
Subsequent queues are non-default unless explicitly set.


### Request Body

- **profileId** (required) `string`: Profile ID
- **name** (required) `string`: Queue name (e.g., Evening Posts)
- **timezone** (required) `string`: IANA timezone
- **slots** (required) `array`: No description
- **active** `boolean`: No description

### Responses

#### 201: Queue created

**Response Body:**

- **success** `boolean`: No description
- **schedule**: `QueueSchedule` - See schema definition
- **nextSlots** `array[string]`: 

#### 400: Invalid request or validation error

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile not found

---

## PUT /v1/queue/slots

**Update schedule**

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.


### Request Body

- **profileId** (required) `string`: No description
- **queueId** `string`: Queue ID to update (optional)
- **name** `string`: Queue name
- **timezone** (required) `string`: No description
- **slots** (required) `array`: No description
- **active** `boolean`: No description
- **setAsDefault** `boolean`: Make this queue the default
- **reshuffleExisting** `boolean`: Whether to reschedule existing queued posts to match new slots

### Responses

#### 200: Queue schedule updated

**Response Body:**

- **success** `boolean`: No description
- **schedule**: `QueueSchedule` - See schema definition
- **nextSlots** `array[string]`: 
- **reshuffledCount** `integer`: No description

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile not found

---

## DELETE /v1/queue/slots

**Delete schedule**

Delete a queue from a profile. Requires queueId to specify which queue to delete.
If deleting the default queue, another queue will be promoted to default.


### Parameters

- **profileId** (required) in query: No description
- **queueId** (required) in query: Queue ID to delete

### Responses

#### 200: Queue schedule deleted

**Response Body:**

- **success** `boolean`: No description
- **deleted** `boolean`: No description

#### 400: Missing profileId or queueId

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## QueueSchedule

### Properties

- **_id** `string`: Unique queue identifier
- **profileId** `string`: Profile ID this queue belongs to
- **name** `string`: Queue name (e.g., "Morning Posts", "Evening Content")
- **timezone** `string`: IANA timezone (e.g., America/New_York)
- **slots** `array`: No description
- **active** `boolean`: Whether the queue is active
- **isDefault** `boolean`: Whether this is the default queue for the profile (used when no queueId specified)
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

---

# Get next available slot API Reference

Returns the next available queue slot for preview purposes. To create a queue post, use POST /v1/posts with queuedFromProfile instead of scheduledFor.

## GET /v1/queue/next-slot

**Get next available slot**

Returns the next available queue slot for preview purposes. To create a queue post, use POST /v1/posts with queuedFromProfile instead of scheduledFor.

### Parameters

- **profileId** (required) in query: No description
- **queueId** (optional) in query: Specific queue ID (optional, defaults to profile's default queue)

### Responses

#### 200: Next available slot

**Response Body:**

- **profileId** `string`: No description
- **nextSlot** `string` (date-time): No description
- **timezone** `string`: No description
- **queueId** `string`: Queue ID this slot belongs to
- **queueName** `string`: Queue name

#### 400: Invalid parameters or inactive queue

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile or queue schedule not found, or no available slots

---

---

# List schedules API Reference

Returns queue schedules for a profile. Use all=true for all queues, or queueId for a specific one. Defaults to the default queue.

## GET /v1/queue/slots

**List schedules**

Returns queue schedules for a profile. Use all=true for all queues, or queueId for a specific one. Defaults to the default queue.

### Parameters

- **profileId** (required) in query: Profile ID to get queues for
- **queueId** (optional) in query: Specific queue ID to retrieve (optional)
- **all** (optional) in query: Set to 'true' to list all queues for the profile

### Responses

#### 200: Queue schedule(s) retrieved

**Response Body:**

*One of the following:*
  - **exists** `boolean`: No description
  - **schedule**: `QueueSchedule` - See schema definition
  - **nextSlots** `array[string]`: 
  - **queues** `array[QueueSchedule]`: 
  - **count** `integer`: No description

#### 400: Missing profileId

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile not found

---

## POST /v1/queue/slots

**Create schedule**

Create an additional queue for a profile. The first queue created becomes the default.
Subsequent queues are non-default unless explicitly set.


### Request Body

- **profileId** (required) `string`: Profile ID
- **name** (required) `string`: Queue name (e.g., Evening Posts)
- **timezone** (required) `string`: IANA timezone
- **slots** (required) `array`: No description
- **active** `boolean`: No description

### Responses

#### 201: Queue created

**Response Body:**

- **success** `boolean`: No description
- **schedule**: `QueueSchedule` - See schema definition
- **nextSlots** `array[string]`: 

#### 400: Invalid request or validation error

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile not found

---

## PUT /v1/queue/slots

**Update schedule**

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.


### Request Body

- **profileId** (required) `string`: No description
- **queueId** `string`: Queue ID to update (optional)
- **name** `string`: Queue name
- **timezone** (required) `string`: No description
- **slots** (required) `array`: No description
- **active** `boolean`: No description
- **setAsDefault** `boolean`: Make this queue the default
- **reshuffleExisting** `boolean`: Whether to reschedule existing queued posts to match new slots

### Responses

#### 200: Queue schedule updated

**Response Body:**

- **success** `boolean`: No description
- **schedule**: `QueueSchedule` - See schema definition
- **nextSlots** `array[string]`: 
- **reshuffledCount** `integer`: No description

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile not found

---

## DELETE /v1/queue/slots

**Delete schedule**

Delete a queue from a profile. Requires queueId to specify which queue to delete.
If deleting the default queue, another queue will be promoted to default.


### Parameters

- **profileId** (required) in query: No description
- **queueId** (required) in query: Queue ID to delete

### Responses

#### 200: Queue schedule deleted

**Response Body:**

- **success** `boolean`: No description
- **deleted** `boolean`: No description

#### 400: Missing profileId or queueId

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## QueueSchedule

### Properties

- **_id** `string`: Unique queue identifier
- **profileId** `string`: Profile ID this queue belongs to
- **name** `string`: Queue name (e.g., "Morning Posts", "Evening Content")
- **timezone** `string`: IANA timezone (e.g., America/New_York)
- **slots** `array`: No description
- **active** `boolean`: Whether the queue is active
- **isDefault** `boolean`: Whether this is the default queue for the profile (used when no queueId specified)
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

---

# Preview upcoming slots API Reference

Returns the next N upcoming queue slot times for a profile as ISO datetime strings.

## GET /v1/queue/preview

**Preview upcoming slots**

Returns the next N upcoming queue slot times for a profile as ISO datetime strings.

### Parameters

- **profileId** (required) in query: No description
- **queueId** (optional) in query: Filter by specific queue ID. Omit to use the default queue.
- **count** (optional) in query: No description

### Responses

#### 200: Queue slots preview

**Response Body:**

- **profileId** `string`: No description
- **count** `integer`: No description
- **slots** `array[string]`: 

#### 400: Invalid parameters

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile or queue schedule not found

---

---

# Update schedule API Reference

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.


## GET /v1/queue/slots

**List schedules**

Returns queue schedules for a profile. Use all=true for all queues, or queueId for a specific one. Defaults to the default queue.

### Parameters

- **profileId** (required) in query: Profile ID to get queues for
- **queueId** (optional) in query: Specific queue ID to retrieve (optional)
- **all** (optional) in query: Set to 'true' to list all queues for the profile

### Responses

#### 200: Queue schedule(s) retrieved

**Response Body:**

*One of the following:*
  - **exists** `boolean`: No description
  - **schedule**: `QueueSchedule` - See schema definition
  - **nextSlots** `array[string]`: 
  - **queues** `array[QueueSchedule]`: 
  - **count** `integer`: No description

#### 400: Missing profileId

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile not found

---

## POST /v1/queue/slots

**Create schedule**

Create an additional queue for a profile. The first queue created becomes the default.
Subsequent queues are non-default unless explicitly set.


### Request Body

- **profileId** (required) `string`: Profile ID
- **name** (required) `string`: Queue name (e.g., Evening Posts)
- **timezone** (required) `string`: IANA timezone
- **slots** (required) `array`: No description
- **active** `boolean`: No description

### Responses

#### 201: Queue created

**Response Body:**

- **success** `boolean`: No description
- **schedule**: `QueueSchedule` - See schema definition
- **nextSlots** `array[string]`: 

#### 400: Invalid request or validation error

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile not found

---

## PUT /v1/queue/slots

**Update schedule**

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.


### Request Body

- **profileId** (required) `string`: No description
- **queueId** `string`: Queue ID to update (optional)
- **name** `string`: Queue name
- **timezone** (required) `string`: No description
- **slots** (required) `array`: No description
- **active** `boolean`: No description
- **setAsDefault** `boolean`: Make this queue the default
- **reshuffleExisting** `boolean`: Whether to reschedule existing queued posts to match new slots

### Responses

#### 200: Queue schedule updated

**Response Body:**

- **success** `boolean`: No description
- **schedule**: `QueueSchedule` - See schema definition
- **nextSlots** `array[string]`: 
- **reshuffledCount** `integer`: No description

#### 400: Invalid request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Profile not found

---

## DELETE /v1/queue/slots

**Delete schedule**

Delete a queue from a profile. Requires queueId to specify which queue to delete.
If deleting the default queue, another queue will be promoted to default.


### Parameters

- **profileId** (required) in query: No description
- **queueId** (required) in query: Queue ID to delete

### Responses

#### 200: Queue schedule deleted

**Response Body:**

- **success** `boolean`: No description
- **deleted** `boolean`: No description

#### 400: Missing profileId or queueId

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## QueueSchedule

### Properties

- **_id** `string`: Unique queue identifier
- **profileId** `string`: Profile ID this queue belongs to
- **name** `string`: Queue name (e.g., "Morning Posts", "Evening Content")
- **timezone** `string`: IANA timezone (e.g., America/New_York)
- **slots** `array`: No description
- **active** `boolean`: Whether the queue is active
- **isDefault** `boolean`: Whether this is the default queue for the profile (used when no queueId specified)
- **createdAt** `string`: No description
- **updatedAt** `string`: No description

---

# Get subreddit feed API Reference

Fetch posts from a subreddit feed. Supports sorting, time filtering, and cursor-based pagination.

## GET /v1/reddit/feed

**Get subreddit feed**

Fetch posts from a subreddit feed. Supports sorting, time filtering, and cursor-based pagination.

### Parameters

- **accountId** (required) in query: No description
- **subreddit** (optional) in query: No description
- **sort** (optional) in query: No description
- **limit** (optional) in query: No description
- **after** (optional) in query: No description
- **t** (optional) in query: No description

### Responses

#### 200: Feed items

**Response Body:**

- **items** `array[RedditPost]`: 
- **after** `string`: No description
- **before** `string`: No description

#### 400: Missing params

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---


# Related Schema Definitions

## RedditPost

A normalized Reddit post returned by the feed and search endpoints

### Properties

- **id** `string`: Reddit post ID (without type prefix)
- **fullname** `string`: Reddit fullname (e.g. t3_abc123)
- **title** `string`: No description
- **author** `string`: No description
- **subreddit** `string`: No description
- **url** `string`: Post URL (may be a gallery URL
- **permalink** `string`: Full permalink to the Reddit post
- **selftext** `string`: Self-post body text (empty string for link posts)
- **createdUtc** `number`: Unix timestamp of post creation
- **score** `integer`: No description
- **numComments** `integer`: No description
- **over18** `boolean`: Whether the post is marked NSFW
- **stickied** `boolean`: No description
- **flairText** `string`: Link flair text if set
- **isGallery** `boolean`: Whether the post is a gallery with multiple images
- **galleryImages** `array`: Individual image URLs for gallery posts (only present when isGallery is true)

---

# Search posts API Reference

Search Reddit posts using a connected account. Optionally scope to a specific subreddit.

## GET /v1/reddit/search

**Search posts**

Search Reddit posts using a connected account. Optionally scope to a specific subreddit.

### Parameters

- **accountId** (required) in query: No description
- **subreddit** (optional) in query: No description
- **q** (required) in query: No description
- **restrict_sr** (optional) in query: No description
- **sort** (optional) in query: No description
- **limit** (optional) in query: No description
- **after** (optional) in query: No description

### Responses

#### 200: Search results

**Response Body:**

- **items** `array[RedditPost]`: 
- **after** `string`: No description
- **before** `string`: No description

#### 400: Missing params

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---


# Related Schema Definitions

## RedditPost

A normalized Reddit post returned by the feed and search endpoints

### Properties

- **id** `string`: Reddit post ID (without type prefix)
- **fullname** `string`: Reddit fullname (e.g. t3_abc123)
- **title** `string`: No description
- **author** `string`: No description
- **subreddit** `string`: No description
- **url** `string`: Post URL (may be a gallery URL
- **permalink** `string`: Full permalink to the Reddit post
- **selftext** `string`: Self-post body text (empty string for link posts)
- **createdUtc** `number`: Unix timestamp of post creation
- **score** `integer`: No description
- **numComments** `integer`: No description
- **over18** `boolean`: Whether the post is marked NSFW
- **stickied** `boolean`: No description
- **flairText** `string`: Link flair text if set
- **isGallery** `boolean`: Whether the post is a gallery with multiple images
- **galleryImages** `array`: Individual image URLs for gallery posts (only present when isGallery is true)

---

# Delete review reply API Reference

Delete a reply to a review (Google Business only). Requires accountId in request body.

## POST /v1/inbox/reviews/{reviewId}/reply

**Reply to review**

Post a reply to a review. Requires accountId in request body.

### Parameters

- **reviewId** (required) in path: Review ID (URL-encoded for Google Business)

### Request Body

- **accountId** (required) `string`: No description
- **message** (required) `string`: No description

### Responses

#### 200: Reply posted

**Response Body:**

- **status** `string`: No description
- **reply** `object`: 
  - **id** `string`: No description
  - **text** `string`: No description
  - **created** `string` (date-time): No description
- **platform** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## DELETE /v1/inbox/reviews/{reviewId}/reply

**Delete review reply**

Delete a reply to a review (Google Business only). Requires accountId in request body.

### Parameters

- **reviewId** (required) in path: No description

### Request Body

- **accountId** (required) `string`: No description

### Responses

#### 200: Reply deleted

**Response Body:**

- **status** `string`: No description
- **message** `string`: No description
- **platform** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# List reviews API Reference

Fetch reviews from all connected Facebook Pages and Google Business accounts. Aggregates data with filtering and sorting options.
Supported platforms: Facebook, Google Business.


## GET /v1/inbox/reviews

**List reviews**

Fetch reviews from all connected Facebook Pages and Google Business accounts. Aggregates data with filtering and sorting options.
Supported platforms: Facebook, Google Business.


### Parameters

- **profileId** (optional) in query: No description
- **platform** (optional) in query: No description
- **minRating** (optional) in query: No description
- **maxRating** (optional) in query: No description
- **hasReply** (optional) in query: Filter by reply status
- **sortBy** (optional) in query: No description
- **sortOrder** (optional) in query: No description
- **limit** (optional) in query: No description
- **cursor** (optional) in query: No description
- **accountId** (optional) in query: Filter by specific social account ID

### Responses

#### 200: Aggregated reviews

**Response Body:**

- **status** `string`: No description
- **data** `array[object]`: 
  - **id** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **accountUsername** `string`: No description
  - **reviewer** `object`: 
    - **id** `string`: No description
    - **name** `string`: No description
    - **profileImage** `string`: No description
  - **rating** `integer`: No description
  - **text** `string`: No description
  - **created** `string` (date-time): No description
  - **hasReply** `boolean`: No description
  - **reply** `object`: 
    - **id** `string`: No description
    - **text** `string`: No description
    - **created** `string` (date-time): No description
  - **reviewUrl** `string`: No description
- **pagination** `object`: 
  - **hasMore** `boolean`: No description
  - **nextCursor** `string`: No description
- **meta** `object`: 
  - **accountsQueried** `integer`: No description
  - **accountsFailed** `integer`: No description
  - **failedAccounts** `array[object]`: 
    - **accountId** `string`: No description
    - **accountUsername** `string`: No description
    - **platform** `string`: No description
    - **error** `string`: No description
    - **code** `string`: Error code if available
    - **retryAfter** `integer`: Seconds to wait before retry (rate limits)
  - **lastUpdated** `string` (date-time): No description
- **summary** `object`: 
  - **totalReviews** `integer`: No description
  - **averageRating** `number`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# Reply to review API Reference

Post a reply to a review. Requires accountId in request body.

## POST /v1/inbox/reviews/{reviewId}/reply

**Reply to review**

Post a reply to a review. Requires accountId in request body.

### Parameters

- **reviewId** (required) in path: Review ID (URL-encoded for Google Business)

### Request Body

- **accountId** (required) `string`: No description
- **message** (required) `string`: No description

### Responses

#### 200: Reply posted

**Response Body:**

- **status** `string`: No description
- **reply** `object`: 
  - **id** `string`: No description
  - **text** `string`: No description
  - **created** `string` (date-time): No description
- **platform** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## DELETE /v1/inbox/reviews/{reviewId}/reply

**Delete review reply**

Delete a reply to a review (Google Business only). Requires accountId in request body.

### Parameters

- **reviewId** (required) in path: No description

### Request Body

- **accountId** (required) `string`: No description

### Responses

#### 200: Reply deleted

**Response Body:**

- **status** `string`: No description
- **message** `string`: No description
- **platform** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# Activate sequence API Reference

Start a draft or paused sequence. The sequence must have at least one step.

## POST /v1/sequences/{sequenceId}/activate

**Activate sequence**

Start a draft or paused sequence. The sequence must have at least one step.

### Parameters

- **sequenceId** (required) in path: No description

### Responses

#### 200: Sequence activated

**Response Body:**

- **success** `boolean`: No description
- **sequence** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description

#### 400: Invalid status or no steps

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Create sequence API Reference

Create a multi-step messaging sequence. Each step has a delay and a message or WhatsApp template.

## GET /v1/sequences

**List sequences**

Returns sequences with enrollment stats. Filter by status, platform, or profile.

### Parameters

- **profileId** (optional) in query: Filter by profile. Omit to list across all profiles
- **status** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Sequences list

**Response Body:**

- **success** `boolean`: No description
- **sequences** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **accountName** `string`: Display name of the sending account
  - **messagePreview** `string`: First step template name or message text snippet
  - **status** `string`: No description - one of: draft, active, paused
  - **stepsCount** `integer`: No description
  - **exitOnReply** `boolean`: No description
  - **exitOnUnsubscribe** `boolean`: No description
  - **totalEnrolled** `integer`: No description
  - **totalCompleted** `integer`: No description
  - **totalExited** `integer`: No description
  - **createdAt** `string` (date-time): No description
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/sequences

**Create sequence**

Create a multi-step messaging sequence. Each step has a delay and a message or WhatsApp template.

### Request Body

- **profileId** (required) `string`: No description
- **accountId** (required) `string`: No description
- **platform** (required) `string`: No description - one of: instagram, facebook, telegram, twitter, bluesky, reddit, whatsapp
- **name** (required) `string`: No description
- **description** `string`: No description
- **steps** `array`: No description
- **exitOnReply** `boolean`: No description
- **exitOnUnsubscribe** `boolean`: No description

### Responses

#### 200: Sequence created

**Response Body:**

- **success** `boolean`: No description
- **sequence** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **status** `string`: No description
  - **stepsCount** `integer`: No description
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Delete sequence API Reference

Permanently delete a sequence. Active enrollments are stopped.

## GET /v1/sequences/{sequenceId}

**Get sequence with steps**

Returns a sequence with all its steps and enrollment stats.

### Parameters

- **sequenceId** (required) in path: No description

### Responses

#### 200: Sequence details with steps

**Response Body:**

- **success** `boolean`: No description
- **sequence** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **status** `string`: No description - one of: draft, active, paused
  - **steps** `array[object]`: 
    - **order** `integer`: No description
    - **delayMinutes** `integer`: No description
    - **message** `object`: 
      - **text** `string`: No description
    - **template** `object`: 
      - **name** `string`: No description
      - **language** `string`: No description
      - **variableMapping** `object`: No description
  - **exitOnReply** `boolean`: No description
  - **exitOnUnsubscribe** `boolean`: No description
  - **totalEnrolled** `integer`: No description
  - **totalCompleted** `integer`: No description
  - **totalExited** `integer`: No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/sequences/{sequenceId}

**Update sequence**

Update a sequence's name, steps, or exit conditions. Steps can only be modified while the sequence is draft or paused.

### Parameters

- **sequenceId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **description** `string`: No description
- **steps** `array`: Replace the full step list. Only allowed while the sequence is draft or paused.
- **exitOnReply** `boolean`: No description
- **exitOnUnsubscribe** `boolean`: No description

### Responses

#### 200: Sequence updated

**Response Body:**

- **success** `boolean`: No description
- **sequence** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **status** `string`: No description
  - **steps** `array[object]`: 
    Type: `object`
  - **exitOnReply** `boolean`: No description
  - **exitOnUnsubscribe** `boolean`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/sequences/{sequenceId}

**Delete sequence**

Permanently delete a sequence. Active enrollments are stopped.

### Parameters

- **sequenceId** (required) in path: No description

### Responses

#### 200: Sequence deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Enroll contacts in a sequence API Reference

Enroll one or more contacts into a sequence. Contacts already enrolled are skipped.

## POST /v1/sequences/{sequenceId}/enroll

**Enroll contacts in a sequence**

Enroll one or more contacts into a sequence. Contacts already enrolled are skipped.

### Parameters

- **sequenceId** (required) in path: No description

### Request Body

- **contactIds** (required) `array`: No description
- **channelIds** `array`: Optional. Auto-detected if not provided.

### Responses

#### 200: Enrollment results

**Response Body:**

- **success** `boolean`: No description
- **enrolled** `integer`: Number of contacts successfully enrolled
- **skipped** `integer`: Number skipped (already enrolled or missing channel)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Get sequence with steps API Reference

Returns a sequence with all its steps and enrollment stats.

## GET /v1/sequences/{sequenceId}

**Get sequence with steps**

Returns a sequence with all its steps and enrollment stats.

### Parameters

- **sequenceId** (required) in path: No description

### Responses

#### 200: Sequence details with steps

**Response Body:**

- **success** `boolean`: No description
- **sequence** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **status** `string`: No description - one of: draft, active, paused
  - **steps** `array[object]`: 
    - **order** `integer`: No description
    - **delayMinutes** `integer`: No description
    - **message** `object`: 
      - **text** `string`: No description
    - **template** `object`: 
      - **name** `string`: No description
      - **language** `string`: No description
      - **variableMapping** `object`: No description
  - **exitOnReply** `boolean`: No description
  - **exitOnUnsubscribe** `boolean`: No description
  - **totalEnrolled** `integer`: No description
  - **totalCompleted** `integer`: No description
  - **totalExited** `integer`: No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/sequences/{sequenceId}

**Update sequence**

Update a sequence's name, steps, or exit conditions. Steps can only be modified while the sequence is draft or paused.

### Parameters

- **sequenceId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **description** `string`: No description
- **steps** `array`: Replace the full step list. Only allowed while the sequence is draft or paused.
- **exitOnReply** `boolean`: No description
- **exitOnUnsubscribe** `boolean`: No description

### Responses

#### 200: Sequence updated

**Response Body:**

- **success** `boolean`: No description
- **sequence** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **status** `string`: No description
  - **steps** `array[object]`: 
    Type: `object`
  - **exitOnReply** `boolean`: No description
  - **exitOnUnsubscribe** `boolean`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/sequences/{sequenceId}

**Delete sequence**

Permanently delete a sequence. Active enrollments are stopped.

### Parameters

- **sequenceId** (required) in path: No description

### Responses

#### 200: Sequence deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List enrollments for a sequence API Reference

Returns enrolled contacts with their progress, status, and next scheduled step.

## GET /v1/sequences/{sequenceId}/enrollments

**List enrollments for a sequence**

Returns enrolled contacts with their progress, status, and next scheduled step.

### Parameters

- **sequenceId** (required) in path: No description
- **status** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Enrollments list with progress

**Response Body:**

- **success** `boolean`: No description
- **enrollments** `array[object]`: 
  - **id** `string`: No description
  - **contactId** `string`: No description
  - **channelId** `string`: No description
  - **platformIdentifier** `string`: No description
  - **contactName** `string`: No description
  - **currentStepIndex** `integer`: No description
  - **status** `string`: No description - one of: active, completed, exited, paused
  - **exitReason** `string`: No description
  - **nextStepAt** `string` (date-time): No description
  - **stepsSent** `integer`: No description
  - **lastStepSentAt** `string` (date-time): No description
  - **createdAt** `string` (date-time): No description
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List sequences API Reference

Returns sequences with enrollment stats. Filter by status, platform, or profile.

## GET /v1/sequences

**List sequences**

Returns sequences with enrollment stats. Filter by status, platform, or profile.

### Parameters

- **profileId** (optional) in query: Filter by profile. Omit to list across all profiles
- **status** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Sequences list

**Response Body:**

- **success** `boolean`: No description
- **sequences** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **accountName** `string`: Display name of the sending account
  - **messagePreview** `string`: First step template name or message text snippet
  - **status** `string`: No description - one of: draft, active, paused
  - **stepsCount** `integer`: No description
  - **exitOnReply** `boolean`: No description
  - **exitOnUnsubscribe** `boolean`: No description
  - **totalEnrolled** `integer`: No description
  - **totalCompleted** `integer`: No description
  - **totalExited** `integer`: No description
  - **createdAt** `string` (date-time): No description
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/sequences

**Create sequence**

Create a multi-step messaging sequence. Each step has a delay and a message or WhatsApp template.

### Request Body

- **profileId** (required) `string`: No description
- **accountId** (required) `string`: No description
- **platform** (required) `string`: No description - one of: instagram, facebook, telegram, twitter, bluesky, reddit, whatsapp
- **name** (required) `string`: No description
- **description** `string`: No description
- **steps** `array`: No description
- **exitOnReply** `boolean`: No description
- **exitOnUnsubscribe** `boolean`: No description

### Responses

#### 200: Sequence created

**Response Body:**

- **success** `boolean`: No description
- **sequence** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **status** `string`: No description
  - **stepsCount** `integer`: No description
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Pause sequence API Reference

Pause an active sequence. Enrolled contacts stop receiving messages until the sequence is reactivated.

## POST /v1/sequences/{sequenceId}/pause

**Pause sequence**

Pause an active sequence. Enrolled contacts stop receiving messages until the sequence is reactivated.

### Parameters

- **sequenceId** (required) in path: No description

### Responses

#### 200: Sequence paused

**Response Body:**

- **success** `boolean`: No description
- **sequence** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description

#### 400: Sequence is not active

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Unenroll contact API Reference

Remove a contact from a sequence. No further messages will be sent to this contact.

## DELETE /v1/sequences/{sequenceId}/enroll/{contactId}

**Unenroll contact**

Remove a contact from a sequence. No further messages will be sent to this contact.

### Parameters

- **sequenceId** (required) in path: No description
- **contactId** (required) in path: No description

### Responses

#### 200: Contact unenrolled

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Update sequence API Reference

Update a sequence's name, steps, or exit conditions. Steps can only be modified while the sequence is draft or paused.

## GET /v1/sequences/{sequenceId}

**Get sequence with steps**

Returns a sequence with all its steps and enrollment stats.

### Parameters

- **sequenceId** (required) in path: No description

### Responses

#### 200: Sequence details with steps

**Response Body:**

- **success** `boolean`: No description
- **sequence** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **status** `string`: No description - one of: draft, active, paused
  - **steps** `array[object]`: 
    - **order** `integer`: No description
    - **delayMinutes** `integer`: No description
    - **message** `object`: 
      - **text** `string`: No description
    - **template** `object`: 
      - **name** `string`: No description
      - **language** `string`: No description
      - **variableMapping** `object`: No description
  - **exitOnReply** `boolean`: No description
  - **exitOnUnsubscribe** `boolean`: No description
  - **totalEnrolled** `integer`: No description
  - **totalCompleted** `integer`: No description
  - **totalExited** `integer`: No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/sequences/{sequenceId}

**Update sequence**

Update a sequence's name, steps, or exit conditions. Steps can only be modified while the sequence is draft or paused.

### Parameters

- **sequenceId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **description** `string`: No description
- **steps** `array`: Replace the full step list. Only allowed while the sequence is draft or paused.
- **exitOnReply** `boolean`: No description
- **exitOnUnsubscribe** `boolean`: No description

### Responses

#### 200: Sequence updated

**Response Body:**

- **success** `boolean`: No description
- **sequence** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **status** `string`: No description
  - **steps** `array[object]`: 
    Type: `object`
  - **exitOnReply** `boolean`: No description
  - **exitOnUnsubscribe** `boolean`: No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/sequences/{sequenceId}

**Delete sequence**

Permanently delete a sequence. Active enrollments are stopped.

### Parameters

- **sequenceId** (required) in path: No description

### Responses

#### 200: Sequence deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Share a tracking tag with an ad account API Reference

Shares the pixel with another ad account so campaigns/audiences in that
account can use it. Requires 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). Meta
only (platform `metaads`); other platforms return 405.


## GET /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts

**List ad accounts a tracking tag is shared with**

Meta only (platform `metaads`); other platforms return 405.

### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.

### Responses

#### 200: Shared ad accounts listed

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **sharedAccounts** `array[SharedAdAccount]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support shared accounts.

---

## POST /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts

**Share a tracking tag with an ad account**

Shares the pixel with another ad account so campaigns/audiences in that
account can use it. Requires 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). Meta
only (platform `metaads`); other platforms return 405.


### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.

### Request Body

- **adAccountId** (required) `string`: Ad account to share with, e.g. `act_123456789`.

### Responses

#### 201: Tracking tag shared with the ad account

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **ok** `boolean`: No description

#### 400: Invalid body / `adAccountId`, or Meta rejected the share (e.g. personal ad account).

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support shared accounts.

---

## DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts

**Stop sharing a tracking tag with an ad account**

`adAccountId` may be passed as a query parameter (recommended) or as a
JSON body field for clients that can send DELETE bodies. Meta only
(platform `metaads`); other platforms return 405.


### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.
- **adAccountId** (optional) in query: Ad account to unshare, e.g. `act_123456789`. May also be sent in the JSON body.

### Responses

#### 204: Ad account unshared (no content).

#### 400: `adAccountId` missing (neither query nor body), or Meta rejected the unshare.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support shared accounts.

---


# Related Schema Definitions

## SharedAdAccount

An ad account a tracking tag is shared with (Meta `shared_accounts` edge).

### Properties

- **id** (required) `string`: Ad account id, in `act_<digits>` form.
- **name** `string`: No description
- **businessId** `string`: Business Manager id that owns the ad account

---

# Create a tracking tag (Meta Pixel) API Reference

Creates a Meta Pixel on the given ad account (`POST /act_{id}/adspixels`
— `name` is the only input). Returns the created tag including its
install `code`. The 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.

Creating a 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`.

NOT idempotent: each call creates a new pixel. Do not retry blindly on
timeout. Meta only (platform `metaads`); other platforms return 405.


## GET /v1/accounts/{accountId}/tracking-tags

**List tracking tags (Meta Pixels)**

Returns the tracking tags (Meta Pixels) the connected ads account can
see. Pass `?adAccountId=act_...` to scope the list to a single ad
account; 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). The list view omits `code` — call `getTrackingTag` for
the install snippet and full detail.

Meta only today (platform `metaads`); other platforms return 405. The
`accountId` must be the Meta *ads* SocialAccount created by the Ads
add-on connect flow, not a Facebook/Instagram posting account. Get your
`act_...` ids from `GET /v1/ads/accounts`.


### Parameters

- **accountId** (required) in path: Meta ads SocialAccount id (platform `metaads`).
- **adAccountId** (optional) in query: Optional. Scope to one ad account, e.g. `act_123456789`.

### Responses

#### 200: Tracking tags listed

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **tags** `array[TrackingTag]`: 

#### 400: Account platform not supported, or invalid `adAccountId`.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account not found or not accessible.

#### 405: Platform does not support listing tracking tags.

---

## POST /v1/accounts/{accountId}/tracking-tags

**Create a tracking tag (Meta Pixel)**

Creates a Meta Pixel on the given ad account (`POST /act_{id}/adspixels`
— `name` is the only input). Returns the created tag including its
install `code`. The 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.

Creating a 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`.

NOT idempotent: each call creates a new pixel. Do not retry blindly on
timeout. Meta only (platform `metaads`); other platforms return 405.


### Parameters

- **accountId** (required) in path: Meta ads SocialAccount id (platform `metaads`).

### Request Body

- **adAccountId** (required) `string`: Meta ad account id, e.g. `act_123456789`.
- **name** (required) `string`: No description

### Responses

#### 201: Tracking tag created

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **tag**: `TrackingTag` - See schema definition

#### 400: Invalid body, invalid `adAccountId`, over the per-business pixel cap, or ad account not in a Business Manager.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account not found or not accessible.

#### 405: Platform does not support creating tracking tags.

---


# Related Schema Definitions

## TrackingTag

A platform measurement tag — the thing you create, install on a
website, send events to, and target ads against. On Meta this is a
Pixel (`kind: pixel`). The shape is platform-neutral so other platforms
(Pinterest Tag, LinkedIn Insight Tag, etc.) can be added without
changing the contract; platform-specific fields are simply absent where
a platform has no equivalent. Returned by `listTrackingTags`,
`createTrackingTag`, `getTrackingTag`, and `updateTrackingTag`.


### Properties

- **id** (required) `string`: Platform-native tag id. Meta: numeric pixel id, as a string.
- **name** (required) `string`: No description
- **platform** (required) `string`: No description - one of: metaads
- **kind** (required) `string`: Platform-native flavor of the tag (Meta: `pixel`). - one of: pixel, tag, insight_tag
- **status** (required) `string`: `inactive` when the platform reports the tag as broken/unavailable. - one of: active, inactive
- **code** `string`: The base-code `<script>` snippet to install on the site. Meta only;
populated by `getTrackingTag`, omitted from the list view.

- **lastFiredTime** `integer`: Unix seconds of the last event the tag received, or `null` if it
never fired. The practical "is it installed and working" signal.

- **isUnavailable** `boolean`: Whether the tag is in a broken/unavailable state (Meta `is_unavailable`).
- **installed** `boolean`: Convenience flag derived from `lastFiredTime` — has the tag ever fired.
- **creationTime** `integer`: Unix seconds the tag was created.
- **ownerBusinessId** `string`: Business Manager id that owns the tag, or `null` when the tag lives
on a personal (non-BM) ad account — such tags can't be shared with
other ad accounts.

- **ownerAdAccountId** `string`: Ad account id (`act_...`) that owns the tag, when reported.

---

# Aggregated event stats for a tracking tag (Meta Pixel) API Reference

Returns aggregated event counts for the pixel (`GET /{pixel_id}/stats`).
Rows are passed through from Meta as-is — their shape depends on the
`aggregation` requested. Meta only (platform `metaads`); other platforms
return 405.


## GET /v1/accounts/{accountId}/tracking-tags/{tagId}/stats

**Aggregated event stats for a tracking tag (Meta Pixel)**

Returns aggregated event counts for the pixel (`GET /{pixel_id}/stats`).
Rows are passed through from Meta as-is — their shape depends on the
`aggregation` requested. Meta only (platform `metaads`); other platforms
return 405.


### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.
- **aggregation** (optional) in query: Aggregation dimension. Defaults to `event`.
- **startTime** (optional) in query: Unix seconds lower bound.
- **endTime** (optional) in query: Unix seconds upper bound.

### Responses

#### 200: Stats fetched

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **stats** `object`: 
  - **aggregation** `string`: No description
  - **startTime** `integer`: No description
  - **endTime** `integer`: No description
  - **rows** `array[object]`: 
    Type: `object` with additional properties

#### 400: Invalid query parameter.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support tracking-tag stats.

---

---

# Fetch a single tracking tag (Meta Pixel) API Reference

Returns the full tag record including the base-code `code` snippet,
`lastFiredTime`, `ownerBusinessId`, `isUnavailable`, etc. Meta only
(platform `metaads`); other platforms return 405.


## GET /v1/accounts/{accountId}/tracking-tags/{tagId}

**Fetch a single tracking tag (Meta Pixel)**

Returns the full tag record including the base-code `code` snippet,
`lastFiredTime`, `ownerBusinessId`, `isUnavailable`, etc. Meta only
(platform `metaads`); other platforms return 405.


### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.

### Responses

#### 200: Tracking tag fetched

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **tag**: `TrackingTag` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support fetching a tracking tag.

---

## PATCH /v1/accounts/{accountId}/tracking-tags/{tagId}

**Update a tracking tag (Meta Pixel)**

Partial-update a pixel. Whitelisted fields: `name` (rename),
`enableAutomaticMatching`, `automaticMatchingFields`,
`firstPartyCookieStatus`, `dataUseSetting`. At least one is required.
Returns the re-fetched canonical tag. Meta only (platform `metaads`);
other platforms return 405.

There 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.


### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.

### Request Body

- **name** `string`: No description
- **enableAutomaticMatching** `boolean`: Meta Advanced Matching toggle (`enable_automatic_matching`).
- **automaticMatchingFields** `array`: Which user fields Advanced Matching may collect. Meta's
terse codes: em=email, ph=phone, fn=first name, ln=last
name, ge=gender, db=date of birth, ct=city, st=state,
zp=zip.

- **firstPartyCookieStatus** `string`: No description - one of: empty, first_party_cookie_disabled, first_party_cookie_enabled
- **dataUseSetting** `string`: No description - one of: advertising_and_analytics, analytics_only, empty

### Responses

#### 200: Tracking tag updated (re-fetched canonical state)

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **tag**: `TrackingTag` - See schema definition

#### 400: Invalid body (e.g. no fields supplied) or Meta validation failure.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support updating tracking tags.

---


# Related Schema Definitions

## TrackingTag

A platform measurement tag — the thing you create, install on a
website, send events to, and target ads against. On Meta this is a
Pixel (`kind: pixel`). The shape is platform-neutral so other platforms
(Pinterest Tag, LinkedIn Insight Tag, etc.) can be added without
changing the contract; platform-specific fields are simply absent where
a platform has no equivalent. Returned by `listTrackingTags`,
`createTrackingTag`, `getTrackingTag`, and `updateTrackingTag`.


### Properties

- **id** (required) `string`: Platform-native tag id. Meta: numeric pixel id, as a string.
- **name** (required) `string`: No description
- **platform** (required) `string`: No description - one of: metaads
- **kind** (required) `string`: Platform-native flavor of the tag (Meta: `pixel`). - one of: pixel, tag, insight_tag
- **status** (required) `string`: `inactive` when the platform reports the tag as broken/unavailable. - one of: active, inactive
- **code** `string`: The base-code `<script>` snippet to install on the site. Meta only;
populated by `getTrackingTag`, omitted from the list view.

- **lastFiredTime** `integer`: Unix seconds of the last event the tag received, or `null` if it
never fired. The practical "is it installed and working" signal.

- **isUnavailable** `boolean`: Whether the tag is in a broken/unavailable state (Meta `is_unavailable`).
- **installed** `boolean`: Convenience flag derived from `lastFiredTime` — has the tag ever fired.
- **creationTime** `integer`: Unix seconds the tag was created.
- **ownerBusinessId** `string`: Business Manager id that owns the tag, or `null` when the tag lives
on a personal (non-BM) ad account — such tags can't be shared with
other ad accounts.

- **ownerAdAccountId** `string`: Ad account id (`act_...`) that owns the tag, when reported.

---

# List ad accounts a tracking tag is shared with API Reference

Meta only (platform `metaads`); other platforms return 405.

## GET /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts

**List ad accounts a tracking tag is shared with**

Meta only (platform `metaads`); other platforms return 405.

### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.

### Responses

#### 200: Shared ad accounts listed

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **sharedAccounts** `array[SharedAdAccount]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support shared accounts.

---

## POST /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts

**Share a tracking tag with an ad account**

Shares the pixel with another ad account so campaigns/audiences in that
account can use it. Requires 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). Meta
only (platform `metaads`); other platforms return 405.


### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.

### Request Body

- **adAccountId** (required) `string`: Ad account to share with, e.g. `act_123456789`.

### Responses

#### 201: Tracking tag shared with the ad account

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **ok** `boolean`: No description

#### 400: Invalid body / `adAccountId`, or Meta rejected the share (e.g. personal ad account).

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support shared accounts.

---

## DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts

**Stop sharing a tracking tag with an ad account**

`adAccountId` may be passed as a query parameter (recommended) or as a
JSON body field for clients that can send DELETE bodies. Meta only
(platform `metaads`); other platforms return 405.


### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.
- **adAccountId** (optional) in query: Ad account to unshare, e.g. `act_123456789`. May also be sent in the JSON body.

### Responses

#### 204: Ad account unshared (no content).

#### 400: `adAccountId` missing (neither query nor body), or Meta rejected the unshare.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support shared accounts.

---


# Related Schema Definitions

## SharedAdAccount

An ad account a tracking tag is shared with (Meta `shared_accounts` edge).

### Properties

- **id** (required) `string`: Ad account id, in `act_<digits>` form.
- **name** `string`: No description
- **businessId** `string`: Business Manager id that owns the ad account

---

# List tracking tags (Meta Pixels) API Reference

Returns the tracking tags (Meta Pixels) the connected ads account can
see. Pass `?adAccountId=act_...` to scope the list to a single ad
account; 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). The list view omits `code` — call `getTrackingTag` for
the install snippet and full detail.

Meta only today (platform `metaads`); other platforms return 405. The
`accountId` must be the Meta *ads* SocialAccount created by the Ads
add-on connect flow, not a Facebook/Instagram posting account. Get your
`act_...` ids from `GET /v1/ads/accounts`.


## GET /v1/accounts/{accountId}/tracking-tags

**List tracking tags (Meta Pixels)**

Returns the tracking tags (Meta Pixels) the connected ads account can
see. Pass `?adAccountId=act_...` to scope the list to a single ad
account; 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). The list view omits `code` — call `getTrackingTag` for
the install snippet and full detail.

Meta only today (platform `metaads`); other platforms return 405. The
`accountId` must be the Meta *ads* SocialAccount created by the Ads
add-on connect flow, not a Facebook/Instagram posting account. Get your
`act_...` ids from `GET /v1/ads/accounts`.


### Parameters

- **accountId** (required) in path: Meta ads SocialAccount id (platform `metaads`).
- **adAccountId** (optional) in query: Optional. Scope to one ad account, e.g. `act_123456789`.

### Responses

#### 200: Tracking tags listed

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **tags** `array[TrackingTag]`: 

#### 400: Account platform not supported, or invalid `adAccountId`.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account not found or not accessible.

#### 405: Platform does not support listing tracking tags.

---

## POST /v1/accounts/{accountId}/tracking-tags

**Create a tracking tag (Meta Pixel)**

Creates a Meta Pixel on the given ad account (`POST /act_{id}/adspixels`
— `name` is the only input). Returns the created tag including its
install `code`. The 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.

Creating a 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`.

NOT idempotent: each call creates a new pixel. Do not retry blindly on
timeout. Meta only (platform `metaads`); other platforms return 405.


### Parameters

- **accountId** (required) in path: Meta ads SocialAccount id (platform `metaads`).

### Request Body

- **adAccountId** (required) `string`: Meta ad account id, e.g. `act_123456789`.
- **name** (required) `string`: No description

### Responses

#### 201: Tracking tag created

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **tag**: `TrackingTag` - See schema definition

#### 400: Invalid body, invalid `adAccountId`, over the per-business pixel cap, or ad account not in a Business Manager.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account not found or not accessible.

#### 405: Platform does not support creating tracking tags.

---


# Related Schema Definitions

## TrackingTag

A platform measurement tag — the thing you create, install on a
website, send events to, and target ads against. On Meta this is a
Pixel (`kind: pixel`). The shape is platform-neutral so other platforms
(Pinterest Tag, LinkedIn Insight Tag, etc.) can be added without
changing the contract; platform-specific fields are simply absent where
a platform has no equivalent. Returned by `listTrackingTags`,
`createTrackingTag`, `getTrackingTag`, and `updateTrackingTag`.


### Properties

- **id** (required) `string`: Platform-native tag id. Meta: numeric pixel id, as a string.
- **name** (required) `string`: No description
- **platform** (required) `string`: No description - one of: metaads
- **kind** (required) `string`: Platform-native flavor of the tag (Meta: `pixel`). - one of: pixel, tag, insight_tag
- **status** (required) `string`: `inactive` when the platform reports the tag as broken/unavailable. - one of: active, inactive
- **code** `string`: The base-code `<script>` snippet to install on the site. Meta only;
populated by `getTrackingTag`, omitted from the list view.

- **lastFiredTime** `integer`: Unix seconds of the last event the tag received, or `null` if it
never fired. The practical "is it installed and working" signal.

- **isUnavailable** `boolean`: Whether the tag is in a broken/unavailable state (Meta `is_unavailable`).
- **installed** `boolean`: Convenience flag derived from `lastFiredTime` — has the tag ever fired.
- **creationTime** `integer`: Unix seconds the tag was created.
- **ownerBusinessId** `string`: Business Manager id that owns the tag, or `null` when the tag lives
on a personal (non-BM) ad account — such tags can't be shared with
other ad accounts.

- **ownerAdAccountId** `string`: Ad account id (`act_...`) that owns the tag, when reported.

---

# Stop sharing a tracking tag with an ad account API Reference

`adAccountId` may be passed as a query parameter (recommended) or as a
JSON body field for clients that can send DELETE bodies. Meta only
(platform `metaads`); other platforms return 405.


## GET /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts

**List ad accounts a tracking tag is shared with**

Meta only (platform `metaads`); other platforms return 405.

### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.

### Responses

#### 200: Shared ad accounts listed

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **sharedAccounts** `array[SharedAdAccount]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support shared accounts.

---

## POST /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts

**Share a tracking tag with an ad account**

Shares the pixel with another ad account so campaigns/audiences in that
account can use it. Requires 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). Meta
only (platform `metaads`); other platforms return 405.


### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.

### Request Body

- **adAccountId** (required) `string`: Ad account to share with, e.g. `act_123456789`.

### Responses

#### 201: Tracking tag shared with the ad account

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **ok** `boolean`: No description

#### 400: Invalid body / `adAccountId`, or Meta rejected the share (e.g. personal ad account).

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support shared accounts.

---

## DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts

**Stop sharing a tracking tag with an ad account**

`adAccountId` may be passed as a query parameter (recommended) or as a
JSON body field for clients that can send DELETE bodies. Meta only
(platform `metaads`); other platforms return 405.


### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.
- **adAccountId** (optional) in query: Ad account to unshare, e.g. `act_123456789`. May also be sent in the JSON body.

### Responses

#### 204: Ad account unshared (no content).

#### 400: `adAccountId` missing (neither query nor body), or Meta rejected the unshare.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support shared accounts.

---


# Related Schema Definitions

## SharedAdAccount

An ad account a tracking tag is shared with (Meta `shared_accounts` edge).

### Properties

- **id** (required) `string`: Ad account id, in `act_<digits>` form.
- **name** `string`: No description
- **businessId** `string`: Business Manager id that owns the ad account

---

# Update a tracking tag (Meta Pixel) API Reference

Partial-update a pixel. Whitelisted fields: `name` (rename),
`enableAutomaticMatching`, `automaticMatchingFields`,
`firstPartyCookieStatus`, `dataUseSetting`. At least one is required.
Returns the re-fetched canonical tag. Meta only (platform `metaads`);
other platforms return 405.

There 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.


## GET /v1/accounts/{accountId}/tracking-tags/{tagId}

**Fetch a single tracking tag (Meta Pixel)**

Returns the full tag record including the base-code `code` snippet,
`lastFiredTime`, `ownerBusinessId`, `isUnavailable`, etc. Meta only
(platform `metaads`); other platforms return 405.


### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.

### Responses

#### 200: Tracking tag fetched

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **tag**: `TrackingTag` - See schema definition

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support fetching a tracking tag.

---

## PATCH /v1/accounts/{accountId}/tracking-tags/{tagId}

**Update a tracking tag (Meta Pixel)**

Partial-update a pixel. Whitelisted fields: `name` (rename),
`enableAutomaticMatching`, `automaticMatchingFields`,
`firstPartyCookieStatus`, `dataUseSetting`. At least one is required.
Returns the re-fetched canonical tag. Meta only (platform `metaads`);
other platforms return 405.

There 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.


### Parameters

- **accountId** (required) in path: No description
- **tagId** (required) in path: Pixel id.

### Request Body

- **name** `string`: No description
- **enableAutomaticMatching** `boolean`: Meta Advanced Matching toggle (`enable_automatic_matching`).
- **automaticMatchingFields** `array`: Which user fields Advanced Matching may collect. Meta's
terse codes: em=email, ph=phone, fn=first name, ln=last
name, ge=gender, db=date of birth, ct=city, st=state,
zp=zip.

- **firstPartyCookieStatus** `string`: No description - one of: empty, first_party_cookie_disabled, first_party_cookie_enabled
- **dataUseSetting** `string`: No description - one of: advertising_and_analytics, analytics_only, empty

### Responses

#### 200: Tracking tag updated (re-fetched canonical state)

**Response Body:**

- **platform** `string`: No description - one of: metaads
- **tag**: `TrackingTag` - See schema definition

#### 400: Invalid body (e.g. no fields supplied) or Meta validation failure.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).

#### 404: Account or tracking tag not found.

#### 405: Platform does not support updating tracking tags.

---


# Related Schema Definitions

## TrackingTag

A platform measurement tag — the thing you create, install on a
website, send events to, and target ads against. On Meta this is a
Pixel (`kind: pixel`). The shape is platform-neutral so other platforms
(Pinterest Tag, LinkedIn Insight Tag, etc.) can be added without
changing the contract; platform-specific fields are simply absent where
a platform has no equivalent. Returned by `listTrackingTags`,
`createTrackingTag`, `getTrackingTag`, and `updateTrackingTag`.


### Properties

- **id** (required) `string`: Platform-native tag id. Meta: numeric pixel id, as a string.
- **name** (required) `string`: No description
- **platform** (required) `string`: No description - one of: metaads
- **kind** (required) `string`: Platform-native flavor of the tag (Meta: `pixel`). - one of: pixel, tag, insight_tag
- **status** (required) `string`: `inactive` when the platform reports the tag as broken/unavailable. - one of: active, inactive
- **code** `string`: The base-code `<script>` snippet to install on the site. Meta only;
populated by `getTrackingTag`, omitted from the list view.

- **lastFiredTime** `integer`: Unix seconds of the last event the tag received, or `null` if it
never fired. The practical "is it installed and working" signal.

- **isUnavailable** `boolean`: Whether the tag is in a broken/unavailable state (Meta `is_unavailable`).
- **installed** `boolean`: Convenience flag derived from `lastFiredTime` — has the tag ever fired.
- **creationTime** `integer`: Unix seconds the tag was created.
- **ownerBusinessId** `string`: Business Manager id that owns the tag, or `null` when the tag lives
on a personal (non-BM) ad account — such tags can't be shared with
other ad accounts.

- **ownerAdAccountId** `string`: Ad account id (`act_...`) that owns the tag, when reported.

---

# Bookmark a tweet API Reference

Bookmark a tweet by ID.
Requires the bookmark.write OAuth scope.
Rate limit: 50 requests per 15-min window.


## POST /v1/twitter/bookmark

**Bookmark a tweet**

Bookmark a tweet by ID.
Requires the bookmark.write OAuth scope.
Rate limit: 50 requests per 15-min window.


### Request Body

- **accountId** (required) `string`: The social account ID
- **tweetId** (required) `string`: The ID of the tweet to bookmark

### Responses

#### 200: Tweet bookmarked

**Response Body:**

- **status** `string`: No description (example: "success")
- **tweetId** `string`: No description
- **bookmarked** `boolean`: No description
- **platform** `string`: No description (example: "twitter")

#### 400: Bad request or platform limitation

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## DELETE /v1/twitter/bookmark

**Remove bookmark**

Remove a bookmark from a tweet.


### Parameters

- **accountId** (required) in query: No description
- **tweetId** (required) in query: The ID of the tweet to unbookmark

### Responses

#### 200: Bookmark removed

**Response Body:**

- **status** `string`: No description (example: "success")
- **tweetId** `string`: No description
- **bookmarked** `boolean`: No description (example: false)
- **platform** `string`: No description (example: "twitter")

#### 400: Bad request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Follow a user API Reference

Follow a user on X/Twitter.
Requires the follows.write OAuth scope.
For protected accounts, a follow request is sent instead (pending_follow will be true).


## POST /v1/twitter/follow

**Follow a user**

Follow a user on X/Twitter.
Requires the follows.write OAuth scope.
For protected accounts, a follow request is sent instead (pending_follow will be true).


### Request Body

- **accountId** (required) `string`: The social account ID
- **targetUserId** (required) `string`: The Twitter ID of the user to follow

### Responses

#### 200: User followed or follow request sent

**Response Body:**

- **status** `string`: No description (example: "success")
- **targetUserId** `string`: No description
- **following** `boolean`: No description
- **pending_follow** `boolean`: True if the target account is protected and a follow request was sent
- **platform** `string`: No description (example: "twitter")

#### 400: Bad request or platform limitation

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## DELETE /v1/twitter/follow

**Unfollow a user**

Unfollow a user on X/Twitter.


### Parameters

- **accountId** (required) in query: No description
- **targetUserId** (required) in query: The Twitter ID of the user to unfollow

### Responses

#### 200: User unfollowed

**Response Body:**

- **status** `string`: No description (example: "success")
- **targetUserId** `string`: No description
- **following** `boolean`: No description (example: false)
- **platform** `string`: No description (example: "twitter")

#### 400: Bad request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Remove bookmark API Reference

Remove a bookmark from a tweet.


## POST /v1/twitter/bookmark

**Bookmark a tweet**

Bookmark a tweet by ID.
Requires the bookmark.write OAuth scope.
Rate limit: 50 requests per 15-min window.


### Request Body

- **accountId** (required) `string`: The social account ID
- **tweetId** (required) `string`: The ID of the tweet to bookmark

### Responses

#### 200: Tweet bookmarked

**Response Body:**

- **status** `string`: No description (example: "success")
- **tweetId** `string`: No description
- **bookmarked** `boolean`: No description
- **platform** `string`: No description (example: "twitter")

#### 400: Bad request or platform limitation

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## DELETE /v1/twitter/bookmark

**Remove bookmark**

Remove a bookmark from a tweet.


### Parameters

- **accountId** (required) in query: No description
- **tweetId** (required) in query: The ID of the tweet to unbookmark

### Responses

#### 200: Bookmark removed

**Response Body:**

- **status** `string`: No description (example: "success")
- **tweetId** `string`: No description
- **bookmarked** `boolean`: No description (example: false)
- **platform** `string`: No description (example: "twitter")

#### 400: Bad request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Retweet a post API Reference

Retweet (repost) a tweet by ID.
Rate limit: 50 requests per 15-min window. Shares the 300/3hr creation limit with tweet creation.


## POST /v1/twitter/retweet

**Retweet a post**

Retweet (repost) a tweet by ID.
Rate limit: 50 requests per 15-min window. Shares the 300/3hr creation limit with tweet creation.


### Request Body

- **accountId** (required) `string`: The social account ID
- **tweetId** (required) `string`: The ID of the tweet to retweet

### Responses

#### 200: Tweet retweeted

**Response Body:**

- **status** `string`: No description (example: "success")
- **tweetId** `string`: No description
- **retweeted** `boolean`: No description
- **platform** `string`: No description (example: "twitter")

#### 400: Bad request or platform limitation

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## DELETE /v1/twitter/retweet

**Undo retweet**

Undo a retweet (un-repost a tweet).


### Parameters

- **accountId** (required) in query: No description
- **tweetId** (required) in query: The ID of the original tweet to un-retweet

### Responses

#### 200: Retweet undone

**Response Body:**

- **status** `string`: No description (example: "success")
- **tweetId** `string`: No description
- **retweeted** `boolean`: No description (example: false)
- **platform** `string`: No description (example: "twitter")

#### 400: Bad request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Undo retweet API Reference

Undo a retweet (un-repost a tweet).


## POST /v1/twitter/retweet

**Retweet a post**

Retweet (repost) a tweet by ID.
Rate limit: 50 requests per 15-min window. Shares the 300/3hr creation limit with tweet creation.


### Request Body

- **accountId** (required) `string`: The social account ID
- **tweetId** (required) `string`: The ID of the tweet to retweet

### Responses

#### 200: Tweet retweeted

**Response Body:**

- **status** `string`: No description (example: "success")
- **tweetId** `string`: No description
- **retweeted** `boolean`: No description
- **platform** `string`: No description (example: "twitter")

#### 400: Bad request or platform limitation

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## DELETE /v1/twitter/retweet

**Undo retweet**

Undo a retweet (un-repost a tweet).


### Parameters

- **accountId** (required) in query: No description
- **tweetId** (required) in query: The ID of the original tweet to un-retweet

### Responses

#### 200: Retweet undone

**Response Body:**

- **status** `string`: No description (example: "success")
- **tweetId** `string`: No description
- **retweeted** `boolean`: No description (example: false)
- **platform** `string`: No description (example: "twitter")

#### 400: Bad request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Unfollow a user API Reference

Unfollow a user on X/Twitter.


## POST /v1/twitter/follow

**Follow a user**

Follow a user on X/Twitter.
Requires the follows.write OAuth scope.
For protected accounts, a follow request is sent instead (pending_follow will be true).


### Request Body

- **accountId** (required) `string`: The social account ID
- **targetUserId** (required) `string`: The Twitter ID of the user to follow

### Responses

#### 200: User followed or follow request sent

**Response Body:**

- **status** `string`: No description (example: "success")
- **targetUserId** `string`: No description
- **following** `boolean`: No description
- **pending_follow** `boolean`: True if the target account is protected and a follow request was sent
- **platform** `string`: No description (example: "twitter")

#### 400: Bad request or platform limitation

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

## DELETE /v1/twitter/follow

**Unfollow a user**

Unfollow a user on X/Twitter.


### Parameters

- **accountId** (required) in query: No description
- **targetUserId** (required) in query: The Twitter ID of the user to unfollow

### Responses

#### 200: User unfollowed

**Response Body:**

- **status** `string`: No description (example: "success")
- **targetUserId** `string`: No description
- **following** `boolean`: No description (example: false)
- **platform** `string`: No description (example: "twitter")

#### 400: Bad request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Account not found

---

---

# Get plan and usage stats API Reference

Returns the current plan name, billing period, plan limits, and usage counts.

The response shape depends on the account's `billingSystem`:
  * Stripe users: per-period `usage.uploads` / `usage.profiles` counters.
  * Metronome (usage-based) 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`. The legacy `usage.xApiCalls` 3-tier
    aggregate is still emitted for back-compat but excludes the
    $0.200 URL tier and any future tiers — new clients should
    consume `xApiCallsByOperation` only.


## GET /v1/usage-stats

**Get plan and usage stats**

Returns the current plan name, billing period, plan limits, and usage counts.

The response shape depends on the account's `billingSystem`:
  * Stripe users: per-period `usage.uploads` / `usage.profiles` counters.
  * Metronome (usage-based) 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`. The legacy `usage.xApiCalls` 3-tier
    aggregate is still emitted for back-compat but excludes the
    $0.200 URL tier and any future tiers — new clients should
    consume `xApiCallsByOperation` only.


### Parameters

- **reconcile** (optional) in query: For Stripe subscription users, `true` forces a subscription
reconciliation pass even when cached plan data looks complete.
Omit the parameter, or pass `false`, to use the default
first-time-only reconciliation behavior. Invalid boolean values are
rejected.


### Responses

#### 200: Usage stats

**Response Body:**

- **billingSystem** `string`: Which billing system the account is on. Shape of `usage`/`spend` differs. - one of: stripe, metronome
- **planName** `string`: No description
- **billingPeriod** `string`: No description - one of: monthly, yearly
- **signupDate** `string` (date-time): No description
- **billingAnchorDay** `integer`: Day of month (1-31) when the billing cycle resets
- **hasAccess** `boolean`: True if the account is in good standing. False for past-due/unpaid/paused subscriptions.
- **customerId** `string`: Stripe customer ID, when present.
- **isInvitedUser** `boolean`: True if this is a team member; limits/usage reflect the account owner.
- **autoUpgradeEnabled** `boolean`: Stripe-only. Always false for Metronome users.
- **limits** `object`: Plan limits. For Metronome users both fields are `-1` (unlimited).
  - **uploads** `integer`: No description
  - **profiles** `integer`: No description
- **usage** `object`: Per-period usage counts. Fields present depend on `billingSystem`:
Stripe returns `uploads` / `profiles` / `lastReset`;
Metronome returns `connectedAccounts` / `xApiCalls` / `xApiCallsByOperation`.

  - **uploads** `integer`: Stripe users only. Uploads consumed in the current period.
  - **profiles** `integer`: Stripe users only. Profiles currently owned.
  - **lastReset** `string` (date-time): Stripe users only.
  - **connectedAccounts** `integer`: Metronome users only. Accounts currently connected across the team.
  - **xApiCalls** `object`: **Deprecated.** Legacy 3-tier aggregate. Operations outside the
three historical prices ($0.005/$0.010/$0.015) — notably the
$0.200 "Posts with URL" tier added April 2026 — are silently
excluded from this shape. Use `xApiCallsByOperation` instead;
it captures every tier and is the source of truth for
per-operation call counts.

    - **x_api_005** `integer`: Calls at $0.005 per call (reads, lists, bookmarks, content manage, etc.)
    - **x_api_010** `integer`: Calls at $0.010 per call (user reads, DM reads, follow reads, trends, list create, privacy update)
    - **x_api_015** `integer`: Calls at $0.015 per call (posts/replies, DM sends, user interactions)
  - **xApiCallsByOperation** `object`: Metronome users only. Per-operation X API call counts keyed by
operation (e.g. `posts_read`, `content_create`,
`content_create_with_url`). Resolve each key to price and metadata
via `GET /v1/billing/x-pricing`. This is the canonical source —
covers every price tier including the $0.200 URL tier that
`xApiCalls` excludes.
 (example: {"posts_read":42,"content_create":7,"content_create_with_url":3,"dm_interaction_create":1})
- **spend** `object`: Metronome users only. Current-period spend summary.
  - **currentPeriodCents** `integer`: Total current-period spend in cents (all products combined).
  - **creditsRemainingCents** `integer`: Free-tier credit remaining in cents. Applied before any charge.
  - **xSpendCents** `integer`: Current-period X/Twitter API spend in cents, summed from
`xApiCallsByOperation` × per-operation prices. Tier-agnostic
(covers every price including the $0.200 URL tier). Rounded
up for conservative enforcement against `xSpendLimitCents`.

  - **xSpendLimitCents** `integer`: Monthly X spend cap set by the account owner, or null if no cap.
When current X spend hits this cap, analytics and inbox sync are
auto-paused for X accounts. Publishing is never blocked by this cap.


#### 400: Invalid query parameter

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## UsageStats

Plan and usage stats. The response shape depends on `billingSystem`:
  * Stripe users (default): per-period counters like `usage.uploads` and
    `usage.profiles` are returned, scoped by the plan's `limits`.
  * Metronome users (usage-based): `limits` are unlimited (-1). The
    `usage` block carries connected-account and per-X-operation counts,
    and the `spend` block carries current-period costs plus the X cap.


### Properties

- **billingSystem** `string`: Which billing system the account is on. Shape of `usage`/`spend` differs. - one of: stripe, metronome
- **planName** `string`: No description
- **billingPeriod** `string`: No description - one of: monthly, yearly
- **signupDate** `string`: No description
- **billingAnchorDay** `integer`: Day of month (1-31) when the billing cycle resets
- **hasAccess** `boolean`: True if the account is in good standing. False for past-due/unpaid/paused subscriptions.
- **customerId** `string`: Stripe customer ID, when present.
- **isInvitedUser** `boolean`: True if this is a team member; limits/usage reflect the account owner.
- **autoUpgradeEnabled** `boolean`: Stripe-only. Always false for Metronome users.
- **limits** `object`: Plan limits. For Metronome users both fields are `-1` (unlimited).
  - **uploads** `integer`: 
  - **profiles** `integer`: 
- **usage** `object`: Per-period usage counts. Fields present depend on `billingSystem`:
Stripe returns `uploads` / `profiles` / `lastReset`;
Metronome returns `connectedAccounts` / `xApiCalls` / `xApiCallsByOperation`.

  - **uploads** `integer`: Stripe users only. Uploads consumed in the current period.
  - **profiles** `integer`: Stripe users only. Profiles currently owned.
  - **lastReset** `string`: Stripe users only.
  - **connectedAccounts** `integer`: Metronome users only. Accounts currently connected across the team.
  - **xApiCalls** `object`: **Deprecated.** Legacy 3-tier aggregate. Operations outside the
three historical prices ($0.005/$0.010/$0.015) — notably the
$0.200 "Posts with URL" tier added April 2026 — are silently
excluded from this shape. Use `xApiCallsByOperation` instead;
it captures every tier and is the source of truth for
per-operation call counts.

  - **xApiCallsByOperation** `object`: Metronome users only. Per-operation X API call counts keyed by
operation (e.g. `posts_read`, `content_create`,
`content_create_with_url`). Resolve each key to price and metadata
via `GET /v1/billing/x-pricing`. This is the canonical source —
covers every price tier including the $0.200 URL tier that
`xApiCalls` excludes.

- **spend** `object`: Metronome users only. Current-period spend summary.
  - **currentPeriodCents** `integer`: Total current-period spend in cents (all products combined).
  - **creditsRemainingCents** `integer`: Free-tier credit remaining in cents. Applied before any charge.
  - **xSpendCents** `integer`: Current-period X/Twitter API spend in cents, summed from
`xApiCallsByOperation` × per-operation prices. Tier-agnostic
(covers every price including the $0.200 URL tier). Rounded
up for conservative enforcement against `xSpendLimitCents`.

  - **xSpendLimitCents** `integer`: Monthly X spend cap set by the account owner, or null if no cap.
When current X spend hits this cap, analytics and inbox sync are
auto-paused for X accounts. Publishing is never blocked by this cap.

---

# Get X/Twitter API pricing table API Reference

Returns Zernio's canonical X/Twitter API pricing table. Each X action has its
own Metronome product and its own rate, and Zernio passes X API costs through
at exact rates with zero markup.

The response is identical for every authenticated user (pricing is universal),
so it is safe to cache on the client for the duration of a billing period.

To compute your own per-operation spend, pair this endpoint with
`GET /v1/usage-stats` — that endpoint returns `usage.xApiCallsByOperation`
keyed by the same `operation` field you get here.


## GET /v1/billing/x-pricing

**Get X/Twitter API pricing table**

Returns Zernio's canonical X/Twitter API pricing table. Each X action has its
own Metronome product and its own rate, and Zernio passes X API costs through
at exact rates with zero markup.

The response is identical for every authenticated user (pricing is universal),
so it is safe to cache on the client for the duration of a billing period.

To compute your own per-operation spend, pair this endpoint with
`GET /v1/usage-stats` — that endpoint returns `usage.xApiCallsByOperation`
keyed by the same `operation` field you get here.


### Responses

#### 200: X pricing table

**Response Body:**

- **currency** `string`: No description (example: "USD")
- **markup** `string`: Always 0% — Zernio does not mark up X API rates. (example: "0%")
- **source** `string` (uri): No description (example: "https://developer.x.com/#pricing")
- **lastVerified** `string` (date): Date the prices were last verified against X's published rates.
- **tiers** `array[object]`: Rollup of operations grouped by their per-call price.
  - **tier** `string`: Tier key derived from price (e.g. `x_api_005` for $0.005,
`x_api_200` for $0.200). The first three keys map to the
legacy `xApiCalls` aggregate; new tiers (e.g. `x_api_200`
for the URL tier added April 2026) are surfaced here but
not in the legacy shape.
 (example: "x_api_005")
  - **pricePerCallUsd** `number`: No description (example: 0.005)
  - **operationCount** `integer`: No description (example: 13)
- **operations** `array[XApiOperation]`: Flat list of every X operation Zernio can perform, with its rate.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## XApiPricing

Canonical X/Twitter API pricing table. Zernio passes X API costs through
at exact rates with zero markup, so every call you make has a known per-unit
price. Use this payload alongside `/v1/usage-stats` (which returns
per-operation call counts via `xApiCallsByOperation`) to compute exact
cost attribution by X action.


### Properties

- **currency** `string`: No description
- **markup** `string`: Always 0% — Zernio does not mark up X API rates.
- **source** `string`: No description
- **lastVerified** `string`: Date the prices were last verified against X's published rates.
- **tiers** `array`: Rollup of operations grouped by their per-call price.
- **operations** `array`: Flat list of every X operation Zernio can perform, with its rate.

## XApiOperation

A single X API operation with its per-call price and the Zernio platform methods that trigger it.

### Properties

- **operation** `string`: Internal operation key. Matches keys in `xApiCallsByOperation`.
- **eventType** `string`: Metronome `event_type` emitted when this operation runs.
- **displayName** `string`: Human-readable label shown on Metronome invoices.
- **pricePerCallUsd** `number`: No description
- **pricePerCallCents** `number`: Per-call price in cents. Fractional values are intentional.
- **tier** `string`: Tier key derived from `pricePerCallUsd` (e.g. `x_api_005` for
$0.005, `x_api_200` for $0.200). Useful for grouping operations
by price in dashboards.

- **triggeredBy** `array`: Zernio platform methods that emit this operation, with their metering rule.

---

# Get user API Reference

Returns a single user's details by ID, including name, email, and role.

## GET /v1/users/{userId}

**Get user**

Returns a single user's details by ID, including name, email, and role.

### Parameters

- **userId** (required) in path: No description

### Responses

#### 200: User

**Response Body:**

- **user** `object`: 
  - **_id** `string`: No description
  - **name** `string`: No description
  - **email** `string`: No description
  - **role** `string`: No description
  - **isRoot** `boolean`: No description
  - **profileAccess** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Forbidden

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List users API Reference

Returns all users in the workspace including roles and profile access. Also returns the currentUserId of the caller.

## GET /v1/users

**List users**

Returns all users in the workspace including roles and profile access. Also returns the currentUserId of the caller.

### Responses

#### 200: Users

**Response Body:**

- **currentUserId** `string`: No description
- **users** `array[object]`: 
  - **_id** `string`: No description
  - **name** `string`: No description
  - **email** `string`: No description
  - **role** `string`: No description
  - **isRoot** `boolean`: No description
  - **profileAccess** `array[string]`: 
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Validate media URL API Reference

Check if a media URL is accessible and return metadata (content type, file size) plus per-platform size limit comparisons.

Performs a HEAD request (with GET fallback) to detect content type and size. Rejects private/localhost URLs for SSRF protection.

Platform limits are sourced from each platform's actual upload constraints.


## POST /v1/tools/validate/media

**Validate media URL**

Check if a media URL is accessible and return metadata (content type, file size) plus per-platform size limit comparisons.

Performs a HEAD request (with GET fallback) to detect content type and size. Rejects private/localhost URLs for SSRF protection.

Platform limits are sourced from each platform's actual upload constraints.


### Request Body

- **url** (required) `string`: Public media URL to validate

### Responses

#### 200: Media validation result

**Response Body:**

- **valid** `boolean`: No description
- **url** `string` (uri): No description
- **error** `string`: Error message if valid is false
- **contentType** `string`: No description (example: "image/jpeg")
- **size** `integer`: File size in bytes
- **sizeFormatted** `string`: No description (example: "245 KB")
- **type** `string`: No description - one of: image, video, unknown
- **platformLimits** `object`: Per-platform size limit comparison (only present when size and type are known) (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}})

---

---

# Validate character count API Reference

Check weighted character count per platform and whether the text is within each platform's limit.

Twitter/X uses weighted counting (URLs = 23 chars via t.co, emojis = 2 chars). All other platforms use plain character length.

Returns counts and limits for all 15 supported platform variants.


## POST /v1/tools/validate/post-length

**Validate character count**

Check weighted character count per platform and whether the text is within each platform's limit.

Twitter/X uses weighted counting (URLs = 23 chars via t.co, emojis = 2 chars). All other platforms use plain character length.

Returns counts and limits for all 15 supported platform variants.


### Request Body

- **text** (required) `string`: The post text to check

### Responses

#### 200: Character counts per platform

**Response Body:**

- **text** `string`: No description
- **platforms** `object`: No description (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}})

---

---

# Validate post content API Reference

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.

Accepts the same body as POST /v1/posts. Does NOT validate accounts, process media, or track usage. This is content-only validation.

Returns errors for failures and warnings for near-limit content (>90% of character limit).


## POST /v1/tools/validate/post

**Validate post content**

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.

Accepts the same body as POST /v1/posts. Does NOT validate accounts, process media, or track usage. This is content-only validation.

Returns errors for failures and warnings for near-limit content (>90% of character limit).


### Request Body

- **content** `string`: Post text content
- **platforms** (required) `array`: Target platforms (same format as POST /v1/posts)
- **mediaItems** `array`: Root media items shared across platforms

### Responses

#### 200: Validation result

**Response Body:**

*One of the following:*
  - **valid** `boolean`: No description
  - **message** `string`: No description (example: "No validation issues found.")
  - **warnings** `array[object]`: 
    - **platform** `string`: No description
    - **warning** `string`: No description
  - **valid** `boolean`: No description
  - **errors** `array[object]`: 
    - **platform** `string`: No description
    - **error** `string`: No description
  - **warnings** `array[object]`: 
    - **platform** `string`: No description
    - **warning** `string`: No description

---

---

# Check subreddit existence API Reference

Check if a subreddit exists and return basic info (title, subscriber count, NSFW status, post types allowed).

When 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.


## GET /v1/tools/validate/subreddit

**Check subreddit existence**

Check if a subreddit exists and return basic info (title, subscriber count, NSFW status, post types allowed).

When 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.


### Parameters

- **name** (required) in query: Subreddit name (with or without "r/" prefix)
- **accountId** (optional) in query: Reddit social account ID for authenticated lookup (recommended for reliable results)

### Responses

#### 200: Subreddit lookup result

**Response Body:**

*One of the following:*
  - **exists** `boolean`: No description
  - **subreddit** `object`: 
    - **name** `string`: No description (example: "programming")
    - **title** `string`: No description (example: "programming")
    - **description** `string`: No description (example: "Computer Programming")
    - **subscribers** `integer`: No description (example: 6844284)
    - **isNSFW** `boolean`: No description
    - **type** `string`: No description - one of: public, private, restricted (example: "public")
    - **allowImages** `boolean`: No description
    - **allowVideos** `boolean`: No description
  - **exists** `boolean`: No description
  - **error** `string`: No description

---

---

# Create webhook API Reference

Create a new webhook configuration. Maximum 10 webhooks per user.

`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.

Webhooks are automatically disabled after 10 consecutive delivery failures.


## GET /v1/webhooks/settings

**List webhooks**

Retrieve all configured webhooks for the authenticated user. Supports up to 10 webhooks per user.

### Responses

#### 200: Webhooks retrieved successfully

**Response Body:**

- **webhooks** `array[Webhook]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/webhooks/settings

**Create webhook**

Create a new webhook configuration. Maximum 10 webhooks per user.

`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.

Webhooks are automatically disabled after 10 consecutive delivery failures.


### Request Body

- **name** (required) `string`: Webhook name (1-50 characters)
- **url** (required) `string`: Webhook endpoint URL (must be a valid URL, whitespace trimmed)
- **secret** `string`: Secret key for HMAC-SHA256 signature verification
- **events** (required) `array`: Events to subscribe to (at least one required)
- **isActive** `boolean`: Enable or disable webhook delivery. Defaults to `true` when omitted.
- **customHeaders** `object`: Custom headers to include in webhook requests

### Responses

#### 200: Webhook created successfully

**Response Body:**

- **success** `boolean`: No description
- **webhook**: `Webhook` - See schema definition

#### 400: Validation error or maximum webhooks reached

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/webhooks/settings

**Update webhook**

Update an existing webhook configuration. All fields except `_id` are optional; only provided fields will be updated.

When provided, `name` must be 1-50 characters, `url` must be a valid URL, and `events` must contain at least one event. Whitespace is trimmed from `url` before validation.

Webhooks are automatically disabled after 10 consecutive delivery failures.


### Request Body

- **_id** (required) `string`: Webhook ID to update (required)
- **name** `string`: Webhook name (1-50 characters). Must be non-empty if provided.
- **url** `string`: Webhook endpoint URL (must be a valid URL, whitespace trimmed). Must be a valid URL if provided.
- **secret** `string`: Secret key for HMAC-SHA256 signature verification
- **events** `array`: Events to subscribe to. Must contain at least one event if provided.
- **isActive** `boolean`: Enable or disable webhook delivery
- **customHeaders** `object`: Custom headers to include in webhook requests

### Responses

#### 200: Webhook updated successfully

**Response Body:**

- **success** `boolean`: No description
- **webhook**: `Webhook` - See schema definition

#### 400: Validation error or missing webhook ID

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Webhook not found

---

## DELETE /v1/webhooks/settings

**Delete webhook**

Permanently delete a webhook configuration.

### Parameters

- **id** (required) in query: Webhook ID to delete

### Responses

#### 200: Webhook deleted successfully

**Response Body:**

- **success** `boolean`: No description

#### 400: Webhook ID required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## Webhook

Individual webhook configuration for receiving real-time notifications

### Properties

- **_id** `string`: Unique webhook identifier
- **name** `string`: Webhook name (for identification) (max: 50)
- **url** `string`: Webhook endpoint URL
- **secret** `string`: Secret key for HMAC-SHA256 signature verification.
- **events** `array`: Events subscribed to
- **isActive** `boolean`: Whether webhook delivery is enabled
- **lastFiredAt** `string`: Timestamp of last successful webhook delivery
- **failureCount** `integer`: Consecutive delivery failures (resets on success, webhook disabled at 10)
- **customHeaders** `object`: Custom headers included in webhook requests

---

# Delete webhook API Reference

Permanently delete a webhook configuration.

## GET /v1/webhooks/settings

**List webhooks**

Retrieve all configured webhooks for the authenticated user. Supports up to 10 webhooks per user.

### Responses

#### 200: Webhooks retrieved successfully

**Response Body:**

- **webhooks** `array[Webhook]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/webhooks/settings

**Create webhook**

Create a new webhook configuration. Maximum 10 webhooks per user.

`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.

Webhooks are automatically disabled after 10 consecutive delivery failures.


### Request Body

- **name** (required) `string`: Webhook name (1-50 characters)
- **url** (required) `string`: Webhook endpoint URL (must be a valid URL, whitespace trimmed)
- **secret** `string`: Secret key for HMAC-SHA256 signature verification
- **events** (required) `array`: Events to subscribe to (at least one required)
- **isActive** `boolean`: Enable or disable webhook delivery. Defaults to `true` when omitted.
- **customHeaders** `object`: Custom headers to include in webhook requests

### Responses

#### 200: Webhook created successfully

**Response Body:**

- **success** `boolean`: No description
- **webhook**: `Webhook` - See schema definition

#### 400: Validation error or maximum webhooks reached

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/webhooks/settings

**Update webhook**

Update an existing webhook configuration. All fields except `_id` are optional; only provided fields will be updated.

When provided, `name` must be 1-50 characters, `url` must be a valid URL, and `events` must contain at least one event. Whitespace is trimmed from `url` before validation.

Webhooks are automatically disabled after 10 consecutive delivery failures.


### Request Body

- **_id** (required) `string`: Webhook ID to update (required)
- **name** `string`: Webhook name (1-50 characters). Must be non-empty if provided.
- **url** `string`: Webhook endpoint URL (must be a valid URL, whitespace trimmed). Must be a valid URL if provided.
- **secret** `string`: Secret key for HMAC-SHA256 signature verification
- **events** `array`: Events to subscribe to. Must contain at least one event if provided.
- **isActive** `boolean`: Enable or disable webhook delivery
- **customHeaders** `object`: Custom headers to include in webhook requests

### Responses

#### 200: Webhook updated successfully

**Response Body:**

- **success** `boolean`: No description
- **webhook**: `Webhook` - See schema definition

#### 400: Validation error or missing webhook ID

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Webhook not found

---

## DELETE /v1/webhooks/settings

**Delete webhook**

Permanently delete a webhook configuration.

### Parameters

- **id** (required) in query: Webhook ID to delete

### Responses

#### 200: Webhook deleted successfully

**Response Body:**

- **success** `boolean`: No description

#### 400: Webhook ID required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## Webhook

Individual webhook configuration for receiving real-time notifications

### Properties

- **_id** `string`: Unique webhook identifier
- **name** `string`: Webhook name (for identification) (max: 50)
- **url** `string`: Webhook endpoint URL
- **secret** `string`: Secret key for HMAC-SHA256 signature verification.
- **events** `array`: Events subscribed to
- **isActive** `boolean`: Whether webhook delivery is enabled
- **lastFiredAt** `string`: Timestamp of last successful webhook delivery
- **failureCount** `integer`: Consecutive delivery failures (resets on success, webhook disabled at 10)
- **customHeaders** `object`: Custom headers included in webhook requests

---

# List webhook delivery logs API Reference

Retrieve recorded webhook delivery attempts for the authenticated user, most recent first.
Logs are retained for 30 days. Supports filtering by status, event type, webhook ID, and event ID,
plus offset-based pagination.


## GET /v1/webhooks/logs

**List webhook delivery logs**

Retrieve recorded webhook delivery attempts for the authenticated user, most recent first.
Logs are retained for 30 days. Supports filtering by status, event type, webhook ID, and event ID,
plus offset-based pagination.


### Parameters

- **limit** (optional) in query: Maximum number of logs to return
- **skip** (optional) in query: Number of logs to skip (offset-based pagination)
- **status** (optional) in query: Filter by delivery outcome
- **event** (optional) in query: Filter by event type (e.g. post.published)
- **webhookId** (optional) in query: Filter by webhook configuration ID
- **eventId** (optional) in query: Filter by stable webhook event ID

### Responses

#### 200: Webhook logs retrieved successfully

**Response Body:**

- **logs** `array[WebhookLog]`: 
- **pagination** `object`: 
  - **total** `integer`: Total number of matching logs
  - **limit** `integer`: Maximum number of logs returned per page
  - **skip** `integer`: Number of logs skipped
  - **pages** `integer`: Total number of pages
  - **hasMore** `boolean`: Whether more logs are available beyond this page

#### 400: Invalid query parameter

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## WebhookLog

A single webhook delivery attempt recorded by Zernio (30-day retention).

### Properties

- **userId** `string`: ID of the account owner the webhook belongs to
- **webhookId** `string`: ID of the webhook configuration that produced this delivery
- **webhookName** `string`: Name of the webhook configuration at delivery time
- **eventId** `string`: Stable webhook event ID (correlates to the delivered payload)
- **event** `string`: Event type that triggered the delivery (e.g. post.published)
- **url** `string`: Destination URL the webhook was delivered to
- **status** `string`: Delivery outcome - one of: success, failed
- **statusCode** `integer`: HTTP status code returned by the destination endpoint
- **requestPayload** `object`: The JSON payload sent to the destination endpoint
- **responseBody** `string`: Response body returned by the destination endpoint
- **errorMessage** `string`: Error message when delivery failed
- **attemptNumber** `integer`: Delivery attempt number (increments on retries)
- **responseTime** `integer`: Time taken by the destination endpoint to respond, in milliseconds
- **createdAt** `string`: Timestamp the delivery was attempted

---

# List webhooks API Reference

Retrieve all configured webhooks for the authenticated user. Supports up to 10 webhooks per user.

## GET /v1/webhooks/settings

**List webhooks**

Retrieve all configured webhooks for the authenticated user. Supports up to 10 webhooks per user.

### Responses

#### 200: Webhooks retrieved successfully

**Response Body:**

- **webhooks** `array[Webhook]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/webhooks/settings

**Create webhook**

Create a new webhook configuration. Maximum 10 webhooks per user.

`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.

Webhooks are automatically disabled after 10 consecutive delivery failures.


### Request Body

- **name** (required) `string`: Webhook name (1-50 characters)
- **url** (required) `string`: Webhook endpoint URL (must be a valid URL, whitespace trimmed)
- **secret** `string`: Secret key for HMAC-SHA256 signature verification
- **events** (required) `array`: Events to subscribe to (at least one required)
- **isActive** `boolean`: Enable or disable webhook delivery. Defaults to `true` when omitted.
- **customHeaders** `object`: Custom headers to include in webhook requests

### Responses

#### 200: Webhook created successfully

**Response Body:**

- **success** `boolean`: No description
- **webhook**: `Webhook` - See schema definition

#### 400: Validation error or maximum webhooks reached

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/webhooks/settings

**Update webhook**

Update an existing webhook configuration. All fields except `_id` are optional; only provided fields will be updated.

When provided, `name` must be 1-50 characters, `url` must be a valid URL, and `events` must contain at least one event. Whitespace is trimmed from `url` before validation.

Webhooks are automatically disabled after 10 consecutive delivery failures.


### Request Body

- **_id** (required) `string`: Webhook ID to update (required)
- **name** `string`: Webhook name (1-50 characters). Must be non-empty if provided.
- **url** `string`: Webhook endpoint URL (must be a valid URL, whitespace trimmed). Must be a valid URL if provided.
- **secret** `string`: Secret key for HMAC-SHA256 signature verification
- **events** `array`: Events to subscribe to. Must contain at least one event if provided.
- **isActive** `boolean`: Enable or disable webhook delivery
- **customHeaders** `object`: Custom headers to include in webhook requests

### Responses

#### 200: Webhook updated successfully

**Response Body:**

- **success** `boolean`: No description
- **webhook**: `Webhook` - See schema definition

#### 400: Validation error or missing webhook ID

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Webhook not found

---

## DELETE /v1/webhooks/settings

**Delete webhook**

Permanently delete a webhook configuration.

### Parameters

- **id** (required) in query: Webhook ID to delete

### Responses

#### 200: Webhook deleted successfully

**Response Body:**

- **success** `boolean`: No description

#### 400: Webhook ID required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## Webhook

Individual webhook configuration for receiving real-time notifications

### Properties

- **_id** `string`: Unique webhook identifier
- **name** `string`: Webhook name (for identification) (max: 50)
- **url** `string`: Webhook endpoint URL
- **secret** `string`: Secret key for HMAC-SHA256 signature verification.
- **events** `array`: Events subscribed to
- **isActive** `boolean`: Whether webhook delivery is enabled
- **lastFiredAt** `string`: Timestamp of last successful webhook delivery
- **failureCount** `integer`: Consecutive delivery failures (resets on success, webhook disabled at 10)
- **customHeaders** `object`: Custom headers included in webhook requests

---

# Send test webhook API Reference

Send a test webhook to verify your endpoint is configured correctly. The test payload includes event: "webhook.test" to distinguish it from real events.


## POST /v1/webhooks/test

**Send test webhook**

Send a test webhook to verify your endpoint is configured correctly. The test payload includes event: "webhook.test" to distinguish it from real events.


### Request Body

- **webhookId** (required) `string`: ID of the webhook to test

### Responses

#### 200: Test webhook sent successfully

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 400: Webhook ID required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 500: Test webhook failed to deliver

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

---

---

# Update webhook API Reference

Update an existing webhook configuration. All fields except `_id` are optional; only provided fields will be updated.

When provided, `name` must be 1-50 characters, `url` must be a valid URL, and `events` must contain at least one event. Whitespace is trimmed from `url` before validation.

Webhooks are automatically disabled after 10 consecutive delivery failures.


## GET /v1/webhooks/settings

**List webhooks**

Retrieve all configured webhooks for the authenticated user. Supports up to 10 webhooks per user.

### Responses

#### 200: Webhooks retrieved successfully

**Response Body:**

- **webhooks** `array[Webhook]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/webhooks/settings

**Create webhook**

Create a new webhook configuration. Maximum 10 webhooks per user.

`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.

Webhooks are automatically disabled after 10 consecutive delivery failures.


### Request Body

- **name** (required) `string`: Webhook name (1-50 characters)
- **url** (required) `string`: Webhook endpoint URL (must be a valid URL, whitespace trimmed)
- **secret** `string`: Secret key for HMAC-SHA256 signature verification
- **events** (required) `array`: Events to subscribe to (at least one required)
- **isActive** `boolean`: Enable or disable webhook delivery. Defaults to `true` when omitted.
- **customHeaders** `object`: Custom headers to include in webhook requests

### Responses

#### 200: Webhook created successfully

**Response Body:**

- **success** `boolean`: No description
- **webhook**: `Webhook` - See schema definition

#### 400: Validation error or maximum webhooks reached

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## PUT /v1/webhooks/settings

**Update webhook**

Update an existing webhook configuration. All fields except `_id` are optional; only provided fields will be updated.

When provided, `name` must be 1-50 characters, `url` must be a valid URL, and `events` must contain at least one event. Whitespace is trimmed from `url` before validation.

Webhooks are automatically disabled after 10 consecutive delivery failures.


### Request Body

- **_id** (required) `string`: Webhook ID to update (required)
- **name** `string`: Webhook name (1-50 characters). Must be non-empty if provided.
- **url** `string`: Webhook endpoint URL (must be a valid URL, whitespace trimmed). Must be a valid URL if provided.
- **secret** `string`: Secret key for HMAC-SHA256 signature verification
- **events** `array`: Events to subscribe to. Must contain at least one event if provided.
- **isActive** `boolean`: Enable or disable webhook delivery
- **customHeaders** `object`: Custom headers to include in webhook requests

### Responses

#### 200: Webhook updated successfully

**Response Body:**

- **success** `boolean`: No description
- **webhook**: `Webhook` - See schema definition

#### 400: Validation error or missing webhook ID

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Webhook not found

---

## DELETE /v1/webhooks/settings

**Delete webhook**

Permanently delete a webhook configuration.

### Parameters

- **id** (required) in query: Webhook ID to delete

### Responses

#### 200: Webhook deleted successfully

**Response Body:**

- **success** `boolean`: No description

#### 400: Webhook ID required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---


# Related Schema Definitions

## Webhook

Individual webhook configuration for receiving real-time notifications

### Properties

- **_id** `string`: Unique webhook identifier
- **name** `string`: Webhook name (for identification) (max: 50)
- **url** `string`: Webhook endpoint URL
- **secret** `string`: Secret key for HMAC-SHA256 signature verification.
- **events** `array`: Events subscribed to
- **isActive** `boolean`: Whether webhook delivery is enabled
- **lastFiredAt** `string`: Timestamp of last successful webhook delivery
- **failureCount** `integer`: Consecutive delivery failures (resets on success, webhook disabled at 10)
- **customHeaders** `object`: Custom headers included in webhook requests

---

# Add participants API Reference

Add participants to a WhatsApp group. Maximum 8 participants per request.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


## POST /v1/whatsapp/wa-groups/{groupId}/participants

**Add participants**

Add participants to a WhatsApp group. Maximum 8 participants per request.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **phoneNumbers** (required) `array`: Phone numbers in E.164 format (max 8)

### Responses

#### 200: Participants added

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/whatsapp/wa-groups/{groupId}/participants

**Remove participants**

Remove participants from a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **phoneNumbers** (required) `array`: Phone numbers to remove

### Responses

#### 200: Participants removed

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Approve join requests API Reference

Approve pending join requests for a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


## GET /v1/whatsapp/wa-groups/{groupId}/join-requests

**List join requests**

List pending join requests for a WhatsApp group (only for groups with approval_required mode).

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Join requests

**Response Body:**

- **success** `boolean`: No description
- **joinRequests** `array[object]`: 
  - **user** `string`: Phone number
  - **timestamp** `integer`: UNIX timestamp of request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/whatsapp/wa-groups/{groupId}/join-requests

**Approve join requests**

Approve pending join requests for a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **phoneNumbers** (required) `array`: Phone numbers to approve

### Responses

#### 200: Requests approved

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/whatsapp/wa-groups/{groupId}/join-requests

**Reject join requests**

Reject pending join requests for a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **phoneNumbers** (required) `array`: Phone numbers to reject

### Responses

#### 200: Requests rejected

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Block users API Reference

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.

Meta constraints, surfaced per-user in `failed` (the request itself still
succeeds for the rest of the batch):
- Only users who messaged your business within the last 24 hours can be
  blocked (failures outside the window report "Re-engagement required").
- Up to 1,000 users per request; the blocklist caps at 64,000.
- Other WhatsApp Business accounts cannot be blocked.


## GET /v1/whatsapp/block-users

**List blocked users**

List the WhatsApp users blocked on this number. Cursor-paginated; pass
`nextCursor` back as `after` to fetch the next page. The blocklist holds
up to 64,000 users.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID
- **limit** (optional) in query: Page size.
- **after** (optional) in query: Cursor from a previous response's `nextCursor`.

### Responses

#### 200: Blocked users

**Response Body:**

- **blockedUsers** `array[object]`: 
  - **waId** `string`: WhatsApp user ID (usually the phone number without `+`).
- **nextCursor** `string`: Pass as `after` to fetch the next page. Null when there are no more pages.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/block-users

**Block users**

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.

Meta constraints, surfaced per-user in `failed` (the request itself still
succeeds for the rest of the batch):
- Only users who messaged your business within the last 24 hours can be
  blocked (failures outside the window report "Re-engagement required").
- Up to 1,000 users per request; the blocklist caps at 64,000.
- Other WhatsApp Business accounts cannot be blocked.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **users** (required) `array`: Phone numbers (E.164, e.g. "+16505551234") or WhatsApp user IDs to block.

### Responses

#### 200: Per-user results

**Response Body:**

- **blocked** `array[object]`: Users successfully blocked.
  - **input** `string`: The value you sent.
  - **waId** `string`: Resolved WhatsApp user ID.
- **failed** `array[object]`: Users that could not be blocked, with reasons.
  - **input** `string`: No description
  - **errors** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## DELETE /v1/whatsapp/block-users

**Unblock users**

Unblock one or more previously blocked WhatsApp users on this number.
Up to 1,000 users per request; per-user failures are reported in
`failed` without failing the rest of the batch.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **users** (required) `array`: Phone numbers (E.164) or WhatsApp user IDs to unblock.

### Responses

#### 200: Per-user results

**Response Body:**

- **unblocked** `array[object]`: Users successfully unblocked.
  - **input** `string`: The value you sent.
  - **waId** `string`: Resolved WhatsApp user ID.
- **failed** `array[object]`: Users that could not be unblocked, with reasons.
  - **input** `string`: No description
  - **errors** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Provision CTWA conversions dataset API Reference

Creates (or fetches, if one already exists) the Meta dataset that
Click-to-WhatsApp ad events are reported against via the Conversions
API, and persists its ID on the account as `metadata.metaCapiDatasetId`.

The call is GET-first idempotent — a WABA can only own one CTWA
dataset, so a second call after a successful provision is a safe no-op
that returns the same ID with `created: false`.

Requires the connected WhatsApp account's token to carry the
`whatsapp_business_manage_events` permission. If the permission is
missing the endpoint returns 422 with a message asking the user to
reconnect the account.


## GET /v1/whatsapp/dataset

**Get CTWA conversions dataset**

Returns the Meta Click-to-WhatsApp conversions dataset currently linked
to the WhatsApp account, if one has been provisioned. Reads only from
the stored `metadata.metaCapiDatasetId` — never hits Meta, never
creates a dataset. Use this to detect whether `POST /v1/whatsapp/conversions`
is configured for an account.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Dataset lookup

**Response Body:**

- **datasetId** `string`: Meta dataset ID linked to the WABA, or null if not provisioned yet

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/dataset

**Provision CTWA conversions dataset**

Creates (or fetches, if one already exists) the Meta dataset that
Click-to-WhatsApp ad events are reported against via the Conversions
API, and persists its ID on the account as `metadata.metaCapiDatasetId`.

The call is GET-first idempotent — a WABA can only own one CTWA
dataset, so a second call after a successful provision is a safe no-op
that returns the same ID with `created: false`.

Requires the connected WhatsApp account's token to carry the
`whatsapp_business_manage_events` permission. If the permission is
missing the endpoint returns 422 with a message asking the user to
reconnect the account.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID

### Responses

#### 200: Dataset provisioned (or already present)

**Response Body:**

- **datasetId** `string`: Meta dataset ID linked to the WABA
- **created** `boolean`: True if Meta created a new dataset on this call; false if one already existed

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

#### 422: Account is missing `whatsapp_business_manage_events` — reconnect required

#### 502: Upstream Meta failure during provisioning

---

---

# Create group API Reference

Create a new WhatsApp group chat. Returns the group ID and optionally an invite link.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


## GET /v1/whatsapp/wa-groups

**List active groups**

List active WhatsApp group chats for a business phone number.
These are actual WhatsApp group conversations on the platform.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID
- **limit** (optional) in query: Max groups to return
- **after** (optional) in query: Pagination cursor

### Responses

#### 200: List of active groups

**Response Body:**

- **groups** `array[object]`: 
  - **id** `string`: Group ID
  - **subject** `string`: Group name
  - **createdAt** `string`: Group creation timestamp
- **paging** `object`: 
  - **cursors** `object`: 
    - **after** `string`: No description
    - **before** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/whatsapp/wa-groups

**Create group**

Create a new WhatsApp group chat. Returns the group ID and optionally an invite link.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **subject** (required) `string`: Group name (max 128 characters)
- **description** `string`: Group description (max 2048 characters)
- **joinApprovalMode** `string`: Whether users need approval to join via invite link - one of: approval_required, auto_approve

### Responses

#### 201: Group created

**Response Body:**

- **success** `boolean`: No description
- **group** `object`: 
  - **groupId** `string`: No description
  - **inviteLink** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Create invite link API Reference

Create a new invite link for a WhatsApp group. The previous link is revoked.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


## POST /v1/whatsapp/wa-groups/{groupId}/invite-link

**Create invite link**

Create a new invite link for a WhatsApp group. The previous link is revoked.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Invite link created

**Response Body:**

- **success** `boolean`: No description
- **inviteLink** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Create template API Reference

Create a new message template. Supports two modes:

Custom template: Provide components with your own content. Submitted to Meta for review (can take up to 24h).

Library template: Provide library_template_name instead of components to use a pre-built template
from Meta's template library. Library templates are pre-approved (no review wait). You can optionally
customize parameters and buttons via library_template_body_inputs and library_template_button_inputs.

Browse available library templates at: https://business.facebook.com/wa/manage/message-templates/


## GET /v1/whatsapp/templates

**List templates**

List all message templates for the WhatsApp Business Account (WABA) associated with the given account.
Templates are fetched directly from the WhatsApp Cloud API.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Templates retrieved successfully

**Response Body:**

- **success** `boolean`: No description
- **templates** `array[object]`: 
  - **id** `string`: WhatsApp template ID
  - **name** `string`: No description
  - **status** `string`: No description - one of: APPROVED, PENDING, REJECTED
  - **category** `string`: No description - one of: AUTHENTICATION, MARKETING, UTILITY
  - **language** `string`: No description
  - **components** `array[object]`: 
    Type: `object`

#### 400: accountId is required or WABA ID not found

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/templates

**Create template**

Create a new message template. Supports two modes:

Custom template: Provide components with your own content. Submitted to Meta for review (can take up to 24h).

Library template: Provide library_template_name instead of components to use a pre-built template
from Meta's template library. Library templates are pre-approved (no review wait). You can optionally
customize parameters and buttons via library_template_body_inputs and library_template_button_inputs.

Browse available library templates at: https://business.facebook.com/wa/manage/message-templates/


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **name** (required) `string`: Template name (lowercase, letters/numbers/underscores, must start with a letter)
- **category** (required) `string`: Template category - one of: AUTHENTICATION, MARKETING, UTILITY
- **language** (required) `string`: Template language code (e.g., en_US)
- **components** `array`: Template components (header, body, footer, buttons). Required for custom templates, omit when using library_template_name.
- **library_template_name** `string`: Name of a pre-built template from Meta's template library (e.g., "appointment_reminder",
"auto_pay_reminder_1", "address_update"). When provided, the template is pre-approved
by Meta with no review wait. Omit components when using this field.

- **library_template_body_inputs** `object`: Optional body customizations for library templates. Available options depend on the
template (e.g., add_contact_number, add_learn_more_link, add_security_recommendation,
add_track_package_link, code_expiration_minutes).

- **library_template_button_inputs** `array`: Optional button customizations for library templates. Each item specifies button type
and configuration (e.g., URL, phone number, quick reply).


### Responses

#### 200: Template created (pre-approved for library templates, pending review for custom)

**Response Body:**

- **success** `boolean`: No description
- **template** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: APPROVED for library templates, PENDING for custom
  - **category** `string`: No description
  - **language** `string`: No description

#### 400: Validation error (invalid name format

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Delete group API Reference

Delete a WhatsApp group and remove all participants.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


## GET /v1/whatsapp/wa-groups/{groupId}

**Get group info**

Retrieve metadata about a WhatsApp group including subject, description,
participants, and settings.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Group info

**Response Body:**

- **success** `boolean`: No description
- **group** `object`: 
  - **id** `string`: No description
  - **subject** `string`: No description
  - **description** `string`: No description
  - **joinApprovalMode** `string`: No description
  - **participants** `array[object]`: 
    - **user** `string`: Phone number
    - **admin** `string`: No description
  - **participantCount** `integer`: No description
  - **createdAt** `integer`: UNIX timestamp
  - **isSuspended** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## POST /v1/whatsapp/wa-groups/{groupId}

**Update group settings**

Update the subject, description, or join approval mode of a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **subject** `string`: No description
- **description** `string`: No description
- **joinApprovalMode** `string`: No description - one of: approval_required, auto_approve

### Responses

#### 200: Group updated

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/whatsapp/wa-groups/{groupId}

**Delete group**

Delete a WhatsApp group and remove all participants.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Group deleted

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Delete template API Reference

Permanently delete a message template by name.


## GET /v1/whatsapp/templates/{templateName}

**Get template**

Retrieve a single message template by name.


### Parameters

- **templateName** (required) in path: Template name
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Template retrieved successfully

**Response Body:**

- **success** `boolean`: No description
- **template** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description
  - **category** `string`: No description
  - **language** `string`: No description
  - **components** `array[object]`: 
    Type: `object`

#### 400: accountId is required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/whatsapp/templates/{templateName}

**Update template**

Update a message template's components. Only certain fields can be updated depending on
the template's current approval state. Approved templates can only have components updated.


### Parameters

- **templateName** (required) in path: Template name

### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **components** (required) `array`: Updated template components

### Responses

#### 200: Template updated successfully

**Response Body:**

- **success** `boolean`: No description
- **template** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description

#### 400: Validation error (missing fields)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/whatsapp/templates/{templateName}

**Delete template**

Permanently delete a message template by name.


### Parameters

- **templateName** (required) in path: Template name
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Template deleted successfully

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 400: accountId or template name is required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Check if a user is blocked API Reference

Definitive blocked-state lookup for a single contact. Meta exposes no
membership endpoint, so this reads Zernio's blocklist mirror (kept in
sync by the block/unblock endpoints; the first call per account
backfills the mirror from Meta's full list). Constant-time regardless
of blocklist size.


## GET /v1/whatsapp/block-users/status

**Check if a user is blocked**

Definitive blocked-state lookup for a single contact. Meta exposes no
membership endpoint, so this reads Zernio's blocklist mirror (kept in
sync by the block/unblock endpoints; the first call per account
backfills the mirror from Meta's full list). Constant-time regardless
of blocklist size.


### Parameters

- **accountId** (required) in query: No description
- **user** (required) in query: Consumer wa_id or E.164 phone (leading + optional)

### Responses

#### 200: Blocked state

**Response Body:**

- **blocked** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# List blocked users API Reference

List the WhatsApp users blocked on this number. Cursor-paginated; pass
`nextCursor` back as `after` to fetch the next page. The blocklist holds
up to 64,000 users.


## GET /v1/whatsapp/block-users

**List blocked users**

List the WhatsApp users blocked on this number. Cursor-paginated; pass
`nextCursor` back as `after` to fetch the next page. The blocklist holds
up to 64,000 users.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID
- **limit** (optional) in query: Page size.
- **after** (optional) in query: Cursor from a previous response's `nextCursor`.

### Responses

#### 200: Blocked users

**Response Body:**

- **blockedUsers** `array[object]`: 
  - **waId** `string`: WhatsApp user ID (usually the phone number without `+`).
- **nextCursor** `string`: Pass as `after` to fetch the next page. Null when there are no more pages.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/block-users

**Block users**

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.

Meta constraints, surfaced per-user in `failed` (the request itself still
succeeds for the rest of the batch):
- Only users who messaged your business within the last 24 hours can be
  blocked (failures outside the window report "Re-engagement required").
- Up to 1,000 users per request; the blocklist caps at 64,000.
- Other WhatsApp Business accounts cannot be blocked.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **users** (required) `array`: Phone numbers (E.164, e.g. "+16505551234") or WhatsApp user IDs to block.

### Responses

#### 200: Per-user results

**Response Body:**

- **blocked** `array[object]`: Users successfully blocked.
  - **input** `string`: The value you sent.
  - **waId** `string`: Resolved WhatsApp user ID.
- **failed** `array[object]`: Users that could not be blocked, with reasons.
  - **input** `string`: No description
  - **errors** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## DELETE /v1/whatsapp/block-users

**Unblock users**

Unblock one or more previously blocked WhatsApp users on this number.
Up to 1,000 users per request; per-user failures are reported in
`failed` without failing the rest of the batch.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **users** (required) `array`: Phone numbers (E.164) or WhatsApp user IDs to unblock.

### Responses

#### 200: Per-user results

**Response Body:**

- **unblocked** `array[object]`: Users successfully unblocked.
  - **input** `string`: The value you sent.
  - **waId** `string`: Resolved WhatsApp user ID.
- **failed** `array[object]`: Users that could not be unblocked, with reasons.
  - **input** `string`: No description
  - **errors** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Get business profile API Reference

Retrieve the WhatsApp Business profile for the account (about, address, description, email, websites, etc.).


## GET /v1/whatsapp/business-profile

**Get business profile**

Retrieve the WhatsApp Business profile for the account (about, address, description, email, websites, etc.).


### Parameters

- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Business profile retrieved successfully

**Response Body:**

- **success** `boolean`: No description
- **businessProfile** `object`: 
  - **about** `string`: Short description (max 139 chars)
  - **address** `string`: No description
  - **description** `string`: Full description (max 512 chars)
  - **email** `string`: No description
  - **profilePictureUrl** `string` (uri): No description
  - **websites** `array[string]`: 
  - **vertical** `string`: Business category

#### 400: accountId is required or phone number ID not found

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/business-profile

**Update business profile**

Update the WhatsApp Business profile. All fields are optional; only provided fields will be updated.
Constraints: about max 139 chars, description max 512 chars, max 2 websites.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **about** `string`: Short business description (max 139 characters)
- **address** `string`: Business address
- **description** `string`: Full business description (max 512 characters)
- **email** `string`: Business email
- **websites** `array`: Business websites (max 2)
- **vertical** `string`: Business category (e.g., RETAIL, ENTERTAINMENT, etc.)
- **profilePictureHandle** `string`: Handle from resumable upload for profile picture

### Responses

#### 200: Business profile updated successfully

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 400: Validation error (field too long

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Get CTWA conversions dataset API Reference

Returns the Meta Click-to-WhatsApp conversions dataset currently linked
to the WhatsApp account, if one has been provisioned. Reads only from
the stored `metadata.metaCapiDatasetId` — never hits Meta, never
creates a dataset. Use this to detect whether `POST /v1/whatsapp/conversions`
is configured for an account.


## GET /v1/whatsapp/dataset

**Get CTWA conversions dataset**

Returns the Meta Click-to-WhatsApp conversions dataset currently linked
to the WhatsApp account, if one has been provisioned. Reads only from
the stored `metadata.metaCapiDatasetId` — never hits Meta, never
creates a dataset. Use this to detect whether `POST /v1/whatsapp/conversions`
is configured for an account.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Dataset lookup

**Response Body:**

- **datasetId** `string`: Meta dataset ID linked to the WABA, or null if not provisioned yet

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/dataset

**Provision CTWA conversions dataset**

Creates (or fetches, if one already exists) the Meta dataset that
Click-to-WhatsApp ad events are reported against via the Conversions
API, and persists its ID on the account as `metadata.metaCapiDatasetId`.

The call is GET-first idempotent — a WABA can only own one CTWA
dataset, so a second call after a successful provision is a safe no-op
that returns the same ID with `created: false`.

Requires the connected WhatsApp account's token to carry the
`whatsapp_business_manage_events` permission. If the permission is
missing the endpoint returns 422 with a message asking the user to
reconnect the account.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID

### Responses

#### 200: Dataset provisioned (or already present)

**Response Body:**

- **datasetId** `string`: Meta dataset ID linked to the WABA
- **created** `boolean`: True if Meta created a new dataset on this call; false if one already existed

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

#### 422: Account is missing `whatsapp_business_manage_events` — reconnect required

#### 502: Upstream Meta failure during provisioning

---

---

# Get display name status API Reference

Fetch the current display name and its Meta review status for a WhatsApp Business account.
Display name changes require Meta approval and can take 1-3 business days.


## GET /v1/whatsapp/business-profile/display-name

**Get display name status**

Fetch the current display name and its Meta review status for a WhatsApp Business account.
Display name changes require Meta approval and can take 1-3 business days.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Display name info retrieved

**Response Body:**

- **success** `boolean`: No description
- **displayName** `object`: 
  - **name** `string`: Current verified display name
  - **status** `string`: Meta review status for the display name - one of: APPROVED, PENDING_REVIEW, DECLINED, NONE
  - **phoneNumber** `string`: Display phone number

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/business-profile/display-name

**Request display name change**

Submit a display name change request for the WhatsApp Business account.
The new name must follow WhatsApp naming guidelines (3-512 characters, must represent your business).
Changes require Meta review and approval, which typically takes 1-3 business days.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **displayName** (required) `string`: New display name (must follow WhatsApp naming guidelines)

### Responses

#### 200: Display name change submitted for review

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description
- **displayName** `object`: 
  - **name** `string`: No description
  - **status** `string`: No description - one of: PENDING_REVIEW

#### 400: Invalid display name (too short

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Get group info API Reference

Retrieve metadata about a WhatsApp group including subject, description,
participants, and settings.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


## GET /v1/whatsapp/wa-groups/{groupId}

**Get group info**

Retrieve metadata about a WhatsApp group including subject, description,
participants, and settings.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Group info

**Response Body:**

- **success** `boolean`: No description
- **group** `object`: 
  - **id** `string`: No description
  - **subject** `string`: No description
  - **description** `string`: No description
  - **joinApprovalMode** `string`: No description
  - **participants** `array[object]`: 
    - **user** `string`: Phone number
    - **admin** `string`: No description
  - **participantCount** `integer`: No description
  - **createdAt** `integer`: UNIX timestamp
  - **isSuspended** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## POST /v1/whatsapp/wa-groups/{groupId}

**Update group settings**

Update the subject, description, or join approval mode of a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **subject** `string`: No description
- **description** `string`: No description
- **joinApprovalMode** `string`: No description - one of: approval_required, auto_approve

### Responses

#### 200: Group updated

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/whatsapp/wa-groups/{groupId}

**Delete group**

Delete a WhatsApp group and remove all participants.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Group deleted

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Look up a library template API Reference

Look up a single pre-approved Template Library template by its exact name, to
introspect its structure before importing it. Most 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.


## GET /v1/whatsapp/template-library

**Look up a library template**

Look up a single pre-approved Template Library template by its exact name, to
introspect its structure before importing it. Most 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.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID
- **name** (required) in query: Exact library template name

### Responses

#### 200: Library template (or null if no exact match)

**Response Body:**

- **template** `object`: 
  - **name** `string`: No description
  - **language** `string`: No description
  - **category** `string`: No description
  - **body** `string`: No description
  - **body_params** `array[string]`: 
  - **buttons** `array[object]`: 
    - **type** `string`: QUICK_REPLY, URL, PHONE_NUMBER, OTP, FLOW, ...
    - **text** `string`: No description

#### 400: Missing or invalid query params

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Get template API Reference

Retrieve a single message template by name.


## GET /v1/whatsapp/templates/{templateName}

**Get template**

Retrieve a single message template by name.


### Parameters

- **templateName** (required) in path: Template name
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Template retrieved successfully

**Response Body:**

- **success** `boolean`: No description
- **template** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description
  - **category** `string`: No description
  - **language** `string`: No description
  - **components** `array[object]`: 
    Type: `object`

#### 400: accountId is required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/whatsapp/templates/{templateName}

**Update template**

Update a message template's components. Only certain fields can be updated depending on
the template's current approval state. Approved templates can only have components updated.


### Parameters

- **templateName** (required) in path: Template name

### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **components** (required) `array`: Updated template components

### Responses

#### 200: Template updated successfully

**Response Body:**

- **success** `boolean`: No description
- **template** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description

#### 400: Validation error (missing fields)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/whatsapp/templates/{templateName}

**Delete template**

Permanently delete a message template by name.


### Parameters

- **templateName** (required) in path: Template name
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Template deleted successfully

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 400: accountId or template name is required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List templates API Reference

List all message templates for the WhatsApp Business Account (WABA) associated with the given account.
Templates are fetched directly from the WhatsApp Cloud API.


## GET /v1/whatsapp/templates

**List templates**

List all message templates for the WhatsApp Business Account (WABA) associated with the given account.
Templates are fetched directly from the WhatsApp Cloud API.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Templates retrieved successfully

**Response Body:**

- **success** `boolean`: No description
- **templates** `array[object]`: 
  - **id** `string`: WhatsApp template ID
  - **name** `string`: No description
  - **status** `string`: No description - one of: APPROVED, PENDING, REJECTED
  - **category** `string`: No description - one of: AUTHENTICATION, MARKETING, UTILITY
  - **language** `string`: No description
  - **components** `array[object]`: 
    Type: `object`

#### 400: accountId is required or WABA ID not found

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/templates

**Create template**

Create a new message template. Supports two modes:

Custom template: Provide components with your own content. Submitted to Meta for review (can take up to 24h).

Library template: Provide library_template_name instead of components to use a pre-built template
from Meta's template library. Library templates are pre-approved (no review wait). You can optionally
customize parameters and buttons via library_template_body_inputs and library_template_button_inputs.

Browse available library templates at: https://business.facebook.com/wa/manage/message-templates/


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **name** (required) `string`: Template name (lowercase, letters/numbers/underscores, must start with a letter)
- **category** (required) `string`: Template category - one of: AUTHENTICATION, MARKETING, UTILITY
- **language** (required) `string`: Template language code (e.g., en_US)
- **components** `array`: Template components (header, body, footer, buttons). Required for custom templates, omit when using library_template_name.
- **library_template_name** `string`: Name of a pre-built template from Meta's template library (e.g., "appointment_reminder",
"auto_pay_reminder_1", "address_update"). When provided, the template is pre-approved
by Meta with no review wait. Omit components when using this field.

- **library_template_body_inputs** `object`: Optional body customizations for library templates. Available options depend on the
template (e.g., add_contact_number, add_learn_more_link, add_security_recommendation,
add_track_package_link, code_expiration_minutes).

- **library_template_button_inputs** `array`: Optional button customizations for library templates. Each item specifies button type
and configuration (e.g., URL, phone number, quick reply).


### Responses

#### 200: Template created (pre-approved for library templates, pending review for custom)

**Response Body:**

- **success** `boolean`: No description
- **template** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: APPROVED for library templates, PENDING for custom
  - **category** `string`: No description
  - **language** `string`: No description

#### 400: Validation error (invalid name format

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# List recent WhatsApp conversion events API Reference

Returns the most recent conversion events sent through
`POST /v1/whatsapp/conversions` for the given WhatsApp account.
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.

Per-event payload mirrors the structured log we write on every
successful send: `eventName`, `conversationId`, `eventsReceived`,
`eventsFailed`, `traceId`, `durationMs`, and the wall-clock
`timestamp`.


## GET /v1/whatsapp/conversions

**List recent WhatsApp conversion events**

Returns the most recent conversion events sent through
`POST /v1/whatsapp/conversions` for the given WhatsApp account.
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.

Per-event payload mirrors the structured log we write on every
successful send: `eventName`, `conversationId`, `eventsReceived`,
`eventsFailed`, `traceId`, `durationMs`, and the wall-clock
`timestamp`.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID
- **limit** (optional) in query: Max events to return (1-200, default 50).

### Responses

#### 200: Recent conversion events

**Response Body:**

- **events** `array[object]`: 
  - **timestamp** `string` (date-time): When the event was sent to Meta.
  - **eventName** `string`: One of LeadSubmitted, Purchase, AddToCart, InitiateCheckout, ViewContent.
  - **conversationId** `string`: No description
  - **eventsReceived** `integer`: Number of events Meta accepted on this send (usually 1).
  - **eventsFailed** `integer`: Number of events Meta rejected (usually 0).
  - **traceId** `string`: Meta fbtrace_id for cross-referencing in Events Manager.
  - **durationMs** `integer`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/conversions

**Send WhatsApp conversion event**

Forward a WhatsApp Business Messaging conversion event (`LeadSubmitted`,
`Purchase`, `AddToCart`, `InitiateCheckout`, `ViewContent`) to Meta's
Conversions API with `action_source = business_messaging` and
`messaging_channel = whatsapp`. The endpoint looks up the originating
CTWA click ID (`ctwa_clid`) captured on the first inbound message of
the conversation and replays it on every event so Meta can attribute
the conversion back to the Click-to-WhatsApp ad that drove the chat.

Configuration prerequisite on the WhatsApp account metadata:
  - `metaCapiDatasetId`: the Meta dataset ID linked to the WABA.
    Provision one with `POST /v1/whatsapp/dataset`.

The WABA ID (already set automatically at connect time) is forwarded as
`user_data.whatsapp_business_account_id`, which is the per-channel
attribution identifier Meta requires for WhatsApp events. No Facebook
Page ID is needed (that field is the Messenger-branch identifier).

Identify the conversation by either `conversationId` (preferred) or
`phoneE164` (digits only, no `+`). At least one is required. If the
conversation has no captured `ctwa_clid`, the request returns 422
because there is nothing to attribute.

Token and dataset coupling: the 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. Either share the dataset with the WhatsApp
app's Business in BM, or use a dataset already in the same Business
as the WABA.


### Request Body

- **accountId** (required) `string`: WhatsApp SocialAccount ID.
- **eventName** (required) `string`: Live-verified allowlist of event names accepted by Meta's
CAPI for Business Messaging (Graph API v25.0). Other
standard pixel events including `Lead`,
`CompleteRegistration`, `Subscribe`, `Schedule`, `Contact`,
`StartTrial`, `AddPaymentInfo`, `Search`, and
`SubmitApplication` are rejected with subcode 2804066
("Messaging Event Invalid Event Type") on
`action_source = business_messaging` events. Custom event
names are also rejected.

Use `LeadSubmitted` (NOT `Lead`) for lead-style conversions.
 - one of: LeadSubmitted, Purchase, AddToCart, InitiateCheckout, ViewContent
- **eventTime** `number`: Unix seconds. Defaults to the time of the request when
omitted. Meta's attribution window is 7 days from click;
events older than that lose attribution.

- **eventId** (required) `string`: Stable dedup key. Reuse to suppress duplicate events
(Meta dedupes against pixel events with the same id).

- **conversationId** `string`: Zernio Conversation `_id` (preferred lookup). The
conversation must have a captured `ctwa_clid` in metadata
(set automatically by the WhatsApp webhook on the first
inbound message after a CTWA ad click).

- **phoneE164** `string`: Contact phone number, digits only with no '+'. When used
in lieu of `conversationId`, the handler resolves to the
most recent CTWA-attributed conversation for this phone
on the supplied account.

- **value** `number`: Conversion value (e.g. order total).
- **currency** `string`: ISO 4217 currency code (e.g. `USD`).
- **contentIds** `array`: Optional product / content identifiers.
- **email** `string`: User email. Normalized + SHA-256 hashed before sending to Meta.
- **externalId** `string`: Stable customer identifier. Lowercased + SHA-256 hashed
before sending to Meta.

- **testCode** `string`: Meta `test_event_code` passthrough. Routes the event to
the Test Events tab in Events Manager instead of the
production dataset, useful for development.


### Responses

#### 200: Event submitted to Meta. Inspect `eventsFailed` and `failures[]`
to detect partial failures. A 200 does not mean Meta accepted the
event; the status reflects "request reached Meta" only.


**Response Body:**

- **platform** `string`: No description - one of: metaads
- **eventsReceived** `integer`: Events accepted by Meta.
- **eventsFailed** `integer`: Events rejected by Meta (see failures).
- **failures** `array[object]`: Per-event failure detail. Empty when all events were
accepted.

  - **eventIndex** `integer`: Index into the submitted events array.
  - **eventId** `string`: Echoes back the eventId of the failed event.
  - **message** `string`: No description
  - **code**: One of multiple types
- **traceId** `string`: Meta `fbtrace_id` for debugging. Surface in support
tickets.


#### 400: Invalid body.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Conversation not found.

#### 422: Configuration missing (no `metaCapiDatasetId` on the account, set
it via POST /v1/whatsapp/dataset) OR the resolved conversation has
no captured `ctwa_clid`.


---

---

# List active groups API Reference

List active WhatsApp group chats for a business phone number.
These are actual WhatsApp group conversations on the platform.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


## GET /v1/whatsapp/wa-groups

**List active groups**

List active WhatsApp group chats for a business phone number.
These are actual WhatsApp group conversations on the platform.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID
- **limit** (optional) in query: Max groups to return
- **after** (optional) in query: Pagination cursor

### Responses

#### 200: List of active groups

**Response Body:**

- **groups** `array[object]`: 
  - **id** `string`: Group ID
  - **subject** `string`: Group name
  - **createdAt** `string`: Group creation timestamp
- **paging** `object`: 
  - **cursors** `object`: 
    - **after** `string`: No description
    - **before** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/whatsapp/wa-groups

**Create group**

Create a new WhatsApp group chat. Returns the group ID and optionally an invite link.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **subject** (required) `string`: Group name (max 128 characters)
- **description** `string`: Group description (max 2048 characters)
- **joinApprovalMode** `string`: Whether users need approval to join via invite link - one of: approval_required, auto_approve

### Responses

#### 201: Group created

**Response Body:**

- **success** `boolean`: No description
- **group** `object`: 
  - **groupId** `string`: No description
  - **inviteLink** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# List join requests API Reference

List pending join requests for a WhatsApp group (only for groups with approval_required mode).

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


## GET /v1/whatsapp/wa-groups/{groupId}/join-requests

**List join requests**

List pending join requests for a WhatsApp group (only for groups with approval_required mode).

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Join requests

**Response Body:**

- **success** `boolean`: No description
- **joinRequests** `array[object]`: 
  - **user** `string`: Phone number
  - **timestamp** `integer`: UNIX timestamp of request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/whatsapp/wa-groups/{groupId}/join-requests

**Approve join requests**

Approve pending join requests for a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **phoneNumbers** (required) `array`: Phone numbers to approve

### Responses

#### 200: Requests approved

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/whatsapp/wa-groups/{groupId}/join-requests

**Reject join requests**

Reject pending join requests for a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **phoneNumbers** (required) `array`: Phone numbers to reject

### Responses

#### 200: Requests rejected

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Reject join requests API Reference

Reject pending join requests for a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


## GET /v1/whatsapp/wa-groups/{groupId}/join-requests

**List join requests**

List pending join requests for a WhatsApp group (only for groups with approval_required mode).

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Join requests

**Response Body:**

- **success** `boolean`: No description
- **joinRequests** `array[object]`: 
  - **user** `string`: Phone number
  - **timestamp** `integer`: UNIX timestamp of request

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/whatsapp/wa-groups/{groupId}/join-requests

**Approve join requests**

Approve pending join requests for a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **phoneNumbers** (required) `array`: Phone numbers to approve

### Responses

#### 200: Requests approved

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/whatsapp/wa-groups/{groupId}/join-requests

**Reject join requests**

Reject pending join requests for a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **phoneNumbers** (required) `array`: Phone numbers to reject

### Responses

#### 200: Requests rejected

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Remove participants API Reference

Remove participants from a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


## POST /v1/whatsapp/wa-groups/{groupId}/participants

**Add participants**

Add participants to a WhatsApp group. Maximum 8 participants per request.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **phoneNumbers** (required) `array`: Phone numbers in E.164 format (max 8)

### Responses

#### 200: Participants added

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## DELETE /v1/whatsapp/wa-groups/{groupId}/participants

**Remove participants**

Remove participants from a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **phoneNumbers** (required) `array`: Phone numbers to remove

### Responses

#### 200: Participants removed

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Send WhatsApp conversion event API Reference

Forward a WhatsApp Business Messaging conversion event (`LeadSubmitted`,
`Purchase`, `AddToCart`, `InitiateCheckout`, `ViewContent`) to Meta's
Conversions API with `action_source = business_messaging` and
`messaging_channel = whatsapp`. The endpoint looks up the originating
CTWA click ID (`ctwa_clid`) captured on the first inbound message of
the conversation and replays it on every event so Meta can attribute
the conversion back to the Click-to-WhatsApp ad that drove the chat.

Configuration prerequisite on the WhatsApp account metadata:
  - `metaCapiDatasetId`: the Meta dataset ID linked to the WABA.
    Provision one with `POST /v1/whatsapp/dataset`.

The WABA ID (already set automatically at connect time) is forwarded as
`user_data.whatsapp_business_account_id`, which is the per-channel
attribution identifier Meta requires for WhatsApp events. No Facebook
Page ID is needed (that field is the Messenger-branch identifier).

Identify the conversation by either `conversationId` (preferred) or
`phoneE164` (digits only, no `+`). At least one is required. If the
conversation has no captured `ctwa_clid`, the request returns 422
because there is nothing to attribute.

Token and dataset coupling: the 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. Either share the dataset with the WhatsApp
app's Business in BM, or use a dataset already in the same Business
as the WABA.


## GET /v1/whatsapp/conversions

**List recent WhatsApp conversion events**

Returns the most recent conversion events sent through
`POST /v1/whatsapp/conversions` for the given WhatsApp account.
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.

Per-event payload mirrors the structured log we write on every
successful send: `eventName`, `conversationId`, `eventsReceived`,
`eventsFailed`, `traceId`, `durationMs`, and the wall-clock
`timestamp`.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID
- **limit** (optional) in query: Max events to return (1-200, default 50).

### Responses

#### 200: Recent conversion events

**Response Body:**

- **events** `array[object]`: 
  - **timestamp** `string` (date-time): When the event was sent to Meta.
  - **eventName** `string`: One of LeadSubmitted, Purchase, AddToCart, InitiateCheckout, ViewContent.
  - **conversationId** `string`: No description
  - **eventsReceived** `integer`: Number of events Meta accepted on this send (usually 1).
  - **eventsFailed** `integer`: Number of events Meta rejected (usually 0).
  - **traceId** `string`: Meta fbtrace_id for cross-referencing in Events Manager.
  - **durationMs** `integer`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/conversions

**Send WhatsApp conversion event**

Forward a WhatsApp Business Messaging conversion event (`LeadSubmitted`,
`Purchase`, `AddToCart`, `InitiateCheckout`, `ViewContent`) to Meta's
Conversions API with `action_source = business_messaging` and
`messaging_channel = whatsapp`. The endpoint looks up the originating
CTWA click ID (`ctwa_clid`) captured on the first inbound message of
the conversation and replays it on every event so Meta can attribute
the conversion back to the Click-to-WhatsApp ad that drove the chat.

Configuration prerequisite on the WhatsApp account metadata:
  - `metaCapiDatasetId`: the Meta dataset ID linked to the WABA.
    Provision one with `POST /v1/whatsapp/dataset`.

The WABA ID (already set automatically at connect time) is forwarded as
`user_data.whatsapp_business_account_id`, which is the per-channel
attribution identifier Meta requires for WhatsApp events. No Facebook
Page ID is needed (that field is the Messenger-branch identifier).

Identify the conversation by either `conversationId` (preferred) or
`phoneE164` (digits only, no `+`). At least one is required. If the
conversation has no captured `ctwa_clid`, the request returns 422
because there is nothing to attribute.

Token and dataset coupling: the 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. Either share the dataset with the WhatsApp
app's Business in BM, or use a dataset already in the same Business
as the WABA.


### Request Body

- **accountId** (required) `string`: WhatsApp SocialAccount ID.
- **eventName** (required) `string`: Live-verified allowlist of event names accepted by Meta's
CAPI for Business Messaging (Graph API v25.0). Other
standard pixel events including `Lead`,
`CompleteRegistration`, `Subscribe`, `Schedule`, `Contact`,
`StartTrial`, `AddPaymentInfo`, `Search`, and
`SubmitApplication` are rejected with subcode 2804066
("Messaging Event Invalid Event Type") on
`action_source = business_messaging` events. Custom event
names are also rejected.

Use `LeadSubmitted` (NOT `Lead`) for lead-style conversions.
 - one of: LeadSubmitted, Purchase, AddToCart, InitiateCheckout, ViewContent
- **eventTime** `number`: Unix seconds. Defaults to the time of the request when
omitted. Meta's attribution window is 7 days from click;
events older than that lose attribution.

- **eventId** (required) `string`: Stable dedup key. Reuse to suppress duplicate events
(Meta dedupes against pixel events with the same id).

- **conversationId** `string`: Zernio Conversation `_id` (preferred lookup). The
conversation must have a captured `ctwa_clid` in metadata
(set automatically by the WhatsApp webhook on the first
inbound message after a CTWA ad click).

- **phoneE164** `string`: Contact phone number, digits only with no '+'. When used
in lieu of `conversationId`, the handler resolves to the
most recent CTWA-attributed conversation for this phone
on the supplied account.

- **value** `number`: Conversion value (e.g. order total).
- **currency** `string`: ISO 4217 currency code (e.g. `USD`).
- **contentIds** `array`: Optional product / content identifiers.
- **email** `string`: User email. Normalized + SHA-256 hashed before sending to Meta.
- **externalId** `string`: Stable customer identifier. Lowercased + SHA-256 hashed
before sending to Meta.

- **testCode** `string`: Meta `test_event_code` passthrough. Routes the event to
the Test Events tab in Events Manager instead of the
production dataset, useful for development.


### Responses

#### 200: Event submitted to Meta. Inspect `eventsFailed` and `failures[]`
to detect partial failures. A 200 does not mean Meta accepted the
event; the status reflects "request reached Meta" only.


**Response Body:**

- **platform** `string`: No description - one of: metaads
- **eventsReceived** `integer`: Events accepted by Meta.
- **eventsFailed** `integer`: Events rejected by Meta (see failures).
- **failures** `array[object]`: Per-event failure detail. Empty when all events were
accepted.

  - **eventIndex** `integer`: Index into the submitted events array.
  - **eventId** `string`: Echoes back the eventId of the failed event.
  - **message** `string`: No description
  - **code**: One of multiple types
- **traceId** `string`: Meta `fbtrace_id` for debugging. Surface in support
tickets.


#### 400: Invalid body.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Conversation not found.

#### 422: Configuration missing (no `metaCapiDatasetId` on the account, set
it via POST /v1/whatsapp/dataset) OR the resolved conversation has
no captured `ctwa_clid`.


---

---

# Unblock users API Reference

Unblock one or more previously blocked WhatsApp users on this number.
Up to 1,000 users per request; per-user failures are reported in
`failed` without failing the rest of the batch.


## GET /v1/whatsapp/block-users

**List blocked users**

List the WhatsApp users blocked on this number. Cursor-paginated; pass
`nextCursor` back as `after` to fetch the next page. The blocklist holds
up to 64,000 users.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID
- **limit** (optional) in query: Page size.
- **after** (optional) in query: Cursor from a previous response's `nextCursor`.

### Responses

#### 200: Blocked users

**Response Body:**

- **blockedUsers** `array[object]`: 
  - **waId** `string`: WhatsApp user ID (usually the phone number without `+`).
- **nextCursor** `string`: Pass as `after` to fetch the next page. Null when there are no more pages.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/block-users

**Block users**

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.

Meta constraints, surfaced per-user in `failed` (the request itself still
succeeds for the rest of the batch):
- Only users who messaged your business within the last 24 hours can be
  blocked (failures outside the window report "Re-engagement required").
- Up to 1,000 users per request; the blocklist caps at 64,000.
- Other WhatsApp Business accounts cannot be blocked.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **users** (required) `array`: Phone numbers (E.164, e.g. "+16505551234") or WhatsApp user IDs to block.

### Responses

#### 200: Per-user results

**Response Body:**

- **blocked** `array[object]`: Users successfully blocked.
  - **input** `string`: The value you sent.
  - **waId** `string`: Resolved WhatsApp user ID.
- **failed** `array[object]`: Users that could not be blocked, with reasons.
  - **input** `string`: No description
  - **errors** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## DELETE /v1/whatsapp/block-users

**Unblock users**

Unblock one or more previously blocked WhatsApp users on this number.
Up to 1,000 users per request; per-user failures are reported in
`failed` without failing the rest of the batch.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **users** (required) `array`: Phone numbers (E.164) or WhatsApp user IDs to unblock.

### Responses

#### 200: Per-user results

**Response Body:**

- **unblocked** `array[object]`: Users successfully unblocked.
  - **input** `string`: The value you sent.
  - **waId** `string`: Resolved WhatsApp user ID.
- **failed** `array[object]`: Users that could not be unblocked, with reasons.
  - **input** `string`: No description
  - **errors** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Update business profile API Reference

Update the WhatsApp Business profile. All fields are optional; only provided fields will be updated.
Constraints: about max 139 chars, description max 512 chars, max 2 websites.


## GET /v1/whatsapp/business-profile

**Get business profile**

Retrieve the WhatsApp Business profile for the account (about, address, description, email, websites, etc.).


### Parameters

- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Business profile retrieved successfully

**Response Body:**

- **success** `boolean`: No description
- **businessProfile** `object`: 
  - **about** `string`: Short description (max 139 chars)
  - **address** `string`: No description
  - **description** `string`: Full description (max 512 chars)
  - **email** `string`: No description
  - **profilePictureUrl** `string` (uri): No description
  - **websites** `array[string]`: 
  - **vertical** `string`: Business category

#### 400: accountId is required or phone number ID not found

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/business-profile

**Update business profile**

Update the WhatsApp Business profile. All fields are optional; only provided fields will be updated.
Constraints: about max 139 chars, description max 512 chars, max 2 websites.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **about** `string`: Short business description (max 139 characters)
- **address** `string`: Business address
- **description** `string`: Full business description (max 512 characters)
- **email** `string`: Business email
- **websites** `array`: Business websites (max 2)
- **vertical** `string`: Business category (e.g., RETAIL, ENTERTAINMENT, etc.)
- **profilePictureHandle** `string`: Handle from resumable upload for profile picture

### Responses

#### 200: Business profile updated successfully

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 400: Validation error (field too long

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Request display name change API Reference

Submit a display name change request for the WhatsApp Business account.
The new name must follow WhatsApp naming guidelines (3-512 characters, must represent your business).
Changes require Meta review and approval, which typically takes 1-3 business days.


## GET /v1/whatsapp/business-profile/display-name

**Get display name status**

Fetch the current display name and its Meta review status for a WhatsApp Business account.
Display name changes require Meta approval and can take 1-3 business days.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Display name info retrieved

**Response Body:**

- **success** `boolean`: No description
- **displayName** `object`: 
  - **name** `string`: Current verified display name
  - **status** `string`: Meta review status for the display name - one of: APPROVED, PENDING_REVIEW, DECLINED, NONE
  - **phoneNumber** `string`: Display phone number

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/business-profile/display-name

**Request display name change**

Submit a display name change request for the WhatsApp Business account.
The new name must follow WhatsApp naming guidelines (3-512 characters, must represent your business).
Changes require Meta review and approval, which typically takes 1-3 business days.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **displayName** (required) `string`: New display name (must follow WhatsApp naming guidelines)

### Responses

#### 200: Display name change submitted for review

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description
- **displayName** `object`: 
  - **name** `string`: No description
  - **status** `string`: No description - one of: PENDING_REVIEW

#### 400: Invalid display name (too short

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Update group settings API Reference

Update the subject, description, or join approval mode of a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


## GET /v1/whatsapp/wa-groups/{groupId}

**Get group info**

Retrieve metadata about a WhatsApp group including subject, description,
participants, and settings.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Group info

**Response Body:**

- **success** `boolean`: No description
- **group** `object`: 
  - **id** `string`: No description
  - **subject** `string`: No description
  - **description** `string`: No description
  - **joinApprovalMode** `string`: No description
  - **participants** `array[object]`: 
    - **user** `string`: Phone number
    - **admin** `string`: No description
  - **participantCount** `integer`: No description
  - **createdAt** `integer`: UNIX timestamp
  - **isSuspended** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## POST /v1/whatsapp/wa-groups/{groupId}

**Update group settings**

Update the subject, description, or join approval mode of a WhatsApp group.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Request Body

- **subject** `string`: No description
- **description** `string`: No description
- **joinApprovalMode** `string`: No description - one of: approval_required, auto_approve

### Responses

#### 200: Group updated

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/whatsapp/wa-groups/{groupId}

**Delete group**

Delete a WhatsApp group and remove all participants.

Not available on [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence) numbers. Requires a Cloud API-only number.


### Parameters

- **groupId** (required) in path: Group ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Group deleted

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Update template API Reference

Update a message template's components. Only certain fields can be updated depending on
the template's current approval state. Approved templates can only have components updated.


## GET /v1/whatsapp/templates/{templateName}

**Get template**

Retrieve a single message template by name.


### Parameters

- **templateName** (required) in path: Template name
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Template retrieved successfully

**Response Body:**

- **success** `boolean`: No description
- **template** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description
  - **category** `string`: No description
  - **language** `string`: No description
  - **components** `array[object]`: 
    Type: `object`

#### 400: accountId is required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/whatsapp/templates/{templateName}

**Update template**

Update a message template's components. Only certain fields can be updated depending on
the template's current approval state. Approved templates can only have components updated.


### Parameters

- **templateName** (required) in path: Template name

### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **components** (required) `array`: Updated template components

### Responses

#### 200: Template updated successfully

**Response Body:**

- **success** `boolean`: No description
- **template** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description

#### 400: Validation error (missing fields)

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/whatsapp/templates/{templateName}

**Delete template**

Permanently delete a message template by name.


### Parameters

- **templateName** (required) in path: Template name
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Template deleted successfully

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 400: accountId or template name is required

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Upload profile picture API Reference

Upload a new profile picture for the WhatsApp Business Profile.
Uses Meta's resumable upload API under the hood: creates an upload session,
uploads the image bytes, then updates the business profile with the resulting handle.


## POST /v1/whatsapp/business-profile/photo

**Upload profile picture**

Upload a new profile picture for the WhatsApp Business Profile.
Uses Meta's resumable upload API under the hood: creates an upload session,
uploads the image bytes, then updates the business profile with the resulting handle.


### Request Body


### Responses

#### 200: Profile picture updated successfully

**Response Body:**

- **success** `boolean`: No description
- **message** `string`: No description

#### 400: Invalid file type

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Disable calling on a number API Reference

Disable calling. Sends calling.status=DISABLED to Meta (best-effort)
and flips the local `callingEnabled` flag off. forwardTo and SIP
creds are preserved so a re-enable does not lose the destination.


## POST /v1/whatsapp/phone-numbers/{id}/calling

**Enable calling on a number**

Enable WhatsApp Business Calling on a connected number. Configures
Meta calling.status=ENABLED with our Telnyx SIP endpoint, fetches and
stores the Meta-issued SIP password (encrypted), and snapshots the
customer's forward-to destination.


### Parameters

- **id** (required) in path: WhatsAppPhoneNumber Mongo ID

### Request Body

- **accountId** (required) `string`: No description
- **forwardTo** (required) `string`: tel:+E164 / sip:... / wss://... destination
- **sipAuthUsername** `string`: No description
- **sipAuthPassword** `string`: Stored encrypted
- **recordingEnabled** `boolean`: No description
- **callIconCountries** `array`: No description

### Responses

#### 200: Calling enabled

**Response Body:**

- **success** `boolean`: No description
- **callingEnabled** `boolean`: No description
- **sipHostname** `string`: No description
- **forwardTo** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp phone number not found

#### 422: Not eligible to enable calling: not on usage-based billing, or the number's messaging limit is below Meta's ~2,000-daily-recipient threshold (TIER_250). Warm the number up to raise the limit.

---

## PATCH /v1/whatsapp/phone-numbers/{id}/calling

**Update calling config**

Update fields on an already-enabled number. Only fields present in
the body are written; `undefined` leaves the stored value alone,
explicit `null` clears a nullable field. No Meta side effect, this
only changes local routing state consumed by the Telnyx webhook
handler.


### Parameters

- **id** (required) in path: No description

### Request Body

- **accountId** (required) `string`: No description
- **forwardTo** `string`: No description
- **sipAuthUsername** `string`: No description
- **sipAuthPassword** `string`: No description
- **recordingEnabled** `boolean`: No description
- **callIconCountries** `array`: No description

### Responses

#### 200: Updated

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp phone number not found

#### 422: Calling must be enabled before settings can be updated

---

## DELETE /v1/whatsapp/phone-numbers/{id}/calling

**Disable calling on a number**

Disable calling. Sends calling.status=DISABLED to Meta (best-effort)
and flips the local `callingEnabled` flag off. forwardTo and SIP
creds are preserved so a re-enable does not lose the destination.


### Parameters

- **id** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Disabled

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp phone number not found

---

---

# Enable calling on a number API Reference

Enable WhatsApp Business Calling on a connected number. Configures
Meta calling.status=ENABLED with our Telnyx SIP endpoint, fetches and
stores the Meta-issued SIP password (encrypted), and snapshots the
customer's forward-to destination.


## POST /v1/whatsapp/phone-numbers/{id}/calling

**Enable calling on a number**

Enable WhatsApp Business Calling on a connected number. Configures
Meta calling.status=ENABLED with our Telnyx SIP endpoint, fetches and
stores the Meta-issued SIP password (encrypted), and snapshots the
customer's forward-to destination.


### Parameters

- **id** (required) in path: WhatsAppPhoneNumber Mongo ID

### Request Body

- **accountId** (required) `string`: No description
- **forwardTo** (required) `string`: tel:+E164 / sip:... / wss://... destination
- **sipAuthUsername** `string`: No description
- **sipAuthPassword** `string`: Stored encrypted
- **recordingEnabled** `boolean`: No description
- **callIconCountries** `array`: No description

### Responses

#### 200: Calling enabled

**Response Body:**

- **success** `boolean`: No description
- **callingEnabled** `boolean`: No description
- **sipHostname** `string`: No description
- **forwardTo** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp phone number not found

#### 422: Not eligible to enable calling: not on usage-based billing, or the number's messaging limit is below Meta's ~2,000-daily-recipient threshold (TIER_250). Warm the number up to raise the limit.

---

## PATCH /v1/whatsapp/phone-numbers/{id}/calling

**Update calling config**

Update fields on an already-enabled number. Only fields present in
the body are written; `undefined` leaves the stored value alone,
explicit `null` clears a nullable field. No Meta side effect, this
only changes local routing state consumed by the Telnyx webhook
handler.


### Parameters

- **id** (required) in path: No description

### Request Body

- **accountId** (required) `string`: No description
- **forwardTo** `string`: No description
- **sipAuthUsername** `string`: No description
- **sipAuthPassword** `string`: No description
- **recordingEnabled** `boolean`: No description
- **callIconCountries** `array`: No description

### Responses

#### 200: Updated

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp phone number not found

#### 422: Calling must be enabled before settings can be updated

---

## DELETE /v1/whatsapp/phone-numbers/{id}/calling

**Disable calling on a number**

Disable calling. Sends calling.status=DISABLED to Meta (best-effort)
and flips the local `callingEnabled` flag off. forwardTo and SIP
creds are preserved so a re-enable does not lose the destination.


### Parameters

- **id** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Disabled

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp phone number not found

---

---

# Estimate per-minute cost for a destination API Reference

Returns a zero-markup estimated cost for an outbound call to the
given destination, broken down by Meta + Telnyx + recording line
items. Costs are pass-through, no margin applied.


## GET /v1/whatsapp/calls/estimate

**Estimate per-minute cost for a destination**

Returns a zero-markup estimated cost for an outbound call to the
given destination, broken down by Meta + Telnyx + recording line
items. Costs are pass-through, no margin applied.


### Parameters

- **accountId** (required) in query: No description
- **to** (required) in query: No description
- **minutes** (optional) in query: No description
- **recording** (optional) in query: No description

### Responses

#### 200: Estimate

**Response Body:**

- **destinationCountry** `string`: No description
- **perMinuteUsd** `number`: No description
- **breakdown** `object`: 
  - **metaMinutes** `integer`: No description
  - **metaCostUSD** `number`: Estimated Meta per-minute charge, billed by Meta directly to your WABA. Display only; not billed by Zernio.
  - **telnyxCostUSD** `number`: No description
  - **recordingCostUSD** `number`: No description
  - **billableCostUSD** `number`: Estimated amount Zernio bills you = Telnyx leg + recording (excludes Meta).
  - **totalCostUSD** `number`: Estimated full cost incl. the Meta portion you pay directly. Display only.

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Check call permission for a consumer API Reference

Returns the permission state and the list of available actions for
a given consumer wa_id (e.g. `start_call`, `send_call_permission_request`).
Use this before placing a call to decide whether to prompt for
consent first.


## GET /v1/whatsapp/call-permissions

**Check call permission for a consumer**

Returns the permission state and the list of available actions for
a given consumer wa_id (e.g. `start_call`, `send_call_permission_request`).
Use this before placing a call to decide whether to prompt for
consent first.


### Parameters

- **accountId** (required) in query: No description
- **to** (required) in query: Consumer wa_id (E.164

### Responses

#### 200: Permission state

**Response Body:**

- **permission** `object`: 
  - **status** `string`: No description - one of: temporary, no_permission, permanent
  - **expiration_time** `integer`: Unix seconds when temporary
- **actions** `array[object]`: 
  - **action_name** `string`: No description - one of: send_call_permission_request, start_call
  - **can_perform_action** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Get a single call API Reference



## GET /v1/whatsapp/calls/{callId}

**Get a single call**

### Parameters

- **callId** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Call

**Response Body:**

- **call** `object`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Call not found

---

---

# Get calling config for an account API Reference

Returns the local calling configuration snapshot for the connected
WhatsApp account: whether calling is enabled, the forward-to
destination URI, recording opt-in state, the WhatsAppPhoneNumber
doc id (use as `{id}` on the calling-config write endpoints) and
whether SIP digest credentials are stored (the encrypted password
itself is never returned).


## GET /v1/whatsapp/calling

**Get calling config for an account**

Returns the local calling configuration snapshot for the connected
WhatsApp account: whether calling is enabled, the forward-to
destination URI, recording opt-in state, the WhatsAppPhoneNumber
doc id (use as `{id}` on the calling-config write endpoints) and
whether SIP digest credentials are stored (the encrypted password
itself is never returned).


### Parameters

- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Calling config

**Response Body:**

- **phoneNumberDocId** `string`: WhatsAppPhoneNumber Mongo ID (use on /v1/whatsapp/phone-numbers/{id}/calling)
- **phoneNumber** `string`: No description
- **callingEnabled** `boolean`: No description
- **callDeepLink** `string`: 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** `string`: tel:+E164 / sip:... / wss://... destination
- **recordingEnabled** `boolean`: No description
- **sipAuthUsername** `string`: No description
- **sipAuthPasswordConfigured** `boolean`: True when a SIP digest password is stored. The plaintext is never returned.
- **callIconCountries** `array[string]`: 

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp phone number not found for this account

---

---

# Initiate outbound call API Reference

Initiates an outbound Business-Initiated Call. The Telnyx-side SIP
leg is originated server-side (Option B: SIP-first). Telnyx INVITEs
Meta directly over TLS:5061 with the SIP digest credentials we
captured at calling-enablement time). No client-side SDP is
required; pass only `accountId` and `to`.

To send the consumer the call-consent prompt instead of placing a
call, pass `action: "send_call_permission_request"` (+ optional
`bodyText`). The consumer must tap Allow in WhatsApp before
`start_call` is permitted; Meta limits the prompt to 1 per consumer
per 24h (2 per 7 days) and requires an open 24h service window.


## POST /v1/whatsapp/calls

**Initiate outbound call**

Initiates an outbound Business-Initiated Call. The Telnyx-side SIP
leg is originated server-side (Option B: SIP-first). Telnyx INVITEs
Meta directly over TLS:5061 with the SIP digest credentials we
captured at calling-enablement time). No client-side SDP is
required; pass only `accountId` and `to`.

To send the consumer the call-consent prompt instead of placing a
call, pass `action: "send_call_permission_request"` (+ optional
`bodyText`). The consumer must tap Allow in WhatsApp before
`start_call` is permitted; Meta limits the prompt to 1 per consumer
per 24h (2 per 7 days) and requires an open 24h service window.


### Request Body

- **accountId** (required) `string`: No description
- **to** (required) `string`: Consumer wa_id (E.164
- **action** `string`: Omit to place a call. Set to send the consent prompt instead. - one of: send_call_permission_request
- **bodyText** `string`: Body text shown with the consent prompt (send_call_permission_request only).
- **forwardTo** `string`: Per-call destination override. Same accepted shape as the
number's stored forwardTo (tel:+E164, sip:..., wss://...).

- **recordOverride** `boolean`: No description
- **biz_opaque_callback_data** `string`: Accepted for forward compatibility. Not currently echoed
back in webhook payloads (SIP-first flow does not pass
through Meta's Graph API where Meta would echo this).


### Responses

#### 200: Call originated; lifecycle continues asynchronously via webhooks.

**Response Body:**

- **success** `boolean`: No description
- **callId** `string`: Internal Call doc ID
- **telnyxCallControlId** `string`: Telnyx call_control_id of the outbound leg
- **status** `string`: No description - one of: dialing
- **direction** `string`: No description - one of: outbound
- **to** `string`: No description
- **forwardTo** `string`: No description
- **recordingEnabled** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 409: No active call permission — send a permission request first.

#### 422: Calling not enabled

#### 502: Telnyx-side originate failed; the Call doc has been marked failed.

---

## GET /v1/whatsapp/calls

**List call history for an account**

Compact history listing for a single connected account. Results are
scoped to the resolved SocialAccount; profile-scoped team members
cannot read calls on sibling accounts.


### Parameters

- **accountId** (required) in query: No description
- **status** (optional) in query: No description
- **direction** (optional) in query: No description
- **since** (optional) in query: No description
- **until** (optional) in query: No description
- **limit** (optional) in query: No description

### Responses

#### 200: Calls

**Response Body:**

- **calls** `array[object]`: 
  - **_id** `string`: No description
  - **direction** `string`: No description - one of: inbound, outbound
  - **from** `string`: No description
  - **to** `string`: No description
  - **status** `string`: No description - one of: ringing, answered, ended, failed
  - **startedAt** `string` (date-time): No description
  - **endedAt** `string` (date-time): No description
  - **durationSeconds** `integer`: No description
  - **endReason** `string`: No description - one of: hangup, no_answer, rejected, error
  - **recordingUrl** `string`: No description
  - **billing** `object`: 
    - **metaCostUSD** `number`: Meta per-minute charge, billed by Meta directly to your WABA. Display only; not billed by Zernio.
    - **telnyxCostUSD** `number`: No description
    - **recordingCostUSD** `number`: No description
    - **billableCostUSD** `number`: Amount Zernio bills you = Telnyx leg + recording (excludes Meta).
    - **totalCostUSD** `number`: Full cost incl. the Meta portion you pay directly. Display only.
    - **currency** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# List call history for an account API Reference

Compact history listing for a single connected account. Results are
scoped to the resolved SocialAccount; profile-scoped team members
cannot read calls on sibling accounts.


## POST /v1/whatsapp/calls

**Initiate outbound call**

Initiates an outbound Business-Initiated Call. The Telnyx-side SIP
leg is originated server-side (Option B: SIP-first). Telnyx INVITEs
Meta directly over TLS:5061 with the SIP digest credentials we
captured at calling-enablement time). No client-side SDP is
required; pass only `accountId` and `to`.

To send the consumer the call-consent prompt instead of placing a
call, pass `action: "send_call_permission_request"` (+ optional
`bodyText`). The consumer must tap Allow in WhatsApp before
`start_call` is permitted; Meta limits the prompt to 1 per consumer
per 24h (2 per 7 days) and requires an open 24h service window.


### Request Body

- **accountId** (required) `string`: No description
- **to** (required) `string`: Consumer wa_id (E.164
- **action** `string`: Omit to place a call. Set to send the consent prompt instead. - one of: send_call_permission_request
- **bodyText** `string`: Body text shown with the consent prompt (send_call_permission_request only).
- **forwardTo** `string`: Per-call destination override. Same accepted shape as the
number's stored forwardTo (tel:+E164, sip:..., wss://...).

- **recordOverride** `boolean`: No description
- **biz_opaque_callback_data** `string`: Accepted for forward compatibility. Not currently echoed
back in webhook payloads (SIP-first flow does not pass
through Meta's Graph API where Meta would echo this).


### Responses

#### 200: Call originated; lifecycle continues asynchronously via webhooks.

**Response Body:**

- **success** `boolean`: No description
- **callId** `string`: Internal Call doc ID
- **telnyxCallControlId** `string`: Telnyx call_control_id of the outbound leg
- **status** `string`: No description - one of: dialing
- **direction** `string`: No description - one of: outbound
- **to** `string`: No description
- **forwardTo** `string`: No description
- **recordingEnabled** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 409: No active call permission — send a permission request first.

#### 422: Calling not enabled

#### 502: Telnyx-side originate failed; the Call doc has been marked failed.

---

## GET /v1/whatsapp/calls

**List call history for an account**

Compact history listing for a single connected account. Results are
scoped to the resolved SocialAccount; profile-scoped team members
cannot read calls on sibling accounts.


### Parameters

- **accountId** (required) in query: No description
- **status** (optional) in query: No description
- **direction** (optional) in query: No description
- **since** (optional) in query: No description
- **until** (optional) in query: No description
- **limit** (optional) in query: No description

### Responses

#### 200: Calls

**Response Body:**

- **calls** `array[object]`: 
  - **_id** `string`: No description
  - **direction** `string`: No description - one of: inbound, outbound
  - **from** `string`: No description
  - **to** `string`: No description
  - **status** `string`: No description - one of: ringing, answered, ended, failed
  - **startedAt** `string` (date-time): No description
  - **endedAt** `string` (date-time): No description
  - **durationSeconds** `integer`: No description
  - **endReason** `string`: No description - one of: hangup, no_answer, rejected, error
  - **recordingUrl** `string`: No description
  - **billing** `object`: 
    - **metaCostUSD** `number`: Meta per-minute charge, billed by Meta directly to your WABA. Display only; not billed by Zernio.
    - **telnyxCostUSD** `number`: No description
    - **recordingCostUSD** `number`: No description
    - **billableCostUSD** `number`: Amount Zernio bills you = Telnyx leg + recording (excludes Meta).
    - **totalCostUSD** `number`: Full cost incl. the Meta portion you pay directly. Display only.
    - **currency** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Update calling config API Reference

Update fields on an already-enabled number. Only fields present in
the body are written; `undefined` leaves the stored value alone,
explicit `null` clears a nullable field. No Meta side effect, this
only changes local routing state consumed by the Telnyx webhook
handler.


## POST /v1/whatsapp/phone-numbers/{id}/calling

**Enable calling on a number**

Enable WhatsApp Business Calling on a connected number. Configures
Meta calling.status=ENABLED with our Telnyx SIP endpoint, fetches and
stores the Meta-issued SIP password (encrypted), and snapshots the
customer's forward-to destination.


### Parameters

- **id** (required) in path: WhatsAppPhoneNumber Mongo ID

### Request Body

- **accountId** (required) `string`: No description
- **forwardTo** (required) `string`: tel:+E164 / sip:... / wss://... destination
- **sipAuthUsername** `string`: No description
- **sipAuthPassword** `string`: Stored encrypted
- **recordingEnabled** `boolean`: No description
- **callIconCountries** `array`: No description

### Responses

#### 200: Calling enabled

**Response Body:**

- **success** `boolean`: No description
- **callingEnabled** `boolean`: No description
- **sipHostname** `string`: No description
- **forwardTo** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp phone number not found

#### 422: Not eligible to enable calling: not on usage-based billing, or the number's messaging limit is below Meta's ~2,000-daily-recipient threshold (TIER_250). Warm the number up to raise the limit.

---

## PATCH /v1/whatsapp/phone-numbers/{id}/calling

**Update calling config**

Update fields on an already-enabled number. Only fields present in
the body are written; `undefined` leaves the stored value alone,
explicit `null` clears a nullable field. No Meta side effect, this
only changes local routing state consumed by the Telnyx webhook
handler.


### Parameters

- **id** (required) in path: No description

### Request Body

- **accountId** (required) `string`: No description
- **forwardTo** `string`: No description
- **sipAuthUsername** `string`: No description
- **sipAuthPassword** `string`: No description
- **recordingEnabled** `boolean`: No description
- **callIconCountries** `array`: No description

### Responses

#### 200: Updated

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp phone number not found

#### 422: Calling must be enabled before settings can be updated

---

## DELETE /v1/whatsapp/phone-numbers/{id}/calling

**Disable calling on a number**

Disable calling. Sends calling.status=DISABLED to Meta (best-effort)
and flips the local `callingEnabled` flag off. forwardTo and SIP
creds are preserved so a re-enable does not lose the destination.


### Parameters

- **id** (required) in path: No description
- **accountId** (required) in query: No description

### Responses

#### 200: Disabled

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp phone number not found

---

---

# Create flow API Reference

Create a new WhatsApp Flow in DRAFT status. Optionally clone an existing flow.
After creating, upload a Flow JSON definition, then publish to make it sendable.


## GET /v1/whatsapp/flows

**List flows**

List all WhatsApp Flows for the Business Account (WABA) associated with the given account.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Flows retrieved

**Response Body:**

- **success** `boolean`: No description
- **flows** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description - one of: DRAFT, PUBLISHED, DEPRECATED, BLOCKED, THROTTLED
  - **categories** `array[string]`: 
  - **validation_errors** `array[object]`: 
    Type: `object`
  - **version** `integer`: 1-based version within the flow's clone lineage (Zernio-tracked; Meta has no native versioning). Standalone flows are version 1.
  - **lineageId** `string`: Stable group key for the flow's version lineage (the root flow's ID).

#### 400: WABA ID not found on account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/flows

**Create flow**

Create a new WhatsApp Flow in DRAFT status. Optionally clone an existing flow.
After creating, upload a Flow JSON definition, then publish to make it sendable.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **name** (required) `string`: Flow display name
- **categories** (required) `array`: Flow categories
- **cloneFlowId** `string`: Optional: ID of an existing flow to clone the Flow JSON from
- **asVersion** `boolean`: When cloning, true keeps the clone in cloneFlowId's version lineage (auto-numbered next version); false/absent creates an independent flow. Ignored without cloneFlowId.

### Responses

#### 200: Flow created

**Response Body:**

- **success** `boolean`: No description
- **flow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description (example: "DRAFT")
  - **categories** `array[string]`: 
  - **version** `integer`: Version within the clone lineage
  - **lineageId** `string`: Version-lineage group key

#### 400: Validation error

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Delete flow API Reference

Delete a DRAFT flow. This is irreversible. Only flows in DRAFT status can be deleted.


## GET /v1/whatsapp/flows/{flowId}

**Get flow**

Get details for a specific flow, including status, categories, validation errors, and preview URL.


### Parameters

- **flowId** (required) in path: Flow ID
- **accountId** (required) in query: WhatsApp social account ID
- **fields** (optional) in query: Comma-separated fields to return (default: id,name,status,categories,validation_errors,json_version,preview,data_api_version,endpoint_uri)

### Responses

#### 200: Flow details

**Response Body:**

- **success** `boolean`: No description
- **flow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description
  - **categories** `array[string]`: 
  - **validation_errors** `array[object]`: 
    Type: `object`
  - **json_version** `string`: No description
  - **preview** `object`: 
    - **preview_url** `string`: No description
    - **expires_at** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Flow or account not found

---

## PATCH /v1/whatsapp/flows/{flowId}

**Update flow**

Update metadata (name, categories) of a DRAFT flow. Published flows are immutable.


### Parameters

- **flowId** (required) in path: Flow ID

### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **name** `string`: New flow name
- **categories** `array`: No description

### Responses

#### 200: Flow updated

**Response Body:**

- **success** `boolean`: No description

#### 400: At least one of name or categories is required, or flow is not in DRAFT status

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account or flow not found

---

## DELETE /v1/whatsapp/flows/{flowId}

**Delete flow**

Delete a DRAFT flow. This is irreversible. Only flows in DRAFT status can be deleted.


### Parameters

- **flowId** (required) in path: Flow ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Flow deleted

**Response Body:**

- **success** `boolean`: No description

#### 400: Flow is not in DRAFT status

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account or flow not found

---

---

# Deprecate flow API Reference

Deprecate a PUBLISHED flow. This is irreversible. Deprecated flows cannot be sent
or opened, but existing active sessions may continue until they complete.


## POST /v1/whatsapp/flows/{flowId}/deprecate

**Deprecate flow**

Deprecate a PUBLISHED flow. This is irreversible. Deprecated flows cannot be sent
or opened, but existing active sessions may continue until they complete.


### Parameters

- **flowId** (required) in path: Flow ID

### Request Body

- **accountId** (required) `string`: WhatsApp social account ID

### Responses

#### 200: Flow deprecated

**Response Body:**

- **success** `boolean`: No description

#### 400: Flow is not in PUBLISHED status

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Get flow JSON asset API Reference

Get the flow JSON asset metadata, including a temporary download URL for the Flow JSON file.


## GET /v1/whatsapp/flows/{flowId}/json

**Get flow JSON asset**

Get the flow JSON asset metadata, including a temporary download URL for the Flow JSON file.


### Parameters

- **flowId** (required) in path: Flow ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Flow JSON asset

**Response Body:**

- **success** `boolean`: No description
- **assets** `array[object]`: 
  - **name** `string`: No description (example: "flow.json")
  - **asset_type** `string`: No description (example: "FLOW_JSON")
  - **download_url** `string`: Temporary URL to download the flow JSON

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## PUT /v1/whatsapp/flows/{flowId}/json

**Upload flow JSON**

Upload or update the Flow JSON for a DRAFT flow. The Flow JSON defines all screens,
components (text inputs, dropdowns, date pickers, etc.), and navigation.

Meta validates the JSON on upload and returns any validation errors.
See: https://developers.facebook.com/docs/whatsapp/flows/reference/flowjson


### Parameters

- **flowId** (required) in path: Flow ID

### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **flow_json**: Platform-specific settings (see schema definitions below)

### Responses

#### 200: Flow JSON uploaded

**Response Body:**

- **success** `boolean`: No description
- **validation_errors** `array[object]`: Empty array if valid; otherwise, contains validation error details from Meta
  - **error** `string`: No description
  - **error_type** `string`: No description
  - **message** `string`: No description
  - **line_start** `integer`: No description
  - **line_end** `integer`: No description
  - **column_start** `integer`: No description
  - **column_end** `integer`: No description

#### 400: Invalid JSON or flow is not in DRAFT status

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Get flow preview URL API Reference

Get Meta's public web-preview URL for a flow (drafts included), embeddable as an
interactive iframe. The link is reused across calls (valid ~30 days); pass
invalidate=true to mint a fresh one (the previous link stops working).


## GET /v1/whatsapp/flows/{flowId}/preview

**Get flow preview URL**

Get Meta's public web-preview URL for a flow (drafts included), embeddable as an
interactive iframe. The link is reused across calls (valid ~30 days); pass
invalidate=true to mint a fresh one (the previous link stops working).


### Parameters

- **flowId** (required) in path: Flow ID
- **accountId** (required) in query: WhatsApp social account ID
- **invalidate** (optional) in query: Mint a fresh preview link (default false)

### Responses

#### 200: Preview URL

**Response Body:**

- **preview_url** `string`: No description
- **expires_at** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Flow or account not found

---

---

# Get flow API Reference

Get details for a specific flow, including status, categories, validation errors, and preview URL.


## GET /v1/whatsapp/flows/{flowId}

**Get flow**

Get details for a specific flow, including status, categories, validation errors, and preview URL.


### Parameters

- **flowId** (required) in path: Flow ID
- **accountId** (required) in query: WhatsApp social account ID
- **fields** (optional) in query: Comma-separated fields to return (default: id,name,status,categories,validation_errors,json_version,preview,data_api_version,endpoint_uri)

### Responses

#### 200: Flow details

**Response Body:**

- **success** `boolean`: No description
- **flow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description
  - **categories** `array[string]`: 
  - **validation_errors** `array[object]`: 
    Type: `object`
  - **json_version** `string`: No description
  - **preview** `object`: 
    - **preview_url** `string`: No description
    - **expires_at** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Flow or account not found

---

## PATCH /v1/whatsapp/flows/{flowId}

**Update flow**

Update metadata (name, categories) of a DRAFT flow. Published flows are immutable.


### Parameters

- **flowId** (required) in path: Flow ID

### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **name** `string`: New flow name
- **categories** `array`: No description

### Responses

#### 200: Flow updated

**Response Body:**

- **success** `boolean`: No description

#### 400: At least one of name or categories is required, or flow is not in DRAFT status

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account or flow not found

---

## DELETE /v1/whatsapp/flows/{flowId}

**Delete flow**

Delete a DRAFT flow. This is irreversible. Only flows in DRAFT status can be deleted.


### Parameters

- **flowId** (required) in path: Flow ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Flow deleted

**Response Body:**

- **success** `boolean`: No description

#### 400: Flow is not in DRAFT status

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account or flow not found

---

---

# List flow responses API Reference

List the responses customers submitted when completing a flow (parsed from the
nfm_reply messages received via webhook), newest first. Scope to a single flow
with `flowId` — this matches responses whose flow_token carries the `<flowId>:`
prefix that Zernio stamps on auto-generated tokens at send time. Responses sent
with a custom integrator-supplied flow_token are not attributed to a flow.


## GET /v1/whatsapp/flow-responses

**List flow responses**

List the responses customers submitted when completing a flow (parsed from the
nfm_reply messages received via webhook), newest first. Scope to a single flow
with `flowId` — this matches responses whose flow_token carries the `<flowId>:`
prefix that Zernio stamps on auto-generated tokens at send time. Responses sent
with a custom integrator-supplied flow_token are not attributed to a flow.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID
- **flowId** (optional) in query: Scope to responses for this flow
- **limit** (optional) in query: Max responses to return

### Responses

#### 200: Flow responses

**Response Body:**

- **responses** `array[object]`: 
  - **id** `string`: Message ID
  - **receivedAt** `string` (date-time): No description
  - **from** `string`: Sender wa_id / phone
  - **senderName** `string`: No description
  - **conversationId** `string`: No description
  - **flowToken** `string`: No description
  - **data** `object`: Submitted field values (flow_token removed)
  - **raw** `string`: Raw response_json string

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# List flow versions API Reference

List the flow's version history (the clone lineage Zernio tracks, since Meta has no
native versioning), newest version first. Each entry is enriched with the version's
live name and status from Meta. A flow with no lineage returns just itself as version 1.


## GET /v1/whatsapp/flows/{flowId}/versions

**List flow versions**

List the flow's version history (the clone lineage Zernio tracks, since Meta has no
native versioning), newest version first. Each entry is enriched with the version's
live name and status from Meta. A flow with no lineage returns just itself as version 1.


### Parameters

- **flowId** (required) in path: Flow ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Version history

**Response Body:**

- **versions** `array[object]`: 
  - **flowId** `string`: No description
  - **version** `integer`: No description
  - **parentFlowId** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description
  - **missing** `boolean`: True when Meta no longer has this flow

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Flow or account not found

---

---

# List flows API Reference

List all WhatsApp Flows for the Business Account (WABA) associated with the given account.


## GET /v1/whatsapp/flows

**List flows**

List all WhatsApp Flows for the Business Account (WABA) associated with the given account.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Flows retrieved

**Response Body:**

- **success** `boolean`: No description
- **flows** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description - one of: DRAFT, PUBLISHED, DEPRECATED, BLOCKED, THROTTLED
  - **categories** `array[string]`: 
  - **validation_errors** `array[object]`: 
    Type: `object`
  - **version** `integer`: 1-based version within the flow's clone lineage (Zernio-tracked; Meta has no native versioning). Standalone flows are version 1.
  - **lineageId** `string`: Stable group key for the flow's version lineage (the root flow's ID).

#### 400: WABA ID not found on account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## POST /v1/whatsapp/flows

**Create flow**

Create a new WhatsApp Flow in DRAFT status. Optionally clone an existing flow.
After creating, upload a Flow JSON definition, then publish to make it sendable.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **name** (required) `string`: Flow display name
- **categories** (required) `array`: Flow categories
- **cloneFlowId** `string`: Optional: ID of an existing flow to clone the Flow JSON from
- **asVersion** `boolean`: When cloning, true keeps the clone in cloneFlowId's version lineage (auto-numbered next version); false/absent creates an independent flow. Ignored without cloneFlowId.

### Responses

#### 200: Flow created

**Response Body:**

- **success** `boolean`: No description
- **flow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description (example: "DRAFT")
  - **categories** `array[string]`: 
  - **version** `integer`: Version within the clone lineage
  - **lineageId** `string`: Version-lineage group key

#### 400: Validation error

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Publish flow API Reference

Publish a DRAFT flow. This is irreversible. Once published, the flow and its JSON
become immutable and the flow can be sent to users. To update a published flow,
create a new flow (optionally cloning this one via cloneFlowId).


## POST /v1/whatsapp/flows/{flowId}/publish

**Publish flow**

Publish a DRAFT flow. This is irreversible. Once published, the flow and its JSON
become immutable and the flow can be sent to users. To update a published flow,
create a new flow (optionally cloning this one via cloneFlowId).


### Parameters

- **flowId** (required) in path: Flow ID

### Request Body

- **accountId** (required) `string`: WhatsApp social account ID

### Responses

#### 200: Flow published

**Response Body:**

- **success** `boolean`: No description

#### 400: Flow is not in DRAFT status or has validation errors

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Send flow message API Reference

Send a published flow as an interactive message with a CTA button.
When the recipient taps the button, the flow opens natively in WhatsApp.
Flow responses are received via webhooks.


## POST /v1/whatsapp/flows/send

**Send flow message**

Send a published flow as an interactive message with a CTA button.
When the recipient taps the button, the flow opens natively in WhatsApp.
Flow responses are received via webhooks.


### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **to** (required) `string`: Recipient phone number (E.164 format, e.g. +1234567890)
- **flow_id** (required) `string`: Published flow ID
- **flow_cta** (required) `string`: CTA button text (e.g. 'Book Now', 'Sign Up')
- **flow_action** `string`: Action type: navigate opens a screen directly, data_exchange hits your endpoint first - one of: navigate, data_exchange
- **flow_token** `string`: 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** `object`: No description
- **body** (required) `string`: Message body text
- **header** `object`: No description
- **footer** `string`: Optional footer text
- **draft** `boolean`: Set true to test an unpublished (DRAFT) flow

### Responses

#### 200: Flow message sent

**Response Body:**

- **success** `boolean`: No description
- **messageId** `string`: WhatsApp message ID (WAMID)

#### 400: Validation error or missing phone number ID

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Update flow API Reference

Update metadata (name, categories) of a DRAFT flow. Published flows are immutable.


## GET /v1/whatsapp/flows/{flowId}

**Get flow**

Get details for a specific flow, including status, categories, validation errors, and preview URL.


### Parameters

- **flowId** (required) in path: Flow ID
- **accountId** (required) in query: WhatsApp social account ID
- **fields** (optional) in query: Comma-separated fields to return (default: id,name,status,categories,validation_errors,json_version,preview,data_api_version,endpoint_uri)

### Responses

#### 200: Flow details

**Response Body:**

- **success** `boolean`: No description
- **flow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **status** `string`: No description
  - **categories** `array[string]`: 
  - **validation_errors** `array[object]`: 
    Type: `object`
  - **json_version** `string`: No description
  - **preview** `object`: 
    - **preview_url** `string`: No description
    - **expires_at** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Flow or account not found

---

## PATCH /v1/whatsapp/flows/{flowId}

**Update flow**

Update metadata (name, categories) of a DRAFT flow. Published flows are immutable.


### Parameters

- **flowId** (required) in path: Flow ID

### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **name** `string`: New flow name
- **categories** `array`: No description

### Responses

#### 200: Flow updated

**Response Body:**

- **success** `boolean`: No description

#### 400: At least one of name or categories is required, or flow is not in DRAFT status

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account or flow not found

---

## DELETE /v1/whatsapp/flows/{flowId}

**Delete flow**

Delete a DRAFT flow. This is irreversible. Only flows in DRAFT status can be deleted.


### Parameters

- **flowId** (required) in path: Flow ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Flow deleted

**Response Body:**

- **success** `boolean`: No description

#### 400: Flow is not in DRAFT status

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account or flow not found

---

---

# Upload flow JSON API Reference

Upload or update the Flow JSON for a DRAFT flow. The Flow JSON defines all screens,
components (text inputs, dropdowns, date pickers, etc.), and navigation.

Meta validates the JSON on upload and returns any validation errors.
See: https://developers.facebook.com/docs/whatsapp/flows/reference/flowjson


## GET /v1/whatsapp/flows/{flowId}/json

**Get flow JSON asset**

Get the flow JSON asset metadata, including a temporary download URL for the Flow JSON file.


### Parameters

- **flowId** (required) in path: Flow ID
- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Flow JSON asset

**Response Body:**

- **success** `boolean`: No description
- **assets** `array[object]`: 
  - **name** `string`: No description (example: "flow.json")
  - **asset_type** `string`: No description (example: "FLOW_JSON")
  - **download_url** `string`: Temporary URL to download the flow JSON

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

## PUT /v1/whatsapp/flows/{flowId}/json

**Upload flow JSON**

Upload or update the Flow JSON for a DRAFT flow. The Flow JSON defines all screens,
components (text inputs, dropdowns, date pickers, etc.), and navigation.

Meta validates the JSON on upload and returns any validation errors.
See: https://developers.facebook.com/docs/whatsapp/flows/reference/flowjson


### Parameters

- **flowId** (required) in path: Flow ID

### Request Body

- **accountId** (required) `string`: WhatsApp social account ID
- **flow_json**: Platform-specific settings (see schema definitions below)

### Responses

#### 200: Flow JSON uploaded

**Response Body:**

- **success** `boolean`: No description
- **validation_errors** `array[object]`: Empty array if valid; otherwise, contains validation error details from Meta
  - **error** `string`: No description
  - **error_type** `string`: No description
  - **message** `string`: No description
  - **line_start** `integer`: No description
  - **line_end** `integer`: No description
  - **column_start** `integer`: No description
  - **column_end** `integer`: No description

#### 400: Invalid JSON or flow is not in DRAFT status

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Check a country's availability + address constraint API Reference

Pre-purchase check, so you can warn BEFORE a customer invests in KYC
(regulated review is async, 1-3 days). Tells you whether we have
deliverable inventory, and what address the customer needs:
  - `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.
  - `addressConstraint: country` → any in-country address works.
  - `addressConstraint: none` → field-only / instant country, no address.
Call this before starting the KYC form for regulated countries.


## GET /v1/whatsapp/phone-numbers/availability

**Check a country's availability + address constraint**

Pre-purchase check, so you can warn BEFORE a customer invests in KYC
(regulated review is async, 1-3 days). Tells you whether we have
deliverable inventory, and what address the customer needs:
  - `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.
  - `addressConstraint: country` → any in-country address works.
  - `addressConstraint: none` → field-only / instant country, no address.
Call this before starting the KYC form for regulated countries.


### Parameters

- **country** (required) in query: ISO-2 country code.

### Responses

#### 200: Availability + address constraint.

**Response Body:**

- **country** `string`: No description
- **numberType** `string`: No description
- **available** `boolean`: Whether deliverable voice inventory exists right now.
- **addressConstraint** `string`: No description - one of: geo, country, none
- **areas** `array[string]`: For `geo` only — the area(s) the registered address must be in.

#### 400: Country not offerable

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Get number status API Reference

Live snapshot of a connected number straight from Meta: the phone-number node
(display number, display name + approval, quality rating, messaging-limit tier,
throughput, official-business badge, connection status, health_status) and its
owning WhatsApp Business Account (name, business verification, timezone,
health_status). Fetched live because Meta updates quality/tier/name/health over
time; the call also refreshes the cached values shown on the connection card.


## GET /v1/whatsapp/number-info

**Get number status**

Live snapshot of a connected number straight from Meta: the phone-number node
(display number, display name + approval, quality rating, messaging-limit tier,
throughput, official-business badge, connection status, health_status) and its
owning WhatsApp Business Account (name, business verification, timezone,
health_status). Fetched live because Meta updates quality/tier/name/health over
time; the call also refreshes the cached values shown on the connection card.


### Parameters

- **accountId** (required) in query: WhatsApp social account ID

### Responses

#### 200: Number + WABA status

**Response Body:**

- **phone** `object`: 
  - **display_phone_number** `string`: No description
  - **verified_name** `string`: No description
  - **name_status** `string`: APPROVED, AVAILABLE_WITHOUT_REVIEW, PENDING_REVIEW, DECLINED, EXPIRED, NONE
  - **quality_rating** `string`: GREEN, YELLOW, RED, UNKNOWN
  - **messaging_limit_tier** `string`: e.g. TIER_250, TIER_1K, TIER_UNLIMITED
  - **throughput** `object`: 
    - **level** `string`: STANDARD or HIGH
  - **status** `string`: e.g. CONNECTED
  - **is_official_business_account** `boolean`: No description
  - **platform_type** `string`: e.g. CLOUD_API
  - **health_status** `object`: Meta's can_send_message health object (messaging + calling signals)
- **waba** `object`: 
  - **name** `string`: No description
  - **business_verification_status** `string`: verified, not_verified, pending, ...
  - **timezone_id** `string`: Meta integer timezone-enum id
  - **health_status** `object`: No description

#### 400: Phone number ID not found on account

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: WhatsApp account not found

---

---

# Get regulated-number KYC form spec API Reference

For a Tier 3/4 country, the fields the end customer must provide (Telnyx
regulatory requirements) before a number can be ordered: text, date,
address, or file (document) per requirement.


## GET /v1/whatsapp/phone-numbers/kyc

**Get regulated-number KYC form spec**

For a Tier 3/4 country, the fields the end customer must provide (Telnyx
regulatory requirements) before a number can be ordered: text, date,
address, or file (document) per requirement.


### Parameters

- **country** (required) in query: No description
- **profileId** (required) in query: No description

### Responses

#### 200: The KYC form spec.

**Response Body:**

- **country** `string`: No description
- **numberType** `string`: No description
- **fields** `array[object]`: 
  - **requirementId** `string`: No description
  - **label** `string`: No description
  - **kind** `string`: "action" = an out-of-band verification (e.g. Onfido); not filled here, fulfilled after the order via a link. - one of: text, date, address, file, action
  - **description** `string`: Plain-English explanation of what to provide.
  - **example** `string`: Concrete example value.
  - **localTo** `string`: ISO country the value must be local to
- **reusable** `object`: Present when this account already has an approved verification for the country that can be reused (skip the form). `fromPhoneNumber`/`details` mirror the newest option; `options` lists ALL approved verifications (agencies hold one per end client) — pass the chosen option's `fromPhoneNumber` as `reuseFrom` on POST.
  - **available** `boolean`: No description
  - **fromPhoneNumber** `string`: No description
  - **details** `array[object]`: 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.
    - **label** `string`: No description
    - **value** `string`: No description
  - **options** `array[object]`: One entry per distinct approved verification, newest first.
    - **fromPhoneNumber** `string`: No description
    - **details** `array[object]`: 
      - **label** `string`: No description
      - **value** `string`: No description

#### 400: Country not available

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/whatsapp/phone-numbers/kyc

**Submit regulated-number KYC**

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. Builds + submits a
regulatory requirement group and claims a pending_regulatory slot; the
number is ordered + activated once the provider approves (asynchronous).
A customer may hold several same-country numbers in review at once; a
double-submit of the SAME attempt is deduped via `submissionId`.

For 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). A one-sided ID is a common decline
reason; fix it via POST /v1/whatsapp/phone-numbers/{id}/remediate.

Before 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.


### Request Body

- **profileId** (required) `string`: No description
- **country** (required) `string`: No description
- **submissionId** `string`: Idempotency token for this submission attempt. A retry/double-submit with the same token returns the same number; omit and each call creates a new number.
- **reuse** `boolean`: Reuse a prior approved verification for this country (skips document/field collection; places the order immediately).
- **reuseFrom** `string`: Which approved verification to reuse when several exist: the phone number it was originally approved for (GET reusable.options[].fromPhoneNumber). Omitted = newest. No match = 409.
- **endUserFirstName** `string`: End user's legal first name. Required when the country has an action/ID-verification (Onfido) requirement.
- **endUserLastName** `string`: End user's legal last name. Same condition as endUserFirstName.
- **values** `object`: requirementId → textual value
- **documents** `array`: 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).
- **address** `object`: No description

### Responses

#### 200: KYC submitted (or already submitted); number pending review.

**Response Body:**

- **status** `string`: No description - one of: kyc_submitted, kyc_reused, kyc_already_submitted
- **phoneNumber** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description
  - **country** `string`: No description

#### 400: Validation error (e.g. address not in-country

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 409: reuse requested but no prior approved verification exists for this country

---

---

# Get the declined requirements to fix API Reference

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).
The customer fixes just those — Telnyx supports correcting a declined
requirement group and re-submitting it (no new number/group). Falls back
to the full spec if the provider exposes no per-requirement flags.


## GET /v1/whatsapp/phone-numbers/{id}/remediate

**Get the declined requirements to fix**

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).
The customer fixes just those — Telnyx supports correcting a declined
requirement group and re-submitting it (no new number/group). Falls back
to the full spec if the provider exposes no per-requirement flags.


### Parameters

- **id** (required) in path: WhatsAppPhoneNumber id.

### Responses

#### 200: The declined requirements to fix.

**Response Body:**

- **country** `string`: No description
- **numberType** `string`: No description
- **declineReason** `string`: No description
- **fields** `array[object]`: Same field shape as GET /v1/whatsapp/phone-numbers/kyc.
  Type: `object`

#### 400: Number is not awaiting remediation

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Number not found

---

## POST /v1/whatsapp/phone-numbers/{id}/remediate

**Fix a declined number and re-submit**

Submit corrected values/documents for the declined requirement(s). We
PATCH them onto the SAME requirement group and re-submit it for approval;
the number goes `regulatory_declined` → `pending_regulatory`. No new
number and no new billing. Body shape matches the KYC submit (values /
documents / address) — send only the corrected fields.


### Parameters

- **id** (required) in path: No description

### Request Body

- **values** `object`: No description
- **documents** `array`: No description
- **address** `object`: Same shape as the KYC submit address.

### Responses

#### 200: Re-submitted for approval.

**Response Body:**

- **status** `string`: No description (example: "resubmitted")
- **phoneNumber** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description

#### 400: Number is not awaiting remediation / nothing to remediate

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Number not found

---

---

# Get phone number API Reference

Retrieve the current status of a purchased phone number. Poll this to
track Meta pre-verification (US sync path) and, for regulated (Tier 3/4)
numbers, the async lifecycle: pending_regulatory → active (or
regulatory_declined). When a regulated number has an Onfido ID step,
`onfidoVerificationUrl` appears here once the order is placed — forward
it to the end user. (Or subscribe to the whatsapp.number.* webhooks
instead of polling.)


## GET /v1/whatsapp/phone-numbers/{phoneNumberId}

**Get phone number**

Retrieve the current status of a purchased phone number. Poll this to
track Meta pre-verification (US sync path) and, for regulated (Tier 3/4)
numbers, the async lifecycle: pending_regulatory → active (or
regulatory_declined). When a regulated number has an Onfido ID step,
`onfidoVerificationUrl` appears here once the order is placed — forward
it to the end user. (Or subscribe to the whatsapp.number.* webhooks
instead of polling.)


### Parameters

- **phoneNumberId** (required) in path: Phone number record ID

### Responses

#### 200: Phone number retrieved successfully

**Response Body:**

- **phoneNumber** `object`: 
  - **id** `string`: No description
  - **phoneNumber** `string`: No description
  - **status** `string`: No description - one of: pending_payment, pending_regulatory, regulatory_declined, provisioning, verifying, active, suspended, releasing, released
  - **country** `string`: No description
  - **metaPreverifiedId** `string`: No description
  - **metaVerificationStatus** `string`: No description
  - **onfidoVerificationUrl** `string`: 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** `string`: No description
  - **endUserLastName** `string`: No description
  - **regulatoryDeclineReason** `string`: Reviewer rejection reason when status is regulatory_declined.
  - **provisionedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/whatsapp/phone-numbers/{phoneNumberId}

**Release phone number**

Release a purchased phone number. This will:
1. Disconnect any linked WhatsApp social account
2. Decrement the Stripe subscription quantity (or cancel if last number)
3. Release the number from Telnyx
4. Mark the number as released


### Parameters

- **phoneNumberId** (required) in path: Phone number record ID

### Responses

#### 200: Phone number released successfully

**Response Body:**

- **message** `string`: No description
- **phoneNumber** `object`: 
  - **id** `string`: No description
  - **phoneNumber** `string`: No description
  - **status** `string`: "released"
  - **releasedAt** `string` (date-time): No description

#### 400: Phone number is already released or being released

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List phone numbers API Reference

List all WhatsApp phone numbers purchased by the authenticated user.
By default, released numbers are excluded. Connected (bring-your-own)
numbers are returned in the separate `connected` array — they are not
billed and have no provisioning lifecycle.


## GET /v1/whatsapp/phone-numbers

**List phone numbers**

List all WhatsApp phone numbers purchased by the authenticated user.
By default, released numbers are excluded. Connected (bring-your-own)
numbers are returned in the separate `connected` array — they are not
billed and have no provisioning lifecycle.


### Parameters

- **status** (optional) in query: Filter by status (by default excludes released numbers). NOTE:
`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/whatsapp/phone-numbers/{id}/remediate. `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`.

- **profileId** (optional) in query: Filter by profile

### Responses

#### 200: Phone numbers retrieved successfully

**Response Body:**

- **numbers** `array[object]`: 
  - **_id** `string`: No description
  - **phoneNumber** `string`: No description
  - **country** `string`: No description
  - **status** `string`: No description - one of: pending_payment, pending_regulatory, regulatory_declined, provisioning, verifying, active, suspended, releasing, released
  - **registrantName** `string`: For regulated numbers
  - **telnyxOrderId** `string`: Present once the number order has been placed (i.e. the requirement group was approved). Absent while still in identity review.
  - **monthlyCents** `integer`: Per-country monthly price in cents ($2..$25).
  - **profileId** `object`: No description
  - **provisionedAt** `string` (date-time): No description
  - **metaPreverifiedId** `string`: No description
  - **metaVerificationStatus** `string`: No description
  - **onfidoVerificationUrl** `string`: 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.
  - **endUserFirstName** `string`: No description
  - **endUserLastName** `string`: No description
  - **regulatoryDeclineReason** `string`: Reviewer rejection reason when status is regulatory_declined.
  - **createdAt** `string` (date-time): No description
- **connected** `array[object]`: Connected (bring-your-own) WhatsApp numbers — your own WABA
numbers linked via Embedded Signup. Not provisioned or billed
by Zernio, so they are not in `numbers`; `accountId` is the
social-account id used by the messaging and inbox endpoints.
Included only on the default and `status=active` views.

  - **accountId** `string`: No description
  - **phoneNumber** `string`: No description
  - **displayName** `string`: No description
  - **profileId** `string`: No description
  - **connectedAt** `string` (date-time): No description
- **sandbox** `object`: The shared WhatsApp sandbox (one Zernio-owned number, all users test
against it). Present when the sandbox is configured; null otherwise.
The `accountId` lets you address the sandbox in compose endpoints.
`template` is the only template a sandbox send is allowed to use.

  - **phoneNumber** `string`: No description (example: "+12029087457")
  - **accountId** `string`: No description
  - **template** `object`: 
    - **name** `string`: No description (example: "sandbox_start")
    - **language** `string`: No description (example: "en")
  - **isSandbox** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# List offerable number countries API Reference

The WhatsApp number countries available to purchase, each with its flat
monthly price (cents), regulatory tier, whether it needs end-user KYC
(Tier 3/4), and whether outbound calling is available (not BIC-blocked).
Drives the country picker. Tier-4 countries appear only when enabled.


## GET /v1/whatsapp/phone-numbers/countries

**List offerable number countries**

The WhatsApp number countries available to purchase, each with its flat
monthly price (cents), regulatory tier, whether it needs end-user KYC
(Tier 3/4), and whether outbound calling is available (not BIC-blocked).
Drives the country picker. Tier-4 countries appear only when enabled.


### Responses

#### 200: Offerable countries, cheapest first.

**Response Body:**

- **countries** `array[object]`: 
  - **code** `string`: ISO 3166-1 alpha-2
  - **tier** `integer`: No description - one of: 1, 2, 3, 4
  - **monthlyCents** `integer`: No description
  - **needsKyc** `boolean`: No description
  - **outboundCallingAvailable** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Purchase phone number API Reference

Initiate purchasing a WhatsApp phone number. Payment-first flow: the user does not pick
a specific number. The system either creates a Stripe Checkout Session (first number)
or increments the existing subscription quantity and provisions inline (subsequent numbers).

Requires a paid plan. The maximum number of phone numbers is determined by the user's plan.


## POST /v1/whatsapp/phone-numbers/purchase

**Purchase phone number**

Initiate purchasing a WhatsApp phone number. Payment-first flow: the user does not pick
a specific number. The system either creates a Stripe Checkout Session (first number)
or increments the existing subscription quantity and provisions inline (subsequent numbers).

Requires a paid plan. The maximum number of phone numbers is determined by the user's plan.


### Request Body

- **profileId** (required) `string`: Profile to associate the number with
- **country** `string`: 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.

- **purchaseIntentId** `string`: 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.

- **allowMultiple** `boolean`: 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).


### Responses

#### 200: Either a checkout URL (first number) or the provisioned phone number (subsequent numbers).


**Response Body:**

*One of the following:*
  - **message** `string`: No description
  - **checkoutUrl** `string` (uri): No description
  - **message** `string`: No description
  - **phoneNumber** `object`: 
    - **id** `string`: No description
    - **phoneNumber** `string`: No description
    - **status** `string`: No description
    - **country** `string`: No description
    - **provisionedAt** `string` (date-time): No description
    - **metaPreverifiedId** `string`: No description
    - **metaVerificationStatus** `string`: No description
  - **status** `string`: No description - one of: already_purchased
  - **numberId** `string`: No description
  - **phoneNumber** `string`: No description

#### 202: Country requires end-user KYC before the number can be ordered.

**Response Body:**

- **status** `string`: No description - one of: kyc_required
- **country** `string`: No description
- **kycUrl** `string`: No description

#### 400: Plan limit reached

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 402: Payment method required (Metronome user with no card on file). Response body carries code: PAYMENT_REQUIRED; add a card, then retry.

#### 403: A paid plan is required

#### 409: Duplicate-purchase protection: another number was purchased for this user within the last 10 minutes. Retry with allowMultiple: true to confirm the additional purchase is intentional.


**Response Body:**

- **error** `string`: No description
- **code** `string`: No description - one of: PURCHASE_VELOCITY

#### 422: International numbers require usage-based billing (legacy Stripe users are US-only). Response body code: USAGE_BILLING_REQUIRED.

---

---

# Release phone number API Reference

Release a purchased phone number. This will:
1. Disconnect any linked WhatsApp social account
2. Decrement the Stripe subscription quantity (or cancel if last number)
3. Release the number from Telnyx
4. Mark the number as released


## GET /v1/whatsapp/phone-numbers/{phoneNumberId}

**Get phone number**

Retrieve the current status of a purchased phone number. Poll this to
track Meta pre-verification (US sync path) and, for regulated (Tier 3/4)
numbers, the async lifecycle: pending_regulatory → active (or
regulatory_declined). When a regulated number has an Onfido ID step,
`onfidoVerificationUrl` appears here once the order is placed — forward
it to the end user. (Or subscribe to the whatsapp.number.* webhooks
instead of polling.)


### Parameters

- **phoneNumberId** (required) in path: Phone number record ID

### Responses

#### 200: Phone number retrieved successfully

**Response Body:**

- **phoneNumber** `object`: 
  - **id** `string`: No description
  - **phoneNumber** `string`: No description
  - **status** `string`: No description - one of: pending_payment, pending_regulatory, regulatory_declined, provisioning, verifying, active, suspended, releasing, released
  - **country** `string`: No description
  - **metaPreverifiedId** `string`: No description
  - **metaVerificationStatus** `string`: No description
  - **onfidoVerificationUrl** `string`: 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** `string`: No description
  - **endUserLastName** `string`: No description
  - **regulatoryDeclineReason** `string`: Reviewer rejection reason when status is regulatory_declined.
  - **provisionedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/whatsapp/phone-numbers/{phoneNumberId}

**Release phone number**

Release a purchased phone number. This will:
1. Disconnect any linked WhatsApp social account
2. Decrement the Stripe subscription quantity (or cancel if last number)
3. Release the number from Telnyx
4. Mark the number as released


### Parameters

- **phoneNumberId** (required) in path: Phone number record ID

### Responses

#### 200: Phone number released successfully

**Response Body:**

- **message** `string`: No description
- **phoneNumber** `object`: 
  - **id** `string`: No description
  - **phoneNumber** `string`: No description
  - **status** `string`: "released"
  - **releasedAt** `string` (date-time): No description

#### 400: Phone number is already released or being released

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Fix a declined number and re-submit API Reference

Submit corrected values/documents for the declined requirement(s). We
PATCH them onto the SAME requirement group and re-submit it for approval;
the number goes `regulatory_declined` → `pending_regulatory`. No new
number and no new billing. Body shape matches the KYC submit (values /
documents / address) — send only the corrected fields.


## GET /v1/whatsapp/phone-numbers/{id}/remediate

**Get the declined requirements to fix**

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).
The customer fixes just those — Telnyx supports correcting a declined
requirement group and re-submitting it (no new number/group). Falls back
to the full spec if the provider exposes no per-requirement flags.


### Parameters

- **id** (required) in path: WhatsAppPhoneNumber id.

### Responses

#### 200: The declined requirements to fix.

**Response Body:**

- **country** `string`: No description
- **numberType** `string`: No description
- **declineReason** `string`: No description
- **fields** `array[object]`: Same field shape as GET /v1/whatsapp/phone-numbers/kyc.
  Type: `object`

#### 400: Number is not awaiting remediation

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Number not found

---

## POST /v1/whatsapp/phone-numbers/{id}/remediate

**Fix a declined number and re-submit**

Submit corrected values/documents for the declined requirement(s). We
PATCH them onto the SAME requirement group and re-submit it for approval;
the number goes `regulatory_declined` → `pending_regulatory`. No new
number and no new billing. Body shape matches the KYC submit (values /
documents / address) — send only the corrected fields.


### Parameters

- **id** (required) in path: No description

### Request Body

- **values** `object`: No description
- **documents** `array`: No description
- **address** `object`: Same shape as the KYC submit address.

### Responses

#### 200: Re-submitted for approval.

**Response Body:**

- **status** `string`: No description (example: "resubmitted")
- **phoneNumber** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description

#### 400: Number is not awaiting remediation / nothing to remediate

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Number not found

---

---

# Search available numbers to purchase API Reference

Search the provider's inventory for numbers available to purchase in a
country (default US). Optional filters narrow the results. The country
must be offerable (see GET /v1/whatsapp/phone-numbers/countries).


## GET /v1/whatsapp/phone-numbers/available

**Search available numbers to purchase**

Search the provider's inventory for numbers available to purchase in a
country (default US). Optional filters narrow the results. The country
must be offerable (see GET /v1/whatsapp/phone-numbers/countries).


### Parameters

- **country** (optional) in query: No description
- **type** (optional) in query: Number type; defaults to the country's WhatsApp-safe type
- **prefix** (optional) in query: Area code
- **locality** (optional) in query: City
- **contains** (optional) in query: Pattern to match within the number
- **limit** (optional) in query: No description

### Responses

#### 200: Available numbers.

**Response Body:**

- **country** `string`: No description
- **numberType** `string`: No description
- **numbers** `array[object]`: 
  - **phoneNumber** `string`: No description

#### 400: Country not available

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Submit regulated-number KYC API Reference

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. Builds + submits a
regulatory requirement group and claims a pending_regulatory slot; the
number is ordered + activated once the provider approves (asynchronous).
A customer may hold several same-country numbers in review at once; a
double-submit of the SAME attempt is deduped via `submissionId`.

For 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). A one-sided ID is a common decline
reason; fix it via POST /v1/whatsapp/phone-numbers/{id}/remediate.

Before 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.


## GET /v1/whatsapp/phone-numbers/kyc

**Get regulated-number KYC form spec**

For a Tier 3/4 country, the fields the end customer must provide (Telnyx
regulatory requirements) before a number can be ordered: text, date,
address, or file (document) per requirement.


### Parameters

- **country** (required) in query: No description
- **profileId** (required) in query: No description

### Responses

#### 200: The KYC form spec.

**Response Body:**

- **country** `string`: No description
- **numberType** `string`: No description
- **fields** `array[object]`: 
  - **requirementId** `string`: No description
  - **label** `string`: No description
  - **kind** `string`: "action" = an out-of-band verification (e.g. Onfido); not filled here, fulfilled after the order via a link. - one of: text, date, address, file, action
  - **description** `string`: Plain-English explanation of what to provide.
  - **example** `string`: Concrete example value.
  - **localTo** `string`: ISO country the value must be local to
- **reusable** `object`: Present when this account already has an approved verification for the country that can be reused (skip the form). `fromPhoneNumber`/`details` mirror the newest option; `options` lists ALL approved verifications (agencies hold one per end client) — pass the chosen option's `fromPhoneNumber` as `reuseFrom` on POST.
  - **available** `boolean`: No description
  - **fromPhoneNumber** `string`: No description
  - **details** `array[object]`: 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.
    - **label** `string`: No description
    - **value** `string`: No description
  - **options** `array[object]`: One entry per distinct approved verification, newest first.
    - **fromPhoneNumber** `string`: No description
    - **details** `array[object]`: 
      - **label** `string`: No description
      - **value** `string`: No description

#### 400: Country not available

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/whatsapp/phone-numbers/kyc

**Submit regulated-number KYC**

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. Builds + submits a
regulatory requirement group and claims a pending_regulatory slot; the
number is ordered + activated once the provider approves (asynchronous).
A customer may hold several same-country numbers in review at once; a
double-submit of the SAME attempt is deduped via `submissionId`.

For 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). A one-sided ID is a common decline
reason; fix it via POST /v1/whatsapp/phone-numbers/{id}/remediate.

Before 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.


### Request Body

- **profileId** (required) `string`: No description
- **country** (required) `string`: No description
- **submissionId** `string`: Idempotency token for this submission attempt. A retry/double-submit with the same token returns the same number; omit and each call creates a new number.
- **reuse** `boolean`: Reuse a prior approved verification for this country (skips document/field collection; places the order immediately).
- **reuseFrom** `string`: Which approved verification to reuse when several exist: the phone number it was originally approved for (GET reusable.options[].fromPhoneNumber). Omitted = newest. No match = 409.
- **endUserFirstName** `string`: End user's legal first name. Required when the country has an action/ID-verification (Onfido) requirement.
- **endUserLastName** `string`: End user's legal last name. Same condition as endUserFirstName.
- **values** `object`: requirementId → textual value
- **documents** `array`: 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).
- **address** `object`: No description

### Responses

#### 200: KYC submitted (or already submitted); number pending review.

**Response Body:**

- **status** `string`: No description - one of: kyc_submitted, kyc_reused, kyc_already_submitted
- **phoneNumber** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description
  - **country** `string`: No description

#### 400: Validation error (e.g. address not in-country

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 409: reuse requested but no prior approved verification exists for this country

---

---

# Upload a single regulated-number KYC document API Reference

Upload ONE document and get back its provider document id, to reference
from POST /v1/whatsapp/phone-numbers/kyc via `documents[].documentId`.
Send the RAW file bytes as the request body (not base64); put the filename
in the `X-Filename` header. Uploading documents one-per-request keeps each
request under the ~4.5MB body limit. The document streams straight to the
number provider and is not stored by Zernio.


## POST /v1/whatsapp/phone-numbers/kyc/upload-document

**Upload a single regulated-number KYC document**

Upload ONE document and get back its provider document id, to reference
from POST /v1/whatsapp/phone-numbers/kyc via `documents[].documentId`.
Send the RAW file bytes as the request body (not base64); put the filename
in the `X-Filename` header. Uploading documents one-per-request keeps each
request under the ~4.5MB body limit. The document streams straight to the
number provider and is not stored by Zernio.


### Parameters

- **X-Filename** (required) in header: URL-encoded original filename.

### Request Body


### Responses

#### 200: Document uploaded.

**Response Body:**

- **documentId** `string`: Reference this id in the KYC submit's documents[].documentId.

#### 400: Missing X-Filename, empty body, or file too large (over 20MB).

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Pre-validate a regulated-number KYC address (Tier 4) API Reference

Optional early check for the address step of a Tier 4 (end-user identity)
registration: validates a postal address for deliverability BEFORE the full
KYC submit, so it can be corrected before any documents are uploaded. The
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. Only
the postal address is sent (no documents, no gov-ID fields). 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).


## POST /v1/whatsapp/phone-numbers/kyc/validate-address

**Pre-validate a regulated-number KYC address (Tier 4)**

Optional early check for the address step of a Tier 4 (end-user identity)
registration: validates a postal address for deliverability BEFORE the full
KYC submit, so it can be corrected before any documents are uploaded. The
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. Only
the postal address is sent (no documents, no gov-ID fields). 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).


### Request Body

- **country** (required) `string`: ISO 3166-1 alpha-2 country code.
- **street_address** (required) `string`: No description
- **locality** (required) `string`: City / town.
- **administrative_area** `string`: State / province / region. When omitted
- **postal_code** (required) `string`: No description

### Responses

#### 200: Address is deliverable, or the pre-check was skipped (no region supplied).

**Response Body:**

- **ok** `boolean`: No description (example: true)
- **skipped** `boolean`: true when no `administrative_area` was supplied, so no pre-check ran.

#### 400: The country isn't offered, or the address could not be verified. When the
provider returned usable corrections, `details.addressSuggestions` carries
them per field for a one-click "apply suggestion" card. (Flat error
envelope: `error` is the human message; `code`/`param`/`details` are
top-level siblings.)


**Response Body:**

- **error** `string`: Human-readable message.
- **type** `string`: No description
- **code** `string`: No description (example: "INVALID_FIELD_VALUE")
- **param** `string`: No description (example: "address")
- **details** `object`: 
  - **addressSuggestions** `array[object]`: 
    - **field** `string`: No description (example: "administrative_area")
    - **label** `string`: No description (example: "State / Province")
    - **value** `string`: No description (example: "Dublin")

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Start a sandbox activation for a phone API Reference

Creates (or refreshes) a pending sandbox session for the given phone and
immediately fires the verified sandbox template from the shared sandbox
number to that phone. The session activates when the phone owner replies
to that WhatsApp message — the reply itself is proof of ownership.

One phone per user: if the caller already has a non-expired session for
a DIFFERENT phone, the request is rejected with `invalid_field_value`
(the message names the existing phone so it can be revoked first).
Re-creating a session for the SAME phone is idempotent and refreshes
the verification template.

If Meta rejects the template send (not a WhatsApp number, paused WABA,
token issue), the pending row is rolled back and the Meta error message
is returned in `error` so the caller knows why.


## GET /v1/whatsapp/sandbox/sessions

**List your sandbox sessions**

Returns all of the authenticated user's non-expired sandbox sessions
(pending + active) plus the sandbox phone number. In practice there
is at most one session per user since the sandbox is one-phone-per-user;
the array shape is preserved for forward compatibility.


### Responses

#### 200: Sessions retrieved successfully

**Response Body:**

- **sessions** `array[WhatsAppSandboxSession]`: 
- **sandboxNumber** `string`: The shared sandbox phone number in E.164 form. (example: "+12029087457")

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## POST /v1/whatsapp/sandbox/sessions

**Start a sandbox activation for a phone**

Creates (or refreshes) a pending sandbox session for the given phone and
immediately fires the verified sandbox template from the shared sandbox
number to that phone. The session activates when the phone owner replies
to that WhatsApp message — the reply itself is proof of ownership.

One phone per user: if the caller already has a non-expired session for
a DIFFERENT phone, the request is rejected with `invalid_field_value`
(the message names the existing phone so it can be revoked first).
Re-creating a session for the SAME phone is idempotent and refreshes
the verification template.

If Meta rejects the template send (not a WhatsApp number, paused WABA,
token issue), the pending row is rolled back and the Meta error message
is returned in `error` so the caller knows why.


### Request Body

- **phone** (required) `string`: Recipient phone in international format. Digits, spaces, dashes and a leading `+` are all accepted; the server normalizes to E.164 digits-only.

### Responses

#### 200: Session created or refreshed; verification template sent

**Response Body:**

- **session**: `WhatsAppSandboxSession` - See schema definition
- **sandboxNumber** `string`: No description (example: "+12029087457")

#### 400: Returned when (a) phone format is invalid, (b) phone equals the sandbox
number itself, (c) the user already has a session for a different phone,
or (d) Meta rejected the template send. The `error` field contains the
specific reason; `param` is set when a field is at fault.


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---


# Related Schema Definitions

## WhatsAppSandboxSession

A per-user activation session against the shared WhatsApp sandbox number.
Transitions `pending → active` when the inbound webhook receives a reply
from the matching phone (the reply itself proves ownership).


### Properties

- **id** (required) `string`: Session id. Use this to revoke via DELETE.
- **phoneE164** (required) `string`: Digits-only E.164 form (no +, spaces, or dashes).
- **status** (required) `string`: `pending` until the phone replies to the activation template, then
`active`. Expired sessions are pruned by TTL and never appear in
list responses.
 - one of: pending, active
- **expiresAt** (required) `string`: UTC timestamp at which the session becomes invalid. Pending sessions
get a 24h window; activated sessions get 7 days.

- **activatedAt** `string`: When the session transitioned `pending → active`, or null.
- **createdAt** `string`: No description

---

# Revoke a sandbox session API Reference

Hard-deletes the session. The user loses the ability to send to that
phone via the sandbox until they re-activate it. Existing conversations
and messages already exchanged with that phone are untouched —
revocation only blocks FUTURE sends.

Sessions belonging to other users cannot be revoked; the response is
the same 400 as "session not found" so existence isn't leaked.


## DELETE /v1/whatsapp/sandbox/sessions/{sessionId}

**Revoke a sandbox session**

Hard-deletes the session. The user loses the ability to send to that
phone via the sandbox until they re-activate it. Existing conversations
and messages already exchanged with that phone are untouched —
revocation only blocks FUTURE sends.

Sessions belonging to other users cannot be revoked; the response is
the same 400 as "session not found" so existence isn't leaked.


### Parameters

- **sessionId** (required) in path: The session id returned by POST /v1/whatsapp/sandbox/sessions.

### Responses

#### 200: Session revoked

**Response Body:**

- **success** `boolean`: No description

#### 400: Invalid or unknown session id

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

---

# List your sandbox sessions API Reference

Returns all of the authenticated user's non-expired sandbox sessions
(pending + active) plus the sandbox phone number. In practice there
is at most one session per user since the sandbox is one-phone-per-user;
the array shape is preserved for forward compatibility.


## GET /v1/whatsapp/sandbox/sessions

**List your sandbox sessions**

Returns all of the authenticated user's non-expired sandbox sessions
(pending + active) plus the sandbox phone number. In practice there
is at most one session per user since the sandbox is one-phone-per-user;
the array shape is preserved for forward compatibility.


### Responses

#### 200: Sessions retrieved successfully

**Response Body:**

- **sessions** `array[WhatsAppSandboxSession]`: 
- **sandboxNumber** `string`: The shared sandbox phone number in E.164 form. (example: "+12029087457")

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---

## POST /v1/whatsapp/sandbox/sessions

**Start a sandbox activation for a phone**

Creates (or refreshes) a pending sandbox session for the given phone and
immediately fires the verified sandbox template from the shared sandbox
number to that phone. The session activates when the phone owner replies
to that WhatsApp message — the reply itself is proof of ownership.

One phone per user: if the caller already has a non-expired session for
a DIFFERENT phone, the request is rejected with `invalid_field_value`
(the message names the existing phone so it can be revoked first).
Re-creating a session for the SAME phone is idempotent and refreshes
the verification template.

If Meta rejects the template send (not a WhatsApp number, paused WABA,
token issue), the pending row is rolled back and the Meta error message
is returned in `error` so the caller knows why.


### Request Body

- **phone** (required) `string`: Recipient phone in international format. Digits, spaces, dashes and a leading `+` are all accepted; the server normalizes to E.164 digits-only.

### Responses

#### 200: Session created or refreshed; verification template sent

**Response Body:**

- **session**: `WhatsAppSandboxSession` - See schema definition
- **sandboxNumber** `string`: No description (example: "+12029087457")

#### 400: Returned when (a) phone format is invalid, (b) phone equals the sandbox
number itself, (c) the user already has a session for a different phone,
or (d) Meta rejected the template send. The `error` field contains the
specific reason; `param` is set when a field is at fault.


#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 403: Inbox addon required

---


# Related Schema Definitions

## WhatsAppSandboxSession

A per-user activation session against the shared WhatsApp sandbox number.
Transitions `pending → active` when the inbound webhook receives a reply
from the matching phone (the reply itself proves ownership).


### Properties

- **id** (required) `string`: Session id. Use this to revoke via DELETE.
- **phoneE164** (required) `string`: Digits-only E.164 form (no +, spaces, or dashes).
- **status** (required) `string`: `pending` until the phone replies to the activation template, then
`active`. Expired sessions are pruned by TTL and never appear in
list responses.
 - one of: pending, active
- **expiresAt** (required) `string`: UTC timestamp at which the session becomes invalid. Pending sessions
get a 24h window; activated sessions get 7 days.

- **activatedAt** `string`: When the session transitioned `pending → active`, or null.
- **createdAt** `string`: No description

---

# Activate workflow API Reference

Validate the graph is runnable and set the workflow live. Once active, matching inbound messages start executions. Idempotent.

## POST /v1/workflows/{workflowId}/activate

**Activate workflow**

Validate the graph is runnable and set the workflow live. Once active, matching inbound messages start executions. Idempotent.

### Parameters

- **workflowId** (required) in path: No description

### Responses

#### 200: Workflow activated

**Response Body:**

- **success** `boolean`: No description
- **workflow** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description
  - **entryNodeId** `string`: No description

#### 400: Incomplete or invalid graph

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Create workflow API Reference

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.


## GET /v1/workflows

**List workflows**

Returns workflows with run stats. Filter by status or profile.

### Parameters

- **profileId** (optional) in query: Filter by profile. Omit to list across all profiles
- **status** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Workflows list

**Response Body:**

- **success** `boolean`: No description
- **workflows** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **accountName** `string`: No description
  - **status** `string`: No description - one of: draft, active, paused
  - **nodeCount** `integer`: No description
  - **totalStarted** `integer`: No description
  - **totalCompleted** `integer`: No description
  - **totalExited** `integer`: No description
  - **createdAt** `string` (date-time): No description
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/workflows

**Create workflow**

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.


### Request Body

- **profileId** (required) `string`: No description
- **accountId** (required) `string`: No description
- **platform** `string`: No description - one of: whatsapp, instagram, facebook, telegram, twitter, bluesky, reddit
- **name** (required) `string`: No description
- **description** `string`: No description
- **nodes** `array`: No description
- **edges** `array`: No description
- **entryNodeId** `string`: The trigger node id; derived from the single trigger node if omitted

### Responses

#### 200: Workflow created

**Response Body:**

- **success** `boolean`: No description
- **workflow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **status** `string`: No description
  - **nodeCount** `integer`: No description
  - **entryNodeId** `string`: No description
  - **createdAt** `string` (date-time): No description

#### 400: Invalid graph (duplicate node ids

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Delete workflow API Reference

Permanently delete a workflow and all of its executions.

## GET /v1/workflows/{workflowId}

**Get workflow with graph**

Returns a workflow including its full node/edge graph and run stats.

### Parameters

- **workflowId** (required) in path: No description

### Responses

#### 200: Workflow details

**Response Body:**

- **success** `boolean`: No description
- **workflow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **profileId** `string`: No description
  - **status** `string`: No description - one of: draft, active, paused
  - **entryNodeId** `string`: No description
  - **nodes** `array[WorkflowNode]`: 
  - **edges** `array[WorkflowEdge]`: 
  - **totalStarted** `integer`: No description
  - **totalCompleted** `integer`: No description
  - **totalExited** `integer`: No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/workflows/{workflowId}

**Update workflow**

Update name, description, the graph, or reassign to a different account. The graph can only be modified while the workflow is draft or paused. Account swaps re-validate the graph against the new platform (so e.g. moving from WhatsApp to Facebook surfaces a `start_call` node as an error instead of silently saving an unrunnable graph).


### Parameters

- **workflowId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **description** `string`: No description
- **nodes** `array`: No description
- **edges** `array`: No description
- **entryNodeId** `string`: No description
- **accountId** `string`: Reassign the workflow to a different `SocialAccount`. `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 workspace and be on a workflow-supported platform (whatsapp, instagram, facebook, telegram, twitter, bluesky, reddit). Changing this triggers a graph revalidation against the new platform.


### Responses

#### 200: Workflow updated

**Response Body:**

- **success** `boolean`: No description
- **workflow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **status** `string`: No description
  - **entryNodeId** `string`: No description
  - **nodeCount** `integer`: No description
  - **updatedAt** `string` (date-time): No description

#### 400: Invalid graph

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/workflows/{workflowId}

**Delete workflow**

Permanently delete a workflow and all of its executions.

### Parameters

- **workflowId** (required) in path: No description

### Responses

#### 200: Workflow deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## WorkflowNode

A node in a workflow graph. `config` shape depends on `type`.

### Properties

- **id** (required) `string`: Stable node id referenced by edges
- **type** (required) `string`: Node kind. The 16 supported types break into four groups:
  messaging (send_message),
  control flow (trigger, condition, delay, wait_for_reply, a_b_split, end),
  data ops (set_variable, set_field, add_tag, remove_tag, enroll_sequence),
  integrations (webhook, ai, handoff, start_call).
 - one of: trigger, send_message, wait_for_reply, condition, set_variable, delay, webhook, ai, handoff, start_call, a_b_split, set_field, enroll_sequence, add_tag, remove_tag, end
- **config** `object`: Type-specific settings. All string fields support `{{variable}}` interpolation against the run's variable bag (resolved at execution time).

**trigger**: `{ triggerType: inbound_message|api_call|whatsapp_event, keywords:[string], matchType: any|contains|exact|regex, onlyFirstMessage:boolean, eventType: message_sent|message_delivered|message_read|message_failed|reaction }`. Default `triggerType` is `inbound_message` for legacy nodes. `eventType` is only honored when `triggerType` is `whatsapp_event` (WhatsApp-only).

**send_message**: `{ messageType: text|template|media|interactive, text, template:{name,language,variableMapping}, media:{mediaType:image|video|audio|document, url,caption}, interactive }`. `template` and `interactive` are WhatsApp-only.

**wait_for_reply**: `{ timeoutMinutes:int (max 43200), saveAs:string }`. Resume via the `'reply'` edge on inbound, or `'timeout'` edge after `timeoutMinutes` of silence.

**condition**: `{ rules:[{ id, variable, operator: equals|not_equals|contains|not_contains|starts_with|ends_with|exists|not_exists|matches, value }] }`. First matching rule takes its `id` as the sourceHandle; otherwise `'default'`.

**set_variable**: `{ assignments:[{ name, value }] }`. Run-scoped (lives only for this execution; use `set_field` for persistent values).

**delay**: `{ delayMinutes:int (max 43200) }`. Suspends the run, resumes via timer.

**webhook**: `{ url, method: GET|POST|PUT|PATCH|DELETE, headers, bodyTemplate, saveAs }`. SSRF-guarded (private/loopback/metadata IPs rejected). Response saved as `{ status, ok, body }` to `vars[saveAs]`. Edge: `'success'` on 2xx, `'error'` otherwise.

**ai**: `{ provider: anthropic|openai|google|mistral|groq, 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'`.

**handoff**: `{ note, assignTo }`. Terminates the run as `exited`, flags the conversation for a human operator.

**start_call**: `{ to, forwardTo, requirePermissionFirst, recordingEnabled, saveAs }`. WhatsApp-only. `forwardTo` can be `tel:+E164`, `sip:user@host`, or `wss://…` (AI voice agent). Edges: `'success'`, `'permission_required'`, `'failed'`.

**a_b_split**: `{ percentage: number 0-100 (default 50) }`. Random branch picker. Edges: `'a'` (with probability `percentage/100`), `'b'`.

**set_field**: `{ field, value }`. Persistent custom field on the Contact (vs `set_variable` which is run-scoped). Field name is sanitized to `[A-Za-z0-9_]`. No-op on `api_call` runs (no contact).

**enroll_sequence**: `{ sequenceId, saveAs }`. Enrolls the run's contact into a Sequence. Edges: `'success'`, `'error'`.

**add_tag** / **remove_tag**: `{ tag }`. Push or pull a tag on the Contact. No-op on `api_call` runs.

**end**: no config. Terminates the run as `completed`.

- **position** `object`: Canvas coordinates (ignored by the executor; used by the visual builder).
  - **x** `number`: 
  - **y** `number`: 

## WorkflowEdge

A directed edge between two nodes.

### Properties

- **id** (required) `string`: No description
- **source** (required) `string`: Source node id
- **target** (required) `string`: Target node id
- **sourceHandle** `string`: Selects a branch output of a multi-output node. Null (or omitted) = the node's single/default output. Known handles per node type:

  - **condition** — a rule's `id`, or `'default'` (no rule matched)
  - **wait_for_reply** — `'reply'` (contact replied) | `'timeout'` (no reply in window)
  - **webhook** — `'success'` (2xx) | `'error'` (non-2xx / fetch failed)
  - **ai** — `'success'` (text/JSON response) | `'tool:<toolName>'` (model invoked
    that tool) | `'error'` (upstream failure / non-JSON in JSON mode)
  - **start_call** — `'success'` | `'permission_required'` | `'failed'`
  - **a_b_split** — `'a'` | `'b'`
  - **enroll_sequence** — `'success'` | `'error'`

---

# Duplicate a workflow API Reference

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.


## POST /v1/workflows/{workflowId}/duplicate

**Duplicate a workflow**

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.


### Parameters

- **workflowId** (required) in path: No description

### Responses

#### 201: Workflow duplicated

**Response Body:**

- **success** `boolean`: No description
- **workflow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **status** `string`: No description - one of: draft
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **profileId** `string`: No description
  - **entryNodeId** `string`: No description
  - **nodeCount** `integer`: No description
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Get a specific workflow version API Reference

Returns the full snapshot for a single historical version, including the graph.

## GET /v1/workflows/{workflowId}/versions/{version}

**Get a specific workflow version**

Returns the full snapshot for a single historical version, including the graph.

### Parameters

- **workflowId** (required) in path: No description
- **version** (required) in path: No description

### Responses

#### 200: Version snapshot

**Response Body:**

- **success** `boolean`: No description
- **version** `object`: 
  - **version** `integer`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **entryNodeId** `string`: No description
  - **nodes** `array[WorkflowNode]`: 
  - **edges** `array[WorkflowEdge]`: 
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **profileId** `string`: No description
  - **createdBy** `string`: No description
  - **createdByEmail** `string`: No description
  - **restoredFromVersion** `integer`: No description
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## WorkflowNode

A node in a workflow graph. `config` shape depends on `type`.

### Properties

- **id** (required) `string`: Stable node id referenced by edges
- **type** (required) `string`: Node kind. The 16 supported types break into four groups:
  messaging (send_message),
  control flow (trigger, condition, delay, wait_for_reply, a_b_split, end),
  data ops (set_variable, set_field, add_tag, remove_tag, enroll_sequence),
  integrations (webhook, ai, handoff, start_call).
 - one of: trigger, send_message, wait_for_reply, condition, set_variable, delay, webhook, ai, handoff, start_call, a_b_split, set_field, enroll_sequence, add_tag, remove_tag, end
- **config** `object`: Type-specific settings. All string fields support `{{variable}}` interpolation against the run's variable bag (resolved at execution time).

**trigger**: `{ triggerType: inbound_message|api_call|whatsapp_event, keywords:[string], matchType: any|contains|exact|regex, onlyFirstMessage:boolean, eventType: message_sent|message_delivered|message_read|message_failed|reaction }`. Default `triggerType` is `inbound_message` for legacy nodes. `eventType` is only honored when `triggerType` is `whatsapp_event` (WhatsApp-only).

**send_message**: `{ messageType: text|template|media|interactive, text, template:{name,language,variableMapping}, media:{mediaType:image|video|audio|document, url,caption}, interactive }`. `template` and `interactive` are WhatsApp-only.

**wait_for_reply**: `{ timeoutMinutes:int (max 43200), saveAs:string }`. Resume via the `'reply'` edge on inbound, or `'timeout'` edge after `timeoutMinutes` of silence.

**condition**: `{ rules:[{ id, variable, operator: equals|not_equals|contains|not_contains|starts_with|ends_with|exists|not_exists|matches, value }] }`. First matching rule takes its `id` as the sourceHandle; otherwise `'default'`.

**set_variable**: `{ assignments:[{ name, value }] }`. Run-scoped (lives only for this execution; use `set_field` for persistent values).

**delay**: `{ delayMinutes:int (max 43200) }`. Suspends the run, resumes via timer.

**webhook**: `{ url, method: GET|POST|PUT|PATCH|DELETE, headers, bodyTemplate, saveAs }`. SSRF-guarded (private/loopback/metadata IPs rejected). Response saved as `{ status, ok, body }` to `vars[saveAs]`. Edge: `'success'` on 2xx, `'error'` otherwise.

**ai**: `{ provider: anthropic|openai|google|mistral|groq, 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'`.

**handoff**: `{ note, assignTo }`. Terminates the run as `exited`, flags the conversation for a human operator.

**start_call**: `{ to, forwardTo, requirePermissionFirst, recordingEnabled, saveAs }`. WhatsApp-only. `forwardTo` can be `tel:+E164`, `sip:user@host`, or `wss://…` (AI voice agent). Edges: `'success'`, `'permission_required'`, `'failed'`.

**a_b_split**: `{ percentage: number 0-100 (default 50) }`. Random branch picker. Edges: `'a'` (with probability `percentage/100`), `'b'`.

**set_field**: `{ field, value }`. Persistent custom field on the Contact (vs `set_variable` which is run-scoped). Field name is sanitized to `[A-Za-z0-9_]`. No-op on `api_call` runs (no contact).

**enroll_sequence**: `{ sequenceId, saveAs }`. Enrolls the run's contact into a Sequence. Edges: `'success'`, `'error'`.

**add_tag** / **remove_tag**: `{ tag }`. Push or pull a tag on the Contact. No-op on `api_call` runs.

**end**: no config. Terminates the run as `completed`.

- **position** `object`: Canvas coordinates (ignored by the executor; used by the visual builder).
  - **x** `number`: 
  - **y** `number`: 

## WorkflowEdge

A directed edge between two nodes.

### Properties

- **id** (required) `string`: No description
- **source** (required) `string`: Source node id
- **target** (required) `string`: Target node id
- **sourceHandle** `string`: Selects a branch output of a multi-output node. Null (or omitted) = the node's single/default output. Known handles per node type:

  - **condition** — a rule's `id`, or `'default'` (no rule matched)
  - **wait_for_reply** — `'reply'` (contact replied) | `'timeout'` (no reply in window)
  - **webhook** — `'success'` (2xx) | `'error'` (non-2xx / fetch failed)
  - **ai** — `'success'` (text/JSON response) | `'tool:<toolName>'` (model invoked
    that tool) | `'error'` (upstream failure / non-JSON in JSON mode)
  - **start_call** — `'success'` | `'permission_required'` | `'failed'`
  - **a_b_split** — `'a'` | `'b'`
  - **enroll_sequence** — `'success'` | `'error'`

---

# Get workflow with graph API Reference

Returns a workflow including its full node/edge graph and run stats.

## GET /v1/workflows/{workflowId}

**Get workflow with graph**

Returns a workflow including its full node/edge graph and run stats.

### Parameters

- **workflowId** (required) in path: No description

### Responses

#### 200: Workflow details

**Response Body:**

- **success** `boolean`: No description
- **workflow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **profileId** `string`: No description
  - **status** `string`: No description - one of: draft, active, paused
  - **entryNodeId** `string`: No description
  - **nodes** `array[WorkflowNode]`: 
  - **edges** `array[WorkflowEdge]`: 
  - **totalStarted** `integer`: No description
  - **totalCompleted** `integer`: No description
  - **totalExited** `integer`: No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/workflows/{workflowId}

**Update workflow**

Update name, description, the graph, or reassign to a different account. The graph can only be modified while the workflow is draft or paused. Account swaps re-validate the graph against the new platform (so e.g. moving from WhatsApp to Facebook surfaces a `start_call` node as an error instead of silently saving an unrunnable graph).


### Parameters

- **workflowId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **description** `string`: No description
- **nodes** `array`: No description
- **edges** `array`: No description
- **entryNodeId** `string`: No description
- **accountId** `string`: Reassign the workflow to a different `SocialAccount`. `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 workspace and be on a workflow-supported platform (whatsapp, instagram, facebook, telegram, twitter, bluesky, reddit). Changing this triggers a graph revalidation against the new platform.


### Responses

#### 200: Workflow updated

**Response Body:**

- **success** `boolean`: No description
- **workflow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **status** `string`: No description
  - **entryNodeId** `string`: No description
  - **nodeCount** `integer`: No description
  - **updatedAt** `string` (date-time): No description

#### 400: Invalid graph

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/workflows/{workflowId}

**Delete workflow**

Permanently delete a workflow and all of its executions.

### Parameters

- **workflowId** (required) in path: No description

### Responses

#### 200: Workflow deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## WorkflowNode

A node in a workflow graph. `config` shape depends on `type`.

### Properties

- **id** (required) `string`: Stable node id referenced by edges
- **type** (required) `string`: Node kind. The 16 supported types break into four groups:
  messaging (send_message),
  control flow (trigger, condition, delay, wait_for_reply, a_b_split, end),
  data ops (set_variable, set_field, add_tag, remove_tag, enroll_sequence),
  integrations (webhook, ai, handoff, start_call).
 - one of: trigger, send_message, wait_for_reply, condition, set_variable, delay, webhook, ai, handoff, start_call, a_b_split, set_field, enroll_sequence, add_tag, remove_tag, end
- **config** `object`: Type-specific settings. All string fields support `{{variable}}` interpolation against the run's variable bag (resolved at execution time).

**trigger**: `{ triggerType: inbound_message|api_call|whatsapp_event, keywords:[string], matchType: any|contains|exact|regex, onlyFirstMessage:boolean, eventType: message_sent|message_delivered|message_read|message_failed|reaction }`. Default `triggerType` is `inbound_message` for legacy nodes. `eventType` is only honored when `triggerType` is `whatsapp_event` (WhatsApp-only).

**send_message**: `{ messageType: text|template|media|interactive, text, template:{name,language,variableMapping}, media:{mediaType:image|video|audio|document, url,caption}, interactive }`. `template` and `interactive` are WhatsApp-only.

**wait_for_reply**: `{ timeoutMinutes:int (max 43200), saveAs:string }`. Resume via the `'reply'` edge on inbound, or `'timeout'` edge after `timeoutMinutes` of silence.

**condition**: `{ rules:[{ id, variable, operator: equals|not_equals|contains|not_contains|starts_with|ends_with|exists|not_exists|matches, value }] }`. First matching rule takes its `id` as the sourceHandle; otherwise `'default'`.

**set_variable**: `{ assignments:[{ name, value }] }`. Run-scoped (lives only for this execution; use `set_field` for persistent values).

**delay**: `{ delayMinutes:int (max 43200) }`. Suspends the run, resumes via timer.

**webhook**: `{ url, method: GET|POST|PUT|PATCH|DELETE, headers, bodyTemplate, saveAs }`. SSRF-guarded (private/loopback/metadata IPs rejected). Response saved as `{ status, ok, body }` to `vars[saveAs]`. Edge: `'success'` on 2xx, `'error'` otherwise.

**ai**: `{ provider: anthropic|openai|google|mistral|groq, 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'`.

**handoff**: `{ note, assignTo }`. Terminates the run as `exited`, flags the conversation for a human operator.

**start_call**: `{ to, forwardTo, requirePermissionFirst, recordingEnabled, saveAs }`. WhatsApp-only. `forwardTo` can be `tel:+E164`, `sip:user@host`, or `wss://…` (AI voice agent). Edges: `'success'`, `'permission_required'`, `'failed'`.

**a_b_split**: `{ percentage: number 0-100 (default 50) }`. Random branch picker. Edges: `'a'` (with probability `percentage/100`), `'b'`.

**set_field**: `{ field, value }`. Persistent custom field on the Contact (vs `set_variable` which is run-scoped). Field name is sanitized to `[A-Za-z0-9_]`. No-op on `api_call` runs (no contact).

**enroll_sequence**: `{ sequenceId, saveAs }`. Enrolls the run's contact into a Sequence. Edges: `'success'`, `'error'`.

**add_tag** / **remove_tag**: `{ tag }`. Push or pull a tag on the Contact. No-op on `api_call` runs.

**end**: no config. Terminates the run as `completed`.

- **position** `object`: Canvas coordinates (ignored by the executor; used by the visual builder).
  - **x** `number`: 
  - **y** `number`: 

## WorkflowEdge

A directed edge between two nodes.

### Properties

- **id** (required) `string`: No description
- **source** (required) `string`: Source node id
- **target** (required) `string`: Target node id
- **sourceHandle** `string`: Selects a branch output of a multi-output node. Null (or omitted) = the node's single/default output. Known handles per node type:

  - **condition** — a rule's `id`, or `'default'` (no rule matched)
  - **wait_for_reply** — `'reply'` (contact replied) | `'timeout'` (no reply in window)
  - **webhook** — `'success'` (2xx) | `'error'` (non-2xx / fetch failed)
  - **ai** — `'success'` (text/JSON response) | `'tool:<toolName>'` (model invoked
    that tool) | `'error'` (upstream failure / non-JSON in JSON mode)
  - **start_call** — `'success'` | `'permission_required'` | `'failed'`
  - **a_b_split** — `'a'` | `'b'`
  - **enroll_sequence** — `'success'` | `'error'`

---

# Get an execution's timeline API Reference

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.


## GET /v1/workflows/{workflowId}/executions/{executionId}/events

**Get an execution's timeline**

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.


### Parameters

- **workflowId** (required) in path: No description
- **executionId** (required) in path: No description

### Responses

#### 200: Timeline events for the execution

**Response Body:**

- **success** `boolean`: No description
- **execution** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description - one of: running, waiting, completed, exited, failed
  - **startedAt** `string` (date-time): No description
  - **completedAt** `string` (date-time): No description
- **events** `array[WorkflowExecutionEvent]`: Events in chronological order (oldest first).

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## WorkflowExecutionEvent

One entry in a workflow execution's timeline. Emitted by the executor on every node visit and lifecycle transition, surfaced by `GET /v1/workflows/{workflowId}/executions/ {executionId}/events` for run inspection in the Runs UI.


### Properties

- **action** `string`: No description - one of: execution_started, execution_completed, execution_exited, execution_paused, execution_resumed, node_started, node_completed, node_failed, node_skipped
- **status** `string`: No description - one of: success, failed, pending
- **nodeId** `string`: Present on `node_*` events
- **nodeType** `string`: Present on `node_*` events
- **sourceHandle** `string`: The edge handle the executor followed out of this node (see `WorkflowEdge.sourceHandle`)
- **durationMs** `integer`: Node run time; present on `node_completed` and `node_failed`
- **errorMessage** `string`: Failure detail; present on `node_failed` and `execution_exited`
- **meta** `object`: Per-node-type payload. Shape varies — see WorkflowNode `type`. Examples:
  `send_message` → `{ messageType, text, recipient }`,
  `webhook` → `{ url, method, statusCode, responseTimeMs, responsePreview }`,
  `ai` → `{ model, provider, inputTokens, outputTokens, responsePreview }`,
  `condition` → `{ matchedHandle, rulesEvaluated }`,
  `a_b_split` → `{ percentage, chosen }`.

- **at** `string`: Event timestamp (UTC)

---

# List workflow runs API Reference

Returns recent executions (runs) with their status, current node, and accumulated variables.

## GET /v1/workflows/{workflowId}/executions

**List workflow runs**

Returns recent executions (runs) with their status, current node, and accumulated variables.

### Parameters

- **workflowId** (required) in path: No description
- **status** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Executions list

**Response Body:**

- **success** `boolean`: No description
- **executions** `array[object]`: 
  - **id** `string`: No description
  - **status** `string`: No description - one of: running, waiting, completed, exited, failed
  - **currentNodeId** `string`: No description
  - **waitingFor** `object`: 
    - **kind** `string`: No description - one of: timer, reply
    - **nodeId** `string`: No description
  - **variables** `object`: No description
  - **platformIdentifier** `string`: No description
  - **conversationId** `string`: No description
  - **stepCount** `integer`: No description
  - **lastError** `string`: No description
  - **resumeAt** `string` (date-time): No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description
  - **completedAt** `string` (date-time): No description
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## POST /v1/workflows/{workflowId}/executions

**Manually start a workflow run**

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.


### Parameters

- **workflowId** (required) in path: No description

### Request Body

- **to** `string`: Recipient phone (WhatsApp only)
- **conversationId** `string`: An existing conversation to run in (required for non-WhatsApp workflows)
- **text** `string`: Simulated inbound text

### Responses

#### 200: Run started

**Response Body:**

- **success** `boolean`: No description
- **execution** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description
  - **currentNodeId** `string`: No description
  - **waitingFor** `object`: No description
  - **variables** `object`: No description
  - **conversationId** `string`: No description

#### 400: Missing target

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List a workflow's version history API Reference

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.


## GET /v1/workflows/{workflowId}/versions

**List a workflow's version history**

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.


### Parameters

- **workflowId** (required) in path: No description

### Responses

#### 200: Versions list

**Response Body:**

- **success** `boolean`: No description
- **versions** `array[object]`: Versions in reverse chronological order (newest first).
  - **version** `integer`: Monotonically increasing version number
  - **name** `string`: No description
  - **description** `string`: No description
  - **createdBy** `string`: User id that authored this version
  - **createdByEmail** `string`: Denormalized email so the history UI can render without a join
  - **restoredFromVersion** `integer`: When non-null
  - **createdAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# List workflows API Reference

Returns workflows with run stats. Filter by status or profile.

## GET /v1/workflows

**List workflows**

Returns workflows with run stats. Filter by status or profile.

### Parameters

- **profileId** (optional) in query: Filter by profile. Omit to list across all profiles
- **status** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Workflows list

**Response Body:**

- **success** `boolean`: No description
- **workflows** `array[object]`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **accountName** `string`: No description
  - **status** `string`: No description - one of: draft, active, paused
  - **nodeCount** `integer`: No description
  - **totalStarted** `integer`: No description
  - **totalCompleted** `integer`: No description
  - **totalExited** `integer`: No description
  - **createdAt** `string` (date-time): No description
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

## POST /v1/workflows

**Create workflow**

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.


### Request Body

- **profileId** (required) `string`: No description
- **accountId** (required) `string`: No description
- **platform** `string`: No description - one of: whatsapp, instagram, facebook, telegram, twitter, bluesky, reddit
- **name** (required) `string`: No description
- **description** `string`: No description
- **nodes** `array`: No description
- **edges** `array`: No description
- **entryNodeId** `string`: The trigger node id; derived from the single trigger node if omitted

### Responses

#### 200: Workflow created

**Response Body:**

- **success** `boolean`: No description
- **workflow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **status** `string`: No description
  - **nodeCount** `integer`: No description
  - **entryNodeId** `string`: No description
  - **createdAt** `string` (date-time): No description

#### 400: Invalid graph (duplicate node ids

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

---

---

# Pause workflow API Reference

Stop matching new inbound messages. In-flight executions continue to completion. Idempotent.

## POST /v1/workflows/{workflowId}/pause

**Pause workflow**

Stop matching new inbound messages. In-flight executions continue to completion. Idempotent.

### Parameters

- **workflowId** (required) in path: No description

### Responses

#### 200: Workflow paused

**Response Body:**

- **success** `boolean`: No description
- **workflow** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Restore a previous workflow version API Reference

Replace the current graph with the named version's snapshot. Before the swap, the current graph is itself snapshotted as a new version, so a restore is reversible. The workflow must be in `draft` or `paused` status (same gate as a normal graph edit). The returned workflow carries `restoredFromVersion` so the UI can surface which version was rolled back to.


## POST /v1/workflows/{workflowId}/versions/{version}/restore

**Restore a previous workflow version**

Replace the current graph with the named version's snapshot. Before the swap, the current graph is itself snapshotted as a new version, so a restore is reversible. The workflow must be in `draft` or `paused` status (same gate as a normal graph edit). The returned workflow carries `restoredFromVersion` so the UI can surface which version was rolled back to.


### Parameters

- **workflowId** (required) in path: No description
- **version** (required) in path: No description

### Responses

#### 200: Workflow restored to the named version

**Response Body:**

- **success** `boolean`: No description
- **workflow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **status** `string`: No description
  - **entryNodeId** `string`: No description
  - **nodeCount** `integer`: No description
  - **updatedAt** `string` (date-time): No description
- **restoredFromVersion** `integer`: No description

#### 400: Workflow is not draft/paused

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Manually start a workflow run API Reference

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.


## GET /v1/workflows/{workflowId}/executions

**List workflow runs**

Returns recent executions (runs) with their status, current node, and accumulated variables.

### Parameters

- **workflowId** (required) in path: No description
- **status** (optional) in query: No description
- **limit** (optional) in query: No description
- **skip** (optional) in query: No description

### Responses

#### 200: Executions list

**Response Body:**

- **success** `boolean`: No description
- **executions** `array[object]`: 
  - **id** `string`: No description
  - **status** `string`: No description - one of: running, waiting, completed, exited, failed
  - **currentNodeId** `string`: No description
  - **waitingFor** `object`: 
    - **kind** `string`: No description - one of: timer, reply
    - **nodeId** `string`: No description
  - **variables** `object`: No description
  - **platformIdentifier** `string`: No description
  - **conversationId** `string`: No description
  - **stepCount** `integer`: No description
  - **lastError** `string`: No description
  - **resumeAt** `string` (date-time): No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description
  - **completedAt** `string` (date-time): No description
- **pagination** `object`: 
  - **total** `integer`: No description
  - **limit** `integer`: No description
  - **skip** `integer`: No description
  - **hasMore** `boolean`: No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## POST /v1/workflows/{workflowId}/executions

**Manually start a workflow run**

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.


### Parameters

- **workflowId** (required) in path: No description

### Request Body

- **to** `string`: Recipient phone (WhatsApp only)
- **conversationId** `string`: An existing conversation to run in (required for non-WhatsApp workflows)
- **text** `string`: Simulated inbound text

### Responses

#### 200: Run started

**Response Body:**

- **success** `boolean`: No description
- **execution** `object`: 
  - **id** `string`: No description
  - **status** `string`: No description
  - **currentNodeId** `string`: No description
  - **waitingFor** `object`: No description
  - **variables** `object`: No description
  - **conversationId** `string`: No description

#### 400: Missing target

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

---

# Update workflow API Reference

Update name, description, the graph, or reassign to a different account. The graph can only be modified while the workflow is draft or paused. Account swaps re-validate the graph against the new platform (so e.g. moving from WhatsApp to Facebook surfaces a `start_call` node as an error instead of silently saving an unrunnable graph).


## GET /v1/workflows/{workflowId}

**Get workflow with graph**

Returns a workflow including its full node/edge graph and run stats.

### Parameters

- **workflowId** (required) in path: No description

### Responses

#### 200: Workflow details

**Response Body:**

- **success** `boolean`: No description
- **workflow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **platform** `string`: No description
  - **accountId** `string`: No description
  - **profileId** `string`: No description
  - **status** `string`: No description - one of: draft, active, paused
  - **entryNodeId** `string`: No description
  - **nodes** `array[WorkflowNode]`: 
  - **edges** `array[WorkflowEdge]`: 
  - **totalStarted** `integer`: No description
  - **totalCompleted** `integer`: No description
  - **totalExited** `integer`: No description
  - **createdAt** `string` (date-time): No description
  - **updatedAt** `string` (date-time): No description

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## PATCH /v1/workflows/{workflowId}

**Update workflow**

Update name, description, the graph, or reassign to a different account. The graph can only be modified while the workflow is draft or paused. Account swaps re-validate the graph against the new platform (so e.g. moving from WhatsApp to Facebook surfaces a `start_call` node as an error instead of silently saving an unrunnable graph).


### Parameters

- **workflowId** (required) in path: No description

### Request Body

- **name** `string`: No description
- **description** `string`: No description
- **nodes** `array`: No description
- **edges** `array`: No description
- **entryNodeId** `string`: No description
- **accountId** `string`: Reassign the workflow to a different `SocialAccount`. `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 workspace and be on a workflow-supported platform (whatsapp, instagram, facebook, telegram, twitter, bluesky, reddit). Changing this triggers a graph revalidation against the new platform.


### Responses

#### 200: Workflow updated

**Response Body:**

- **success** `boolean`: No description
- **workflow** `object`: 
  - **id** `string`: No description
  - **name** `string`: No description
  - **description** `string`: No description
  - **status** `string`: No description
  - **entryNodeId** `string`: No description
  - **nodeCount** `integer`: No description
  - **updatedAt** `string` (date-time): No description

#### 400: Invalid graph

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---

## DELETE /v1/workflows/{workflowId}

**Delete workflow**

Permanently delete a workflow and all of its executions.

### Parameters

- **workflowId** (required) in path: No description

### Responses

#### 200: Workflow deleted

#### 401: Unauthorized

**Response Body:**

- **error** `string`: No description (example: "Unauthorized")

#### 404: Resource not found

**Response Body:**

- **error** `string`: No description (example: "Not found")

---


# Related Schema Definitions

## WorkflowNode

A node in a workflow graph. `config` shape depends on `type`.

### Properties

- **id** (required) `string`: Stable node id referenced by edges
- **type** (required) `string`: Node kind. The 16 supported types break into four groups:
  messaging (send_message),
  control flow (trigger, condition, delay, wait_for_reply, a_b_split, end),
  data ops (set_variable, set_field, add_tag, remove_tag, enroll_sequence),
  integrations (webhook, ai, handoff, start_call).
 - one of: trigger, send_message, wait_for_reply, condition, set_variable, delay, webhook, ai, handoff, start_call, a_b_split, set_field, enroll_sequence, add_tag, remove_tag, end
- **config** `object`: Type-specific settings. All string fields support `{{variable}}` interpolation against the run's variable bag (resolved at execution time).

**trigger**: `{ triggerType: inbound_message|api_call|whatsapp_event, keywords:[string], matchType: any|contains|exact|regex, onlyFirstMessage:boolean, eventType: message_sent|message_delivered|message_read|message_failed|reaction }`. Default `triggerType` is `inbound_message` for legacy nodes. `eventType` is only honored when `triggerType` is `whatsapp_event` (WhatsApp-only).

**send_message**: `{ messageType: text|template|media|interactive, text, template:{name,language,variableMapping}, media:{mediaType:image|video|audio|document, url,caption}, interactive }`. `template` and `interactive` are WhatsApp-only.

**wait_for_reply**: `{ timeoutMinutes:int (max 43200), saveAs:string }`. Resume via the `'reply'` edge on inbound, or `'timeout'` edge after `timeoutMinutes` of silence.

**condition**: `{ rules:[{ id, variable, operator: equals|not_equals|contains|not_contains|starts_with|ends_with|exists|not_exists|matches, value }] }`. First matching rule takes its `id` as the sourceHandle; otherwise `'default'`.

**set_variable**: `{ assignments:[{ name, value }] }`. Run-scoped (lives only for this execution; use `set_field` for persistent values).

**delay**: `{ delayMinutes:int (max 43200) }`. Suspends the run, resumes via timer.

**webhook**: `{ url, method: GET|POST|PUT|PATCH|DELETE, headers, bodyTemplate, saveAs }`. SSRF-guarded (private/loopback/metadata IPs rejected). Response saved as `{ status, ok, body }` to `vars[saveAs]`. Edge: `'success'` on 2xx, `'error'` otherwise.

**ai**: `{ provider: anthropic|openai|google|mistral|groq, 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'`.

**handoff**: `{ note, assignTo }`. Terminates the run as `exited`, flags the conversation for a human operator.

**start_call**: `{ to, forwardTo, requirePermissionFirst, recordingEnabled, saveAs }`. WhatsApp-only. `forwardTo` can be `tel:+E164`, `sip:user@host`, or `wss://…` (AI voice agent). Edges: `'success'`, `'permission_required'`, `'failed'`.

**a_b_split**: `{ percentage: number 0-100 (default 50) }`. Random branch picker. Edges: `'a'` (with probability `percentage/100`), `'b'`.

**set_field**: `{ field, value }`. Persistent custom field on the Contact (vs `set_variable` which is run-scoped). Field name is sanitized to `[A-Za-z0-9_]`. No-op on `api_call` runs (no contact).

**enroll_sequence**: `{ sequenceId, saveAs }`. Enrolls the run's contact into a Sequence. Edges: `'success'`, `'error'`.

**add_tag** / **remove_tag**: `{ tag }`. Push or pull a tag on the Contact. No-op on `api_call` runs.

**end**: no config. Terminates the run as `completed`.

- **position** `object`: Canvas coordinates (ignored by the executor; used by the visual builder).
  - **x** `number`: 
  - **y** `number`: 

## WorkflowEdge

A directed edge between two nodes.

### Properties

- **id** (required) `string`: No description
- **source** (required) `string`: Source node id
- **target** (required) `string`: Target node id
- **sourceHandle** `string`: Selects a branch output of a multi-output node. Null (or omitted) = the node's single/default output. Known handles per node type:

  - **condition** — a rule's `id`, or `'default'` (no rule matched)
  - **wait_for_reply** — `'reply'` (contact replied) | `'timeout'` (no reply in window)
  - **webhook** — `'success'` (2xx) | `'error'` (non-2xx / fetch failed)
  - **ai** — `'success'` (text/JSON response) | `'tool:<toolName>'` (model invoked
    that tool) | `'error'` (upstream failure / non-JSON in JSON mode)
  - **start_call** — `'success'` | `'permission_required'` | `'failed'`
  - **a_b_split** — `'a'` | `'b'`
  - **enroll_sequence** — `'success'` | `'error'`

---

# Connecting Accounts

How to connect social media accounts using OAuth flows, headless mode, and non-OAuth platforms

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Before you can post to a platform, you need to connect a social media account to a profile. Zernio supports 14 platforms, each with its own connection method.

## OAuth Flow (Most Platforms)

Most platforms use OAuth. The basic flow is:

1. Call `GET /v1/connect/{platform}` with your `profileId`
2. The API returns an `authUrl`
3. Redirect the user to that URL to authorize
4. After authorization, the user is redirected back to your `redirect_url`
5. The account is connected

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { authUrl } = await zernio.connect.getConnectUrl({
  platform: 'twitter',
  profileId: 'prof_abc123',
  redirectUrl: 'https://myapp.com/callback'
});
// Redirect user to authUrl
```
</Tab>
<Tab value="Python">
```python
result = client.connect.get_connect_url(
    platform="twitter",
    profile_id="prof_abc123",
    redirect_url="https://myapp.com/callback"
)
# Redirect user to result.auth_url
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/connect/twitter?profileId=prof_abc123&redirect_url=https://myapp.com/callback" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

See the [Start OAuth endpoint](/connect/get-connect-url) for full parameter details.

## Platforms Requiring Secondary Selection

Some platforms require an extra step after OAuth - the user needs to select which page, organization, or board to connect:

| Platform | What to Select | Endpoints |
|----------|---------------|-----------|
| Facebook | Page | [List Pages](/connect/list-facebook-pages) → [Select Page](/connect/select-facebook-page) |
| LinkedIn | Organization or Personal | [List Orgs](/connect/list-linkedin-organizations) → [Select Org](/connect/select-linkedin-organization) |
| Pinterest | Board | [List Boards](/connect/list-pinterest-boards-for-selection) → [Select Board](/connect/select-pinterest-board) |
| Google Business | Location | [List Locations](/connect/list-google-business-locations) → [Select Location](/connect/select-google-business-location) |
| Snapchat | Public Profile | [List Profiles](/connect/list-snapchat-profiles) → [Select Profile](/connect/select-snapchat-profile) |

### Standard vs Headless Mode

**Standard mode** (default): Zernio hosts the selection UI. The user picks their page/org in Zernio's hosted interface, then gets redirected to your `redirect_url`.

**Headless mode**: You build your own branded selection UI. Pass `headless=true` when starting the OAuth flow. After OAuth completes, the user is redirected to your `redirect_url` with `tempToken`, `userProfile` (URL-encoded JSON), `step=select_page`, and `connect_token` query params. Your backend then forwards those into the list and select endpoints to finalize the connection.

<Callout type="info">
The Node SDK (`@zernio/node`) does not yet expose `connect.listFacebookPages` / `connect.selectFacebookPage`. Use the Python SDK or hit the endpoints directly via fetch.
</Callout>

<Tabs items={['Python', 'curl']}>
<Tab value="Python">
```python
# 1. Start the connect flow, returns the OAuth URL.
result = client.connect.get_connect_url(
    platform="facebook",
    profile_id="prof_abc123",
    headless=True,
    redirect_url="https://your-app.com/cb",
)
# Redirect the end-user's browser to result["authUrl"].

# 2. Meta redirects the end-user to your redirect_url with these query
#    params: profileId, tempToken, userProfile (URL-encoded JSON),
#    platform=facebook, step=select_page, connect_token.

# 3. Your backend lists the user's pages.
pages = client.connect.list_facebook_pages(
    profile_id="prof_abc123",
    temp_token="<from step 2>",
)

# 4. Your backend posts the chosen pageId. user_profile must be the
#    DECODED dict, json.loads(urllib.parse.unquote(...)) the value
#    you got in step 2.
result = client.connect.select_facebook_page(
    profile_id="prof_abc123",
    page_id=pages["pages"][0]["id"],
    temp_token="<from step 2>",
    user_profile=json.loads(urllib.parse.unquote("<from step 2>")),
    redirect_url="https://your-app.com/final-success",
)
# Redirect the browser to result["redirect_url"]; result["account"]["accountId"]
# is the SocialAccount ID for the connected page.
```
</Tab>
<Tab value="curl">
```bash
# 1. Start the connect flow, returns the OAuth URL.
curl "https://zernio.com/api/v1/connect/facebook?profileId=prof_abc123&headless=true&redirect_url=https://your-app.com/cb" \
  -H "Authorization: Bearer YOUR_API_KEY"
# → 200 { "authUrl": "https://www.facebook.com/...", "state": "..." }
# Redirect the end-user's browser to authUrl.

# 2. Meta redirects the end-user to your redirect_url with profileId,
#    tempToken, userProfile (URL-encoded JSON), platform=facebook,
#    step=select_page, and connect_token query params.

# 3. Your backend lists the user's pages.
curl "https://zernio.com/api/v1/connect/facebook/select-page?profileId=prof_abc123&tempToken=TEMP_TOKEN" \
  -H "Authorization: Bearer YOUR_API_KEY"
# → 200 { "pages": [{ "id": "...", "name": "...", ... }] }

# 4. Your backend posts the chosen pageId. userProfile must be the
#    decoded JSON object, not the URL-encoded string.
curl -X POST "https://zernio.com/api/v1/connect/facebook/select-page" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "prof_abc123",
    "pageId": "123456789",
    "tempToken": "TEMP_TOKEN",
    "userProfile": { "id": "1234567890", "username": "...", "displayName": "..." },
    "redirect_url": "https://your-app.com/final-success"
  }'
# → 200 {
#   "redirect_url": "https://your-app.com/final-success?connected=facebook&profileId=...&username=...",
#   "account": { "accountId": "<fb_id>", "platform": "facebook", ... }
# }
# Redirect the browser to redirect_url.
```
</Tab>
</Tabs>

### Connecting Meta Ads only (skip the Page picker)

If your end-user only needs ads (audience uploads, [Conversions API](/platforms/meta-ads/capi#conversions-api), analytics, list ads/campaigns), you can auto-pick the first Page in your backend without ever rendering a picker. The end-user transitions from Meta's OAuth screen directly to your "Connected" screen.

The flow is identical to the headless flow above, but uses `/v1/connect/facebook/ads` to start and your backend skips any UI step. Roughly 70% of the metaads surface (everything that doesn't emit `object_story_spec.page_id`) works regardless of which Page is bound, so picking the first one is fine for ads-only callers.

The remaining 30%, boost Page posts, [Click-to-WhatsApp ads](/platforms/meta-ads/ctwa#click-to-whatsapp-ads), Lead Gen Forms, IS Page-specific. If your end-user later needs those for a specific Page, surface a picker at that point and POST a new `pageId` to `/v1/connect/facebook/select-page`. Our handler updates the existing Facebook account in place, no re-OAuth.

#### Scoping sync to specific ad accounts

By default, sync covers every `act_*` ad account the connected Meta token can see. That's fine for solo accounts but causes leakage for users in agencies or multi-Business-Manager setups (the token sees every account in every BM the user has a role on). To restrict sync to a specific allowlist, pass `adAccountId` (single) or `adAccountIds` (multiple) on `GET /v1/connect/facebook/ads`:

```
?adAccountId=act_1330190928038136
?adAccountIds=act_1330190928038136,act_3686966528111132
```

Each ID is validated against the connected token's `/me/adaccounts` and persisted server-side. The `account.ads.initial_sync_completed` webhook then carries `account.platformAdAccountId` (when scope is exactly one) and `account.platformAdAccountIds` (always) so you can confirm what was synced. Omit both params to keep the legacy "sync everything visible" behavior. Latest call wins; a subsequent connect with new IDs replaces the prior allowlist.

<Callout type="info">
The Node SDK (`@zernio/node`) does not yet expose `connect.listFacebookPages` / `connect.selectFacebookPage`. Use the Python SDK or hit the endpoints directly via fetch for the headless ads-connect flow.
</Callout>

<Tabs items={['Python', 'curl']}>
<Tab value="Python">
```python
# 1. Start the ads connect flow, returns the OAuth URL.
result = client.connect.connect_ads(
    platform="facebook",
    profile_id="prof_abc123",
    headless=True,
    redirect_url="https://your-app.com/cb",
)
# Redirect the end-user's browser to result["authUrl"].

# 2. End-user completes Meta OAuth. Browser lands at your redirect_url
#    with profileId, tempToken, userProfile, step=select_page, etc.

# 3. Your backend lists pages and auto-picks the first one, no UI shown.
pages = client.connect.list_facebook_pages(
    profile_id="prof_abc123",
    temp_token="<from step 2>",
)

result = client.connect.select_facebook_page(
    profile_id="prof_abc123",
    page_id=pages["pages"][0]["id"],
    temp_token="<from step 2>",
    user_profile=json.loads(urllib.parse.unquote("<from step 2>")),
    redirect_url="https://your-app.com/final-success",
)
# Redirect the browser to result["redirect_url"]. The metaads
# SocialAccount is created alongside the Facebook account.
```
</Tab>
<Tab value="curl">
```bash
# 1. Start the ads connect flow, returns the OAuth URL.
curl "https://zernio.com/api/v1/connect/facebook/ads?profileId=prof_abc123&headless=true&redirect_url=https://your-app.com/cb" \
  -H "Authorization: Bearer YOUR_API_KEY"
# → 200 { "authUrl": "...", "state": "..." }

# 2. End-user OAuths. Browser lands at your redirect_url with the
#    standard headless params (profileId, tempToken, userProfile, etc.).

# 3. Your backend lists pages and auto-picks the first one.
curl "https://zernio.com/api/v1/connect/facebook/select-page?profileId=prof_abc123&tempToken=TEMP_TOKEN" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://zernio.com/api/v1/connect/facebook/select-page" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "prof_abc123",
    "pageId": "FIRST_PAGE_ID",
    "tempToken": "TEMP_TOKEN",
    "userProfile": { "id": "...", "username": "...", "displayName": "..." },
    "redirect_url": "https://your-app.com/final-success"
  }'
# Redirect the browser to the response's redirect_url. The metaads
# SocialAccount is created alongside the Facebook account.
```
</Tab>
</Tabs>

## Non-OAuth Platforms

### Bluesky

Bluesky uses app passwords instead of OAuth:

<Callout type="info">
The Node SDK (`@zernio/node`) does not yet expose `connect.connectBlueskyCredentials`. Use the Python SDK or hit the endpoint directly via fetch.
</Callout>

<Tabs items={['Python', 'curl']}>
<Tab value="Python">
```python
account = client.connect.connect_bluesky_credentials(
    identifier="yourhandle.bsky.social",
    app_password="your-app-password",
    state="profile_id=prof_abc123",
)
print(f"Connected: {account['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/connect/bluesky/credentials" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "yourhandle.bsky.social",
    "appPassword": "your-app-password",
    "state": "profile_id=prof_abc123"
  }'
```
</Tab>
</Tabs>

See [Connect Bluesky](/connect/connect-bluesky-credentials) for details.

### Telegram

Telegram uses an access code flow:

1. Call `POST /v1/connect/telegram` to [initiate the connection](/connect/initiate-telegram-connect) and get an access code
2. The user sends this code to the Zernio Telegram bot
3. Poll `GET /v1/connect/telegram` to [check the status](/connect/get-telegram-connect-status) until connected

## Managing Connected Accounts

After connecting, you can:

- [List all accounts](/accounts/list-accounts) - see all connected accounts
- [Update an account](/accounts/update-account) - change settings like default pages or boards
- [Check account health](/accounts/get-all-accounts-health) - verify tokens and permissions are valid
- [Disconnect an account](/accounts/delete-account) - remove a connection

## Updating Selections After Connection

You can change the selected page, organization, or board on an existing connection without re-authenticating:

- [Update Facebook Page](/connect/update-facebook-page)
- [Update LinkedIn Organization](/connect/update-linkedin-organization)
- [Update Pinterest Board](/connect/update-pinterest-boards)
- [Update GMB Location](/connect/update-gmb-location)
- [Update Reddit Subreddit](/connect/update-reddit-subreddits)

---

# Error Handling

Error envelope, stable codes, and HTTP status codes returned by the Zernio API

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Error Response Format

Every non-2xx response returns a flat JSON envelope modeled on Stripe's error shape:

```json
{
  "error": "budgetAmount is required",
  "type": "invalid_request_error",
  "code": "missing_required_field",
  "param": "budgetAmount",
  "docUrl": "https://docs.zernio.com/guides/error-handling"
}
```

| Field | Stable | Description |
|-------|--------|-------------|
| `error` | No | Human-readable message. Reworded freely between releases. Never branch client logic on this. |
| `type` | Yes | High-level category (`invalid_request_error`, `authentication_error`, `permission_error`, `not_found`, `rate_limit_error`, `platform_error`, `api_error`). |
| `code` | Yes | Machine-readable code (e.g. `missing_required_field`, `ads_connection_required`). Use this for programmatic handling. |
| `param` | Yes | Field or query parameter at fault, when applicable. Dotted path for nested fields (e.g. `images.square`). |
| `docUrl` | Yes | Link to error-specific documentation when available. |
| `platform` | Yes | Set on `platform_error`. One of `meta`, `google`, `tiktok`, `linkedin`, `pinterest`, `twitter`. |
| `platformError` | Yes | Set on `platform_error`. The raw upstream payload returned by the platform, forwarded unchanged for inspection. |

<Callout type="info">
**Backward-compatible.** The top-level `error` string is preserved so existing code that reads `response.error` as a string still works. New fields (`type`, `code`, `param`, ...) are added as top-level siblings, not under a nested `details` object.
</Callout>

### Stability contract

- `type` and `code` values are stable once shipped. Build retries, alerting, and i18n against them.
- The `error` message can change freely. Treat it as display-only.
- New codes may be added at any time. Removing a code is a breaking change.

## Error Types

| Type | Default Status | When It Happens |
|------|----------------|-----------------|
| `invalid_request_error` | 400 / 422 | Missing required fields, wrong types, mutually exclusive fields, invalid JSON, unmet preconditions. |
| `authentication_error` | 401 | Missing or invalid API key. |
| `permission_error` | 403 | Valid key but feature requires a plan upgrade or add-on (e.g. Ads add-on for AppSumo users; Usage-plan users have all features bundled). |
| `not_found` | 404 | Resource doesn't exist or isn't accessible under this API key. |
| `rate_limit_error` | 429 | Request rate limit exceeded. See [rate limits](/guides/rate-limits). |
| `platform_error` | 502 (or upstream 4xx) | Upstream social platform (Meta, Google, TikTok, LinkedIn, Pinterest, X) rejected the request. See "Platform Errors" below. |
| `api_error` | 500 | Unexpected server-side error. Safe to retry with backoff. |

## Common Error Codes

| Code | Type | Meaning |
|------|------|---------|
| `missing_required_field` | invalid_request_error | A required field is missing from the body or query. `param` points at the field. |
| `invalid_field_value` | invalid_request_error | A field has the wrong type, format, or enum value. `param` points at the field. |
| `mutually_exclusive_fields` | invalid_request_error | Two incompatible fields were both provided (e.g. `creatives[]` + `adSetId`). |
| `invalid_json_body` | invalid_request_error | Body could not be parsed as JSON. |
| `missing_credentials` | authentication_error | No `Authorization` header. |
| `invalid_credentials` | authentication_error | The API key is invalid, revoked, or expired. |
| `ads_addon_required` | permission_error | The caller does not have the Ads add-on. |
| `feature_not_available` | permission_error | The caller's subscription tier does not include this feature. |
| `account_not_found` | not_found | The referenced account is unknown or not accessible. |
| `ad_not_found` | not_found | The referenced ad is unknown or not accessible. |
| `post_not_found` | not_found | The referenced post is unknown or not accessible. |
| `audience_not_found` | not_found | The referenced audience is unknown or not accessible. |
| `linked_account_required` | invalid_request_error | The connected account is missing a required linked account (e.g. Instagram Ads requires a linked Facebook account). |
| `ads_connection_required` | invalid_request_error | The platform's ads integration isn't connected (e.g. X Ads, TikTok Ads, Google Ads). Call the relevant `/v1/connect/*/ads` flow. |
| `instagram_business_account_unresolved` | invalid_request_error | The Instagram Business Account ID couldn't be resolved from the linked Page. The user must connect their Instagram to the Page in Meta Business Settings. |
| `missing_square_image` | invalid_request_error | Google Display requires both `images.landscape` and `images.square`; only one was sent. |
| `ad_not_commentable` | invalid_request_error | The ad exists but its creative format does not expose a commentable underlying post (e.g. Story ads, Dynamic Product Ads). Returned by `GET /v1/ads/{adId}/comments`. |
| `rate_limited` | rate_limit_error | Request rate limit exceeded on this endpoint. |
| `platform_api_error` | platform_error | Upstream platform rejected the call. Inspect `platform` + `platformError`. |
| `internal_error` | api_error | Unexpected server-side error. |

## Platform Errors

When an upstream platform (Meta, Google, TikTok, LinkedIn, Pinterest, X) rejects a request, Zernio surfaces a `platform_error` envelope with the original payload passed through for inspection.

```json
{
  "error": "Google rejected the ad: NOT_ENOUGH_SQUARE_MARKETING_IMAGE_ASSET",
  "type": "platform_error",
  "code": "platform_api_error",
  "platform": "google",
  "platformError": {
    "code": 3,
    "message": "Request contains an invalid argument.",
    "details": [ { "errors": [ { "errorCode": { "assetError": "NOT_ENOUGH_SQUARE_MARKETING_IMAGE_ASSET" }, "message": "Too few." } ] } ]
  }
}
```

- `platform_error` returns the upstream 4xx status when the platform indicated bad input, or `502 Bad Gateway` when the platform returned 5xx / didn't indicate a status.
- Inspect `platformError` for platform-specific error codes you may want to map for retries or end-user messages.
- `platform` identifies which upstream surfaced the error, so one handler can branch by integration.

## Post Publishing Failures

When a scheduled post fails to publish to one or more platforms, the post status reflects the outcome:

| Post Status | Meaning |
|-------------|---------|
| `published` | All platforms published successfully. |
| `partial` | Some platforms published, others failed. |
| `failed` | All platforms failed to publish. |

Each platform entry in the post has its own `status` and `error` fields:

```json
{
  "post": {
    "status": "partial",
    "platforms": [
      { "platform": "twitter", "status": "published", "platformPostUrl": "https://twitter.com/..." },
      { "platform": "instagram", "status": "failed", "error": "Media processing failed: video too short for Reels" }
    ]
  }
}
```

### Common publishing errors

| Error | Cause | Fix |
|-------|-------|-----|
| Token expired | OAuth token needs refresh | [Check account health](/accounts/get-all-accounts-health) and reconnect. |
| Rate limited by platform | Too many posts to this platform | Wait and retry, or space out posts. |
| Media processing failed | File format/size not supported by platform | Check [platform requirements](/platforms). |
| Duplicate content | Platform rejected identical content | Modify the content slightly. |
| Permissions missing | Account lacks required permissions | Reconnect with proper scopes. |

### Retrying failed posts

For `failed` or `partial` posts, use the [retry endpoint](/posts/retry-post):

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.retryPost('post_123');
```
</Tab>
<Tab value="Python">
```python
result = client.posts.retry_post("post_123")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/posts/post_123/retry" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Only the failed platforms are retried; already-published platforms are skipped.

## Account Health

Proactively check if your connected accounts are healthy before publishing:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const health = await zernio.accounts.getAccountHealth();
```
</Tab>
<Tab value="Python">
```python
health = client.accounts.get_account_health()
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/accounts/health" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

The [health check endpoint](/accounts/get-all-accounts-health) returns token validity, permissions status, and recommendations for each account.

## Webhook Reliability

If you use [webhooks](/webhooks/get-webhook-settings) to track post status:

- Webhooks are delivered at least once (you may receive duplicates); dedupe by event id.
- Failed deliveries are retried with exponential backoff.
- You can view delivery logs in the [webhooks dashboard](/webhooks).

## Best Practices

- **Branch on `type` and `code`**, never on `error` text.
- **Handle `429`** by respecting the `Retry-After` header.
- **Treat `platform_error` upstream 4xx as caller-fixable** (bad input forwarded from the platform) and 5xx / 502 as transient.
- **Monitor account health** periodically to catch token expirations early.
- **Use webhooks** instead of polling for post status updates.
- **Log errors with full context**, include the request body and the entire response envelope (including `platformError`) for debugging.

---

# Media Uploads

How to upload images, videos, and documents for use in posts

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

Posts with media perform better on every platform. Zernio uses presigned URLs for fast, direct uploads up to 5GB.

## Upload Flow

1. Request a presigned URL from `POST /v1/media/presign`
2. Upload the file directly to the returned `uploadUrl` using a PUT request
3. Use the `publicUrl` in your post's `mediaItems` array

### Step 1: Get a Presigned URL

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.media.getMediaPresignedUrl({
  body: {
    filename: 'photo.jpg',
    contentType: 'image/jpeg'
  }
});
const { uploadUrl, publicUrl } = data;
```
</Tab>
<Tab value="Python">
```python
result = client.media.get_media_presigned_url(
    filename="photo.jpg",
    content_type="image/jpeg"
)
upload_url = result["uploadUrl"]
public_url = result["publicUrl"]
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/media/presign" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "photo.jpg",
    "contentType": "image/jpeg"
  }'
```
</Tab>
</Tabs>

**Response:**
```json
{
  "uploadUrl": "https://<bucket>.r2.cloudflarestorage.com/temp/1234567890_abc123_photo.jpg?X-Amz-Signature=...",
  "publicUrl": "https://media.zernio.com/temp/1234567890_abc123_photo.jpg",
  "key": "temp/1234567890_abc123_photo.jpg",
  "expiresIn": 3600
}
```

The `uploadUrl` is valid for one hour (`expiresIn` is in seconds). Uploads start in temporary storage that expires after 7 days; when a post using the `publicUrl` publishes, Zernio copies the media to permanent storage. Make sure posts referencing an upload publish within 7 days of uploading.

### Step 2: Upload the File

Upload directly to the presigned URL (no auth header needed):

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Upload directly to the presigned URL (no auth needed)
await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'image/jpeg' },
  body: fileBuffer
});
```
</Tab>
<Tab value="Python">
```python
import httpx

# Upload directly to the presigned URL (no auth needed)
with open("photo.jpg", "rb") as f:
    httpx.put(upload_url, content=f.read(), headers={"Content-Type": "image/jpeg"})
```
</Tab>
<Tab value="curl">
```bash
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg
```
</Tab>
</Tabs>

### Step 3: Use in a Post

Include the `publicUrl` in your post:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Check out this photo!',
  mediaItems: [
    { url: publicUrl, type: 'image' }
  ],
  platforms: [
    { platform: 'twitter', accountId: 'acc_xyz789' }
  ]
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Check out this photo!",
    media_items=[
        {"url": public_url, "type": "image"}
    ],
    platforms=[
        {"platform": "twitter", "accountId": "acc_xyz789"}
    ]
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out this photo!",
    "mediaItems": [
      { "url": "PUBLIC_URL_FROM_STEP_1", "type": "image" }
    ],
    "platforms": [
      { "platform": "twitter", "accountId": "acc_xyz789" }
    ]
  }'
```
</Tab>
</Tabs>

See the [Presigned Upload endpoint](/media/get-media-presigned-url) for full parameter details.

## Supported Formats

| Type | Formats | Max Size |
|------|---------|----------|
| Images | JPG, PNG, GIF, WebP | 5 GB |
| Videos | MP4, MOV, AVI, WebM | 5 GB |
| Documents | PDF (LinkedIn only) | 100 MB |

## Platform-Specific Media Rules

Each platform has its own requirements for media. Here's a quick reference:

| Platform | Max Images | Max Videos | Notes |
|----------|-----------|-----------|-------|
| Twitter | 4 | 1 | No mixing images and videos |
| Instagram | 10 (carousel) | 1 (Reel) | Stories: single image/video |
| Facebook | Multiple | 1 | Stories: single image/video |
| LinkedIn | 20 images | 1 | Single PDF supported (max 300 pages) |
| TikTok | 35 photos | 1 | No mixing photos and videos |
| YouTube | - | 1 (required) | Optional custom thumbnail |
| Pinterest | 1 | 1 | One image or one video per Pin |
| Bluesky | 4 | 1 | Images auto-compressed to ~1MB |
| Threads | 10 images | 1 | No video carousels |
| Snapchat | 1 | 1 | Required for all post types |

For detailed platform requirements, see the [Platforms](/platforms) section or the [Create Post endpoint](/posts/create-post).

## Auto-Compression

Some platforms have strict file size limits. Zernio handles this automatically:

- **Bluesky**: Images are automatically recompressed to stay under Bluesky's ~1MB blob limit
- **YouTube Thumbnails**: Custom thumbnails via `MediaItem.thumbnail` are processed to meet YouTube's requirements

## Custom Media Per Platform

You can use different media for different platforms in the same post using `customMedia` in the platform entry:

```json
{
  "content": "Same text, different media per platform",
  "mediaItems": [{ "url": "default-image.jpg", "type": "image" }],
  "platforms": [
    { "platform": "twitter", "accountId": "acc_1" },
    {
      "platform": "instagram",
      "accountId": "acc_2",
      "customMedia": [{ "url": "square-image.jpg", "type": "image" }]
    }
  ]
}
```

---

# Platform Settings

Configure Twitter threads, Instagram Stories, TikTok privacy, YouTube visibility, and LinkedIn settings when posting via the Zernio API.

When creating posts, you can provide platform-specific settings in the `platformSpecificData` field of each `PlatformTarget`. This allows you to customize how your content appears and behaves on each social network.

---

## Twitter/X

Create multi-tweet threads with Twitter's `threadItems` array.

| Property | Type | Description |
|----------|------|-------------|
| `threadItems` | array | Sequence of tweets in a thread. First item is the root tweet. |
| `threadItems[].content` | string | Tweet text content |
| `threadItems[].mediaItems` | array | Media attachments for this tweet |
| `geoRestriction` | object | Restrict media visibility to specific countries. Only applies when media is attached (ignored for text-only tweets). The tweet text remains visible globally. |
| `geoRestriction.countries` | string[] | Uppercase ISO 3166-1 alpha-2 codes, max 25. Example: `["US", "ES"]` |

```json
{
  "threadItems": [
    { "content": "🧵 Here's everything you need to know about our API..." },
    { "content": "1/ First, authentication is simple..." },
    { "content": "2/ Next, create your first post..." }
  ]
}
```

---

## Threads (by Meta)

Similar to Twitter, create multi-post threads on Threads.

| Property | Type | Description |
|----------|------|-------------|
| `threadItems` | array | Sequence of posts (root then replies in order) |
| `threadItems[].content` | string | Post text content |
| `threadItems[].mediaItems` | array | Media attachments for this post |

---

## Facebook

| Property | Type | Description |
|----------|------|-------------|
| `contentType` | `"story"` | Publish as a Facebook Page Story (24-hour ephemeral) |
| `firstComment` | string | Auto-post a first comment (feed posts only, not stories) |
| `pageId` | string | Target Page ID for multi-page posting. Use `GET /v1/accounts/{id}/facebook-page` to list available pages. Uses default page if omitted. |
| `geoRestriction` | object | Restrict post visibility to specific countries (hard restriction). `geoRestriction.countries`: array of uppercase ISO 3166-1 alpha-2 codes, max 25. Not supported for stories. |

**Constraints:**
- ❌ Cannot mix videos and images in the same post
- ✅ Up to 10 images for feed posts
- ✅ Stories require media (single image or video)
- ⚠️ Story text captions are not displayed
- ⏱️ Stories disappear after 24 hours
- 📄 Use `pageId` to post to multiple Facebook Pages from the same account connection

```json
{
  "contentType": "story",
  "pageId": "123456789"
}
```

---

## Instagram

| Property | Type | Description |
|----------|------|-------------|
| `contentType` | `"story"` | Publish as an Instagram Story |
| `shareToFeed` | boolean | For Reels only. When `true` (default), the Reel appears on both the Reels tab and profile feed. Set to `false` for Reels tab only. |
| `collaborators` | string[] | Up to 3 usernames to invite as collaborators (feed/Reels only) |
| `firstComment` | string | Auto-post a first comment (not applied to Stories) |
| `trialParams` | object | Trial Reels configuration (Reels only). Trial Reels are initially shared only with non-followers. |
| `trialParams.graduationStrategy` | `"MANUAL"` \| `"SS_PERFORMANCE"` | `MANUAL`: graduate via Instagram app. `SS_PERFORMANCE`: auto-graduate based on performance. |
| `userTags` | array | Tag Instagram users in photos by username and position coordinates (not supported for stories or videos). For carousels, use `mediaIndex` to tag specific slides (defaults to 0). |
| `userTags[].username` | string | Instagram username (@ symbol optional, auto-removed) |
| `userTags[].x` | number | X coordinate from left edge (0.0–1.0) |
| `userTags[].y` | number | Y coordinate from top edge (0.0–1.0) |
| `userTags[].mediaIndex` | integer | Zero-based carousel slide index to tag (defaults to 0). Tags targeting video items or out-of-range indices are ignored. |
| `audioName` | string | Custom name for the original audio in Reels. Replaces the default "Original Audio" label. Only applies to Reels (video posts). Can only be set once - either during creation or later from the Instagram audio page in the app. |
| `thumbOffset` | integer | Millisecond offset from the start of the video to use as the Reel thumbnail. Only applies to Reels. If a custom thumbnail URL (`instagramThumbnail` in mediaItems) is provided, it takes priority. Defaults to 0 (first frame). |

**Constraints:**
- 📐 Feed posts require aspect ratio between **0.8** (4:5) and **1.91** (1.91:1)
- 📱 9:16 images must use `contentType: "story"`
- 🎠 Carousels support up to 10 media items
- 🗜️ Images > 8MB auto-compressed
- 📹 Story videos > 100MB auto-compressed
- 🎬 Reel videos > 300MB auto-compressed
- 🏷️ User tags: supported on images only (not stories/videos); for carousels, use `userTags[].mediaIndex` to tag specific slides (defaults to 0)

```json
{
  "firstComment": "Link in bio! 🔗",
  "collaborators": ["brandpartner", "creator123"],
  "userTags": [
    { "username": "friend_username", "x": 0.5, "y": 0.5 }
  ]
}
```

---

## LinkedIn

| Property | Type | Description |
|----------|------|-------------|
| `organizationUrn` | string | Target LinkedIn Organization URN for multi-organization posting. Format: `urn:li:organization:123456789`. Use `GET /v1/accounts/{id}/linkedin-organizations` to list available organizations. Uses default organization if omitted. |
| `firstComment` | string | Auto-post a first comment |
| `disableLinkPreview` | boolean | Set `true` to disable URL previews (default: `false`) |
| `geoRestriction` | object | Restrict post visibility to specific countries (hard restriction). Organization pages only, requires 300+ targeted followers. |
| `geoRestriction.countries` | string[] | Uppercase ISO 3166-1 alpha-2 codes, max 25. Example: `["US", "ES"]` |

**Constraints:**
- ✅ Up to 20 images per post
- ❌ Multi-video posts not supported
- 📄 Single PDF document posts supported
- 🔗 Link previews auto-generated when no media attached
- 🏢 Use `organizationUrn` to post to multiple organizations from the same account connection

```json
{
  "firstComment": "What do you think? Drop a comment below! 👇",
  "disableLinkPreview": false
}
```

---

## Reddit

| Property | Type | Description |
|----------|------|-------------|
| `subreddit` | string | Target subreddit name (without "r/" prefix). Overrides the default subreddit configured on the account connection. |
| `title` | string | Post title (max 300 chars). Defaults to the first line of content, truncated to 300 characters. |
| `url` | string (URI) | URL for link posts. If provided (and forceSelf is not true), creates a link post instead of a text post. |
| `forceSelf` | boolean | When true, creates a text/self post even when a URL or media is provided. |
| `flairId` | string | Flair ID for the post (required by some subreddits). Use `GET /v1/accounts/{id}/reddit-flairs?subreddit=name` to list available flairs. |
| `nativeVideo` | boolean | Defaults to `true` for video media items (uploads to Reddit's CDN, renders as embedded player). Set `false` to post as a plain link instead. Subreddits that block videos fall back automatically. |
| `videogif` | boolean | When `true`, submit the native video as a silent looping videogif. |
| `videoPosterUrl` | string (URI) | Custom poster/thumbnail. If omitted, Zernio auto-extracts the video's first frame. |

---

## Pinterest

| Property | Type | Description |
|----------|------|-------------|
| `title` | string | Pin title (max 100 chars, defaults to first line of content) |
| `boardId` | string | Target board ID (uses first available if omitted) |
| `link` | string (URI) | Destination link for the pin |
| `coverImageUrl` | string (URI) | Cover image for video pins |
| `coverImageKeyFrameTime` | integer | Key frame time in seconds for video cover |

```json
{
  "title": "10 Tips for Better Photography",
  "boardId": "board-123",
  "link": "https://example.com/photography-tips"
}
```

---

## YouTube

| Property | Type | Description |
|----------|------|-------------|
| `title` | string | Video title (max 100 chars, defaults to first line of content) |
| `visibility` | `"public"` \| `"private"` \| `"unlisted"` | Video visibility (default: `public`) |
| `madeForKids` | boolean | COPPA compliance: Set to `true` if video is made for kids (child-directed content). Defaults to `false`. Videos marked as made for kids have restricted features (no comments, no notifications, limited ad targeting). |
| `firstComment` | string | Auto-post a first comment (max 10,000 chars) |
| `tags` | string[] | Tags/keywords for the video (see constraints below) |
| `containsSyntheticMedia` | boolean | AI-generated content disclosure flag. Set to true if your video contains AI-generated or synthetic content that could be mistaken for real people, places, or events. This helps viewers understand when realistic content has been created or altered using AI. YouTube may add a label to videos when this is set. Added to YouTube Data API in October 2024.
| `categoryId` | string | YouTube video category ID. Defaults to `"22"` (People & Blogs). Common categories: `"1"` (Film & Animation), `"2"` (Autos & Vehicles), `"10"` (Music), `"15"` (Pets & Animals), `"17"` (Sports), `"20"` (Gaming), `"22"` (People & Blogs), `"23"` (Comedy), `"24"` (Entertainment), `"25"` (News & Politics), `"26"` (Howto & Style), `"27"` (Education), `"28"` (Science & Technology). |


**Tag Constraints:**
- ✅ No count limit; duplicates are automatically removed
- 📏 Each tag must be ≤ 100 characters
- 📊 Combined total across all tags ≤ 500 characters (YouTube's limit)

**Automatic Detection:**
- ⏱️ Videos ≤ 3 minutes → **YouTube Shorts**
- 🎬 Videos > 3 minutes → **Regular videos**
- 🖼️ Custom thumbnails supported for regular videos only
- ❌ Custom thumbnails NOT supported for Shorts via API
- 👶 `madeForKids` defaults to `false` (not child-directed)

```json
{
  "title": "How to Use Our API in 5 Minutes",
  "visibility": "public",
  "madeForKids": false,
  "firstComment": "Thanks for watching! 🙏 Subscribe for more tutorials!"
}
```

---

## TikTok

> ⚠️ **Required Consent**: TikTok posts will fail without `content_preview_confirmed: true` and `express_consent_given: true`.

TikTok settings are nested inside `platformSpecificData.tiktokSettings`:

| Property | Type | Description |
|----------|------|-------------|
| `privacy_level` | string | **Required.** Must be one from your account's available options |
| `allow_comment` | boolean | **Required.** Allow comments on the post |
| `allow_duet` | boolean | Required for video posts |
| `allow_stitch` | boolean | Required for video posts |
| `content_preview_confirmed` | boolean | **Required.** Must be `true` |
| `express_consent_given` | boolean | **Required.** Must be `true` |
| `draft` | boolean | Send to Creator Inbox as draft instead of publishing |
| `description` | string | Long-form description for photo posts (max 4000 chars) |
| `video_cover_timestamp_ms` | integer | Thumbnail frame timestamp in ms (default: 1000) |
| `photo_cover_index` | integer | Cover image index for carousels (0-based, default: 0) |
| `auto_add_music` | boolean | Let TikTok add recommended music (photos only) |
| `video_made_with_ai` | boolean | Disclose AI-generated content |
| `commercial_content_type` | `"none"` \| `"brand_organic"` \| `"brand_content"` | Commercial disclosure |
| `brand_partner_promote` | boolean | Brand partner promotion flag |
| `is_brand_organic_post` | boolean | Brand organic post flag |
| `media_type` | `"video"` \| `"photo"` | Optional override (defaults based on media items) |

**Constraints:**
- 📸 Photo carousels support up to 35 images
- 📝 Video titles: up to 2200 characters
- 📝 Photo titles: auto-truncated to 90 chars (use `description` for longer text)
- 🔒 `privacy_level` must match your account's available options (no defaults)

```json
{
  "accountId": "tiktok-012",
  "platformSpecificData": {
    "tiktokSettings": {
      "privacy_level": "PUBLIC_TO_EVERYONE",
      "allow_comment": true,
      "allow_duet": true,
      "allow_stitch": true,
      "content_preview_confirmed": true,
      "express_consent_given": true,
      "description": "Full description here since photo titles are limited to 90 chars..."
    }
  }
}
```

---

## Google Business Profile

| Property | Type | Description |
|----------|------|-------------|
| `topicType` | `"STANDARD"` \| `"EVENT"` \| `"OFFER"` | Post type. Defaults to `STANDARD` if omitted. `EVENT` requires the `event` object. `OFFER` requires `offer` and optionally `event` for the offer period. |
| `event` | object | Event details. Required for `EVENT`, optional for `OFFER`. See schedule format below. |
| `event.title` | string | Event or offer title displayed on Google Search and Maps |
| `event.schedule` | object | Date/time range. Contains `startDate`, `startTime`, `endDate`, `endTime`. Each date field accepts `{ year, month, day }` or an ISO 8601 string (e.g., `"2026-05-15T09:00:00Z"`). Time fields accept `{ hours, minutes }` or an ISO string. |
| `offer` | object | Offer details for `OFFER` posts. All sub-fields optional. |
| `offer.couponCode` | string | Promo/coupon code |
| `offer.redeemOnlineUrl` | string (URI) | URL where the offer can be redeemed online |
| `offer.termsConditions` | string | Terms and conditions text |
| `locationId` | string | Target Google Business location ID for multi-location posting. Format: `locations/123456789`. Use `GET /v1/accounts/{id}/gmb-locations` to list available locations. Uses default location if omitted. |
| `languageCode` | string | BCP 47 language code for the post content (e.g., `en`, `de`, `es`, `fr`). If omitted, language is auto-detected from the post text. |
| `callToAction.type` | enum | `LEARN_MORE`, `BOOK`, `ORDER`, `SHOP`, `SIGN_UP`, `CALL` |
| `callToAction.url` | string (URI) | Destination URL for the CTA button |

**Constraints:**
- ✅ Text content + single image only
- ❌ Videos not supported
- 🔗 CTA button drives user engagement
- 📍 Posts appear on Google Search/Maps
- 🗺️ Use `locationId` to post to multiple locations from the same account connection

```json
{
  "topicType": "EVENT",
  "event": {
    "title": "Grand Opening Weekend",
    "schedule": {
      "startDate": { "year": 2026, "month": 5, "day": 15 },
      "startTime": { "hours": 9, "minutes": 0 },
      "endDate": { "year": 2026, "month": 5, "day": 16 },
      "endTime": { "hours": 17, "minutes": 0 }
    }
  },
  "callToAction": {
    "type": "LEARN_MORE",
    "url": "https://example.com/grand-opening"
  }
}
```

---

## Telegram

| Property | Type | Description |
|----------|------|-------------|
| `parseMode` | `"HTML"` \| `"Markdown"` \| `"MarkdownV2"` | Text formatting mode (default: `HTML`) |
| `disableWebPagePreview` | boolean | Set `true` to disable link previews |
| `disableNotification` | boolean | Send message silently (no notification sound) |
| `protectContent` | boolean | Prevent forwarding and saving of the message |

**Constraints:**
- 📸 Up to 10 images per post (media album)
- 🎬 Up to 10 videos per post (media album)
- 📝 Text-only posts: up to 4096 characters
- 🖼️ Media captions: up to 1024 characters
- 👤 Channel posts show channel name/logo as author
- 🤖 Group posts show "Zernio" as the bot author
- 📊 Analytics not available via API (Telegram limitation)

```json
{
  "parseMode": "HTML",
  "disableWebPagePreview": false,
  "disableNotification": false,
  "protectContent": true
}
```

---

## Snapchat

| Property | Type | Description |
|----------|------|-------------|
| `contentType` | `"story"` \| `"saved_story"` \| `"spotlight"` | Type of Snapchat content (default: `story`) |

**Content Types:**
- **Story** (default): Ephemeral snap visible for 24 hours. No caption/text supported.
- **Saved Story**: Permanent story saved to your Public Profile. Uses post content as title (max 45 chars).
- **Spotlight**: Video for Snapchat's entertainment feed. Supports description (max 160 chars) with hashtags.

**Constraints:**
- 👤 Requires a Snapchat Public Profile
- 🖼️ Media required for all content types (no text-only posts)
- 1️⃣ Only one media item per post
- 📸 Images: max 20 MB, JPEG/PNG format
- 🎬 Videos: max 500 MB, MP4 format, 5-60 seconds, min 540x960px
- 📐 Aspect ratio: 9:16 recommended
- 🔒 Media is automatically encrypted (AES-256-CBC) before upload

```json
{
  "contentType": "saved_story"
}
```

---

## Bluesky

Bluesky doesn't require `platformSpecificData` but has important constraints:

**Constraints:**
- 🖼️ Up to 4 images per post
- 🗜️ Images > ~1MB are automatically recompressed to meet Bluesky's blob size limit
- 🔗 Link previews auto-generated when no media is attached

```json
{
  "content": "Just posted this via the Zernio API! 🦋",
  "platforms": [
    {
      "platform": "bluesky",
      "accountId": "bluesky-123"
    }
  ]
}
```

---

## Complete Example

Here's a real-world example posting to multiple platforms with platform-specific settings:

```json
{
  "content": "Excited to announce our new product! 🎉",
  "mediaItems": [
    { "url": "https://example.com/product.jpg", "type": "image" }
  ],
  "platforms": [
    {
      "platform": "twitter",
      "accountId": "twitter-123",
      "platformSpecificData": {
        "threadItems": [
          { "content": "Excited to announce our new product! 🎉" },
          { "content": "Here's what makes it special... 🧵" }
        ]
      }
    },
    {
      "platform": "instagram",
      "accountId": "instagram-456",
      "platformSpecificData": {
        "firstComment": "Link in bio! 🔗",
        "collaborators": ["brandpartner"]
      }
    },
    {
      "platform": "linkedin",
      "accountId": "linkedin-789",
      "platformSpecificData": {
        "firstComment": "What features would you like to see next? 👇"
      }
    },
    {
      "platform": "tiktok",
      "accountId": "tiktok-012",
      "platformSpecificData": {
        "tiktokSettings": {
          "privacy_level": "PUBLIC_TO_EVERYONE",
          "allow_comment": true,
          "allow_duet": false,
          "allow_stitch": false,
          "content_preview_confirmed": true,
          "express_consent_given": true
        }
      }
    },
    {
      "platform": "youtube",
      "accountId": "youtube-345",
      "platformSpecificData": {
        "title": "New Product Announcement",
        "visibility": "public",
        "firstComment": "Thanks for watching! Subscribe for updates! 🔔"
      }
    },
    {
      "platform": "googlebusiness",
      "accountId": "gbp-678",
      "platformSpecificData": {
        "topicType": "EVENT",
        "event": {
          "title": "New Product Launch",
          "schedule": {
            "startDate": { "year": 2026, "month": 6, "day": 1 },
            "startTime": { "hours": 10, "minutes": 0 },
            "endDate": { "year": 2026, "month": 6, "day": 1 },
            "endTime": { "hours": 18, "minutes": 0 }
          }
        },
        "callToAction": {
          "type": "SHOP",
          "url": "https://example.com/product"
        }
      }
    },
    {
      "platform": "telegram",
      "accountId": "telegram-901",
      "platformSpecificData": {
        "parseMode": "HTML",
        "disableNotification": false,
        "protectContent": false
      }
    },
    {
      "platform": "snapchat",
      "accountId": "snapchat-234",
      "platformSpecificData": {
        "contentType": "saved_story"
      }
    }
  ]
}
```

---

# Queue Scheduling

Drip-feed posts automatically using profile queues instead of computing schedule times yourself

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

Queues let you define recurring posting slots on a profile (for example, every weekday at 9:00 and 17:00). Instead of computing a `scheduledFor` time for every post, pass `queuedFromProfile` when creating the post and Zernio assigns it to the next available slot.

This is the answer to "how do I drip-feed 50 posts": create them in a loop with `queuedFromProfile` and each one lands on the next free slot, in order.

## Schedule a post via queue

Pass the profile ID as `queuedFromProfile` instead of `scheduledFor`:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.posts.createPost({
  body: {
    content: 'Post 1 of 50',
    platforms: [
      { platform: 'twitter', accountId: 'acc_xyz789' }
    ],
    queuedFromProfile: 'YOUR_PROFILE_ID'
  }
});
console.log(data.post.scheduledFor); // the slot Zernio assigned
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Post 1 of 50",
    platforms=[
        {"platform": "twitter", "accountId": "acc_xyz789"}
    ],
    queued_from_profile="YOUR_PROFILE_ID",
)
print(result["post"]["scheduledFor"])  # the slot Zernio assigned
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Post 1 of 50",
    "platforms": [
      { "platform": "twitter", "accountId": "acc_xyz789" }
    ],
    "queuedFromProfile": "YOUR_PROFILE_ID"
  }'
```
</Tab>
</Tabs>

The response comes back with `status: "scheduled"`, the assigned time in `scheduledFor`, and the queue context echoed in `queuedFromProfile` and `queueId`. Repeat the call for each post in your batch; every post takes the next free slot.

## Using a specific queue

A profile can have multiple queues. Pass `queueId` alongside `queuedFromProfile` to target one; if omitted, the profile's default queue is used.

## Previewing the next slot

`GET /v1/queue/next-slot` returns the next available slot for a profile. Use it for display purposes only (for example, showing the user when their post would go out).

<Callout type="warn">
Do not call `/v1/queue/next-slot` and pass the returned time as `scheduledFor`. That bypasses queue locking, so two concurrent creates can land on the same slot. Always schedule queue posts with `queuedFromProfile` and let the API assign the time.
</Callout>

See the [Create post endpoint](/posts/create-post) for all fields, and the [Queue endpoints](/queue/list-queue-slots) for managing slots.

---

# Rate Limits

API rate limits by plan, posting velocity limits, and how to handle throttling

## API Request Limits

Rate limits are applied per API key, bucketed by your team's total connected social accounts. The more accounts you've scaled to, the higher your req/min ceiling.

| Connected accounts | Requests per Minute |
|---|---|
| 0–2 (free tier) | 60 |
| 3–2,000 | 600 |
| 2,001+ | 1,200 |

Connected accounts are counted across the whole billing team (owner + invited members).

Legacy AppSumo lifetime tiers get a flat **600 req/min** regardless of tier.

### Per-Second Limits for Analytics Endpoints

Analytics endpoints are rate limited on a **1-second window** rather than a 1-minute window. The per-second cap is derived from your req/min limit:

```
requests_per_second = max(2, requests_per_minute / 60)
```

Every plan has a floor of **2 req/s**, so even free-tier keys can burst at the same baseline.

| Connected accounts | Requests per Minute | Requests per Second (analytics) |
|---|---|---|
| 0–2 (free tier) | 60 | 2 |
| 3–2,000 | 600 | 10 |
| 2,001+ | 1,200 | 20 |

Legacy AppSumo lifetime tiers get a flat **10 req/s** on analytics endpoints regardless of tier.

These endpoints use the per-second window:

- `GET /api/v1/analytics`
- `GET /api/v1/analytics/best-time`
- `GET /api/v1/analytics/content-decay`
- `GET /api/v1/analytics/daily-metrics`
- `GET /api/v1/analytics/post-timeline`
- `GET /api/v1/analytics/posting-frequency`

All other endpoints continue to use the standard 1-minute window from the table above.

### Rate Limit Headers

Every API response includes these headers:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Your plan's requests-per-minute limit |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |

### Handling Rate Limits

When you exceed the limit, the API returns `429 Too Many Requests`:

```json
{
  "error": "Rate limit exceeded. Please try again later."
}
```

Best approach: check `X-RateLimit-Remaining` before making requests, and back off when it's low. If you receive a `429`, wait until `X-RateLimit-Reset` before retrying.

## Posting Velocity Limits

Independent of API rate limits, there are limits on how fast you can publish posts to prevent platform-level throttling:

| Scenario | Limit |
|----------|-------|
| Posts per account | Platform-dependent cooldown between posts |
| Immediate publishes | Subject to platform rate limits |
| Bulk uploads | Validated and queued, published according to schedule |

These limits protect your accounts from being flagged by social platforms. If a post is rejected due to velocity limiting, you'll receive an error explaining the cooldown period.

## Analytics Data Freshness

Analytics endpoints have their own caching and refresh behavior rather than strict rate limits:

- **Post analytics** - Cached for 60 minutes. Requests trigger a background refresh if cache is stale. No rate limit on API requests.
- **Follower stats** - Refreshed once per day automatically.
- **YouTube daily views** - Data has a 2-3 day delay from YouTube's Analytics API.

See the [Analytics endpoints](/analytics/get-analytics) for details.

## Tips for Staying Within Limits

- **Use pagination** - Don't fetch all resources at once. Use `limit` and `offset` parameters.
- **Cache responses** - Store data locally instead of re-fetching frequently.
- **Use webhooks** - Subscribe to [webhooks](/webhooks/get-webhook-settings) instead of polling for post status changes.
- **Batch operations** - Use [bulk upload](/posts/bulk-upload-posts) instead of creating posts one at a time.

---

# Analytics

Google Business performance and search keyword analytics

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Analytics

> **Included** — Analytics is bundled with every paid account on the [Usage plan](/pricing).

<Callout type="warn">
**Per-post analytics are not available for Google Business Profile.** Google [deprecated the per-post insights endpoint](https://developers.google.com/my-business/content/sunset-dates) and did not ship a replacement. Per-post views, clicks and likes for GBP posts no longer exist on Google's side, not on Zernio, not anywhere.

For GBP engagement data, use the **location-level Performance API** documented below.
</Callout>

### Performance Metrics

The [Performance API](/analytics/get-google-business-performance) returns daily time-series data for your Google Business Profile location. Metrics include impressions (Maps/Search, desktop/mobile), website clicks, call clicks, direction requests, conversations, bookings, and food orders. Data may be delayed 2-3 days. Max 18 months of historical data.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.analytics.getGoogleBusinessPerformance({
  query: {
    accountId: 'YOUR_ACCOUNT_ID',
    startDate: '2026-01-01',
    endDate: '2026-03-31'
  }
});
console.log(data.metrics);
// { WEBSITE_CLICKS: { total: 42, values: [...] }, CALL_CLICKS: { total: 7, values: [...] }, ... }
```
</Tab>
<Tab value="Python">
```python
response = client.analytics.get_google_business_performance(
    account_id='YOUR_ACCOUNT_ID',
    start_date='2026-01-01',
    end_date='2026-03-31'
)
print(response.metrics)
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics/googlebusiness/performance?accountId=YOUR_ACCOUNT_ID&startDate=2026-01-01&endDate=2026-03-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Available metrics: `BUSINESS_IMPRESSIONS_DESKTOP_MAPS`, `BUSINESS_IMPRESSIONS_DESKTOP_SEARCH`, `BUSINESS_IMPRESSIONS_MOBILE_MAPS`, `BUSINESS_IMPRESSIONS_MOBILE_SEARCH`, `BUSINESS_CONVERSATIONS`, `BUSINESS_DIRECTION_REQUESTS`, `CALL_CLICKS`, `WEBSITE_CLICKS`, `BUSINESS_BOOKINGS`, `BUSINESS_FOOD_ORDERS`, `BUSINESS_FOOD_MENU_CLICKS`.

### Search Keywords

The [Search Keywords API](/analytics/get-google-business-search-keywords) returns keywords that triggered impressions for your location, aggregated monthly. Keywords below a minimum impression threshold set by Google are excluded. Max 18 months of historical data.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.analytics.getGoogleBusinessSearchKeywords({
  query: {
    accountId: 'YOUR_ACCOUNT_ID',
    startMonth: '2026-01',
    endMonth: '2026-03'
  }
});
data.keywords.forEach(k => console.log(`${k.keyword}: ${k.impressions} impressions`));
```
</Tab>
<Tab value="Python">
```python
response = client.analytics.get_google_business_search_keywords(
    account_id='YOUR_ACCOUNT_ID',
    start_month='2026-01',
    end_month='2026-03'
)
for k in response.keywords:
    print(f"{k.keyword}: {k.impressions} impressions")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics/googlebusiness/search-keywords?accountId=YOUR_ACCOUNT_ID&startMonth=2026-01&endMonth=2026-03" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

---

# Business Profile Management

Manage location details, attributes, services, menus, media, reviews, and verifications

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Business Profile Management

Beyond posting, you can manage your Google Business Profile listing directly through the API. Each subsection below covers a specific management feature.

### Food Menus

Manage food menus for locations that support them (restaurants, cafes, etc.). Menu items support `price` (with currency code), `dietaryRestriction` (VEGETARIAN, VEGAN, GLUTEN_FREE), `allergen` (DAIRY, GLUTEN, SHELLFISH), `spiciness`, `servesNumPeople`, and `preparationMethods`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Get menus
const menus = await zernio.gmbfoodmenus.getGoogleBusinessFoodMenus('YOUR_ACCOUNT_ID');
console.log('Food menus:', menus);

// Update menus
await zernio.gmbfoodmenus.updateGoogleBusinessFoodMenus('YOUR_ACCOUNT_ID', {
  menus: [{
    labels: [{ displayName: 'Lunch Menu', languageCode: 'en' }],
    sections: [{
      labels: [{ displayName: 'Appetizers' }],
      items: [{
        labels: [{ displayName: 'Caesar Salad', description: 'Romaine, parmesan, croutons' }],
        attributes: {
          price: { currencyCode: 'USD', units: '12' },
          dietaryRestriction: ['VEGETARIAN']
        }
      }]
    }]
  }],
  updateMask: 'menus'
});
```
</Tab>
<Tab value="Python">
```python
# Get menus
menus = client.accounts.get_google_business_food_menus("YOUR_ACCOUNT_ID")
print("Food menus:", menus)

# Update menus
client.accounts.update_google_business_food_menus("YOUR_ACCOUNT_ID",
    menus=[{
        "labels": [{"displayName": "Lunch Menu", "languageCode": "en"}],
        "sections": [{
            "labels": [{"displayName": "Appetizers"}],
            "items": [{
                "labels": [{"displayName": "Caesar Salad", "description": "Romaine, parmesan, croutons"}],
                "attributes": {
                    "price": {"currencyCode": "USD", "units": "12"},
                    "dietaryRestriction": ["VEGETARIAN"]
                }
            }]
        }]
    }],
    update_mask="menus"
)
```
</Tab>
<Tab value="curl">
```bash
# Get menus
curl -X GET https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-food-menus \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update menus
curl -X PUT https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-food-menus \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "menus": [{
      "labels": [{"displayName": "Lunch Menu", "languageCode": "en"}],
      "sections": [{
        "labels": [{"displayName": "Appetizers"}],
        "items": [{
          "labels": [{"displayName": "Caesar Salad", "description": "Romaine, parmesan, croutons"}],
          "attributes": {
            "price": {"currencyCode": "USD", "units": "12"},
            "dietaryRestriction": ["VEGETARIAN"]
          }
        }]
      }]
    }],
    "updateMask": "menus"
  }'
```
</Tab>
</Tabs>

See the [GMB Food Menus API Reference](/google-business/get-google-business-food-menus) for full schema details.

### Location Details

Read and update your business information including hours, special hours, description, phone numbers, and website. Use `readMask` to request specific fields and `updateMask` to update them. Available fields include `regularHours`, `specialHours`, `profile.description`, `websiteUri`, and `phoneNumbers`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Get location details
const details = await zernio.gmblocationdetails.getGoogleBusinessLocationDetails('YOUR_ACCOUNT_ID', {
  readMask: 'regularHours,specialHours,profile,websiteUri'
});

// Update business hours
await zernio.gmblocationdetails.updateGoogleBusinessLocationDetails('YOUR_ACCOUNT_ID', {
  updateMask: 'regularHours',
  regularHours: {
    periods: [
      { openDay: 'MONDAY', openTime: '09:00', closeDay: 'MONDAY', closeTime: '17:00' },
      { openDay: 'TUESDAY', openTime: '09:00', closeDay: 'TUESDAY', closeTime: '17:00' }
    ]
  }
});
```
</Tab>
<Tab value="Python">
```python
# Get location details
details = client.accounts.get_google_business_location_details("YOUR_ACCOUNT_ID",
    read_mask="regularHours,specialHours,profile,websiteUri"
)

# Update business hours
client.accounts.update_google_business_location_details("YOUR_ACCOUNT_ID",
    update_mask="regularHours",
    regular_hours={
        "periods": [
            {"openDay": "MONDAY", "openTime": "09:00", "closeDay": "MONDAY", "closeTime": "17:00"},
            {"openDay": "TUESDAY", "openTime": "09:00", "closeDay": "TUESDAY", "closeTime": "17:00"}
        ]
    }
)
```
</Tab>
<Tab value="curl">
```bash
# Get location details
curl -X GET "https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-location-details?readMask=regularHours,specialHours,profile,websiteUri" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update business hours
curl -X PUT https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-location-details \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updateMask": "regularHours",
    "regularHours": {
      "periods": [
        {"openDay": "MONDAY", "openTime": "09:00", "closeDay": "MONDAY", "closeTime": "17:00"},
        {"openDay": "TUESDAY", "openTime": "09:00", "closeDay": "TUESDAY", "closeTime": "17:00"}
      ]
    }
  }'
```
</Tab>
</Tabs>

See the [GMB Location Details API Reference](/google-business/get-google-business-location-details) for the full schema.

### Verification

Check a location's verification status and drive the verification flow programmatically. `GET /gmb-verifications` returns the location's Voice of Merchant state plus its verification history. `hasVoiceOfMerchant` tells you whether the listing is verified and published; when it is `false`, `verify.hasPendingVerification` tells you whether a verification is already in progress (so you can distinguish "pending" from "not started").

To verify a location: call `POST /gmb-verifications/options` to see which methods Google offers, `POST /gmb-verifications` to start one (Google then mails a postcard, calls, or texts the business), and `POST /gmb-verifications/{verificationId}/complete` with the PIN to finish.

<Callout type="info">
Reviews, edits, and other listing data only surface once a location is matched to a published Google Maps place (it has a `placeId`, visible via [Location Details](#location-details)) and has Voice of Merchant. If `GET /gmb-reviews` returns an empty array for a listing that has reviews on Google, check `hasVoiceOfMerchant` here first: the connected location is usually not yet verified or not yet matched to its Maps place.
</Callout>

<Callout type="warn">
`POST /gmb-verifications` is a real-world action: it triggers Google to send a postcard, call, or SMS to the business. Service-area businesses must include a `context` (service address) when fetching options, otherwise Google returns a 400.
</Callout>

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// 1. Check verification state
const { data: state } = await zernio.gmbverifications.getGoogleBusinessVerifications({
  path: { accountId: 'YOUR_ACCOUNT_ID' }
});

// 2. See which methods are available
const { data: options } = await zernio.gmbverifications.fetchGoogleBusinessVerificationOptions({
  path: { accountId: 'YOUR_ACCOUNT_ID' },
  body: { languageCode: 'en-US' }
});

// 3. Start a verification (e.g. by SMS)
const { data: started } = await zernio.gmbverifications.startGoogleBusinessVerification({
  path: { accountId: 'YOUR_ACCOUNT_ID' },
  body: { method: 'SMS', languageCode: 'en-US', phoneNumber: '+14155550123' }
});

// 4. Complete it with the PIN Google sent
await zernio.gmbverifications.completeGoogleBusinessVerification({
  path: { accountId: 'YOUR_ACCOUNT_ID', verificationId: 'VERIFICATION_ID' },
  body: { pin: '123456' }
});
```
</Tab>
<Tab value="Python">
```python
# 1. Check verification state
state = client.accounts.get_google_business_verifications("YOUR_ACCOUNT_ID")

# 2. See which methods are available
options = client.accounts.fetch_google_business_verification_options(
    "YOUR_ACCOUNT_ID", language_code="en-US"
)

# 3. Start a verification (e.g. by SMS)
started = client.accounts.start_google_business_verification(
    "YOUR_ACCOUNT_ID", method="SMS", language_code="en-US", phone_number="+14155550123"
)

# 4. Complete it with the PIN Google sent
client.accounts.complete_google_business_verification(
    "YOUR_ACCOUNT_ID", "VERIFICATION_ID", pin="123456"
)
```
</Tab>
<Tab value="curl">
```bash
# 1. Check verification state
curl -X GET "https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-verifications" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. See which methods are available
curl -X POST "https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-verifications/options" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "languageCode": "en-US" }'

# 3. Start a verification (e.g. by SMS)
curl -X POST "https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-verifications" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "method": "SMS", "languageCode": "en-US", "phoneNumber": "+14155550123" }'

# 4. Complete it with the PIN Google sent
curl -X POST "https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-verifications/VERIFICATION_ID/complete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pin": "123456" }'
```
</Tab>
</Tabs>

See the [GMB Verification API Reference](/google-business/get-google-business-verifications) for the full schema.

### Media (Photos)

Upload, list, and delete photos for your Google Business Profile listing. Photo categories: `COVER`, `PROFILE`, `LOGO`, `EXTERIOR`, `INTERIOR`, `FOOD_AND_DRINK`, `MENU`, `PRODUCT`, `TEAMS`, `ADDITIONAL`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// List photos
const media = await zernio.gmbmedia.listGoogleBusinessMedia('YOUR_ACCOUNT_ID');

// Upload a photo
await zernio.gmbmedia.createGoogleBusinessMedia('YOUR_ACCOUNT_ID', {
  sourceUrl: 'https://example.com/photos/interior.jpg',
  description: 'Dining area with outdoor seating',
  category: 'INTERIOR'
});
```
</Tab>
<Tab value="Python">
```python
# List photos
media = client.accounts.list_google_business_media("YOUR_ACCOUNT_ID")

# Upload a photo
client.accounts.create_google_business_media("YOUR_ACCOUNT_ID",
    source_url="https://example.com/photos/interior.jpg",
    description="Dining area with outdoor seating",
    category="INTERIOR"
)
```
</Tab>
<Tab value="curl">
```bash
# List photos
curl -X GET https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-media \
  -H "Authorization: Bearer YOUR_API_KEY"

# Upload a photo
curl -X POST https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://example.com/photos/interior.jpg",
    "description": "Dining area with outdoor seating",
    "category": "INTERIOR"
  }'
```
</Tab>
</Tabs>

See the [GMB Media API Reference](/google-business/list-google-business-media) for full details.

### Attributes

Manage amenities and services like delivery, Wi-Fi, outdoor seating, and payment types. Available attributes vary by business category. Common ones include `has_dine_in`, `has_takeout`, `has_delivery`, `has_wifi`, `has_outdoor_seating`, and `pay_credit_card_types_accepted`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Get attributes
const attrs = await zernio.gmbattributes.getGoogleBusinessAttributes('YOUR_ACCOUNT_ID');

// Update attributes
await zernio.gmbattributes.updateGoogleBusinessAttributes('YOUR_ACCOUNT_ID', {
  attributes: [
    { name: 'has_delivery', values: [true] },
    { name: 'has_outdoor_seating', values: [true] }
  ],
  attributeMask: 'has_delivery,has_outdoor_seating'
});
```
</Tab>
<Tab value="Python">
```python
# Get attributes
attrs = client.accounts.get_google_business_attributes("YOUR_ACCOUNT_ID")

# Update attributes
client.accounts.update_google_business_attributes("YOUR_ACCOUNT_ID",
    attributes=[
        {"name": "has_delivery", "values": [True]},
        {"name": "has_outdoor_seating", "values": [True]}
    ],
    attribute_mask="has_delivery,has_outdoor_seating"
)
```
</Tab>
<Tab value="curl">
```bash
# Get attributes
curl -X GET https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-attributes \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update attributes
curl -X PUT https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-attributes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": [
      {"name": "has_delivery", "values": [true]},
      {"name": "has_outdoor_seating", "values": [true]}
    ],
    "attributeMask": "has_delivery,has_outdoor_seating"
  }'
```
</Tab>
</Tabs>

See the [GMB Attributes API Reference](/google-business/get-google-business-attributes) for full details.

### Place Actions

Manage booking, ordering, and reservation buttons that appear on your listing. Action types: `APPOINTMENT`, `ONLINE_APPOINTMENT`, `DINING_RESERVATION`, `FOOD_ORDERING`, `FOOD_DELIVERY`, `FOOD_TAKEOUT`, `SHOP_ONLINE`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// List place actions
const actions = await zernio.gmbplaceactions.listGoogleBusinessPlaceActions('YOUR_ACCOUNT_ID');

// Create a place action
await zernio.gmbplaceactions.createGoogleBusinessPlaceAction('YOUR_ACCOUNT_ID', {
  uri: 'https://order.ubereats.com/mybusiness',
  placeActionType: 'FOOD_ORDERING'
});
```
</Tab>
<Tab value="Python">
```python
# List place actions
actions = client.accounts.list_google_business_place_actions("YOUR_ACCOUNT_ID")

# Create a place action
client.accounts.create_google_business_place_action("YOUR_ACCOUNT_ID",
    uri="https://order.ubereats.com/mybusiness",
    place_action_type="FOOD_ORDERING"
)
```
</Tab>
<Tab value="curl">
```bash
# List place actions
curl -X GET https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-place-actions \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create a place action
curl -X POST https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-place-actions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://order.ubereats.com/mybusiness",
    "placeActionType": "FOOD_ORDERING"
  }'
```
</Tab>
</Tabs>

See the [GMB Place Actions API Reference](/google-business/list-google-business-place-actions) for full details.

### Services

Get and manage the services offered by a Google Business Profile location. Services can be structured (using a predefined `serviceTypeId`) or free-form (custom label), with an optional `price`.

> **Note:** Google's API requires full replacement of the service list. Use `PUT /v1/accounts/{accountId}/gmb-services` to replace the entire list.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Get services
const services = await zernio.gmbservices.getGoogleBusinessServices('YOUR_ACCOUNT_ID');
console.log('Services:', services);

// Replace services (full replacement)
await zernio.gmbservices.updateGoogleBusinessServices('YOUR_ACCOUNT_ID', {
  serviceItems: [
    {
      freeFormServiceItem: {
        category: 'categories/gcid:plumber',
        label: {
          displayName: 'Pipe Repair',
          description: 'Emergency and scheduled pipe repair'
        }
      },
      price: { currencyCode: 'USD', units: '150' }
    }
  ]
});
```
</Tab>
<Tab value="Python">
```python
# Get services
services = client.gmb_services.get_google_business_services("YOUR_ACCOUNT_ID")
print("Services:", services)

# Replace services (full replacement)
client.gmb_services.update_google_business_services("YOUR_ACCOUNT_ID",
    service_items=[
        {
            "freeFormServiceItem": {
                "category": "categories/gcid:plumber",
                "label": {
                    "displayName": "Pipe Repair",
                    "description": "Emergency and scheduled pipe repair"
                }
            },
            "price": {"currencyCode": "USD", "units": "150"}
        }
    ]
)
```
</Tab>
<Tab value="curl">
```bash
# Get services
curl -X GET https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-services \
  -H "Authorization: Bearer YOUR_API_KEY"

# Replace services (full replacement)
curl -X PUT https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-services \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceItems": [
      {
        "freeFormServiceItem": {
          "category": "categories/gcid:plumber",
          "label": {
            "displayName": "Pipe Repair",
            "description": "Emergency and scheduled pipe repair"
          }
        },
        "price": {
          "currencyCode": "USD",
          "units": "150"
        }
      }
    ]
  }'
```
</Tab>
</Tabs>

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// List place actions
const actions = await zernio.gmbplaceactions.listGoogleBusinessPlaceActions('YOUR_ACCOUNT_ID');

// Create a place action
await zernio.gmbplaceactions.createGoogleBusinessPlaceAction('YOUR_ACCOUNT_ID', {
  uri: 'https://order.ubereats.com/mybusiness',
  placeActionType: 'FOOD_ORDERING'
});
```
</Tab>
<Tab value="Python">
```python
# List place actions
actions = client.accounts.list_google_business_place_actions("YOUR_ACCOUNT_ID")

# Create a place action
client.accounts.create_google_business_place_action("YOUR_ACCOUNT_ID",
    uri="https://order.ubereats.com/mybusiness",
    place_action_type="FOOD_ORDERING"
)
```
</Tab>
<Tab value="curl">
```bash
# List place actions
curl -X GET https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-place-actions \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create a place action
curl -X POST https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-place-actions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://order.ubereats.com/mybusiness",
    "placeActionType": "FOOD_ORDERING"
  }'
```
</Tab>
</Tabs>

See the [GMB Place Actions API Reference](/google-business/list-google-business-place-actions) for full details.

#### Update an existing place action

Use `PATCH /v1/accounts/{accountId}/gmb-place-actions` to update an existing action link (change `uri` and/or `placeActionType`). Only fields included in the request body are updated.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
await zernio.gmbplaceactions.updateGoogleBusinessPlaceAction('YOUR_ACCOUNT_ID', {
  name: 'locations/123/placeActionLinks/456',
  uri: 'https://order.doordash.com/joespizza'
});
```
</Tab>
<Tab value="Python">
```python
client.accounts.update_google_business_place_action("YOUR_ACCOUNT_ID",
    name="locations/123/placeActionLinks/456",
    uri="https://order.doordash.com/joespizza"
)
```
</Tab>
<Tab value="curl">
```bash
curl -X PATCH "https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-place-actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "locations/123/placeActionLinks/456",
    "uri": "https://order.doordash.com/joespizza"
  }'
```
</Tab>
</Tabs>

---

# Event & Offer Posts

Create event and offer posts via topicType

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Event and Offer Posts (topicType)

Google Business Profile supports three post types via `platformSpecificData.topicType`:

| topicType | When to use | Required fields |
|----------|-------------|----------------|
| `STANDARD` | Regular updates | None |
| `EVENT` | Announcements with a date range (grand openings, live music, workshops) | `event` |
| `OFFER` | Promotions and discounts | `offer` |

> **Note:** For `EVENT` posts, Google returns a 400 error if `event` is omitted.

### Event Post Example

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Join us for our Grand Opening Weekend! Food, music, and giveaways.',
  mediaItems: [
    { type: 'image', url: 'https://example.com/grand-opening.jpg' }
  ],
  platforms: [{
    platform: 'googlebusiness',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      topicType: 'EVENT',
      event: {
        title: 'Grand Opening Weekend',
        schedule: {
          startDate: { year: 2026, month: 5, day: 15 },
          startTime: { hours: 9, minutes: 0 },
          endDate: { year: 2026, month: 5, day: 16 },
          endTime: { hours: 17, minutes: 0 }
        }
      },
      callToAction: {
        type: 'LEARN_MORE',
        url: 'https://mybusiness.com/grand-opening'
      }
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Join us for our Grand Opening Weekend! Food, music, and giveaways.",
    media_items=[
        {"type": "image", "url": "https://example.com/grand-opening.jpg"}
    ],
    platforms=[{
        "platform": "googlebusiness",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "topicType": "EVENT",
            "event": {
                "title": "Grand Opening Weekend",
                "schedule": {
                    "startDate": {"year": 2026, "month": 5, "day": 15},
                    "startTime": {"hours": 9, "minutes": 0},
                    "endDate": {"year": 2026, "month": 5, "day": 16},
                    "endTime": {"hours": 17, "minutes": 0}
                }
            },
            "callToAction": {
                "type": "LEARN_MORE",
                "url": "https://mybusiness.com/grand-opening"
            }
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Join us for our Grand Opening Weekend! Food, music, and giveaways.",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/grand-opening.jpg"}
    ],
    "platforms": [{
      "platform": "googlebusiness",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "topicType": "EVENT",
        "event": {
          "title": "Grand Opening Weekend",
          "schedule": {
            "startDate": {"year": 2026, "month": 5, "day": 15},
            "startTime": {"hours": 9, "minutes": 0},
            "endDate": {"year": 2026, "month": 5, "day": 16},
            "endTime": {"hours": 17, "minutes": 0}
          }
        },
        "callToAction": {
          "type": "LEARN_MORE",
          "url": "https://mybusiness.com/grand-opening"
        }
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Offer Post Example

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'This weekend only: Save 20% on all services. Use code SAVE20.',
  mediaItems: [
    { type: 'image', url: 'https://example.com/save20.jpg' }
  ],
  platforms: [{
    platform: 'googlebusiness',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      topicType: 'OFFER',
      offer: {
        offerType: 'OFFER',
        redeemOnlineUrl: 'https://mybusiness.com/redeem',
        couponCode: 'SAVE20',
        termsConditions: 'Valid Fri–Sun only. One per customer.'
      },
      callToAction: {
        type: 'SHOP',
        url: 'https://mybusiness.com/services'
      }
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="This weekend only: Save 20% on all services. Use code SAVE20.",
    media_items=[
        {"type": "image", "url": "https://example.com/save20.jpg"}
    ],
    platforms=[{
        "platform": "googlebusiness",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "topicType": "OFFER",
            "offer": {
                "offerType": "OFFER",
                "redeemOnlineUrl": "https://mybusiness.com/redeem",
                "couponCode": "SAVE20",
                "termsConditions": "Valid Fri–Sun only. One per customer."
            },
            "callToAction": {
                "type": "SHOP",
                "url": "https://mybusiness.com/services"
            }
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This weekend only: Save 20% on all services. Use code SAVE20.",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/save20.jpg"}
    ],
    "platforms": [{
      "platform": "googlebusiness",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "topicType": "OFFER",
        "offer": {
          "offerType": "OFFER",
          "redeemOnlineUrl": "https://mybusiness.com/redeem",
          "couponCode": "SAVE20",
          "termsConditions": "Valid Fri–Sun only. One per customer."
        },
        "callToAction": {
          "type": "SHOP",
          "url": "https://mybusiness.com/services"
        }
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Language Code Example

By default, post language is auto-detected from text. If auto-detection may be inaccurate (very short posts, mixed-language content, transliterated text), set `languageCode` explicitly.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Diese Woche: 20% Rabatt auf alle Services.',
  mediaItems: [
    { type: 'image', url: 'https://example.com/promo.jpg' }
  ],
  platforms: [{
    platform: 'googlebusiness',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      languageCode: 'de'
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Diese Woche: 20% Rabatt auf alle Services.",
    media_items=[
        {"type": "image", "url": "https://example.com/promo.jpg"}
    ],
    platforms=[{
        "platform": "googlebusiness",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "languageCode": "de"
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Diese Woche: 20% Rabatt auf alle Services.",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/promo.jpg"}
    ],
    "platforms": [{
      "platform": "googlebusiness",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "languageCode": "de"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

---

# Inbox

Reviews and Q&A in the inbox

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Inbox

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

Google Business supports reviews management with real-time notifications.

### Reviews

| Feature | Supported |
|---------|-----------|
| List reviews | ✅ |
| Reply to reviews | ✅ |
| Delete reply | ✅ |
| Real-time webhooks | ✅ (`review.new`, `review.updated`) |

### Limitations

- **No DMs** - Google Business does not have a messaging system accessible via API
- **No comments** - Posts on Google Business do not support comments

See [Reviews API Reference](/reviews/list-inbox-reviews) for endpoint details.

### Batch get reviews (multiple locations)

Use `POST /v1/accounts/{accountId}/gmb-reviews/batch` to fetch reviews across multiple locations in a single request. Reviews are grouped by location in the response.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-reviews/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locationNames": [
      "accounts/123/locations/456",
      "accounts/123/locations/789"
    ],
    "pageSize": 50
  }'
```
</Tab>
<Tab value="JavaScript">
```javascript
const { data } = await zernio.accounts.batchGetGoogleBusinessReviews('YOUR_ACCOUNT_ID', {
  locationNames: [
    'accounts/123/locations/456',
    'accounts/123/locations/789'
  ],
  pageSize: 50
});

data.locationReviews.forEach(lr => {
  console.log(lr.locationName, lr.totalReviewCount, lr.averageRating);
});
```
</Tab>
<Tab value="Python">
```python
data = client.accounts.batch_get_google_business_reviews("YOUR_ACCOUNT_ID",
    location_names=[
        "accounts/123/locations/456",
        "accounts/123/locations/789"
    ],
    page_size=50
)

for lr in data["locationReviews"]:
    print(lr["locationName"], lr.get("totalReviewCount"), lr.get("averageRating"))
```
</Tab>
</Tabs>

---

# Google Business

Schedule and automate Google Business Profile posts with Zernio API

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Cards, Card } from 'fumadocs-ui/components/card';
import { PlatformCapabilities } from '@/components/platform-capabilities';

## Quick Reference

<PlatformCapabilities rows={[
  { property: 'Character limit', value: '1,500' },
  { property: 'Images per post', value: '1' },
  { property: 'Videos per post', value: 'Not supported' },
  { property: 'Image formats', value: 'JPEG, PNG only (WebP auto-converted)' },
  { property: 'Image max size', value: '5 MB' },
  { property: 'Image min dimensions', value: '400 x 300 px' },
  { property: 'Post types', value: 'Text, Text+Image, Text+CTA, Event, Offer' },
  { property: 'Scheduling', value: 'Yes' },
  { property: 'Inbox (Reviews)', value: 'Yes' },
  { property: 'Inbox (DMs/Comments)', value: 'No' },
  { property: 'Analytics', value: 'Location-level only (per-post deprecated by Google)' },
]} />

## Before You Start

<Callout type="info">
Google Business Profile is **not social media** -- it's local SEO. Posts appear on Google Search, Google Maps, and Google Knowledge Panel. They contribute to local search ranking. Posts are visible for about 7 days before being archived. Post weekly minimum.

- Requires a **verified** Google Business Profile
- Posts appear in Google Search + Maps (not a social feed)
- Videos are **not supported**
- No text-only posts via API (media or CTA recommended for visibility)
</Callout>

## Related Endpoints

- [Connect Google Business Account](/guides/connecting-accounts) - OAuth flow
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Image uploads
- [GMB Reviews](/google-business/get-google-business-reviews) - Manage reviews
- [GMB Food Menus](/google-business/get-google-business-food-menus) - Manage food menus
- [GMB Location Details](/google-business/get-google-business-location-details) - Hours, description, contact info
- [GMB Verification](/google-business/get-google-business-verifications) - Check status, start and complete verification
- [GMB Media](/google-business/list-google-business-media) - Photos management
- [GMB Attributes](/google-business/get-google-business-attributes) - Amenities and services
- [GMB Services](/google-business/get-google-business-services) - List and replace services
- [GMB Place Actions](/google-business/list-google-business-place-actions) - Booking and ordering links
- [Performance Metrics](/analytics/get-google-business-performance) - Daily impressions, clicks, calls, directions, bookings
- [Search Keywords](/analytics/get-google-business-search-keywords) - Keywords that triggered impressions
- [Reviews](/reviews/list-inbox-reviews)

## In This Section

<Cards>
  <Card title="Posts & Content Types" href="/platforms/google-business/posts" description="Create updates, offers, CTAs, and other Google Business post types" />
  <Card title="Event & Offer Posts" href="/platforms/google-business/events-offers" description="Create event and offer posts via topicType" />
  <Card title="Multi-Location Posting" href="/platforms/google-business/multi-location" description="Post to many business locations at once" />
  <Card title="Business Profile Management" href="/platforms/google-business/business-profile" description="Manage location details, attributes, services, menus, media, reviews, and verifications" />
  <Card title="Analytics" href="/platforms/google-business/analytics" description="Google Business performance and search keyword analytics" />
  <Card title="Inbox" href="/platforms/google-business/inbox" description="Reviews and Q&A in the inbox" />
  <Card title="Media & Limits" href="/platforms/google-business/reference" description="Media requirements, platform-specific fields, and common errors" />
</Cards>

---

# Multi-Location Posting

Post to many business locations at once

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Multi-Location Posting

If your connected Google Business account manages multiple locations, you can post to different locations from the same account connection.

### List Available Locations

First, retrieve the list of locations you can post to:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const locations = await zernio.connect.getGmbLocations('YOUR_ACCOUNT_ID');
console.log('Available locations:', locations);
```
</Tab>
<Tab value="Python">
```python
locations = client.connect.get_gmb_locations("YOUR_ACCOUNT_ID")
print("Available locations:", locations)
```
</Tab>
<Tab value="curl">
```bash
curl -X GET https://zernio.com/api/v1/accounts/YOUR_ACCOUNT_ID/gmb-locations \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

### Post to Multiple Locations

Use the same `accountId` multiple times with different `locationId` values:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Now open at all locations! Visit us today.',
  mediaItems: [
    { type: 'image', url: 'https://example.com/store.jpg' }
  ],
  platforms: [
    {
      platform: 'googlebusiness',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: { locationId: 'locations/111111111' }
    },
    {
      platform: 'googlebusiness',
      accountId: 'YOUR_ACCOUNT_ID',
      platformSpecificData: { locationId: 'locations/222222222' }
    }
  ],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Now open at all locations! Visit us today.",
    media_items=[
        {"type": "image", "url": "https://example.com/store.jpg"}
    ],
    platforms=[
        {
            "platform": "googlebusiness",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {"locationId": "locations/111111111"}
        },
        {
            "platform": "googlebusiness",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {"locationId": "locations/222222222"}
        }
    ],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Now open at all locations! Visit us today.",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/store.jpg"}
    ],
    "platforms": [
      {
        "platform": "googlebusiness",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "locationId": "locations/111111111"
        }
      },
      {
        "platform": "googlebusiness",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
          "locationId": "locations/222222222"
        }
      }
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

The `locationId` format is `locations/` followed by the location ID number.

---

# Posts & Content Types

Create updates, offers, CTAs, and other Google Business post types

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Start

Create a Google Business Profile post with an image:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'We are open this holiday weekend! Stop by for our special seasonal menu.',
  mediaItems: [
    { type: 'image', url: 'https://example.com/holiday-special.jpg' }
  ],
  platforms: [
    { platform: 'googlebusiness', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Posted to Google Business!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="We are open this holiday weekend! Stop by for our special seasonal menu.",
    media_items=[
        {"type": "image", "url": "https://example.com/holiday-special.jpg"}
    ],
    platforms=[
        {"platform": "googlebusiness", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Posted to Google Business! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "We are open this holiday weekend! Stop by for our special seasonal menu.",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/holiday-special.jpg"}
    ],
    "platforms": [
      {"platform": "googlebusiness", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

### Text + Image Post

The most common and recommended post type. A single image with text. No `contentType` field is needed -- this is the default when media is included.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Fresh seasonal menu available now! Visit us to try our new dishes.',
  mediaItems: [
    { type: 'image', url: 'https://example.com/seasonal-menu.jpg' }
  ],
  platforms: [
    { platform: 'googlebusiness', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Fresh seasonal menu available now! Visit us to try our new dishes.",
    media_items=[
        {"type": "image", "url": "https://example.com/seasonal-menu.jpg"}
    ],
    platforms=[
        {"platform": "googlebusiness", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Fresh seasonal menu available now! Visit us to try our new dishes.",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/seasonal-menu.jpg"}
    ],
    "platforms": [
      {"platform": "googlebusiness", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Text-Only Post

Text-only posts are supported but have lower visibility on Google Search and Maps. Adding an image or CTA is recommended.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Happy Friday! We are offering 20% off all services this weekend. Mention this post when you visit!',
  platforms: [
    { platform: 'googlebusiness', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Happy Friday! We are offering 20% off all services this weekend. Mention this post when you visit!",
    platforms=[
        {"platform": "googlebusiness", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Happy Friday! We are offering 20% off all services this weekend. Mention this post when you visit!",
    "platforms": [
      {"platform": "googlebusiness", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Post with CTA Button

Add a call-to-action button to drive traffic. The CTA appears as a prominent button below the post content.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Book your appointment today! Limited spots available this week.',
  mediaItems: [
    { type: 'image', url: 'https://example.com/booking.jpg' }
  ],
  platforms: [{
    platform: 'googlebusiness',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      callToAction: {
        type: 'BOOK',
        url: 'https://mybusiness.com/book'
      }
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Book your appointment today! Limited spots available this week.",
    media_items=[
        {"type": "image", "url": "https://example.com/booking.jpg"}
    ],
    platforms=[{
        "platform": "googlebusiness",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "callToAction": {
                "type": "BOOK",
                "url": "https://mybusiness.com/book"
            }
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Book your appointment today! Limited spots available this week.",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/booking.jpg"}
    ],
    "platforms": [{
      "platform": "googlebusiness",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "callToAction": {
          "type": "BOOK",
          "url": "https://mybusiness.com/book"
        }
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

**Available CTA Types:**

| Type | Description | Best For |
|------|-------------|----------|
| `LEARN_MORE` | Link to more information | Articles, about pages |
| `BOOK` | Booking/reservation link | Services, appointments |
| `ORDER` | Online ordering link | Restaurants, food |
| `SHOP` | E-commerce link | Retail, products |
| `SIGN_UP` | Registration link | Events, newsletters |
| `CALL` | Phone call action | Contact, inquiries |

### Event Post

Promote an event with a title, date range, and optional CTA. Events appear prominently on your Google listing with the event title and schedule.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Join us for our Grand Opening Weekend! Free samples and live music.',
  mediaItems: [
    { type: 'image', url: 'https://example.com/grand-opening.jpg' }
  ],
  platforms: [{
    platform: 'googlebusiness',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      topicType: 'EVENT',
      event: {
        title: 'Grand Opening Weekend',
        schedule: {
          startDate: { year: 2026, month: 5, day: 15 },
          startTime: { hours: 9, minutes: 0 },
          endDate: { year: 2026, month: 5, day: 16 },
          endTime: { hours: 17, minutes: 0 }
        }
      },
      callToAction: {
        type: 'LEARN_MORE',
        url: 'https://mybusiness.com/grand-opening'
      }
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Join us for our Grand Opening Weekend! Free samples and live music.",
    media_items=[
        {"type": "image", "url": "https://example.com/grand-opening.jpg"}
    ],
    platforms=[{
        "platform": "googlebusiness",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "topicType": "EVENT",
            "event": {
                "title": "Grand Opening Weekend",
                "schedule": {
                    "startDate": {"year": 2026, "month": 5, "day": 15},
                    "startTime": {"hours": 9, "minutes": 0},
                    "endDate": {"year": 2026, "month": 5, "day": 16},
                    "endTime": {"hours": 17, "minutes": 0}
                }
            },
            "callToAction": {
                "type": "LEARN_MORE",
                "url": "https://mybusiness.com/grand-opening"
            }
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Join us for our Grand Opening Weekend! Free samples and live music.",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/grand-opening.jpg"}
    ],
    "platforms": [{
      "platform": "googlebusiness",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "topicType": "EVENT",
        "event": {
          "title": "Grand Opening Weekend",
          "schedule": {
            "startDate": {"year": 2026, "month": 5, "day": 15},
            "startTime": {"hours": 9, "minutes": 0},
            "endDate": {"year": 2026, "month": 5, "day": 16},
            "endTime": {"hours": 17, "minutes": 0}
          }
        },
        "callToAction": {
          "type": "LEARN_MORE",
          "url": "https://mybusiness.com/grand-opening"
        }
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

Schedule dates also accept ISO 8601 strings, which are converted automatically:

```json
{
  "topicType": "EVENT",
  "event": {
    "title": "Grand Opening Weekend",
    "schedule": {
      "startDate": "2026-05-15T00:00:00Z",
      "startTime": "2026-05-15T09:00:00Z",
      "endDate": "2026-05-16T00:00:00Z",
      "endTime": "2026-05-16T17:00:00Z"
    }
  }
}
```

### Offer Post

Promote a deal with coupon codes, redemption URLs, and terms. Offer posts include an event object that sets the offer period and title displayed on Google.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Holiday sale! 20% off everything through the end of December.',
  mediaItems: [
    { type: 'image', url: 'https://example.com/holiday-sale.jpg' }
  ],
  platforms: [{
    platform: 'googlebusiness',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      topicType: 'OFFER',
      event: {
        title: 'Holiday Sale - 20% Off',
        schedule: {
          startDate: { year: 2026, month: 12, day: 1 },
          endDate: { year: 2026, month: 12, day: 31 }
        }
      },
      offer: {
        couponCode: 'HOLIDAY20',
        redeemOnlineUrl: 'https://mybusiness.com/shop',
        termsConditions: 'Valid in-store and online. Cannot be combined with other offers.'
      }
    }
  }],
  publishNow: true
});
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Holiday sale! 20% off everything through the end of December.",
    media_items=[
        {"type": "image", "url": "https://example.com/holiday-sale.jpg"}
    ],
    platforms=[{
        "platform": "googlebusiness",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "topicType": "OFFER",
            "event": {
                "title": "Holiday Sale - 20% Off",
                "schedule": {
                    "startDate": {"year": 2026, "month": 12, "day": 1},
                    "endDate": {"year": 2026, "month": 12, "day": 31}
                }
            },
            "offer": {
                "couponCode": "HOLIDAY20",
                "redeemOnlineUrl": "https://mybusiness.com/shop",
                "termsConditions": "Valid in-store and online. Cannot be combined with other offers."
            }
        }
    }],
    publish_now=True
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Holiday sale! 20% off everything through the end of December.",
    "mediaItems": [
      {"type": "image", "url": "https://example.com/holiday-sale.jpg"}
    ],
    "platforms": [{
      "platform": "googlebusiness",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "topicType": "OFFER",
        "event": {
          "title": "Holiday Sale - 20% Off",
          "schedule": {
            "startDate": {"year": 2026, "month": 12, "day": 1},
            "endDate": {"year": 2026, "month": 12, "day": 31}
          }
        },
        "offer": {
          "couponCode": "HOLIDAY20",
          "redeemOnlineUrl": "https://mybusiness.com/shop",
          "termsConditions": "Valid in-store and online. Cannot be combined with other offers."
        }
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

**Offer fields** (all optional, but at least one recommended):

| Field | Type | Description |
|-------|------|-------------|
| `couponCode` | string | Promo code customers can use |
| `redeemOnlineUrl` | string (URI) | URL where the offer can be redeemed |
| `termsConditions` | string | Terms and conditions text |

---

# Media & Limits

Media requirements, platform-specific fields, and common errors

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Media Requirements

| Property | Requirement |
|----------|-------------|
| **Max images** | 1 per post |
| **Formats** | JPEG, PNG (WebP auto-converted) |
| **Max file size** | 5 MB |
| **Min dimensions** | 400 x 300 px |
| **Recommended** | 1200 x 900 px (4:3) |

Google may crop images. Use 4:3 aspect ratio for best results.

## Platform-Specific Fields

All fields are set inside `platformSpecificData` on the platform entry.

| Field | Type | Description |
|-------|------|-------------|
| `topicType` | `"STANDARD"` \| `"EVENT"` \| `"OFFER"` | Post type. Defaults to `STANDARD`. `EVENT` requires the `event` object. `OFFER` requires `offer` and optionally `event` for the offer period. |
| `event` | object | Event details. Required for `EVENT`, optional for `OFFER` (sets offer period). Contains `title` (string) and `schedule` with `startDate`, `startTime`, `endDate`, `endTime`. Dates accept `{ year, month, day }` objects or ISO 8601 strings. |
| `offer` | object | Offer details for `OFFER` posts. Fields: `couponCode`, `redeemOnlineUrl`, `termsConditions` (all optional). |
| `locationId` | string | For multi-location businesses. Format: `locations/111111111`. Get locations via `GET /v1/accounts/{accountId}/gmb-locations`. If omitted, posts to default location. |
| `languageCode` | string | BCP 47 language code (e.g., `en`, `de`). Sets metadata only -- does not translate content. |
| `topicType` | `STANDARD` \| `EVENT` \| `OFFER` \| `ALERT` | Post type. `STANDARD` is a regular update. `EVENT` requires `event`. `OFFER` requires `offer`. Defaults to `STANDARD` if omitted. |
| `callToAction` | `{ type, url }` | CTA button. `type`: `LEARN_MORE`, `BOOK`, `ORDER`, `SHOP`, `SIGN_UP`, `CALL`. `url`: valid HTTPS URL. |
| `event` | object | Event details. Required when `topicType` is `EVENT`. Event schedule accepts both ISO 8601 strings (e.g. `2026-04-15T09:00:00Z`) and Google's native `{ year, month, day }` objects. |
| `offer` | object | Offer details. Required when `topicType` is `OFFER`. |

## Media URL Requirements

| Requirement | Details |
|-------------|---------|
| **Public URL** | Must be publicly accessible |
| **HTTPS** | Secure URLs only |
| **No redirects** | Direct link to image |
| **No auth required** | Cannot require login |

```
https://mybucket.s3.amazonaws.com/image.jpg       (valid)
https://example.com/images/post.png                (valid)
https://example.com/image?token=abc                (invalid - auth required)
http://example.com/image.jpg                       (invalid - not HTTPS)
```

## What You Can't Do

These features are not available through Google Business Profile's API:

- Post videos
- Respond to Q&A (deprecated by Google, replaced by AI-powered "Ask Maps")
- Manage service areas
- Manage business categories

## Common Errors

Google Business has a **6.5% failure rate** across Zernio's platform (557 failures out of 8,529 attempts). Here are the most frequent errors and how to fix them:

| Error | Meaning | Fix |
|-------|---------|-----|
| "Image not found" | Image URL is inaccessible or requires authentication | Verify URL is publicly accessible. Ensure HTTPS. Test URL in an incognito browser. |
| "Invalid image format" | Unsupported file format or corrupted file | Use JPEG or PNG only. GIF is not supported. Re-export the image if corrupted. |
| "Image too small" | Image dimensions below minimum | Use at least 400 x 300 px. Recommended: 1200 x 900 px. |
| Post not appearing | Post may be pending review or account not verified | Posts may take 24-48 hours to appear. Check Google Business Console for approval status. Ensure account is verified. |
| CTA not working | Invalid or inaccessible URL | Verify URL is valid and accessible. Use HTTPS. Avoid shortened URLs. |

---

# Ad Comments

Read and manage comments on your Meta ads

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Ad Comments

Comments on ad creatives (including dark posts, ads created directly in Meta Ads Manager that never went live organically on the Page feed) aren't reachable through the standard [`GET /v1/inbox/comments/{postId}`](/comments/list-inbox-comments) endpoint, because dark posts don't live in Zernio's post database and Meta's public media-level Graph API endpoints don't resolve them.

Use [`GET /v1/ads/{adId}/comments`](/ads/get-ad-comments) instead. It resolves the creative's underlying story via the Marketing API (`effective_object_story_id` on Facebook, `effective_instagram_media_id` on Instagram), then fetches the comments from the Graph API. The response matches the inbox endpoint shape so you can reuse the same rendering logic.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { comments, meta } = await zernio.ads.getAdComments({
  path: { adId: 'AD_ID' },
  query: { limit: 50 },
});

console.log(meta.platform);         // 'facebook' | 'instagram'
console.log(meta.effectiveStoryId); // underlying post ID

for (const c of comments) {
  console.log(c.from.name, c.message);
}
```
</Tab>
<Tab value="Python">
```python
res = client.ads.get_ad_comments(
    ad_id="AD_ID",
    limit=50,
)
for c in res["comments"]:
    print(c["from"]["name"], c["message"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://api.zernio.com/v1/ads/AD_ID/comments?limit=50" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

Returns `ad_not_commentable` when the creative format does not expose an underlying commentable post (Story ads, Dynamic Product Ads). Returns `feature_not_available` for non-Meta ad platforms.

---

# Custom Audiences

Build custom and lookalike audiences

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Custom Audiences

Create a Lookalike Audience:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const audience = await zernio.adaudiences.createAdAudience({
  body: {
    accountId: 'acc_metaads_123',
    adAccountId: 'act_1234567890',
    type: 'lookalike',
    name: 'LAL 1% of US customers',
    sourceAudienceId: '6123456789',
    country: 'US',
    ratio: 0.01,
  },
});
```
</Tab>
<Tab value="Python">
```python
audience = client.ad_audiences.create_ad_audience(
    account_id="acc_metaads_123",
    ad_account_id="act_1234567890",
    type="lookalike",
    name="LAL 1% of US customers",
    source_audience_id="6123456789",
    country="US",
    ratio=0.01,
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/audiences" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_metaads_123",
    "adAccountId": "act_1234567890",
    "type": "lookalike",
    "name": "LAL 1% of US customers",
    "sourceAudienceId": "6123456789",
    "country": "US",
    "ratio": 0.01
  }'
```
</Tab>
</Tabs>

Add users to a customer list (SHA-256 hashed automatically):

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
await zernio.adaudiences.addUsersToAdAudience({
  path: { audienceId: 'AUDIENCE_ID' },
  body: {
    users: [
      { email: 'user@example.com' },
      { phone: '+14155551234' },
    ],
  },
});
```
</Tab>
<Tab value="Python">
```python
client.ad_audiences.add_users_to_ad_audience(
    audience_id="AUDIENCE_ID",
    users=[
        {"email": "user@example.com"},
        {"phone": "+14155551234"},
    ],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/audiences/AUDIENCE_ID/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      { "email": "user@example.com" },
      { "phone": "+14155551234" }
    ]
  }'
```
</Tab>
</Tabs>

---

# Boost a Post

Turn an existing organic post into a paid ad

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Boost a Post

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.boostPost({ body: {
  postId: 'POST_ID',
  accountId: 'ACCOUNT_ID',
  adAccountId: 'act_1234567890',
  name: 'Spring launch boost',
  goal: 'traffic',
  budget: { amount: 40, type: 'daily' },
  schedule: { startDate: '2026-04-20', endDate: '2026-04-27' },
  targeting: {
    ageMin: 25,
    ageMax: 45,
    countries: ['US', 'CA'],
    interests: [{ id: '6003139266461', name: 'DevOps' }]
  }
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.boost_post(
    post_id="POST_ID",
    account_id="ACCOUNT_ID",
    ad_account_id="act_1234567890",
    name="Spring launch boost",
    goal="traffic",
    budget={"amount": 40, "type": "daily"},
    schedule={"startDate": "2026-04-20", "endDate": "2026-04-27"},
    targeting={"ageMin": 25, "ageMax": 45, "countries": ["US", "CA"]},
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/boost" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postId": "POST_ID",
    "accountId": "ACCOUNT_ID",
    "adAccountId": "act_1234567890",
    "name": "Spring launch boost",
    "goal": "traffic",
    "budget": { "amount": 40, "type": "daily" },
    "schedule": { "startDate": "2026-04-20", "endDate": "2026-04-27" },
    "targeting": {
      "ageMin": 25,
      "ageMax": 45,
      "countries": ["US", "CA"]
    }
  }'
```
</Tab>
</Tabs>

---

# Campaigns & Ad Sets

Create standalone campaigns and manage campaigns, ad sets, and budgets

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Create a Standalone Campaign

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const ad = await zernio.ads.createStandaloneAd({ body: {
  accountId: 'acc_metaads_123',
  adAccountId: 'act_1234567890',
  name: 'Spring sale - US Feed',
  goal: 'traffic',
  budgetAmount: 75,
  budgetType: 'daily',
  headline: 'Spring Sale - 30% off',
  body: 'Limited time. Upgrade today.',
  imageUrl: 'https://cdn.example.com/spring.jpg',
  callToAction: 'SHOP_NOW',
  linkUrl: 'https://example.com/spring',
  countries: ['US'],
  ageMin: 25,
  ageMax: 55,
}});
```
</Tab>
<Tab value="Python">
```python
ad = client.ads.create_standalone_ad(
    account_id="acc_metaads_123",
    ad_account_id="act_1234567890",
    name="Spring sale - US Feed",
    goal="traffic",
    budget_amount=75,
    budget_type="daily",
    headline="Spring Sale - 30% off",
    body="Limited time. Upgrade today.",
    image_url="https://cdn.example.com/spring.jpg",
    call_to_action="SHOP_NOW",
    link_url="https://example.com/spring",
    countries=["US"],
    age_min=25,
    age_max=55,
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_metaads_123",
    "adAccountId": "act_1234567890",
    "name": "Spring sale - US Feed",
    "goal": "traffic",
    "budgetAmount": 75,
    "budgetType": "daily",
    "headline": "Spring Sale - 30% off",
    "body": "Limited time. Upgrade today.",
    "imageUrl": "https://cdn.example.com/spring.jpg",
    "callToAction": "SHOP_NOW",
    "linkUrl": "https://example.com/spring",
    "countries": ["US"],
    "ageMin": 25,
    "ageMax": 55,
    "interests": [{ "id": "6003139266461", "name": "DevOps" }]
  }'
```
</Tab>
</Tabs>

<Callout type="info">
For `goal: "conversions"`, `"lead_conversion"`, `"lead_generation"`, `"app_promotion"`, or `"catalog_sales"`, see [Conversion campaigns and promoted objects](/platforms/meta-ads/conversion-campaigns#conversion-campaigns-and-promoted-objects) below — Meta requires a `promotedObject` (Pixel + event, Page, or App) on the ad set for those optimization goals.
</Callout>

<Callout type="info">
**`/v1/ads/create` uses a flat body** (every field at the top level). The `/v1/ads/boost` endpoint is different, it uses nested `budget`, `schedule`, and `targeting` objects. Don't mix the two shapes. Platform is inferred from `accountId`, so no `platform` field in the body.
</Callout>

## Manage Campaigns & Ad Sets

Zernio exposes the full Meta campaign tree with CBO/ABO awareness, review-state,
and budget-level routing, enough to build a Meta Ads Manager replacement
on top of `GET /v1/ads/tree` and the write endpoints below.

### Bid strategy

Meta's full bid-strategy enum is supported on writes (`POST /v1/ads/create`, `POST /v1/ads/boost`, `PUT /v1/ads/ad-sets/{adSetId}`, `PUT /v1/ads/campaigns/{campaignId}`) and surfaced on reads (`GET /v1/ads/tree`, `/v1/ads/campaigns`, `/v1/ads/{adId}`).

| `bidStrategy` | Required companion field | Notes |
|---|---|---|
| `LOWEST_COST_WITHOUT_CAP` (default) | — | Auto-bid; Meta optimizes to spend the budget. |
| `LOWEST_COST_WITH_BID_CAP` | `bidAmount` (whole currency units) | Auto-bid with a hard ceiling. |
| `COST_CAP` | `bidAmount` (whole currency units) | Target average cost per result. |
| `LOWEST_COST_WITH_MIN_ROAS` | `roasAverageFloor` (decimal multiplier, e.g. `2.0` = 2.0× ROAS) | Requires a value-optimized campaign (e.g. `OUTCOME_SALES` with a connected pixel/dataset). |

`bidAmount` is whole currency units of the ad account (USD: `5` = $5.00; JPY: `100` = ¥100). Internally converted to Meta's smallest-denomination integer (cents for USD).

`roasAverageFloor` is a decimal multiplier; we encode it as Meta's `bid_constraints.roas_average_floor` × 10000 (so `2.0` → `20000`).

Create an ad with a $5 cost cap:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.ads.createStandaloneAd({
  body: {
    accountId: 'ACCOUNT_ID',
    adAccountId: 'act_123',
    name: 'Spring sale',
    goal: 'conversions',
    budgetAmount: 50,
    budgetType: 'daily',
    headline: 'Spring sale',
    body: '20% off everything',
    callToAction: 'SHOP_NOW',
    linkUrl: 'https://example.com',
    imageUrl: 'https://cdn.example.com/banner.jpg',
    bidStrategy: 'COST_CAP',
    bidAmount: 5,
    promotedObject: { pixelId: '1729525464415281', customEventType: 'PURCHASE' },
  },
});
```
</Tab>
<Tab value="Python">
```python
result = client.ads.create_standalone_ad(
    account_id="ACCOUNT_ID",
    ad_account_id="act_123",
    name="Spring sale",
    goal="conversions",
    budget_amount=50,
    budget_type="daily",
    headline="Spring sale",
    body="20% off everything",
    call_to_action="SHOP_NOW",
    link_url="https://example.com",
    image_url="https://cdn.example.com/banner.jpg",
    bid_strategy="COST_CAP",
    bid_amount=5,
    promoted_object={"pixelId": "1729525464415281", "customEventType": "PURCHASE"},
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "ACCOUNT_ID",
    "adAccountId": "act_123",
    "name": "Spring sale",
    "goal": "conversions",
    "budgetAmount": 50,
    "budgetType": "daily",
    "headline": "Spring sale",
    "body": "20% off everything",
    "callToAction": "SHOP_NOW",
    "linkUrl": "https://example.com",
    "imageUrl": "https://cdn.example.com/banner.jpg",
    "bidStrategy": "COST_CAP",
    "bidAmount": 5,
    "promotedObject": { "pixelId": "1729525464415281", "customEventType": "PURCHASE" }
  }'
```
</Tab>
</Tabs>

Switch an ad set to ROAS-floor bidding:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
await zernio.adcampaigns.updateAdSet({
  path: { adSetId: 'AD_SET_ID' },
  body: {
    platform: 'facebook',
    bidStrategy: 'LOWEST_COST_WITH_MIN_ROAS',
    roasAverageFloor: 2.5,
  },
});
```
</Tab>
<Tab value="Python">
```python
client.ad_campaigns.update_ad_set(
    ad_set_id="AD_SET_ID",
    platform="facebook",
    bid_strategy="LOWEST_COST_WITH_MIN_ROAS",
    roas_average_floor=2.5,
)
```
</Tab>
<Tab value="curl">
```bash
curl -X PUT "https://zernio.com/api/v1/ads/ad-sets/AD_SET_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "facebook",
    "bidStrategy": "LOWEST_COST_WITH_MIN_ROAS",
    "roasAverageFloor": 2.5
  }'
```
</Tab>
</Tabs>

Campaign-level `PUT /v1/ads/campaigns/{campaignId}` accepts `bidStrategy` only — Meta's spec has no `bid_amount` or `bid_constraints` at the campaign level (those live on the ad set). Campaign-level bid edits also require the campaign to be CBO (campaign-level budget); ABO campaigns return 409 with a pointer to the ad-set endpoint.

### ROAS + revenue-per-event

Every `metrics` object on `/v1/ads/tree`, `/v1/ads/campaigns`, and `/v1/ads/{adId}` now carries three Meta-specific monetary fields alongside the existing `actions` + `conversions` counts:

| Field | Type | Notes |
|-------|------|-------|
| `actionValues` | `{[action_type]: number}` | Monetary mirror of `actions`, from Meta's `action_values[]`. Values in ad-account native currency (see the campaign's `currency` field). Populated for the same action types Meta reports values on (purchases, AddToCart with value, etc.). |
| `purchaseValue` | `number` | Convenience sum of purchase-type action values, picked from `actionValues` via the same priority list as `conversions` (`offsite_conversion.fb_pixel_purchase` → `omni_purchase` → `purchase`). Same unit as `spend`. |
| `roas` | `number` | Derived `purchaseValue / spend`. Recomputed from summed numerator + denominator at ad-set and campaign levels (not averaged across children) so the rollup is mathematically correct. Equivalent to Meta's `purchase_roas` under default attribution. |

Example campaign rollup for a purchase campaign:
```json
"metrics": {
  "spend": 493.39,
  "purchaseValue": 2456.78,
  "roas": 4.98,
  "conversions": 42,
  "costPerConversion": 11.75,
  "actions": { "offsite_conversion.fb_pixel_purchase": 42, "add_to_cart": 138, "link_click": 1205 },
  "actionValues": { "offsite_conversion.fb_pixel_purchase": 2456.78, "add_to_cart": 4230.50 }
}
```

For cost-per-AddToCart, cost-per-Lead, etc., read the relevant `actions[key]` divided by `spend`. Pick `offsite_conversion.fb_pixel_*` keys in `actions` / `actionValues` when available to avoid Meta's parallel pixel+omni+canonical reporting (same conversion counted under multiple keys).

### Reading the campaign tree

`GET /v1/ads/tree` returns nested Campaign → Ad Set → Ad with rolled-up metrics
(including `conversions` and raw `actions` counts). Each campaign node exposes:

| Field | Type | Notes |
|-------|------|-------|
| `status` | `active \| paused \| pending_review \| …` | Delivery status derived from child ads |
| `reviewStatus` | `in_review \| approved \| rejected \| with_issues \| null` | Platform-side review, **distinct from `status`** |
| `platformCampaignStatus` | string | Raw Meta `Campaign.effective_status` |
| `campaignIssuesInfo` | object[] \| null | Meta's raw `issues_info[]` when delivery issues exist |
| `budgetLevel` | `campaign \| adset \| null` | Canonical CBO/ABO switch |
| `campaignBudget` | `{ amount, type } \| null` | Populated only for CBO |
| `adSetBudget` (on ad-set nodes) | `{ amount, type } \| null` | Populated only for ABO |
| `isBudgetScheduleEnabled` | boolean | Mirrors Meta `Campaign.is_budget_schedule_enabled` |
| `currency` | string | ISO 4217 code, budgets are in ad-account native currency, NOT normalized |

Default `?source=all` (matches the Zernio UI) returns both Zernio-created and
platform-discovered ads. Pass `?source=zernio` to restrict.

### Update a CBO campaign budget

Use `PUT /v1/ads/campaigns/{campaignId}` when `budgetLevel === 'campaign'`.
If you call this on an ABO campaign, Zernio returns `409` with
`code: "BUDGET_LEVEL_MISMATCH"`, route to the ad-set endpoint instead.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
await zernio.adcampaigns.updateAdCampaign({
  path: { campaignId: 'CAMPAIGN_ID' },
  body: {
    platform: 'facebook',
    budget: { amount: 250, type: 'daily' },
  },
});
```
</Tab>
<Tab value="Python">
```python
client.ad_campaigns.update_ad_campaign(
    campaign_id="CAMPAIGN_ID",
    platform="facebook",
    budget={"amount": 250, "type": "daily"},
)
```
</Tab>
<Tab value="curl">
```bash
curl -X PUT "https://zernio.com/api/v1/ads/campaigns/CAMPAIGN_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "facebook",
    "budget": { "amount": 250, "type": "daily" }
  }'
```
</Tab>
</Tabs>

### Update an ABO ad-set (budget and/or status)

`PUT /v1/ads/ad-sets/{adSetId}` when `budgetLevel === 'adset'`. Supply
`budget` and/or `status`, at least one is required. Returns `409` with
`code: "BUDGET_LEVEL_MISMATCH"` if the parent campaign is CBO.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
await zernio.adcampaigns.updateAdSet({
  path: { adSetId: 'ADSET_ID' },
  body: {
    platform: 'facebook',
    budget: { amount: 75, type: 'daily' },
    status: 'active',
  },
});
```
</Tab>
<Tab value="Python">
```python
client.ad_campaigns.update_ad_set(
    ad_set_id="ADSET_ID",
    platform="facebook",
    budget={"amount": 75, "type": "daily"},
    status="active",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X PUT "https://zernio.com/api/v1/ads/ad-sets/ADSET_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "facebook",
    "budget": { "amount": 75, "type": "daily" },
    "status": "active"
  }'
```
</Tab>
</Tabs>

For status-only toggles, the symmetric `PUT /v1/ads/ad-sets/{adSetId}/status`
mirrors `/v1/ads/campaigns/{campaignId}/status`.

### Pause / resume a campaign (single or bulk)

Single campaign, cascades to all ad sets and ads:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
await zernio.adcampaigns.updateAdCampaignStatus({
  path: { campaignId: 'CAMPAIGN_ID' },
  body: { status: 'paused', platform: 'facebook' },
});
```
</Tab>
<Tab value="Python">
```python
client.ad_campaigns.update_ad_campaign_status(
    campaign_id="CAMPAIGN_ID",
    status="paused",
    platform="facebook",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X PUT "https://zernio.com/api/v1/ads/campaigns/CAMPAIGN_ID/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused", "platform": "facebook" }'
```
</Tab>
</Tabs>

Bulk (up to 50 campaigns), each row's result is reported independently so
one failure doesn't fail the whole batch:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
await zernio.adcampaigns.bulkUpdateAdCampaignStatus({
  body: {
    status: 'paused',
    campaigns: [
      { platformCampaignId: '1202...', platform: 'facebook' },
      { platformCampaignId: '1203...', platform: 'facebook' },
    ],
  },
});
```
</Tab>
<Tab value="Python">
```python
client.ad_campaigns.bulk_update_ad_campaign_status(
    status="paused",
    campaigns=[
        {"platformCampaignId": "1202...", "platform": "facebook"},
        {"platformCampaignId": "1203...", "platform": "facebook"},
    ],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/campaigns/bulk-status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused",
    "campaigns": [
      { "platformCampaignId": "1202...", "platform": "facebook" },
      { "platformCampaignId": "1203...", "platform": "facebook" }
    ]
  }'
```
</Tab>
</Tabs>

### Duplicate a campaign

`POST /v1/ads/campaigns/{campaignId}/duplicate` wraps Meta's native
`POST /{campaign-id}/copies` endpoint. Defaults to `deepCopy: true` +
`statusOption: "PAUSED"` so the copy is created with the full hierarchy but
doesn't start delivering until you activate it. Zernio triggers a sync
discovery after the copy so the new hierarchy materializes in `/ads/tree`
within seconds (set `syncAfter: false` to skip).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.adcampaigns.duplicateAdCampaign({
  path: { campaignId: 'CAMPAIGN_ID' },
  body: {
    platform: 'facebook',
    deepCopy: true,
    statusOption: 'PAUSED',
    renameStrategy: 'DEEP_RENAME',
    renameSuffix: ' (copy)',
  },
});
```
</Tab>
<Tab value="Python">
```python
result = client.ad_campaigns.duplicate_ad_campaign(
    campaign_id="CAMPAIGN_ID",
    platform="facebook",
    deep_copy=True,
    status_option="PAUSED",
    rename_strategy="DEEP_RENAME",
    rename_suffix=" (copy)",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/campaigns/CAMPAIGN_ID/duplicate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "facebook",
    "deepCopy": true,
    "statusOption": "PAUSED",
    "renameStrategy": "DEEP_RENAME",
    "renameSuffix": " (copy)"
  }'
```
</Tab>
</Tabs>

Returns `{ copiedCampaignId, discovery, raw }`. For hierarchies with > ~2
objects Meta requires async-batch mode; the synchronous path will return the
exact Meta error message so you can fall back to async in your client.

### Delete a campaign

`DELETE /v1/ads/campaigns/{campaignId}` cascades on Meta's side (removes all
ad sets + ads) and marks local Ad docs as `cancelled` in the same pass.
The route requires `platform` in the body so we know which platform's API
to call.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
await zernio.adcampaigns.deleteAdCampaign({
  path: { campaignId: 'CAMPAIGN_ID' },
  body: { platform: 'facebook' },
});
```
</Tab>
<Tab value="Python">
```python
client.ad_campaigns.delete_ad_campaign(
    campaign_id="CAMPAIGN_ID",
    platform="facebook",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X DELETE "https://zernio.com/api/v1/ads/campaigns/CAMPAIGN_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "facebook" }'
```
</Tab>
</Tabs>

---

# Conversions API

Send server-side conversion events to Meta

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Conversions API

Send offline conversion events (deal closed, lead qualified, trial converted) back to Meta via the Graph API `events` endpoint. Zernio uses the Meta Ads account you already connected, no additional OAuth, no pixel-scoped CAPI token to paste. PII is SHA-256 hashed server-side per Meta's spec before anything leaves your server.

### Discover available pixels

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.ads.listConversionDestinations({
  path: { accountId: 'ACCOUNT_ID' },
});
```
</Tab>
<Tab value="Python">
```python
data = client.ads.list_conversion_destinations(account_id="ACCOUNT_ID")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/accounts/ACCOUNT_ID/conversion-destinations" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Returns every pixel accessible to the connected ad accounts. Use the returned `id` as `destinationId` on the send call.

### Send a conversion event

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.ads.sendConversions({ body: {
  accountId: 'ACCOUNT_ID',
  destinationId: '1729525464415281', // pixel ID
  events: [{
    eventName: 'Lead',
    eventTime: Math.floor(Date.now() / 1000),
    eventId: 'order_abc_123', // dedup key, must match pixel event if dual-tracking
    value: 42.50,
    currency: 'USD',
    actionSource: 'crm',
    user: {
      email: 'customer@example.com',
      phone: '+14155551234',
      firstName: 'Jane',
      lastName: 'Doe',
      country: 'US',
    },
  }],
}});
```
</Tab>
<Tab value="Python">
```python
result = client.ads.send_conversions(
    account_id="ACCOUNT_ID",
    destination_id="1729525464415281",
    events=[{
        "eventName": "Lead",
        "eventTime": int(time.time()),
        "eventId": "order_abc_123",
        "value": 42.50,
        "currency": "USD",
        "actionSource": "crm",
        "user": {
            "email": "customer@example.com",
            "phone": "+14155551234",
            "firstName": "Jane",
            "lastName": "Doe",
            "country": "US",
        },
    }],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/conversions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "ACCOUNT_ID",
    "destinationId": "1729525464415281",
    "events": [{
      "eventName": "Lead",
      "eventTime": 1744732800,
      "eventId": "order_abc_123",
      "value": 42.50,
      "currency": "USD",
      "actionSource": "crm",
      "user": {
        "email": "customer@example.com",
        "phone": "+14155551234",
        "firstName": "Jane",
        "lastName": "Doe",
        "country": "US"
      }
    }]
  }'
```
</Tab>
</Tabs>

### Match keys

The more identifiers you send on `user`, the higher Meta's Event Match Quality. All are normalized and SHA-256 hashed server-side per Meta's spec (you send plaintext); `ipAddress`, `userAgent`, `fbc`, and `fbp` are sent unhashed per Meta's requirement. Supported keys:

- Contact: `email`, `phone`, `firstName`, `lastName`
- Location / demographic: `country`, `city`, `state`, `zip`, `dob` (YYYYMMDD), `gender` (`f` or `m`)
- Identifiers: `externalId` (your stable user/device id), `ipAddress`, `userAgent`
- Click IDs (under `user.clickIds`): `fbc` (from the `fbclid` URL param), `fbp` (the `_fbp` cookie)

The highest-signal web keys are `fbc`, `fbp`, `externalId`, `ipAddress`, and `userAgent`, send them whenever you capture them at first touch.

### Standard event names

`Purchase`, `Lead`, `CompleteRegistration`, `AddToCart`, `InitiateCheckout`, `AddPaymentInfo`, `Subscribe`, `StartTrial`, `ViewContent`, `Search`, `Contact`, `SubmitApplication`, `Schedule`. Custom event names are accepted too.

### Test mode

Pass `testCode: "TEST12345"` at the request root to route events to the Test Events tab in Meta Events Manager without affecting production pixel data.

### Deduplication

Pass a stable `eventId` on every event. Meta dedupes against your pixel within a 48-hour window when `eventId` matches. Missing or inconsistent `eventId` between pixel and CAPI double-counts conversions, the #1 cause of inflated reports.

### Batching

Up to 1,000 events per request (Zernio chunks larger batches automatically). Meta rejects the entire batch if any event is malformed, the response includes `failures[]` with per-event error detail and a `traceId` you can look up in Meta support.

### Event Match Quality

Read Event Match Quality (EMQ) and pixel-to-CAPI coverage back from Meta without opening Events Manager. Pass the pixel/dataset `destinationId` and you get, per event, the composite EMQ score (0-10), per-match-key coverage, and the event coverage rate (how well your CAPI events dedupe against the pixel).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.ads.getConversionsQuality({
  query: { accountId: 'ACCOUNT_ID', destinationId: '1729525464415281' },
});
```
</Tab>
<Tab value="Python">
```python
data = client.ads.get_conversions_quality(
    account_id="ACCOUNT_ID",
    destination_id="1729525464415281",
)
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/ads/conversions/quality?accountId=ACCOUNT_ID&destinationId=1729525464415281" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

```json
{
  "platform": "metaads",
  "rows": [
    {
      "eventName": "Purchase",
      "compositeScore": 6.2,
      "matchKeys": [{ "identifier": "email", "coveragePercentage": 80 }],
      "eventCoveragePercentage": 75
    }
  ]
}
```

Web events only (a Meta limitation, app and offline EMQ aren't exposed by the API). Uses the connected Meta Ads account, no extra permission.

---

# Catalog Ads

Advantage+ catalog ads — dynamic product and vehicle ads from a Meta product catalog

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Advantage+ catalog ads

Catalog ads (Meta's dynamic product ads / Advantage+ catalog ads) promote items from a Meta **product catalog** — e-commerce products, vehicle inventory, hotels — with creatives Meta renders per item. One ad, N items: Meta picks which product or vehicle each person sees.

Zernio supports them end-to-end with `goal: "catalog_sales"` on `POST /v1/ads/create`, plus two discovery endpoints to find the customer's catalogs and product sets. Everything works with the permissions accounts already granted on connect — no reconnect needed.

<Callout type="info">
**Catalog contents are managed in Meta Commerce Manager** (or a feed provider), not through this API. Zernio reads the catalogs and runs ads on them. The ad account also needs a Meta Pixel — a Meta requirement for catalog campaigns (see the table below).
</Callout>

## 1. Find the catalog and product set

Catalogs hang off the ad account's business. List them, then list the chosen catalog's product sets — the product set is what the ad actually promotes.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { catalogs } = await zernio.ads.listAdCatalogs({
  accountId: 'acc_metaads_123',
  adAccountId: 'act_1234567890',
});
// [{ id: '1003405825408877', name: 'Vehicle Inventory', vertical: 'vehicles', productCount: 132 }]

const { productSets } = await zernio.ads.listAdCatalogProductSets({
  catalogId: catalogs[0].id,
  accountId: 'acc_metaads_123',
});
// [{ id: '1003260032095191', name: 'All vehicles', productCount: 132 }]
```
</Tab>
<Tab value="Python">
```python
catalogs = client.ads.list_ad_catalogs(
    account_id="acc_metaads_123",
    ad_account_id="act_1234567890",
)

product_sets = client.ads.list_ad_catalog_product_sets(
    catalog_id=catalogs["catalogs"][0]["id"],
    account_id="acc_metaads_123",
)
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/ads/catalogs?accountId=acc_metaads_123&adAccountId=act_1234567890" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"

curl "https://zernio.com/api/v1/ads/catalogs/1003405825408877/product-sets?accountId=acc_metaads_123" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

## 2. Create the catalog campaign

`goal: "catalog_sales"` builds the whole chain: a Sales-objective campaign, an ad set bound to the product set, and a **catalog template creative**. There is no `imageUrl` or `video` — Meta renders the visuals from the catalog items.

The copy fields become the template, and they accept Meta's catalog template tags (`{{product.name}}`, `{{product.price}}`, or for vehicle catalogs `{{vehicle.make}}`, `{{vehicle.model}}`, `{{vehicle.year}}`, `{{vehicle.price}}`), so each rendered item carries its own data.

| Required `promotedObject` field | Why |
|---|---|
| `productSetId` | The items to promote (and the template creative's source). |
| `pixelId` | Meta requires the pixel on catalog ad sets — its "Promoted Object is Required" error actually means the pixel is missing. |
| `customEventType` | The conversion event to optimize toward, e.g. `PURCHASE`, `LEAD`, `VIEW_CONTENT`. |

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.ads.createStandaloneAd({
  body: {
    accountId: 'acc_metaads_123',
    adAccountId: 'act_1234567890',
    name: 'Vehicle inventory - catalog',
    goal: 'catalog_sales',
    budgetAmount: 30,
    budgetType: 'daily',
    headline: '{{vehicle.year}} {{vehicle.make}} {{vehicle.model}}',
    body: 'Find your next car',
    description: '{{vehicle.price}}',
    callToAction: 'LEARN_MORE',
    linkUrl: 'https://example.com/inventory',
    countries: ['CL'],
    promotedObject: {
      productSetId: '1003260032095191',
      pixelId: '1729525464415281',
      customEventType: 'PURCHASE',
    },
  },
});
```
</Tab>
<Tab value="Python">
```python
result = client.ads.create_standalone_ad(
    account_id="acc_metaads_123",
    ad_account_id="act_1234567890",
    name="Vehicle inventory - catalog",
    goal="catalog_sales",
    budget_amount=30,
    budget_type="daily",
    headline="{{vehicle.year}} {{vehicle.make}} {{vehicle.model}}",
    body="Find your next car",
    description="{{vehicle.price}}",
    call_to_action="LEARN_MORE",
    link_url="https://example.com/inventory",
    countries=["CL"],
    promoted_object={
        "productSetId": "1003260032095191",
        "pixelId": "1729525464415281",
        "customEventType": "PURCHASE",
    },
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_metaads_123",
    "adAccountId": "act_1234567890",
    "name": "Vehicle inventory - catalog",
    "goal": "catalog_sales",
    "budgetAmount": 30,
    "budgetType": "daily",
    "headline": "{{vehicle.year}} {{vehicle.make}} {{vehicle.model}}",
    "body": "Find your next car",
    "description": "{{vehicle.price}}",
    "callToAction": "LEARN_MORE",
    "linkUrl": "https://example.com/inventory",
    "countries": ["CL"],
    "promotedObject": {
      "productSetId": "1003260032095191",
      "pixelId": "1729525464415281",
      "customEventType": "PURCHASE"
    }
  }'
```
</Tab>
</Tabs>

## Behavior and limits

- **Targeting** works like any other campaign (countries, age, gender, placements, saved audiences). Broad targeting is fine — Meta matches items to people. Retargeting off pixel events can be layered with `optimizationGoal: "OFFSITE_CONVERSIONS"`.
- **Single shape only.** `catalog_sales` can't be combined with `creatives[]`, `adSetId` (attach), `dynamicCreative`, or `placementAssets` — the catalog template is already the multi-item mechanism.
- **Instagram placement** is handled for you: catalog creatives need an explicit Instagram identity, and Zernio falls back to the Page-backed Instagram account automatically when the connected Page has no linked IG.
- The default ad-set optimization is `LINK_CLICKS`; override with `optimizationGoal` (e.g. `OFFSITE_CONVERSIONS`).
- The legacy `PRODUCT_CATALOG_SALES` objective is retired by Meta on modern ad accounts; Zernio uses the current Sales-objective shape.

---

# Conversion Campaigns

Conversion campaigns and promoted objects

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Conversion campaigns and promoted objects

Optimization goals that point at a specific event/page/app need a `promotedObject` on the ad set. Without it Meta rejects the ad-set create with `error_subcode: 1815430` (*"Please select a promoted object for your ad set."*). Zernio enforces this upfront so you get a clean `400 invalid_request_error` with `param: "promotedObject"` instead of a passthrough Meta error.

| `goal` | Meta objective + optimization | Required `promotedObject` fields |
|--------|-------------------|----------------------------------|
| `conversions` | Sales → `OFFSITE_CONVERSIONS` | `pixelId` + `customEventType` (a commerce event, e.g. `PURCHASE`, `ADD_TO_CART`, `START_TRIAL`) |
| `lead_conversion` | Leads → `OFFSITE_CONVERSIONS` | `pixelId` + `customEventType` (a leads event, e.g. `LEAD`, `SUBMIT_APPLICATION`, `SCHEDULE`, `CONTACT`) |
| `app_promotion` | App promotion → `APP_INSTALLS` | `applicationId` + `objectStoreUrl` |
| `lead_generation` | Leads → `LEAD_GENERATION` (instant form) | `pageId` (auto-filled from the connected Page when omitted) |
| `catalog_sales` | Sales → catalog template creative | `productSetId` + `pixelId` + `customEventType` — see [Catalog Ads](/platforms/meta-ads/catalog-ads) |

`customEventType` accepts Meta's standard event names: `PURCHASE`, `LEAD`, `COMPLETE_REGISTRATION`, `ADD_TO_CART`, `INITIATE_CHECKOUT`, `ADD_PAYMENT_INFO`, `SUBSCRIBE`, `START_TRIAL`, `VIEW_CONTENT`, `SEARCH`, `CONTACT`, `SUBMIT_APPLICATION`, `SCHEDULE`. Custom-conversion-driven optimization is supported via `customConversionId` instead of (or alongside) `customEventType`.

<Callout type="info">
**`conversions` vs `lead_conversion`.** Meta gates which conversion events are valid by campaign objective. `conversions` runs the **Sales** objective (commerce events like `PURCHASE`); a leads event such as `LEAD` is rejected there. For **website pixel lead** optimization use `lead_conversion` (the **Leads** objective with `OFFSITE_CONVERSIONS`). `lead_generation` is also the Leads objective but optimizes for an **instant form** (`leadGenFormId`) rather than a website pixel event.
</Callout>

<Callout type="info">
**Override the ad-set optimization goal.** By default the ad-set `optimization_goal` is derived from `goal` (e.g. `traffic` → `LINK_CLICKS`). Pass `optimizationGoal` to set it explicitly, e.g. `"LANDING_PAGE_VIEWS"`, `"REACH"`, `"IMPRESSIONS"`, `"OFFSITE_CONVERSIONS"`, `"THRUPLAY"`. It's forwarded verbatim and Meta validates it against the campaign objective (incompatible combinations are rejected).
</Callout>

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.ads.createStandaloneAd({
  body: {
    accountId: 'acc_metaads_123',
    adAccountId: 'act_1234567890',
    name: 'Spring sale - Purchase optimization',
    goal: 'conversions',
    budgetAmount: 75,
    budgetType: 'daily',
    headline: 'Spring Sale - 30% off',
    body: 'Limited time. Upgrade today.',
    imageUrl: 'https://cdn.example.com/spring.jpg',
    callToAction: 'SHOP_NOW',
    linkUrl: 'https://example.com/spring',
    countries: ['US'],
    promotedObject: {
      pixelId: '1729525464415281',
      customEventType: 'PURCHASE',
    },
  },
});
```
</Tab>
<Tab value="Python">
```python
result = client.ads.create_standalone_ad(
    account_id="acc_metaads_123",
    ad_account_id="act_1234567890",
    name="Spring sale - Purchase optimization",
    goal="conversions",
    budget_amount=75,
    budget_type="daily",
    headline="Spring Sale - 30% off",
    body="Limited time. Upgrade today.",
    image_url="https://cdn.example.com/spring.jpg",
    call_to_action="SHOP_NOW",
    link_url="https://example.com/spring",
    countries=["US"],
    promoted_object={
        "pixelId": "1729525464415281",
        "customEventType": "PURCHASE",
    },
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_metaads_123",
    "adAccountId": "act_1234567890",
    "name": "Spring sale - Purchase optimization",
    "goal": "conversions",
    "budgetAmount": 75,
    "budgetType": "daily",
    "headline": "Spring Sale - 30% off",
    "body": "Limited time. Upgrade today.",
    "imageUrl": "https://cdn.example.com/spring.jpg",
    "callToAction": "SHOP_NOW",
    "linkUrl": "https://example.com/spring",
    "countries": ["US"],
    "promotedObject": {
      "pixelId": "1729525464415281",
      "customEventType": "PURCHASE"
    }
  }'
```
</Tab>
</Tabs>

Need a pixel ID? Use [`zernio.trackingtags.listTrackingTags()`](/tracking-tags/list-tracking-tags) to list the pixels a connected ad account can see (or [`zernio.trackingtags.createTrackingTag()`](/tracking-tags/create-tracking-tag) to make one) — see [Meta Pixels](/platforms/meta-ads/pixels#meta-pixels) below. [`zernio.ads.listConversionDestinations()`](/platforms/meta-ads/capi#conversions-api) returns the same set, in case you're already wiring that.

Other Meta-specific knobs on `promotedObject`:

| Field | When you'd use it |
|-------|-------------------|
| `customConversionId` | Optimising against a Custom Conversion (instead of a standard event). Pair with `pixelId`. |
| `productCatalogId` + `productSetId` | Catalog Ads / Advantage+ Shopping campaigns. |
| `applicationId` + `objectStoreUrl` | App-install / app-engagement campaigns (`goal: "app_promotion"`). |

---

# Creative Testing

Run multi-creative campaigns to test variations

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Multi-creative campaigns (creative testing)

For creative A/B testing, don't spin up one campaign per creative, that fragments the budget across parallel ad sets and none of them exit Meta's learning phase (~50 conversions/week required). Instead, pass `creatives[]` on `POST /v1/ads/create` to get 1 campaign → 1 ad set → N ads sharing the same budget, targeting, and schedule. Meta's delivery algorithm allocates budget across the creatives inside the single ad set.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.ads.createStandaloneAd({
  body: {
    accountId: 'acc_metaads_123',
    adAccountId: 'act_1234567890',
    name: 'Spring Launch',
    goal: 'traffic',
    budgetAmount: 100,
    budgetType: 'daily',
    countries: ['AR'],
    ageMin: 25,
    ageMax: 45,
    creatives: [
      { headline: 'Spring - 30% off', body: 'Limited time.', imageUrl: 'https://cdn.example.com/a.jpg', linkUrl: 'https://example.com/a', callToAction: 'SHOP_NOW' },
      { headline: 'Just for you', body: 'Curated picks.', imageUrl: 'https://cdn.example.com/b.jpg', linkUrl: 'https://example.com/b', callToAction: 'SHOP_NOW' },
      { headline: 'Free shipping', body: 'This week only.', imageUrl: 'https://cdn.example.com/c.jpg', linkUrl: 'https://example.com/c', callToAction: 'SHOP_NOW' },
    ],
  },
});
```
</Tab>
<Tab value="Python">
```python
result = client.ads.create_standalone_ad(
    account_id="acc_metaads_123",
    ad_account_id="act_1234567890",
    name="Spring Launch",
    goal="traffic",
    budget_amount=100,
    budget_type="daily",
    countries=["AR"],
    age_min=25,
    age_max=45,
    creatives=[
        {"headline": "Spring - 30% off", "body": "Limited time.", "imageUrl": "https://cdn.example.com/a.jpg", "linkUrl": "https://example.com/a", "callToAction": "SHOP_NOW"},
        {"headline": "Just for you", "body": "Curated picks.", "imageUrl": "https://cdn.example.com/b.jpg", "linkUrl": "https://example.com/b", "callToAction": "SHOP_NOW"},
        {"headline": "Free shipping", "body": "This week only.", "imageUrl": "https://cdn.example.com/c.jpg", "linkUrl": "https://example.com/c", "callToAction": "SHOP_NOW"},
    ],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_metaads_123",
    "adAccountId": "act_1234567890",
    "name": "Spring Launch",
    "goal": "traffic",
    "budgetAmount": 100,
    "budgetType": "daily",
    "countries": ["AR"],
    "ageMin": 25,
    "ageMax": 45,
    "creatives": [
      { "headline": "Spring - 30% off", "body": "Limited time.", "imageUrl": "https://cdn.example.com/a.jpg", "linkUrl": "https://example.com/a", "callToAction": "SHOP_NOW" },
      { "headline": "Just for you", "body": "Curated picks.", "imageUrl": "https://cdn.example.com/b.jpg", "linkUrl": "https://example.com/b", "callToAction": "SHOP_NOW" },
      { "headline": "Free shipping", "body": "This week only.", "imageUrl": "https://cdn.example.com/c.jpg", "linkUrl": "https://example.com/c", "callToAction": "SHOP_NOW" }
    ]
  }'
```
</Tab>
</Tabs>

Returns `{ ads: [...], platformCampaignId, platformAdSetId, message }`, N Ad documents sharing the same `platformCampaignId` + `platformAdSetId`. Each ad's name is `"<name> #N"` (e.g. "Spring Launch #1", "Spring Launch #2"). To add more creatives later without spinning up a new campaign, use the attach shape below.

Meta-only today. Non-Meta platforms return 400.

---

# Creatives

Attach creatives, video creatives, and placement asset customization

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Attach a creative to an existing ad set

To iterate on creatives after a campaign is already running, pass `adSetId` on `POST /v1/ads/create` with a single creative. One new ad gets attached to the existing ad set, budget, targeting, schedule, and goal are inherited from the ad set on Meta's side. No new campaign is created.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.ads.createStandaloneAd({
  body: {
    accountId: 'acc_metaads_123',
    adAccountId: 'act_1234567890',
    adSetId: '120250000000000000',
    name: 'Spring Launch #4',
    headline: 'One more angle',
    body: 'Social proof variant.',
    imageUrl: 'https://cdn.example.com/d.jpg',
    linkUrl: 'https://example.com/d',
    callToAction: 'SHOP_NOW',
  },
});
```
</Tab>
<Tab value="Python">
```python
result = client.ads.create_standalone_ad(
    account_id="acc_metaads_123",
    ad_account_id="act_1234567890",
    ad_set_id="120250000000000000",
    name="Spring Launch #4",
    headline="One more angle",
    body="Social proof variant.",
    image_url="https://cdn.example.com/d.jpg",
    link_url="https://example.com/d",
    call_to_action="SHOP_NOW",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_metaads_123",
    "adAccountId": "act_1234567890",
    "adSetId": "120250000000000000",
    "name": "Spring Launch #4",
    "headline": "One more angle",
    "body": "Social proof variant.",
    "imageUrl": "https://cdn.example.com/d.jpg",
    "linkUrl": "https://example.com/d",
    "callToAction": "SHOP_NOW"
  }'
```
</Tab>
</Tabs>

Returns `{ ad, message }`. Useful for weekly creative drops onto a stable ad set that Meta has already optimised on.

## Video creatives

All three shapes (standalone, multi-creative, attach) accept video. Replace `imageUrl` with a `video` object carrying the video URL and a still-image thumbnail:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.ads.createStandaloneAd({
  body: {
    accountId: 'acc_metaads_123',
    adAccountId: 'act_1234567890',
    name: 'Spring launch video',
    goal: 'video_views',
    budgetAmount: 75,
    budgetType: 'daily',
    headline: 'Spring drop is live',
    body: 'See it in action.',
    video: {
      url: 'https://cdn.example.com/spring.mp4',
      thumbnailUrl: 'https://cdn.example.com/spring-poster.jpg',
    },
    callToAction: 'SHOP_NOW',
    linkUrl: 'https://example.com/spring',
  },
});
```
</Tab>
<Tab value="Python">
```python
result = client.ads.create_standalone_ad(
    account_id="acc_metaads_123",
    ad_account_id="act_1234567890",
    name="Spring launch video",
    goal="video_views",
    budget_amount=75,
    budget_type="daily",
    headline="Spring drop is live",
    body="See it in action.",
    video={
        "url": "https://cdn.example.com/spring.mp4",
        "thumbnailUrl": "https://cdn.example.com/spring-poster.jpg",
    },
    call_to_action="SHOP_NOW",
    link_url="https://example.com/spring",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_metaads_123",
    "adAccountId": "act_1234567890",
    "name": "Spring launch video",
    "goal": "video_views",
    "budgetAmount": 75,
    "budgetType": "daily",
    "headline": "Spring drop is live",
    "body": "See it in action.",
    "video": {
      "url": "https://cdn.example.com/spring.mp4",
      "thumbnailUrl": "https://cdn.example.com/spring-poster.jpg"
    },
    "callToAction": "SHOP_NOW",
    "linkUrl": "https://example.com/spring"
  }'
```
</Tab>
</Tabs>

For multi-creative, put `video: { url, thumbnailUrl }` on each entry of `creatives[]` instead of `imageUrl`. `video` and `imageUrl` are mutually exclusive per creative, supply exactly one.

<Callout type="warn">
**Thumbnail is optional.** When you omit `video.thumbnailUrl`, the poster is auto-generated from Meta's own preferred video thumbnail (the same candidates Ads Manager shows), so `"video": { "url": "..." }` is a complete video creative. Supply your own public image URL (1200x628 or 1080x1080 recommended) to control the exact still frame — a supplied thumbnail always wins.
</Callout>

**Sync upload, long-running.** Zernio uploads the video to Meta via chunked transfer and blocks until Meta finishes transcoding (`status.video_status === "ready"`). Longer videos can take several minutes. The endpoint is configured with `maxDuration = 800s` on our side; set your HTTP client timeout to at least 15 minutes so it doesn't bail before Meta finishes. If transcoding hasn't completed within 10 minutes, the request fails with a `platform_error`.

## Placement asset customization

This is Ads Manager's "use a different creative per placement" on one ad: a 9:16 asset on Stories and Reels, a 1:1 or 4:5 on Feed, all served by a single ad. Pass a `placementAssets` object to `/v1/ads/create`. Each rule pins one asset to one or more placements, and a default asset covers every placement no rule matches.

This is distinct from [multi-creative campaigns](/platforms/meta-ads/creative-testing#multi-creative-campaigns-creative-testing) (N separate ads Meta A/B-tests) and from `dynamicCreative` (an asset *pool* Meta auto-optimizes). `placementAssets` is deterministic: you decide exactly which asset shows where.

<Callout type="info">
**Meta only** (`facebook` / `instagram`). The shared copy (`headline`, `body`, `linkUrl`, `callToAction`) comes from the top-level fields, only the *image or video* varies per placement.
</Callout>

### Image per placement

```typescript
const result = await zernio.ads.createStandaloneAd({
  body: {
    accountId: 'acc_metaads_123',
    adAccountId: 'act_1234567890',
    name: 'Spring launch (placement-tailored)',
    goal: 'traffic',
    budgetAmount: 50,
    budgetType: 'daily',
    headline: 'Spring drop is live',
    body: 'See it in action.',
    callToAction: 'SHOP_NOW',
    linkUrl: 'https://example.com/spring',
    placementAssets: {
      // Catch-all: shown on any placement no rule below matches.
      defaultImageUrl: 'https://cdn.example.com/1x1.jpg',
      rules: [
        {
          imageUrl: 'https://cdn.example.com/9x16.jpg',
          placements: {
            publisherPlatforms: ['instagram', 'facebook'],
            instagramPositions: ['story', 'reels'],
            facebookPositions: ['story', 'facebook_reels'],
          },
        },
        {
          imageUrl: 'https://cdn.example.com/4x5.jpg',
          placements: {
            instagramPositions: ['stream'],
            facebookPositions: ['feed'],
          },
        },
      ],
    },
  },
});
```

### Video per placement

Swap `imageUrl` for `videoUrl` (and `defaultImageUrl` for `defaultVideoUrl`). Poster thumbnails are optional here. Meta auto-generates one if you omit `thumbnailUrl` / `defaultThumbnailUrl`, though supplying your own gives you control over the still frame.

```typescript
const result = await zernio.ads.createStandaloneAd({
  body: {
    accountId: 'acc_metaads_123',
    adAccountId: 'act_1234567890',
    name: 'Spring launch video (placement-tailored)',
    goal: 'video_views',
    budgetAmount: 75,
    budgetType: 'daily',
    headline: 'Spring drop is live',
    body: 'See it in action.',
    callToAction: 'SHOP_NOW',
    linkUrl: 'https://example.com/spring',
    placementAssets: {
      defaultVideoUrl: 'https://cdn.example.com/1x1.mp4',
      defaultThumbnailUrl: 'https://cdn.example.com/1x1-poster.jpg', // optional
      rules: [
        {
          videoUrl: 'https://cdn.example.com/9x16.mp4',
          thumbnailUrl: 'https://cdn.example.com/9x16-poster.jpg', // optional
          placements: {
            publisherPlatforms: ['instagram', 'facebook'],
            instagramPositions: ['story', 'reels'],
            facebookPositions: ['story', 'facebook_reels'],
          },
        },
        {
          videoUrl: 'https://cdn.example.com/4x5.mp4',
          placements: {
            instagramPositions: ['stream'],
            facebookPositions: ['feed'],
          },
        },
      ],
    },
  },
});
```

### Rules

| Field | Type | Notes |
|-------|------|-------|
| `defaultImageUrl` / `defaultVideoUrl` | string | Required. The catch-all asset for placements no rule matches. Set exactly one (image *or* video, see below). |
| `defaultThumbnailUrl` | string | Optional. Poster for `defaultVideoUrl`; Meta auto-generates if omitted. |
| `rules[]` | object[] | 1-10 rules. Each pins one asset to one or more placements. |
| `rules[].imageUrl` / `rules[].videoUrl` | string | The asset for this rule. Must match the block's media mode. |
| `rules[].thumbnailUrl` | string | Optional poster for `videoUrl`. |
| `rules[].placements` | object | At least one placement field required (`publisherPlatforms` and/or a `*Positions` field). Same vocabulary as the [Targeting](/platforms/meta-ads/targeting#targeting) `placements` object. |

<Callout type="warn">
**All-image or all-video, never mixed.** A `placementAssets` block is one ad format. Use `imageUrl` + `defaultImageUrl` throughout, *or* `videoUrl` + `defaultVideoUrl` throughout. Mixing the two returns a `400`.
</Callout>

`placementAssets` builds a single placement-customized ad, so it's mutually exclusive with `creatives[]`, `adSetId`, and `dynamicCreative`. Meta enforces placement co-selection rules (e.g. `profile_feed` requires `feed`) and we surface the resulting error verbatim.

<Callout type="info">
**Works on instant-form lead ads too.** `placementAssets` is supported on `goal: "lead_generation"` (with a `leadGenFormId`) — the instant form is attached for you (the ad set is configured with the on-ad destination automatically). The auto-optimizing pool `dynamicCreative` is the exception: it needs a dedicated Dynamic Creative ad set, so `dynamicCreative` + a lead form returns a `422` (use `placementAssets`, a single creative, or run `dynamicCreative` on `traffic`/`conversions`).
</Callout>

---

# Click-to-WhatsApp Ads

Create ads that open a WhatsApp conversation

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Click-to-WhatsApp ads

Create ads that, when tapped, open a WhatsApp conversation with your business instead of sending the user to a website. Zernio drives the full hierarchy (campaign → ad set → creative → ad) in a single call. The CTA is locked to `WHATSAPP_MESSAGE` and the destination is hard-coded to `https://api.whatsapp.com/send`, Meta resolves the actual WhatsApp number from the Page-to-WhatsApp pairing configured in your Page settings.

<Callout type="warn">
  Before calling, the Facebook Page must already be paired with a verified WhatsApp Business number (Meta Business Manager → WhatsApp Accounts → connect a Page). When the Page isn't paired, Meta rejects the ad set with subcode `2446886` and Zernio surfaces a clean `platform_error` envelope.
</Callout>

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.ads.createCtwaAd({ body: {
  accountId: 'FB_OR_IG_ACCOUNT_ID',
  adAccountId: 'act_123456789',
  name: 'Summer promo, WhatsApp',
  headline: 'Chat with us on WhatsApp',
  body: 'Get a personal quote in 2 minutes.',
  imageUrl: 'https://cdn.example.com/promo.jpg',
  budgetAmount: 20,
  budgetType: 'daily',
  currency: 'USD',
  countries: ['US', 'ES'],
}});
```
</Tab>
<Tab value="Python">
```python
result = client.ads.create_ctwa_ad(
    account_id="FB_OR_IG_ACCOUNT_ID",
    ad_account_id="act_123456789",
    name="Summer promo, WhatsApp",
    headline="Chat with us on WhatsApp",
    body="Get a personal quote in 2 minutes.",
    image_url="https://cdn.example.com/promo.jpg",
    budget_amount=20,
    budget_type="daily",
    currency="USD",
    countries=["US", "ES"],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/ctwa" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "FB_OR_IG_ACCOUNT_ID",
    "adAccountId": "act_123456789",
    "name": "Summer promo, WhatsApp",
    "headline": "Chat with us on WhatsApp",
    "body": "Get a personal quote in 2 minutes.",
    "imageUrl": "https://cdn.example.com/promo.jpg",
    "budgetAmount": 20,
    "budgetType": "daily",
    "currency": "USD",
    "countries": ["US", "ES"]
  }'
```
</Tab>
</Tabs>

To close the attribution loop on conversions that happen *inside* the WhatsApp thread, see [Conversions API for Business Messaging](/platforms/whatsapp/ctwa#conversions-api-for-business-messaging) on the WhatsApp page.

### Local CTWA targeting (city radius, regions, ZIPs)

CTWA accepts the full geo-targeting shape, not just countries. For local businesses (e.g. a 25km radius around Milan), pass `cities`, `regions`, `zips`, `metros`, or `customLocations` alongside or instead of `countries`. Same wire shape as [`/v1/ads/create`](/platforms/meta-ads/targeting#targeting), `key`s come from [`/v1/ads/targeting/search`](/platforms/meta-ads/targeting#looking-up-city--region-keys).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.ads.createCtwaAd({ body: {
  accountId: 'FB_OR_IG_ACCOUNT_ID',
  adAccountId: 'act_123456789',
  name: 'Milano local CTWA',
  headline: 'Chat with us on WhatsApp',
  body: 'Get a personal quote in 2 minutes.',
  imageUrl: 'https://cdn.example.com/promo.jpg',
  budgetAmount: 20,
  budgetType: 'daily',
  currency: 'EUR',
  countries: ['IT'],
  cities: [{ key: '2643743', radius: 25, distance_unit: 'kilometer' }],
  dsaBeneficiary: 'Acme Srl',
  dsaPayor: 'Acme Srl',
}});
```
</Tab>
<Tab value="Python">
```python
result = client.ads.create_ctwa_ad(
    account_id="FB_OR_IG_ACCOUNT_ID",
    ad_account_id="act_123456789",
    name="Milano local CTWA",
    headline="Chat with us on WhatsApp",
    body="Get a personal quote in 2 minutes.",
    image_url="https://cdn.example.com/promo.jpg",
    budget_amount=20,
    budget_type="daily",
    currency="EUR",
    countries=["IT"],
    cities=[{"key": "2643743", "radius": 25, "distance_unit": "kilometer"}],
    dsa_beneficiary="Acme Srl",
    dsa_payor="Acme Srl",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/ads/ctwa" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "FB_OR_IG_ACCOUNT_ID",
    "adAccountId": "act_123456789",
    "name": "Milano local CTWA",
    "headline": "Chat with us on WhatsApp",
    "body": "Get a personal quote in 2 minutes.",
    "imageUrl": "https://cdn.example.com/promo.jpg",
    "budgetAmount": 20,
    "budgetType": "daily",
    "currency": "EUR",
    "countries": ["IT"],
    "cities": [{ "key": "2643743", "radius": 25, "distance_unit": "kilometer" }],
    "dsaBeneficiary": "Acme Srl",
    "dsaPayor": "Acme Srl"
  }'
```
</Tab>
</Tabs>

<Callout>
  The legacy `countries: ['US']` default only kicks in when no geo at all is supplied. If you pass `cities` (or any other sub-country geo) without `countries`, Zernio targets exactly that geo, not US.
</Callout>

---

# Meta Ads

Create and boost Facebook + Instagram ads via Zernio API

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

<Callout type="info">
**Included with the [Usage plan](/pricing).** No Meta App review needed. Zernio is an approved Meta Marketing Partner, so you skip the App Review + ads_management permissions entirely.
</Callout>

<Callout type="info">
**`accountId` accepts either shape.** You can pass the posting account ID (`facebook` / `instagram`) or the ads credential account ID (`metaads`), Zernio resolves the sibling internally. For Instagram ads, Zernio auto-resolves the linked Facebook Page and the Instagram Business Account ID (no extra field needed). If the Instagram account has no linked Facebook account, the API returns `code: "linked_account_required"` so you can surface a reconnect flow.
</Callout>

## What's Supported

| Feature | Status |
|---------|--------|
| Standalone campaigns (FB + IG) | Yes |
| Multi-creative campaigns (1 campaign → N ads) | Yes |
| Attach creative to existing ad set | Yes |
| Video creatives (all 3 shapes) | Yes |
| Placement asset customization (different image *or* video per placement) ([details](/platforms/meta-ads/creatives#placement-asset-customization)) | Yes |
| Boost organic posts | Yes |
| CBO vs ABO budget routing + updates | Yes |
| Campaign duplication (deep copy) | Yes |
| Campaign deletion (cascades to ad sets + ads) | Yes |
| Bulk pause / resume campaigns | Yes |
| Ad-set-scoped pause / resume | Yes |
| Custom Audiences (customer list, website, lookalike) | Yes |
| Detailed targeting (interests, age, gender, location) | Yes |
| Campaign > Ad Set > Ad hierarchy | Yes |
| Real-time analytics (spend, CPC, CPM) | Yes |
| ROAS + action_values (revenue per action_type) | Yes |
| Pixel management — create, install code, rename, share, stats ([details](/platforms/meta-ads/pixels#meta-pixels)) | Yes |
| Conversions API (offline events, hashed PII, dedup) | Yes |
| Event Match Quality read-back ([details](/platforms/meta-ads/capi#event-match-quality)) | Yes |
| Ad URL tracking tags — read + update ([details](/platforms/meta-ads/tracking-tags#ad-url-tracking-tags)) | Yes |
| Click-to-WhatsApp ads (CTWA) | Yes |
| Ad comments (read + moderate dark posts) | Yes |
| Lead Gen Forms (create forms, attach to standalone + boosted ads, leads via webhook) ([details](/platforms/meta-ads/lead-forms#lead-gen-forms)) | Yes |
| Ad Library API | Roadmap |
| Advantage+ campaigns | Roadmap |

## In This Section

<Cards>
  <Card title="Ad Comments" href="/platforms/meta-ads/ad-comments" description="Read and manage comments on your Meta ads" />
  <Card title="Boost a Post" href="/platforms/meta-ads/boost" description="Turn an existing organic post into a paid ad" />
  <Card title="Campaigns & Ad Sets" href="/platforms/meta-ads/campaigns" description="Create standalone campaigns and manage campaigns, ad sets, and budgets" />
  <Card title="Creative Testing" href="/platforms/meta-ads/creative-testing" description="Run multi-creative campaigns to test variations" />
  <Card title="Conversion Campaigns" href="/platforms/meta-ads/conversion-campaigns" description="Conversion campaigns and promoted objects" />
  <Card title="Creatives" href="/platforms/meta-ads/creatives" description="Attach creatives, video creatives, and placement asset customization" />
  <Card title="Custom Audiences" href="/platforms/meta-ads/audiences" description="Build custom and lookalike audiences" />
  <Card title="Targeting" href="/platforms/meta-ads/targeting" description="Interest, demographic, and behavior targeting" />
  <Card title="Lead Gen Forms" href="/platforms/meta-ads/lead-forms" description="Create and manage Meta lead generation forms" />
  <Card title="Click-to-WhatsApp Ads" href="/platforms/meta-ads/ctwa" description="Create ads that open a WhatsApp conversation" />
  <Card title="Meta Pixels" href="/platforms/meta-ads/pixels" description="Create and manage Meta Pixels" />
  <Card title="Conversions API" href="/platforms/meta-ads/capi" description="Send server-side conversion events to Meta" />
  <Card title="Ad URL Tracking Tags" href="/platforms/meta-ads/tracking-tags" description="Attach click-URL tracking parameters to ads" />
  <Card title="Media Requirements" href="/platforms/meta-ads/reference" description="Image and video requirements for Meta ads" />
</Cards>

---

# Lead Gen Forms

Create and manage Meta lead generation forms

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Lead Gen Forms

Create native Meta **Lead Gen (Instant) Forms**, attach them to ads, and receive submitted leads in real time. The full flow:

1. **Create a form** on a connected Facebook account with `POST /v1/ads/lead-forms`. Forms are Page-scoped (Instagram lead ads use the linked Page's form under the hood).
2. **Attach it to an ad** by setting `goal: "lead_generation"` and `leadGenFormId` on [`POST /v1/ads/create`](/ads/create-standalone-ad) (standalone) or [`POST /v1/ads/boost`](/ads/boost-post) (boost an existing post). The ad set's lead optimization and promoted Page are derived automatically, no destination URL is needed.
3. **Receive leads** in real time via the [`lead.received`](/webhooks#leadreceived) webhook, or pull them with `GET /v1/ads/lead-forms/{formId}/leads`.

<Callout type="warn">
**One-time setup:** your Facebook Page must accept Facebook's Lead Generation Terms of Service before lead ads can run. If ad creation returns Meta error subcode `1815089` ("Terms of Service Not Accepted"), accept them once at `https://www.facebook.com/ads/leadgen/tos/?page_id=YOUR_PAGE_ID`. Creating forms and reading leads works without it, only running ads requires it.
</Callout>

### Create a form, then a lead ad

Prefilled question types (`EMAIL`, `PHONE`, `FULL_NAME`, `FIRST_NAME`, `LAST_NAME`, …) auto-generate their label and key, send only `{ "type": "..." }`. `CUSTOM` questions require `key`, `label`, and (for choice questions) `options`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// 1. Create the form
const { form } = await zernio.ads.createLeadForm({ body: {
  accountId: 'FACEBOOK_ACCOUNT_ID',
  name: 'Spring promo',
  questions: [
    { type: 'EMAIL' },
    { type: 'FULL_NAME' },
    { type: 'CUSTOM', key: 'budget', label: 'Monthly budget?', options: [
      { key: 'low', value: 'Under $1k' },
      { key: 'high', value: '$1k+' },
    ] },
  ],
  privacyPolicyUrl: 'https://example.com/privacy',
} });

// 2. Create an ad that opens the form (no linkUrl needed)
const { ad } = await zernio.ads.createStandaloneAd({ body: {
  accountId: 'FACEBOOK_ACCOUNT_ID',
  adAccountId: 'act_123',
  name: 'Spring promo lead ad',
  goal: 'lead_generation',
  leadGenFormId: form.id,
  budgetAmount: 10,
  budgetType: 'daily',
  headline: 'Get a quote',
  body: 'Tell us about your project',
  callToAction: 'SIGN_UP',
  imageUrl: 'https://example.com/creative.jpg',
} });
```
</Tab>
<Tab value="Python">
```python
# 1. Create the form
form = client.ads.create_lead_form(
    account_id="FACEBOOK_ACCOUNT_ID",
    name="Spring promo",
    questions=[
        {"type": "EMAIL"},
        {"type": "FULL_NAME"},
        {"type": "CUSTOM", "key": "budget", "label": "Monthly budget?",
         "options": [{"key": "low", "value": "Under $1k"}, {"key": "high", "value": "$1k+"}]},
    ],
    privacy_policy_url="https://example.com/privacy",
)["form"]

# 2. Create an ad that opens the form (no link_url needed)
ad = client.ads.create_standalone_ad(
    account_id="FACEBOOK_ACCOUNT_ID",
    ad_account_id="act_123",
    name="Spring promo lead ad",
    goal="lead_generation",
    lead_gen_form_id=form["id"],
    budget_amount=10,
    budget_type="daily",
    headline="Get a quote",
    body="Tell us about your project",
    call_to_action="SIGN_UP",
    image_url="https://example.com/creative.jpg",
)
```
</Tab>
<Tab value="curl">
```bash
# 1. Create the form
curl -X POST "https://zernio.com/api/v1/ads/lead-forms" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "FACEBOOK_ACCOUNT_ID",
    "name": "Spring promo",
    "questions": [{"type":"EMAIL"},{"type":"FULL_NAME"}],
    "privacyPolicyUrl": "https://example.com/privacy"
  }'

# 2. Create an ad that opens the form (use the returned form id as leadGenFormId)
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "FACEBOOK_ACCOUNT_ID", "adAccountId": "act_123",
    "name": "Spring promo lead ad", "goal": "lead_generation",
    "leadGenFormId": "FORM_ID", "budgetAmount": 10, "budgetType": "daily",
    "headline": "Get a quote", "body": "Tell us about your project",
    "callToAction": "SIGN_UP", "imageUrl": "https://example.com/creative.jpg"
  }'
```
</Tab>
</Tabs>

### Receiving leads

The best way to capture leads is the [`lead.received`](/webhooks#leadreceived) webhook, fired the moment a lead is submitted. The payload carries `lead.fields` (the question-key to answer map) plus `formId` / `adId` provenance. You can also poll for them:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { leads } = await zernio.ads.listFormLeads({
  path: { formId: 'FORM_ID' },
  query: { accountId: 'FACEBOOK_ACCOUNT_ID', limit: 50 },
});
for (const lead of leads) console.log(lead.fields);
```
</Tab>
<Tab value="Python">
```python
leads = client.ads.list_form_leads(
    form_id="FORM_ID", account_id="FACEBOOK_ACCOUNT_ID", limit=50,
)["leads"]
for lead in leads:
    print(lead["fields"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/ads/lead-forms/FORM_ID/leads?accountId=FACEBOOK_ACCOUNT_ID&limit=50" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

To attach a form when **boosting an existing post**, pass the same `leadGenFormId` (and `goal: "lead_generation"`) to [`POST /v1/ads/boost`](/ads/boost-post). To retire a form, `DELETE /v1/ads/lead-forms/{formId}` (Meta archives it, there is no hard delete).

---

# Meta Pixels

Create and manage Meta Pixels

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Meta Pixels

A Meta Pixel is the measurement primitive you install on a website, send events to, and target ads against. Zernio exposes it under the platform-neutral **tracking tags** API — on Meta, `kind` is `pixel`. Uses the Meta Ads account you already connected; no extra OAuth, no `business_management` permission. The `accountId` is the Meta **ads** SocialAccount (the one the Ads add-on connect flow creates), not a Facebook/Instagram posting account; get your `act_...` ad account IDs from [`zernio.ads.listAdAccounts()`](/ads/list-ad-accounts).

### Create a pixel

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.trackingtags.createTrackingTag({
  path: { accountId: 'ACCOUNT_ID' },
  body: { adAccountId: 'act_1234567890', name: 'My Website Pixel' },
});

console.log(data.tag.id);    // new pixel ID — use it in promotedObject.pixelId, audiences, CAPI
console.log(data.tag.code);  // the base-code snippet to install on the site
```
</Tab>
<Tab value="Python">
```python
result = client.tracking_tags.create_tracking_tag(
    account_id="ACCOUNT_ID",
    ad_account_id="act_1234567890",
    name="My Website Pixel",
)
print(result.tag.id)    # new pixel ID
print(result.tag.code)  # the install snippet
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/accounts/ACCOUNT_ID/tracking-tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"adAccountId":"act_1234567890","name":"My Website Pixel"}'
```
</Tab>
</Tabs>

The response is the new tag, including `code` — the base-code snippet to drop on the site. Creating a pixel doesn't install it: install `code`, or skip the snippet entirely and send events server-side via the [Conversions API](/platforms/meta-ads/capi#conversions-api) (a pixel works as a CAPI destination immediately). `installed` is derived from `lastFiredTime` (`null` = it has never fired).

### List, fetch, and rename pixels

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Every pixel the connected ad account can see (pass query.adAccountId to scope to one)
const { data: list } = await zernio.trackingtags.listTrackingTags({
  path: { accountId: 'ACCOUNT_ID' },
});

// One pixel — includes its install code, lastFiredTime, ownerBusinessId
const { data: one } = await zernio.trackingtags.getTrackingTag({
  path: { accountId: 'ACCOUNT_ID', tagId: '1729525464415281' },
});

// Rename, or toggle Advanced Matching / first-party cookies / data-use
await zernio.trackingtags.updateTrackingTag({
  path: { accountId: 'ACCOUNT_ID', tagId: '1729525464415281' },
  body: { name: 'Website Pixel (renamed)', enableAutomaticMatching: true },
});
```
</Tab>
<Tab value="Python">
```python
# Every pixel the connected ad account can see (pass ad_account_id to scope to one)
listing = client.tracking_tags.list_tracking_tags(account_id="ACCOUNT_ID")

# One pixel — includes its install code, last_fired_time, owner_business_id
one = client.tracking_tags.get_tracking_tag(
    account_id="ACCOUNT_ID", tag_id="1729525464415281"
)

# Rename, or toggle Advanced Matching / first-party cookies / data-use
client.tracking_tags.update_tracking_tag(
    account_id="ACCOUNT_ID",
    tag_id="1729525464415281",
    name="Website Pixel (renamed)",
    enable_automatic_matching=True,
)
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/accounts/ACCOUNT_ID/tracking-tags" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://zernio.com/api/v1/accounts/ACCOUNT_ID/tracking-tags/1729525464415281" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X PATCH "https://zernio.com/api/v1/accounts/ACCOUNT_ID/tracking-tags/1729525464415281" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Website Pixel (renamed)","enableAutomaticMatching":true}'
```
</Tab>
</Tabs>

### Share a pixel with another ad account

By default a pixel only works in the ad account it was created on. Share it with others so their campaigns and audiences can use it (`listTrackingTagSharedAccounts` and `removeTrackingTagSharedAccount` round out the set):

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
await zernio.trackingtags.addTrackingTagSharedAccount({
  path: { accountId: 'ACCOUNT_ID', tagId: '1729525464415281' },
  body: { adAccountId: 'act_9876543210' },
});
```
</Tab>
<Tab value="Python">
```python
client.tracking_tags.add_tracking_tag_shared_account(
    account_id="ACCOUNT_ID",
    tag_id="1729525464415281",
    ad_account_id="act_9876543210",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/accounts/ACCOUNT_ID/tracking-tags/1729525464415281/shared-accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"adAccountId":"act_9876543210"}'
```
</Tab>
</Tabs>

For aggregated event counts, call [`zernio.trackingtags.getTrackingTagStats(...)`](/tracking-tags/get-tracking-tag-stats) — `aggregation` is `event` by default; also `host`, `url`, `device_type`, and more.

<Callout type="warn">
**Things to know about Meta Pixels:**
- **Not idempotent.** Each create call makes a new pixel — don't retry blindly on timeout.
- **One pixel per ad account on create.** `POST .../tracking-tags` returns a 400 (`A pixel already exists for this account`) if that ad account already has one. A Business Manager can own many pixels, just not two on the same ad account via this call.
- **No delete.** Meta has no API to delete a pixel. To stop using one, unshare it (`DELETE .../shared-accounts`) or disable it in Events Manager.
- **Personal ad accounts can't share.** A pixel created on an ad account that isn't owned by a Business Manager comes back with `ownerBusinessId: null` and can't be shared with other ad accounts (Meta rejects the share). Claim the ad account into a Business Manager first.
- **Not exposed (needs `business_management`):** sharing a pixel with a partner/agency business, and assigning system users to a pixel.
</Callout>

---

# Media Requirements

Image and video requirements for Meta ads

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Media Requirements

| Type | Format | Max Size | Notes |
|------|--------|----------|-------|
| Feed Image | JPEG, PNG | 30 MB | 1080x1080 or 1200x628 recommended |
| Reels Video | MP4, MOV | 4 GB | 9:16 vertical, max 90 sec |
| Story | JPEG, PNG, MP4 | 30 MB / 4 GB | 9:16 vertical |
| Carousel | JPEG, PNG, MP4 | 30 MB/card | 2-10 cards |

---

# Targeting

Interest, demographic, and behavior targeting

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Targeting

Use `/v1/ads/interests?platform=metaads&q=devops` to search interest IDs, and `/v1/ads/targeting/search?type=city&q=Amsterdam&countryCode=NL` to look up city / region keys.

| Field | Type | Description |
|-------|------|-------------|
| `ageMin` | number | Minimum age (13-65) |
| `ageMax` | number | Maximum age (13-65) |
| `countries` | string[] | ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` when no `cities` or `regions` are provided. |
| `cities` | object[] | City-level targeting. Each entry: `{ key, radius?, distance_unit? }` where `key` is from `/v1/ads/targeting/search`, and `radius` + `distance_unit` (`"kilometer"` or `"mile"`) must be set together. |
| `regions` | object[] | Region/state-level targeting. Each entry: `{ key }` from `/v1/ads/targeting/search?type=region`. |
| `interests` | object[] | `{ id, name }` from `/v1/ads/interests` |
| `gender` | string | `"all"`, `"male"`, or `"female"` (default `"all"`) |

On `/v1/ads/create`, targeting fields are flat at the top level (`ageMin`, `ageMax`, `countries`, `cities`, `regions`, `interests`). On `/v1/ads/boost`, they live inside a `targeting: { ... }` object that's passed through to Meta as-is.

### Looking up city / region keys

Meta's `cities` and `regions` use opaque IDs that aren't derivable from the name. Use the targeting search helper to resolve them:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Find Meta's key for Amsterdam in NL
const { results } = await zernio.ads.searchAdTargetingLocations({
  accountId: 'FB_ACCOUNT_ID',
  q: 'Amsterdam',
  type: 'city',
  countryCode: 'NL',
});
// results[0].key  → "2759794"

// Use the key on /v1/ads/create
await zernio.ads.createStandaloneAd({ body: {
  accountId: 'FB_ACCOUNT_ID',
  adAccountId: 'act_1234567890',
  name: 'Amsterdam launch',
  goal: 'traffic',
  budgetAmount: 20,
  budgetType: 'lifetime',
  endDate: '2026-05-15T00:00:00Z',
  headline: 'Hello Amsterdam',
  body: 'Try us this week.',
  linkUrl: 'https://example.com',
  imageUrl: 'https://cdn.example.com/promo.jpg',
  callToAction: 'LEARN_MORE',
  cities: [{ key: '2759794', radius: 25, distance_unit: 'kilometer' }],
  dsaBeneficiary: 'Acme BV',
  dsaPayor: 'Acme BV',
}});
```
</Tab>
<Tab value="Python">
```python
results = client.ads.search_ad_targeting_locations(
    account_id="FB_ACCOUNT_ID",
    q="Amsterdam",
    type="city",
    country_code="NL",
)["results"]
# results[0]["key"]  → "2759794"

client.ads.create_standalone_ad(
    account_id="FB_ACCOUNT_ID",
    ad_account_id="act_1234567890",
    name="Amsterdam launch",
    goal="traffic",
    budget_amount=20,
    budget_type="lifetime",
    end_date="2026-05-15T00:00:00Z",
    headline="Hello Amsterdam",
    body="Try us this week.",
    link_url="https://example.com",
    image_url="https://cdn.example.com/promo.jpg",
    call_to_action="LEARN_MORE",
    cities=[{"key": "2759794", "radius": 25, "distance_unit": "kilometer"}],
    dsa_beneficiary="Acme BV",
    dsa_payor="Acme BV",
)
```
</Tab>
<Tab value="curl">
```bash
# 1. Look up the city key
curl "https://zernio.com/api/v1/ads/targeting/search?accountId=FB_ACCOUNT_ID&q=Amsterdam&type=city&countryCode=NL" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Use the key on /v1/ads/create
curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "FB_ACCOUNT_ID",
    "adAccountId": "act_1234567890",
    "name": "Amsterdam launch",
    "goal": "traffic",
    "budgetAmount": 20,
    "budgetType": "lifetime",
    "endDate": "2026-05-15T00:00:00Z",
    "headline": "Hello Amsterdam",
    "body": "Try us this week.",
    "linkUrl": "https://example.com",
    "imageUrl": "https://cdn.example.com/promo.jpg",
    "callToAction": "LEARN_MORE",
    "cities": [{ "key": "2759794", "radius": 25, "distance_unit": "kilometer" }],
    "dsaBeneficiary": "Acme BV",
    "dsaPayor": "Acme BV"
  }'
```
</Tab>
</Tabs>

`type` accepts `city`, `region`, `country`, `subcity`, `neighborhood`, `zip`, `metro_area`, `geo_market`. Pass `countryCode` to disambiguate when the same name exists in multiple countries (e.g. there are several "Eindhoven"s globally).

<Callout type="warn">
  Don't combine `cities` with the same `countries`, Meta returns a "locations overlap" error because the city is already inside the country boundary. Either drop the country, or scope `countries` to a different country than the cities you're targeting.
</Callout>

---

# Ad URL Tracking Tags

Attach click-URL tracking parameters to ads

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Ad URL tracking tags

Separate from the [Meta Pixels](/platforms/meta-ads/pixels#meta-pixels) above (those are the measurement pixel). These are the `url_tags` appended to an ad's click destination, the UTM-style attribution params on the landing-page URL. Read them to audit a campaign, or update them to fix missing or wrong tags.

Read the current tags off any ad (works on synced ads too):

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.ads.getAdTrackingTags({ path: { adId: 'AD_ID' } });
// { platform: 'facebook', level: 'creative', urlTags: 'utm_source=meta&utm_medium=cpc', templateUrlSpec: null }
```
</Tab>
<Tab value="Python">
```python
data = client.ads.get_ad_tracking_tags(ad_id="AD_ID")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/ads/AD_ID/tracking-tags" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Updating tags on Meta rebuilds the creative behind the scenes (Meta creatives are immutable, so changing `url_tags` means creating a fresh creative and repointing the ad). Zernio does this for you and **preserves the existing creative verbatim**, re-posting its current headline, body, CTA, and image (reused by hash, never re-uploaded) with only the new tags added. So you send `urlTags` alone, there's nothing to read back or supply:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.ads.updateAdTrackingTags({
  path: { adId: 'AD_ID' },
  body: {
    urlTags: [
      { key: 'utm_source', value: 'meta' },
      { key: 'utm_medium', value: 'cpc' },
    ],
  },
});
```
</Tab>
<Tab value="Python">
```python
data = client.ads.update_ad_tracking_tags(
    ad_id="AD_ID",
    url_tags=[
        {"key": "utm_source", "value": "meta"},
        {"key": "utm_medium", "value": "cpc"},
    ],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X PATCH "https://zernio.com/api/v1/ads/AD_ID/tracking-tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urlTags": [
      { "key": "utm_source", "value": "meta" },
      { "key": "utm_medium", "value": "cpc" }
    ]
  }'
```
</Tab>
</Tabs>

<Callout type="info">
**`creative` is optional.** Omit it to preserve the existing creative (above). Pass it (`headline`, `body`, `callToAction`, `linkUrl`, `imageUrl`) only to rebuild the creative explicitly, or for the few creatives Zernio can't auto-preserve. SHARE / page-post-boost / dark posts and Advantage+ asset-feed creatives have their underlying spec stripped by Meta, so they return a `422` asking for `creative`.
</Callout>

---

# Analytics & Engagement

Tweet analytics and engagement actions

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Analytics

> **Included** — Analytics is bundled with every paid account on the [Usage plan](/pricing).

Available metrics via the [Analytics API](/analytics/get-analytics):

| Metric | Available |
|--------|-----------|
| Impressions | ✅ |
| Likes | ✅ |
| Comments | ✅ |
| Shares | ✅ |
| Clicks | ✅ |
| Views | ✅ |

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const analytics = await zernio.analytics.getAnalytics({
  platform: 'twitter',
  fromDate: '2024-01-01',
  toDate: '2024-01-31'
});
console.log(analytics.posts);
```
</Tab>
<Tab value="Python">
```python
analytics = client.analytics.get_analytics(
    platform="twitter",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(analytics["posts"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/analytics?platform=twitter&fromDate=2024-01-01&toDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

## Engagement

Retweet, bookmark, and follow directly through the API. All engagement endpoints share a **50 requests per 15-min window** rate limit. Retweets also share the 300/3hr creation limit with tweet creation.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Retweet
await zernio.twitterengagement.retweetPost({
  accountId: 'YOUR_ACCOUNT_ID',
  tweetId: '1748391029384756102'
});

// Bookmark
await zernio.twitterengagement.bookmarkPost({
  accountId: 'YOUR_ACCOUNT_ID',
  tweetId: '1748391029384756102'
});

// Follow
await zernio.twitterengagement.followUser({
  accountId: 'YOUR_ACCOUNT_ID',
  targetUserId: '123456789'
});
```
</Tab>
<Tab value="Python">
```python
# Retweet
client.twitter_engagement.retweet_post(
    account_id="YOUR_ACCOUNT_ID",
    tweet_id="1748391029384756102"
)

# Bookmark
client.twitter_engagement.bookmark_post(
    account_id="YOUR_ACCOUNT_ID",
    tweet_id="1748391029384756102"
)

# Follow
client.twitter_engagement.follow_user(
    account_id="YOUR_ACCOUNT_ID",
    target_user_id="123456789"
)
```
</Tab>
<Tab value="curl">
```bash
# Retweet
curl -X POST https://zernio.com/api/v1/twitter/retweet \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "YOUR_ACCOUNT_ID", "tweetId": "1748391029384756102"}'

# Bookmark
curl -X POST https://zernio.com/api/v1/twitter/bookmark \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "YOUR_ACCOUNT_ID", "tweetId": "1748391029384756102"}'

# Follow
curl -X POST https://zernio.com/api/v1/twitter/follow \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "YOUR_ACCOUNT_ID", "targetUserId": "123456789"}'
```
</Tab>
</Tabs>

| Action | Endpoint | Undo |
|--------|----------|------|
| Retweet | `POST /v1/twitter/retweet` | `DELETE /v1/twitter/retweet` |
| Bookmark | `POST /v1/twitter/bookmark` | `DELETE /v1/twitter/bookmark` |
| Follow | `POST /v1/twitter/follow` | `DELETE /v1/twitter/follow` |

See [Twitter Engagement API Reference](/twitter-engagement/retweet-post) for full endpoint documentation.

---

# Fields, Geo & Polls

Platform-specific fields, geo-restriction, polls, and media URL requirements

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Platform-Specific Fields

All fields go inside `platformSpecificData` on the Twitter platform entry.

| Field | Type | Description |
|-------|------|-------------|
| `replyToTweetId` | string | ID of an existing tweet to reply to. The published tweet will appear as a reply in that tweet's thread. For threads, only the first tweet replies to the target; subsequent tweets chain normally. |
| `quoteTweetId` | string | ID (or full status URL) of an existing tweet to quote-repost. Mutually exclusive with media and poll. For threads, applies to the first tweet only. |
| `replySettings` | "following" \| "mentionedUsers" \| "subscribers" \| "verified" | Controls who can reply to the tweet. Omit for default (everyone can reply). For threads, applies to the first tweet only. Cannot be combined with `replyToTweetId`. |
| `threadItems` | Array\<\{content, mediaItems?\}\> | Complete sequence of tweets in a thread. The first item becomes the root tweet and must be provided as `threadItems[0]`. When `threadItems` is provided, top-level `content` is for display/search only and is NOT published. |
| `poll` | object | Create a poll with this tweet. Mutually exclusive with media attachments and threads. |
| `poll.options` | string[] | Poll options (2-4 choices, max 25 characters each). |
| `poll.duration_minutes` | number | Poll duration in minutes (5 min to 7 days). |
| `longVideo` | boolean | Enable long video uploads (over 140 seconds) using amplify_video. Requires X Premium; may require allowlisting. |
| `geoRestriction` | object | Restrict media visibility to specific countries. Only applies when media is attached (ignored for text-only tweets). `geoRestriction.countries`: array of uppercase ISO 3166-1 alpha-2 codes, max 25. The media is hidden in restricted countries; the tweet text remains visible globally. |
| `paidPartnership` | boolean | When true, label the post 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` | boolean | When true, label the post as containing AI-generated media (not AI-written text). For threads, applies to the root tweet only. |
| `sensitiveMedia` | object | Marks attached media with a sensitive-content warning (requires media; ignored for text-only tweets). At least one flag must be true. |
| `sensitiveMedia.adultContent` | boolean | Content contains adult material. |
| `sensitiveMedia.graphicViolence` | boolean | Content depicts graphic violence. |
| `sensitiveMedia.other` | boolean | Content has other sensitive characteristics. |

## Geo-Restriction

Restrict who can see your tweet's media by country. This applies at the media level: the media is hidden for users outside the specified countries, but the tweet text remains visible globally. Requires media to be attached.

```json
{
  "platforms": [{
    "platform": "twitter",
    "accountId": "YOUR_ACCOUNT_ID",
    "platformSpecificData": {
      "geoRestriction": {
        "countries": ["US", "ES"]
      }
    }
  }],
  "mediaItems": [{"type": "image", "url": "https://example.com/photo.jpg"}]
}
```

## Paid partnership, AI labels, and sensitive media

Zernio supports additional X labels via `platformSpecificData`.

> **Note:** `paidPartnership` and `madeWithAi` apply to the root tweet only (for threads).

### Paid partnership label

Set `platformSpecificData.paidPartnership: true` to label the post as a paid partnership / paid promotion.

> **Note:** Field availability may depend on your X API access tier.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Sponsored: our new feature is live",
    "platforms": [{
      "platform": "twitter",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "paidPartnership": true
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Sponsored: our new feature is live',
  platforms: [{
    platform: 'twitter',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      paidPartnership: true
    }
  }],
  publishNow: true
});

console.log('Tweet posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Sponsored: our new feature is live",
    platforms=[{
        "platform": "twitter",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "paidPartnership": True
        }
    }],
    publish_now=True
)
post = result.post
print(f"Tweet posted! {post['_id']}")
```
</Tab>
</Tabs>

### AI-generated media label

Set `platformSpecificData.madeWithAi: true` to label the post as containing AI-generated media.

> **Note:** Per X, this label is for AI-generated media, not AI-written text.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "AI-generated image (labeled)",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/ai-image.jpg"}
    ],
    "platforms": [{
      "platform": "twitter",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "madeWithAi": true
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'AI-generated image (labeled)',
  mediaItems: [{ type: 'image', url: 'https://cdn.example.com/ai-image.jpg' }],
  platforms: [{
    platform: 'twitter',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      madeWithAi: true
    }
  }],
  publishNow: true
});

console.log('Tweet posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="AI-generated image (labeled)",
    media_items=[{"type": "image", "url": "https://cdn.example.com/ai-image.jpg"}],
    platforms=[{
        "platform": "twitter",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "madeWithAi": True
        }
    }],
    publish_now=True
)
post = result.post
print(f"Tweet posted! {post['_id']}")
```
</Tab>
</Tabs>

### Sensitive media warning

Use `platformSpecificData.sensitiveMedia` to mark attached media with a sensitive-content warning.

> **Note:** Requires media (ignored for text-only tweets). At least one flag must be `true`.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Sensitive media example",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/photo.jpg"}
    ],
    "platforms": [{
      "platform": "twitter",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "sensitiveMedia": {
          "adultContent": true,
          "graphicViolence": false,
          "other": false
        }
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Sensitive media example',
  mediaItems: [{ type: 'image', url: 'https://cdn.example.com/photo.jpg' }],
  platforms: [{
    platform: 'twitter',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      sensitiveMedia: {
        adultContent: true,
        graphicViolence: false,
        other: false
      }
    }
  }],
  publishNow: true
});

console.log('Tweet posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Sensitive media example",
    media_items=[{"type": "image", "url": "https://cdn.example.com/photo.jpg"}],
    platforms=[{
        "platform": "twitter",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "sensitiveMedia": {
                "adultContent": True,
                "graphicViolence": False,
                "other": False
            }
        }
    }],
    publish_now=True
)
post = result.post
print(f"Tweet posted! {post['_id']}")
```
</Tab>
</Tabs>

## Polls

Create a Twitter/X poll by providing `platformSpecificData.poll`.

> **Note:** Polls are mutually exclusive with `mediaItems` and `platformSpecificData.threadItems`.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Which feature should we ship next?",
    "platforms": [{
      "platform": "twitter",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "poll": {
          "options": ["Dark mode", "New analytics", "More integrations"],
          "duration_minutes": 1440
        }
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Which feature should we ship next?',
  platforms: [{
    platform: 'twitter',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      poll: {
        options: ['Dark mode', 'New analytics', 'More integrations'],
        duration_minutes: 1440
      }
    }
  }],
  publishNow: true
});
console.log('Poll posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Which feature should we ship next?",
    platforms=[{
        "platform": "twitter",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "poll": {
                "options": ["Dark mode", "New analytics", "More integrations"],
                "duration_minutes": 1440
            }
        }
    }],
    publish_now=True
)
post = result.post
print(f"Poll posted! {post['_id']}")
```
</Tab>
</Tabs>

## Media URL Requirements

<Callout type="error">
**These do not work as media URLs:**
- **Google Drive** -- returns an HTML download page, not the file
- **Dropbox** -- returns an HTML preview page
- **OneDrive / SharePoint** -- returns HTML
- **iCloud** -- returns HTML

Test your URL in an incognito browser window. If you see a webpage instead of the raw image or video, it will not work.
</Callout>

Media URLs must be:
- Publicly accessible (no authentication required)
- Returning actual media bytes with the correct `Content-Type` header
- Not behind redirects that resolve to HTML pages
- Hosted on a fast, reliable CDN

**Supabase URLs:** Zernio auto-proxies Supabase storage URLs, so they work without additional configuration.

---

# Inbox

Direct messages in the inbox

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Inbox

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

Twitter/X supports DMs and comments through the unified Inbox API.

### Direct Messages

| Feature | Supported |
|---------|-----------|
| List conversations | ✅ |
| Fetch messages | ✅ |
| Send text messages | ✅ |
| Send attachments | ✅ (images, videos - max 25 MB) |
| Archive/unarchive | ❌ |

#### Create conversation (send a DM)

Use `POST /v1/inbox/conversations` to start a new DM conversation (or append to an existing thread).

> **Note:** X DM write endpoints require **X API Pro tier ($5,000/month)** or Enterprise access. This applies to BYOK users who provide their own X API credentials.

> **Note:** By default, Zernio checks DM eligibility (recipient `receives_your_dm`). If the recipient does not accept DMs, the API returns `422` with code `DM_NOT_ALLOWED`. You can skip this check with `skipDmCheck: true`.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/inbox/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_ACCOUNT_ID",
    "participantUsername": "targetuser",
    "message": "Hello from Zernio Inbox API!"
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const result = await zernio.messages.createInboxConversation({
  accountId: 'YOUR_ACCOUNT_ID',
  participantUsername: 'targetuser',
  message: 'Hello from Zernio Inbox API!'
});

console.log('DM sent:', result.data.conversationId, result.data.messageId);
```
</Tab>
<Tab value="Python">
```python
result = client.messages.create_inbox_conversation(
    account_id="YOUR_ACCOUNT_ID",
    participant_username="targetuser",
    message="Hello from Zernio Inbox API!"
)

print("DM sent:", result["data"]["conversationId"], result["data"]["messageId"])
```
</Tab>
</Tabs>

### Comments

| Feature | Supported |
|---------|-----------|
| List comments on posts | ✅ |
| Post new comment | ✅ |
| Reply to comments | ✅ |
| Delete comments | ✅ |
| Like/unlike comments | ✅ |
| Hide/unhide comments | ✅ |

### Limitations

- **Encrypted X Chat DMs not accessible** - X has replaced traditional DMs with end-to-end encrypted "X Chat" for many accounts. Messages sent or received through encrypted X Chat are not returned by X's API. This means some conversations may show only outgoing messages or appear empty. This is an [X platform limitation](https://help.x.com/en/using-x/about-chat) that affects all third-party applications.
- **DM permissions** - DMs require `dm.read` and `dm.write` scopes
- **Reply search** - Uses cached conversation threads (2-min TTL) to manage rate limits
- **Cached DMs** - Conversations are cached with a 15-min TTL

See [Messages](/messages/list-inbox-conversations) and [Comments](/comments/list-inbox-comments) API Reference for endpoint details.

---

# Twitter/X

Schedule and automate Twitter/X posts with Zernio API

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Cards, Card } from 'fumadocs-ui/components/card';
import { PlatformCapabilities } from '@/components/platform-capabilities';

## Quick Reference

<PlatformCapabilities rows={[
  { property: 'Character limit', value: '280 (free) / 25,000 (Premium)' },
  { property: 'Images per post', value: '4 (or 1 GIF)' },
  { property: 'Videos per post', value: '1' },
  { property: 'Image formats', value: 'JPEG, PNG, WebP, GIF' },
  { property: 'Image max size', value: '5 MB (images), 15 MB (GIFs)' },
  { property: 'Video formats', value: 'MP4, MOV' },
  { property: 'Video max size', value: '512 MB' },
  { property: 'Video max duration', value: '140 seconds' },
  { property: 'Threads', value: 'Yes (via threadItems)' },
  { property: 'Scheduling', value: 'Yes' },
  { property: 'Inbox (DMs)', value: 'Yes' },
  { property: 'Inbox (Comments)', value: 'Yes' },
  { property: 'Analytics', value: 'Yes' },
]} />

## Before You Start

<Callout type="warn">
Twitter has a strict **280 character limit** for free accounts. URLs always count as 23 characters regardless of actual length. Emojis count as 2 characters. If you're cross-posting from platforms with higher limits (LinkedIn 3,000, Facebook 63,000), use `customContent` to provide a shorter Twitter version or your post **WILL** fail.

Additional requirements:
- Duplicate tweets are rejected (even very similar content)
- Free accounts: 280 characters, Premium accounts: 25,000 characters
</Callout>

<Callout type="info">
**X API costs are passed through at exact rate, with zero markup.** Unlike other platforms, X (Twitter) operates on a pay-per-call API model. Every X API operation Zernio performs on your behalf — posting, reading analytics, sending DMs, fetching followers — is metered against your account at X's published price.

Common rates that appear on your invoice:

- **Posts: Read** — $0.005 per resource (analytics, post lookups)
- **Content: Create** — $0.015 per request (publishing a tweet)
- **Content: Create with URL** — $0.200 per request (tweets containing http/https links — yes, X charges 13× more for these)
- **DM: Read** / **DM: Send** — $0.010 / $0.015 per resource

These appear as itemized line items on your monthly invoice. Zernio's per-call price always equals X's published price, never higher. The full rate table is at [docs.x.com/x-api/getting-started/pricing](https://docs.x.com/x-api/getting-started/pricing).

You can set a **monthly X spend cap** from the dashboard's Billing tab to prevent surprise bills. At 80% of the cap you get a warning email; at 100% Zernio automatically pauses X analytics + inbox polling for the rest of the period.
</Callout>

## Related Endpoints

- [Connect Twitter Account](/guides/connecting-accounts) - OAuth flow
- [Create Post](/posts/create-post) - Post creation and scheduling
- [Upload Media](/guides/media-uploads) - Image and video uploads
- [Analytics](/analytics/get-analytics) - Post performance metrics
- [Twitter Engagement](/twitter-engagement/retweet-post) - Retweet, bookmark, follow
- [Messages](/messages/list-inbox-conversations) and [Comments](/comments/list-inbox-comments)

## In This Section

<Cards>
  <Card title="Posts & Editing" href="/platforms/twitter/posts" description="Create tweets, threads, and edit published tweets" />
  <Card title="Replies & Quotes" href="/platforms/twitter/replies-quotes" description="Reply tweets and quote reposts" />
  <Card title="Media & Video" href="/platforms/twitter/media" description="Media requirements and long video uploads (Premium)" />
  <Card title="Fields, Geo & Polls" href="/platforms/twitter/fields-polls" description="Platform-specific fields, geo-restriction, polls, and media URL requirements" />
  <Card title="Analytics & Engagement" href="/platforms/twitter/analytics-engagement" description="Tweet analytics and engagement actions" />
  <Card title="Inbox" href="/platforms/twitter/inbox" description="Direct messages in the inbox" />
  <Card title="Limits & Errors" href="/platforms/twitter/reference" description="What you cannot do and common errors" />
</Cards>

---

# Media & Video

Media requirements and long video uploads (Premium)

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Media Requirements

### Images

| Property | Requirement |
|----------|-------------|
| **Max images** | 4 per tweet |
| **Formats** | JPEG, PNG, WebP, GIF |
| **Max file size** | 5 MB (images), 15 MB (GIFs) |
| **Min dimensions** | 4 x 4 px |
| **Max dimensions** | 8192 x 8192 px |
| **Recommended** | 1200 x 675 px (16:9) |

#### Aspect Ratios

| Type | Ratio | Dimensions |
|------|-------|------------|
| Landscape | 16:9 | 1200 x 675 px |
| Square | 1:1 | 1200 x 1200 px |
| Portrait | 4:5 | 1080 x 1350 px |

### GIFs

| Property | Requirement |
|----------|-------------|
| **Max per tweet** | 1 (consumes all 4 image slots) |
| **Max file size** | 15 MB |
| **Max dimensions** | 1280 x 1080 px |
| **Behavior** | Auto-plays in timeline |

### Videos

| Property | Requirement |
|----------|-------------|
| **Max videos** | 1 per tweet |
| **Formats** | MP4, MOV |
| **Max file size** | 512 MB |
| **Max duration** | 140 seconds (2 min 20 sec) standard; up to ~10 minutes with Premium long video (see below) |
| **Min duration** | 0.5 seconds |
| **Min dimensions** | 32 x 32 px |
| **Max dimensions** | 1920 x 1200 px |
| **Frame rate** | 40 fps max |
| **Bitrate** | 25 Mbps max |

## Long Video Uploads (Premium)

By default, X limits API video uploads to **140 seconds**. If the connected X account has an active **X Premium** subscription, you can enable long video uploads (over 140 seconds) by setting `platformSpecificData.longVideo: true`.

> **Note:** Not all Premium accounts have API long-video access, as X may require separate allowlisting.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Long video upload (Premium)",
    "mediaItems": [
      {"type": "video", "url": "https://cdn.example.com/long-video.mp4"}
    ],
    "platforms": [{
      "platform": "twitter",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "longVideo": true
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Long video upload (Premium)',
  mediaItems: [{ type: 'video', url: 'https://cdn.example.com/long-video.mp4' }],
  platforms: [{
    platform: 'twitter',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      longVideo: true
    }
  }],
  publishNow: true
});

console.log('Tweet posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Long video upload (Premium)",
    media_items=[{"type": "video", "url": "https://cdn.example.com/long-video.mp4"}],
    platforms=[{
        "platform": "twitter",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {"longVideo": True}
    }],
    publish_now=True
)

post = result.post
print(f"Tweet posted! {post['_id']}")
```
</Tab>
</Tabs>

#### Recommended Video Specs

| Property | Recommended |
|----------|-------------|
| Resolution | 1280 x 720 px (720p) |
| Aspect ratio | 16:9 (landscape) or 1:1 (square) |
| Frame rate | 30 fps |
| Codec | H.264 |
| Audio | AAC, 128 kbps |

---

# Posts & Editing

Create tweets, threads, and edit published tweets

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Start

Post a tweet in under 60 seconds:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Hello from Zernio API!',
  platforms: [
    { platform: 'twitter', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Tweet posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Hello from Zernio API!",
    platforms=[
        {"platform": "twitter", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Tweet posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from Zernio API!",
    "platforms": [
      {"platform": "twitter", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

## Content Types

### Text Tweet

A simple text-only tweet. Keep it under 280 characters for free accounts.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Just shipped a new feature. Check it out!',
  platforms: [
    { platform: 'twitter', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Tweet posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Just shipped a new feature. Check it out!",
    platforms=[
        {"platform": "twitter", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Tweet posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Just shipped a new feature. Check it out!",
    "platforms": [
      {"platform": "twitter", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Tweet with Image

Attach up to 4 images per tweet. JPEG, PNG, WebP, and GIF formats are supported.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Check out this photo!',
  mediaItems: [
    { type: 'image', url: 'https://cdn.example.com/photo.jpg' }
  ],
  platforms: [
    { platform: 'twitter', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Tweet with image posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Check out this photo!",
    media_items=[
        {"type": "image", "url": "https://cdn.example.com/photo.jpg"}
    ],
    platforms=[
        {"platform": "twitter", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Tweet with image posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out this photo!",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/photo.jpg"}
    ],
    "platforms": [
      {"platform": "twitter", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Tweet with Video

Attach a single video per tweet. MP4 and MOV formats, up to 512 MB, max 140 seconds (standard uploads).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'New product demo',
  mediaItems: [
    { type: 'video', url: 'https://cdn.example.com/demo.mp4' }
  ],
  platforms: [
    { platform: 'twitter', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Tweet with video posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="New product demo",
    media_items=[
        {"type": "video", "url": "https://cdn.example.com/demo.mp4"}
    ],
    platforms=[
        {"platform": "twitter", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Tweet with video posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New product demo",
    "mediaItems": [
      {"type": "video", "url": "https://cdn.example.com/demo.mp4"}
    ],
    "platforms": [
      {"platform": "twitter", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Tweet with GIF

Only 1 GIF per tweet (it consumes all 4 image slots). Max 15 MB, 1280 x 1080 px. Animated GIFs auto-play in the timeline.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Check out this animation!',
  mediaItems: [
    { type: 'gif', url: 'https://cdn.example.com/animation.gif' }
  ],
  platforms: [
    { platform: 'twitter', accountId: 'YOUR_ACCOUNT_ID' }
  ],
  publishNow: true
});
console.log('Tweet with GIF posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Check out this animation!",
    media_items=[
        {"type": "gif", "url": "https://cdn.example.com/animation.gif"}
    ],
    platforms=[
        {"platform": "twitter", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    publish_now=True
)
post = result.post
print(f"Tweet with GIF posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out this animation!",
    "mediaItems": [
      {"type": "gif", "url": "https://cdn.example.com/animation.gif"}
    ],
    "platforms": [
      {"platform": "twitter", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

### Thread (Multi-Tweet)

Create Twitter threads with multiple connected tweets using `platformSpecificData.threadItems`. Each item becomes a reply to the previous tweet and can have its own content and media.

> **Note:** 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]`.

## Edit Published Tweets

Zernio supports editing **published** tweets via X's edit feature.

> **Note:** Editing is currently supported for **X (Twitter) only**, requires an active **X Premium** subscription on the connected account, must be within **1 hour** of the original publish time, is limited to **5 edits per tweet** (enforced by X), and supports **text-only** edits (media changes are not supported).

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts/YOUR_POST_ID/edit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "twitter",
    "content": "Updated tweet text with corrected information"
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const result = await zernio.posts.editPost({
  postId: 'YOUR_POST_ID',
  platform: 'twitter',
  content: 'Updated tweet text with corrected information'
});

console.log('Edited tweet:', result.id, result.url);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.edit_post(
    post_id="YOUR_POST_ID",
    platform="twitter",
    content="Updated tweet text with corrected information"
)

print("Edited tweet:", result["id"], result["url"])
```
</Tab>
</Tabs>

---

# Limits & Errors

What you cannot do and common errors

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## What You Can't Do

These features are not available through Twitter's API:

- Create Spaces
- Post to Communities
- Pin tweets to profile
- Add Twitter Cards (must be configured on the destination URL via meta tags)
- Post as a personal DM broadcast

## Common Errors

Twitter/X has a **21.3% failure rate** across Zernio's platform (17,385 failures out of 81,796 attempts). Here are the most frequent errors and how to fix them:

| Error | What it means | How to fix |
|-------|---------------|------------|
| "Tweet text is too long (X characters). Twitter's limit is 280 characters. Note: URLs count as 23 characters." | Exceeds 280 character limit for free accounts | Shorten text or use `customContent` for Twitter. Remember: URLs = 23 chars, emojis = 2 chars. |
| "X (Twitter) does not allow duplicate tweets" | Same or very similar content was already posted | Modify the text, even slightly. |
| "Rate limit hit. Please wait 10 minutes" | Zernio's velocity limit was triggered | Reduce posting frequency. Space posts at least 4 minutes apart. |
| "Missing tweet.write scope" / "forbidden" | OAuth token lacks required permissions | Reconnect the account with all required scopes. |
| Token expired | OAuth access was revoked or expired | Reconnect the account. Subscribe to the `account.disconnected` webhook to catch this proactively. |

---

# Replies & Quotes

Reply tweets and quote reposts

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Reply Tweets

Use `platformSpecificData.replyToTweetId` to publish a tweet as a reply to an existing tweet.

> **Note:** `replyToTweetId` cannot be combined with `replySettings`. For threads, only the first tweet replies to the target; subsequent tweets chain normally.

## Quote Tweets (Quote Reposts)

Use `platformSpecificData.quoteTweetId` to publish a quote tweet (quote repost) of an existing tweet.

> **Note:** `quoteTweetId` is mutually exclusive with `mediaItems` and `platformSpecificData.poll`. For threads, it applies to the first tweet only.

> **Note:** X only permits quoting your own posts or posts you are mentioned in / part of the conversation thread of; quoting an arbitrary other account's post is rejected by X.

> **Note:** Quoting via `quoteTweetId` is billed at the standard create rate ($0.015). Pasting a tweet URL into the text is billed at the URL rate ($0.20).

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Adding context via quote tweet",
    "platforms": [{
      "platform": "twitter",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "quoteTweetId": "1748391029384756102"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Adding context via quote tweet',
  platforms: [{
    platform: 'twitter',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      quoteTweetId: '1748391029384756102'
    }
  }],
  publishNow: true
});

console.log('Quote tweet posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Adding context via quote tweet",
    platforms=[{
        "platform": "twitter",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "quoteTweetId": "1748391029384756102"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Quote tweet posted! {post['_id']}")
```
</Tab>
</Tabs>

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Replying via Zernio API",
    "platforms": [{
      "platform": "twitter",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "replyToTweetId": "1748391029384756102"
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  content: 'Replying via Zernio API',
  platforms: [{
    platform: 'twitter',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      replyToTweetId: '1748391029384756102'
    }
  }],
  publishNow: true
});
console.log('Reply posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    content="Replying via Zernio API",
    platforms=[{
        "platform": "twitter",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "replyToTweetId": "1748391029384756102"
        }
    }],
    publish_now=True
)
post = result.post
print(f"Reply posted! {post['_id']}")
```
</Tab>
</Tabs>

### Reply Thread

To reply with a thread, combine `replyToTweetId` with `threadItems`. Only the first thread item replies to the target tweet.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": [{
      "platform": "twitter",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "replyToTweetId": "1748391029384756102",
        "threadItems": [
          {"content": "1/ Reply thread: first tweet replies to the target"},
          {"content": "2/ Follow-up tweet in the same thread"}
        ]
      }
    }],
    "publishNow": true
  }'
```
</Tab>
<Tab value="JavaScript">
```typescript
const { post } = await zernio.posts.createPost({
  platforms: [{
    platform: 'twitter',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      replyToTweetId: '1748391029384756102',
      threadItems: [
        { content: '1/ Reply thread: first tweet replies to the target' },
        { content: '2/ Follow-up tweet in the same thread' }
      ]
    }
  }],
  publishNow: true
});
console.log('Reply thread posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    platforms=[{
        "platform": "twitter",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "replyToTweetId": "1748391029384756102",
            "threadItems": [
                {"content": "1/ Reply thread: first tweet replies to the target"},
                {"content": "2/ Follow-up tweet in the same thread"}
            ]
        }
    }],
    publish_now=True
)
post = result.post
print(f"Reply thread posted! {post['_id']}")
```
</Tab>
</Tabs>

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { post } = await zernio.posts.createPost({
  platforms: [{
    platform: 'twitter',
    accountId: 'YOUR_ACCOUNT_ID',
    platformSpecificData: {
      threadItems: [
        {
          content: '1/ Starting a thread about API design',
          mediaItems: [{ type: 'image', url: 'https://cdn.example.com/image1.jpg' }]
        },
        { content: '2/ First, always use proper HTTP methods...' },
        { content: '3/ Second, version your APIs from day one...' },
        { content: '4/ Finally, document everything! /end' }
      ]
    }
  }],
  publishNow: true
});
console.log('Thread posted!', post._id);
```
</Tab>
<Tab value="Python">
```python
result = client.posts.create_post(
    platforms=[{
        "platform": "twitter",
        "accountId": "YOUR_ACCOUNT_ID",
        "platformSpecificData": {
            "threadItems": [
                {
                    "content": "1/ Starting a thread about API design",
                    "mediaItems": [{"type": "image", "url": "https://cdn.example.com/image1.jpg"}]
                },
                {"content": "2/ First, always use proper HTTP methods..."},
                {"content": "3/ Second, version your APIs from day one..."},
                {"content": "4/ Finally, document everything! /end"}
            ]
        }
    }],
    publish_now=True
)
post = result.post
print(f"Thread posted! {post['_id']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": [{
      "platform": "twitter",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "threadItems": [
          {
            "content": "1/ Starting a thread about API design",
            "mediaItems": [{"type": "image", "url": "https://cdn.example.com/image1.jpg"}]
          },
          {
            "content": "2/ First, always use proper HTTP methods..."
          },
          {
            "content": "3/ Second, version your APIs from day one..."
          },
          {
            "content": "4/ Finally, document everything! /end"
          }
        ]
      }
    }],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

---

# Broadcasts

Send WhatsApp template messages to many recipients with per-recipient variables and scheduling

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Quick Start

Send a WhatsApp template message to multiple recipients. Create a broadcast, add phone numbers, and send:

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

const zernio = new Zernio();

// Step 1: Create a WhatsApp broadcast with a Meta-approved template
const { data: broadcast } = await zernio.broadcasts.createBroadcast({
  body: {
    profileId: 'YOUR_PROFILE_ID',
    accountId: 'YOUR_WHATSAPP_ACCOUNT_ID',
    platform: 'whatsapp',
    name: 'Welcome Campaign',
    template: {
      name: 'hello_world',
      language: 'en'
    }
  }
});

// Step 2: Add WhatsApp recipients by phone number
await zernio.broadcasts.addBroadcastRecipients({
  path: { broadcastId: broadcast.broadcast.id },
  body: {
    phones: ['+1234567890', '+0987654321']
  }
});

// Step 3: Send the WhatsApp broadcast
const { data: result } = await zernio.broadcasts.sendBroadcast({
  path: { broadcastId: broadcast.broadcast.id }
});
console.log(`Sent: ${result.sent}, Failed: ${result.failed}`);
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio()

# Step 1: Create a WhatsApp broadcast with a Meta-approved template
broadcast = client.broadcasts.create_broadcast(
    profile_id='YOUR_PROFILE_ID',
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    platform='whatsapp',
    name='Welcome Campaign',
    template={
        'name': 'hello_world',
        'language': 'en'
    }
)

# Step 2: Add WhatsApp recipients by phone number
client.broadcasts.add_broadcast_recipients(
    broadcast_id=broadcast.broadcast.id,
    phones=['+1234567890', '+0987654321']
)

# Step 3: Send the WhatsApp broadcast
result = client.broadcasts.send_broadcast(
    broadcast_id=broadcast.broadcast.id
)
print(f"Sent: {result.sent}, Failed: {result.failed}")
```
</Tab>
<Tab value="curl">
```bash
# Step 1: Create a WhatsApp broadcast
BROADCAST_ID=$(curl -s -X POST https://zernio.com/api/v1/broadcasts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "YOUR_PROFILE_ID",
    "accountId": "YOUR_WHATSAPP_ACCOUNT_ID",
    "platform": "whatsapp",
    "name": "Welcome Campaign",
    "template": {
      "name": "hello_world",
      "language": "en"
    }
  }' | jq -r '.broadcast.id')

# Step 2: Add WhatsApp recipients by phone number
curl -X POST "https://zernio.com/api/v1/broadcasts/$BROADCAST_ID/recipients" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones": ["+1234567890", "+0987654321"]}'

# Step 3: Send the WhatsApp broadcast
curl -X POST "https://zernio.com/api/v1/broadcasts/$BROADCAST_ID/send" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

## Broadcasts

Send WhatsApp template messages to many recipients at once. Broadcasts support per-recipient template variables, scheduling, and delivery tracking (sent, delivered, read).

### Create a Broadcast

Create a WhatsApp broadcast by specifying your WABA account and a Meta-approved template:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.broadcasts.createBroadcast({
  body: {
    profileId: 'YOUR_PROFILE_ID',
    accountId: 'YOUR_WHATSAPP_ACCOUNT_ID',
    platform: 'whatsapp',
    name: 'January Newsletter',
    template: {
      name: 'monthly_update',
      language: 'en',
      components: [{
        type: 'body',
        parameters: [{ type: 'text', text: '{{1}}' }]
      }]
    }
  }
});
console.log('Broadcast created:', data.broadcast.id);
```
</Tab>
<Tab value="Python">
```python
response = client.broadcasts.create_broadcast(
    profile_id='YOUR_PROFILE_ID',
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    platform='whatsapp',
    name='January Newsletter',
    template={
        'name': 'monthly_update',
        'language': 'en',
        'components': [{
            'type': 'body',
            'parameters': [{'type': 'text', 'text': '{{1}}'}]
        }]
    }
)
print(f"Broadcast created: {response.broadcast.id}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/broadcasts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "YOUR_PROFILE_ID",
    "accountId": "YOUR_WHATSAPP_ACCOUNT_ID",
    "platform": "whatsapp",
    "name": "January Newsletter",
    "template": {
      "name": "monthly_update",
      "language": "en",
      "components": [{
        "type": "body",
        "parameters": [{"type": "text", "text": "{{1}}"}]
      }]
    }
  }'
```
</Tab>
</Tabs>

### Template Variables

WhatsApp templates use numbered placeholders (`{{1}}`, `{{2}}`, and so on) defined in the template body when you create it, for example `Hi {{1}}, your order {{2}} has been confirmed!`. Only numbered placeholders are supported, not named ones.

To fill those placeholders, add a `variableMapping` to the broadcast's `template`. It maps each placeholder position to a contact field or a static value, and Zernio resolves it for every recipient automatically at send time (so `{{1}}` becomes each contact's own name, `{{2}}` their order number, and so on):

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.broadcasts.createBroadcast({
  body: {
    profileId: 'YOUR_PROFILE_ID',
    accountId: 'YOUR_WHATSAPP_ACCOUNT_ID',
    platform: 'whatsapp',
    name: 'Order Confirmations',
    template: {
      name: 'order_confirmation',
      language: 'en',
      components: [{
        type: 'body',
        parameters: [
          { type: 'text', text: '{{1}}' },
          { type: 'text', text: '{{2}}' }
        ]
      }],
      // Resolved per recipient at send time
      variableMapping: {
        '1': { field: 'name' },                           // each contact's name
        '2': { field: 'custom', customValue: 'VIP-2025' } // same value for everyone
      }
    }
  }
});
```
</Tab>
<Tab value="Python">
```python
response = client.broadcasts.create_broadcast(
    profile_id='YOUR_PROFILE_ID',
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    platform='whatsapp',
    name='Order Confirmations',
    template={
        'name': 'order_confirmation',
        'language': 'en',
        'components': [{
            'type': 'body',
            'parameters': [
                {'type': 'text', 'text': '{{1}}'},
                {'type': 'text', 'text': '{{2}}'}
            ]
        }],
        # Resolved per recipient at send time
        'variableMapping': {
            '1': {'field': 'name'},                            # each contact's name
            '2': {'field': 'custom', 'customValue': 'VIP-2025'} # same value for everyone
        }
    }
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/broadcasts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "YOUR_PROFILE_ID",
    "accountId": "YOUR_WHATSAPP_ACCOUNT_ID",
    "platform": "whatsapp",
    "name": "Order Confirmations",
    "template": {
      "name": "order_confirmation",
      "language": "en",
      "components": [{
        "type": "body",
        "parameters": [
          {"type": "text", "text": "{{1}}"},
          {"type": "text", "text": "{{2}}"}
        ]
      }],
      "variableMapping": {
        "1": { "field": "name" },
        "2": { "field": "custom", "customValue": "VIP-2025" }
      }
    }
  }'
```
</Tab>
</Tabs>

Each `variableMapping` entry maps a position to one of these `field` values:

| `field` | Resolves to |
| --- | --- |
| `name` | The contact's name (falls back to "there" if unset) |
| `phone` | The recipient's phone number |
| `email` | The contact's email |
| `company` | The contact's company |
| `custom` | The literal `customValue` string (same for every recipient) |

<Callout type="warn">
The number of `variableMapping` entries must match the number of placeholders in the template body. A mismatch makes Meta reject the send with a parameter-count error (code 132000).
</Callout>

### Add Recipients

Add WhatsApp recipients by phone number, existing contact IDs, or by matching your contact segment filters. Phone numbers are in E.164 format (e.g., `+1234567890`):

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Add WhatsApp recipients by phone number (auto-creates contacts)
const { data } = await zernio.broadcasts.addBroadcastRecipients({
  path: { broadcastId: 'BROADCAST_ID' },
  body: {
    phones: ['+1555000111', '+1555000222']
  }
});
console.log(`Added: ${data.added}, Skipped: ${data.skipped}`);

// Or add existing contacts by ID
await zernio.broadcasts.addBroadcastRecipients({
  path: { broadcastId: 'BROADCAST_ID' },
  body: {
    contactIds: ['contact_1', 'contact_2']
  }
});

// Or auto-populate from your broadcast's segment filters (e.g., all contacts tagged "vip")
await zernio.broadcasts.addBroadcastRecipients({
  path: { broadcastId: 'BROADCAST_ID' },
  body: { useSegment: true }
});
```
</Tab>
<Tab value="Python">
```python
# Add WhatsApp recipients by phone number (auto-creates contacts)
response = client.broadcasts.add_broadcast_recipients(
    broadcast_id='BROADCAST_ID',
    phones=['+1555000111', '+1555000222']
)
print(f"Added: {response.added}, Skipped: {response.skipped}")

# Or add existing contacts by ID
client.broadcasts.add_broadcast_recipients(
    broadcast_id='BROADCAST_ID',
    contact_ids=['contact_1', 'contact_2']
)

# Or auto-populate from your broadcast's segment filters
client.broadcasts.add_broadcast_recipients(
    broadcast_id='BROADCAST_ID',
    use_segment=True
)
```
</Tab>
<Tab value="curl">
```bash
# Add WhatsApp recipients by phone number
curl -X POST "https://zernio.com/api/v1/broadcasts/BROADCAST_ID/recipients" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones": ["+1555000111", "+1555000222"]}'

# Or add existing contacts by ID
curl -X POST "https://zernio.com/api/v1/broadcasts/BROADCAST_ID/recipients" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactIds": ["contact_1", "contact_2"]}'
```
</Tab>
</Tabs>

### Send a Broadcast

Triggers immediate delivery of the WhatsApp template messages to all recipients:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.broadcasts.sendBroadcast({
  path: { broadcastId: 'BROADCAST_ID' }
});
console.log(`Sent: ${data.sent}, Failed: ${data.failed}`);
```
</Tab>
<Tab value="Python">
```python
response = client.broadcasts.send_broadcast(
    broadcast_id='BROADCAST_ID'
)
print(f"Sent: {response.sent}, Failed: {response.failed}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/broadcasts/BROADCAST_ID/send" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

### Schedule a Broadcast

Schedule the WhatsApp broadcast for a future time. Zernio sends the template messages automatically at the scheduled time:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
await zernio.broadcasts.scheduleBroadcast({
  path: { broadcastId: 'BROADCAST_ID' },
  body: { scheduledAt: '2025-02-01T10:00:00.000Z' }
});
```
</Tab>
<Tab value="Python">
```python
client.broadcasts.schedule_broadcast(
    broadcast_id='BROADCAST_ID',
    scheduled_at='2025-02-01T10:00:00.000Z'
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/broadcasts/BROADCAST_ID/schedule" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduledAt": "2025-02-01T10:00:00.000Z"}'
```
</Tab>
</Tabs>

---

# Calling

Inbound and outbound WhatsApp voice calling

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Calling

WhatsApp Business Calling lets customers place a voice call to your business number from inside the WhatsApp chat. Zernio bridges the call to a destination you choose: a regular phone number, a SIP endpoint, or an AI voice agent (Vapi, Retell, or any WebSocket media server). Both inbound (customer calls you) and outbound (you call the customer) are supported.

<Callout type="warn">
Calling is available on the [Usage plan](/pricing) only, so it requires usage-based billing to be active on your account. Zernio bills the carrier connection (plus an optional recording surcharge) at cost with zero markup; Meta bills its per-minute outbound rate directly to your WABA (see [Pricing & Costs](#pricing--costs)).

**Outbound is restricted by country and messaging tier.** Meta blocks business-initiated calls on numbers registered in the US, Canada, Egypt, Vietnam, and Nigeria. Inbound calls to those numbers still work. For outbound elsewhere, Meta's production guidance requires the number to be at the 2,000-recipient daily messaging tier (`TIER_2K`); below that, outbound may be rate-limited by Meta.
</Callout>

### Get Calling Config

Read the current calling state for a connected number. Returns the `phoneNumberDocId` you need for the enable/update/disable calls, along with the forwarding destination and recording flag.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappcalling.getWhatsAppCallingConfig({
  query: { accountId: 'YOUR_ACCOUNT_ID' }
});
console.log(data.phoneNumberDocId, data.callingEnabled, data.forwardTo);
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp_calling.get_whats_app_calling_config(account_id='YOUR_ACCOUNT_ID')
print(response['phoneNumberDocId'], response['callingEnabled'], response['forwardTo'])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/calling?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

### Enable Calling

Turn calling on for a number and set the forwarding destination. The `id` in the path is the `phoneNumberDocId` from the config call above. `forwardTo` accepts `tel:+E164` (phone), `sip:...` (SIP endpoint), or `wss://...` (WebSocket media server / AI agent).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappcalling.enableWhatsAppCalling({
  path: { id: 'PHONE_NUMBER_DOC_ID' },
  body: {
    accountId: 'YOUR_ACCOUNT_ID',
    forwardTo: 'tel:+13105551234',
    recordingEnabled: false,
  }
});
console.log('Calling enabled:', data.callingEnabled);
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp_calling.enable_whats_app_calling(
    id='PHONE_NUMBER_DOC_ID',
    account_id='YOUR_ACCOUNT_ID',
    forward_to='tel:+13105551234',
    recording_enabled=False,
)
print('Calling enabled:', response['callingEnabled'])
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/whatsapp/phone-numbers/PHONE_NUMBER_DOC_ID/calling" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "YOUR_ACCOUNT_ID", "forwardTo": "tel:+13105551234", "recordingEnabled": false}'
```
</Tab>
</Tabs>

<Callout type="info">
Recording is off by default. When `recordingEnabled` is true, a consent prompt plays before recording starts, and recording adds a small per-minute surcharge to what Zernio bills (the carrier connection).
</Callout>

To change the destination or recording flag later, use `updateWhatsAppCalling` (PATCH) with the same path id. To turn calling off, use `disableWhatsAppCalling` (DELETE) with the `accountId` query param; the forwarding destination is preserved so you can re-enable without reconfiguring.

### Check Call Permission

Before placing an outbound call, confirm the consumer has granted call permission. WhatsApp requires the customer to opt in; the response tells you whether you can start a call now or must first request permission.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappcalling.getWhatsAppCallPermissions({
  query: { accountId: 'YOUR_ACCOUNT_ID', to: '+13105551234' }
});
console.log(data.permission.status); // 'permanent' | 'temporary' | 'no_permission'
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp_calling.get_whats_app_call_permissions(
    account_id='YOUR_ACCOUNT_ID',
    to='+13105551234',
)
print(response['permission']['status'])  # 'permanent' | 'temporary' | 'no_permission'
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/call-permissions?accountId=YOUR_ACCOUNT_ID&to=%2B13105551234" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

### Place an Outbound Call

Dial a consumer. The call bridges to the number's configured `forwardTo` destination unless you pass an override. Only `accountId` and `to` are required.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappcalling.initiateWhatsAppCall({
  body: { accountId: 'YOUR_ACCOUNT_ID', to: '+13105551234' }
});
console.log(data.callId, data.status); // '...', 'dialing'
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp_calling.initiate_whats_app_call(
    account_id='YOUR_ACCOUNT_ID',
    to='+13105551234',
)
print(response['callId'], response['status'])  # '...', 'dialing'
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/whatsapp/calls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "YOUR_ACCOUNT_ID", "to": "+13105551234"}'
```
</Tab>
</Tabs>

### List Call History

Fetch past calls for a number, with optional filters by status, direction, and date range. Each call carries its duration, end reason, recording URL (if enabled), and a billing breakdown.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappcalling.listWhatsAppCalls({
  query: { accountId: 'YOUR_ACCOUNT_ID', direction: 'inbound', limit: 50 }
});
// billing.billableCostUSD is what Zernio charges (carrier connection +
// recording). Meta's per-minute outbound rate is billed by Meta directly to
// your WABA and is reported separately as billing.metaCostUSD (display only).
data.calls.forEach(c => console.log(c.direction, c.status, c.durationSeconds, c.billing?.billableCostUSD));
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp_calling.list_whats_app_calls(
    account_id='YOUR_ACCOUNT_ID',
    direction='inbound',
    limit=50,
)
# billing.billableCostUSD is what Zernio charges (carrier connection +
# recording). Meta's per-minute outbound rate is billed by Meta directly to
# your WABA and is reported separately as billing.metaCostUSD (display only).
for c in response['calls']:
    print(c['direction'], c['status'], c.get('durationSeconds'), c.get('billing', {}).get('billableCostUSD'))
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/calls?accountId=YOUR_ACCOUNT_ID&direction=inbound&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

---

# Connection & Setup

Connect a WhatsApp Business Account via redirect flow, headless credentials, or the dashboard

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Connection (API)

WhatsApp requires a **WhatsApp Business Account (WABA)** and uses Meta's infrastructure for authentication. There are two ways to connect via the API:

### Option 1: Redirect Flow (Recommended)

The standard OAuth-style redirect flow. Works from any domain, no JavaScript SDK required. Same pattern as connecting Instagram, TikTok, or any other platform.

1. Your app calls the connect endpoint to get an auth URL
2. You redirect the user to Meta's WhatsApp signup page
3. User selects or creates a WhatsApp Business Account and picks a phone number
4. User is redirected back to your app with the connection details

**Step 1: Get the auth URL**

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.get('/v1/connect/whatsapp', {
  params: {
    profileId: 'YOUR_PROFILE_ID',
    redirect_url: 'https://yourdomain.com/callback'
  }
});

// Redirect your user to the auth URL
// data.authUrl -> Meta's WhatsApp signup page
```
</Tab>
<Tab value="Python">
```python
response = client.get('/v1/connect/whatsapp', params={
    'profileId': 'YOUR_PROFILE_ID',
    'redirect_url': 'https://yourdomain.com/callback'
})
auth_url = response.json()['authUrl']
# Redirect user to auth_url
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/connect/whatsapp?profileId=YOUR_PROFILE_ID&redirect_url=https://yourdomain.com/callback" \
  -H "Authorization: Bearer YOUR_API_KEY"
# Returns: { "authUrl": "https://facebook.com/...", "state": "..." }
```
</Tab>
</Tabs>

**Step 2:** Redirect your user to the `authUrl`. They complete WhatsApp Business signup on Meta's page.

**Step 3:** After completing signup, the user is redirected back to your `redirect_url` with connection details appended as query parameters:

```
https://yourdomain.com/callback?connected=whatsapp&profileId=xxx&accountId=xxx&username=+1234567890
```

The account is now connected and ready to send and receive messages.

<Callout type="info">
This is the same connect flow used by all platforms in Zernio. No Facebook JavaScript SDK is needed. Works from any domain.
</Callout>

### Option 2: Headless Credentials (No Browser)

If you already have your Meta credentials, you can connect entirely via API with no browser popup. This is ideal for server-to-server integrations, CLI tools, or automated provisioning.

**Prerequisites:** Create a System User in [Meta Business Suite](https://business.facebook.com/settings/system-users), generate a permanent access token with `whatsapp_business_management` and `whatsapp_business_messaging` permissions (add `whatsapp_business_manage_events` too if you plan to use [Click-to-WhatsApp conversion tracking](/platforms/whatsapp/ctwa#conversions-api-for-business-messaging)), and get your WABA ID and Phone Number ID from the WhatsApp Manager.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.post('/v1/connect/whatsapp/credentials', {
  profileId: 'YOUR_PROFILE_ID',
  accessToken: 'YOUR_META_SYSTEM_USER_TOKEN',
  wabaId: 'YOUR_WABA_ID',
  phoneNumberId: 'YOUR_PHONE_NUMBER_ID'
});
console.log('Connected:', data.account.accountId);
```
</Tab>
<Tab value="Python">
```python
response = client.post('/v1/connect/whatsapp/credentials', json={
    'profileId': 'YOUR_PROFILE_ID',
    'accessToken': 'YOUR_META_SYSTEM_USER_TOKEN',
    'wabaId': 'YOUR_WABA_ID',
    'phoneNumberId': 'YOUR_PHONE_NUMBER_ID'
})
print(f"Connected: {response.json()['account']['accountId']}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/connect/whatsapp/credentials \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "YOUR_PROFILE_ID",
    "accessToken": "YOUR_META_SYSTEM_USER_TOKEN",
    "wabaId": "YOUR_WABA_ID",
    "phoneNumberId": "YOUR_PHONE_NUMBER_ID"
  }'
```
</Tab>
</Tabs>

The endpoint validates your credentials against Meta's API, creates the connection, subscribes to webhooks, and registers the phone number on the WhatsApp network. If the `phoneNumberId` is not found in your WABA, the response includes available phone numbers so you can correct it.

### WhatsApp Business App Coexistence

Businesses that already use the **WhatsApp Business app** can connect their existing number to Cloud API without giving up the app. During the Embedded Signup flow (Option 1), they will see an option to connect their existing WhatsApp Business app account and phone number.

When a business chooses this option:

- Their phone number works with **both** the WhatsApp Business app and Cloud API simultaneously
- Messages sent and received are **mirrored** between both apps (up to 6 months of history is synced)
- Contacts from the WhatsApp Business app are imported automatically
- The business can still send individual messages from the WA Business app

**Limitations:**

| Feature | Status |
|---------|--------|
| Throughput | Fixed at 20 messages per second |
| Group chats (app-side) | Not synced. WA Business app groups are not visible via API |
| Groups API | Not supported. To create or manage groups via API (see [Group Chats](/platforms/whatsapp/groups)) you need a non-coexistence number (Cloud API only) |
| Voice/video calls | Not supported via API |
| Disappearing messages | Turned off for all 1:1 chats |
| View once messages | Disabled for all 1:1 chats |
| Broadcast lists | Disabled in the WA Business app |

**Disconnection:** The business disconnects from the WhatsApp Business app (Settings > Account > Business Platform > Disconnect). This cannot be done via API. When they disconnect, Zernio automatically deactivates the account.

<Callout type="info">
Coexistence is transparent to your integration. You use the same API endpoints for sending messages, managing contacts, and everything else. The only difference is the lower throughput limit (20 mps vs. the standard Cloud API throughput).
</Callout>

## Getting Started (App Setup)

Follow these steps to connect your WhatsApp Business Account through the Zernio dashboard.

### Step 1: Go to Connections

Navigate to **Connections** in the sidebar and find the **WhatsApp** card. Click **+ Connect** to start the setup.

![Go to Connections and click Connect on WhatsApp](/docs-static/whatsapp/1.png)

### Step 2: Choose Your Number Type

You'll see two options:

1. **Get a new number** (recommended) - Zernio provisions and verifies a number for you. You pick the country next. US is $2/mo; most other countries run $2 to $25/mo (shown before you confirm).
2. **Use my own number** - Bring your existing phone number. Requires verification during setup.

![Choose between getting a new number or using your own](/docs-static/whatsapp/2.png)

### Step 3: Pick a Country and Confirm

Choose the country for your number and review its monthly price.

- **US and other instant countries** are provisioned and verified in about 30 seconds.
- **Regulated countries** (most of Europe, plus many others) require a one-time identity-verification (KYC) form before the number can be provisioned: the registrant's name, a local address, and an ID document or business registration. Some countries (for example, Australia) also require the end user to complete an ID check via a secure link. After you submit, the order goes to regulatory review and the number activates within 1-3 business days; we email you (and fire the [`whatsapp.number.activated`](/webhooks#whatsappnumberactivated) webhook) when it's ready.

Click **Confirm** to proceed.

![Pick a country and confirm your phone number purchase](/docs-static/whatsapp/3.png)

### Step 4: Auto-Verification

Zernio automatically verifies your number with Meta. This usually takes about 30 seconds - just wait for the verification to complete.

![Auto-verifying your number with Meta](/docs-static/whatsapp/4.png)

### Step 5: Continue to Meta Registration

Once verification is complete, click **Continue to WhatsApp setup** to register your phone number with Meta.

![Click continue to register with Meta](/docs-static/whatsapp/5.png)

### Step 6: Meta Account Setup

You'll be redirected to Meta's Embedded Signup. Here you can either create a new WhatsApp Business Account or connect to an existing one. Follow the prompts to complete the setup.

![Meta Embedded Signup - create or choose account](/docs-static/whatsapp/6.png)

<Callout type="warn">
Planning to use the [Groups API](/platforms/whatsapp/groups)? In this step, do **not** choose "Connect existing WhatsApp Business app account". That option activates [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence), which disables group create and management endpoints. Create a new WABA or select a number that is not already in the WhatsApp Business app.
</Callout>

### Step 7: Select Your Number

In the phone number selection, you'll see the number you purchased already marked as **Verified**. Select it and continue.

![Your purchased number appears as verified](/docs-static/whatsapp/7.png)

### Step 8: Connected!

Once verified, your WhatsApp account appears in your connections list with a **connected** status. You can now click **Settings** to configure it.

![WhatsApp connected successfully](/docs-static/whatsapp/8.png)

### Step 9: Manage Templates

Click **Settings** on your WhatsApp connection to view and create message templates. Templates must be approved by Meta before use.

![View and manage your WhatsApp templates](/docs-static/whatsapp/9.png)

### Step 10: Configure Business Profile

Switch to the **Business Profile** tab to customize your profile picture, display name, about text, description, and contact information.

![Configure your WhatsApp Business Profile](/docs-static/whatsapp/10.png)

<Callout type="warn">
After connecting, you'll start in Meta's **sandbox tier** with a limit of 250 unique contacts per day. This limit increases automatically as you build messaging history and maintain quality.
</Callout>

---

# Contacts & Profile

Manage your WhatsApp contact list and business profile

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Contacts

Manage your WhatsApp contact list for broadcasts and messaging. Store phone numbers, tags, opt-in status, and custom fields for each contact.

### Create a Contact

Create a WhatsApp contact with their phone number. The phone number links the contact to your WABA for messaging:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.contacts.createContact({
  body: {
    profileId: 'YOUR_PROFILE_ID',
    name: 'John Doe',
    email: 'john@example.com',
    tags: ['vip', 'newsletter'],
    // Link this contact to your WhatsApp number
    accountId: 'YOUR_WHATSAPP_ACCOUNT_ID',
    platform: 'whatsapp',
    platformIdentifier: '+1234567890'
  }
});
console.log('Contact created:', data.contact.id);
```
</Tab>
<Tab value="Python">
```python
response = client.contacts.create_contact(
    profile_id='YOUR_PROFILE_ID',
    name='John Doe',
    email='john@example.com',
    tags=['vip', 'newsletter'],
    # Link this contact to your WhatsApp number
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    platform='whatsapp',
    platform_identifier='+1234567890'
)
print(f"Contact created: {response.contact.id}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "YOUR_PROFILE_ID",
    "name": "John Doe",
    "email": "john@example.com",
    "tags": ["vip", "newsletter"],
    "accountId": "YOUR_WHATSAPP_ACCOUNT_ID",
    "platform": "whatsapp",
    "platformIdentifier": "+1234567890"
  }'
```
</Tab>
</Tabs>

### Bulk Import

Import up to 1,000 WhatsApp contacts at once with phone numbers and tags. Duplicates are automatically skipped:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.contacts.bulkCreateContacts({
  body: {
    profileId: 'YOUR_PROFILE_ID',
    accountId: 'YOUR_WHATSAPP_ACCOUNT_ID',
    platform: 'whatsapp',
    contacts: [
      { name: 'John Doe', platformIdentifier: '+1234567890', tags: ['vip'] },
      { name: 'Jane Smith', platformIdentifier: '+0987654321', tags: ['newsletter'] }
    ]
  }
});
console.log(`Created: ${data.created}, Skipped: ${data.skipped}`);
```
</Tab>
<Tab value="Python">
```python
response = client.contacts.bulk_create_contacts(
    profile_id='YOUR_PROFILE_ID',
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    platform='whatsapp',
    contacts=[
        {'name': 'John Doe', 'platform_identifier': '+1234567890', 'tags': ['vip']},
        {'name': 'Jane Smith', 'platform_identifier': '+0987654321', 'tags': ['newsletter']}
    ]
)
print(f"Created: {response.created}, Skipped: {response.skipped}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/contacts/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "YOUR_PROFILE_ID",
    "accountId": "YOUR_WHATSAPP_ACCOUNT_ID",
    "platform": "whatsapp",
    "contacts": [
      {"name": "John Doe", "platformIdentifier": "+1234567890", "tags": ["vip"]},
      {"name": "Jane Smith", "platformIdentifier": "+0987654321", "tags": ["newsletter"]}
    ]
  }'
```
</Tab>
</Tabs>

### Update a Contact

Update a WhatsApp contact's tags, opt-in status, or other fields:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.contacts.updateContact({
  path: { contactId: 'CONTACT_ID' },
  body: {
    tags: ['vip', 'promo-march'],
    isSubscribed: true
  }
});
console.log('Updated:', data.contact.id);
```
</Tab>
<Tab value="Python">
```python
response = client.contacts.update_contact(
    contact_id='CONTACT_ID',
    tags=['vip', 'promo-march'],
    is_subscribed=True
)
print(f"Updated: {response.contact.id}")
```
</Tab>
<Tab value="curl">
```bash
curl -X PATCH "https://zernio.com/api/v1/contacts/CONTACT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["vip", "promo-march"], "isSubscribed": true}'
```
</Tab>
</Tabs>

## Business Profile

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Get business profile
const { data } = await zernio.whatsapp.getWhatsAppBusinessProfile({
  query: { accountId: 'YOUR_ACCOUNT_ID' }
});
console.log(data.businessProfile);

// Update business profile
await zernio.whatsapp.updateWhatsAppBusinessProfile({
  body: {
    accountId: 'YOUR_ACCOUNT_ID',
    about: 'Your go-to store for widgets',
    description: 'We sell the best widgets in town.',
    email: 'hello@example.com',
    websites: ['https://example.com']
  }
});
```
</Tab>
<Tab value="Python">
```python
# Get business profile
response = client.whatsapp.get_whats_app_business_profile(
    account_id='YOUR_ACCOUNT_ID'
)
print(response.business_profile)

# Update business profile
client.whatsapp.update_whats_app_business_profile(
    account_id='YOUR_ACCOUNT_ID',
    about='Your go-to store for widgets',
    description='We sell the best widgets in town.',
    email='hello@example.com',
    websites=['https://example.com']
)
```
</Tab>
<Tab value="curl">
```bash
# Get business profile
curl "https://zernio.com/api/v1/whatsapp/business-profile?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update business profile
curl -X POST https://zernio.com/api/v1/whatsapp/business-profile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_ACCOUNT_ID",
    "about": "Your go-to store for widgets",
    "description": "We sell the best widgets in town.",
    "email": "hello@example.com",
    "websites": ["https://example.com"]
  }'
```
</Tab>
</Tabs>

---

# Click-to-WhatsApp Ads

Capture CTWA clicks and forward conversion events to Meta for attribution

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Click-to-WhatsApp ads & attribution

Click-to-WhatsApp (CTWA) ads are Meta ads that, when tapped, open a WhatsApp conversation with your business instead of a website. They're a Meta Ads concept, Zernio creates them via [`POST /v1/ads/ctwa`](/platforms/meta-ads/ctwa#click-to-whatsapp-ads) (see the [Meta Ads page](/platforms/meta-ads/ctwa#click-to-whatsapp-ads) for the request shape and prerequisites).

This page covers the WhatsApp side of the loop: capturing the originating click and sending conversion events back to Meta for attribution.

### Automatic ctwa_clid capture

When a user reaches your WhatsApp business via a CTWA ad, Meta attaches a `referral` object, including `ctwa_clid` (Meta's click ID for WhatsApp), to the **first inbound message** of the conversation. Zernio's webhook handler captures it automatically and persists it on the [Conversation](/messages/list-inbox-conversations) record's `metadata`:

```json
{
  "metadata": {
    "ctwa_clid": "AbCdEfGhIjKlMn0pQrStUvWxYz",
    "ctwa_captured_at": "2026-04-27T09:18:44.991Z",
    "ctwa_source_id": "120000000000000000",
    "ctwa_source_url": "https://fb.me/...",
    "ctwa_headline": "Chat with us on WhatsApp",
    "ctwa_source_type": "ad"
  }
}
```

The capture is one-shot, once `ctwa_clid` is set, later messages from the same user never overwrite it (Meta only emits `referral` on the first message after a click).

### Conversions API for Business Messaging

Forward conversion events that happen inside the WhatsApp thread back to Meta with `action_source = business_messaging` so they attribute to the originating CTWA ad. Distinct from Meta Ads' general [Conversions API](/platforms/meta-ads/capi#conversions-api): that one is for web pixel events; this one is purpose-built for messaging conversions.

#### Provision the dataset

Before sending events you need a Meta dataset linked to the WABA. Zernio creates one for you in a single call. The endpoint is GET-first idempotent (a WABA can only own one CTWA dataset), so re-running it is a safe no-op that returns the existing ID with `created: false`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsapp.createWhatsAppDataset({
  body: { accountId: 'WHATSAPP_ACCOUNT_ID' }
});
console.log(data.datasetId, data.created); // created: false if one already existed
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp.create_whats_app_dataset(
    account_id='WHATSAPP_ACCOUNT_ID'
)
print(response.dataset_id, response.created)  # created: False if one already existed
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/whatsapp/dataset" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "WHATSAPP_ACCOUNT_ID"}'
```
</Tab>
</Tabs>

The dataset ID is persisted on the WhatsApp account as `metadata.metaCapiDatasetId`, which is what [`POST /v1/whatsapp/conversions`](/platforms/whatsapp/ctwa#send-a-conversion-event) reads to attribute events. There is also a `GET /v1/whatsapp/dataset?accountId=` that returns the persisted ID without touching Meta, useful for surfacing whether tracking is set up on an account.

<Callout type="warn">
  If Meta rejects the call with `(#100) Invalid parameter`, the most common cause is that the connected WhatsApp Business Account is not fully verified yet. Complete business verification in Meta Business Manager and try again. The endpoint returns `422` and includes Meta's raw error so other causes (region restrictions, app-level disablement) are visible. If you connect via [Headless Credentials](/platforms/whatsapp/connection#option-2-headless-credentials-no-browser), make sure your System User token includes `whatsapp_business_manage_events`, the scope is auto-extended to tokens minted through the [Redirect Flow](/platforms/whatsapp/connection#option-1-redirect-flow-recommended) but not to System User tokens you mint yourself.
</Callout>

<Callout type="info">
  Prefer to use an existing dataset (for example, one you already own in a different Business Manager)? Skip the provisioning call and set `metadata.metaCapiDatasetId` directly. In that case the WhatsApp account's access token must have access to that dataset, 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). Share the dataset with the WhatsApp app's Business in Meta Business Manager, or use one already in the same Business.
</Callout>

#### Send a conversion event

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const result = await zernio.whatsapp.sendWhatsAppConversion({ body: {
  accountId: 'WHATSAPP_ACCOUNT_ID',
  conversationId: 'CONVERSATION_ID', // or use phoneE164
  eventName: 'LeadSubmitted',
  eventId: 'lead_abc_123',
  value: 49.00,
  currency: 'USD',
}});
```
</Tab>
<Tab value="Python">
```python
result = client.whatsapp.send_whats_app_conversion(
    account_id="WHATSAPP_ACCOUNT_ID",
    conversation_id="CONVERSATION_ID",
    event_name="LeadSubmitted",
    event_id="lead_abc_123",
    value=49.00,
    currency="USD",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/whatsapp/conversions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "WHATSAPP_ACCOUNT_ID",
    "conversationId": "CONVERSATION_ID",
    "eventName": "LeadSubmitted",
    "eventId": "lead_abc_123",
    "value": 49.00,
    "currency": "USD"
  }'
```
</Tab>
</Tabs>

#### Check recent activity

List the most recent conversion events sent for a WhatsApp account, useful if you want to mirror the "Conversions" tab inside your own dashboard or build alerting on top of attribution sends.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsapp.listWhatsAppConversions({
  query: { accountId: 'WHATSAPP_ACCOUNT_ID', limit: 50 }
});
data.events.forEach(e => {
  console.log(e.timestamp, e.eventName, e.conversationId, e.eventsReceived, e.eventsFailed);
});
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp.list_whats_app_conversions(
    account_id='WHATSAPP_ACCOUNT_ID', limit=50
)
for e in response.events:
    print(e.timestamp, e.event_name, e.conversation_id, e.events_received, e.events_failed)
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/conversions?accountId=WHATSAPP_ACCOUNT_ID&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

Each row carries the event timestamp, the event name (one of the [supported event names](/platforms/whatsapp/ctwa#supported-event-names)), the originating Zernio `conversationId`, `eventsReceived` / `eventsFailed` as Meta reported them on the send, the Meta `traceId` (`fbtrace_id`, handy for cross-referencing in Meta Events Manager), and how long the send took.

<Callout type="info">
  The feed is sourced from delivery logs, not a persisted event store, so the window is bounded by log retention (about 30 days). If you need a long-lived audit trail, persist on your side as you call `POST /v1/whatsapp/conversions`.
</Callout>

### Supported event names

Meta's allowlist for `business_messaging` events is narrower than the standard pixel CAPI:

| Event | Use for |
|---|---|
| `LeadSubmitted` | Form filled, contact details captured, lead qualified |
| `Purchase` | Customer completed a purchase (payment confirmed, invoice issued) |
| `AddToCart` | Customer added an item to cart in-thread |
| `InitiateCheckout` | Customer started a checkout flow |
| `ViewContent` | Customer viewed a specific product / service |

<Callout type="info">
  `Lead` (the standard pixel name) is **not** accepted on `business_messaging` events. Use `LeadSubmitted` instead. Other standard pixel names (`CompleteRegistration`, `Subscribe`, `Schedule`, `Contact`, `StartTrial`, `AddPaymentInfo`, `Search`, `SubmitApplication`) are also rejected, these constraints are live-verified against Graph API v25.0 and enforced at Zernio's request boundary.
</Callout>

### Attribution window & test mode

Meta's attribution window is **7 days from click**. If the customer's `ctwa_clid` was captured more than 7 days ago, the event still posts but won't attribute.

Pass `testCode: "TEST12345"` at the request root to route events to the Test Events tab in Meta Events Manager without affecting production dataset data.

### Resolving the conversation

You can identify the originating conversation either way:
- `conversationId`, preferred. The Zernio Conversation `_id` returned by [list conversations](/messages/list-inbox-conversations).
- `phoneE164`, fallback. Digits only, no `+`. The handler picks the most recent CTWA-attributed conversation for that phone on the supplied account.

If the resolved conversation has no captured `ctwa_clid`, the request returns `422`, there's nothing to attribute (the conversation didn't originate from a CTWA ad, or pre-dates Zernio's capture).

---

# Flows

Build interactive WhatsApp Flows: forms, surveys, and booking experiences

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Flows

WhatsApp Flows let you build native interactive forms, surveys, and booking experiences inside WhatsApp. Flows are created in DRAFT status, populated with a Flow JSON definition, then published for sending. Published flows are immutable -- to update, create a new flow (optionally cloning the old one).

### Create and Publish a Flow

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Step 1: Create a flow
const { data } = await zernio.whatsappflows.createWhatsAppFlow({
  body: {
    accountId: 'YOUR_WHATSAPP_ACCOUNT_ID',
    name: 'lead_capture_form',
    categories: ['LEAD_GENERATION']
  }
});
const flowId = data.flow.id;

// Step 2: Upload the Flow JSON
await zernio.whatsappflows.uploadWhatsAppFlowJson({
  path: { flowId },
  body: {
    accountId: 'YOUR_WHATSAPP_ACCOUNT_ID',
    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}' } } }
          ]
        }
      }]
    }
  }
});

// Step 3: Publish (irreversible)
await zernio.whatsappflows.publishWhatsAppFlow({
  path: { flowId },
  body: { accountId: 'YOUR_WHATSAPP_ACCOUNT_ID' }
});
```
</Tab>
<Tab value="Python">
```python
# Step 1: Create a flow
response = client.whatsapp_flows.create_whats_app_flow(
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    name='lead_capture_form',
    categories=['LEAD_GENERATION']
)
flow_id = response.flow.id

# Step 2: Upload the Flow JSON
client.whatsapp_flows.upload_whats_app_flow_json(
    flow_id=flow_id,
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    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}'}}}
                ]
            }
        }]
    }
)

# Step 3: Publish (irreversible)
client.whatsapp_flows.publish_whats_app_flow(
    flow_id=flow_id,
    account_id='YOUR_WHATSAPP_ACCOUNT_ID'
)
```
</Tab>
<Tab value="curl">
```bash
# Step 1: Create a flow
FLOW_ID=$(curl -s -X POST https://zernio.com/api/v1/whatsapp/flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_WHATSAPP_ACCOUNT_ID",
    "name": "lead_capture_form",
    "categories": ["LEAD_GENERATION"]
  }' | jq -r '.flow.id')

# Step 2: Upload the Flow JSON
curl -X PUT "https://zernio.com/api/v1/whatsapp/flows/$FLOW_ID/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_WHATSAPP_ACCOUNT_ID",
    "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}"}}}
          ]
        }
      }]
    }
  }'

# Step 3: Publish (irreversible)
curl -X POST "https://zernio.com/api/v1/whatsapp/flows/$FLOW_ID/publish" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "YOUR_WHATSAPP_ACCOUNT_ID"}'
```
</Tab>
</Tabs>

### Preview a Flow

Get a public web-preview URL that renders the flow (drafts included) so you can visualize it before publishing. The link works without login and can be embedded as an iframe or shared with stakeholders. It is reused across calls (valid ~30 days); pass `invalidate: true` to mint a fresh one (the previous link stops working).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappflows.getWhatsAppFlowPreview({
  path: { flowId },
  query: { accountId: 'YOUR_WHATSAPP_ACCOUNT_ID' }
});
console.log(data.preview_url); // embed as <iframe src="...&interactive=true" />
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp_flows.get_whats_app_flow_preview(
    flow_id=flow_id,
    account_id='YOUR_WHATSAPP_ACCOUNT_ID'
)
print(response.preview_url)
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/flows/$FLOW_ID/preview?accountId=YOUR_WHATSAPP_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

### Version a Flow

A published flow is immutable, so the way to iterate is to clone it into a new draft. There are two distinct intents:

- **New version** -- a clone that stays in the original flow's version lineage, auto-numbered. Pass `cloneFlowId` plus `asVersion: true`. The list and create responses carry `version` + `lineageId`, and the full chain is available via the versions endpoint.
- **Clone** -- an independent duplicate with its own fresh lineage (version 1). Pass `cloneFlowId` only.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// New version of a published flow (stays in the same lineage)
const { data } = await zernio.whatsappflows.createWhatsAppFlow({
  body: {
    accountId: 'YOUR_WHATSAPP_ACCOUNT_ID',
    name: 'lead_capture_form',
    categories: ['LEAD_GENERATION'],
    cloneFlowId: 'PUBLISHED_FLOW_ID',
    asVersion: true
  }
});
console.log(`Created v${data.flow.version} (draft)`);

// Inspect the full version history (newest first)
const { data: history } = await zernio.whatsappflows.listWhatsAppFlowVersions({
  path: { flowId: data.flow.id },
  query: { accountId: 'YOUR_WHATSAPP_ACCOUNT_ID' }
});
history.versions.forEach(v => console.log(`v${v.version} - ${v.status}`));
```
</Tab>
<Tab value="Python">
```python
# New version of a published flow (stays in the same lineage)
response = client.whatsapp_flows.create_whats_app_flow(
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    name='lead_capture_form',
    categories=['LEAD_GENERATION'],
    clone_flow_id='PUBLISHED_FLOW_ID',
    as_version=True
)
print(f"Created v{response.flow.version} (draft)")

# Inspect the full version history (newest first)
history = client.whatsapp_flows.list_whats_app_flow_versions(
    flow_id=response.flow.id,
    account_id='YOUR_WHATSAPP_ACCOUNT_ID'
)
for v in history.versions:
    print(f"v{v.version} - {v.status}")
```
</Tab>
<Tab value="curl">
```bash
# New version of a published flow (stays in the same lineage)
curl -X POST https://zernio.com/api/v1/whatsapp/flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_WHATSAPP_ACCOUNT_ID",
    "name": "lead_capture_form",
    "categories": ["LEAD_GENERATION"],
    "cloneFlowId": "PUBLISHED_FLOW_ID",
    "asVersion": true
  }'

# Version history (newest first)
curl "https://zernio.com/api/v1/whatsapp/flows/$FLOW_ID/versions?accountId=YOUR_WHATSAPP_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

<Callout>
Version history is tracked by Zernio (Meta has no native flow versioning). Omit `asVersion` to get an independent clone instead of a new version. A flow that was never cloned reports as `version: 1` of its own lineage.
</Callout>

### Read Flow Responses

When a customer completes a flow, their submission arrives as an `nfm_reply` webhook. List those submissions per flow without touching the inbox:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappflows.listWhatsAppFlowResponses({
  query: { accountId: 'YOUR_WHATSAPP_ACCOUNT_ID', flowId: 'YOUR_FLOW_ID' }
});
data.responses.forEach(r => {
  console.log(`${r.from} @ ${r.receivedAt}:`, r.data); // r.data = submitted fields
});
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp_flows.list_whats_app_flow_responses(
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    flow_id='YOUR_FLOW_ID'
)
for r in response.responses:
    print(f"{r.from_} @ {r.received_at}:", r.data)  # r.data = submitted fields
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/flow-responses?accountId=YOUR_WHATSAPP_ACCOUNT_ID&flowId=YOUR_FLOW_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

<Callout>
Per-flow scoping works because Zernio encodes the flow id into the `flow_token` it auto-generates at send time (`<flowId>:<uuid>`), and that token round-trips through Meta inside the response. If you send a flow with your own custom `flow_token`, those responses won't be attributed to a flow (they still arrive via webhook). Only flows sent after this token convention shipped are attributable.
</Callout>

### Flow Lifecycle

| Status | Description |
|--------|-------------|
| `DRAFT` | Editable. Upload/update JSON, change name and categories. |
| `PUBLISHED` | Immutable. Can be sent to users. To update, create a new version via `cloneFlowId` + `asVersion`. |
| `DEPRECATED` | No longer sendable. |
| `BLOCKED` | Blocked by Meta for policy violations. |
| `THROTTLED` | Temporarily rate-limited by Meta. |

### Flow Categories

`SIGN_UP`, `SIGN_IN`, `APPOINTMENT_BOOKING`, `LEAD_GENERATION`, `CONTACT_US`, `CUSTOMER_SUPPORT`, `SURVEY`, `OTHER`

<Callout type="warn">
Publishing a flow is **irreversible**. Once published, the flow and its JSON cannot be modified. To make changes, create a [new version](#version-a-flow) (`cloneFlowId` + `asVersion: true`) which copies the published flow into a fresh draft you can edit and publish.
</Callout>

See [WhatsApp Flows API Reference](/whatsapp-flows/list-whatsapp-flows) for all endpoints.

---

# Group Chats

Create and manage WhatsApp group chats, participants, and invite links

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Group Chats

Create and manage WhatsApp group conversations directly from the API. Groups appear in the Inbox alongside individual conversations, and you can send messages to groups using the same messaging endpoints.

<Callout type="warn">
The Groups API is **not supported on phone numbers connected via [Coexistence](/platforms/whatsapp/connection#whatsapp-business-app-coexistence)** (Cloud API + WhatsApp Business app on the same number). Meta disables group create, list, and management endpoints for coexistence and Multi-solution Conversations setups. To use the Groups API, connect a number in Cloud API-only mode.
</Callout>

**How to tell if a number is in Coexistence**

- If the same phone number is still active in the WhatsApp Business app on a phone **and** connected to Zernio at the same time, it's Coexistence.
- You can also check in [Meta Business Suite](https://business.facebook.com) under WhatsApp Accounts > Phone Numbers. Numbers running Coexistence keep the mobile app registration active alongside the Cloud API.

**Migrating a Coexistence number to Cloud API-only**

Meta does not expose an API to flip an existing number out of Coexistence. The business has to disconnect from the WhatsApp Business app (Settings > Account > Business Platform > Disconnect on the phone). Once disconnected, Zernio deactivates the account automatically. Reconnect the number via Embedded Signup or [Headless Credentials](/platforms/whatsapp/connection#option-2-headless-credentials-no-browser) without choosing the "existing WA Business app account" option, and the Groups API will be available.

<Callout type="info">
These are actual WhatsApp group chats on the platform, not contact groups used for broadcast targeting (which are at `/v1/whatsapp/groups`).
</Callout>

### Create a Group

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsapp.createWhatsAppGroupChat({
  body: {
    accountId: 'YOUR_WHATSAPP_ACCOUNT_ID',
    subject: 'Customer Support Team',
    description: 'Internal support coordination',
    joinApprovalMode: 'approval_required'
  }
});
console.log('Group created:', data.group.groupId);
console.log('Invite link:', data.group.inviteLink);
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp.create_whats_app_group_chat(
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    subject='Customer Support Team',
    description='Internal support coordination',
    join_approval_mode='approval_required'
)
print(f"Group created: {response.group.group_id}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/whatsapp/wa-groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_WHATSAPP_ACCOUNT_ID",
    "subject": "Customer Support Team",
    "description": "Internal support coordination",
    "joinApprovalMode": "approval_required"
  }'
```
</Tab>
</Tabs>

### List Active Groups

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsapp.listWhatsAppGroupChats({
  query: { accountId: 'YOUR_WHATSAPP_ACCOUNT_ID', limit: 50 }
});
data.groups.forEach(g => console.log(`${g.subject} (${g.id})`));
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp.list_whats_app_group_chats(
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    limit=50
)
for g in response.groups:
    print(f"{g.subject} ({g.id})")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/wa-groups?accountId=YOUR_WHATSAPP_ACCOUNT_ID&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

### Manage Participants

Add up to 8 participants per request, or remove participants from a group:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Add participants
await zernio.whatsapp.addWhatsAppGroupParticipants({
  path: { groupId: 'GROUP_ID' },
  query: { accountId: 'YOUR_WHATSAPP_ACCOUNT_ID' },
  body: { phoneNumbers: ['+1234567890', '+0987654321'] }
});

// Remove participants
await zernio.whatsapp.removeWhatsAppGroupParticipants({
  path: { groupId: 'GROUP_ID' },
  query: { accountId: 'YOUR_WHATSAPP_ACCOUNT_ID' },
  body: { phoneNumbers: ['+1234567890'] }
});
```
</Tab>
<Tab value="Python">
```python
# Add participants
client.whatsapp.add_whats_app_group_participants(
    group_id='GROUP_ID',
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    phone_numbers=['+1234567890', '+0987654321']
)

# Remove participants
client.whatsapp.remove_whats_app_group_participants(
    group_id='GROUP_ID',
    account_id='YOUR_WHATSAPP_ACCOUNT_ID',
    phone_numbers=['+1234567890']
)
```
</Tab>
<Tab value="curl">
```bash
# Add participants
curl -X POST "https://zernio.com/api/v1/whatsapp/wa-groups/GROUP_ID/participants?accountId=YOUR_WHATSAPP_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumbers": ["+1234567890", "+0987654321"]}'

# Remove participants
curl -X DELETE "https://zernio.com/api/v1/whatsapp/wa-groups/GROUP_ID/participants?accountId=YOUR_WHATSAPP_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumbers": ["+1234567890"]}'
```
</Tab>
</Tabs>

### Invite Links & Join Requests

Generate invite links for your group and manage pending join requests:

<Tabs items={['Node.js', 'curl']}>
<Tab value="Node.js">
```typescript
// Create invite link
const { data } = await zernio.whatsapp.createWhatsAppGroupInviteLink({
  path: { groupId: 'GROUP_ID' },
  query: { accountId: 'YOUR_WHATSAPP_ACCOUNT_ID' }
});
console.log('Invite link:', data.inviteLink);

// List pending join requests (for groups with approval_required)
const { data: requests } = await zernio.whatsapp.listWhatsAppGroupJoinRequests({
  path: { groupId: 'GROUP_ID' },
  query: { accountId: 'YOUR_WHATSAPP_ACCOUNT_ID' }
});

// Approve join requests
await zernio.whatsapp.approveWhatsAppGroupJoinRequests({
  path: { groupId: 'GROUP_ID' },
  query: { accountId: 'YOUR_WHATSAPP_ACCOUNT_ID' },
  body: { phoneNumbers: ['+1234567890'] }
});
```
</Tab>
<Tab value="curl">
```bash
# Create invite link
curl -X POST "https://zernio.com/api/v1/whatsapp/wa-groups/GROUP_ID/invite-link?accountId=YOUR_WHATSAPP_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# List pending join requests
curl "https://zernio.com/api/v1/whatsapp/wa-groups/GROUP_ID/join-requests?accountId=YOUR_WHATSAPP_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Approve join requests
curl -X POST "https://zernio.com/api/v1/whatsapp/wa-groups/GROUP_ID/join-requests?accountId=YOUR_WHATSAPP_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumbers": ["+1234567890"]}'
```
</Tab>
</Tabs>

### Sending Messages to Groups

Send messages to a group using the standard Inbox messaging API. Group conversations are created automatically when a group message is received, and you can reply using the conversation ID:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// Send a text message to a group conversation
await zernio.messages.sendInboxMessage({
  path: { conversationId: 'CONVERSATION_ID' },
  body: {
    accountId: 'YOUR_ACCOUNT_ID',
    message: 'Hello team!',
  },
});
```
</Tab>
<Tab value="Python">
```python
client.messages.send_inbox_message(
    conversation_id="CONVERSATION_ID",
    account_id="YOUR_ACCOUNT_ID",
    message="Hello team!",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/inbox/conversations/CONVERSATION_ID/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_ACCOUNT_ID",
    "message": "Hello team!"
  }'
```
</Tab>
</Tabs>

<Callout type="warn">
Group messages from all participants appear in the Inbox. Each group has its own conversation thread identified by the group ID.
</Callout>

---

# Inbox

Receive and reply to WhatsApp direct messages

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Inbox

> **Included** — Inbox (DMs, comments, reviews) is bundled with every paid account on the [Usage plan](/pricing).

All WhatsApp features (broadcasts, sequences, DM conversations) are included with the Usage plan. WhatsApp DM conversations are available through the [unified Inbox API](/messages/list-inbox-conversations), which aggregates conversations across all supported platforms.

### Direct Messages

| Feature | Supported |
|---------|-----------|
| List conversations | Yes |
| Fetch messages | Yes |
| Send text messages | Yes |
| Send attachments | Yes (images, videos, documents, audio) |
| Send voice notes | Yes — pass `voiceNote: true` on an audio attachment to render as a true voice message (waveform, autoplay, profile-picture bubble). The file must be `.ogg` encoded with the OPUS codec (mono); dashboard mic recordings are transcoded server-side. Omitting the flag sends as a basic audio attachment (still shows a microphone icon when the codec is Opus, but without the voice-message UI). |
| Send interactive messages | Yes (reply buttons, list, CTA URL, flow) via the `interactive` / `buttons` fields |
| Send location & contact cards | Yes via the `location` / `contacts` fields |
| Reply to a specific message | Yes via `replyTo` (the quoted message's `platformMessageId`) |
| React to a message | Yes (emoji) via [Add message reaction](/messages/add-message-reaction) |
| Typing indicator | Yes via [Send typing indicator](/messages/send-typing-indicator) |
| Archive/unarchive | Yes |

### Attachment Support

| Type | Supported | Max Size |
|------|-----------|----------|
| Images | Yes | 5 MB |
| Videos | Yes | 16 MB |
| Documents | Yes | 100 MB |
| Audio | Yes | 16 MB |

### Webhooks

WhatsApp emits the full set of message + delivery lifecycle webhooks:

| Event | When it fires |
|-------|---------------|
| `message.received` | New incoming WhatsApp message |
| `message.sent` | Outgoing message is sent |
| `message.delivered` | Outgoing message is delivered to the recipient |
| `message.read` | Recipient reads an outgoing message |
| `message.failed` | Outgoing message fails to deliver, the payload `error` object carries the Cloud API error code (e.g. `131026` recipient phone not reachable) |
| `message.deleted` | The business deletes a previously-sent outgoing message via `DELETE /v1/inbox/conversations/{conversationId}/messages/{messageId}` |
| `reaction.received` | A participant adds or removes an emoji reaction. `reaction.emoji` is empty on removal (the Cloud API does not report which emoji was removed) |

Subscribe via [Create webhook settings](/webhooks/create-webhook-settings). See the [Webhooks](/webhooks) page for payload details.

**Note:** WhatsApp Cloud API does not expose incoming-message edits or recipient-side unsends, so `message.edited` and incoming-side `message.deleted` are not emitted. These are platform limitations.

### Notes

- **24-hour window**: Free-form messages only within 24 hours of customer's last message
- **Templates**: Required to initiate or re-initiate conversations outside the window
- **Delivery tracking**: Messages have sent/delivered/read status updates via webhooks

See [Inbox API Reference](/messages/list-inbox-conversations) for endpoint details.

---

# WhatsApp

Send WhatsApp broadcasts, manage templates, contacts, and conversations with Zernio API

import { Callout } from 'fumadocs-ui/components/callout';
import { Cards, Card } from 'fumadocs-ui/components/card';
import { PlatformCapabilities } from '@/components/platform-capabilities';

## Quick Reference

<PlatformCapabilities rows={[
  { property: 'Message types', value: 'Text, Template, Image, Video, Document, Audio' },
  { property: 'Template required', value: 'Yes (outside 24h conversation window)' },
  { property: 'Image formats', value: 'JPEG, PNG' },
  { property: 'Image max size', value: '5 MB' },
  { property: 'Video formats', value: 'MP4, 3GPP' },
  { property: 'Video max size', value: '16 MB' },
  { property: 'Document formats', value: 'PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT' },
  { property: 'Document max size', value: '100 MB' },
  { property: 'Audio formats', value: 'MP3, OGG, AMR, AAC' },
  { property: 'Audio max size', value: '16 MB' },
  { property: 'Scheduling', value: 'No (use broadcasts with scheduling)' },
  { property: 'Inbox (DMs)', value: 'Yes' },
  { property: 'Inbox (Comments)', value: 'No' },
  { property: 'Group Chats', value: <>Yes, (Usage plan) (non-coexistence numbers only, see <a href="/platforms/whatsapp/groups">Group Chats</a>)</> },
  { property: 'Flows', value: 'Yes (interactive forms, surveys, booking)' },
  { property: 'Calling', value: <>Yes, (Usage plan) (inbound + outbound voice, see <a href="/platforms/whatsapp/calling">Calling</a>)</> },
  { property: 'Analytics', value: 'No' },
]} />

## Before You Start

<Callout type="warn">
WhatsApp requires a **WhatsApp Business Account (WABA)**. This is different from a regular WhatsApp account.

Requirements:
- A Meta Business account (business.facebook.com)
- WhatsApp Business Account (created during the connection flow)
- At least one phone number registered with the WABA
- Approved message templates for initiating conversations (Meta reviews these)
- **24-hour rule:** You can only send free-form messages within 24 hours of the customer's last message. Outside that window, you must use an approved template.
</Callout>

## In This Section

<Cards>
  <Card title="Connection & Setup" href="/platforms/whatsapp/connection" description="Connect a WABA via redirect, headless credentials, or the dashboard" />
  <Card title="Broadcasts" href="/platforms/whatsapp/broadcasts" description="Send template messages to many recipients with per-recipient variables" />
  <Card title="Templates" href="/platforms/whatsapp/templates" description="Create, list, and import Meta-approved templates" />
  <Card title="Contacts & Profile" href="/platforms/whatsapp/contacts" description="Manage your contact list and business profile" />
  <Card title="Phone Numbers" href="/platforms/whatsapp/phone-numbers" description="Purchase, verify, KYC, and release numbers" />
  <Card title="Calling" href="/platforms/whatsapp/calling" description="Inbound and outbound WhatsApp voice calling" />
  <Card title="Group Chats" href="/platforms/whatsapp/groups" description="Create and manage groups, participants, and invite links" />
  <Card title="Inbox" href="/platforms/whatsapp/inbox" description="Receive and reply to WhatsApp direct messages" />
  <Card title="Flows" href="/platforms/whatsapp/flows" description="Build interactive forms, surveys, and booking experiences" />
  <Card title="Click-to-WhatsApp Ads" href="/platforms/whatsapp/ctwa" description="Capture CTWA clicks and forward conversions to Meta" />
  <Card title="Pricing & Costs" href="/platforms/whatsapp/pricing" description="What Zernio and Meta each charge" />
  <Card title="Media & Limits" href="/platforms/whatsapp/reference" description="Media requirements, analytics, and common errors" />
</Cards>

## Related Endpoints

- [Broadcasts](/broadcasts/create-broadcast) - Create and send WhatsApp broadcast campaigns
- [Contacts](/contacts/list-contacts) - Manage your WhatsApp contact list
- [Templates](/whatsapp/get-whatsapp-templates) - Manage Meta-approved WhatsApp templates
- [Group Chats](/whatsapp/list-whatsapp-group-chats) - Create and manage WhatsApp group conversations
- [Flows](/whatsapp-flows/list-whatsapp-flows) - Build interactive forms, surveys, and booking experiences
- [Connect via Credentials](/connect/connect-whatsapp-credentials) - Headless WhatsApp connection
- [Inbox](/messages/list-inbox-conversations) - View and manage WhatsApp DM conversations (included with the Usage plan)

---

# Phone Numbers

Purchase, verify, KYC, and release WhatsApp phone numbers for your WABA

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Phone Numbers

Manage WhatsApp phone numbers: purchase, verify, and release numbers for your WABA. Numbers are available in 50+ countries. US numbers provision instantly; regulated countries require a one-time identity-verification (KYC) form first, after which the number activates within a few business days. Use the [`whatsapp.number.activated`](/webhooks#whatsappnumberactivated) webhook to know when a regulated number is ready instead of polling.

### List Available Countries

Returns the countries you can buy a number in, each with its monthly price (cents), whether it needs KYC, and whether outbound calling is available. Use this to drive a country picker before [purchasing](/platforms/whatsapp/phone-numbers#purchase-a-number).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappphonenumbers.listWhatsAppNumberCountries();
data.countries.forEach(c =>
  console.log(`${c.code}: $${(c.monthlyCents / 100).toFixed(2)}/mo${c.needsKyc ? ' (KYC)' : ''}`)
);
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp_phone_numbers.list_whats_app_number_countries()
for c in response.countries:
    kyc = ' (KYC)' if c.needs_kyc else ''
    print(f"{c.code}: ${c.monthly_cents / 100:.2f}/mo{kyc}")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/phone-numbers/countries" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

#### Countries & pricing

Price is per number, per month, billed by the active day and separate from Meta's usage fees. Countries marked **†** provision instantly; all others require a one-time [identity-verification (KYC) form](#regulated-countries-kyc) and activate within 1-3 business days. The [`countries`](#list-available-countries) endpoint is the live source of truth.

| Price / mo | Countries |
|---|---|
| **$2** | United States †, Canada †, U.S. Virgin Islands †, Ireland, Austria, Belgium, Czechia, Finland, France, Germany, Greece, Hungary, Italy, Lithuania, Luxembourg, New Zealand, Norway, Portugal, Romania, Slovakia, Spain, Switzerland, United Kingdom |
| **$3** | Puerto Rico †, Netherlands †, Brazil, Croatia, Estonia |
| **$4** | Israel †, Latvia |
| **$5** | Cyprus, Mexico, Singapore |
| **$6** | Iceland †, Australia |
| **$8** | Denmark †, Chile, Dominican Republic, Réunion, Turkey |
| **$10** | El Salvador †, Guadeloupe, Martinique, Panama, Poland, South Africa, Sweden, French Guiana |
| **$12** | Costa Rica |
| **$15** | Georgia, Thailand |
| **$20** | Colombia †, Indonesia |

<Callout type="info">
**†** Provisions instantly. Every other country requires the one-time KYC form and a short regulatory review. Country codes are ISO-2 (for example `US`, `GB`, `DE`); the [`countries`](#list-available-countries) endpoint returns each code with its current price.
</Callout>

### List Your Numbers

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappphonenumbers.getWhatsAppPhoneNumbers();
data.numbers.forEach(n => console.log(`${n.phoneNumber} (${n.status})`));
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp_phone_numbers.get_whats_app_phone_numbers()
for n in response.numbers:
    print(f"{n.phone_number} ({n.status})")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/phone-numbers" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

### Number Status

A live snapshot of a connected number, straight from Meta: display name + approval, quality rating, messaging-limit tier, throughput, official-business badge, connection status, and the owning Business Account's verification status. Useful for monitoring deliverability and limits.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsapp.getWhatsAppNumberInfo({
  query: { accountId: 'YOUR_ACCOUNT_ID' }
});
console.log(data.phone.quality_rating, data.phone.messaging_limit_tier);
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp.get_whats_app_number_info(account_id='YOUR_ACCOUNT_ID')
print(response.phone.quality_rating, response.phone.messaging_limit_tier)
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/number-info?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

### Purchase a Number

Pass `country` (ISO-2, default `US`) to choose the country. For instant countries the number provisions inline. For a regulated country the response is `status: "kyc_required"` with a `kycUrl`. Collect the [KYC form](#regulated-countries-kyc) and submit it before the number is ordered.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappphonenumbers.purchaseWhatsAppPhoneNumber({
  body: { profileId: 'YOUR_PROFILE_ID', country: 'GB' }
});
if (data.checkoutUrl) {
  console.log('Complete payment:', data.checkoutUrl); // first number: Stripe checkout
} else if (data.status === 'kyc_required') {
  console.log('Regulated country, collect KYC:', data.kycUrl);
} else {
  console.log('Number provisioned:', data.phoneNumber.phoneNumber);
}
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp_phone_numbers.purchase_whats_app_phone_number(
    profile_id='YOUR_PROFILE_ID', country='GB'
)
if getattr(response, 'checkout_url', None):
    print(f"Complete payment: {response.checkout_url}")  # first number: Stripe checkout
elif getattr(response, 'status', None) == 'kyc_required':
    print(f"Regulated country, collect KYC: {response.kyc_url}")
else:
    print(f"Number provisioned: {response.phone_number.phone_number}")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/whatsapp/phone-numbers/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profileId": "YOUR_PROFILE_ID", "country": "GB"}'
```
</Tab>
</Tabs>

**Duplicate protection.** Retrying a purchase is safe if you send a `purchaseIntentId` (any string up to 100 chars, one per intended purchase): a repeat with the same key returns `status: "already_purchased"` with the existing number instead of buying a second one. Independently, any second purchase within 10 minutes of a previous one returns `409` with `code: "PURCHASE_VELOCITY"`; pass `allowMultiple: true` to confirm it is intentional (for example, bulk provisioning).

### Regulated Countries (KYC)

Regulated (non-US) countries require the registrant's identity details before the number is ordered. Before collecting anything, check availability for the country (`checkWhatsAppNumberAvailability`, `GET /availability?country=XX`). It returns whether there is deliverable inventory and an `addressConstraint`: `geo` means the registrant's address must be in one of the returned `areas` (a few countries stock numbers tied to a specific city), `country` means any in-country address works, `none` means no address is required. Checking first avoids the worst case: a submission that passes review but can never be assigned a number because the address is in the wrong area.

Then fetch the form for the country (`getWhatsAppNumberKycForm`): it returns the exact fields that country requires (text fields, an address, and document uploads such as an ID or business registration), plus whether the owner already has a reusable, approved verification for that country.

Then submit the collected values, documents, and address (`submitWhatsAppNumberKyc`). Each document can be sent inline (base64) or as a `documentId` from a prior upload. For an ID-card requirement, carriers usually need BOTH sides: combine the front and back into a single file before uploading (a one-sided ID is a common decline reason). The order goes to regulatory review and the number activates within 1-3 business days. Some countries (for example, Australia) also return a `verification_required` step: forward the `verificationUrl` to the end user to complete an ID check. Listen for [`whatsapp.number.activated`](/webhooks#whatsappnumberactivated) / [`whatsapp.number.declined`](/webhooks#whatsappnumberdeclined) to know the outcome. If the regulator needs more information mid-review, [`whatsapp.number.action_required`](/webhooks#whatsappnumberaction_required) fires with the request, and the submitter is emailed; the missing details can be provided from the dashboard and the review resumes automatically.

<Tabs items={['curl']}>
<Tab value="curl">
```bash
# 1. Get the KYC form for the country
curl "https://zernio.com/api/v1/whatsapp/phone-numbers/kyc?country=GB&profileId=YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Submit the collected details (documents are base64-encoded)
curl -X POST "https://zernio.com/api/v1/whatsapp/phone-numbers/kyc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "YOUR_PROFILE_ID",
    "country": "GB",
    "values": { "REQUIREMENT_ID": "Acme Ltd | Jane Doe | +44..." },
    "documents": [{ "requirementId": "REQUIREMENT_ID", "filename": "id.png", "base64": "..." }],
    "address": {
      "requirementId": "REQUIREMENT_ID", "country_code": "GB",
      "street_address": "10 Downing Street", "locality": "London",
      "administrative_area": "London", "postal_code": "SW1A 2AA"
    }
  }'
```
</Tab>
</Tabs>

<Callout type="info">
The published SDKs don't yet expose dedicated `getWhatsAppNumberKycForm` / `submitWhatsAppNumberKyc` methods. Use raw HTTP (above) until the next SDK regen catches up. PII (ID documents, address) streams straight to our number provider in-request; Zernio never stores the document bytes.
</Callout>

### Fix a Declined Number

If a regulated number is declined, you do not start over: fix only what the reviewer flagged and re-submit the same number. A declined number stays in the list under `status: "pending_regulatory"` with a `regulatoryDeclineReason`. Fetch the remediation form (`getWhatsAppNumberRemediation`, `GET /{id}/remediate`) — it returns ONLY the requirements that were declined — then re-submit the corrected values to the same endpoint (`remediateWhatsAppNumber`, `POST /{id}/remediate`). The number goes back to review on the same record; you keep its place in the queue.

<Tabs items={['curl']}>
<Tab value="curl">
```bash
# 1. Get just the declined requirements for the number
curl "https://zernio.com/api/v1/whatsapp/phone-numbers/PHONE_NUMBER_ID/remediate" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Re-submit the corrected fields/documents (same shape as the KYC submit)
curl -X POST "https://zernio.com/api/v1/whatsapp/phone-numbers/PHONE_NUMBER_ID/remediate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "values": { "REQUIREMENT_ID": "corrected value" },
    "documents": [{ "requirementId": "REQUIREMENT_ID", "filename": "id.png", "base64": "..." }]
  }'
```
</Tab>
</Tabs>

### Verify a Number

After purchasing, verify the number with Meta by requesting an OTP and submitting it:

<Callout type="info">
The published Node SDK (`@zernio/node`) and Python SDK (`zernio-sdk`) do not yet expose dedicated methods for `requestWhatsAppVerificationCode` / `verifyWhatsAppPhoneNumber`. Use raw HTTP requests until the next SDK regen catches up.
</Callout>

<Tabs items={['curl']}>
<Tab value="curl">
```bash
# Step 1: Request verification code
curl -X POST "https://zernio.com/api/v1/whatsapp/phone-numbers/PHONE_NUMBER_ID/request-code" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "SMS"}'

# Step 2: Submit the code
curl -X POST "https://zernio.com/api/v1/whatsapp/phone-numbers/PHONE_NUMBER_ID/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'
```
</Tab>
</Tabs>

---

# Pricing & Costs

What Zernio and Meta each charge for WhatsApp

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Pricing & Costs

WhatsApp has two separate billing components: Zernio platform fees and Meta messaging fees.

### What Zernio charges

All WhatsApp features (broadcasts, sequences, DM conversations) are included with the [Usage plan](/pricing). The Usage plan has no post limits or profile limits.

Two WhatsApp items are billed separately on top of the plan:

| Item | Cost |
|---|---|
| Dedicated number | From $2/mo per active number, which we provision for you. US is $2/mo; other countries are priced per country (typically $2 to $25/mo) and shown before purchase. Billed per number per active day. |
| Calling, inbound | Free |
| Calling, outbound | Carrier connection billed by Zernio at cost; Meta's per-minute rate is billed by Meta directly to your WABA (varies by country; ~$0.015/min in the US) |

Calling involves two separate bills. Meta charges its per-minute outbound rate (varies by destination country) directly to your WhatsApp Business Account, the same way it bills template messages. Zernio bills only the carrier connection, plus an optional recording surcharge, at cost with zero markup. Inbound calls are always free. See [Calling](/platforms/whatsapp/calling) for setup.

### What Meta charges

Meta charges **per delivered template message** and **per minute of outbound calling**. These fees are billed directly to your WhatsApp Business Account, not through Zernio.

| Message type | Cost |
|---|---|
| Template messages (marketing, utility, authentication) | Charged per delivery (varies by category + recipient country) |
| Non-template messages (within 24h customer service window) | Free |
| Utility templates sent within customer service window | Free |

Rates depend on the template category and the recipient's country code. See [Meta's pricing page](https://developers.facebook.com/docs/whatsapp/pricing) and [rate cards by country](https://developers.facebook.com/docs/whatsapp/pricing#rates) for current rates.

<Callout type="warn">
You must set up a payment method in your WhatsApp Business Account through [Meta Business Suite](https://business.facebook.com). Without a valid payment method, Meta will block template message delivery once your free tier is exhausted.
</Callout>

### How billing works

Zernio and Meta bill separately. Your Zernio subscription covers platform access (API, broadcasts, contacts, templates, inbox). Meta bills your credit card directly through your WABA for message delivery fees. Zernio does not charge or mark up Meta's messaging fees.

### Sandbox vs production numbers

**Sandbox number** - When you first connect via Embedded Signup, you can test with Meta's sandbox. Sandbox numbers have limited sending (up to 250 unique contacts/day) and messages are tagged as test.

**Dedicated number** - A production number purchased through Zernio, available on all plans. US numbers are pre-verified and provisioned instantly; numbers in other countries are priced per country and, where the country regulates them, require a one-time KYC form (and sometimes an end-user ID check) before activation. The first number purchase requires a small deposit via Stripe that goes toward your account credits.

**Bring your own number** - Connect via [Headless Credentials](/platforms/whatsapp/connection#option-2-headless-credentials-no-browser) using your existing Meta System User token and phone number.

---

# Media & Limits

Media requirements, analytics support, and common errors

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Media Requirements

### Images

| Property | Requirement |
|----------|-------------|
| **Formats** | JPEG, PNG |
| **Max file size** | 5 MB |

### Videos

| Property | Requirement |
|----------|-------------|
| **Formats** | MP4, 3GPP |
| **Max file size** | 16 MB |
| **Codec** | H.264 video, AAC audio |

### Documents

| Property | Requirement |
|----------|-------------|
| **Formats** | PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT |
| **Max file size** | 100 MB |

### Audio

| Property | Requirement |
|----------|-------------|
| **Formats** | MP3, OGG (with opus codec), AMR, AAC |
| **Max file size** | 16 MB |


## Analytics

WhatsApp does not provide post-level analytics through its API. Message delivery status (sent, delivered, read) is tracked per-recipient in broadcasts.

## What You Can't Do

- Send free-form messages outside the 24-hour conversation window (must use templates)
- Send messages to numbers without WhatsApp
- Use personal WhatsApp accounts (must be WhatsApp Business)
- Send more than 250 unique contacts/day on a new account (tier 0 limit, increases with usage)
- Schedule individual messages (use broadcasts with scheduling instead)
- Get per-message analytics (only delivery status)

## Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| "Template not found" (132001) | Template name or language code doesn't match | Verify the exact template name and language code (e.g., "en" not "en_US") |
| "Invalid phone number" (131021) | Recipient number format is incorrect or doesn't have WhatsApp | Use E.164 format with country code (e.g., +1234567890) |
| "Re-engagement required" (131026) | 24-hour conversation window expired | Send an approved template message to re-initiate |
| "Rate limit hit" (131047) | Too many messages sent too quickly | Reduce sending frequency, wait for rate limit to reset |
| "Media download failed" (131052) | WhatsApp can't fetch media from the URL | Ensure URL is publicly accessible with no auth required |
| "Not in allowed list" (131030) | Number not in Meta's sandbox test list | Add the number to your test recipients in Meta Business Suite |
| "Account locked" (131031) | Meta suspended the WhatsApp Business account | Contact Meta support to resolve |

---

# Sandbox

Test WhatsApp sending against a sandbox number before going to production

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Sandbox

Zernio runs a **shared WhatsApp sandbox number** every account can test against without purchasing or verifying their own number. Use it to validate message flows, bot replies, and webhook payloads end-to-end before going live.

| Property | Value |
|----------|-------|
| Shared number | One Zernio-owned WhatsApp number (returned by `GET /v1/whatsapp/phone-numbers` under `sandbox`) |
| Verification model | Reply-based: we send a verified template to your test phone, you reply, the session activates |
| Templates allowed | One, locked: `sandbox_start` (no merge fields) |
| Free-form text & interactive | Yes, within the 24h customer-service window after the user replies |
| Test phones per user | 1 (one active session at a time) |
| Daily caps per user | 50 messages / 5 distinct recipients (effectively 1) |
| Pending session TTL | 24 hours |
| Activated session TTL | 7 days |
| Billing | Free (no per-number charge, no message charge) |

<Callout type="info">
The sandbox is for testing only. To send to multiple recipients, sync templates from WhatsApp Manager, or run production traffic, [purchase a real WhatsApp number](#phone-numbers) instead.
</Callout>

### Why activation matters

Without ownership verification, anyone with a Zernio API key could fire the verified Meta template from `+1 202 908 7457` at any phone they typed. That would degrade the WABA's quality rating (shared across all users) and drain its messaging tier. Activation closes the abuse vector: only phones the user proved they control via a WhatsApp reply can be targeted from the sandbox.

### Step 1 — Discover the sandbox

The sandbox phone number, the SocialAccount id you need to send from, and the locked template name all come back from the standard phone-numbers endpoint:

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappphonenumbers.getWhatsAppPhoneNumbers();
if (!data.sandbox) throw new Error('Sandbox not configured on this environment');
const { accountId, phoneNumber, template } = data.sandbox;
// accountId → use as `accountId` in inbox compose calls
// phoneNumber → the sandbox MSISDN (display only)
// template   → { name: 'sandbox_start', language: 'en' }
```
</Tab>
<Tab value="Python">
```python
response = client.whatsappphonenumbers.get_whats_app_phone_numbers()
if not response.sandbox:
    raise Exception("Sandbox not configured on this environment")
account_id = response.sandbox.account_id
phone_number = response.sandbox.phone_number
template = response.sandbox.template  # { name, language }
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/phone-numbers" \
  -H "Authorization: Bearer YOUR_API_KEY"
# → { "numbers": [...], "sandbox": { "accountId": "...", "phoneNumber": "+12029087457", "template": { "name": "sandbox_start", "language": "en" } } }
```
</Tab>
</Tabs>

### Step 2 — Start activation for a test phone

Posting a phone creates a `pending` session and immediately fires the verified `sandbox_start` template **from the sandbox number to that phone**. The end user opens WhatsApp on their phone and replies to that message — any text reply (including tapping the "Reply and verify" quick-reply button) flips the session to `active`.

One phone per user: if you already have a pending or active session for a different phone, the request returns a 400 naming the existing phone so you know to revoke it first.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappsandbox.createWhatsAppSandboxSession({
  body: { phone: '+34688246216' }
});
console.log(data.session.id, data.session.status); // 'pending'
// Tell the user: "Check WhatsApp on +34 688 24 62 16 and reply to verify"
```
</Tab>
<Tab value="Python">
```python
response = client.whatsappsandbox.create_whats_app_sandbox_session(phone='+34688246216')
print(response.session.id, response.session.status)  # 'pending'
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/whatsapp/sandbox/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+34688246216"}'
```
</Tab>
</Tabs>

### Step 3 — Wait for the user to reply

Activation is automatic. You can poll the list endpoint, or — if you've configured webhooks — listen for the conversation events.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsappsandbox.listWhatsAppSandboxSessions();
const session = data.sessions[0];
if (session?.status === 'active') {
  console.log('Verified at', session.activatedAt);
}
```
</Tab>
<Tab value="Python">
```python
response = client.whatsappsandbox.list_whats_app_sandbox_sessions()
session = response.sessions[0] if response.sessions else None
if session and session.status == 'active':
    print('Verified at', session.activated_at)
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/sandbox/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

### Step 4 — Send to the activated phone

Once `active`, the phone is a normal WhatsApp conversation in the user's inbox. Send the locked template using the standard inbox compose endpoint, addressed at the sandbox account. The same template + activation gate applies — random phone numbers are rejected.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.inbox.createConversation({
  body: {
    accountId: sandbox.accountId,
    participantId: '34688246216',           // digits only, must match the activated phone
    templateName: sandbox.template.name,    // 'sandbox_start'
    templateLanguage: sandbox.template.language, // 'en'
    templateParams: []
  }
});
console.log('Conversation:', data.data.id);
```
</Tab>
<Tab value="Python">
```python
response = client.inbox.create_conversation(
    account_id=sandbox.account_id,
    participant_id='34688246216',
    template_name=sandbox.template.name,
    template_language=sandbox.template.language,
    template_params=[]
)
print('Conversation:', response.data.id)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/inbox/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "SANDBOX_ACCOUNT_ID",
    "participantId": "34688246216",
    "templateName": "sandbox_start",
    "templateLanguage": "en",
    "templateParams": []
  }'
```
</Tab>
</Tabs>

After the user replies, the 24h customer-service window opens — within that window you can send free-form text via `POST /v1/inbox/conversations/{conversationId}/messages` exactly like any other conversation.

### Replacing the activated phone

Activate a different phone by deleting the current session first, then creating a new one:

<Tabs items={['curl']}>
<Tab value="curl">
```bash
# 1. Revoke the existing session
curl -X DELETE "https://zernio.com/api/v1/whatsapp/sandbox/sessions/SESSION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Start activation for the new phone
curl -X POST "https://zernio.com/api/v1/whatsapp/sandbox/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+34999888777"}'
```
</Tab>
</Tabs>

### Common errors

| Error | Cause | Fix |
|-------|-------|-----|
| `invalid_field_value` with "This phone is not activated for sandbox sends" | The recipient phone has no active session for the calling user | Run the activation flow (Steps 2–3) for that phone first |
| `invalid_field_value` with "You can only test one phone at a time. Revoke +X first" | The user already has a session for a different phone | DELETE the existing session, then POST the new phone |
| `invalid_field_value` with "Cannot activate the sandbox number itself" | The phone passed is the sandbox MSISDN | Use a real, different WhatsApp number |
| `invalid_field_value` with "Could not send the activation message…" | Meta rejected the template send (number not on WhatsApp, paused WABA, etc.) — the underlying Meta message is included | Verify the phone is a WhatsApp account on a registered MSISDN |
| `rate_limited` | Hit the 50 messages / 5 recipients per 24h cap | Wait for the rolling window to free up, or use a paid number |
| 403 from any `/sandbox/*` endpoint | Inbox addon not enabled on the user's plan | Enable the Inbox addon |

---

# Templates

Create, list, and import Meta-approved WhatsApp message templates

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## Templates

WhatsApp templates are required for initiating conversations outside the 24-hour messaging window. They must be submitted to Meta for approval before use.

### List Templates

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsapp.getWhatsAppTemplates({
  query: { accountId: 'YOUR_ACCOUNT_ID' }
});
data.templates.forEach(t => console.log(`${t.name} (${t.status}) - ${t.language}`));
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp.get_whats_app_templates(
    account_id='YOUR_ACCOUNT_ID'
)
for t in response.templates:
    print(f"{t.name} ({t.status}) - {t.language}")
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/whatsapp/templates?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
</Tab>
</Tabs>

### Create a Template

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.whatsapp.createWhatsAppTemplate({
  body: {
    accountId: 'YOUR_ACCOUNT_ID',
    name: 'order_confirmation',
    category: 'UTILITY',
    language: 'en',
    components: [{ type: 'BODY', text: 'Hi {{1}}, your order {{2}} has been confirmed!' }]
  }
});
console.log(`Template created: ${data.template.name} (${data.template.status})`);
```
</Tab>
<Tab value="Python">
```python
response = client.whatsapp.create_whats_app_template(
    account_id='YOUR_ACCOUNT_ID',
    name='order_confirmation',
    category='UTILITY',
    language='en',
    components=[{'type': 'BODY', 'text': 'Hi {{1}}, your order {{2}} has been confirmed!'}]
)
print(f"Template created: {response.template.name} ({response.template.status})")
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/whatsapp/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_ACCOUNT_ID",
    "name": "order_confirmation",
    "category": "UTILITY",
    "language": "en",
    "components": [{"type": "BODY", "text": "Hi {{1}}, your order {{2}} has been confirmed!"}]
  }'
```
</Tab>
</Tabs>

<Callout type="info">
Templates are reviewed by Meta and can take up to 24 hours to be approved. Only approved templates can be used for sending messages.
</Callout>

### Import from the Template Library

Instead of writing a template, you can create one from [Meta's pre-approved Template Library](https://business.facebook.com/latest/whatsapp_manager/template_library) — these skip the review wait. Pass `library_template_name` instead of `components`.

Look the template up first to see its structure: a library template with **URL or PHONE_NUMBER buttons requires a matching `library_template_button_inputs` array** at create time (one entry per button, in order), or Meta rejects it with *"give the same number of button inputs to match the library buttons."* A library template usually exists in many languages — pass `language` to pick the right variant.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
// 1. Look up the library template (to see its buttons + the exact language)
const { data: lib } = await zernio.whatsapp.getWhatsAppLibraryTemplate({
  query: { accountId: 'YOUR_ACCOUNT_ID', name: 'account_creation_confirmation_3', language: 'en_US' }
});

// 2. Create it, supplying inputs for its URL / PHONE_NUMBER buttons
const { data } = await zernio.whatsapp.createWhatsAppTemplate({
  body: {
    accountId: 'YOUR_ACCOUNT_ID',
    name: 'account_creation_confirmation_3',
    category: 'UTILITY',
    language: lib.template.language, // use the library template's actual code
    library_template_name: 'account_creation_confirmation_3',
    library_template_button_inputs: [
      { type: 'URL', url: { base_url: 'https://your-site.com/account', url_suffix_example: 'https://your-site.com/account' } }
    ]
  }
});
```
</Tab>
<Tab value="Python">
```python
# 1. Look up the library template (to see its buttons + the exact language)
lib = client.whatsapp.get_whats_app_library_template(
    account_id='YOUR_ACCOUNT_ID', name='account_creation_confirmation_3', language='en_US'
)

# 2. Create it, supplying inputs for its URL / PHONE_NUMBER buttons
response = client.whatsapp.create_whats_app_template(
    account_id='YOUR_ACCOUNT_ID',
    name='account_creation_confirmation_3',
    category='UTILITY',
    language=lib.template.language,
    library_template_name='account_creation_confirmation_3',
    library_template_button_inputs=[
        {'type': 'URL', 'url': {'base_url': 'https://your-site.com/account', 'url_suffix_example': 'https://your-site.com/account'}}
    ]
)
```
</Tab>
<Tab value="curl">
```bash
# 1. Look up the library template
curl "https://zernio.com/api/v1/whatsapp/template-library?accountId=YOUR_ACCOUNT_ID&name=account_creation_confirmation_3&language=en_US" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Create it with button inputs
curl -X POST https://zernio.com/api/v1/whatsapp/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_ACCOUNT_ID",
    "name": "account_creation_confirmation_3",
    "category": "UTILITY",
    "language": "en_US",
    "library_template_name": "account_creation_confirmation_3",
    "library_template_button_inputs": [
      { "type": "URL", "url": { "base_url": "https://your-site.com/account", "url_suffix_example": "https://your-site.com/account" } }
    ]
  }'
```
</Tab>
</Tabs>

---

# Chat SDK

Build chatbots that work across Instagram, Facebook, Telegram, WhatsApp, Twitter/X, Bluesky, and Reddit through a single Chat SDK adapter.

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';

[Chat SDK](https://chat-sdk.dev) is Vercel's unified TypeScript framework for building chatbots across messaging platforms. The `@zernio/chat-sdk-adapter` is the **vendor official** Zernio adapter, [listed on chat-sdk.dev](https://chat-sdk.dev/adapters/zernio), letting you build a single chatbot that works across all Zernio-supported messaging platforms.

## Why use this?

Even if Chat SDK shipped native adapters for every social platform, you'd still need to apply to Meta's developer program, go through App Review, get WhatsApp Business verification, apply for X elevated API access, register a Reddit OAuth app, and set up a Telegram bot. That's 6+ developer programs, review processes, OAuth app configurations, and ongoing token refresh management.

Zernio handles all of that. Your users connect their accounts through OAuth in the Zernio dashboard, and you get a single API key. No developer program applications, no app reviews, no token management.

| Without Zernio | With Zernio |
|---|---|
| Apply to 6+ developer programs | Connect accounts in a dashboard |
| Go through platform App Reviews | No reviews needed |
| Build 7 OAuth app configurations | 1 API key |
| Manage token refresh per platform | Zernio handles token lifecycle |
| 7 webhook endpoints to maintain | 1 webhook endpoint |
| Platform-specific error handling | Unified error responses |

## Setup

<Steps>

<Step>
### Install the adapter

```bash
npm install @zernio/chat-sdk-adapter chat @chat-adapter/state-memory
```

<Callout type="info">
For production, swap `@chat-adapter/state-memory` for a persistent state adapter like `@chat-adapter/state-redis` or `@chat-adapter/state-pg`. See [State Adapters](https://chat-sdk.dev/docs/state) for all options.
</Callout>
</Step>

<Step>
### Configure environment variables

```bash
# Required: your Zernio API key (read-write)
ZERNIO_API_KEY=your_api_key

# Recommended: webhook secret for signature verification
ZERNIO_WEBHOOK_SECRET=your_webhook_secret
```

Get your API key from [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys). Make sure the key has **read-write** permissions.
</Step>

<Step>
### Create your bot

```typescript title="lib/bot.ts"
import { Chat } from "chat";
import { createZernioAdapter } from "@zernio/chat-sdk-adapter";
import { createMemoryState } from "@chat-adapter/state-memory";

export const bot = new Chat({
  userName: "pizza-bot",
  adapters: {
    zernio: createZernioAdapter(),
  },
  state: createMemoryState(),
});

// Register a handler for incoming messages (use /.*/ to match every message)
bot.onNewMessage(/.*/, async (thread, message) => {
  const platform = (message.raw as any).platform;
  await thread.post(`Hello from ${platform}!`);
});
```
</Step>

<Step>
### Add a webhook route

<Tabs items={['Next.js App Router', 'Express']}>
<Tab value="Next.js App Router">
```typescript title="app/api/chat-webhook/route.ts"
import { bot } from "@/lib/bot";

export async function POST(request: Request) {
  return bot.webhooks.zernio(request);
}
```
</Tab>
<Tab value="Express">
```typescript title="server.ts"
import express from "express";
import { bot } from "./lib/bot";

const app = express();

app.post("/api/chat-webhook", async (req, res) => {
  const response = await bot.webhooks.zernio(req);
  res.status(response.status).send(await response.text());
});
```
</Tab>
</Tabs>
</Step>

<Step>
### Configure your Zernio webhook

In the [Zernio dashboard](https://zernio.com/dashboard/webhooks), create a webhook:

- **URL**: `https://your-app.com/api/chat-webhook`
- **Events**: Select `message.received` and `comment.received`. Add `reaction.received` if you handle reactions (routes to `bot.onReaction`).
- **Secret**: Set a strong secret (same as `ZERNIO_WEBHOOK_SECRET`)
</Step>

</Steps>

## Configuration

The adapter auto-detects credentials from environment variables. You can also pass them explicitly:

```typescript
const adapter = createZernioAdapter({
  apiKey: "your-api-key",
  webhookSecret: "your-webhook-secret",
  baseUrl: "https://zernio.com/api",  // default
  botName: "My Bot",                   // default: "Zernio Bot"
});
```

| Env Variable | Config Key | Required | Description |
|---|---|---|---|
| `ZERNIO_API_KEY` | `apiKey` | Yes | API key for sending messages |
| `ZERNIO_WEBHOOK_SECRET` | `webhookSecret` | Recommended | HMAC-SHA256 secret for webhook verification |
| `ZERNIO_API_BASE_URL` | `baseUrl` | No | Override API base URL |
| `ZERNIO_BOT_NAME` | `botName` | No | Bot display name |

## Accessing platform data

Every message includes the raw Zernio payload, so you can access platform-specific data:

```typescript
bot.onNewMessage(/.*/, async (thread, message) => {
  const raw = message.raw as any;

  // Which platform sent this message
  console.log(raw.platform); // "instagram" | "facebook" | "telegram" | ...

  // Instagram-specific sender info
  if (raw.sender.instagramProfile) {
    console.log(raw.sender.instagramProfile.followerCount);
    console.log(raw.sender.instagramProfile.isVerified);
  }

  // WhatsApp phone number
  if (raw.sender.phoneNumber) {
    console.log(raw.sender.phoneNumber);
  }

  // Attachments (images, videos, etc.)
  for (const att of raw.attachments) {
    console.log(att.type, att.url);
  }
});
```

## Handling reactions

Reactions (WhatsApp and Telegram) are delivered as their own event and route to `onReaction`, not `onNewMessage`, so a 👍 is never mistaken for an inbound message. Subscribe your webhook to `reaction.received` to receive them.

```typescript
bot.onReaction(async (event) => {
  // event.emoji     the normalized emoji (use event.rawEmoji for the raw platform value)
  // event.added     true when added, false when removed
  // event.messageId the message that was reacted to
  // event.thread    the thread where it happened
  if (event.added) {
    await event.thread.post(`Thanks for the ${event.emoji}!`);
  }
});
```

## Supported features

| Feature | Supported | Notes |
|---|---|---|
| Send messages | Yes | Text across all platforms |
| Rich messages (cards) | Yes | Buttons and templates on FB, IG, Telegram, WhatsApp |
| Edit messages | Partial | Telegram only |
| Delete messages | Partial | Telegram, X (full); Bluesky, Reddit (self-only) |
| Send reactions | Partial | Telegram and WhatsApp |
| Receive reactions (`onReaction`) | Partial | WhatsApp and Telegram, via the `reaction.received` webhook |
| Typing indicators | Partial | Facebook Messenger and Telegram |
| AI streaming | Partial | Live post+edit on Telegram; full reply posted once on platforms without message editing (WhatsApp, Instagram, Facebook, X, Bluesky, Reddit) |
| File attachments | Yes | Via media upload endpoint |
| Fetch messages | Yes | Full conversation history (supports `limit`, `cursor`, and `direction`) |
| Fetch thread info | Yes | Participant details, platform, status |
| Webhook verification | Yes | HMAC-SHA256 |
| Comment webhooks | Yes | `comment.received` routed through handlers |
| Reaction webhooks | Yes | `reaction.received` routed to `onReaction` |

## API client

The adapter exports a standalone API client for direct Zernio API calls beyond what Chat SDK covers:

```typescript
import { ZernioApiClient } from "@zernio/chat-sdk-adapter";

const client = new ZernioApiClient("your-api-key", "https://zernio.com/api");

// List conversations
const { data, pagination } = await client.listConversations({
  platform: "instagram",
  status: "active",
  limit: 20,
});

// Send a message with an attachment
await client.sendMessage(conversationId, {
  accountId: "acc-123",
  message: "Check this out!",
  attachmentUrl: "https://example.com/image.jpg",
  attachmentType: "image",
});
```

## Prerequisites

- A [Zernio API key](https://zernio.com/dashboard/api-keys) with read-write permissions
- At least one [connected social account](/guides/connecting-accounts)
- Inbox features available on your Zernio account (included with the [Usage plan](/pricing); AppSumo users need the Inbox add-on)
- Node.js 20+ (for native `fetch` and `crypto` support)

<Callout type="info">
Inbox features (including `message.received` webhooks) are bundled with every paid account on the Usage plan. AppSumo users need the Inbox add-on; contact support if you need to enable it.
</Callout>

## Resources

- [GitHub repository](https://github.com/zernio-dev/chat-sdk-adapter)
- [npm package](https://www.npmjs.com/package/@zernio/chat-sdk-adapter)
- [Chat SDK documentation](https://chat-sdk.dev)
- [Zernio Webhook API](/webhooks)
- [Zernio Inbox API](/messages/list-inbox-conversations)

---

# Integrations

Automate social media posting via n8n, Make.com, Zapier, or OpenClaw. Schedule and cross-post to Twitter, Instagram, LinkedIn, TikTok & 10 more.

import { Cards, Card } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';

Connect Zernio API with your favorite automation platforms to build powerful social media workflows without writing code.

## Chat SDK

<Cards>
  <Card
    title="Chat SDK"
    description="Vendor official adapter for building multi-platform chatbots with Vercel's Chat SDK"
    href="/resources/integrations/chat-sdk"
  />
</Cards>

## Automation Platforms

<Cards>
  <Card
    title="n8n"
    description="Official verified Zernio node for workflow automation"
    href="/resources/integrations/n8n"
  />
  <Card
    title="Make"
    description="Official Zernio app with 20+ dedicated modules"
    href="/resources/integrations/make"
  />
  <Card
    title="Zapier"
    description="Official Zernio app with OAuth and 7,000+ app triggers"
    href="/resources/integrations/zapier"
  />
  <Card
    title="OpenClaw"
    description="Official Zernio skill from ClawHub for AI-driven posting"
    href="/resources/integrations/openclaw"
  />
</Cards>

## How It Works

Zernio has official, native integrations for n8n, Make, and Zapier, with dedicated nodes and modules that handle authentication and API formatting for you. OpenClaw connects via a custom skill.

| Platform | Integration Type | Auth Setup | Best For |
|----------|-----------------|------------|----------|
| n8n | Verified node (`n8n-nodes-zernio`) | API Key credential | Self-hosted, complex workflows |
| Make | Native app (20+ modules) | API Key connection | Visual scenarios, webhook triggers |
| Zapier | Native app (OAuth) | OAuth account linking | Simple automations, 7,000+ app triggers |
| OpenClaw | ClawHub skill (`zernio-api`) | Environment variable | AI-driven posting, natural language |

## Prerequisites

Before setting up any integration, you need:

1. A Zernio API key from [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys)
2. At least one [connected social media account](/guides/connecting-accounts)
3. An account on your chosen automation platform

<Callout type="info">
All integrations use the same API endpoints documented in the [API Reference](/). The guides below show platform-specific setup and configuration.
</Callout>

---

# Make

Native Make.com app for social media automation. 20+ modules for Twitter, Instagram, LinkedIn, TikTok, YouTube, Pinterest, Reels & Stories.

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

Automate social media publishing across 14+ platforms using the official Zernio app on Make.com. Build visual scenarios with dedicated modules for each platform, no HTTP configuration required.

## Quick Reference

| Detail | Value |
|--------|-------|
| **Make App Name** | Zernio (Make Nodes Zernio) |
| **App Directory** | [make.com/en/integrations/make-nodes-late](https://www.make.com/en/integrations/make-nodes-late) |
| **Module Count** | 20+ dedicated modules |
| **Auth Method** | API Key connection |

## Available Modules

### Content Creation

| Module | Description |
|--------|-------------|
| **Add Post to Twitter/X** | Publish or schedule a tweet |
| **Add Post to LinkedIn** | Publish or schedule a LinkedIn post |
| **Add Post to Facebook** | Publish or schedule a Facebook post |
| **Add Post to Instagram** | Publish or schedule an Instagram post |
| **Add Instagram Stories** | Create an Instagram Story |
| **Add Instagram Reels** | Create an Instagram Reel |
| **Add Post to TikTok** | Publish or schedule a TikTok video |
| **Add Post to Threads** | Publish or schedule a Threads post |
| **Add Post to Bluesky** | Publish or schedule a Bluesky post |
| **Upload YouTube Video** | Upload and publish a YouTube video |
| **Upload Pinterest Image Pin** | Create an image pin |
| **Upload Pinterest Video Pin** | Create a video pin |

### Management

| Module | Description |
|--------|-------------|
| **Get Social Accounts** | List all connected social accounts |
| **Get Post List** | List posts with filtering by status |
| **Get Post by ID** | Retrieve a specific post's details |
| **List Profiles** | List all profiles |
| **List Pinterest Boards** | List boards for a Pinterest account |
| **Update a Post** | Edit draft or scheduled posts |
| **Delete a Post** | Remove draft, scheduled, or failed posts |
| **Delete a Social Account** | Disconnect a social account |
| **Retry Adding a Post** | Republish a failed post |
| **Make an API Call** | Custom request for any Zernio API endpoint |

<Callout type="warn">
You need a Zernio API key and at least one connected social media account before setting up this integration. Get your key at [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys).
</Callout>

## Setup

<Steps>

<Step>
### Find the Zernio App

In your Make scenario editor, click the **+** button to add a module. Search for **"Zernio"** in the app picker.

Select any Zernio module to get started (e.g., **Add Post to Twitter/X**).
</Step>

<Step>
### Create a Connection

When prompted, click **Add** to create a new connection:

1. Give the connection a name (e.g., "My Zernio Account")
2. Paste your API key from [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys)
3. Click **Save**

The connection is reusable across all Zernio modules in your scenarios.

<Callout type="warn">
Treat your API key like a password. If compromised, regenerate it immediately from the Zernio dashboard.
</Callout>
</Step>

<Step>
### Test the Connection

Select the **Get Social Accounts** module, choose your connection, and click **Run once**. You should see your connected social media accounts.
</Step>

</Steps>

## Create a Post

1. Add a Zernio module for your target platform (e.g., **Add Post to Twitter/X**)
2. Select your **Connection**
3. Select a **Profile** from the dropdown
4. Select a **Social Account** from the dropdown
5. Enter the **Text** content
6. Optionally add **Media URLs** (image or video links)
7. Optionally set a **Scheduled Date** for future publishing

Click **Run once** to test. The post will be published or scheduled based on your configuration.

### Using Dynamic Data

Map data from previous modules into Zernio module fields:

- Click into any field and select values from the module mapping panel
- Example: Map `{{1.title}}` from a Google Sheets trigger into the Text field
- Example: Map `{{2.imageUrl}}` from a media module into Media URLs

## Schedule a Post

Set the **Scheduled Date** field to a future ISO 8601 timestamp. If left empty, the post is published immediately.

Use Make's built-in date functions for dynamic scheduling:

| Function | Result |
|----------|--------|
| `{{addDays(now; 1)}}` | Tomorrow, same time |
| `{{formatDate(addDays(now; 1); "YYYY-MM-DD")}}T09:00:00Z` | Tomorrow at 9 AM UTC |
| `{{addHours(now; 3)}}` | 3 hours from now |

## Cross-Post to Multiple Platforms

Use Make's **Router** module to split a scenario into parallel paths, each targeting a different platform:

1. **Trigger** (Google Sheets, Webhook, Schedule, etc.)
2. **Router** → Split into paths
3. **Path A** → Zernio: Add Post to Twitter/X
4. **Path B** → Zernio: Add Post to LinkedIn
5. **Path C** → Zernio: Add Post to Bluesky

Each path can have its own content formatting, shorter text for Twitter, longer for LinkedIn, etc.

## Scenario Examples

### Google Sheets Content Calendar

1. **Google Sheets → Watch Rows**, Trigger when a new row is added
2. **Zernio → Add Post to Twitter/X**, Map the row's content and schedule date

### Webhook-Triggered Posting

1. **Webhooks → Custom Webhook**, Receive POST requests from your app
2. **Zernio → Add Post to LinkedIn**, Post the incoming content

Send content to the webhook URL:

```bash
curl -X POST "https://hook.make.com/YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from my app!", "platform": "linkedin"}'
```

### RSS Feed to Social Media

1. **RSS → Watch RSS Feed Items**, Check for new blog posts
2. **Text Parser → Match Pattern**, Extract title and link
3. **Router** → Split into platform paths
4. **Zernio → Add Post to Twitter/X**, Short post with link
5. **Zernio → Add Post to LinkedIn**, Longer post with context

### Retry Failed Posts

1. **Schedule → Every Hour**, Check periodically
2. **Zernio → Get Post List**, Filter by `failed` status
3. **Iterator**, Loop through failed posts
4. **Zernio → Retry Adding a Post**, Retry each failed post

## Custom API Requests

For operations not covered by dedicated modules, use **Make an API Call**:

| Field | Value |
|-------|-------|
| **URL** | `/v1/analytics` (relative to base URL) |
| **Method** | GET |

This sends an authenticated request to any Zernio API endpoint. See the [API Reference](/) for all available endpoints.

## Error Handling

### Error Handler Routes

Right-click any Zernio module and select **Add error handler**:

| Handler | When to Use |
|---------|-------------|
| **Break** | Rate limits (429), store for manual retry |
| **Ignore** | Non-critical failures, skip and continue |
| **Rollback** | Critical failures, stop the scenario |
| **Resume** | Provide a fallback value and continue |

### Rate Limits

Zernio API has [rate limits by plan](/guides/rate-limits). For high-volume scenarios:

- Use the **Sleep** module between Zernio modules to space out requests
- Set your scenario schedule to an appropriate interval
- Monitor for 429 responses and use Break handlers

## Operations Cost

Each Zernio module execution consumes one Make operation:

| Schedule | Operations/Day | Operations/Month |
|----------|-----------------|-------------------|
| Every 15 min | 96 | ~2,880 |
| Every hour | 24 | ~720 |
| Every day | 1 | ~30 |
| Webhook (on demand) | Varies | Only when triggered |

## Links

- [Zernio on Make.com](https://www.make.com/en/integrations/make-nodes-late)
- [App Documentation](https://apps.make.com/make-nodes-late)
- [Get API Key](https://zernio.com/dashboard/api-keys)
- [API Reference](/)

---

# n8n

Verified n8n node for social media automation. Post to Twitter, Instagram, LinkedIn, TikTok & more with scheduling, media uploads, webhooks, and cross-posting.

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

Automate social media posting across 14+ platforms using the official Zernio node for n8n. No HTTP configuration needed, the node handles authentication, request formatting, and response parsing.

## Quick Reference

| Detail | Value |
|--------|-------|
| **Node Package** | `n8n-nodes-zernio` |
| **Version** | 0.0.12+ |
| **Source** | [github.com/zernio-dev/n8n-nodes-zernio](https://github.com/zernio-dev/n8n-nodes-zernio) |
| **npm** | [npmjs.com/package/n8n-nodes-zernio](https://www.npmjs.com/package/n8n-nodes-zernio) |
| **License** | MIT |
| **Works On** | n8n Cloud and self-hosted |

## Available Operations

| Resource | Operations |
|----------|------------|
| **Posts** | Create and schedule posts to Twitter/X, Instagram, Facebook, LinkedIn, TikTok, YouTube, Threads, Bluesky |
| **Profiles** | Create profiles, connect social media platforms |
| **Media** | Upload files, presign large files (>4MB) |
| **Webhooks** | Receive `post.published` and `post.failed` events |
| **Usage** | Monitor usage statistics |

<Callout type="warn">
You need a Zernio API key and at least one connected social media account before setting up this integration. Get your key at [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys).
</Callout>

## Setup

<Steps>

<Step>
### Install the Zernio Node

The Zernio node is a verified n8n node, search for **"Zernio"** in the n8n node palette and it will appear directly. No community node installation required.

On self-hosted instances, install via npm:

```
npm install n8n-nodes-zernio
```

Restart n8n after installation. The Zernio node will appear in the node palette.
</Step>

<Step>
### Add Your API Key

When you first add a Zernio node to a workflow, n8n will prompt you to create a **Zernio API** credential.

1. Click **Create New Credential**
2. Paste your API key from [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys)
3. Click **Save**

The credential is reusable across all Zernio nodes in your workflows.
</Step>

<Step>
### Test the Connection

Add a Zernio node, select **Profiles** → **List Profiles**, and click **Execute Node**. You should see your Zernio profiles in the output.
</Step>

</Steps>

## Create a Post

1. Add a **Zernio** node to your workflow
2. Set **Resource** to **Posts**
3. Set **Operation** to the target platform (e.g., **Add Post to Twitter/X**)
4. Select your **Profile** and **Social Account** from the dropdowns
5. Enter your post **Content**
6. Optionally set a **Scheduled Date** for future publishing

The node handles all the API formatting, just fill in the fields.

### Platform-Specific Operations

Each platform has its own operation with relevant fields:

| Operation | Platform-Specific Fields |
|-----------|--------------------------|
| Add Post to Twitter/X | Content, Media URLs |
| Add Post to Instagram | Content, Media URLs |
| Add Instagram Stories | Content, Image URL |
| Add Instagram Reels | Content, Video URL, Thumbnail |
| Add Post to LinkedIn | Content, Media URLs |
| Add Post to Facebook | Content, Media URLs |
| Add Post to TikTok | Content, Video URL |
| Upload YouTube Video | Content, Video URL, Thumbnail |
| Add Post to Threads | Content, Media URLs |
| Add Post to Bluesky | Content, Media URLs |
| Upload Pinterest Image Pin | Content, Image URL, Board, Link |
| Upload Pinterest Video Pin | Content, Video URL, Board, Cover Image, Link |

### Using Dynamic Data

Map fields from previous nodes directly into the Zernio node fields using n8n expressions:

- **Content**: `{{ $json.postText }}`, from a Google Sheets, RSS, or Code node
- **Scheduled Date**: `{{ $json.publishDate }}`, ISO 8601 timestamp
- **Media URLs**: `{{ $json.imageUrl }}`, from a media source

## Schedule a Post

Set the **Scheduled Date** field to a future timestamp. The post will be queued and published at that time.

To compute the date dynamically, use a **Code** node before the Zernio node:

```javascript
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
tomorrow.setHours(9, 0, 0, 0);

return [{ json: { scheduledFor: tomorrow.toISOString() } }];
```

Then map `{{ $json.scheduledFor }}` into the Zernio node's Scheduled Date field.

## Upload Media

For files under 4MB:

1. Set **Resource** to **Media**
2. Set **Operation** to **Upload**
3. Provide the file from a previous node (e.g., HTTP Request, Google Drive, or Read Binary File)

For files over 4MB, use the **Presign** operation first to get a pre-signed upload URL, upload the file, then reference the media URL when creating a post.

## Webhooks

Set up real-time notifications for post and account events:

1. Add a Zernio node with **Resource** → **Webhooks**
2. Configure the webhook URL (your n8n webhook endpoint)
3. Select the events you want to receive

Available events:

| Event | Description |
|-------|-------------|
| `post.scheduled` | Post scheduled for future publishing |
| `post.published` | Post successfully published |
| `post.failed` | Post failed on all platforms |
| `post.partial` | Post published to some platforms, failed on others |
| `account.connected` | Social account connected |
| `account.disconnected` | Social account disconnected |

Use a **Webhook** trigger node to receive these events and trigger follow-up actions (e.g., send a Slack notification on failure).

## Workflow Examples

### Scheduled Daily Posting from Google Sheets

1. **Schedule Trigger** → Run every day at 9:00 AM
2. **Google Sheets** → Read the next row from your content calendar
3. **Zernio** → Create post with the row's content, platform, and optional media

### RSS Feed to Social Media

1. **Schedule Trigger** → Check every hour
2. **RSS Feed Read** → Read your blog RSS feed
3. **IF** → Check if there are new items
4. **Zernio** → Post new articles to Twitter/X and LinkedIn

### AI Content Generation Pipeline

1. **Schedule Trigger** → Run daily
2. **HTTP Request** → Fetch trending topics or RSS items
3. **OpenAI** → Generate platform-optimized post content
4. **Zernio** → Post to multiple platforms with tailored content

<Callout type="info">
Pre-built workflow templates are available at [zernio.com/n8n-templates](https://zernio.com/n8n-templates), including RSS-to-social pipelines with AI content generation and Google Sheets auto-posting.
</Callout>

## Error Handling

### Retry on Failure

On the Zernio node, go to **Settings** → **Retry on Fail**:

| Setting | Recommended Value |
|---------|-------------------|
| **Max Tries** | 3 |
| **Wait Between Tries (ms)** | 2000 |

### Webhook Monitoring

Set up a webhook for `post.failed` events to get notified instantly when a post fails to publish. Combine with a Slack or email node for alerts.

### Error Workflow

Set up an **Error Workflow** in your workflow settings:

1. Create a separate workflow with an **Error Trigger** node
2. Add notification actions (email, Slack, etc.)
3. In your main workflow, go to **Settings** → **Error Workflow** and select it

## Rate Limits

The Zernio node respects the same [rate limits](/guides/rate-limits) as direct API calls. For high-volume workflows, space out executions using the Schedule Trigger interval or add Wait nodes between batches.

## Links

- [Zernio Node on n8n](https://n8n.io/integrations/zernio/)
- [npm Package](https://www.npmjs.com/package/n8n-nodes-zernio)
- [Source Code](https://github.com/zernio-dev/n8n-nodes-zernio)
- [Workflow Templates](https://zernio.com/n8n-templates)
- [Get API Key](https://zernio.com/dashboard/api-keys)
- [API Reference](/)

---

# OpenClaw

ClawHub skill for social media automation via natural language. Post to Twitter, Instagram, LinkedIn & 11 more platforms. Scheduling, cross-posting & analytics.

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

Post to 14+ social media platforms directly from OpenClaw using natural language. Install the official Zernio skill from ClawHub and start scheduling content with conversational commands.

## Quick Reference

| Detail | Value |
|--------|-------|
| **Skill Name** | `zernio-api` |
| **ClawHub** | [clawhub.ai/mikipalet/zernio-api](https://clawhub.ai/mikipalet/zernio-api) |
| **Install Command** | `npx clawhub@latest install mikipalet/zernio-api` |
| **Auth Method** | Bearer token via `ZERNIO_API_KEY` environment variable |
| **Base URL** | `https://zernio.com/api/v1` |

## What the Skill Covers

The Zernio skill provides OpenClaw with comprehensive API knowledge across these areas:

| Area | Capabilities |
|------|-------------|
| **Profiles** | Create and manage brand profiles |
| **Account Connections** | OAuth flows for connecting social accounts |
| **Posts** | Create, schedule, bulk upload, and retry posts |
| **Media** | Presigned URL uploads for images and video |
| **Queue Management** | Manage queue slots for scheduled publishing |
| **Webhooks** | Delivery/status event notifications, webhook verification |
| **Analytics** | Post performance data |

Supported platforms: Twitter/X, Instagram, Facebook, LinkedIn, TikTok, YouTube, Pinterest, Reddit, Bluesky, Threads, Google Business, Telegram, Snapchat, WhatsApp.

<Callout type="warn">
You need a Zernio API key, at least one connected social media account, and a working OpenClaw installation. Get your key at [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys).
</Callout>

## Setup

<Steps>

<Step>
### Install the Skill from ClawHub

```bash
npx clawhub@latest install mikipalet/zernio-api
```

This downloads the skill and its rule files (`authentication.md`, `posts.md`, `accounts.md`, `connect.md`, `platforms.md`, `webhooks.md`, `media.md`) into your local skills directory.
</Step>

<Step>
### Add Your API Key

Add your Zernio API key to your OpenClaw environment file:

```bash
echo 'ZERNIO_API_KEY=sk_your_api_key_here' >> ~/.openclaw/.env
```

Replace `sk_your_api_key_here` with your actual key from [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys).
</Step>

<Step>
### Restart OpenClaw

Restart your OpenClaw session so it picks up the new skill:

```bash
openclaw restart
```
</Step>

</Steps>

## Using the Skill

Once installed, you can use natural language to manage your social media through OpenClaw:

### Publishing Posts

> **You:** Post "Just shipped a new feature!" to Twitter
>
> **OpenClaw:** I'll post that to Twitter for you. Let me first check your connected accounts... Done! Posted successfully.

### Scheduling

> **You:** Schedule a LinkedIn post for tomorrow at 9am: "Excited to share our Q1 results"
>
> **OpenClaw:** Scheduled your LinkedIn post for 2026-03-17 at 09:00 UTC.

### Cross-Posting

> **You:** Cross-post "Big announcement coming soon" to Twitter, LinkedIn, and Bluesky
>
> **OpenClaw:** Posted to all three platforms successfully.

### Managing Posts

> **You:** Show me my recent posts
>
> **OpenClaw:** Here are your recent posts: [lists posts with status, platform, and content]

> **You:** Retry all my failed posts
>
> **OpenClaw:** Found 2 failed posts. Retrying... Both posts published successfully.

### Connecting Accounts

> **You:** Connect my Instagram account
>
> **OpenClaw:** I'll start the OAuth flow for Instagram. Open this URL to authorize: [auth URL]

### Analytics

> **You:** How did my last Twitter post perform?
>
> **OpenClaw:** Your last tweet got 1,234 impressions, 56 likes, and 12 retweets.

## Webhook Integration

OpenClaw can receive webhook events from external services to trigger Zernio API posts.

### Configure an Incoming Webhook

Add a webhook endpoint to your OpenClaw configuration (`~/.openclaw/openclaw.json`):

```json
{
  "webhooks": {
    "zernio-post": {
      "path": "/webhooks/zernio-post",
      "secret": "your_webhook_secret",
      "action": "Run the zernio-api skill to publish the post content from the payload"
    }
  }
}
```

External services can POST to `http://your-openclaw-host:port/webhooks/zernio-post` with a JSON body:

```json
{
  "text": "Hello from a webhook!",
  "platform": "twitter"
}
```

OpenClaw will invoke the Zernio skill to publish the post.

## Advanced Workflows

### Blog-to-Social Pipeline

1. OpenClaw watches your blog RSS feed (via a scheduled skill or webhook)
2. When a new post is detected, it summarizes the content using AI
3. It crafts platform-appropriate versions (short for Twitter, longer for LinkedIn)
4. It calls Zernio API to post to each platform

### Content Calendar

1. Store your content calendar in Apple Notes, Notion, or a local file
2. Set up a scheduled OpenClaw task to check for posts due today
3. OpenClaw reads the entry and posts via Zernio API

### Media Uploads

> **You:** Post this product photo to Instagram with the caption "New arrivals!"
>
> **OpenClaw:** I'll generate a presigned upload URL for the image, upload it, and create the Instagram post.

The skill knows how to use presigned URLs for media uploads, handling the multi-step flow automatically.

## Troubleshooting

### "Skill not found"

Verify the skill is installed:

```bash
ls ~/.openclaw/skills/zernio-api/
```

You should see `SKILL.md` and the rule files. If not, reinstall:

```bash
npx clawhub@latest install mikipalet/zernio-api
```

### "ZERNIO_API_KEY not set"

Verify the environment variable is in your `.env` file:

```bash
grep ZERNIO_API_KEY ~/.openclaw/.env
```

Make sure it starts with `sk_` and has no extra spaces or quotes around the value.

### Authentication Errors (401)

1. Check your API key at [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys)
2. Verify the key is active and not expired
3. Restart OpenClaw after any `.env` changes

### Rate Limits (429)

Zernio API has [rate limits by plan](/guides/rate-limits). If you hit limits:

- Space out automated posts
- Upgrade your Zernio plan for higher limits
- Check the `Retry-After` header in the response

## Links

- [Zernio Skill on ClawHub](https://clawhub.ai/mikipalet/zernio-api)
- [Get API Key](https://zernio.com/dashboard/api-keys)
- [API Reference](/)

---

# Zapier

Native Zapier app for social media automation. Trigger posts from Google Sheets, Notion, RSS, Ghost & 7,000+ apps. Scheduling, Reels, Stories & Pinterest.

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

Automate social media publishing across 14+ platforms using the official Zernio app on Zapier. Connect Zernio with 7,000+ apps to trigger posts from Google Sheets, Notion, RSS feeds, CRMs, and more.

## Quick Reference

| Detail | Value |
|--------|-------|
| **Zapier App** | [Zernio](https://zapier.com/apps/late/integrations) |
| **Auth Method** | OAuth (connect your Zernio account) |
| **Role** | Action app (receives content, publishes posts) |
| **Popular Triggers** | Schedule, Notion, Google Sheets, Ghost, RSS, Gmail |

## Available Actions

### Create Content

| Action | Required Fields | Optional Fields |
|--------|----------------|-----------------|
| **Create Post** | Platform, Account ID, Content | Scheduled For, Media URLs |
| **Create Instagram Reel** | Account ID, Video URL | Content, Thumbnail, Scheduled For |
| **Create Instagram Story** | Account ID, Image URL | Content, Scheduled For |
| **Create YouTube Video** | Account ID, Content, Video URL | Thumbnail, Scheduled For |
| **Add Pinterest Image Pin** | Account ID, Board ID, Link, Content, Image |, |
| **Add Pinterest Video Pin** | Account ID, Board ID, Content, Link, Cover Image, Video |, |

### Manage Posts

| Action | Description |
|--------|-------------|
| **Update Post** | Edit draft or scheduled posts |
| **Delete Post** | Remove draft, scheduled, or failed posts |
| **Retry Add Post** | Republish a failed post |

### Search & Lookup

| Action | Description |
|--------|-------------|
| **Get Post by ID** | Retrieve a specific post's details |
| **Get Posts** | List posts with filtering (status, profile, date, pagination) |
| **Get Profiles** | List all profiles |
| **Get Social Accounts** | List connected accounts for a profile |
| **Get Pinterest Board List** | List boards for a Pinterest account |

### Account Management

| Action | Description |
|--------|-------------|
| **Delete Social Account** | Disconnect a social account |

<Callout type="warn">
You need a Zernio account with at least one connected social media account before setting up this integration. Connect accounts at [zernio.com](https://zernio.com).
</Callout>

## Setup

<Steps>

<Step>
### Find the Zernio App

Go to [zapier.com](https://zapier.com) and create a new Zap. When adding an action step, search for **"Zernio"** in the app picker.

<Callout type="warn">
Make sure you select **Zernio** (zernio.com), not "Later", they are different products.
</Callout>
</Step>

<Step>
### Connect Your Account

Click **Sign in** when prompted. You'll be redirected to Zernio's OAuth flow:

1. Log in to your Zernio account
2. Authorize Zapier to access your Zernio data
3. You'll be redirected back to Zapier

The connection is reusable across all Zaps.
</Step>

<Step>
### Select a Profile and Account

When configuring a Zernio action:

1. Select a **Profile** from the dropdown
2. Select a **Social Account** from the dropdown (filtered to the chosen profile)
3. Fill in the content fields

Click **Test step** to verify the connection works.
</Step>

</Steps>

## Create a Post

1. Add a trigger (see [Popular Triggers](#popular-triggers) below)
2. Add **Zernio** as the action app
3. Choose **Create Post** as the action event
4. Select your **Profile** and **Social Account**
5. Enter the post **Content** (or map from the trigger step)
6. Optionally set **Scheduled For** to delay publishing

Leave **Scheduled For** empty to publish immediately.

### Mapping Dynamic Content

Click into any field and select values from your trigger step:

- **Content**: Map a Google Sheets column, Notion property, or RSS title
- **Media URLs**: Map a file URL from Google Drive, Dropbox, or Airtable
- **Scheduled For**: Map a date column from your content calendar

## Popular Triggers

Zernio is an action-only app, it receives content from other apps. These are the most popular trigger combinations:

### Schedule by Zapier

Post on a recurring schedule:

| Schedule | Use Case |
|----------|----------|
| Every day at 9 AM | Daily content from a spreadsheet |
| Every Monday | Weekly roundup post |
| Every hour | High-frequency updates |
| First of month | Monthly recap |

Schedule triggers do not count toward task usage.

### Google Sheets

Post when a new row is added to your content calendar:

1. **Google Sheets → New Spreadsheet Row**, Trigger on new rows
2. **Zernio → Create Post**, Map columns to post fields

| Sheet Column | Zernio Field |
|-------------|------------|
| Content | Content |
| Platform | Platform |
| Image URL | Media URLs |
| Publish Date | Scheduled For |

### Notion

Post when a Notion database entry changes status:

1. **Notion → Updated Database Item**, Trigger when status changes to "Ready"
2. **Filter by Zapier**, Only continue if status = "Ready"
3. **Zernio → Create Post**, Map Notion properties to post fields

### RSS Feed

Auto-post new blog articles:

1. **RSS by Zapier → New Item in Feed**, Enter your blog feed URL
2. **Zernio → Create Post**, Map title and link to content

### Ghost / CMS

Post when a new article is published:

1. **Ghost → Published Post**, Trigger on new publications
2. **Zernio → Create Post**, Share the article across social platforms

## Schedule a Post

Set the **Scheduled For** field to a future date. Accepts ISO 8601 timestamps.

To compute dates dynamically, add a **Code by Zapier** step (JavaScript) before the Zernio action:

```javascript
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
tomorrow.setHours(9, 0, 0, 0);

output = [{ scheduledFor: tomorrow.toISOString() }];
```

Map `scheduledFor` from the Code step into Zernio's **Scheduled For** field.

## Cross-Post to Multiple Platforms

### Option A: Multiple Actions

Add multiple Zernio actions in a single Zap, each targeting a different platform:

1. **Trigger** → Your content source
2. **Zernio → Create Post** → Twitter/X
3. **Zernio → Create Post** → LinkedIn
4. **Zernio → Create Post** → Bluesky

### Option B: Paths (Paid Plans)

Use **Paths by Zapier** to send different content to each platform:

1. **Trigger** → Content source
2. **Paths by Zapier**
   - **Path A** (Twitter) → Zernio: Create Post with short content
   - **Path B** (LinkedIn) → Zernio: Create Post with long-form content
   - **Fallback** → Zernio: Create Post to all remaining platforms

## Zap Examples

### Content Calendar Automation

1. **Google Sheets → New Row**, Content calendar with columns: Content, Platform, Image URL, Publish Date
2. **Filter**, Only continue if "Status" column is "Ready"
3. **Zernio → Create Post**, Map all fields

### Blog-to-Social Pipeline

1. **RSS by Zapier → New Item**, Your blog feed
2. **Code by Zapier**, Format the post: `New: ${title}\n\n${link}`
3. **Zernio → Create Post** → Twitter/X
4. **Zernio → Create Post** → LinkedIn (with longer excerpt)

### Failed Post Recovery

1. **Schedule by Zapier → Every Hour**
2. **Zernio → Get Posts**, Filter by status = "failed"
3. **Filter**, Only continue if results exist
4. **Zernio → Retry Add Post**, Retry the failed post

## Error Handling

### Common Errors

| Issue | Cause | Fix |
|-------|-------|-----|
| "Account not found" | Profile or account ID mismatch | Re-select from the dropdowns |
| "Content too long" | Exceeds platform character limit | Shorten content or use a Code step to truncate |
| "Rate limit exceeded" | Too many requests | Space out Zap executions |
| "Cannot delete published post" | Post already published | Only draft/scheduled/failed posts can be deleted |

### Auto-Replay

Zapier automatically retries certain failures. For persistent errors:

1. Go to **Zap History** → find the failed run
2. Review the error details
3. Fix the issue
4. Click **Replay** to retry

### Filters as Guards

Add **Filter by Zapier** before Zernio actions to prevent bad API calls:

- Only continue if content is not empty
- Only continue if platform is a valid value
- Only continue if publish date is in the future

## Task Usage

Each successful Zernio action counts as one Zapier task:

| Pattern | Tasks/Day | Tasks/Month |
|---------|-----------|-------------|
| Daily post to 1 platform | 1 | ~30 |
| Daily post to 3 platforms | 3 | ~90 |
| Hourly check + post | 24 | ~720 |
| Webhook-triggered | Varies | Only when triggered |

## Links

- [Zernio on Zapier](https://zapier.com/apps/late/integrations)
- [Get API Key](https://zernio.com/dashboard/api-keys)
- [API Reference](/)

---

# Migrate from Ayrshare

Step-by-step guide to migrate from Ayrshare to Zernio API

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

This guide walks you through migrating from Ayrshare to Zernio. Choose the path that fits your situation:

| Path | Best for | Effort |
|------|----------|--------|
| **[Drop-in SDK](#drop-in-sdk-replacement)** | Already using the Ayrshare `social-media-api` npm package | ~5 minutes |
| **[Full API migration](#quick-reference)** | Using raw HTTP calls or a custom client | 1–2 hours |

---

## Drop-in SDK Replacement

If you're using the Ayrshare `social-media-api` npm package, the fastest way to migrate is our **drop-in replacement SDK**. All method signatures are identical - just swap the package and API key.

### Install

```bash
npm uninstall social-media-api
npm install @zernio/social-media-api
```

### Update your import

```diff
- import SocialMediaAPI from 'social-media-api';
+ import SocialMediaAPI from '@zernio/social-media-api';

const social = new SocialMediaAPI('your_zernio_api_key');
```

That's it. All existing calls (`post`, `history`, `upload`, `createProfile`, etc.) work without changes.

### Supported methods

All core Ayrshare SDK methods are fully supported:

| Category | Methods |
|----------|---------|
| Posts | `post`, `delete`, `getPost`, `retryPost`, `updatePost` |
| History | `history` |
| User | `user` |
| Profiles | `createProfile`, `deleteProfile`, `updateProfile`, `getProfiles` |
| Media | `upload`, `media`, `mediaUploadUrl`, `verifyMediaExists` |
| Analytics | `analyticsPost`, `analyticsSocial` |
| Comments | `postComment`, `getComments`, `deleteComments`, `replyComment` |
| Webhooks | `registerWebhook`, `unregisterWebhook`, `listWebhooks` |
| Scheduling | `setAutoSchedule`, `deleteAutoSchedule`, `listAutoSchedule` |
| Reviews | `reviews`, `review`, `replyReview`, `deleteReplyReview` |

<Callout type="warn">
**Not yet available:** AI generation (`generatePost`, `generateRewrite`, etc.), RSS feeds, URL shortening, and a few media/analytics utilities return `501` for now. See the [full compatibility list](https://github.com/zernio-dev/social-media-api#not-yet-available) for details.
</Callout>

### Multi-profile support

If you use Ayrshare Profile Keys, the SDK supports the same pattern:

```typescript
social.setProfileKey('your_profile_key');

// All subsequent requests are scoped to this profile
const history = await social.history({ lastRecords: 10 });
```

Find your profile keys via `social.getProfiles()`.

<Callout type="info">
**Source code & issues:** [github.com/zernio-dev/social-media-api](https://github.com/zernio-dev/social-media-api)
</Callout>

---

## Full API Migration

If you're making raw HTTP calls or want to use Zernio's native API directly, follow the steps below.

## Quick Reference

The main differences at a glance:

| What | Ayrshare | Zernio |
|------|----------|------|
| Base URL | `api.ayrshare.com/api` | `zernio.com/api/v1` |
| Content field | `post` | `content` |
| Platforms | `["twitter", "facebook"]` | `[{platform, accountId}]` |
| Media | `mediaUrls: ["url"]` | `mediaItems: [{type, url}]` |
| Schedule | `scheduleDate` | `scheduledFor` |
| Publish now | Omit `scheduleDate` | `publishNow: true` |
| Multi-user | `Profile-Key` header | Profiles as resources |

---

## Before You Start

<Callout type="info">
**What you'll need:**
- Your Ayrshare API key and Profile Keys
- A Zernio account ([sign up here](https://zernio.com))
- A Zernio API key from your dashboard
</Callout>

### How Zernio organizes accounts

Zernio uses a two-level structure:

```
Profile: "Acme Corp"
├── Twitter (@acmecorp)
├── LinkedIn (Acme Corp Page)
└── Facebook (Acme Corp)

Profile: "Side Project"
├── Twitter (@sideproject)
└── Instagram (@sideproject)
```

**Profiles** group social accounts together (like brands or clients). Each **Account** is a connected social media account with its own `accountId`.

---

## Step 1: Set Up Zernio Profiles

For each Ayrshare Profile Key, create a corresponding Zernio profile:

```bash
curl -X POST https://zernio.com/api/v1/profiles \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Brand"}'
```

Save the returned `_id` - you'll need it to connect accounts.

---

## Step 2: Connect Social Accounts

Initiate OAuth for each platform you had connected in Ayrshare:

```bash
curl -X GET "https://zernio.com/api/v1/connect/{platform}?profileId=PROFILE_ID&redirect_url=https://yourapp.com/callback" \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY"
```

**Supported platforms:** `twitter` `instagram` `facebook` `linkedin` `tiktok` `youtube` `pinterest` `reddit` `bluesky` `threads` `googlebusiness` `telegram` `snapchat`

<Callout type="warn">
**Platform name change:** Ayrshare uses `gmb` for Google My Business. Zernio uses `googlebusiness` (no underscore).
</Callout>

The response includes an `authUrl` - redirect your user there to complete authorization.

---

## Step 3: Get Your Account IDs

After connecting, fetch the account IDs:

```bash
curl -X GET "https://zernio.com/api/v1/accounts?profileId=PROFILE_ID" \
  -H "Authorization: Bearer YOUR_ZERNIO_API_KEY"
```

```json
{
  "accounts": [
    {
      "_id": "abc123",
      "platform": "twitter",
      "username": "@yourhandle",
      "displayName": "Your Name"
    }
  ]
}
```

**Store this mapping** in your database - you'll need the `_id` values when creating posts.

---

## Step 4: Update Your Post Calls

Here's how the API calls change:

<Tabs items={['Immediate Post', 'Scheduled Post', 'With Media']}>
<Tab value="Immediate Post">

**Ayrshare:**
```bash
curl -X POST https://api.ayrshare.com/api/post \
  -H "Authorization: Bearer API_KEY" \
  -H "Profile-Key: PROFILE_KEY" \
  -d '{
    "post": "Hello world!",
    "platforms": ["twitter", "linkedin"]
  }'
```

**Zernio:**
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer API_KEY" \
  -d '{
    "content": "Hello world!",
    "platforms": [
      {"platform": "twitter", "accountId": "abc123"},
      {"platform": "linkedin", "accountId": "def456"}
    ],
    "publishNow": true
  }'
```

</Tab>
<Tab value="Scheduled Post">

**Ayrshare:**
```bash
curl -X POST https://api.ayrshare.com/api/post \
  -d '{
    "post": "See you tomorrow!",
    "platforms": ["twitter"],
    "scheduleDate": "2025-01-15T10:00:00Z"
  }'
```

**Zernio:**
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -d '{
    "content": "See you tomorrow!",
    "platforms": [
      {"platform": "twitter", "accountId": "abc123"}
    ],
    "scheduledFor": "2025-01-15T10:00:00Z"
  }'
```

<Callout type="info">
Omit `publishNow` for scheduled posts - it defaults to `false`.
</Callout>

</Tab>
<Tab value="With Media">

**Ayrshare:**
```bash
curl -X POST https://api.ayrshare.com/api/post \
  -d '{
    "post": "Check this out!",
    "platforms": ["twitter"],
    "mediaUrls": ["https://example.com/image.jpg"]
  }'
```

**Zernio:**
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -d '{
    "content": "Check this out!",
    "platforms": [
      {"platform": "twitter", "accountId": "abc123"}
    ],
    "mediaItems": [
      {"type": "image", "url": "https://example.com/image.jpg"}
    ],
    "publishNow": true
  }'
```

</Tab>
</Tabs>

### Key changes summary

| Ayrshare | Zernio |
|----------|------|
| `post` | `content` |
| `platforms: ["twitter"]` | `platforms: [{platform: "twitter", accountId: "..."}]` |
| `mediaUrls: ["url"]` | `mediaItems: [{type: "image", url: "..."}]` |
| `scheduleDate` | `scheduledFor` |
| Omit scheduleDate to publish | `publishNow: true` |
| `Profile-Key` header | Not needed (use `accountId` in platforms) |

---

## Step 5: Update Media Uploads

Zernio uses presigned URLs for uploads (supports files up to 5GB):

<Steps>
### Request a presigned URL

```bash
curl -X POST https://zernio.com/api/v1/media/presign \
  -H "Authorization: Bearer API_KEY" \
  -d '{"filename": "photo.jpg", "contentType": "image/jpeg"}'
```

Response:
```json
{
  "uploadUrl": "https://storage.../presigned-url",
  "publicUrl": "https://media.zernio.com/temp/photo.jpg"
}
```

### Upload your file

```bash
curl -X PUT "https://storage.../presigned-url" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@photo.jpg"
```

### Use the public URL in your post

```json
{
  "mediaItems": [
    {"type": "image", "url": "https://media.zernio.com/temp/photo.jpg"}
  ]
}
```
</Steps>

<Callout type="info">
**Already have public URLs?** Skip the upload - just pass your URLs directly in `mediaItems`.
</Callout>

**Supported types:** `image/jpeg` `image/png` `image/webp` `image/gif` `video/mp4` `video/quicktime` `video/webm` `application/pdf`

---

## Step 6: Migrate Scheduled Posts

Don't lose your queued content! Export scheduled posts from Ayrshare and recreate them in Zernio.

**Export from Ayrshare:**
```bash
curl -X GET https://api.ayrshare.com/api/history \
  -H "Authorization: Bearer AYRSHARE_KEY" \
  -H "Profile-Key: PROFILE_KEY"
```

**Recreate in Zernio** for each post with a future `scheduleDate`:
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -d '{
    "content": "...",
    "platforms": [{"platform": "twitter", "accountId": "..."}],
    "scheduledFor": "2025-01-20T14:00:00Z"
  }'
```

Then delete or pause the Ayrshare posts to avoid duplicates.

---

## Cutover Strategy

<Callout type="warn">
**Don't switch all at once.** Use a gradual rollout to catch issues early.
</Callout>

| Phase | Actions |
|-------|---------|
| **Prep** | Create Zernio profiles, connect accounts, build integration |
| **Pilot** | Test with internal users for a few days |
| **Rollout** | Enable for 10% → 50% → 100% of users |
| **Cutoff** | Disable Ayrshare, keep keys for 30 days as fallback |

---

## Troubleshooting

| Error | Cause | Fix |
|-------|-------|-----|
| Invalid accountId | Using Ayrshare profile key | Use Zernio account `_id` from `/v1/accounts` |
| Platform not supported | Wrong platform name | Use `googlebusiness` not `gmb` |
| Media not found | URL inaccessible | Ensure HTTPS and publicly accessible |
| Post not publishing | Wrong date format | Use ISO 8601 UTC: `2025-01-15T10:00:00Z` |

---

## Code Example: Node.js

```javascript
// Zernio post function
const createPost = async (content, accounts, media = [], scheduledFor = null) => {
  const response = await fetch('https://zernio.com/api/v1/posts', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ZERNIO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      content,
      platforms: accounts, // [{platform: "twitter", accountId: "..."}]
      mediaItems: media.map(url => ({
        type: url.match(/\.(mp4|mov|webm)$/i) ? 'video' : 'image',
        url
      })),
      ...(scheduledFor ? { scheduledFor } : { publishNow: true })
    }),
  });

  const data = await response.json();
  return data.post._id;
};
```

---

## Need Help?

- **Zernio API Docs:** [docs.zernio.com](https://docs.zernio.com)
- **Support:** miki@zernio.com
- **Rate Limits:** 60-1,200 req/min, bucketed by your team's connected-account count (0-2: 60, 3-2,000: 600, 2,001+: 1,200) — see [/guides/rate-limits](/guides/rate-limits)

---