> ## 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.

# Create Accounts

> Create new account seats and update your subscription billing

## Endpoint

```
POST https://api.ugc.inc/accounts/create
```

## Overview

Create one or more new account seats for your organization. This endpoint automatically updates your Stripe subscription billing based on the tier of each account.

* If only `tier` is provided, the account is created with status `uninitialized`
* If all detail fields (`tier`, `platform`, `username`, `pfp_url`, `keywords`) are provided, the account is created with status `pending` and will begin setup automatically
* If some but not all detail fields are provided, a **400 error** is returned

## Request Body

<ParamField body="accounts" type="array" required>
  Array of accounts to create. Each account object contains:

  <Expandable title="Account object properties">
    <ParamField body="tier" type="'basic' | 'premium'" required>
      Subscription tier for the account. Determines the device type and billing rate.

      * `basic` — \$40/mo per account
      * `premium` — \$100/mo per account
    </ParamField>

    <ParamField body="platform" type="'tiktok' | 'instagram'">
      Social media platform. Required if providing account details.
    </ParamField>

    <ParamField body="username" type="string">
      Account username/handle on the platform. Required if providing account details.
    </ParamField>

    <ParamField body="pfp_url" type="string">
      URL to the account's profile picture. Required if providing account details.
    </ParamField>

    <ParamField body="keywords" type="string">
      Comma-separated keywords for warmup activities. Required if providing account details.
    </ParamField>

    <ParamField body="nick_name" type="string">
      Display name shown on profile
    </ParamField>

    <ParamField body="bio" type="string">
      Account bio text
    </ParamField>

    <ParamField body="age_range" type="string">
      Age range for the account persona
    </ParamField>

    <ParamField body="sex" type="string">
      Sex/gender for the account persona
    </ParamField>

    <ParamField body="location" type="string">
      Geographic location for the account
    </ParamField>

    <ParamField body="description" type="string">
      Description/interest area for the account. Used by v1\_smart warmup for browse tasks
    </ParamField>

    <ParamField body="tag" type="string">
      Custom tag for categorization
    </ParamField>

    <ParamField body="org_group" type="string">
      Organization group identifier
    </ParamField>

    <ParamField body="user_group" type="string">
      User group identifier
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  When providing account details, all four fields (`platform`, `username`, `pfp_url`, `keywords`) must be present. Providing some but not all will result in a 400 error.
</Note>

## Response

<ResponseField name="data" type="object">
  Response object containing success summary and created accounts

  <Expandable title="Response properties">
    <ResponseField name="message" type="string">
      Summary message indicating how many accounts were created
    </ResponseField>

    <ResponseField name="successful" type="number">
      Number of accounts successfully created
    </ResponseField>

    <ResponseField name="failed" type="number">
      Number of accounts that failed to create
    </ResponseField>

    <ResponseField name="accounts" type="array">
      Array of created account summaries

      <Expandable title="Account summary properties">
        <ResponseField name="id" type="string">
          Unique account identifier
        </ResponseField>

        <ResponseField name="tier" type="'basic' | 'premium'">
          Account tier
        </ResponseField>

        <ResponseField name="status" type="'uninitialized' | 'pending'">
          Account status after creation
        </ResponseField>

        <ResponseField name="platform" type="string | null">
          Platform type (if details were provided)
        </ResponseField>

        <ResponseField name="username" type="string | null">
          Username (if details were provided)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.ugc.inc/accounts/create \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "accounts": [
        {
          "tier": "basic"
        },
        {
          "tier": "premium",
          "platform": "tiktok",
          "username": "newcreator",
          "pfp_url": "https://example.com/avatar.jpg",
          "keywords": "fitness,health,workout",
          "nick_name": "New Creator",
          "tag": "influencer"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.ugc.inc/accounts/create',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'accounts': [
              {
                  'tier': 'basic'
              },
              {
                  'tier': 'premium',
                  'platform': 'tiktok',
                  'username': 'newcreator',
                  'pfp_url': 'https://example.com/avatar.jpg',
                  'keywords': 'fitness,health,workout',
                  'nick_name': 'New Creator',
                  'tag': 'influencer'
              }
          ]
      }
  )

  data = response.json()

  if data['ok']:
      print(f"Created {data['data']['successful']} account(s)")
      for account in data['data']['accounts']:
          print(f"  {account['id']} - {account['tier']} ({account['status']})")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.ugc.inc/accounts/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      accounts: [
        {
          tier: 'basic'
        },
        {
          tier: 'premium',
          platform: 'tiktok',
          username: 'newcreator',
          pfp_url: 'https://example.com/avatar.jpg',
          keywords: 'fitness,health,workout',
          nick_name: 'New Creator',
          tag: 'influencer'
        }
      ]
    })
  });

  const data = await response.json();

  if (data.ok) {
    console.log(`Created ${data.data.successful} account(s)`);
    data.data.accounts.forEach(account => {
      console.log(`  ${account.id} - ${account.tier} (${account.status})`);
    });
  }
  ```

  ```typescript React theme={null}
  import { UGCClient } from 'ugcinc';

  const client = new UGCClient({
    apiKey: 'YOUR_API_KEY'
  });

  const response = await client.accounts.createAccounts({
    accounts: [
      {
        tier: 'basic'
      },
      {
        tier: 'premium',
        platform: 'tiktok',
        username: 'newcreator',
        pfp_url: 'https://example.com/avatar.jpg',
        keywords: 'fitness,health,workout',
        nick_name: 'New Creator',
        tag: 'influencer'
      }
    ]
  });

  if (response.ok) {
    console.log(`Created ${response.data.successful} account(s)`);
    response.data.accounts.forEach(account => {
      console.log(`${account.id} - ${account.tier} (${account.status})`);
    });
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Success",
    "data": {
      "message": "Successfully created 2 account(s)",
      "successful": 2,
      "failed": 0,
      "accounts": [
        {
          "id": "acc_123456",
          "tier": "basic",
          "status": "uninitialized",
          "platform": null,
          "username": null
        },
        {
          "id": "acc_789012",
          "tier": "premium",
          "status": "pending",
          "platform": "tiktok",
          "username": "newcreator"
        }
      ]
    }
  }
  ```

  ```json Error - Missing Detail Fields theme={null}
  {
    "ok": false,
    "code": 400,
    "message": "Account 0: When providing account details, all of 'username', 'pfp_url', 'keywords', and 'platform' are required. Missing: pfp_url, keywords"
  }
  ```

  ```json Error - No Billing theme={null}
  {
    "ok": false,
    "code": 400,
    "message": "No billing record linked to this organization. Please set up billing first."
  }
  ```
</ResponseExample>