Accounts

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:

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

{
  "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:

Person
Business

For individual users. Provide identity details under the person field:

{
  "entity_type": "person",
  "person": {
    "name": { "first": "Jane", "middle": "M", "last": "Doe" },
    "birth_date": "1990-05-15",
    "sex": "female"
  }
}

For business entities. Provide details under the business field:

{
  "entity_type": "business",
  "business": {
    "legal_name": "Acme Corp",
    "registration_number": "REG-12345",
    "tax_id": "TAX-67890"
  }
}

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:

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

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:

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:

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:

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

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.

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 to begin collecting applicant information and running verifications.

Overview

Workflow API

Credentials API

Document API

Identity API (Legacy)

What is an Account?

Account Statuses

Creating an Account

Response

Entity Types

Using `external_id`

Updating an Account

Reading Account Status

Redacting an Account

Relationships

Next Steps

​What is an Account?

​Account Statuses

​Creating an Account

​Response

​Entity Types

​Using external_id

​Updating an Account

​Reading Account Status

​Redacting an Account

​Relationships

​Next Steps

What is an Account?

Account Statuses

Creating an Account

Response

Entity Types

Using `external_id`

Updating an Account

Reading Account Status

Redacting an Account

Relationships

Next Steps