Xylo.
Log InGet Started
Back to Blog
tiktok-adsapitutorial

TikTok Ads API: The Developer Guide

A practical guide to the TikTok Marketing API for developers. Covers authentication, campaign management, audience targeting, and how Xylo simplifies TikTok Ads integration.

Xylo Team|February 19, 2026|7 min read

TikTok Ads for Developers

TikTok has grown from a short-video social platform to one of the top three digital advertising channels globally. The TikTok Marketing API gives developers programmatic access to campaign management, audience targeting, creative upload, and performance reporting across TikTok, Pangle (TikTok's audience network), and other ByteDance properties.

This guide covers the TikTok Marketing API fundamentals, common integration patterns, and how Xylo simplifies the developer experience.

API Overview

The TikTok Marketing API is a REST API with JSON payloads. Unlike Meta's Graph API or Google's gRPC-based API, TikTok's API follows relatively conventional REST patterns. However, it has its own set of quirks.

Base URL

https://business-api.tiktok.com/open_api/v1.3/

Authentication

TikTok uses OAuth 2.0 with long-lived access tokens:

  1. Register as a TikTok Marketing API developer
  2. Create an app in the TikTok for Business developer portal
  3. Get user authorization through the OAuth flow
  4. Receive an access token (valid for 24 hours) and refresh token (valid for 365 days)
# Exchange auth code for tokens
curl -X POST "https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "secret": "YOUR_APP_SECRET",
    "auth_code": "AUTH_CODE_FROM_REDIRECT"
  }'

The 24-hour token lifetime is the shortest among the major ad platforms. You need robust token refresh logic.

Response Format

TikTok's API returns a consistent envelope:

{
  "code": 0,
  "message": "OK",
  "request_id": "20260319abc123def456",
  "data": {
    "list": [...],
    "page_info": {
      "page": 1,
      "page_size": 20,
      "total_number": 45,
      "total_page": 3
    }
  }
}

A code of 0 means success. Non-zero codes indicate errors, with message providing details.

Campaign Structure

TikTok follows a three-tier hierarchy similar to Meta:

Campaign
  └── Ad Group (similar to Meta's Ad Set)
       └── Ad

Fetching Campaigns

curl -G "https://business-api.tiktok.com/open_api/v1.3/campaign/get/" \
  -H "Access-Token: YOUR_ACCESS_TOKEN" \
  -d "advertiser_id=7123456789012345678" \
  -d "fields=[\"campaign_id\",\"campaign_name\",\"budget\",\"budget_mode\",\"operation_status\",\"objective_type\"]"

Response:

{
  "code": 0,
  "data": {
    "list": [
      {
        "campaign_id": "1790000000000001",
        "campaign_name": "Summer Sale - TikTok",
        "budget": 100.00,
        "budget_mode": "BUDGET_MODE_DAY",
        "operation_status": "ENABLE",
        "objective_type": "CONVERSIONS"
      }
    ],
    "page_info": { "total_number": 1, "page": 1, "page_size": 20, "total_page": 1 }
  }
}

TikTok API Quirks

Several patterns differ from Meta and Google:

Aspect TikTok Meta Google
Budget format Float in dollars String in cents Integer in micros
Status field operation_status: "ENABLE" status: "ACTIVE" status: "ENABLED"
Status values ENABLE, DISABLE, DELETE ACTIVE, PAUSED, ARCHIVED ENABLED, PAUSED, REMOVED
Pagination Page-based (page, page_size) Cursor-based Page tokens
Campaign objectives CONVERSIONS, REACH, etc. OUTCOME_SALES, etc. SEARCH, DISPLAY, etc.
IDs Numeric strings Numeric strings Numeric
Error format code + message error.code + error.message gRPC status

Creating Campaigns

The Raw API Way

curl -X POST "https://business-api.tiktok.com/open_api/v1.3/campaign/create/" \
  -H "Access-Token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiser_id": "7123456789012345678",
    "campaign_name": "Q2 Prospecting",
    "objective_type": "CONVERSIONS",
    "budget_mode": "BUDGET_MODE_DAY",
    "budget": 75.00,
    "operation_status": "DISABLE"
  }'

The Xylo Way

const response = await fetch("https://api.xyloapi.dev/v1/campaigns", {
  method: "POST",
  headers: {
    "x-api-key": process.env.XYLO_API_KEY!,
    "x-ad-account": "tiktok_7123456789012345678",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Q2 Prospecting",
    objective: "conversions",
    daily_budget: 75.00,
    status: "paused",
  }),
});

The Xylo request uses the same format as Meta and Google campaigns. Status is "paused" (not "DISABLE"), the field is name (not campaign_name), and the objective is lowercase.

Audience Targeting

TikTok offers several targeting dimensions:

Demographic Targeting

{
  "age_groups": ["AGE_25_34", "AGE_35_44"],
  "gender": "GENDER_FEMALE",
  "languages": ["en"],
  "location_ids": [6252001]
}

Interest and Behavior Targeting

{
  "interest_category_ids": [26001, 26002],
  "action_category_ids": [100001],
  "video_action_categories": ["WATCHED_TO_END", "LIKED", "SHARED"]
}

Custom Audiences

TikTok supports custom audiences similar to Meta:

  • Customer file audiences -- upload hashed email or phone data
  • App activity audiences -- target based on in-app actions
  • Engagement audiences -- reach users who engaged with your TikTok content
  • Website traffic audiences -- retarget visitors (requires TikTok Pixel)
  • Lookalike audiences -- find similar users based on a source audience

Through Xylo, audience management follows the same patterns as Meta:

// Create a custom audience on TikTok
const response = await fetch("https://api.xyloapi.dev/v1/audiences", {
  method: "POST",
  headers: {
    "x-api-key": process.env.XYLO_API_KEY!,
    "x-ad-account": "tiktok_7123456789012345678",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Top Customers - TikTok",
    type: "customer_list",
    customers: [
      { email: "customer@example.com", phone: "+15551234567" }
    ],
  }),
});

Performance Reporting

Raw API Reporting

curl -G "https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/" \
  -H "Access-Token: YOUR_ACCESS_TOKEN" \
  -d "advertiser_id=7123456789012345678" \
  -d "report_type=BASIC" \
  -d "data_level=AUCTION_CAMPAIGN" \
  -d "dimensions=[\"campaign_id\",\"stat_time_day\"]" \
  -d "metrics=[\"spend\",\"impressions\",\"clicks\",\"conversion\",\"cost_per_conversion\",\"ctr\",\"cpc\"]" \
  -d "start_date=2026-03-01" \
  -d "end_date=2026-03-15"

The reporting API uses a separate endpoint from the campaign management API. You specify dimensions and metrics explicitly, and the response uses a flat structure (which is actually cleaner than Meta's nested actions).

Xylo Reporting

curl "https://api.xyloapi.dev/v1/campaigns?date_preset=last_7d" \
  -H "x-api-key: xylo_live_abc123" \
  -H "x-ad-account: tiktok_7123456789012345678"

Response:

{
  "data": [
    {
      "id": "1790000000000001",
      "platform": "tiktok",
      "name": "Summer Sale - TikTok",
      "status": "active",
      "objective": "conversions",
      "daily_budget": 100.00,
      "insights": {
        "impressions": 234567,
        "clicks": 4532,
        "spend": 312.45,
        "cpc": 0.07,
        "cpm": 1.33,
        "ctr": 1.93,
        "conversions": 67,
        "cost_per_conversion": 4.66
      }
    }
  ],
  "meta": {
    "cached": false,
    "meta_api_version": "v1.3"
  }
}

The same shape as Meta and Google campaign data. Cross-platform aggregation requires no platform-specific code.

TikTok Pixel and Events API

TikTok's conversion tracking mirrors Meta's approach with two components:

TikTok Pixel (Client-Side)

<script>
  !function (w, d, t) {
    w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];
    ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie"];
    ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};
    for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);
    ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e};
    ttq.load=function(e,n){var i="https://analytics.tiktok.com/i18n/pixel/events.js";
    ttq._i=ttq._i||{};ttq._i[e]=[];ttq._i[e]._u=i;ttq._t=ttq._t||{};ttq._t[e+\"_\"+n]=+new Date;
    (function(){var o=document.createElement("script");o.type="text/javascript";o.async=!0;o.src=i+"?sdkid="+e+"&lib="+t;
    var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(o,a)})()};
    ttq.load('YOUR_PIXEL_ID');
    ttq.page();
  }(window, document, 'ttq');
</script>

Events API (Server-Side)

const response = await fetch(
  "https://business-api.tiktok.com/open_api/v1.3/pixel/track/",
  {
    method: "POST",
    headers: {
      "Access-Token": process.env.TIKTOK_ACCESS_TOKEN!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      pixel_code: "YOUR_PIXEL_ID",
      event: "CompletePayment",
      event_id: `purchase_${orderId}`, // for dedup with pixel
      timestamp: new Date().toISOString(),
      context: {
        user_agent: req.headers["user-agent"],
        ip: req.ip,
      },
      properties: {
        contents: [{ content_id: "SKU-123", quantity: 1, price: 49.99 }],
        currency: "USD",
        value: 49.99,
      },
    }),
  }
);

Like Meta's CAPI, the Events API provides server-side tracking that is unaffected by ad blockers.

Rate Limits

TikTok's rate limits are simpler than Meta's:

Endpoint Type Rate Limit
Campaign CRUD 10 requests/second per app
Reporting 5 requests/second per app
Audience management 5 requests/second per app
Overall 600 requests/minute per app

When you hit a limit, TikTok returns code: 40100 with a retry-after suggestion. Xylo handles this automatically with exponential backoff.

Cross-Platform Comparison with TikTok

If you are running ads on TikTok alongside Meta and Google, Xylo's normalized data makes comparison straightforward:

const accounts = [
  { platform: "meta", id: "act_123456789" },
  { platform: "google", id: "customers/1234567890" },
  { platform: "tiktok", id: "tiktok_7123456789012345678" },
];

const results = await Promise.all(
  accounts.map(async (account) => {
    const response = await fetch(
      "https://api.xyloapi.dev/v1/campaigns?date_preset=last_7d",
      {
        headers: {
          "x-api-key": process.env.XYLO_API_KEY!,
          "x-ad-account": account.id,
        },
      }
    );
    const data = await response.json();
    return { platform: account.platform, campaigns: data.data };
  })
);

// All campaigns in the same format, ready for aggregation
const allCampaigns = results.flatMap((r) => r.campaigns);
const totalSpend = allCampaigns.reduce((s, c) => s + c.insights.spend, 0);
console.log(`Total cross-platform spend: $${totalSpend.toFixed(2)}`);

Getting Started

Option A: Raw TikTok API

  1. Register as a TikTok Marketing API developer
  2. Create an app and get approval
  3. Implement OAuth flow for access tokens
  4. Handle 24-hour token refresh cycle
  5. Build reporting and management integrations

Estimated setup time: 3-5 days.

Option B: Xylo

  1. Sign up for Xylo
  2. Connect your TikTok Business account through the dashboard
  3. Generate an API key
  4. Start making requests using the same interface as Meta and Google

Estimated setup time: 5 minutes.

For cross-platform reporting strategies, read our cross-platform ad reporting guide. For AI-powered TikTok management, see building AI agents for ads. Check the API documentation for the complete TikTok endpoint reference.

Ready to simplify your ads API integration?

Get started with Xylo in minutes. One API key for every ad platform.

Start for FreeRead the Docs