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 enabled values.
`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_niche_warming`	boolean	No	`false`	Enable niche warming. Mutually exclusive with `wants_deep_warming`.
`wants_deep_warming`	boolean	No	`false`	Enable deep warming. Instagram only. Mutually exclusive with `wants_niche_warming`.
`wants_moderation`	boolean	No	`false`	Enable content moderation.
`niche_warming_instructions`	string	No	-	Instructions for niche warming. Required when `wants_niche_warming` is `true`.
`moderation_notice`	string	No	-	Optional notice for moderation.
`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.",
    "wants_moderation": true,
    "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": 594,
  "credits_remaining": 9406,
  "cost_breakdown": {
    "per_account_with_videos": {
      "account_creation": 25,
      "video_slots": 6,
      "edit_slots": 0,
      "niche_warming": 7,
      "deep_warming": 0,
      "moderation": 25,
      "total": 63
    },
    "per_account_only": {
      "account_creation": 25,
      "video_slots": 0,
      "edit_slots": 0,
      "niche_warming": 7,
      "deep_warming": 0,
      "moderation": 25,
      "total": 57
    },
    "accounts_with_videos": 2,
    "accounts_without_videos": 3,
    "platforms_count": 2,
    "total": 594
  }
}

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_niche_warming and wants_deep_warming are mutually exclusive.
wants_deep_warming is only valid for Instagram. If platforms includes TikTok, do not set wants_deep_warming: true.
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"

Error Responses

Status	Code	Description
`400`	`INVALID_BODY`	Invalid request body or unsupported field.
`400`	`INVALID_COUNTRY`	Country is not enabled.
`400`	`WARMING_CONFLICT`	Niche warming and deep warming cannot both be enabled.
`400`	`DEEP_WARMING_INSTAGRAM_ONLY`	Deep warming is only valid for Instagram-only requests.
`402`	`INSUFFICIENT_CREDITS`	Not enough credits for the full bulk operation.
`429`	`RATE_LIMIT_EXCEEDED`	Create rate limit exceeded.

Next Steps

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