TikTok Custom Audiences - TikTok Ads API

Create and manage TikTok Custom Audiences via TikTok Marketing API. Upload customer files with auto-hashing, create lookalike audiences, manage segments for TikTok advertising campaigns.

Features

Audience Management

• create_audience - Create a new custom audience
• get_audience - Get details of a specific audience
• list_audiences - List all custom audiences
• update_audience - Update audience name
• delete_audience - Delete a custom audience

User Management

• upload_users - Upload users to audience (auto-hashes PII)
• get_audience_size - Get audience size and status

Advanced Features

• create_lookalike - Create lookalike audience from source
• share_audience - Share audience with another advertiser

Quick Start

{
  "input": "your input here"
}

Demo Mode

Set demoMode: true to test with sample data (no charges). When you're ready for real results, set demoMode: false or omit it.

{
  "demoMode": true,
  ...
}

Input Parameters

Parameter	Type	Required	Description
See input schema

Output Format

Audience Object

{
  "audience_id": "7123456789012345678",
  "name": "High Value Customers",
  "audience_type": "CUSTOMER_FILE",
  "cover_num": 15420,
  "is_valid": true,
  "is_expiring": false,
  "create_time": "2024-01-20 14:30:00",
  "modify_time": "2024-01-21 10:15:00"
}

Upload Response

{
  "audience_id": "7123456789012345678",
  "upload_num": 1000,
  "match_num": 650,
  "match_rate": 65.0,
  "status": "PROCESSING"
}

Pricing

This actor uses pay-per-event billing: $0.01 per query (all tasks)

Use Cases

Retarget Customers

1. Export customer emails from CRM
2. Use upload_users with fileType: EMAIL
3. Create TikTok ad campaigns targeting the audience

Expand Reach

1. Create audience of best customers
2. Use create_lookalike with BALANCED type
3. Reach similar users on TikTok

Cross-Account Sharing

1. Create audience in main account
2. Use share_audience with agency account ID
3. Agency can target same audience

---

Common Problems & Solutions

"Invalid API key" error

Cause: Your API key is wrong, expired, or doesn't have the right permissions. Fix: Double-check your API key. Make sure you copied it exactly without extra spaces.

"Rate limit exceeded" error

Cause: You've hit the API's rate limits. Fix: Wait a few minutes, then try again. Consider reducing the number of concurrent requests.

Empty or incomplete results

Cause: The target may have anti-scraping protection or the data doesn't exist. Fix:

• Check if the URL/search query is correct
• Try with different parameters
• Some sites may block automated access

Demo data showing instead of real results

Cause: demoMode is still set to true. Fix: Set demoMode: false and provide your API key(s).

---

Built by John Rippy | Actor Arsenal