Create Bulk

Create multiple bundles in one request.

POST /bundles/bulk

The bulk endpoint creates accounts_count x platforms.length bundles for one country. It debits credits atomically for the whole batch.

Request Body

All fields are top-level. There is no options wrapper and no metadata field in the public contract.

Field	Type	Required	Default	Description
`platforms`	string[]	Yes	-	One or more platforms. Public values: `tiktok`, `instagram`.
`country`	string	Yes	-	TokPortal country code or supported alias. Use `GET /countries` to list countries available for new account creation. Disabled countries and countries restricted to existing-account `videos_only` work are excluded.
`accounts_count`	integer	Yes	-	Number of accounts to create per platform. Min `1`, max `100`.
`upload_accounts_count`	integer	No	`0`	How many accounts per platform should receive video slots. Must be `<= accounts_count`. The rest are `account_only` bundles.
`videos_per_account`	integer	No	`0`	Number of video slots for each account that receives videos. Max `500`.
`wants_advanced_warming`	boolean	No	`false`	Enable Advanced Niche Warming (recommended) on every account of the batch. 3 credits per niche target per account, TikTok and Instagram only. Requires `advanced_warming_terms_count` or `advanced_warming_terms`. See the Advanced Niche Warming guide.
`advanced_warming_terms_count`	integer	No	-	Number of niche targets purchased per account (3-30, multiples of 3). Recommended flow: buy the count now, then write each bundle's targets via `PUT /bundles/{id}/account`. Unconfigured purchases are auto-refunded after 14 days.
`advanced_warming_terms`	string[]	No	-	Alternative: the same explicit targets applied to every account of the batch (3-30 terms, count multiple of 3, each 2-50 characters).
`wants_niche_warming`	boolean	No	`false`	Enable niche warming (review-based, being deprecated). Mutually exclusive with `wants_advanced_warming`.
`wants_deep_warming`	boolean	No	`false`	⚠️ Discontinued. Rejected with `DEEP_WARMING_DEPRECATED`. Use Advanced Niche Warming instead.
`wants_moderation`	boolean	No	`false`	⚠️ Deprecated — ignored. Was the community-management add-on; replaced by the Comments API.
`niche_warming_instructions`	string	No	-	Instructions for niche warming. Required when `wants_niche_warming` is `true`.
`moderation_notice`	string	No	-	⚠️ Deprecated — ignored. Use the Comments API.
`auto_finalize_videos`	boolean	No	`true`	Automatically finalize videos when ready.
`external_ref`	string	No	-	Your external reference. Max 200 characters.

How It Works

Example:

{
  "accounts_count": 10,
  "upload_accounts_count": 3,
  "platforms": ["tiktok", "instagram"],
  "country": "US",
  "videos_per_account": 5
}

Result:

Platform	`account_and_videos`	`account_only`	Total bundles
TikTok	3	7	10
Instagram	3	7	10
Total	6	14	20

Total video slots: 3 upload accounts x 2 platforms x 5 videos = 30.

Example

curl -X POST https://app.tokportal.com/api/ext/bundles/bulk \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts_count": 5,
    "upload_accounts_count": 2,
    "platforms": ["tiktok", "instagram"],
    "country": "US",
    "videos_per_account": 3,
    "wants_niche_warming": true,
    "niche_warming_instructions": "Lifestyle and product review content.",
    "external_ref": "q2-launch-us"
  }'

Response

{
  "data": {
    "bundles_created": 10,
    "bundles": [
      {
        "id": "bnd_001",
        "platform": "tiktok",
        "bundle_type": "account_and_videos"
      },
      {
        "id": "bnd_002",
        "platform": "tiktok",
        "bundle_type": "account_only"
      }
    ],
    "summary": {
      "platforms": ["tiktok", "instagram"],
      "accounts_per_platform": 5,
      "accounts_with_videos": 2,
      "accounts_without_videos": 3,
      "videos_per_account": 3
    }
  },
  "credits_charged": 344,
  "credits_remaining": 9656,
  "cost_breakdown": {
    "per_account_with_videos": {
      "account_creation": 25,
      "video_slots": 6,
      "edit_slots": 0,
      "niche_warming": 7,
      "deep_warming": 0,
      "moderation": 0,
      "total": 38
    },
    "per_account_only": {
      "account_creation": 25,
      "video_slots": 0,
      "edit_slots": 0,
      "niche_warming": 7,
      "deep_warming": 0,
      "moderation": 0,
      "total": 32
    },
    "accounts_with_videos": 2,
    "accounts_without_videos": 3,
    "platforms_count": 2,
    "total": 344
  }
}

The sample is shortened. The real response includes every created bundle and the server-calculated credit breakdown.

Validation Rules

upload_accounts_count cannot exceed accounts_count.
If videos_per_account is greater than 0, set upload_accounts_count greater than 0 to create upload-capable bundles.
wants_advanced_warming requires either advanced_warming_terms_count or advanced_warming_terms (3-30 targets, multiples of 3) — otherwise ADVANCED_WARMING_TERMS. Every platform of the batch must be TikTok or Instagram (ADVANCED_WARMING_PLATFORM).
wants_advanced_warming and wants_niche_warming are mutually exclusive (WARMING_CONFLICT).
wants_deep_warming: true is always rejected with DEEP_WARMING_DEPRECATED — deep warming is discontinued.
niche_warming_instructions is required when wants_niche_warming is true.
country must be enabled for your organization.

Countries

The endpoint accepts one country per request. To create bundles in several countries, loop over country codes and call POST /bundles/bulk once per country.

Use:

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

Use only the response's data list for bulk creation. The separate videos_only_countries list applies exclusively to video orders on existing accounts and is not valid for this endpoint.

Error Responses

Status	Code	Description
`400`	`INVALID_BODY`	Invalid request body or unsupported field.
`400`	`INVALID_COUNTRY`	Country is not enabled.
`400`	`WARMING_CONFLICT`	Advanced Niche Warming and niche warming cannot both be enabled.
`400`	`ADVANCED_WARMING_TERMS`	Provide `advanced_warming_terms` or `advanced_warming_terms_count` (3-30, multiples of 3).
`400`	`ADVANCED_WARMING_PLATFORM`	Advanced Niche Warming is only available for TikTok and Instagram.

Next Steps

Configure account profiles for created bundles.
Configure videos for account_and_videos bundles.
Publish bundles when they are ready.