Skip to main content
This guide walks you through ingesting financial accounts - Bank Accounts, Blockchain Wallets, and Payment Accounts - and associating them with clients in Corsa. Full API endpoint details are available in the API Reference (requires API credentials).
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"
    }
  ]
}

​
Step 5: Create Payment Accounts

Endpoint: POST /v1/payment-accounts Payment accounts represent alternative payment identifiers used in emerging market payment rails - such as PIX keys (Brazil), CLABE numbers (Mexico), mobile money accounts, or internal account identifiers. Create a payment account and optionally associate it with clients. 
POST /v1/payment-accounts?upsert=true
Content-Type: application/json

{
  "referenceId": "REF-PA-001",
  "identifier": "+55 11 91234-5678",
  "identifierType": "MOBILE_MONEY",
  "accountHolderName": "Maria Silva",
  "currency": "BRL",
  "countries": ["BRA"],
  "associatedClients": [
    {
      "clientId": "client-uuid-123",
      "name": "Primary Payment Account"
    }
  ]
}

​
Key Fields

FieldRequiredDescription
identifierYesPrimary identifier for the payment account (e.g., PIX key, mobile number, CLABE)
referenceIdNoYour external reference ID (used for upsert matching)
identifierTypeNoType of identifier: MOBILE_MONEY, PIX, CLABE, INTERNAL, CREDIT_CARD, DEBIT_CARD
routingCodeNoRouting or network code for the payment method
currencyNoISO 4217 currency code (e.g., BRL, MXN, USD)
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 payment account if matched by referenceId or identifier.

​
Step 6: Associate Payment Accounts with Clients

Endpoint: POST /v1/payment-accounts/{paymentAccountId}/clients Add client associations to an existing payment account. 
POST /v1/payment-accounts/payment-account-uuid/clients
Content-Type: application/json

{
  "clients": [
    {
      "clientId": "client-uuid-456",
      "name": "Secondary PIX Holder"
    }
  ]
}

​
What’s Next?

Ingest Operations

Ingest deposits, withdrawals, trades, and transfers for your clients.

Ingest Sessions

Track client sessions with device fingerprinting.