CSV Import

Bulk-import videos into a bundle from a CSV file. The system parses each row, downloads video files from the provided URLs, uploads them to TokPortal storage, and configures the corresponding video positions automatically.

Download Templates

• TikTok CSV Template — Columns: position, name, video_type, video_url, carousel_images, description, target_publish_start_date, editing_instructions, tiktok_sound_url
• Instagram CSV Template — Columns: same as TikTok + instagram_content_type, instagram_location, instagram_collaborators, instagram_audio_name, instagram_add_to_story

Import Videos from CSV

POST /bundles/:id/videos/import-csv

Content-Type: multipart/form-data

Upload a .csv file as the file field. Each row maps to a video position in the bundle.

curl -X POST https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos/import-csv \
  -H "X-API-Key: tok_live_xxx" \
  -F "file=@videos.csv"

Response:

{
  "data": {
    "imported": 5,
    "skipped": 0,
    "errors": []
  }
}

If some rows fail validation, they are returned in the errors array while valid rows are still imported:

{
  "data": {
    "imported": 3,
    "skipped": 2,
    "errors": [
      {
        "row": 4,
        "message": "target_publish_date must be at least 3 days from today."
      },
      {
        "row": 5,
        "message": "carousel_images is required when video_type is carousel."
      }
    ]
  }
}

CSV Column Reference

Column	Required	Description
position	Yes	Video position in the bundle (1-indexed).
video_type	Yes	video or carousel.
description	Yes	Caption or description for the post.
target_publish_date	Yes	Publish date in YYYY-MM-DD format (full date strings also accepted).
video_url	Conditional	URL to the video file. Required when video_type is video. Google Drive links are supported.
carousel_images	Conditional	Semicolon-separated image URLs. Required when video_type is carousel.
tiktok_sound_url	Conditional	TikTok sound URL. Required for TikTok carousels, optional for videos.
editing_instructions	No	Free-text instructions for the creator.
external_ref	No	Your own reference ID for this video.
instagram_content_type	Conditional	reel or post. Required for Instagram bundles.
instagram_location	No	Location tag for Instagram posts.
instagram_collaborators	No	Semicolon-separated Instagram usernames.
instagram_audio_name	No	Audio track name for Instagram Reels.
instagram_add_to_story	No	true or false.
youtube_title	Conditional	Video title. Required for YouTube bundles.
youtube_tags	No	Semicolon-separated tags.
youtube_category	No	YouTube category name.
youtube_visibility	No	public, unlisted, or private.

Video Download Behavior

The system downloads video and image files from the URLs provided in the CSV and re-uploads them to TokPortal's own storage. This means:

• Google Drive links are supported (public or shared links).
• Direct download URLs from any publicly accessible host work.
• After import, the video_url and carousel_images fields on the video will point to TokPortal storage URLs, not the originals.

Formatting Rules

• Dates — Use YYYY-MM-DD (e.g., 2026-03-15) or a full ISO date string (e.g., 2026-03-15T00:00:00Z).
• Multi-value fields — Use semicolons (;) to separate multiple values in carousel_images, instagram_collaborators, and youtube_tags.
• Boolean fields — Use true or false (case-insensitive).

Sample CSV — TikTok

position,video_type,description,target_publish_date,video_url,tiktok_sound_url,editing_instructions,external_ref
1,video,"Unboxing the new collection #ad",2026-03-15,https://drive.google.com/uc?id=abc123,https://www.tiktok.com/music/trending-789,"Add brand logo at the end",campaign-42-v1
2,video,"Trying the product for a week #sponsored",2026-03-18,https://drive.google.com/uc?id=def456,,,campaign-42-v2
3,carousel,"Top 5 looks from the drop",2026-03-21,,https://www.tiktok.com/music/chill-456,,campaign-42-v3

For row 3 (carousel), you would also need a carousel_images column:

position,video_type,description,target_publish_date,carousel_images,tiktok_sound_url,external_ref
3,carousel,"Top 5 looks from the drop",2026-03-21,"https://example.com/img1.jpg;https://example.com/img2.jpg;https://example.com/img3.jpg",https://www.tiktok.com/music/chill-456,campaign-42-v3

Sample CSV — Instagram

position,video_type,instagram_content_type,description,target_publish_date,video_url,instagram_location,instagram_collaborators,instagram_add_to_story,external_ref
1,video,reel,"Morning routine with our skincare ✨",2026-03-20,https://drive.google.com/uc?id=ghi789,"Los Angeles, California",brandofficial,true,ig-reel-001
2,carousel,post,"Summer collection — which is your fave?",2026-03-22,,"Miami, Florida",,false,ig-post-002