Onboard an individual customer

Goal

Onboard an individual customer to Bastion so they can hold digital assets and use conversions and transfers.

Key entities

Entity	Description
Your platform	The product integrating Bastion’s APIs
Individual customer	A person your platform onboards and verifies
Identity	The record of an individual customer in Bastion, used for KYC and permissions
Account	A unique operational unit tied to an Identity. Each Account has its own wallet address per supported blockchain and is used to perform transactions

Flow overview

The steps needed to onboard and transact an individual customer are:

Create identity
Submit KYC
Track status
1. (Conditionally required) Identity verification check
Create account
Start transacting

Simulation for sandbox testing

Refer to sandbox testing and simulations for a guide on how to use simulation labels to simulate both the onboarding and IDV checks to facilitate testing.

Prerequisites

You have access to your dashboard
You’ve created an API key
You’ve registered a webhook

Step 1 – create an individual identity

Create an identity in Bastion as soon as your customer signs up or when they first try to use financial features. Request

POST /v2/identities
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "label": "merchant-user-48291",
  "identity_type": "INDIVIDUAL"
}

Response

{
 "id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
 "identity_type": "INDIVIDUAL",
 "account_ids": [],
  "label": "merchant-user-48291",
  "fiat_operations_enabled": false,
  "status": "PENDING_ONBOARDING",
  "sub_status": "CREATED"
}

Store the returned identity_id alongside your internal customer ID for all future calls.

Tip: Use label for a stable, non-PII identifier (e.g., your internal customer ID). Do not include names, emails, or phone numbers.

Step 2 – submit KYC data

Submit KYC information for the identity. Your platform collects this data and sends it to Bastion. Request

POST /v2/identities/{identity_id}/compliance
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "kyc": {
    "first_name": "Jane",
    "middle_name": "Q",
    "last_name": "Doe",
    "date_of_birth": "1990-04-20",
    "ip_address": "203.0.113.10",
    "physical_address": {
      "street_line_1": "123 Market St",
      "street_line_2": "Suite 400",
      "city": "San Francisco",
      "postal_code": "94105",
      "country": "US",
      "region_code": "CA"
    },
    "tax_id_number": "123-45-6789",
    "phone_number": "+14155552671",
    "email_address": "jane.doe@example.com",
    "account_purpose": "TRADING",
    "source_of_funds": "EMPLOYMENT_SALARY",
    "occupation": "FINANCE_AND_INSURANCE",
    "nationality": "US",
    "country_of_birth": "US",
    "additional_id_number": "D1234567"
  }
}

Bastion processes KYC asynchronously. It updates the status over time and emits webhook events, or you can poll as described below.

Step 3 – track KYC status

Track KYC status via

identity_status_update webhooks (recommended) or
polling via GET /v2/identities/{identity_id}

Typically, most KYC checks are approved within seconds once data is submitted.

Option A: webhooks

Configure a webhook endpoint in the Bastion Dashboard to react to KYC status changes in real time. Event: identity_status_update Example event

{
  "id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
  "type": "identity_status_update",
  "data": {
    "identity": {
      "id": "3CPgtujGnpORK9EKaXu5U9OclxU",
      "label": "merchant-user-48291",
      "identity_type": "INDIVIDUAL",
      "status": "ACTIVE"
    },
    "affected_account_ids": [],
    "status_reason": null,
    "previous_status": "PENDING_ONBOARDING",
    "previous_sub_status": "COMPLIANCE_CHECKS_IN_PROGRESS"
  }
}

Use this event to:

Mark the customer as approved or failed in your system
Enable or block access to financial features

Option B: polling

Poll the identity endpoint as a fallback.

GET /v2/identities/{identity_id}
Authorization: Bearer YOUR_API_KEY

Response (approved)

{
 "id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
 "identity_type": "INDIVIDUAL",
 "account_ids": [],
  "label": "merchant-user-48291",
  "fiat_operations_enabled": false,
  "status": "ACTIVE",
  "sub_status": "IDENTITY_SUB_STATUS_UNSPECIFIED"
}

Key fields

Field	Meaning
`status`	`ACTIVE`: Onboarding completed and identity is available to transact
`sub_status`	Onboarding detail when status is `PENDING_ONBOARDING` (e.g. compliance running, IDV steps, RFI); otherwise not meaningful / often unspecified
`allowed_to_transact_fungibles`	Whether the identity can use crypto transfers
`fiat_operations_enabled`	Whether on/off-ramp conversions are enabled

Only proceed to account creation after status = ACTIVE.

Terminal KYC statuses

A KYC attempt resolves to one of two terminal statuses:

Status	Meaning
`ACTIVE`	KYC approved. Inform the customer of successful onboarding and proceed to downstream actions, such as account creation.
`REJECTED`	KYC denied. The identity is not able to transact or proceed with account opening.

Any other status (for example PENDING_ONBOARDING) means the attempt is still in progress. Keep listening for identity_status_update events or continue polling. For the full list of identity statuses, see Identities and accounts.

Step 3a – identity verification

For a subset of identities undergoing KYC, Bastion may require you to run an additional identity verification (IDV) process. When required, Bastion emits the identity_status_update event.

{
  "id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
  "type": "identity_status_update",
  "data": {
    "identity": {
      "id": "3CPgtujGnpORK9EKaXu5U9OclxU",
      "label": "merchant-user-48291",
      "identity_type": "INDIVIDUAL",
      "status": "PENDING_ONBOARDING",
      "sub_status": "IDV_REQUIRED"
    },
    "affected_account_ids": [],
    "status_reason": null,
    "previous_status": "PENDING_ONBOARDING",
    "previous_sub_status": null
  }
}

When IDV is required, create a new IDV by using the endpoint /v2/identities/{identity_id}/id_verification. Request

{
  "identity_id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
  "redirect_url": "https://yourapp.example/idv/return",
  "reason": "ONBOARDING",
  "request_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Response

{
  "id": "01HZXIDVCHK0000000001",
  "identity_id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
  "verification_url": "https://idv.vendor.example/session/abc123",
  "reason": "ONBOARDING",
  "request_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "redirect_url": "https://yourapp.example/idv/return",
  "status": "IN_PROGRESS",
  "created_at": "2026-04-20T16:00:00Z",
  "updated_at": "2026-04-20T16:00:00Z"
}

Provide the returned verification_url to the onboarding end user to undergo IDV. Continue polling (or listening to the webhook) for the identity status to turn ACTIVE as the signal for KYC completion.

The source of truth for identity status is the identity’s status field: data.identity.status on the identity_status_update webhook, or GET identity. Do not rely on the status of IDV checks.

Step 4 – create an account

Once status is ACTIVE, create an account linked to the identity. Use a unique request_id (UUID) as an idempotency key. Reuse the same request_id on retries to avoid duplicate accounts. Request

POST /v2/accounts
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "identity_id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
  "type": "SEGREGATED"
}

Response

{
  "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "identity_type": "INDIVIDUAL",
  "addresses": [
    {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "chains": ["ETHEREUM_MAINNET", "BASE_MAINNET"]
    },
    {
      "address": "DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK",
      "chains": ["SOLANA_MAINNET"]
    }
  ],
  "identity_id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
  "id": "01HZXBANKACCOUNTIDEXAMPLE0",
  "type": "SEGREGATED",
  "frozen": false,
  "identity_status": "ACTIVE",
  "identity_sub_status": "IDENTITY_SUB_STATUS_UNSPECIFIED",
  "account_status": "ACTIVE"
}

Capture the account_id. Use this account for:

Checking balances
On-ramp and off-ramp conversions
Crypto transfers

Step 5 – verify setup

Confirm the customer is fully ready:

Check identity status — GET /v2/identities/{identity_id}
Check account — Verify account_ids includes the new account and account_status = ACTIVE
Check balances (optional) — GET /v2/accounts/{account_id}/balances

Next actions:

Top up via on-ramp (USD → stablecoin)
Send crypto via /v2/crypto/transfers
Withdraw via off-ramp (stablecoin → USD)

Implementation notes

Recommendation	Details
Wait for KYC approval	Accounts cannot be created until `status = ACTIVE`. Always wait before enabling money movement. Most KYC checks are approved within seconds once data and documents are submitted.
Mirror in your database	Store `identity_id`, `account_id`, and status in your own system. Keep in sync via webhooks.
Separate auth from KYC	Your login, session, and device security are separate from Bastion’s KYC. Treat Bastion as the financial/compliance layer only.

Getting Started

Concepts

Quickstarts

Compliance

Security

Bastion Dashboard

LLMs and MCP Server

Onboard an individual customer

Goal

Key entities

Flow overview

Simulation for sandbox testing

Prerequisites

Step 1 – create an individual identity

Step 2 – submit KYC data

Step 3 – track KYC status

Option A: webhooks

Option B: polling

Terminal KYC statuses

Step 3a – identity verification

Step 4 – create an account

Step 5 – verify setup

Implementation notes

​Goal

​Key entities

​Flow overview

​Simulation for sandbox testing

​Prerequisites

​Step 1 – create an individual identity

​Step 2 – submit KYC data

​Step 3 – track KYC status

​Option A: webhooks

​Option B: polling

​Terminal KYC statuses

​Step 3a – identity verification

​Step 4 – create an account

​Step 5 – verify setup

​Implementation notes

Goal

Key entities

Flow overview

Simulation for sandbox testing

Prerequisites

Step 1 – create an individual identity

Step 2 – submit KYC data

Step 3 – track KYC status

Option A: webhooks

Option B: polling

Terminal KYC statuses

Step 3a – identity verification

Step 4 – create an account

Step 5 – verify setup

Implementation notes