Account Configuration

Configure the account details for a bundle. Account configuration is required before a bundle can be published.

Configure Account

Set or update the account details for a bundle.

PUT /bundles/:id/account

Request Body

Field	Type	Required	Description
`username`	string	Yes	Account username. 1-24 characters, alphanumeric plus `.` and `_`.
`visible_name`	string	Yes	Display name. 1-30 characters.
`biography`	string	Yes	Account biography. Max 80 characters.
`profile_picture_url`	string	Yes	URL to the profile picture image.
`link_in_bio`	string	No	Link displayed in the bio. Instagram only.
`niche_warming_instructions`	string	No	Instructions for niche warming behavior. Only applies when `niche_warming` is enabled.
`advanced_warming_terms`	string[]	No	Niche targets for an Advanced Niche Warming purchase made with `advanced_warming_terms_count` at bundle creation. Must sanitize to exactly the purchased count. One-shot: once set (or the session already started), further attempts return `409 WARMING_TERMS_ALREADY_SET`. See the Advanced Niche Warming guide.

Validation Rules

Field	Rule
`username`	1-24 characters. Allowed: `[a-zA-Z0-9_.]`
`visible_name`	1-30 characters.
`biography`	Max 80 characters.
`profile_picture_url`	Must be a valid URL.
`link_in_bio`	Must be a valid URL. Instagram only.

WARNING: Avoid duplicated wording across accounts Do not create multiple accounts that reuse the same words in the username or visible_name. Prefer unique usernames and nicknames for every account. Reusing the same words across many accounts on the same platform increases the risk of mass-ban detection by the platform's anti-spam systems.

Requirements

Bundle must be in pending_setup or configured status.
You cannot modify account configuration after the bundle has been published (unpublish first).

Advanced Niche Warming targets

If the bundle was created with wants_advanced_warming: true and a target count (advanced_warming_terms_count), this endpoint is where you write the actual niche targets:

Pass advanced_warming_terms with exactly the purchased number of targets (each 2-50 characters; duplicates are removed case-insensitively). A mismatch returns 400 ADVANCED_WARMING_TERMS with details.purchased_terms_count.
Configuration is one-shot per warming purchase — afterwards the API returns 409 WARMING_TERMS_ALREADY_SET.
Warming starts immediately when the account/order is already active (the warming.session_started webhook fires); otherwise it starts automatically at account submission / order accept.
Count-only purchases never configured within 14 days are auto-cancelled and fully refunded.
On success the response includes "_warming": { "terms_configured": true, "started": <bool> }, and the account's advanced_warming summary reflects the new state (terms_configured: true).

Example

curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_abc123/account \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "streetstyle.nyc",
    "visible_name": "Street Style NYC",
    "biography": "Daily street fashion from New York City.",
    "profile_picture_url": "https://cdn.example.com/profiles/streetstyle.jpg",
    "niche_warming_instructions": "Engage with fashion and streetwear content in NYC area."
  }'

Response

{
  "data": {
    "id": "acc_xyz789",
    "bundle_id": "bnd_abc123",
    "status": "configured",
    "platform": "tiktok",
    "username": "streetstyle.nyc",
    "visible_name": "Street Style NYC",
    "biography": "Daily street fashion from New York City.",
    "profile_picture_url": "profile-pictures/bnd_abc123/streetstyle.jpg",
    "link_in_bio": null,
    "country": "US",
    "is_niche_warmed": false,
    "is_deep_warmed": false,
    "deep_warming_verification_status": null,
    "niche_warming_instructions": "Engage with fashion and streetwear content in NYC area.",
    "advanced_warming": null,
    "feedback": null,
    "created_at": "2026-02-10T10:00:00Z"
  }
}

NOTE: Response shape The account fields are returned flat under data — there is no nested data.account wrapper. The id field is the account ID (not the bundle ID). Use bundle_id to reference the parent bundle.

advanced_warming summarizes the latest advanced warming session of the account (session_id, status, terms_total, terms_verified, started_at, completed_at) or is null when the account has none. Fetch the full per-term reports with GET /warming-sessions/{session_id}. The legacy is_deep_warmed / deep_warming_verification_status fields remain for old bundles — deep warming is discontinued for new orders.

If an external profile_picture_url was provided, it is automatically downloaded and re-hosted; the response will include _info.profile_picture_rehosted: true. If the profile picture is missing, the response will include a _warnings array.

Instagram Example with Link in Bio

curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_d4e5f6/account \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "cafe.paris_",
    "visible_name": "Caf\u00e9 Paris",
    "biography": "Les meilleurs caf\u00e9s parisiens.",
    "profile_picture_url": "https://cdn.example.com/profiles/cafeparis.jpg",
    "link_in_bio": "https://cafeparis.example.com"
  }'

Response

{
  "data": {
    "id": "acc_pqr456",
    "bundle_id": "bnd_d4e5f6",
    "status": "configured",
    "platform": "instagram",
    "username": "cafe.paris_",
    "visible_name": "Caf\u00e9 Paris",
    "biography": "Les meilleurs caf\u00e9s parisiens.",
    "profile_picture_url": "profile-pictures/bnd_d4e5f6/cafeparis.jpg",
    "link_in_bio": "https://cafeparis.example.com",
    "country": "FR",
    "is_niche_warmed": false,
    "is_deep_warmed": false,
    "deep_warming_verification_status": null,
    "niche_warming_instructions": null,
    "advanced_warming": {
      "session_id": "6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "status": "in_progress",
      "terms_total": 6,
      "terms_verified": 2,
      "started_at": "2026-07-10T12:00:00Z",
      "completed_at": null
    },
    "feedback": null,
    "created_at": "2026-02-10T10:15:00Z"
  }
}

Get Account

Retrieve the current account configuration for a bundle.

GET /bundles/:id/account

Example

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

Response

{
  "data": {
    "id": "acc_xyz789",
    "bundle_id": "bnd_abc123",
    "status": "configured",
    "platform": "tiktok",
    "username": "streetstyle.nyc",
    "visible_name": "Street Style NYC",
    "biography": "Daily street fashion from New York City.",
    "profile_picture_url": "profile-pictures/bnd_abc123/streetstyle.jpg",
    "link_in_bio": null,
    "country": "US",
    "is_niche_warmed": false,
    "is_deep_warmed": false,
    "deep_warming_verification_status": null,
    "niche_warming_instructions": "Engage with fashion and streetwear content in NYC area.",
    "feedback": null,
    "created_at": "2026-02-10T10:00:00Z"
  }
}

Error Responses

Status	Code	Description
`400`	`invalid_username`	Username does not match allowed pattern `[a-zA-Z0-9_.]` or exceeds 24 characters.
`400`	`invalid_visible_name`	Visible name is empty or exceeds 30 characters.
`400`	`biography_too_long`	Biography exceeds 80 characters.
`400`	`invalid_url`	`profile_picture_url` or `link_in_bio` is not a valid URL.
`400`	`link_in_bio_instagram_only`	`link_in_bio` is only supported on Instagram.
`400`	`ADVANCED_WARMING_TERMS`	`advanced_warming_terms` does not sanitize to exactly the purchased target count (`details.purchased_terms_count`).
`409`	`invalid_status`	Bundle is not in `pending_setup` or `configured` status.
`409`	`DUPLICATE_ACCOUNT_BUNDLE`	An active bundle already exists for this username on the same platform. `details.existing_bundle_id` contains the conflicting bundle. Does not apply to `videos_only` bundles.
`409`	`WARMING_TERMS_ALREADY_SET`	The Advanced Niche Warming targets are already configured (or the session already started). Targets can only be set once per warming purchase.
`404`	`bundle_not_found`	Bundle does not exist.
`404`	`WARMING_SESSION_NOT_FOUND`	`advanced_warming_terms` was passed but the bundle has no warming session to configure (e.g. created without Advanced Niche Warming).