Skip to main content

Domain Model

This section explains the core objects manipulated by the API.

Bundle (listing_bundles)​

  • Container for an orderable mission.
  • Types: account_only, account_and_videos, videos_only.
  • Fields (high-level): id, creator_id, title, country (codes like USA, FR, UK), bundle_type, videos_quantity, status, external_ref, pricing breakdown.
  • Lifecycle: draft → pending_setup → published → accepted → in_review → finalized → completed.
  • For videos_only, you must reference an owned saved_account.

Account Listing (account_listings)​

  • The account creation/configuration part of a bundle.
  • Key fields: requested_username, visible_name, biography, profile_picture_url, status, optional tiktok_url when delivered.
  • Configure via POST /account-configure. Finalize via POST /finalize-account.

Video Listing (video_listings)​

  • One row per video slot within a bundle when videos are requested.
  • Key fields: position, video_type, description, video_url, target_publish_start_date, target_publish_end_date, status, optional tiktok_url when delivered.
  • Configure via POST /video-configure-at-position (by position). Publish/finalize/corrections via dedicated endpoints.

Saved Account (saved_accounts)​

  • Durable TikTok account created/managed through TokPortal, can be reused for videos_only bundles.
  • Stores credentials and tiktok_url internally (not exposed publicly).

Orders (orders)​

  • Internal assignment of a bundle to a local manager. Surfaces in bundles-state.

Wallet​

  • Prepaid credits used to publish bundles. Charged upon bundles-publish.

Ownership and Access​

  • All reads/writes are scoped to the API key owner.
  • Endpoints will return not_owner or not_owner_or_not_found if the resource does not belong to the caller.