Accounts

Connect TikTok, Instagram, Facebook Pages and Threads accounts through a hosted link, and read their capabilities and quota.

Preview

Preview: the API and MCP server are in private beta; details may change.

A connected account (acc_...) is one TikTok creator account, one Instagram Professional account, one Facebook Page, or one Threads account. Accounts are created through a hosted connect link that the account owner opens directly, never by your integration holding their credentials.

Required scope: accounts:write for POST /connect/links, refresh-capabilities and DELETE; accounts:read for GET.

Endpoints

Method	Path	Description
POST	`/connect/links`	Create a hosted connect link for one or more platforms
GET	`/accounts`	List connected accounts, filterable by profile, platform and status
GET	`/accounts/{id}`	Get one account, including its capabilities and quota
POST	`/accounts/{id}/refresh-capabilities`	Re-fetch platform capabilities (for example TikTok `creator_info`) before building your own UI
DELETE	`/accounts/{id}`	Disconnect the account and delete its data

Create a connect link

Request parameters

Name	Type	Required	Description
`profile_id`	string	Yes	The profile (`prof_...`) this account belongs to
`platforms`	array of strings	Yes	Any of `tiktok`, `instagram`, `facebook`, `threads`
`redirect_url`	string	No	Where to send the end user after connecting. Must match a domain allowed in workspace settings

curl -X POST https://api.getimma.com/v1/connect/links \
  -H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f9b6c2e-3b9a-4b8a-9b2e-3f9b6c2e3b9a" \
  -d '{
    "profile_id": "prof_01J...",
    "platforms": ["tiktok", "instagram"]
  }'

Response:

{ "url": "https://getimma.com/connect/k8Fq2..." }

Send this link to the account owner, commonly over Telegram. They log in on each platform's own screen and grant access; nothing is entered on your side. The link expires after 7 days by default.

Get an account

curl https://api.getimma.com/v1/accounts/acc_01J... \
  -H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx"

Response:

{
  "id": "acc_01J...",
  "profile_id": "prof_01J...",
  "platform": "tiktok",
  "status": "active",
  "handle": "@dapursekar",
  "capabilities": {
    "privacy_level_options": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY"],
    "max_video_post_duration_sec": 180
  },
  "quota": {
    "kind": "tiktok_direct_post",
    "used": 3,
    "limit": 15,
    "resets_at": "2026-09-29T00:00:00+07:00"
  }
}

capabilities reflects the platform's own account settings, for example a TikTok account's allowed privacy options and maximum video length (from creator_info), refreshed every time a composer or approval page opens. quota reflects the platform's posting limit for that account; see Platform rules for the limits per platform.

Refresh capabilities

curl -X POST https://api.getimma.com/v1/accounts/acc_01J.../refresh-capabilities \
  -H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx"

Call this before rendering your own composer or approval UI so a TikTok account's privacy options and duration limit are current, instead of relying on a cached value.

Disconnect

curl -X DELETE https://api.getimma.com/v1/accounts/acc_01J... \
  -H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx"

Revokes the platform token where the platform supports it and deletes the account's stored data. Post history stays visible with the account shown as disconnected; only metrics and comments are removed per the retention rules.

Errors

Code	HTTP	When
`unauthorized`	401	Missing or invalid API key
`insufficient_scope`	403	Key lacks `accounts:read` or `accounts:write`
`invalid_redirect_url`	400	`redirect_url` is outside the workspace's allowed domains
`not_found`	404	Account does not exist, or belongs to another workspace
`token_expired`	-	Returned on the account object itself as `status: needs_reconnect`, not as a request error

See Errors for the shared error shape.

Platform notes

TikTok: capabilities for a TikTok account always comes from a fresh creator_info call before it is shown to a user, never a stale cache, because privacy options and duration limits can change between sessions. IMMA AI never picks a privacy level on your behalf; see Platform rules.
Facebook Pages: an account here is one Page. A user who is not a Page admin, or lacks the CREATE_CONTENT task, can be listed but cannot be used as a post target.
Instagram: requires an Instagram Professional (Business or Creator) account; personal accounts cannot be connected.
Threads: connected through a separate Threads app login, independent of the Instagram connection.