Skip to main content

​
Overview

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

​
Fields

FieldTypeDescription
idstringUnique account identifier
typestringPlatform type: 'tiktok' or 'instagram'
tagstring | nullCustom tag for categorization
org_groupstring | nullOrganization group identifier
user_groupstring | nullUser group identifier
usernamestring | nullAccount username/handle on the platform
nick_namestring | nullDisplay name shown on profile
pfp_urlstring | nullURL to account’s profile picture
warmup_enabledboolean | nullWhether warmup tasks are enabled for this account
warmup_version'original' | 'v1_smart' | nullWarmup scheduling algorithm version. 'original' uses the standard scheduling logic, 'v1_smart' uses an optimized algorithm with custom flows
descriptionstring | nullDescription/interest area for the account. Used by v1_smart warmup for browse tasks
keywordsstring | nullSearch keywords used for warmup tasks (comma-separated)
profilesstring | nullProfile usernames to search for warmup tasks (comma-separated)
phone_typestring | nullAccount hosting type: 'physical_iphone', 'physical_android', 'emulated_android', 'social_api', or 'tracking'. Tracking accounts are read-only and cannot be used for posting
approvedbooleanWhether the account configuration follows recommended best practices. Defaults to true. Set to false when a user overrides guidelines.
statusstringAccount status: 'pending', 'initialized', 'setup', 'warming', 'warmed', 'needs_replacement', or 'replacing'

​
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:
StatusDescription
pendingAccount is awaiting initialization
initializedAccount has been created but not fully set up
setupAccount is fully configured and ready for warmup
warmingAccount is currently in the warmup phase
warmedAccount has completed warmup and is ready for posting
needs_replacementAccount needs to be replaced with a new one
replacingAccount is being replaced

​
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",
  "approved": true,
  "status": "warmed"
}