Zernio
Zernio
API Reference

Audiences

List custom audiencesGETCreate custom audiencePOSTGet audience detailsGETUpdate an audiencePUTDelete custom audienceDELETEAdd users to audiencePOSTReplace audience companiesPOST
Dashboard
llms.txtOpenAPI
OverviewPlatformsAPI ReferenceResources
Audiences

List custom audiences

Returns custom audiences for the given ad account. Supports Meta, Google, TikTok, Pinterest, LinkedIn, and X (Twitter).

PlatformsMetaGoogleTikTokLinkedInPinterestX
GET
/v1/ads/audiences

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication - use your Zernio API key as a Bearer token

In: header

Query Parameters

accountId*string

Social 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

{  "audiences": [    {      "id": "string",      "accountId": "string",      "platformAudienceId": "string",      "name": "string",      "description": "string",      "type": "customer_list",      "spec": {        "countries": [          "string"        ],        "regions": [          {            "key": "string",            "name": "string"          }        ],        "cities": [          {            "key": "string",            "name": "string",            "radius": 0,            "distanceUnit": "mile"          }        ],        "zips": [          {            "key": "string",            "name": "string"          }        ],        "metros": [          {            "key": "string",            "name": "string"          }        ],        "customLocations": [          {            "latitude": -90,            "longitude": -180,            "radius": 0,            "distanceUnit": "mile",            "name": "string",            "address": "string"          }        ],        "excludedLocations": {          "countries": [            "string"          ],          "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"        ],        "audienceInclude": [          "string"        ],        "audienceExclude": [          "string"        ]      },      "platform": "string",      "size": 0,      "status": "string"    }  ]}
Was this page helpful?

Upload an ad video

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. The endpoint waits until Meta reports the video ready (chunked upload + transcode can take minutes; the handler runs up to 800 s).

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; `company_list`, `engagement` and `website_retargeting` are LinkedIn-only. `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` 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.