TokPortal API for Agencies

Agencies can manage multiple client workflows from one TokPortal organization by using title, external_ref, webhooks, and analytics exports. The API does not create separate sub-accounts or client billing ledgers by itself; build that mapping in your own system.

Data model for clients

Use your internal client/campaign IDs in external_ref.

{
  "client_id": "acme",
  "campaign_id": "spring-2026",
  "tokportal_external_ref": "acme-spring-2026-us"
}

Then send that value when creating bundles.

Create a client bundle

curl -X POST https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_type": "account_and_videos",
    "platform": "tiktok",
    "country": "US",
    "title": "Acme - US TikTok",
    "videos_quantity": 10,
    "external_ref": "acme-spring-2026-us"
  }'

Reference: Create Bundle

Configure account and content

Account configuration:

curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_abc123/account \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "acme_us",
    "visible_name": "Acme",
    "biography": "New launches weekly.",
    "profile_picture_url": "https://cdn.example.com/acme/profile.jpg"
  }'

Video configuration:

curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_abc123/videos/batch \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "videos": [
      {
        "position": 1,
        "video_type": "video",
        "description": "Acme launch clip #1",
        "target_publish_date": "2026-06-05",
        "video_url": "https://cdn.example.com/acme/clip-01.mp4",
        "external_ref": "acme-clip-01"
      }
    ]
  }'

References: Account Configuration, Configure Videos

Scale one client across platforms

Use bulk creation for one country at a time:

curl -X POST https://app.tokportal.com/api/ext/bundles/bulk \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": ["tiktok", "instagram"],
    "country": "US",
    "accounts_count": 3,
    "upload_accounts_count": 1,
    "videos_per_account": 5,
    "external_ref": "acme-spring-2026-us"
  }'

For multiple countries, loop over countries and send one request per country.

Reference: Create Bulk

List and reconcile client work

List bundles by your client/campaign reference:

curl -X GET "https://app.tokportal.com/api/ext/bundles?external_ref=acme-spring-2026-us" \
  -H "X-API-Key: sk_your_key_here"

Use webhooks to update your internal dashboard:

curl -X POST https://app.tokportal.com/api/ext/webhooks \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://agency.example.com/webhooks/tokportal",
    "events": ["bundle.published", "account.finalized", "video.finalized"],
    "description": "Agency client dashboard"
  }'

Reference: Webhooks

Reporting

Use delivered account IDs to pull analytics:

curl -X GET https://app.tokportal.com/api/ext/accounts/acc_abc123/analytics \
  -H "X-API-Key: sk_your_key_here"

Export video analytics as CSV when your plan supports it:

curl -X GET "https://app.tokportal.com/api/ext/analytics/export/videos?account=acc_abc123" \
  -H "X-API-Key: sk_your_key_here"

Reference: Analytics

Credit tracking

Credits are shared across the organization. Use credit history for reconciliation:

curl -X GET "https://app.tokportal.com/api/ext/credits/history?page=1&per_page=50" \
  -H "X-API-Key: sk_your_key_here"

Reference: Credits