TikTok Ads - Lava Documentation

TikTok’s official Marketing API for managing the full lifecycle of TikTok ad campaigns on behalf of authorized advertisers — advertiser discovery, campaigns, ad groups, ads, audiences, custom audiences, creatives, pixels, conversion events, and reporting. Best for agents that need to launch, optimize, or report on TikTok ads through TikTok For Business accounts. Unlike aggregator marketing platforms, this is a first-party surface that exposes TikTok-specific targeting (interests, behaviors, hashtags) and granular reporting breakdowns (placement, creative, audience). 14 example endpoints available through Lava’s AI Gateway. See the TikTok Ads API docs for full documentation.

This provider requires your own credentials — connect your API key or OAuth account before use.

This is a catch-all provider — any valid URL under https://business-api.tiktok.com is supported. TikTok Marketing API. Base URL: https://business-api.tiktok.com/open_api/v1.3. Auth header is Access-Token: <token> (NOT Authorization: Bearer). Discover advertiser_ids via GET /oauth2/advertiser/get/. Most resources are scoped to an advertiser_id query param, e.g. /campaign/get/?advertiser_id=…&campaign_ids=[…]. Responses are wrapped in an envelope: { code, message, request_id, data } — non-zero code indicates an error. Pagination uses page/page_size query params and returns data.page_info { page, page_size, total_number, total_page }. Reports endpoint (GET /report/integrated/get/) accepts breakdowns, dimensions, metrics, and date ranges as query params. See https://business-api.tiktok.com/portal/docs for full reference. The endpoints below are curated examples.

Endpoints

List advertisers that have granted this app permission to manage their accounts. Start here after OAuth to discover the advertiser_ids the user authorized; every other endpoint takes one of these as a query param. Requires app_id and secret as query params alongside the user’s Access-Token.

GET https://business-api.tiktok.com/open_api/v1.3/oauth2/advertiser/get/?app_id={app_id}&secret={secret} — Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/oauth2/advertiser/get/?app_id={app_id}&secret={secret}', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Foauth2%2Fadvertiser%2Fget%2F%3Fapp_id%3D%7Bapp_id%7D%26secret%3D%7Bsecret%7D" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

Fetch details for one or more advertisers — currency, time zone, status, balance, contact info. Useful for confirming an authorized advertiser_id is active before further calls.

GET https://business-api.tiktok.com/open_api/v1.3/advertiser/info/?advertiser_ids=["{advertiser_id}"] — Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/advertiser/info/?advertiser_ids=["{advertiser_id}"]', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Fadvertiser%2Finfo%2F%3Fadvertiser_ids%3D%5B%22%7Badvertiser_id%7D%22%5D" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

List campaigns under an advertiser. Paginated via page/page_size; response envelope includes data.page_info { page, page_size, total_number, total_page }. Filterable by status, objective_type, budget_mode.

GET https://business-api.tiktok.com/open_api/v1.3/campaign/get/?advertiser_id={advertiser_id}&page=1&page_size=20 — Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/campaign/get/?advertiser_id={advertiser_id}&page=1&page_size=20', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Fcampaign%2Fget%2F%3Fadvertiser_id%3D%7Badvertiser_id%7D%26page%3D1%26page_size%3D20" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

Create a new campaign under an advertiser. Required: advertiser_id, campaign_name, objective_type (TRAFFIC, CONVERSIONS, REACH, VIDEO_VIEWS, LEAD_GENERATION, etc.), budget_mode, budget. New campaigns default to DISABLE; activate via campaign/update/.

POST https://business-api.tiktok.com/open_api/v1.3/campaign/create/ — Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/campaign/create/', {
  body: {
"advertiser_id": "{advertiser_id}",
"campaign_name": "Q2 Awareness Campaign",
"objective_type": "TRAFFIC",
"budget_mode": "BUDGET_MODE_DAY",
"budget": 50
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Fcampaign%2Fcreate%2F" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id":"{advertiser_id}","campaign_name":"Q2 Awareness Campaign","objective_type":"TRAFFIC","budget_mode":"BUDGET_MODE_DAY","budget":50}'

Update campaign settings. Common: campaign_name, budget, operation_status (ENABLE / DISABLE / DELETE). Only fields included are modified.

POST https://business-api.tiktok.com/open_api/v1.3/campaign/update/ — Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/campaign/update/', {
  body: {
"advertiser_id": "{advertiser_id}",
"campaign_id": "{campaign_id}",
"operation_status": "ENABLE"
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Fcampaign%2Fupdate%2F" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id":"{advertiser_id}","campaign_id":"{campaign_id}","operation_status":"ENABLE"}'

List ad groups under an advertiser (optionally filtered by campaign_ids). Ad groups carry targeting, placement, bidding, schedule, and conversion event settings.

GET https://business-api.tiktok.com/open_api/v1.3/adgroup/get/?advertiser_id={advertiser_id}&page=1&page_size=20 — Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/adgroup/get/?advertiser_id={advertiser_id}&page=1&page_size=20', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Fadgroup%2Fget%2F%3Fadvertiser_id%3D%7Badvertiser_id%7D%26page%3D1%26page_size%3D20" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

Create an ad group under a campaign. Key fields: campaign_id, adgroup_name, placement_type, placements, billing_event (CPC, CPM, OCPM), bid_type, bid_price, schedule_type, schedule_start_time, location_ids, audience_ids, interests, pixel_id (for conversion ad groups).

POST https://business-api.tiktok.com/open_api/v1.3/adgroup/create/ — Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/adgroup/create/', {
  body: {
"advertiser_id": "{advertiser_id}",
"campaign_id": "{campaign_id}",
"adgroup_name": "US — programmers",
"placement_type": "PLACEMENT_TYPE_NORMAL",
"placements": [
  "PLACEMENT_TIKTOK"
],
"location_ids": [
  "6252001"
],
"billing_event": "CPC",
"bid_type": "BID_TYPE_CUSTOM",
"bid_price": 0.5,
"budget_mode": "BUDGET_MODE_DAY",
"budget": 20,
"schedule_type": "SCHEDULE_FROM_NOW",
"operation_status": "DISABLE"
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Fadgroup%2Fcreate%2F" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id":"{advertiser_id}","campaign_id":"{campaign_id}","adgroup_name":"US — programmers","placement_type":"PLACEMENT_TYPE_NORMAL","placements":["PLACEMENT_TIKTOK"],"location_ids":["6252001"],"billing_event":"CPC","bid_type":"BID_TYPE_CUSTOM","bid_price":0.5,"budget_mode":"BUDGET_MODE_DAY","budget":20,"schedule_type":"SCHEDULE_FROM_NOW","operation_status":"DISABLE"}'

List ads under an advertiser (filterable by campaign_ids or adgroup_ids). Each ad references a creative (video_id or image_ids) and an ad group, inheriting targeting from the ad group.

GET https://business-api.tiktok.com/open_api/v1.3/ad/get/?advertiser_id={advertiser_id}&page=1&page_size=20 — Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/ad/get/?advertiser_id={advertiser_id}&page=1&page_size=20', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Fad%2Fget%2F%3Fadvertiser_id%3D%7Badvertiser_id%7D%26page%3D1%26page_size%3D20" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

Create one or more ads under an ad group. Each ad in `creatives[]` needs ad_name, ad_format, video_id (or image_ids), ad_text, call_to_action, and landing_page_url.

POST https://business-api.tiktok.com/open_api/v1.3/ad/create/ — Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/ad/create/', {
  body: {
"advertiser_id": "{advertiser_id}",
"adgroup_id": "{adgroup_id}",
"creatives": [
  {
    "ad_name": "Programmers — Q2 traffic ad",
    "ad_format": "SINGLE_VIDEO",
    "video_id": "{video_id}",
    "ad_text": "Build faster with our AI tools.",
    "call_to_action": "LEARN_MORE",
    "landing_page_url": "https://example.com/lp"
  }
]
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Fad%2Fcreate%2F" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id":"{advertiser_id}","adgroup_id":"{adgroup_id}","creatives":[{"ad_name":"Programmers — Q2 traffic ad","ad_format":"SINGLE_VIDEO","video_id":"{video_id}","ad_text":"Build faster with our AI tools.","call_to_action":"LEARN_MORE","landing_page_url":"https://example.com/lp"}]}'

List custom audiences (CUSTOMER_FILE, ENGAGEMENT, WEB, APP, LOOKALIKE, etc.) under an advertiser. Use these as targeting building blocks for ad groups.

GET

https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/list/?advertiser_id={advertiser_id}&page=1&page_size=20

— Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/list/?advertiser_id={advertiser_id}&page=1&page_size=20', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Fdmp%2Fcustom_audience%2Flist%2F%3Fadvertiser_id%3D%7Badvertiser_id%7D%26page%3D1%26page_size%3D20" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

Create a customer-file custom audience. Identifiers must be SHA-256 hashed before upload (TikTok will not hash for you). After creation, use /dmp/custom_audience/file/upload/ to add hashed identifiers in batches.

POST https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/create/ — Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/create/', {
  body: {
"advertiser_id": "{advertiser_id}",
"custom_audience_name": "Newsletter subscribers — May",
"audience_sub_type": "NORMAL"
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Fdmp%2Fcustom_audience%2Fcreate%2F" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id":"{advertiser_id}","custom_audience_name":"Newsletter subscribers — May","audience_sub_type":"NORMAL"}'

List TikTok Pixels for an advertiser. Required to find a pixel_id for conversion-based ad groups and for sending server-side events via the Events API.

GET https://business-api.tiktok.com/open_api/v1.3/pixel/list/?advertiser_id={advertiser_id} — Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/pixel/list/?advertiser_id={advertiser_id}', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Fpixel%2Flist%2F%3Fadvertiser_id%3D%7Badvertiser_id%7D" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

TikTok Events API — post a single server-side pixel event. Body fields: pixel_code, event (e.g. CompletePayment), event_id (for deduplication with browser pixel), timestamp (Unix seconds), and context.user identifiers (email, phone_number, external_id — all pre-hashed SHA-256). Optional properties for value/currency/content_id. Used for offline / CRM / CAPI conversion tracking.

POST https://business-api.tiktok.com/open_api/v1.3/pixel/track/ — Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/pixel/track/', {
  body: {
"pixel_code": "{pixel_code}",
"event": "CompletePayment",
"event_id": "order_12345",
"timestamp": 1747008000,
"context": {
  "user": {
    "email": "{sha256_hashed_email}",
    "phone_number": "{sha256_hashed_phone}"
  }
},
"properties": {
  "value": 49.99,
  "currency": "USD"
}
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Fpixel%2Ftrack%2F" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pixel_code":"{pixel_code}","event":"CompletePayment","event_id":"order_12345","timestamp":1747008000,"context":{"user":{"email":"{sha256_hashed_email}","phone_number":"{sha256_hashed_phone}"}},"properties":{"value":49.99,"currency":"USD"}}'

Integrated reporting — pull synchronous performance metrics for an advertiser. Specify report_type (BASIC, AUDIENCE, PLAYABLE_MATERIAL), data_level (AUCTION_CAMPAIGN, AUCTION_ADGROUP, AUCTION_AD, AUCTION_ADVERTISER), dimensions (campaign_id, adgroup_id, stat_time_day, country_code, etc.), metrics (impressions, clicks, spend, cpc, ctr, conversions, conversion_rate), and date_range (start_date / end_date YYYY-MM-DD). Returns paginated rows.

GET

https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/?advertiser_id={advertiser_id}&report_type=BASIC&data_level=AUCTION_CAMPAIGN&dimensions=["campaign_id","stat_time_day"]&metrics=["impressions","clicks","spend","cpc","ctr","conversion"]&start_date=2026-05-01&end_date=2026-05-11&page=1&page_size=100

— Free

SDK
cURL

const data = await lava.gateway('https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/?advertiser_id={advertiser_id}&report_type=BASIC&data_level=AUCTION_CAMPAIGN&dimensions=["campaign_id","stat_time_day"]&metrics=["impressions","clicks","spend","cpc","ctr","conversion"]&start_date=2026-05-01&end_date=2026-05-11&page=1&page_size=100', { method: 'GET' });

curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fbusiness-api.tiktok.com%2Fopen_api%2Fv1.3%2Freport%2Fintegrated%2Fget%2F%3Fadvertiser_id%3D%7Badvertiser_id%7D%26report_type%3DBASIC%26data_level%3DAUCTION_CAMPAIGN%26dimensions%3D%5B%22campaign_id%22%2C%22stat_time_day%22%5D%26metrics%3D%5B%22impressions%22%2C%22clicks%22%2C%22spend%22%2C%22cpc%22%2C%22ctr%22%2C%22conversion%22%5D%26start_date%3D2026-05-01%26end_date%3D2026-05-11%26page%3D1%26page_size%3D100" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"

Next Steps

All Providers

Browse all supported AI providers

Forward Proxy

Learn how to construct proxy URLs and authenticate requests

⌘I

​Endpoints

​List advertisers that have granted this app permission to manage their accounts. Start here after OAuth to discover the advertiser_ids the user authorized; every other endpoint takes one of these as a query param. Requires app_id and secret as query params alongside the user’s Access-Token.

​Fetch details for one or more advertisers — currency, time zone, status, balance, contact info. Useful for confirming an authorized advertiser_id is active before further calls.

​List campaigns under an advertiser. Paginated via page/page_size; response envelope includes data.page_info { page, page_size, total_number, total_page }. Filterable by status, objective_type, budget_mode.

​Create a new campaign under an advertiser. Required: advertiser_id, campaign_name, objective_type (TRAFFIC, CONVERSIONS, REACH, VIDEO_VIEWS, LEAD_GENERATION, etc.), budget_mode, budget. New campaigns default to DISABLE; activate via campaign/update/.

​Update campaign settings. Common: campaign_name, budget, operation_status (ENABLE / DISABLE / DELETE). Only fields included are modified.

​List ad groups under an advertiser (optionally filtered by campaign_ids). Ad groups carry targeting, placement, bidding, schedule, and conversion event settings.

​Create an ad group under a campaign. Key fields: campaign_id, adgroup_name, placement_type, placements, billing_event (CPC, CPM, OCPM), bid_type, bid_price, schedule_type, schedule_start_time, location_ids, audience_ids, interests, pixel_id (for conversion ad groups).

​List ads under an advertiser (filterable by campaign_ids or adgroup_ids). Each ad references a creative (video_id or image_ids) and an ad group, inheriting targeting from the ad group.

​Create one or more ads under an ad group. Each ad in creatives[] needs ad_name, ad_format, video_id (or image_ids), ad_text, call_to_action, and landing_page_url.

​List custom audiences (CUSTOMER_FILE, ENGAGEMENT, WEB, APP, LOOKALIKE, etc.) under an advertiser. Use these as targeting building blocks for ad groups.

​Create a customer-file custom audience. Identifiers must be SHA-256 hashed before upload (TikTok will not hash for you). After creation, use /dmp/custom_audience/file/upload/ to add hashed identifiers in batches.

​List TikTok Pixels for an advertiser. Required to find a pixel_id for conversion-based ad groups and for sending server-side events via the Events API.

​Next Steps

All Providers

Forward Proxy

Endpoints

List advertisers that have granted this app permission to manage their accounts. Start here after OAuth to discover the advertiser_ids the user authorized; every other endpoint takes one of these as a query param. Requires app_id and secret as query params alongside the user’s Access-Token.

Fetch details for one or more advertisers — currency, time zone, status, balance, contact info. Useful for confirming an authorized advertiser_id is active before further calls.

List campaigns under an advertiser. Paginated via page/page_size; response envelope includes data.page_info { page, page_size, total_number, total_page }. Filterable by status, objective_type, budget_mode.

Create a new campaign under an advertiser. Required: advertiser_id, campaign_name, objective_type (TRAFFIC, CONVERSIONS, REACH, VIDEO_VIEWS, LEAD_GENERATION, etc.), budget_mode, budget. New campaigns default to DISABLE; activate via campaign/update/.

Update campaign settings. Common: campaign_name, budget, operation_status (ENABLE / DISABLE / DELETE). Only fields included are modified.

List ad groups under an advertiser (optionally filtered by campaign_ids). Ad groups carry targeting, placement, bidding, schedule, and conversion event settings.

Create an ad group under a campaign. Key fields: campaign_id, adgroup_name, placement_type, placements, billing_event (CPC, CPM, OCPM), bid_type, bid_price, schedule_type, schedule_start_time, location_ids, audience_ids, interests, pixel_id (for conversion ad groups).

List ads under an advertiser (filterable by campaign_ids or adgroup_ids). Each ad references a creative (video_id or image_ids) and an ad group, inheriting targeting from the ad group.

Create one or more ads under an ad group. Each ad in `creatives[]` needs ad_name, ad_format, video_id (or image_ids), ad_text, call_to_action, and landing_page_url.

List custom audiences (CUSTOMER_FILE, ENGAGEMENT, WEB, APP, LOOKALIKE, etc.) under an advertiser. Use these as targeting building blocks for ad groups.

Create a customer-file custom audience. Identifiers must be SHA-256 hashed before upload (TikTok will not hash for you). After creation, use /dmp/custom_audience/file/upload/ to add hashed identifiers in batches.

List TikTok Pixels for an advertiser. Required to find a pixel_id for conversion-based ad groups and for sending server-side events via the Events API.

Next Steps