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

# Identities and accounts

> How Bastion models customers as Identities (KYC/KYB anchor) and Accounts (wallets and balances), including status fields, sub-statuses, and permissions.

Bastion uses a two-tier hierarchy to manage customers and their financial operations: **Identities** at the top level and **Accounts** beneath them. This separation provides flexibility for compliance, multi-wallet scenarios, and organizational structures.

## Identity

An **Identity** represents a verified individual or business entity in the Bastion system. It serves as the compliance and regulatory anchor for all financial activity.

| Aspect     | Description                                                                              |
| ---------- | ---------------------------------------------------------------------------------------- |
| Purpose    | Acts as the subject of KYC (Know Your Customer) or KYB (Know Your Business) verification |
| Compliance | Stores verification status, jurisdiction information, and regulatory checks              |
| Ownership  | Can own multiple Accounts for different purposes                                         |
| Types      | `INDIVIDUAL` for personal customers, `BUSINESS` for corporate entities                   |

Key properties of an Identity:

| Property                        | Description                                                                                                                                    |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `identity_id`                   | Unique identifier assigned by Bastion                                                                                                          |
| `type`                          | Either `INDIVIDUAL` or `BUSINESS`                                                                                                              |
| `status`                        | Current compliance status (`ACTIVE`, `PENDING_ONBOARDING`, `REJECTED`, `SUSPENDED`, `TERMINATED`)                                              |
| `sub_status`                    | Onboarding detail when status is `PENDING_ONBOARDING` (e.g. compliance running, IDV steps, RFI); otherwise not meaningful / often unspecified. |
| `fiat_operations_enabled`       | Whether the identity has passed compliance and can perform fiat operations (on/off-ramp conversions)                                           |
| `allowed_to_transact_fungibles` | Whether the identity can use crypto transfers. Automatically set to `true` once sanctions and jurisdiction checks pass.                        |

Each identity must have a unique email address. Bastion does not allow the same email address to be used across multiple identities for stablecoin conversions.

### `identity.status` values

| Value                | Meaning                                                                                            |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| `PENDING_ONBOARDING` | Identity created; onboarding workflow in progress. See `sub_status` for the precise step.          |
| `ACTIVE`             | KYC/KYB approved, identity is able to transact                                                     |
| `SUSPENDED`          | Previously active; temporarily suspended by Bastion Compliance                                     |
| `REJECTED`           | KYC/KYB denied during onboarding. Identity is not able to transact or proceed with account opening |
| `TERMINATED`         | Identity and all associated accounts are permanently closed.                                       |

### `identity.sub_status` values

| Value                           | Meaning                                                                                                                     |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `CREATED`                       | Identity exists; no compliance work has started yet.                                                                        |
| `COMPLIANCE_CHECKS_IN_PROGRESS` | KYC/KYB checks running.                                                                                                     |
| `IDV_REQUIRED`                  | Identity-document verification needs to be initiated. IDV will only be required for KYC / individual identities.            |
| `IDV_REQUESTED`                 | IDV link sent to the user; awaiting completion. IDV will only be required for KYC / individual identities.                  |
| `IDV_IN_PROGRESS`               | User has started but not finished IDV. IDV will only be required for KYC / individual identities.                           |
| `IDV_EXPIRED`                   | IDV session expired before completion; needs to be re-requested. IDV will only be required for KYC / individual identities. |
| `RFI_REQUIRED`                  | Request-for-information initiated by Bastion (additional documents/data).                                                   |

## Account

An **Account** belongs to an Identity and is the operational unit for financial activity. This is where balances live, transactions originate, and wallet addresses are managed.

| Aspect      | Description                                                                                         |
| ----------- | --------------------------------------------------------------------------------------------------- |
| Purpose     | Holds balances and initiates transactions                                                           |
| Wallets     | Each account receives wallet addresses for supported blockchains                                    |
| Flexibility | An Identity can have multiple Accounts (e.g., for different currencies, use cases, or sub-entities) |
| Isolation   | Balances and transaction history are isolated per Account                                           |

Key properties of an Account:

| Property         | Description                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| `account_id`     | Unique identifier for the account                                                              |
| `identity_id`    | The parent Identity this account belongs to                                                    |
| `account_type`   | Either `SEGREGATED` or `OMNIBUS`. See [Account types](/guides/concepts/custody#account-types). |
| `addresses`      | Wallet addresses mapped to supported chains                                                    |
| `account_status` | Current account status (`ACTIVE`, `FROZEN`, `CLOSED`)                                          |

### `account.status` values

| Value    | Meaning                                                                    |
| -------- | -------------------------------------------------------------------------- |
| `ACTIVE` | Account is cleared to transact and usable.                                 |
| `FROZEN` | Account is blocked (derived from a SUSPENDED parent identity).             |
| `CLOSED` | Account is permanently closed (derived from a TERMINATED parent identity). |

## How identities and accounts relate

An Identity owns one or more Accounts. Each Account has its own balances, wallet addresses, and transaction history, isolated from other Accounts under the same Identity.

<Frame>
  <img src="https://mintcdn.com/bastion/Td2uKqiXbTwasRAd/images/diagrams/identity-accounts-relationship.svg?fit=max&auto=format&n=Td2uKqiXbTwasRAd&q=85&s=fa010faa00a7046b8b9fe76f1de856b9" alt="An identity record owns one or more accounts, each with its own balances, wallets, and transactions" width="900" height="700" data-path="images/diagrams/identity-accounts-relationship.svg" />
</Frame>

## Account types

Every account is either `SEGREGATED`, holding its own on-chain wallet addresses with chain-specific balances, or `OMNIBUS`, where funds are pooled in a custody vault and Bastion tracks each account's balance on an internal ledger. Both are fully custodial under Bastion's US regulated licensing, and your platform uses the same APIs either way.

See [Custody](/guides/concepts/custody#account-types) for how each model holds assets and how balances are returned.

## Common patterns for multiple accounts

| Pattern          | Description                                                         |
| ---------------- | ------------------------------------------------------------------- |
| Multi-currency   | Separate accounts for different fiat currency settlements           |
| Segregated funds | Isolate customer funds from operational funds                       |
| Sub-entities     | A business Identity with accounts for each department or subsidiary |
| Testing          | Maintain separate accounts for sandbox and production               |

## Compliance

An Identity must pass compliance verification (KYC for individuals, KYB for businesses) before accounts can be created or financial operations can begin.

<Frame>
  <img src="https://mintcdn.com/bastion/Td2uKqiXbTwasRAd/images/diagrams/identity-lifecycle.svg?fit=max&auto=format&n=Td2uKqiXbTwasRAd&q=85&s=9a985c9b0c08a11286664c34909c47fc" alt="Identity lifecycle: create identity, submit compliance, await approval, create accounts, transact" width="900" height="610" data-path="images/diagrams/identity-lifecycle.svg" />
</Frame>

* Identity `status` must be `ACTIVE` before creating an account.
* `allowed_to_transact_fungibles` must be `true` before submitting crypto transfers.
* `fiat_operations_enabled` must be `true` before initiating on/off-ramp conversions.
* Compliance requirements vary by jurisdiction and identity type. Business identities typically require more documentation (articles of incorporation, beneficial owner information).
* Some operations may require additional verification even after initial approval.

For step-by-step onboarding instructions, see [Onboard an individual customer](/guides/quickstarts/onboard-an-individual-customer) or [Onboard a business customer](/guides/quickstarts/onboard-a-business-customer).

## Related documentation

* **Concepts**

  * [Custody](/guides/concepts/custody)
  * [Crypto transfers](/guides/concepts/crypto-transfers)
  * [Stablecoin conversions](/guides/concepts/stablecoin-conversions)

* **Getting started**

  * [Onboard an individual customer](/guides/quickstarts/onboard-an-individual-customer)
  * [Onboard a business customer](/guides/quickstarts/onboard-a-business-customer)

* **API reference**

  * [Accounts](/v2/api-reference/accounts/overview)
  * [Identities](/v2/api-reference/identities/overview)


## Related topics

- [Compliance API overview](/v2/api-reference/compliance/overview.md)
- [Get Identity](/v2/api-reference/identities/get-identity.md)
- [Create Identity](/v2/api-reference/identities/create-identity.md)
- [Create an account in the Bastion Dashboard](/guides/dashboard/creating-accounts.md)
- [Product updates](/changelog.md)