Zernio
APIFor you
Zernio
APIFor you
API Reference

Audiences

List custom audiencesGETCreate custom audiencePOSTGet audience detailsGETUpdate an audiencePUTDelete custom audienceDELETEAdd users to audiencePOSTRemove users from audienceDELETEReplace audience companiesPOST
Dashboard
OverviewPlatformsAPI ReferenceResources
Audiences

List custom audiences

Lists the custom audiences in an ad account so you can reuse them for targeting.

Supports Meta, Google, TikTok, Pinterest, LinkedIn, and X.

PlatformsMetaGoogleTikTokLinkedInPinterestX
GET
/v1/ads/audiences

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication: send your Zernio API key in the Authorization header, prefixed with Bearer.

In: header

Query Parameters

accountId*string

Account ID

adAccountId*string

Platform ad account ID

platform?string

Value in

  • "facebook"
  • "instagram"
  • "googleads"
  • "tiktok"
  • "tiktokads"
  • "pinterest"
  • "linkedin"
  • "linkedinads"
  • "twitter"
  • "xads"
type?string

Filter to one audience type. saved_targeting returns stored TargetingSpec audiences; the other types return uploaded/derived audiences.

Value in

  • "customer_list"
  • "company_list"
  • "engagement"
  • "meta_engagement"
  • "website"
  • "website_retargeting"
  • "lookalike"
  • "saved_targeting"

Response Body

application/json

application/json

application/json

application/json

application/json

import Zernio from '@zernio/node';const zernio = new Zernio({ apiKey: process.env.ZERNIO_API_KEY });const { data } = await zernio.adaudiences.listAdAudiences({  query: {    accountId: 'account_abc123',    adAccountId: 'adaccount_abc123',  },});console.log(data);
{  "audiences": [    {      "id": "string",      "accountId": "string",      "platformAudienceId": "string",      "name": "string",      "description": "string",      "type": "customer_list",      "spec": {        "userOs": [          "string"        ],        "userDevice": [          "string"        ],        "countries": [          "string"        ],        "regions": [          "string"        ],        "cities": [          "string"        ],        "zips": [          {            "key": "string",            "name": "string"          }        ],        "metros": [          {            "key": "string",            "name": "string"          }        ],        "countryGroups": [          "africa"        ],        "customLocations": [          {            "latitude": -90,            "longitude": -180,            "radius": 0,            "distanceUnit": "mile",            "name": "string",            "address": "string"          }        ],        "excludedLocations": {          "countries": [            "string"          ],          "countryGroups": [            "africa"          ],          "regions": [            {              "key": "string",              "name": "string"            }          ],          "cities": [            {              "key": "string",              "radius": 0,              "distanceUnit": "mile"            }          ],          "zips": [            {              "key": "string",              "name": "string"            }          ],          "places": [            {              "key": "string"            }          ],          "neighborhoods": [            {              "key": "string"            }          ],          "customLocations": [            {              "latitude": -90,              "longitude": -180,              "radius": 0,              "distanceUnit": "mile",              "name": "string",              "address": "string"            }          ]        },        "ageMin": 13,        "ageMax": 13,        "gender": "all",        "incomeTier": "top_5",        "languages": [          "string"        ],        "interests": [          {            "id": "string",            "name": "string"          }        ],        "behaviors": [          {            "id": "string",            "name": "string"          }        ],        "workPositions": [          {            "id": "string",            "name": "string"          }        ],        "workEmployers": [          {            "id": "string",            "name": "string"          }        ],        "workIndustries": [          {            "id": "string",            "name": "string"          }        ],        "industries": [          "string"        ],        "companySizes": [          "string"        ],        "seniorities": [          "string"        ],        "jobFunctions": [          "string"        ],        "skills": [          "string"        ],        "audienceInclude": [          "string"        ],        "audienceExclude": [          "string"        ],        "communities": [          "string"        ],        "excludedCommunities": [          "string"        ],        "conversationKeywords": [          "string"        ],        "excludedConversationKeywords": [          "string"        ]      },      "platform": "string",      "size": 0,      "status": "string"    }  ]}
Was this page helpful?

Upload an ad video

Uploads a video to a Meta ad account from a URL or file, so you can preview it or use it in ads before any ad exists. Standalone ad-video upload (parallel to POST /v1/ads/images), so a video creative can be rendered via POST /v1/ads/preview or attached via `video.id` on POST /v1/ads/create before an ad exists. Accepts either an https `videoUrl` we download server-side (SSRF-guarded) or raw `videoBase64` bytes; exactly one is required. `videoBase64` is capped by Vercel's body limit, around 4.5 MB payload in practice, so larger videos must come via `videoUrl`. Returns the Meta `video.id` (reusable wherever `video.id` is accepted) plus Meta's auto-generated poster URL when available. By default the endpoint waits until Meta reports the video ready (chunked upload + transcode can take minutes; the handler runs up to 800 s) and answers 201. **Async mode.** Send `async: true` to get a 202 as soon as Meta has accepted the bytes, with `video.status: processing`. Then either poll `GET /v1/ads/videos/{videoId}` until `status` is `ready`, or subscribe to the `ad.video.processed` webhook. A create call that references the video while it is still processing waits up to 30 s, then answers 409 `invalid_resource_state` naming the status endpoint. With `videoUrl` the download and byte transfer still happen inside the request; only Meta's transcode is skipped.

Create custom audience

Creates a custom audience from a customer list, website visitors, a lookalike, or people who engaged with your content. `customer_list` is supported on Meta, Google, X, LinkedIn, TikTok, and Pinterest. `website` (pixel/tag visitors) and `lookalike` are supported on Meta, TikTok, Pinterest and Google. `meta_engagement` is Meta-only, `tiktok_engagement` TikTok-only, `pinterest_engagement` Pinterest-only; `company_list`, `engagement` and `website_retargeting` are LinkedIn-only. A type sent to a platform that does not support it is a 422 `FEATURE_NOT_AVAILABLE`. Per-platform rules for `website`: - Meta: `pixelId` required, `retentionDays` 1-180, optional `urlContains` or raw `rule`. `event` is not accepted. - TikTok: `pixelId` required, `retentionDays` one of 7, 14, 30, 60, 90, 180. `event` is a TikTok pixel event (default `PAGE BROWSE`; also `CLICK BUTTON`, `PIXEL SUBMIT FORM`, `CONTACT`, `DOWNLOAD`, `PIXEL ADD PAYMENT INFO`, `COMPLETE PAYMENT`, `INITIATE CHECKOUT`, `COMPLETE REGISTRATION`, `PRODUCT DETAIL PAGE BROWSE`, `PIXEL SEARCH`, `PIXEL ADD TO CART`, `PLACE AN ORDER`, `PIXEL ADD TO WISHLIST`, `PIXEL SUBSCRIBE`), optional `urlContains`. - Pinterest: `pixelId` is the Pinterest tag id, `retentionDays` 1-540, optional `event` (e.g. `checkout`, `addtocart`). Pinterest matches URLs exactly, so `urlContains` is a 400 there. - Google: no `pixelId` (the account's Google tag is used), `retentionDays` 1-540, `urlContains` defaults to `/` (all visitors). Built as a rule-based user list with prepopulation requested. Per-platform rules for `lookalike`: Meta takes `ratio` (0.01-0.20); Pinterest takes `ratio` in whole percents (0.01-0.10) and `country` US, CA or GB; TikTok and Google take `size` (narrow, balanced, broad) instead of `ratio`. TikTok needs a seed with at least 1,000 matched people. `saved_targeting` stores a reusable TargetingSpec (no member upload, no adAccountId) that you reference later via `savedTargetingId` on `POST /v1/ads/create`. How the audience gets filled depends on the type: - `customer_list` is created empty. Add members with `POST /v1/ads/audiences/{audienceId}/users`. On TikTok and Pinterest the audience is provisioned lazily on that first upload (until then its status is `pending`). - `company_list` is filled AT CREATION from the `companies` array below, which is required. To change the list afterwards send the new full list to `POST /v1/ads/audiences/{audienceId}/companies` (a replace, not a merge). The `/users` endpoint rejects these audiences with a 422. - `website`, `website_retargeting`, `engagement`, `meta_engagement`, `tiktok_engagement`, `pinterest_engagement` and `lookalike` fill themselves from the pixel, engagement source or seed audience you point them at. They take no member upload at all. Create is not idempotent, never auto-retry.