Source: https://developers.tokportal.com/use-cases/platform-guides/bulk-tiktok-accounts-api/
Markdown: https://developers.tokportal.com/use-cases/platform-guides/bulk-tiktok-accounts-api.md

# 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](https://developers.tokportal.com/create-bulk)

## Request shape

```bash
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:

| Result                        | Count |
| ----------------------------- | ----- |
| `account_and_videos` bundles  | 4     |
| `account_only` bundles        | 6     |
| Video slots per upload bundle | 8     |
| Total video slots             | 32    |
| Warming targets per account   | 6     |

`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.

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://developers.tokportal.com/configure-videos)

## CSV import

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

```bash
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](https://developers.tokportal.com/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](https://developers.tokportal.com/webhooks) instead of polling for high-volume workflows.
- Use [Analytics](https://developers.tokportal.com/analytics) after accounts and posts are live; analytics availability depends on account/post state and plan.

Related guides: [DTC Multi-Market Launch](https://developers.tokportal.com/use-cases/industry/dtc-multi-market-launch), [Agency Management](https://developers.tokportal.com/use-cases/industry/agency-multi-client-management), [n8n](https://developers.tokportal.com/use-cases/no-code/n8n-tiktok-automation).