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

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.

PlatformsMetaGoogleTikTokLinkedInPinterestX
POST
/v1/ads/audiences

Authorization

bearerAuth
AuthorizationBearer <token>

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

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

customer_list, website, lookalike or engagement audience (uploaded or derived from a source).

Response Body

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.createAdAudience({  body: {    accountId: 'account_abc123',    adAccountId: 'adaccount_abc123',    name: 'Example',    type: 'customer_list',  },});console.log(data);
{  "audience": {},  "message": "string"}
Was this page helpful?

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.

Get audience details

Shows a custom audience's details, including its latest data from the ad platform when available. Returns the local audience record and fresh data from Meta (if available).

accountId*string
adAccountId*string

Platform ad account ID. Must start with act_ for Meta; bare platform id for others (Google customer id, X/TikTok/LinkedIn/Pinterest account id).

name*string
Lengthlength <= 255
description?string
type*string

Value in

  • "customer_list"
  • "company_list"
  • "engagement"
  • "meta_engagement"
  • "tiktok_engagement"
  • "pinterest_engagement"
  • "website"
  • "website_retargeting"
  • "lookalike"
matchRules?array<>

Required for website_retargeting audiences (LinkedIn only). Each rule is a URL pattern; a member who visits any matching page enters the segment. Needs the LinkedIn Insight Tag installed on the customer's site; the segment only starts filling once the tag reports visits.

The response's platformAudienceId is the LinkedIn adSegment id, valid for downstream use. These segments appear in GET /v1/ads/audiences with type: website_retargeting once LinkedIn has finished building them.

Items1 <= items <= 50
sourceType?string

Required for engagement audiences (LinkedIn only): what members engaged with: a video/leadgen/single-image ad campaign, a Company Page or an Event page.

Value in

  • "VIDEO_ADS"
  • "LEAD_GEN_FORMS"
  • "ORGANIZATION_PAGES"
  • "EVENT_PAGES"
  • "SINGLE_IMAGE_ADS"
trigger?string

Required for engagement audiences. The action, validated by LinkedIn against sourceType. Common values: VIDEO_ADS FIRST_QUARTILE / MIDPOINT / THIRD_QUARTILE / FULL_COMPLETE; LEAD_GEN_FORMS VIEW_FORM / LEAD_FORM_SUBMIT; ORGANIZATION_PAGES VIEW / CTA_CLICK; EVENT_PAGES RSVPED / VIDEO_VIEWED / ENGAGEMENT / CLICK.

lookbackDays?integer

Required for engagement audiences. Rolling window.

Value in

  • 30
  • 60
  • 90
  • 180
  • 365
engagementSources?array<string>

Required for engagement audiences. Campaign URNs for the ad source types, organization URNs for pages and events. LinkedIn creates one rule per source, all sharing the same trigger and lookbackDays.

Items1 <= items <= 50
companies?array<>

Required for company_list audiences (LinkedIn only): plain-text company rows for account targeting. Each row needs at least one identifier. Not hashed, LinkedIn matches these against its own company graph. LinkedIn recommends 1,000+ companies for a usable match rate and takes up to 48h to process the list. Replace the list later with POST /v1/ads/audiences/{audienceId}/companies.

Items1 <= items <= 300000
pixelId?string

website: the Meta pixel, TikTok pixel or Pinterest tag id. Required on those three, rejected on Google.

retentionDays?integer

Required for website (Meta max 180, TikTok 7/14/30/60/90/180, Pinterest and Google max 540), meta_engagement (max 365) and tiktok_engagement (7/14/30/60/90/180; organic and live video and most business-account events only 7/14/30).

Range1 <= value <= 540
engagementSource?string

Required for meta_engagement audiences (Meta only): what people engaged with. page = a Facebook Page, instagram = an IG professional account, video = a video.

Value in

  • "page"
  • "instagram"
  • "video"
sourceId?string

Required for meta_engagement: the Page / IG account / video id.

event?string

meta_engagement: the engagement event; defaults per source (page → page_engaged, instagram → ig_business_profile_all, video → video_watched). Ignored when rule is provided.

website on TikTok: the pixel event (default PAGE BROWSE). website on Pinterest: the tag event (pagevisit, signup, checkout, viewcategory, search, addtocart, watchvideo, lead, custom or a partner-defined event).

tiktok_engagement (required): the TikTok engagement event, validated per source (TikTok's filter values, spaces included):

  • ads: CLICK, IMPRESSION, PLAY 2S, PLAY 6S, PLAY 25, PLAY 50, PLAY 75, PLAY OVER, and the ENGAGEMENT APP PROFILE / ENGAGEMENT TIKTOK INSTANT / ENGAGEMENT COLLECTION ADS CLICK and IMPRESSION events.
  • organic_video: ORGANIC VIDEO PLAY 2S, ORGANIC VIDEO PLAY 6S, ORGANIC VIDEO PLAY OVER, ORGANIC VIDEO ENGAGEMENT.
  • live_video: LIVE VIDEO VIEW, LIVE VIDEO ENGAGEMENT.
  • business_account: BUSINESS ACCOUNT PROFILE FOLLOW, BUSINESS ACCOUNT PROFILE VISIT, BUSINESS ACCOUNT ENGAGEMENT, BUSINESS ACCOUNT PLAY 2S, BUSINESS ACCOUNT PLAY 6S, BUSINESS ACCOUNT PLAY OVER and the rest of TikTok's business-account events. An unknown value is a 400 that lists the valid ones.
Lengthlength <= 100
sourceAudienceId?string

Required for lookalike audiences

country?string

2-letter code, required for lookalike audiences

ratio?number

lookalike on Meta (0.01-0.20) and Pinterest (0.01-0.10, whole percents). Rejected on TikTok and Google.

Range0.01 <= value <= 0.2
size?string

lookalike on TikTok and Google: audience breadth. Rejected on Meta and Pinterest.

Value in

  • "narrow"
  • "balanced"
  • "broad"
source?string

Required for tiktok_engagement: what people engaged with.

Value in

  • "ads"
  • "organic_video"
  • "live_video"
  • "business_account"
sourceIds?array<string>

tiktok_engagement: ad group / campaign ids for ads, video ids for organic_video and live_video (max 10). Required except for business_account.

Items1 <= items <= 50
identityId?string

tiktok_engagement: the TikTok identity that owns the videos or business account. Required for organic_video, live_video and business_account.

identityType?string

tiktok_engagement: type of identityId.

Value in

  • "TT_USER"
  • "BC_AUTH_TT"
identityAuthorizedBcId?string

tiktok_engagement: required when identityType is BC_AUTH_TT.

engagerType?integer

pinterest_engagement: Pinterest's engager_type, passed through when set.

Value in

  • 1
  • 2
engagementType?string

pinterest_engagement: limit to one engagement action.

Value in

  • "click"
  • "save"
  • "closeup"
  • "comment"
  • "like"
engagementDomains?array<string>

pinterest_engagement: people who engaged with Pins from these domains. The domain must be claimed on the Pinterest account or Pinterest rejects it.

campaignIds?array<>

pinterest_engagement: people who engaged with these campaigns' ads.

adIds?array<>

pinterest_engagement: people who engaged with these ads.

pinIds?array<>

pinterest_engagement: people who engaged with these Pins. At least one of engagementDomains, campaignIds, adIds or pinIds is required.

urlContains?string

website on Meta, TikTok and Google. Narrows the audience from all visitors to visitors of URLs containing this substring. Ignored when rule is supplied. A 400 on Pinterest, which only matches exact URLs.

rule?

Meta only (a 400 elsewhere). Optional raw Meta rule, replacing the one we build. Omit it for all visitors of pixelId, or use urlContains for the common page-match case.

For website this is Meta's Flexible Audience Rule and is VALIDATED before we call Meta: every entry in inclusions.rules (and exclusions.rules) must carry event_sources, retention_seconds AND filter. Meta rejects a rule missing any of the three with code 100 / subcode 1713098 ("Invalid rule JSON format"), so a bad shape is a 400 here instead. The pre-2018 flat shapes ({url: ...}, {event: ...}) are not accepted by Meta at all (subcode 1870029).

Example, visitors of /checkout in the last 30 days: {"inclusions":{"operator":"or","rules":[{"event_sources":[{"id":"<pixelId>","type":"pixel"}],"retention_seconds":2592000,"filter":{"operator":"and","filters":[{"field":"url","operator":"i_contains","value":"/checkout"}]}}]}}

Note Meta DERIVES retention_days from retention_seconds and stores event_sources[].id as a number, so a rule read back will not be byte-identical to the one you sent.

For meta_engagement the rule is forwarded verbatim and NOT validated: that type has two dialects (the video source uses a legacy flat array), so no single schema covers both.

customerFileSource?string

Data source declaration for GDPR compliance (customer_list only)