Skip to main content

​
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

StatusDescription
activeThe account is active and in good standing
pendingThe account is awaiting verification or review
inactiveThe account has been deactivated
suspendedThe 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:
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"
  }
}

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