Source: https://developers.tokportal.com/use-cases/industry/agency-multi-client-management/
Markdown: https://developers.tokportal.com/use-cases/industry/agency-multi-client-management.md

# 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`.

```json
{
  "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

```bash
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](https://developers.tokportal.com/create-bundle)

## Configure account and content

Account configuration:

```bash
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:

```bash
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"
      }
    ]
  }'
```

`target_publish_date` cannot be earlier than today + 3 days while the account is still being created, or today + 1 once it is delivered or when the bundle runs on an existing account, and a bundle takes at most 3 videos per day. Client review is time-boxed: a delivered video sits in review and auto-finalizes about 72 hours after entering it, regardless of `auto_finalize_videos`, so collect client feedback and call the finalize or corrections endpoint inside that window.

References: [Account Configuration](https://developers.tokportal.com/account-configuration), [Configure Videos](https://developers.tokportal.com/configure-videos)

## Scale one client across platforms

Use bulk creation for one country at a time:

```bash
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](https://developers.tokportal.com/create-bulk)

## List and reconcile client work

List bundles by your client/campaign reference:

```bash
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:

```bash
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](https://developers.tokportal.com/webhooks)

## Reporting

Use delivered account IDs to pull analytics:

```bash
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:

```bash
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](https://developers.tokportal.com/analytics)

## Credit tracking

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

```bash
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](https://developers.tokportal.com/credits)

Related guides: [Bulk TikTok Account Creation](https://developers.tokportal.com/use-cases/platform-guides/bulk-tiktok-accounts-api), [UGC Distribution](https://developers.tokportal.com/use-cases/industry/ugc-distribution-at-scale), [MCP Server](https://developers.tokportal.com/mcp).