Accounts (Delivered)

Once a bundle is accepted and the account manager creates the social media account, it becomes a saved account (also called a delivered account). These accounts contain full credentials and are available for you to manage.

Accounts are read-only via the API. You can list them, view their details and credentials, and retrieve verification codes, but you cannot modify account data through the API.

WARNING: Support disclaimer on credential access Retrieving an account's password (via POST /accounts/:id/reveal-credentials) or a verification code (via POST /accounts/:id/verification-code) is typically the first step toward logging in to the account outside TokPortal. Doing so from a country other than the target country, with a VPN, or from a different IP address poses real risks to the account and its reach. We strongly recommend using only TokPortal to manage delivered accounts.

The first time you call either of these endpoints for a given account, you acknowledge that TokPortal will no longer provide support on that account and will not be able to respond to refund or modification requests. You will still be able to order videos for the account and use it on TokPortal, but support in case of issues can no longer be guaranteed. The same disclaimer is shown in the dashboard before the password can be revealed or a verification code retrieved. The acknowledgment is per-account and only set once.

Endpoints that only list or return non-credential metadata (e.g. GET /accounts, GET /accounts/:id, GET /accounts/:id/bundles) do not trigger this acknowledgment.

List Accounts

GET /accounts

Returns a paginated list of your delivered accounts. Use query parameters to filter results.

Parameter	Type	Description
`platform`	string	Filter by platform: `tiktok`, `instagram`, or `youtube`.
`country`	string	(Optional) Filter by country code or TokPortal canonical country code (e.g., `US`, `USA`, `FR`, `UK`).
`page`	integer	Page number (default: `1`).
`per_page`	integer	Results per page (default: `25`, max: `100`).

TIP: tip The country parameter is optional. If you just need all your accounts, omit it — or filter by platform only.

curl -X GET "https://app.tokportal.com/api/ext/accounts?platform=tiktok" \
  -H "X-API-Key: sk_xxx"

Response:

{
  "data": [
    {
      "id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
      "platform": "tiktok",
      "username": "coolcreator99",
      "visible_name": "Cool Creator",
      "biography": "Lifestyle & trends | DM for collabs",
      "profile_picture_url": "https://pub-xxx.r2.dev/profile-pictures/pfp-abc123.jpg",
      "country": "US",
      "link_in_bio": "https://linktr.ee/coolcreator99",
      "profile_url": "https://www.tiktok.com/@coolcreator99",
      "tokmail_email": "coolcreator99@tokmail.io",
      "created_at": "2026-01-10T08:00:00Z",
      "updated_at": "2026-02-05T12:30:00Z"
    },
    {
      "id": "b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "platform": "tiktok",
      "username": "trendwatcher22",
      "visible_name": "Trend Watcher",
      "biography": "Following the latest trends",
      "profile_picture_url": null,
      "country": "US",
      "link_in_bio": null,
      "profile_url": "https://www.tiktok.com/@trendwatcher22",
      "tokmail_email": "trendwatcher22@tokmail.io",
      "created_at": "2026-01-12T10:30:00Z",
      "updated_at": "2026-01-12T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 2,
    "total_pages": 1
  }
}

List Response Fields

Field	Type	Description
`id`	string (UUID)	Unique account identifier.
`platform`	string	`tiktok`, `instagram`, or `youtube`.
`username`	string	Platform username.
`visible_name`	string	Display name on the platform.
`biography`	string	Account bio text.
`profile_picture_url`	string \| null	URL to the profile picture.
`country`	string	Country code returned by TokPortal.
`link_in_bio`	string \| null	Link in bio URL.
`profile_url`	string	Direct URL to the social media profile.
`tokmail_email`	string	TokMail email address for this account.
`created_at`	string	ISO 8601 creation timestamp.
`updated_at`	string	ISO 8601 last-updated timestamp.

Note: The list response does not include a status field.

Get Account Details

GET /accounts/:id

Returns account metadata. Credentials are not returned by this endpoint — call POST /accounts/:id/reveal-credentials to obtain them. A plain metadata fetch does not trigger the support disclaimer.

curl -X GET https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c \
  -H "X-API-Key: sk_xxx"

Response:

{
  "data": {
    "id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
    "platform": "tiktok",
    "username": "coolcreator99",
    "visible_name": "Cool Creator",
    "biography": "Lifestyle & trends | DM for collabs",
    "profile_picture_url": "https://pub-xxx.r2.dev/profile-pictures/pfp-abc123.jpg",
    "country": "US",
    "link_in_bio": "https://linktr.ee/coolcreator99",
    "profile_url": "https://www.tiktok.com/@coolcreator99",
    "credentials": null,
    "last_verification_code": null,
    "current_cm_id": "cm_abc123",
    "created_at": "2026-01-10T08:00:00Z",
    "updated_at": "2026-02-05T12:30:00Z",
    "reveal_endpoint": "/api/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/reveal-credentials",
    "verification_code_endpoint": "/api/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/verification-code",
    "remade": {
      "was_remade": true,
      "remade_count": 1,
      "old_username": "coolcreator9",
      "remade_at": "2026-02-04T09:15:00Z"
    }
  }
}

Additional Detail Fields

Field	Type	Description
`credentials`	null	Always `null`. POST `/accounts/:id/reveal-credentials` to obtain the password and social credentials.
`last_verification_code`	null	Always `null`. POST `/accounts/:id/verification-code` to retrieve a fresh code.
`current_cm_id`	string \| null	The ID of the account manager currently assigned.
`reveal_endpoint`	string	Path to POST to in order to reveal credentials (triggers the support disclaimer).
`verification_code_endpoint`	string	Path to POST to in order to retrieve the latest verification code.
`remade`	object	Whether this account was rebuilt (remade) after the previous account was banned or lost. See Remake info below.

Note: The detail response does not include bundle_id or status.

Remake info

When an account is banned or lost, TokPortal can remake it: the same bundle is republished and a fresh social account is created (usually under a slightly altered username). The remade object lets you detect this and recover the previous handle.

Field	Type	Description
`was_remade`	boolean	`true` if this account was remade at least once, otherwise `false`.
`remade_count`	integer	Number of times the underlying bundle has been remade (`0` when never remade).
`old_username`	string \| null	The previous username, captured at the time of the most recent remake. `null` if unknown or never remade.
`remade_at`	string (ISO 8601) \| null	Timestamp of the most recent remake. `null` if never remade.

Note: remade is always present on the detail response. When the account was never remade it returns { "was_remade": false, "remade_count": 0, "old_username": null, "remade_at": null }. It is not included in the list response (GET /accounts).

List Bundles for an Account

GET /accounts/:id/bundles

Returns all bundles associated with a delivered account. This includes bundles where the account was originally created (account_and_videos) and any videos_only bundles linked to this account.

Each bundle includes a video slot summary, making it easy to find bundles with available posting slots.

Parameter	Type	Description
`status`	string	(Optional) Filter by bundle status: `pending_setup`, `published`, `accepted`, `completed`.
`page`	integer	Page number (default: `1`).
`per_page`	integer	Results per page (default: `25`, max: `100`).

curl -X GET "https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/bundles?status=accepted" \
  -H "X-API-Key: sk_xxx"

Response:

{
  "data": [
    {
      "id": "b1a2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "title": "US TikTok Campaign Q1",
      "bundle_type": "account_and_videos",
      "platform": "tiktok",
      "country": "USA",
      "status": "accepted",
      "videos_quantity": 10,
      "edits_quantity": 2,
      "used_edits": 1,
      "credit_cost": 50,
      "external_ref": "campaign-q1-2026",
      "existing_account_id": null,
      "auto_finalize_videos": true,
      "wants_niche_warming": true,
      "wants_deep_warming": false,
      "wants_moderation": false,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-02-01T14:30:00Z",
      "videos": {
        "total": 10,
        "pending": 3,
        "configured": 2,
        "published": 5,
        "accepted": 0,
        "finalized": 0
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

TIP: Finding available posting slots Use the videos.pending count to identify bundles that have empty video slots ready to be configured. This is especially useful when managing many bundles for the same account — you can quickly find where to schedule your next video without paginating through all bundles.

Retrieve Verification Code

POST /accounts/:id/verification-code

Retrieves the most recent 6-digit verification code from the account's TokMail inbox.

WARNING: warning Calling this endpoint triggers the support disclaimer described at the top of this page. See Support disclaimer on credential access.

How it works:

Trigger a verification code from the platform (e.g., request a login code from TikTok or Instagram).
Wait a few seconds for the email to arrive.
Call this endpoint to retrieve the code from the TokMail inbox.

curl -X POST https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/verification-code \
  -H "X-API-Key: sk_xxx"

Response:

{
  "data": {
    "account_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
    "verification_code": "482937",
    "source": "email"
  }
}

Response Fields

Field	Type	Description
`account_id`	string (UUID)	The account this code belongs to.
`verification_code`	string	The 6-digit verification code.
`source`	string	`"email"` (fetched from inbox) or `"cached"` (returned from cache).

Error — no code found:

{
  "error": {
    "code": "VERIFICATION_CODE_NOT_FOUND",
    "message": "No verification code found in the inbox. Make sure you triggered the code from the platform first and wait a few seconds before retrying."
  }
}

Tip: If you receive a VERIFICATION_CODE_NOT_FOUND error, wait 5-10 seconds and retry. Email delivery can take a moment.