v2
latestOpenAPI 3.1.02026-08-075421692.0 MBConnect 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.
Path parameters
Platform to connect ads for. Only platforms with ads support are accepted.
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). Accepts an http(s) URL, a custom app scheme for mobile deeplinks (e.g. myapp://callback), or a relative path.
Enable headless mode (same-token platforms only)
Force a fresh OAuth even when an account already exists. Normally the endpoint returns alreadyConnected: true whenever a connected account is found, keying off its active state rather than token liveness. Set force=true to bypass that and always receivean authUrl. Completing the returned OAuth refreshes the stored token on the existing posting and ads accounts in place.
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.
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.
Response
Either an OAuth URL to redirect to, or confirmation that ads are already connected
Example response
{
"alreadyConnected": true,
"scopedAdAccountIds": [
"act_1330190928038136"
]
}