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.

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 or instagram.
country	string	(Optional) Filter by country code (e.g., US, FR, UK).
page	integer	Page number (default: 1).
per_page	integer	Results per page (default: 25, max: 100).

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: tok_live_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 or instagram.
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	ISO 3166-1 alpha-2 country code.
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 full account details including credentials.

curl -X GET https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c \
  -H "X-API-Key: tok_live_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",
    "credentials": {
      "tokmail_email": "coolcreator99@tokmail.io",
      "password": "xK9#mP2$vL7nQ4w",
      "social_credentials": {
        "email": "coolcreator99@tokmail.io",
        "password": "Tr3nd!Set_42x"
      }
    },
    "last_verification_code": "482937",
    "current_cm_id": "cm_abc123"
  }
}

Credential Fields

Credentials are nested under the credentials object:

Field	Path	Description
tokmail_email	credentials.tokmail_email	The TokMail email address assigned to this account. Used for platform sign-up and verification.
password	credentials.password	The TokMail inbox password.
social_credentials.email	credentials.social_credentials.email	The email used to register the social media account.
social_credentials.password	credentials.social_credentials.password	The password for the social media account itself.

Additional Detail Fields

Field	Type	Description
last_verification_code	string | null	The most recently retrieved verification code.
current_cm_id	string | null	The ID of the account manager currently assigned.

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

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: tok_live_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
  }
}

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.

How it works:

1. Trigger a verification code from the platform (e.g., request a login code from TikTok or Instagram).
2. Wait a few seconds for the email to arrive.
3. 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: tok_live_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.