Skip to main content
The customer must already be onboarded and active before you add a feature. You get customerId from the application.approved webhook — see Onboard a Customer and The Onboarding Lifecycle. Calling features before the customer is active returns CUSTOMER_NOT_ONBOARDED.

​
Flow

Add Virtual Accounts by submitting a feature application against an existing customer. The integration:
  1. Discover the customer’s feature requirements.
  2. Submit a VIRTUAL_ACCOUNT feature application.
  3. Listen for virtual_account_application.approved or virtual_account_application.rejected.
  4. Listen for virtual_account.activated.
  5. Fetch the customer’s Virtual Accounts and read balances[] plus depositInstructions[].

​
Request The Feature

Discover any extra requirements for the customer: 
curl 'https://api.conduit.financial/v2/customers/{customerId}/features/requirements?type=VIRTUAL_ACCOUNT' \
  -H "x-api-key: YOUR_API_KEY"
Like the onboarding flow, the discovery response lists any required fields and documents. When present, collect them and include them in the submit body below. When the response asks for nothing extra, submit with just type and asset. Submit the Virtual Account feature application for the target asset. Idempotency-Key is required — without it the call returns IDEMPOTENCY_KEY_REQUIRED. 
curl https://api.conduit.financial/v2/customers/{customerId}/features \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "VIRTUAL_ACCOUNT",
    "asset": "USD"
  }'
The endpoint returns 202 Accepted with a Virtual Account feature application carrying its own application id. Track it through the virtual_account_application.approved and virtual_account_application.rejected webhooks.

​
Listen For Activation

Once the feature application is approved, listen for virtual_account.activated to know the Virtual Account is usable. Deposit instructions populate once the Virtual Account’s status is active. See Webhooks and Virtual Accounts.

​
Retrieve Deposit Instructions

After activation, fetch the Virtual Accounts for the customer: 
curl https://api.conduit.financial/v2/customers/{customerId}/virtual-accounts \
  -H "x-api-key: YOUR_API_KEY"
The response contains VA-level balances and deposit instructions. It does not include provider bank accounts. 
{
  "data": [
    {
      "id": "vac_...",
      "asset": { "code": "USD" },
      "status": "active",
      "balances": [
        {
          "available": { "code": "USD", "amount": "0.00" },
          "pending": { "code": "USD", "amount": "0.00" },
          "frozen": { "code": "USD", "amount": "0.00" }
        }
      ],
      "depositInstructions": [
        {
          "type": "domestic_usd",
          "accountNumber": "123456789",
          "beneficiaryName": "Example Customer",
          "beneficiaryAddress": "1 Main St, New York, NY",
          "bank": {
            "legalName": "Example Bank",
            "address": "2 Bank St, New York, NY"
          },
          "rails": [
            { "rail": "ach", "routingNumber": "021000021", "sameDayEligible": false },
            { "rail": "fedwire", "routingNumber": "021000021" },
            { "rail": "rtp", "routingNumber": "021000021", "networks": ["TCH"] }
          ]
        }
      ],
      "activatedAt": "2026-04-30T00:00:00.000Z",
      "createdAt": "2026-04-30T00:00:00.000Z",
      "updatedAt": "2026-04-30T00:00:00.000Z"
    }
  ],
  "meta": {
    "mode": "cursor",
    "nextCursor": null,
    "previousCursor": null,
    "total": 1
  }
}
Retrieve one Virtual Account when you have its id: 
curl https://api.conduit.financial/v2/customers/{customerId}/virtual-accounts/{virtualAccountId} \
  -H "x-api-key: YOUR_API_KEY"