Skip to main content
This guide walks you through ingesting financial accounts - Bank Accounts and Blockchain Wallets - and associating them with clients in Corsa. Full API reference is available in the API Reference.
Before ingesting accounts and wallets, make sure the related clients have already been ingested. See the Ingesting Clients guide.

​
Step 1: Create Bank Accounts

Endpoint: POST /v1/bank-accounts Create a bank account record and optionally associate it with clients in a single request. 
POST /v1/bank-accounts?upsert=true
Content-Type: application/json

{
  "referenceId": "REF-BA-001",
  "accountNumber": "1234567890",
  "routingNumber": "021000021",
  "bankName": "Chase Bank",
  "accountHolderName": "John Doe",
  "accountType": "checking",
  "currency": "USD",
  "status": "ACTIVE",
  "balanceInCurrency": 15000.50,
  "countries": ["USA"],
  "associatedClients": [
    {
      "clientId": "client-uuid-123",
      "name": "Primary Account"
    }
  ]
}

​
Key Fields

FieldRequiredDescription
accountNumberYesUnique national bank account number
referenceIdNoYour external reference ID (used for upsert matching)
statusNoACTIVE, INACTIVE, or CLOSED
currencyNoISO 4217 currency code (e.g., USD, EUR)
countriesNoISO 3166-1 alpha-3 country codes (max 20)
associatedClientsNoClients to link at creation time (max 50)
riskHistoryNoHistorical risk assessments
customFieldsNoCustom key-value data
The upsert=true query parameter will update an existing bank account if matched by referenceId or accountNumber.

​
Step 2: Associate Bank Accounts with Clients

Endpoint: POST /v1/bank-accounts/{bankAccountId}/clients If you didn’t associate clients at creation time, or need to add more, use this endpoint. 
POST /v1/bank-accounts/bank-account-uuid/clients
Content-Type: application/json

{
  "clients": [
    {
      "clientId": "client-uuid-456",
      "name": "Joint Account Holder"
    }
  ]
}

​
Step 3: Create Blockchain Wallets

Endpoint: POST /v1/blockchain-wallets Create a blockchain wallet record and optionally associate it with clients. 
POST /v1/blockchain-wallets?upsert=true
Content-Type: application/json

{
  "referenceId": "REF-WALLET-001",
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "chain": "ethereum",
  "screeningDate": "2024-01-15T10:30:00.000Z",
  "associatedClients": [
    {
      "clientId": "client-uuid-123",
      "name": "Primary Wallet"
    }
  ]
}

​
Key Fields

FieldRequiredDescription
addressYesWallet address on the blockchain (26-100 chars)
referenceIdNoYour external reference ID (used for upsert matching)
chainNoBlockchain network identifier (e.g., ethereum, bitcoin)
screeningDateNoDate the wallet was last screened
associatedClientsNoClients to link at creation time (max 50)
riskHistoryNoHistorical risk assessments
integrationsNoThird-party integration data (e.g., Chainalysis)
customFieldsNoCustom key-value data
The upsert=true query parameter will update an existing wallet if matched by referenceId or address.

​
Step 4: Associate Blockchain Wallets with Clients

Endpoint: POST /v1/blockchain-wallets/{blockchainWalletId}/clients Add client associations to an existing blockchain wallet. 
POST /v1/blockchain-wallets/wallet-uuid/clients
Content-Type: application/json

{
  "associatedClients": [
    {
      "clientId": "client-uuid-789",
      "name": "Trading Wallet"
    }
  ]
}

​
What’s Next?

Ingest Operations

Ingest deposits, withdrawals, and trades for your clients.

Ingest Sessions

Track client sessions with device fingerprinting.