Audiences & Targeting

Custom Audiences

Create a customer-file Custom Audience with POST /v1/ads/audiences (type: "customer_list"). Then upload members with POST /v1/ads/audiences/{audienceId}/users.

adAccountId is the TikTok advertiser id.

TikTok matches on email only (any phone is ignored). Values are SHA-256 hashed server-side.

The audience is created lazily on the first member upload, because TikTok needs the member file at creation time. The create records it with status pending (no platform id yet). The first users call provisions it on TikTok.

A new audience takes up to 48 hours to finish processing before it is targetable.

const { data: audience } = await zernio.adaudiences.createAdAudience({
  body: {
    accountId: '66b2e19d8c3f5a7e9d0b1c2d',
    adAccountId: '7123456789012345678',
    type: 'customer_list',
    name: 'Cart abandoners'
  }
});

const { data: upload } = await zernio.adaudiences.addUsersToAdAudience({
  path: { audienceId: audience.audience.id },
  body: { users: [{ email: 'jane@example.com' }, { email: 'sam@example.com' }] }
});

console.log(upload.numReceived);

Response (201):

{
  "audience": { "id": "66e5b2c3d4f5a6b7c8d9e0f1", "name": "Cart abandoners", "type": "customer_list", "platform": "tiktok", "status": "pending" },
  "message": "Audience created"
}

Response (200):

{ "message": "Users added", "numReceived": 2, "numInvalid": 0 }

Targeting fields

These fields apply on create:

• countries, ageMin, ageMax, gender
• languages (ISO 639-1; zh_TW targets traditional Chinese)
• interests (from GET /v1/ads/interests)
• behaviors
• regions, cities, zips, metros
• incomeTier

audienceInclude and audienceExclude take the platformAudienceId of a processed Custom Audience.

behaviors are TikTok's video and creator interaction categories, from GET /v1/ads/targeting/search?dimension=behavior. Ids look like:

• video:1913101: people who watched to the end, liked, commented on or shared videos in that category in the last 15 days.
• creator:24001: people who followed or viewed the profile of creators in that category.

TikTok only accepts behaviors with the TikTok placement. When behaviors is set, the ad group runs on TikTok alone.

To change targeting after creation, see Targeting update after creation.