Skip to main content

​
Overview

Link a US bank account to enable ACH/RTP/wire withdrawals. This endpoint lets you connect a customer’s bank account as a payout destination.

​
Prerequisites

  • An application token (obtained from creating a payout link or account widget)
  • Valid access token

​
Endpoint

  • POST {{LIQUIDITY_URL}}/v1/ext/application-token/:token/linked-accounts/:currency/link/bank/:step
  • Auth: Bearer {{accessToken}}

​
Path Parameters

ParameterTypeDescriptionRequired
tokenstringApplication token from payout/account widgetYes
currencystringCurrency code (e.g., USD)Yes
stepstringUsually 1 (initial) or form (micro-deposit verification)Yes

​
Request

curl -X POST "{{LIQUIDITY_URL}}/v1/ext/application-token/{{token}}/linked-accounts/USD/link/bank/1" \
  -H "Authorization: Bearer {{accessToken}}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Quantum Works LLC - RelayBank - ACH",
    "data": {
      "firstName": "John",
      "lastName": "Doe",
      "name": "Quantum Works LLC",
      "accountNumber": "9879264803",
      "routingNumber": "121042882",
      "type": "CHECKING",
      "bankName": "ABC bank",
      "recipientAddress": "9401 San francisco",
      "recipientCity": "San francisco",
      "recipientState": "CA",
      "recipientPostalCode": "12345",
      "routingType": "ACH",
      "email": "timi@gradientfi.com",
      "recipientType": "personal"
    }
  }'

​
Request Body Fields

FieldTypeDescriptionRequired
labelstringDisplay name for the linked accountYes
data.firstNamestringFirst name of account ownerYes
data.lastNamestringLast name of account ownerYes
data.namestringBusiness/account nameYes
data.accountNumberstringBank account numberYes
data.routingNumberstringBank routing number (9 digits)Yes
data.typestringAccount type: CHECKING or SAVINGSYes
data.bankNamestringName of the bankYes
data.recipientAddressstringStreet address of account holderYes
data.recipientCitystringCity of account holderYes
data.recipientStatestringState code (e.g., CA)Yes
data.recipientPostalCodestringZIP/postal codeYes
data.routingTypestringRouting type: ACH, RTP, or WIREYes
data.emailstringEmail address of account holderYes
data.recipientTypestringRecipient type: personal or businessYes

​
Response (200)

{
  "data": {
    "type": "completed",
    "message": "Account successfully linked!",
    "data": {
      "id": "119d213c-65a9-4485-b2bc-14c6dc5a3fb1",
      "currency": "USD",
      "optionType": "bank",
      "account": {
        "label": "Josh Fairpuny - Bank #3340",
        "lastFourDigits": "0000"
      },
      "wallet": {
        "id": "3eb8d02c-30e0-497c-a6ac-e2d203c63198",
        "balance": "99811.95",
        "disabled": false
      },
      "entity": {
        "id": "d5e6f1dd-57bc-4581-98e8-646264a5f2c9",
        "entityType": "BUSINESS"
      }
    }
  }
}

​
Response Fields

FieldTypeDescription
data.data.idstringLinked account ID (use for withdrawals)
data.data.currencystringCurrency of the linked account
data.data.optionTypestringAccount type: bank
data.data.account.labelstringDisplay label for the account
data.data.account.lastFourDigitsstringLast 4 digits of account number
data.data.wallet.idstringAssociated wallet ID
data.data.wallet.balancestringCurrent wallet balance
data.data.entity.idstringEntity ID associated with the account
data.data.entity.entityTypestringEntity type: USER or BUSINESS

​
Notes

  • Store the id from the response for use in withdrawal requests
  • routingType supports ACH, RTP, or WIRE for US accounts
  • Some flows may return a form step for micro-deposit verification (step form)
  • Ensure address/name fields match bank records to avoid verification failures