TokPortal REST API: Complete Developer Guide

The official TikTok Content Posting API lets you upload videos. What it doesn't let you do: add TikTok sounds, use native editing features, post without an API fingerprint, or create new accounts programmatically. If you've hit those walls, you already know why most developers building social media automation pipelines end up duct-taping workarounds together — and why those workarounds eventually break.

The TokPortal API is infrastructure built for what the official API can't do. It gives you full programmatic control over real TikTok and Instagram accounts running on real physical smartphones with local SIM cards in 30+ countries. This guide covers everything: authentication, core endpoints, posting with native sounds, warming, webhooks, and how to wire it all into your existing stack.

The TokPortal API uses API key authentication passed in the request header. All endpoints are documented at developers.tokportal.com — your primary reference for request schemas, response objects, error codes, and rate limits. Every endpoint, parameter, and example lives there. This guide walks you through the architecture and use cases; the docs site has the technical specifics.

Your API key is tied to your TokPortal workspace. Credits are consumed per action: account creation costs 25 credits, video uploads cost 2 credits each, sound volume adjustments cost 1 credit, and warming options run from 7 credits (niche) to 40 credits (deep, Instagram). You're billed only for what you use, which makes the API well-suited to both high-volume pipelines and experimental automation scripts.

Before writing a single API call, understand the architecture. TokPortal organizes accounts into bundles — a bundle is a real physical smartphone in a specific country with a local SIM card. When you create a bundle via the API, you're provisioning a device slot. The account (TikTok or Instagram) then lives on that device and inherits all of its trust signals: carrier data, GPS location, cell tower proximity, local WiFi identifiers, and behavioral patterns built up over time.

This matters because TikTok's device fingerprinting is deep. Accounts created on VPNs or cloud servers get shadowbanned within 48 hours because the signal mismatch is obvious to TikTok's systems. A bundle from TokPortal is indistinguishable from a local user because it is a local user — just one you control via API.

This is worth stopping on. The official TikTok API explicitly does not support adding TikTok sounds to uploaded videos. Sounds are one of the most powerful distribution mechanisms on TikTok — trending sounds can 3–5x organic reach for the same video content. Every manual TikTok creator knows this. But every developer building programmatic TikTok distribution has had to accept that sounds just aren't available in the API.

TokPortal's API breaks that constraint. Because posting happens inside the actual TikTok app on a real device, sounds are added exactly the way a human creator would add them. You pass a TikTok sound URL in your video upload request. TokPortal's device layer adds the sound natively during the posting process. The resulting post is identical to one a creator made manually — complete with the sound attribution, the trending sound discovery surface, and all associated algorithmic benefits.

For developers building UGC distribution pipelines, content agencies managing dozens of accounts, or e-commerce brands seeding product videos across multiple markets, this is the differentiator that changes the economics of organic TikTok.

The TokPortal API handles both TikTok and Instagram through a unified interface. You specify the platform at the bundle level (when creating the account) and again at the upload level (when posting content). Here's what each platform supports:

TikTok: Standard video posts, Carousels (photo mode with sound), captions, hashtags, sounds, location tags, and scheduled posting.

Instagram: Reels, standard feed posts, carousels (swipeable multi-image), fixed photos, and Stories. Instagram posts additionally support location tags, collaborator tags, audio, link in bio updates, and add-to-story triggers. Deep Warming is also exclusive to Instagram accounts.

All content types support scheduling. All post types are submitted through the native app, not through Meta or TikTok's official upload APIs — which is what preserves native features, reach, and algorithm treatment.

Most developers don't use the TokPortal API in isolation. It slots into existing content pipelines, distribution workflows, and marketing automation stacks. Here's how the integrations break down by use case:

Visual workflow builders: If your team uses n8n, you can wire TokPortal API calls directly into automated workflows — trigger posting from a CMS publish event, a Google Sheets row, or a webhook from your product. Make.com works the same way for scenario-based automation. Zapier connects TokPortal to 5,000+ apps if you need lighter-touch no-code integration.

AI agent integration: TokPortal has an MCP (Model Context Protocol) server that lets AI agents — Claude, ChatGPT, or custom agents — autonomously create accounts, schedule videos, and manage campaigns. If you're building an AI-powered content distribution system, the MCP server integration is the fastest path to agent-controlled social distribution.

CRM and data tools: TokPortal webhooks pipe events directly into Airtable, HubSpot, or Salesforce. Use post-published events to trigger CRM workflows, update campaign tracking records, or fire attribution events in your analytics stack.

Polling the analytics endpoint every few minutes is inefficient. TokPortal's webhook system lets you register an endpoint and receive push notifications for every meaningful state change. This is the right architecture for production pipelines.

Key webhook events include: post.published (video went live on TikTok or Instagram), post.failed (post attempt failed with reason), warming.complete (account warming finished), account.flagged (account needs attention), and analytics.updated (new performance data available). Each event payload includes the bundle ID, account details, timestamp, and event-specific metadata.

In practice, this means you can build a pipeline where: a video is approved in your CMS → your system POSTs to TokPortal's upload endpoint → TokPortal posts the video natively → a post.published webhook fires → your analytics dashboard updates automatically → your CRM logs the distribution event. Zero polling, zero manual checking.

Full webhook payload schemas and signature verification instructions are at developers.tokportal.com.

One of the strongest use cases for the TokPortal API is distributing the same video content across multiple countries simultaneously. Here's the logic: TikTok's algorithm is regional. A video posted from a US account reaches a US audience. The same video posted from a German account with German hashtags reaches a German audience. If you want multi-market organic reach, you need accounts in each market — and those accounts need to look local, not like a VPN cluster.

Via the API, you create bundles specifying the target country at provisioning time. A typical multi-market distribution script: create one bundle per target country → warm each account → build a posting loop that uploads the same video (with localized captions and hashtags) to each bundle on a stagger → collect analytics per bundle to compare regional performance.

The API supports 30+ countries including USA, UK, France, Germany, Canada, Australia, Brazil, Indonesia, Philippines, Malaysia, and more. Country availability is returned from the /countries endpoint so you can query it programmatically before provisioning.

When building a pipeline, you need to model costs accurately. Here's the full credit breakdown for API-triggered operations: