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

# Create Instagram Account Bundles with TokPortal API

Use `platform: "instagram"` when creating a TokPortal bundle. The API can create account-only bundles, account-and-video bundles, or videos-only bundles for an existing delivered account.

This guide covers the public contract. It does not promise reach, engagement, account immunity, or any specific platform outcome.

If you want to launch accounts without writing API calls, [open the account order form](https://app.tokportal.com/auth/signup?redirect=%2Fbundles%2Fcreate\&utm_source=developers_docs\&utm_medium=owned\&utm_campaign=growth_us_launch_202609\&utm_content=instagram_guide_order). Choose Instagram and an available market in the app, then review the cost before ordering. For a US launch from abroad, use the [launch guide and planning brief](https://www.tokportal.com/learn/us-launch-from-abroad?utm_source=developers_docs\&utm_medium=owned\&utm_campaign=growth_us_launch_202609\&utm_content=instagram_guide_plan).

## 1. Preview an Instagram bundle and its cost

First check which countries accept new Instagram accounts. The public endpoint needs no API key:

```bash
curl "https://app.tokportal.com/api/ext/countries?platform=instagram"
```

Choose a country from `data`, the new-account list. A country present only in `videos_only_countries` cannot be used for a new account. The US request below is an example, not a guarantee of current availability.

Set `TOKPORTAL_API_KEY` locally to your own key from [API Keys](https://app.tokportal.com/developer/api-keys?utm_source=developers_docs\&utm_medium=owned\&utm_campaign=growth_us_launch_202609\&utm_content=instagram_guide_api_key). Then simulate the same account and three video slots you intend to order:

```bash
curl -X POST https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: $TOKPORTAL_API_KEY" \
  -H "X-TokPortal-Dry-Run: true" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_type": "account_and_videos",
    "platform": "instagram",
    "country": "US",
    "title": "US Instagram launch",
    "videos_quantity": 3,
    "external_ref": "ig-launch-us"
  }'
```

Check the successful response before continuing:

- `dry_run` is `true` and `credits_charged` is `0`.
- `credits_would_charge` and `cost_breakdown` show the current quote for your workspace. A zero quote is possible when an allowance applies.
- `data.bundle_id` starts with `00000000-0000-4000-8000-`. It is synthetic: no account or order has been created.

If you only need an account, use `bundle_type: "account_only"` and omit `videos_quantity`. To try the later writes without placing an order, keep the dry-run header on every write and follow the [sandbox workflow rules](https://developers.tokportal.com/sandbox). Simulations do not persist account configuration or uploaded media.

### Confirm the quote, then create the real bundle

Bundle creation charges credits immediately. After you approve the scope and current cost, repeat the creation request without `X-TokPortal-Dry-Run`. Keep the `data.bundle_id` from that real response for the steps below; never reuse a synthetic ID in a live request.

The real response includes `data.bundle_id`, `credits_charged`, `credits_remaining`, and `cost_breakdown`. The remaining examples describe real operations. Replace `bnd_abc123` with your real bundle ID, use your own media, and review each operation before running it. If your goal was only to evaluate the price, stop after the preview.

Reference: [Create Bundle](https://developers.tokportal.com/create-bundle)

## 2. Configure the account profile

Account configuration is required before publishing.

```bash
curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_abc123/account \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "mybrand.us",
    "visible_name": "My Brand",
    "biography": "New drops every week.",
    "profile_picture_url": "https://cdn.example.com/mybrand/profile.jpg",
    "link_in_bio": "https://example.com"
  }'
```

For Instagram, `link_in_bio` is supported; on any other platform it is accepted, stored as null, and reported back in the response's `_warnings` array. `biography` is capped at 120 characters on Instagram (80 elsewhere). Use unique usernames and display names across accounts.

Reference: [Account Configuration](https://developers.tokportal.com/account-configuration)

## 3. Configure an Instagram Reel

For a Reel video, use `video_type: "video"` and `instagram_content_type: "reel"`.

```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",
    "instagram_content_type": "reel",
    "description": "Morning routine with the new collection #style",
    "target_publish_date": "YYYY-MM-DD",
    "video_url": "https://cdn.example.com/reels/reel-01.mp4",
    "instagram_audio_name": "Original audio",
    "external_ref": "ig-reel-01"
  }'
```

`video_url` can be any public/direct URL or a `public_url` returned by [Media Upload](https://developers.tokportal.com/media-upload). Every Instagram slot that is not a story requires `instagram_content_type`.

Replace `YYYY-MM-DD` with a future date before sending either media example. `target_publish_date` is the first day of a two-day publishing window, with a minimum lead time in UTC of today + 3 days while the account is still being created and today + 1 once the account is delivered or when the bundle runs on an existing account; an earlier date is rejected with `INVALID_DATE` carrying `earliest_allowed`. A bundle takes at most 3 videos per day (`VIDEOS_PER_DAY_EXCEEDED` beyond that).

## 4. Configure an Instagram carousel post

For a swipeable Instagram carousel, use `video_type: "carousel"` and `instagram_content_type: "post"`.

Upload images first and use the returned `storage_path` values:

```bash
curl -X POST https://app.tokportal.com/api/ext/upload/image/from-url \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cdn.example.com/carousel/slide-1.jpg",
    "bundle_id": "bnd_abc123",
    "purpose": "carousel"
  }'
```

Then configure the slot:

```bash
curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_abc123/videos/2 \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "video_type": "carousel",
    "instagram_content_type": "post",
    "description": "Which look is your favorite?",
    "target_publish_date": "YYYY-MM-DD",
    "carousel_images": [
      "carousel-images/org_xxx/bnd_abc123/slide-1.jpg",
      "carousel-images/org_xxx/bnd_abc123/slide-2.jpg"
    ],
    "instagram_location": "Los Angeles, California"
  }'
```

Reference: [Configure Videos](https://developers.tokportal.com/configure-videos)

## Advanced Niche Warming

Advanced Niche Warming is the warming product. Send `wants_advanced_warming: true` together with `advanced_warming_terms`: 3-30 niche targets, the count a multiple of 3, each 2-50 characters. The flag is mandatory and never inferred, so targets sent without it are rejected with `ADVANCED_WARMING_FLAG_REQUIRED` and nothing is charged; duplicate or out-of-range targets fail the call with `ADVANCED_WARMING_TERMS_REJECTED` rather than being silently dropped. The standard rate is 5 credits per target (per target, never per day) and `GET /credit-costs` returns the effective workspace rate. The manager searches each target while screen-recording, and every recording is verified into a client report. See [Advanced Warming](https://developers.tokportal.com/advanced-warming).

If the targets are not decided yet, buy them with `advanced_warming_terms_count` (3-30, multiple of 3) and set them later with `PUT /bundles/{id}/warming-terms`. Never send both with disagreeing quantities: that fails with `ADVANCED_WARMING_COUNT_MISMATCH`. Unconfigured purchases are auto-cancelled and fully refunded after 14 days.

```bash
curl -X POST https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_type": "account_and_videos",
    "platform": "instagram",
    "country": "US",
    "videos_quantity": 3,
    "wants_advanced_warming": true,
    "advanced_warming_terms": ["street style outfits", "capsule wardrobe", "outfit inspo daily"],
    "external_ref": "ig-advanced-warming-us"
  }'
```

With 3 targets, warming adds 3 x 5 = 15 credits to the 32 for the account and 2 per video slot, so this bundle is 32 + (3 x 2) + 15 = 53 credits.

This is a standard-rate example. Add `X-TokPortal-Dry-Run: true` to the creation request to inspect your current workspace quote before approving a real order.

Legacy footnotes, for workspaces still holding older orders: `wants_deep_warming: true` on a new order is rejected with `DEEP_WARMING_DEPRECATED`, `wants_niche_warming` still requires `niche_warming_instructions`, and it cannot be combined with `wants_advanced_warming` (`WARMING_CONFLICT`).

## Bulk Instagram creation

`POST /bundles/bulk` accepts one `country` and one or more platforms. To cover several countries, call it once per country.

```bash
curl -X POST https://app.tokportal.com/api/ext/bundles/bulk \
  -H "X-API-Key: sk_your_key_here" \
  -H "Idempotency-Key: ig-bulk-us-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": ["instagram"],
    "country": "US",
    "accounts_count": 5,
    "upload_accounts_count": 2,
    "videos_per_account": 6,
    "wants_advanced_warming": true,
    "advanced_warming_terms": ["street style outfits", "capsule wardrobe", "outfit inspo daily"],
    "external_ref": "ig-bulk-us"
  }'
```

This creates 5 Instagram bundles in the selected country. Two include video slots; three are account-only. The 3 warming targets are applied to every account, so warming is 3 x 5 = 15 credits per account: 5 x 32 for the accounts, plus 5 x 15 for warming, plus 2 x 6 x 2 for the video slots = 259 credits.

This is a standard-rate example, not a workspace quote. Add `X-TokPortal-Dry-Run: true` to this bulk request and review the returned total before approving all five accounts. Do not turn an account-only preview into a bulk order without reviewing the new scope and cost.

Reference: [Create Bulk](https://developers.tokportal.com/create-bulk)

## Delivered account access

After delivery, accounts are available through the [Delivered Accounts](https://developers.tokportal.com/saved-accounts) API:

```bash
curl -X GET "https://app.tokportal.com/api/ext/accounts?platform=instagram" \
  -H "X-API-Key: sk_your_key_here"
```

Credential reveal is a separate, irreversible endpoint. A saved account created before the immutable production cutoff keeps the prior 0-credit policy and existing task access, while support and ban coverage end after access. An account created at or after the cutoff costs 150 credits unless an admin-approved Account Owning Fee agreement applies, and the current policy permanently detaches it. Pending Owning Fee approval keeps the 150-credit path available; after approval, reveal activates or uses the stored $10 legacy or $15 new per-30-day rate instead. For a new-policy account, first call the endpoint to receive HTTP 428 and the current policy version, then explicitly accept that exact version as described in [Delivered Accounts](https://developers.tokportal.com/saved-accounts):

```bash
curl -X POST https://app.tokportal.com/api/ext/accounts/acc_abc123/reveal-credentials \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"acknowledge_support_forfeit":true,"policy_version":"VERSION_RETURNED_BY_428"}'
```

Do not send `Idempotency-Key` to this secret-returning endpoint. On `CREDENTIAL_REVEAL_QUOTE_CHANGED`, request and display a fresh policy preview before asking for new confirmation.

Related docs: [Media Upload](https://developers.tokportal.com/media-upload), [Publish & Unpublish](https://developers.tokportal.com/publish-unpublish), [Analytics](https://developers.tokportal.com/analytics), [MCP Server](https://developers.tokportal.com/mcp).