Create a Bank Account

REST request body

{
  "subOrgId": "sub_org_123",
  "accountNumber": "111222333",
  "accountName": "Acme Corp",
  "routingNumber": "021000021",
  "clientBankAccountId": "erp-bank-001",
  "paymentMethod": "US_ACH",
  "bankName": "Chase",
  "streetLine": "270 Park Avenue",
  "city": "New York",
  "state": "NY",
  "postalCode": "10017",
  "country": "US"
}

# Sample only. Generate a new signed token for each request
# (see Authentication). Tokens expire after 120 seconds.
curl --request POST \
  --url "https://api.primevault.com/api/external/bank_accounts/" \
  --header "Authorization: Bearer <signed JWT>" \
  --header "Api-Key: <API key>" \
  --header "Content-Type: application/json" \
  --data '{
    "subOrgId": "sub_org_123",
    "accountNumber": "111222333",
    "accountName": "Acme Corp",
    "routingNumber": "021000021",
    "clientBankAccountId": "erp-bank-001",
    "paymentMethod": "US_ACH",
    "bankName": "Chase",
    "streetLine": "270 Park Avenue",
    "city": "New York",
    "state": "NY",
    "postalCode": "10017",
    "country": "US"
  }'

interface CreateBankAccountRequest {
  subOrgId?: string;
  accountNumber?: string;
  accountName?: string;
  routingNumber?: string;
  clientBankAccountId?: string;
  paymentMethod?: string;
  bankName?: string;
  streetLine?: string;
  city?: string;
  state?: string;
  postalCode?: string;
  country?: string;
}

createBankAccount(request: CreateBankAccountRequest): Promise<BankAccount>

{
  "id": "bank_account_123",
  "orgId": "org_456",
  "subOrgId": "sub_org_123",
  "orgEntityId": "org_entity_123",
  "createdById": "api_user_123",
  "createdAt": "2026-08-04T10:30:00Z",
  "updatedAt": "2026-08-04T10:30:00Z",
  "isDeleted": false,
  "status": "PENDING",
  "accountNumber": "111222333",
  "accountName": "Acme Corp",
  "routingNumber": "021000021",
  "clientBankAccountId": "erp-bank-001",
  "paymentMethod": "US_ACH",
  "bankName": "Chase",
  "streetLine": "270 Park Avenue",
  "city": "New York",
  "state": "NY",
  "postalCode": "10017",
  "country": "US"
}

POST /api/external/bank_accounts/ Creates a new fiat settlement or beneficiary bank account under the API user’s organization. The fields required in practice depend on the country, payment method, and provider. The SDK marks every property optional, so you must send the complete set required for the selected rail.

The fields required in practice depend on the country, payment method, and provider. Send the complete set required for the selected rail even though the SDK marks every property optional.

Request body

string

Sub-org that owns the account. Set only at creation.

string

Bank account number.

string

Account-holder name.

string

Domestic routing identifier where applicable.

string

Client-controlled bank-account reference.

string

Payment rail, for example US_ACH, US_WIRE, SEPA, SWIFT, or BANK_TRANSFER.

string

Bank name.

string

Street address line for the bank or beneficiary.

string

City for the bank or beneficiary address.

string

State or province for the bank or beneficiary address.

string

Postal code for the bank or beneficiary address.

string

Country code for the bank or beneficiary address.

Response

{
  "id": "bank_account_123",
  "orgId": "org_456",
  "subOrgId": "sub_org_123",
  "orgEntityId": "org_entity_123",
  "createdById": "api_user_123",
  "createdAt": "2026-08-04T10:30:00Z",
  "updatedAt": "2026-08-04T10:30:00Z",
  "isDeleted": false,
  "status": "PENDING",
  "accountNumber": "111222333",
  "accountName": "Acme Corp",
  "routingNumber": "021000021",
  "clientBankAccountId": "erp-bank-001",
  "paymentMethod": "US_ACH",
  "bankName": "Chase",
  "streetLine": "270 Park Avenue",
  "city": "New York",
  "state": "NY",
  "postalCode": "10017",
  "country": "US"
}

JavaScript SDK

interface CreateBankAccountRequest {
  subOrgId?: string;
  accountNumber?: string;
  accountName?: string;
  routingNumber?: string;
  clientBankAccountId?: string;
  paymentMethod?: string;
  bankName?: string;
  streetLine?: string;
  city?: string;
  state?: string;
  postalCode?: string;
  country?: string;
}

createBankAccount(request: CreateBankAccountRequest): Promise<BankAccount>

Approve the bank account

A new bank account comes back with status: "PENDING" and needs your API user’s approval. Call Get Approval Message with entityId set to the bank account id, sign the message, and send the signature to Submit Approval Action. See Approvals for the full flow. With the SDK, approve separately or in one call:

const bankAccount = await apiClient.createBankAccount(request);
const approved = await apiClient.createBankAccountApproval(bankAccount);

// Convenience helper: create, then approve.
const approvedBankAccount =
  await apiClient.createBankAccountWithApproval(request);

Use the returned id with Retrieve Bank Account to check the current status.

REST request body

{
  "subOrgId": "sub_org_123",
  "accountNumber": "111222333",
  "accountName": "Acme Corp",
  "routingNumber": "021000021",
  "clientBankAccountId": "erp-bank-001",
  "paymentMethod": "US_ACH",
  "bankName": "Chase",
  "streetLine": "270 Park Avenue",
  "city": "New York",
  "state": "NY",
  "postalCode": "10017",
  "country": "US"
}

# Sample only. Generate a new signed token for each request
# (see Authentication). Tokens expire after 120 seconds.
curl --request POST \
  --url "https://api.primevault.com/api/external/bank_accounts/" \
  --header "Authorization: Bearer <signed JWT>" \
  --header "Api-Key: <API key>" \
  --header "Content-Type: application/json" \
  --data '{
    "subOrgId": "sub_org_123",
    "accountNumber": "111222333",
    "accountName": "Acme Corp",
    "routingNumber": "021000021",
    "clientBankAccountId": "erp-bank-001",
    "paymentMethod": "US_ACH",
    "bankName": "Chase",
    "streetLine": "270 Park Avenue",
    "city": "New York",
    "state": "NY",
    "postalCode": "10017",
    "country": "US"
  }'

interface CreateBankAccountRequest {
  subOrgId?: string;
  accountNumber?: string;
  accountName?: string;
  routingNumber?: string;
  clientBankAccountId?: string;
  paymentMethod?: string;
  bankName?: string;
  streetLine?: string;
  city?: string;
  state?: string;
  postalCode?: string;
  country?: string;
}

createBankAccount(request: CreateBankAccountRequest): Promise<BankAccount>

{
  "id": "bank_account_123",
  "orgId": "org_456",
  "subOrgId": "sub_org_123",
  "orgEntityId": "org_entity_123",
  "createdById": "api_user_123",
  "createdAt": "2026-08-04T10:30:00Z",
  "updatedAt": "2026-08-04T10:30:00Z",
  "isDeleted": false,
  "status": "PENDING",
  "accountNumber": "111222333",
  "accountName": "Acme Corp",
  "routingNumber": "021000021",
  "clientBankAccountId": "erp-bank-001",
  "paymentMethod": "US_ACH",
  "bankName": "Chase",
  "streetLine": "270 Park Avenue",
  "city": "New York",
  "state": "NY",
  "postalCode": "10017",
  "country": "US"
}

⌘I

REST request body

{
  "subOrgId": "sub_org_123",
  "accountNumber": "111222333",
  "accountName": "Acme Corp",
  "routingNumber": "021000021",
  "clientBankAccountId": "erp-bank-001",
  "paymentMethod": "US_ACH",
  "bankName": "Chase",
  "streetLine": "270 Park Avenue",
  "city": "New York",
  "state": "NY",
  "postalCode": "10017",
  "country": "US"
}

# Sample only. Generate a new signed token for each request
# (see Authentication). Tokens expire after 120 seconds.
curl --request POST \
  --url "https://api.primevault.com/api/external/bank_accounts/" \
  --header "Authorization: Bearer <signed JWT>" \
  --header "Api-Key: <API key>" \
  --header "Content-Type: application/json" \
  --data '{
    "subOrgId": "sub_org_123",
    "accountNumber": "111222333",
    "accountName": "Acme Corp",
    "routingNumber": "021000021",
    "clientBankAccountId": "erp-bank-001",
    "paymentMethod": "US_ACH",
    "bankName": "Chase",
    "streetLine": "270 Park Avenue",
    "city": "New York",
    "state": "NY",
    "postalCode": "10017",
    "country": "US"
  }'

interface CreateBankAccountRequest {
  subOrgId?: string;
  accountNumber?: string;
  accountName?: string;
  routingNumber?: string;
  clientBankAccountId?: string;
  paymentMethod?: string;
  bankName?: string;
  streetLine?: string;
  city?: string;
  state?: string;
  postalCode?: string;
  country?: string;
}

createBankAccount(request: CreateBankAccountRequest): Promise<BankAccount>

{
  "id": "bank_account_123",
  "orgId": "org_456",
  "subOrgId": "sub_org_123",
  "orgEntityId": "org_entity_123",
  "createdById": "api_user_123",
  "createdAt": "2026-08-04T10:30:00Z",
  "updatedAt": "2026-08-04T10:30:00Z",
  "isDeleted": false,
  "status": "PENDING",
  "accountNumber": "111222333",
  "accountName": "Acme Corp",
  "routingNumber": "021000021",
  "clientBankAccountId": "erp-bank-001",
  "paymentMethod": "US_ACH",
  "bankName": "Chase",
  "streetLine": "270 Park Avenue",
  "city": "New York",
  "state": "NY",
  "postalCode": "10017",
  "country": "US"
}

API Basics

Approvals

Accounts

Sub-Orgs

Transactions

Request body

Response

JavaScript SDK

Approve the bank account

​Request body

​Response

​JavaScript SDK

​Approve the bank account

Request body

Response

JavaScript SDK

Approve the bank account