> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ugc.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript theme={null}
// 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

```json theme={null}
{
  "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"
}
```