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.
API key authentication - use your Zernio API key as a Bearer token
In: header
Path Parameters
Platform to connect ads for. Only platforms with ads support are accepted.
"facebook" | "instagram" | "linkedin" | "tiktok" | "twitter" | "pinterest" | "googleads"Query Parameters
Your Zernio profile ID
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.
Custom redirect URL after OAuth completes (same-token platforms only)
uriEnable headless mode (same-token platforms only)
false(metaads only) Scope ad sync to a single Meta ad account. Without this
param, sync covers every act_* the connected token can see. Pass this
to limit sync.totalAds / synced and the resulting ads to one ad
account. Format: act_<digits> (matches what /me/adaccounts returns).
Validated against the connected token; unreachable IDs return 400.
For multiple accounts use adAccountIds instead.
^act_\d+$(metaads only) Scope ad sync to multiple Meta ad accounts. Repeat the
param (?adAccountIds=act_1&adAccountIds=act_2) or comma-separate
(?adAccountIds=act_1,act_2). Validated against the connected token.
Persisted server-side; latest call wins. Omitting both adAccountId
and adAccountIds keeps any previously persisted scope unchanged.
Response Body
application/json
application/json
import Zernio from '@zernio/node';const zernio = new Zernio({ apiKey: process.env.ZERNIO_API_KEY });const { data } = await zernio.connect.connectAds({ path: { platform: 'facebook', }, query: { profileId: 'profile_abc123', },});console.log(data);{
"alreadyConnected": true,
"accountId": "664a1b2c3d4e5f6789012345",
"platform": "instagram",
"username": "@mybrand",
"displayName": "My Brand"
}{
"error": "Unauthorized"
}Configure TikTok Ads Brand Identity PATCH
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.
Connect WhatsApp via credentials POST
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)