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

Collect creator assets and usage rights.
Store media at public/direct URLs or upload through Media Upload.
Create one bundle per market/platform, or use bulk creation per country.
Configure localized captions and publish dates.
Publish and monitor lifecycle events.
Compare analytics once posts are live.

Create a market bundle

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

Configure UGC videos

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

Scale across markets

Bulk creation is per country. Loop through target countries:

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

Track performance by market

Use delivered account IDs:

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

Post-level metrics:

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

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 to update your internal content tracker.
Do not use the API copy to imply guaranteed reach or platform safety.