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

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.

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, or lookalike audience (uploaded or derived from a source).

Response Body

application/json

application/json

{  "audience": {},  "message": "string"}
Was this page helpful?

List custom audiences

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

Get audience details

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"
  • "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

Required for website audiences

retentionDays?integer

Required for website (max 180) and meta_engagement (max 365) audiences.

Range1 <= value <= 365
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 only. The engagement event; defaults per source (page → page_engaged, instagram → ig_business_profile_all, video → video_watched). Ignored when rule is provided.

sourceAudienceId?string

Required for lookalike audiences

country?string

2-letter code, required for lookalike audiences

ratio?number

Required for lookalike audiences

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

website only. Narrows the audience from all visitors to visitors of URLs containing this substring. Ignored when rule is supplied.

rule?

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)