API Reference › TikTok Ads › add_tiktok_ad

add_tiktok_ad

TikTok Ads Write

Add a new ad to an existing TikTok ad group

Endpoint

POST https://api.adspirer.ai/api/v1/tools/add_tiktok_ad/execute

Headers

Description

Add a new ad to an existing TikTok ad group. Use this when you need to add additional ads (creatives) to an ad group that was already created. Supports all ad formats: - SINGLE_IMAGE: Provide image_urls (public HTTPS URLs — auto-uploaded) OR image_ids (pre-uploaded TikTok IDs) - SINGLE_VIDEO: Provide video_id (TikTok video ID from creative library) - Spark Ads: Boost organic TikTok posts (requires tiktok_item_id + identity_type=TT_USER) - Carousel: Multi-card ads (first call create_tiktok_carousel_card to get card_id, then provide card_id + card_type here) Identity (identity_id) is auto-resolved — you do NOT need to provide it unless using Spark Ads. Images are auto-uploaded from URLs — you do NOT need to call upload_tiktok_images first. This is useful for: - Testing different creatives in the same ad group - Adding new ad variations without creating a new campaign - A/B testing ad copy, images, or CTAs Required: adgroup_id, ad_text, landing_page_url. For image ads: provide image_urls (easiest) or image_ids. For video ads: provide video_id. For Spark Ads: provide tiktok_item_id and set identity_type to TT_USER.

Request body

All tool arguments are wrapped in an arguments object.

FieldTypeDescription
adgroup_idstring requiredExisting TikTok ad group ID to add the ad to
ad_textstring requiredAd text (1-100 characters).
landing_page_urlstring requiredLanding page URL (must be HTTPS).
ad_namestring optionalAd name. Auto-generated if not provided.
ad_formatstring optionalAd format. **Auto-detected by Adspirer based on creative source** — video_url/video_id → SINGLE_VIDEO; image_urls (slideshow) / image_ids → SINGLE_VIDEO (TikTok in-feed rejects SINGLE_IMAGE). Pass explicitly only when you know what you're doing.
display_namestring optionalBrand name (max 40 chars).
call_to_actionstring optionalCTA button text. Common: LEARN_MORE, SHOP_NOW, SIGN_UP, DOWNLOAD_NOW, INSTALL_NOW, ORDER_NOW, BOOK_NOW, APPLY_NOW, SUBSCRIBE, WATCH_NOW, CONTACT_US. Synonyms (DOWNLOAD, INSTALL, BUY_NOW) are auto-corrected.
image_idsarray optionalTikTok image IDs from upload_tiktok_images (for SINGLE_IMAGE).
image_urlsarray optionalPublic image URLs (HTTPS) — auto-uploaded to TikTok and routed through the slideshow path (image→video).
video_idstring optionalTikTok video ID (for SINGLE_VIDEO format). Use when the video already exists on the advertiser.
video_urlstring optionalPublic video URL (HTTPS, MP4/MOV). Adspirer downloads + uploads + extracts cover. Provide one of: video_url (auto-upload), video_id (already on advertiser), image_urls (slideshow), or tiktok_item_id (Spark).
identity_idstring optionalAdvertiser identity ID. **Auto-resolved by Adspirer**. Leave blank unless you specifically need to use a non-default identity (e.g. for Spark Ads with a particular TT_USER). Run list_tiktok_identities to see available IDs.
identity_typestring optionalIdentity type: BC_AUTH_TT (Business Center authorized — preferred) or TT_USER (for Spark Ads). **Auto-resolved by Adspirer**, leave blank in most cases. Note: CUSTOMIZED_USER was deprecated by TikTok in 2026-04 and is no longer accepted for new ads — Adspirer will reject it.
tiktok_item_idstring optionalTikTok organic post ID for Spark Ads (boost existing TikTok posts as ads).
card_idstring optionalCarousel card ID.
card_typestring optionalCard type: IMAGE or PRODUCT.
click_tracking_urlstring optional3rd-party click tracking URL (DCM, IAS, Branch, AppsFlyer, etc.). Fired when a user clicks. Required by some agencies and brand-safety partners.
impression_tracking_urlstring optional3rd-party impression tracking URL. Fired on each impression. Pairs with click_tracking_url for full-funnel measurement.
video_view_tracking_urlstring optional3rd-party video-view tracking URL. Fired when a video view threshold is met.
tracking_pixel_idstring optionalNumeric tracking-pixel ID for additional event measurement (separate from the conversion pixel).
deeplinkstring optionalApp deep link (e.g. 'myapp://product/123'). Required for re-engagement and app-promotion campaigns to land users in the right in-app screen.
deeplink_typestring optionalDeep link type: NORMAL, DEFERRED. NORMAL opens the app if installed; DEFERRED installs first then triggers the deep-link on first launch.
fallback_typestring optionalFallback when deep link fails (app not installed): APP_INSTALL, WEB_LANDING (use landing_page_url).
disclaimer_textstring optionalDisclaimer text shown alongside the ad — required for regulated industries (financial services, healthcare, alcohol, etc.). **TikTok hard limit: 90 characters.** Backend wraps this in the OpenApiv13adcreateDisclaimerText SDK object automatically. Disclaimer is an allowlist-only feature; non-allowlisted accounts will see TikTok reject with 'feature not available'.
disclaimer_clickable_textsarray optionalClickable disclaimer text segments — schema: [{'text': '...', 'url': '...'}]. Use when disclaimer needs links to terms / risk-factor pages.
disclaimer_typestring optionalDisclaimer type: TEXT_LINK (clickable, default for clickable_texts), TEXT_ONLY. TikTok Ads Manager → Compliance → Disclaimers shows the configured disclaimer presets.
vertical_video_strategystring optionalVideo format strategy. **Live-verified accepted values** (TikTok 2026-05-04): SINGLE_VIDEO (single uploaded video, most common), CATALOG_VIDEOS (DPA from catalog, requires catalog.read scope), CATALOG_UPLOADED_VIDEOS (catalog with manual uploads), LIVE_STREAMING (TikTok Live shopping). Adspirer-default: omit and let TikTok auto-pick.
item_duet_statusstring optionalAllow user duets: ENABLE (creators can react/duet your ad — increases viral potential), DISABLE (brand-safety lockdown). Default: ENABLE.
item_stitch_statusstring optionalAllow user stitches: ENABLE (creators can stitch your ad), DISABLE.
promotional_music_disabledboolean optionalDisable TikTok's promotional commercial-music library. Required for some brand-safe placements when you only want your own audio.
creative_authorizedboolean optionalMark creative as authorized for use across all campaigns / ad-sets in this advertiser (creative library reuse). Default: false.
dark_post_statusstring optionalDark post (only visible as ad, not on organic profile): ENABLE, DISABLE. Useful for A/B testing ad copy without polluting your organic feed.
brand_safety_postbid_partnerstring optionalPostbid brand-safety partner (DV, IAS, MOAT). Measures viewability and brand-safety after the bid is won. Different from pre-bid brand_safety_partner on the ad-group.
brand_safety_vast_urlstring optionalVAST tag URL for IAS/DV postbid measurement.
viewability_postbid_partnerstring optionalViewability measurement partner: MOAT, DV, IAS.
viewability_vast_urlstring optionalVAST URL for postbid viewability measurement.
vast_moat_enabledboolean optionalEnable Moat viewability measurement integration.
page_idstring optionalTikTok Page ID — for Instant Form ads, Custom Instant Page, or App Profile Page. Required for LEAD_GENERATION objective when using TikTok Instant Forms. Discover via list_tiktok_lead_forms (pending lead.read scope).
advertiser_idstring optionalTikTok advertiser ID (optional).

Example request

{
  "arguments": {
    "adgroup_id": "string",
    "ad_text": "string",
    "landing_page_url": "https://example.com",
    "ad_name": "string",
    "ad_format": "string",
    "display_name": "string",
    "call_to_action": "string",
    "image_ids": [
      "string"
    ],
    "image_urls": [
      "string"
    ]
  }
}

Example responses

200 — Success

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for add_tiktok_ad)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "add_tiktok_ad"
}

400 — Tool-level error (bad arguments / multi-account selection)

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "add_tiktok_ad"
}

402 — Quota exhausted

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "add_tiktok_ad",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}

Try it live

Interactive: Swagger UI

Machine-readable: OpenAPI 3.1 spec · llms-full.txt

More tools: TikTok Ads · All tools

Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai