Bulk TikTok Bundle Creation API

POST /bundles/bulk creates multiple bundles in one request. The current public contract supports:

• one country per request, as a code from GET /countries (USA, UK, FR, ...): mostly ISO alpha-2, except the United States (USA) and the United Kingdom (UK), whose aliases US and GB are accepted; a country name fails with INVALID_COUNTRY
• one or more platforms — TikTok and Instagram; a YouTube bundle is rejected with YOUTUBE_DELAYED
• one bundle per account: bulk creation is how you order several accounts at once
• up to 100 accounts per platform per request
• optional video slots on a subset of accounts
• one atomic credit debit for the whole batch

For multiple countries, loop over country codes and send one request per country.

Reference: Create Bulk

Request shape

curl -X POST https://app.tokportal.com/api/ext/bundles/bulk \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": ["tiktok"],
    "country": "US",
    "accounts_count": 10,
    "upload_accounts_count": 4,
    "videos_per_account": 8,
    "wants_advanced_warming": true,
    "advanced_warming_terms": [
      "consumer tech",
      "gadget review",
      "product demo",
      "tech unboxing",
      "smart home setup",
      "everyday carry tech"
    ],
    "external_ref": "bulk-us-q2"
  }'

This creates 10 TikTok bundles in the US target country:

wants_advanced_warming: true is mandatory whenever advanced_warming_terms (3-30 targets, count a multiple of 3, each 2-50 characters) or advanced_warming_terms_count is sent; the whole batch is rejected with ADVANCED_WARMING_FLAG_REQUIRED otherwise, and nothing is charged. Targets are charged per account at the standard rate of 5 credits each, so warming is 6 x 5 = 30 credits on each of the 10 accounts. As a preview only, the batch is (10 x 32) + (10 x 30) + (32 x 2) = 684 credits.

Credits are returned by the API. Do not calculate costs client-side except for previews; the server is the source of truth.

Multi-platform bulk

accounts_count is per platform.

curl -X POST https://app.tokportal.com/api/ext/bundles/bulk \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": ["tiktok", "instagram"],
    "country": "US",
    "accounts_count": 5,
    "upload_accounts_count": 2,
    "videos_per_account": 6,
    "external_ref": "bulk-us-multi-platform"
  }'

This creates 10 bundles total: 5 TikTok and 5 Instagram. For each platform, 2 bundles include video slots and 3 are account-only.

Multi-country rollout

The endpoint does not accept a countries array. Loop from your application or automation tool:

for country in US UK FR DE; do
  curl -X POST https://app.tokportal.com/api/ext/bundles/bulk \
    -H "X-API-Key: $TOKPORTAL_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"platforms\": [\"tiktok\"],
      \"country\": \"$country\",
      \"accounts_count\": 5,
      \"upload_accounts_count\": 2,
      \"videos_per_account\": 8,
      \"external_ref\": \"bulk-q2-$country\"
    }"
done

Validate supported countries before running a loop:

curl -X GET https://app.tokportal.com/api/ext/countries \
  -H "X-API-Key: sk_your_key_here"

Configure videos after creation

Each returned bundle has an id. Configure slots individually:

curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_abc123/videos/1 \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "video_type": "video",
    "description": "Launch clip #1",
    "target_publish_date": "2026-06-05",
    "video_url": "https://cdn.example.com/videos/launch-01.mp4"
  }'

Or configure several positions in one request:

curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_abc123/videos/batch \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "videos": [
      {
        "position": 1,
        "video_type": "video",
        "description": "Launch clip #1",
        "target_publish_date": "2026-06-05",
        "video_url": "https://cdn.example.com/videos/launch-01.mp4"
      },
      {
        "position": 2,
        "video_type": "video",
        "description": "Launch clip #2",
        "target_publish_date": "2026-06-07",
        "video_url": "https://cdn.example.com/videos/launch-02.mp4"
      }
    ]
  }'

The earliest target_publish_date is today + 3 days while the account is still being created, and today + 1 once that account is delivered or when the bundle runs on an existing account. A bundle takes at most 3 videos per day, so spread the 8 slots over at least 3 dates.

Reference: Configure Videos

CSV import

CSV import is multipart file upload, not a csv_url JSON field:

curl -X POST https://app.tokportal.com/api/ext/bundles/bnd_abc123/videos/import-csv \
  -H "X-API-Key: sk_your_key_here" \
  -F "file=@videos.csv" \
  -F "auto_publish=true"

Reference: CSV Import

Production notes

• Split batches larger than the documented request limits.
• Use external_ref to connect TokPortal bundles to your internal campaign IDs.
• Store every returned bundle.id; later video configuration and publish calls are per bundle.
• Use Webhooks instead of polling for high-volume workflows.
• Use Analytics after accounts and posts are live; analytics availability depends on account/post state and plan.

Related guides: DTC Multi-Market Launch, Agency Management, n8n.