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

# Accounts

> Create and manage sub-accounts for your customers.

Sub-accounts map 1:1 to your customers. Each sub-account gets isolated data (conversations, leads, settings) and its own phone number.

## Create Account

<ParamField body="name" type="string" required>
  Display name for the account
</ParamField>

<ParamField body="company_name" type="string">
  Company name used by the AI in conversations. Defaults to `name`.
</ParamField>

<ParamField body="phone_number" type="string">
  Twilio number in E.164 format. If omitted, one is provisioned automatically.
</ParamField>

<ParamField body="forwarding_number" type="string">
  Number to forward voice calls to (E.164)
</ParamField>

<ParamField body="branding.logo_url" type="string">
  Logo URL for white-label embed
</ParamField>

<ParamField body="branding.accent_color" type="string">
  Hex color for UI accent (e.g., `#2563EB`)
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs for your internal tracking
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.recoverbiz.com/v1/accounts \
    -H "X-Partner-Key: pk_live_abc123def456..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Acme Lending",
      "company_name": "Acme Lending Corp",
      "forwarding_number": "+14155559999",
      "branding": {
        "logo_url": "https://acme.com/logo.png",
        "accent_color": "#1E40AF"
      },
      "metadata": {
        "internal_id": "lender_42",
        "tier": "premium"
      }
    }'
  ```

  ```typescript JavaScript theme={null}
  const res = await fetch('https://api.recoverbiz.com/v1/accounts', {
    method: 'POST',
    headers: {
      'X-Partner-Key': 'pk_live_abc123def456...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Acme Lending',
      company_name: 'Acme Lending Corp',
      forwarding_number: '+14155559999',
      branding: {
        logo_url: 'https://acme.com/logo.png',
        accent_color: '#1E40AF',
      },
      metadata: { internal_id: 'lender_42', tier: 'premium' },
    }),
  });
  const account = await res.json();
  ```

  ```python Python theme={null}
  account = requests.post(f'{BASE_URL}/accounts', headers=headers, json={
      'name': 'Acme Lending',
      'company_name': 'Acme Lending Corp',
      'forwarding_number': '+14155559999',
      'branding': {
          'logo_url': 'https://acme.com/logo.png',
          'accent_color': '#1E40AF'
      },
      'metadata': {'internal_id': 'lender_42', 'tier': 'premium'}
  }).json()
  ```
</CodeGroup>

**Response: `201 Created`**

```json theme={null}
{
  "id": "acc_8f3a1b2c",
  "name": "Acme Lending",
  "company_name": "Acme Lending Corp",
  "slug": "acme-lending",
  "status": "active",
  "phone_number": "+14155551234",
  "forwarding_number": "+14155559999",
  "branding": {
    "logo_url": "https://acme.com/logo.png",
    "accent_color": "#1E40AF"
  },
  "metadata": {
    "internal_id": "lender_42",
    "tier": "premium"
  },
  "created_at": "2026-02-15T10:30:00Z"
}
```

## List Accounts

<ParamField query="limit" type="integer" default="50">
  Max results (1-250)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Pagination offset
</ParamField>

<ParamField query="status" type="string">
  Filter by `active` or `deactivated`
</ParamField>

<ParamField query="search" type="string">
  Search by name
</ParamField>

```bash theme={null}
curl https://api.recoverbiz.com/v1/accounts?limit=10&status=active \
  -H "X-Partner-Key: pk_live_abc123def456..."
```

**Response: `200 OK`**

```json theme={null}
{
  "accounts": [
    {
      "id": "acc_8f3a1b2c",
      "name": "Acme Lending",
      "status": "active",
      "phone_number": "+14155551234",
      "stats": {
        "total_leads": 342,
        "total_conversations": 289,
        "active_sequences": 15
      },
      "created_at": "2026-02-15T10:30:00Z"
    }
  ],
  "total": 47,
  "limit": 10,
  "offset": 0
}
```

## Get Account

```bash theme={null}
curl https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c \
  -H "X-Partner-Key: pk_live_abc123def456..."
```

Returns the full account object including branding, metadata, phone number, and current stats.

## Update Account

Update any mutable fields on a sub-account.

```bash theme={null}
curl -X PATCH https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c \
  -H "X-Partner-Key: pk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Financial Services",
    "branding": {
      "accent_color": "#DC2626"
    }
  }'
```

## Deactivate Account

Soft-deactivates the account. Conversations and data are preserved but the AI stops responding to inbound messages and sequences are paused.

```bash theme={null}
curl -X DELETE https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c \
  -H "X-Partner-Key: pk_live_abc123def456..."
```

**Response: `200 OK`**

```json theme={null}
{
  "id": "acc_8f3a1b2c",
  "status": "deactivated",
  "deactivated_at": "2026-02-15T18:00:00Z"
}
```

To reactivate, use `PATCH /accounts/:id` with `{"status": "active"}`.

## Team Members

Sub-accounts support multiple team members, each with their own phone number for multi-agent routing:

```bash theme={null}
curl -X POST https://api.recoverbiz.com/v1/accounts/acc_8f3a1b2c/team/invite \
  -H "X-Partner-Key: pk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@acmelending.com",
    "name": "Sarah Johnson",
    "role": "member",
    "phone_number": "+14155555678",
    "forwarding_number": "+14155559999"
  }'
```

Each team member can have independent AI configurations, context files, and sequences.