Skip to main content

Finding your IDs (My bundles)

This guide helps you quickly copy the IDs you need from the TokPortal web app and shows where to fetch the same data via API. Use it for fast manual lookups during development, and switch to the API for automation.

Where to navigate​

  • Open the TokPortal app → Developer → My bundles.
  • You will see:
    • A list of your bundles (title, external reference, status, type, creation date, total price, TikTok username).
    • A badge “created via API” when is_api_bundle = true.
    • A “COPY ID” button on every bundle row.
    • Expandable bundle details with related objects:
      • Account listings: visible name (nickname), requested username, status, and “COPY ID”.
      • Video listings: name, target publish start date, status, and “COPY ID”.
    • Below the bundles: your saved accounts with profile image, visible name, username, TikTok URL, and “COPY ID”.

When to use this UI vs API​

  • Use the My bundles page for quick lookups and copy/paste workflows.
  • Use the API to integrate programmatically or fetch IDs at runtime.

Object definitions (long‑form)​

Bundle (listing_bundles)​

A bundle is the container for an order in TokPortal. It represents your request to create and/or post content on TikTok.

  • May contain: one Account listing and/or many Video listings
  • Fields:
    • id (UUID), creator_id (UUID)
    • title (string)
    • bundle_type (account_only | account_and_videos | videos_only)
    • videos_quantity (int)
    • status lifecycle: draft → pending_setup → published/accepted → in_review → finalized → completed
    • external_ref (string|null)
    • is_api_bundle (bool)
    • Pricing fields like total_price
    • existing_account_id (UUID|null) for videos‑only
    • Timestamps
  • Relationships: 1→0..1 Account listing, 1→N Video listings; optional link to a Saved account.
  • Usage: create, configure, then publish (wallet charged at publish).

Account listing (account_listings)​

Represents the account creation/configuration inside a bundle.

  • Fields: id (UUID), requested_username, visible_name, biography, profile picture URL, country, status
  • Belongs to: a single bundle
  • Note: For videos_only, an account listing may be synthesized from the saved account for consistency.

Video listing (video_listings)​

Represents one video slot to be posted.

  • Fields: id (UUID), name, description, video_type (currently only video), video_url, tiktok_url (after delivery), target_publish_start_date, optional target_publish_end_date, status, position
  • Belongs to: a single bundle

Saved account (saved_accounts)​

A durable TikTok account created/managed via TokPortal; can be reused for new videos‑only bundles.

  • Fields: id (UUID), account_listing_requested_username, account_listing_visible_name, tiktok_url (optional), profile picture metadata, ownership fields
  • May be referenced by bundles as existing_account_id

Example: fetch bundle state (IDs included)​

cURL

curl -X GET \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  "https://api.tokportal.com/bundles-state?bundle_id=<BUNDLE_ID>"

JS

const res = await fetch(`https://api.tokportal.com/bundles-state?bundle_id=${bundleId}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const data = await res.json();

Response excerpt

{
  "bundle": {
    "id": "bndl_...",
    "title": "My launch",
    "bundle_type": "account_and_videos",
    "status": "pending_setup",
    "external_ref": "order_123",
    "is_api_bundle": true
  },
  "account_listing": {
    "id": "acctlst_...",
    "requested_username": "brand_demo",
    "visible_name": "Brand Demo",
    "status": "configured"
  },
  "video_listings": [
    {
      "id": "vidlst_1",
      "name": "Intro",
      "target_publish_start_date": "2025-09-01",
      "status": "configured"
    }
  ]
}

Tips & best practices​

  • Prefer the My bundles UI for quick manual lookups and to copy IDs fast.
  • Use external_ref to reconcile bundles with your internal orders.
  • The “created via API” badge helps distinguish programmatic orders.
  • All API calls require Authorization: Bearer <api_key> and are scoped by ownership.
  • Never paste API keys in client‑side code; store them in server‑side secrets.