Source: https://developers.tokportal.com/use-cases/industry/ugc-distribution-at-scale/
Markdown: https://developers.tokportal.com/use-cases/industry/ugc-distribution-at-scale.md

# UGC Distribution at Scale

Brands can use TokPortal to distribute approved creator content through country-specific bundles. TokPortal provides the workflow API; you remain responsible for creator permissions, disclosures, localized copy, and content quality.

## Workflow

1. Collect creator assets and usage rights.
2. Store media at public/direct URLs or upload through [Media Upload](https://developers.tokportal.com/media-upload).
3. Create one bundle per market/platform, or use bulk creation per country.
4. Configure localized captions and publish dates.
5. Publish and monitor lifecycle events.
6. Compare analytics once posts are live.

## Create a market bundle

```bash
curl -X POST https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: $TOKPORTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_type": "account_and_videos",
    "platform": "tiktok",
    "country": "US",
    "videos_quantity": 6,
    "title": "UGC Wave 1 - US",
    "wants_advanced_warming": true,
    "advanced_warming_terms": [
      "creator review",
      "product unboxing",
      "daily lifestyle vlog",
      "honest review",
      "home essentials",
      "what i bought"
    ],
    "external_ref": "ugc-wave-1-us"
  }'
```

`wants_advanced_warming: true` is mandatory whenever `advanced_warming_terms` (3-30 targets, count a multiple of 3, each 2-50 characters) or `advanced_warming_terms_count` is sent; without it the call fails with `ADVANCED_WARMING_FLAG_REQUIRED` and nothing is charged. At the standard rate of 5 credits per target, the 6 targets are 30 credits, so this bundle is 32 for the account + 6 x 2 for the video slots + 30 = 74 credits.

Reference: [Create Bundle](https://developers.tokportal.com/create-bundle)

## Configure UGC videos

```bash
curl -X PUT https://app.tokportal.com/api/ext/bundles/bnd_abc123/videos/batch \
  -H "X-API-Key: $TOKPORTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videos": [
      {
        "position": 1,
        "video_type": "video",
        "description": "Creator review: first week with the product #review",
        "target_publish_date": "2026-06-05",
        "video_url": "https://cdn.example.com/ugc/creator-01.mp4",
        "external_ref": "creator-01-us"
      },
      {
        "position": 2,
        "video_type": "video",
        "description": "Unboxing the new drop #unboxing",
        "target_publish_date": "2026-06-07",
        "video_url": "https://cdn.example.com/ugc/creator-02.mp4",
        "external_ref": "creator-02-us"
      }
    ]
  }'
```

Reference: [Configure Videos](https://developers.tokportal.com/configure-videos)

## Scale across markets

Bulk creation is per country. Loop through target countries:

```bash
for country in US UK FR DE; do
  curl -X POST https://app.tokportal.com/api/ext/bundles/bulk \
    -H "X-API-Key: $TOKPORTAL_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"accounts_count\": 2,
      \"upload_accounts_count\": 1,
      \"platforms\": [\"tiktok\", \"instagram\"],
      \"country\": \"$country\",
      \"videos_per_account\": 6,
      \"wants_advanced_warming\": true,
      \"advanced_warming_terms\": [\"creator review\", \"product unboxing\", \"honest review\"],
      \"external_ref\": \"ugc-wave-1-$country\"
    }"
done
```

This creates one country-specific batch at a time; `country` is the code from `GET /countries` — the United States is `USA` and the United Kingdom is `UK`, with `US` and `GB` accepted as aliases; a country name fails with `INVALID_COUNTRY`. `accounts_count` is per platform, so each loop iteration creates 2 TikTok and 2 Instagram bundles. Warming targets are charged per account: 3 x 5 = 15 credits each, so (4 x 32) + (4 x 15) + (2 x 6 x 2) = 212 credits per country batch. Localize captions and publish dates before configuring each bundle.

Reference: [Create Bulk](https://developers.tokportal.com/create-bulk)

## Track performance by market

Use delivered account IDs:

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

Post-level metrics:

```bash
curl -X GET "https://app.tokportal.com/api/ext/accounts/acc_abc123/analytics/videos?sort_by=views&sort_order=desc" \
  -H "X-API-Key: $TOKPORTAL_API_KEY"
```

Reference: [Analytics](https://developers.tokportal.com/analytics)

## Practical notes

- Use `external_ref` to map each video to creator, market, and campaign.
- Avoid reusing identical captions everywhere; localize language and hashtags.
- Spread publish dates using `target_publish_date`: at most 3 videos per day per bundle, and no earlier than today + 3 days while the account is still being created (today + 1 once it is delivered or on an existing account).
- Review delivered videos inside the \~72-hour window before they auto-finalize; `auto_finalize_videos` does not switch that timer off.
- Use [Webhooks](https://developers.tokportal.com/webhooks) to update your internal content tracker.
- Do not use the API copy to imply guaranteed reach or platform safety.

Related guides: [Agency Management](https://developers.tokportal.com/use-cases/industry/agency-multi-client-management), [DTC Multi-Market Launch](https://developers.tokportal.com/use-cases/industry/dtc-multi-market-launch), [Media Upload](https://developers.tokportal.com/media-upload).