Account

Social media account data structure

Overview

Represents a social media account (TikTok or Instagram) that you can manage through the API.

Fields

Field	Type	Description
id	string	Unique account identifier
type	string	Platform type: 'tiktok' or 'instagram'
tag	string | null	Custom tag for categorization
org_group	string | null	Organization group identifier
user_group	string | null	User group identifier
username	string | null	Account username/handle on the platform
nick_name	string | null	Display name shown on profile
pfp_url	string | null	URL to account’s profile picture
warmup_enabled	boolean | null	Whether warmup tasks are enabled for this account
warmup_version	'original' | 'v1_smart' | null	Warmup scheduling algorithm version. 'original' uses the standard scheduling logic, 'v1_smart' uses an optimized algorithm with custom flows
description	string | null	Description/interest area for the account. Used by v1_smart warmup for browse tasks
keywords	string | null	Search keywords used for warmup tasks (comma-separated)
profiles	string | null	Profile usernames to search for warmup tasks (comma-separated)
age_range	string | null	Age band the account’s persona presents as (e.g. '18-24')
sex	string | null	Gender the account’s persona presents as
phone_type	string | null	Account hosting type: 'physical_iphone', 'physical_android', 'emulated_android', 'social_api', or 'tracking'. Tracking accounts are read-only and cannot be used for posting
approved	boolean	Whether the account configuration follows recommended best practices. Defaults to true. Set to false when a user overrides guidelines.
status	string	Account status: 'pending', 'initialized', 'setup', 'warming', 'warmed', 'needs_replacement', 'replacing', or 'quarantined'

Account Organization

The org_group and user_group fields allow you to organize and subdivide accounts:

Organization Groups (org_group)

• Group accounts by department, campaign, or purpose
• Examples: "marketing", "sales", "influencer_campaign_2024"
• Use for filtering accounts by business unit or project
• Multiple accounts can share the same org_group

User Groups (user_group)

• Assign accounts to specific team members or users
• Examples: "john_smith", "team_alpha", "content_creator_1"
• Use for access control and responsibility assignment
• Allows filtering accounts by assigned user/team

Example Use Cases

// Filter accounts by organization group
const marketingAccounts = await client.accounts.getAccounts({
  org_group: 'marketing'
});

// Filter accounts by user assignment
const johnsAccounts = await client.accounts.getAccounts({
  user_group: 'john_smith'
});

// Combine filters
const campaignAccounts = await client.accounts.getAccounts({
  org_group: 'holiday_campaign_2024',
  user_group: 'content_team'
});

Account Status

The status field indicates the current lifecycle stage of an account:

Status	Description
pending	Account is awaiting initialization
initialized	Account has been created but not fully set up
setup	Account is fully configured and ready for warmup
warming	Account is currently in the warmup phase
warmed	Account has completed warmup and is ready for posting
needs_replacement	Account needs to be replaced with a new one
replacing	Account is being replaced
quarantined	Account is paused and will not post. Set when the platform has blocked it — for example a human-verification prompt, a signed-out session, or content strikes — so scheduled posts stop failing until the block is cleared. Nothing is deleted: releasing the account returns it to the status it held before.

Example Response

{
  "id": "acc_123456",
  "type": "tiktok",
  "tag": "influencer",
  "org_group": "marketing",
  "user_group": "john_smith",
  "username": "coolcreator",
  "nick_name": "Cool Creator",
  "pfp_url": "https://storage.example.com/avatar.jpg",
  "warmup_enabled": true,
  "warmup_version": "original",
  "description": "health and wellness content",
  "keywords": "fitness,workout,health",
  "profiles": "fitnessguru,healthcoach",
  "age_range": "18-24",
  "sex": "female",
  "approved": true,
  "status": "warmed"
}