---
title: "Retrieve a virtual account"
method: GET
path: "/virtual_accounts/{id}"
tags: ["Virtual Accounts"]
---

# Retrieve a virtual account

`GET /virtual_accounts/{id}`

## Request

- Base URL: `https://api.cert.zerohash.com`
- URL: `https://api.cert.zerohash.com/virtual_accounts/{id}`
- Auth: API key in header `X-SCX-API-KEY` and API key in header `X-SCX-PASSPHRASE`

Returns a single virtual account. `bank_details` is populated once `status` leaves `PENDING`. An unknown id or an account belonging to another platform return `404 Not Found`.

## Path parameters

- `id` string, uuid, required

## Headers

- `X-SCX-SIGNED` string, required
- `X-SCX-TIMESTAMP` string, required

## Response `200`

The virtual account.

- VirtualAccount
  - `id` string, uuid: The virtual account identifier, equal to the `Idempotency-Key` supplied on creation.
  - `participant_code` string
  - `platform_code` string
  - `provider_type` 'CRB', nullable: Banking partner backing the account.
  - `status` 'PENDING' | 'ACTIVE' | 'CLOSING' | 'CLOSED' | 'BLOCKED' | 'FAILED', nullable: Lifecycle state. `PENDING` until the banking partner issues the account; `FAILED` when the banking partner declined to onboard the customer; `CLOSED`, `BLOCKED` and `FAILED` are terminal.
  - `currency` 'USD'
  - `virtual_account_name` string, nullable: Platform-supplied label for the account, set at creation and immutable afterwards. When supplied it is used verbatim as the title on the banking partner’s own record of the account. `null` when it was not supplied.
  - `named_account` boolean: Echoed back exactly as supplied at creation. Reserved for a future named-account feature; it drives no behaviour today, so do not branch on it.
  - `account_label` string: Label of the account deposits into this virtual account are credited to, set at creation and immutable afterwards. `general` when none was supplied.
  - `bank_details` BankDetails, nullable: Deposit instructions for the virtual account. Present only when `status` is `ACTIVE`, `CLOSING`, `CLOSED` or `BLOCKED`; `null` while the account is `PENDING`, when the banking partner has not yet issued the account, and always for `FAILED`.
    - `bank_account_number` string
    - `bank_routing_number` string
    - `provider_account_id` string: The banking partner's own identifier for the account.
    - `bank_name` string
  - `status_detail` StatusDetail, nullable: Supplementary context for a terminal failure. Populated when `status` is `FAILED` or `BLOCKED`; `null` otherwise. `code` is drawn from a closed, additive set — treat any value not listed in `enum` as a terminal, unclassified failure.
    - `code` 'VA_CREATION_DECLINED' | 'VA_CREATION_FAILED' | 'VA_BLOCKED'
    - `message` string
    - `at` string, date-time, nullable
  - `settlement_policy` union: Determines what happens to money once it lands in the virtual account. Discriminated union on `type` with two variants: - **`HOLD`** — dollars in, dollars held. The USD you send settles as a USD balance in the virtual account. - **`AUTO_CONVERT_AND_WITHDRAW`** — the incoming USD is converted into the selected `asset` and sent to the `external_account_id` previously linked to the participant. Required at creation; there is no implicit default. May be `null` in responses for accounts created before settlement policies were introduced.
    - object: Dollars in, dollars held — the USD you send settles as a USD balance in the virtual account.
      - `type` 'HOLD', required
    - object: Incoming USD is automatically converted into the selected `asset` and sent to the `external_account_id` previously linked to the participant. Both fields are required.
      - `type` 'AUTO_CONVERT_AND_WITHDRAW', required
      - `asset` string, required: Crypto asset the USD balance is converted into before withdrawal.
      - `external_account_id` string, uuid, required: External crypto account the converted funds are sent to. Must already be linked to the participant.
  - `created_at` string, date-time, nullable
  - `updated_at` string, date-time, nullable

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-11-03** `47cf70ae701c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zerohash/apis/zerohash-api/changes/virtual_accounts/:id/get.md)

---

[API](https://skmtc.dev/zerohash/apis/zerohash-api.md) - [All operations](https://skmtc.dev/zerohash/apis/zerohash-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zerohash/apis/zerohash-api/revisions/47cf70ae701c?raw)