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

# Accounts

> Accounts represent external entities in the Beltic Identity platform. Use them to correlate users, track verification status, and manage access.

## What is an Account?

An **Account** is the primary resource for representing an external entity — a person or a business — in the Beltic Identity platform. It serves as the correlation point between your system and Beltic.

When you onboard a user on your platform, you create a corresponding Account in Beltic. From there, you can:

* **Track verification status** by reading the account's status
* **Link sessions and documents** to build a complete identity profile
* **Perform actions** such as suspending or blocking the user on your side based on the account state
* **Store your own reference** via the `external_id` field for easy lookup

## Account Statuses

| Status      | Description                                                   |
| ----------- | ------------------------------------------------------------- |
| `active`    | The account is active and in good standing                    |
| `pending`   | The account is awaiting verification or review                |
| `inactive`  | The account has been deactivated                              |
| `suspended` | The account has been suspended due to policy or risk concerns |

You can read the account status at any time and use it to gate access on your platform. For example, if an account is `suspended`, you might block the user from performing sensitive operations.

## Creating an Account

Create an account by specifying the entity type and providing identity information:

```bash theme={null}
curl -X POST https://api.beltic.com/v1/identity/accounts \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "account",
      "attributes": {
        "external_id": "user-12345",
        "entity_type": "person",
        "person": {
          "name": {
            "first": "Jane",
            "last": "Doe"
          },
          "birth_date": "1990-05-15"
        },
        "contact": {
          "email": "jane@example.com",
          "phone": "+1234567890"
        }
      }
    }
  }'
```

### Response

```json theme={null}
{
  "data": {
    "type": "account",
    "id": "acc_01HQ...",
    "attributes": {
      "status": "pending",
      "external_id": "user-12345",
      "entity_type": "person",
      "person": {
        "name": {
          "first": "Jane",
          "middle": null,
          "last": "Doe"
        },
        "birth_date": "1990-05-15",
        "sex": null
      },
      "business": null,
      "contact": {
        "email": "jane@example.com",
        "phone": "+1234567890"
      },
      "address": null,
      "identity_numbers": [],
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": null,
      "redacted_at": null
    },
    "relationships": {
      "sessions": { "data": [] },
      "documents": { "data": [] }
    }
  }
}
```

## Entity Types

Accounts support two entity types:

<Tabs>
  <Tab title="Person">
    For individual users. Provide identity details under the `person` field:

    ```json theme={null}
    {
      "entity_type": "person",
      "person": {
        "name": { "first": "Jane", "middle": "M", "last": "Doe" },
        "birth_date": "1990-05-15",
        "sex": "female"
      }
    }
    ```
  </Tab>

  <Tab title="Business">
    For business entities. Provide details under the `business` field:

    ```json theme={null}
    {
      "entity_type": "business",
      "business": {
        "legal_name": "Acme Corp",
        "registration_number": "REG-12345",
        "tax_id": "TAX-67890"
      }
    }
    ```
  </Tab>
</Tabs>

## Using `external_id`

The `external_id` field lets you store your own user identifier on the account. This is the recommended way to correlate Beltic accounts with your own database:

```bash theme={null}
# Create with your user ID
curl -X POST https://api.beltic.com/v1/identity/accounts \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "account",
      "attributes": {
        "external_id": "usr_abc123",
        "entity_type": "person"
      }
    }
  }'
```

You can then use the external ID to look up accounts when needed.

## Updating an Account

Update account attributes with a PATCH request:

```bash theme={null}
curl -X PATCH https://api.beltic.com/v1/identity/accounts/{account_id} \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "account",
      "id": "acc_01HQ...",
      "attributes": {
        "contact": {
          "email": "new-email@example.com"
        }
      }
    }
  }'
```

## Reading Account Status

Poll or read the account status to make decisions on your side:

```bash theme={null}
curl -X GET https://api.beltic.com/v1/identity/accounts/{account_id} \
  -H "X-Api-Key: YOUR_API_KEY"
```

Use the `status` field to drive your application logic:

```javascript theme={null}
const account = await getAccount(accountId);

switch (account.data.attributes.status) {
  case 'active':
    // Allow full access
    break;
  case 'pending':
    // Show verification pending message
    break;
  case 'suspended':
    // Block sensitive operations
    break;
  case 'inactive':
    // Prompt re-verification
    break;
}
```

## Redacting an Account

When you need to delete personal data (e.g., for GDPR compliance), redact the account:

```bash theme={null}
curl -X POST https://api.beltic.com/v1/identity/accounts/{account_id}/redact \
  -H "X-Api-Key: YOUR_API_KEY"
```

<Warning>
  Redaction is irreversible. All personal data on the account will be permanently removed. The account record itself is retained with a `redacted_at` timestamp for audit purposes.
</Warning>

## Relationships

An account connects to other Identity resources:

* **Sessions** — Verification sessions created for this account
* **Documents** — Identity documents associated with this account

These relationships are included in the account response and allow you to navigate the complete identity profile from a single entry point.

## Next Steps

Once you have an account, the next step is to [create a session](/guides/identity/sessions) to begin collecting applicant information and running verifications.