> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primevault.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Bank Account

> Save a bank account. Required fields depend on the country, payment method, and provider. The account needs your API user's approval.

**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.

<Note>
  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.
</Note>

## Request body

<ParamField body="subOrgId" type="string">
  Sub-org that owns the account. Set only at creation.
</ParamField>

<ParamField body="accountNumber" type="string">
  Bank account number.
</ParamField>

<ParamField body="accountName" type="string">
  Account-holder name.
</ParamField>

<ParamField body="routingNumber" type="string">
  Domestic routing identifier where applicable.
</ParamField>

<ParamField body="clientBankAccountId" type="string">
  Client-controlled bank-account reference.
</ParamField>

<ParamField body="paymentMethod" type="string">
  Payment rail, for example US\_ACH, US\_WIRE, SEPA, SWIFT, or BANK\_TRANSFER.
</ParamField>

<ParamField body="bankName" type="string">
  Bank name.
</ParamField>

<ParamField body="streetLine" type="string">
  Street address line for the bank or beneficiary.
</ParamField>

<ParamField body="city" type="string">
  City for the bank or beneficiary address.
</ParamField>

<ParamField body="state" type="string">
  State or province for the bank or beneficiary address.
</ParamField>

<ParamField body="postalCode" type="string">
  Postal code for the bank or beneficiary address.
</ParamField>

<ParamField body="country" type="string">
  Country code for the bank or beneficiary address.
</ParamField>

## Response

```json theme={null}
{
  "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

```typescript theme={null}
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](/approvals/get-approval-message) with `entityId` set to the bank account `id`, sign the `message`, and send the signature to [Submit Approval Action](/approvals/submit-approval-action). See [Approvals](/approvals/overview) for the full flow.

With the SDK, approve separately or in one call:

```typescript theme={null}
const bankAccount = await apiClient.createBankAccount(request);
const approved = await apiClient.createBankAccountApproval(bankAccount);

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

<Note>
  Use the returned `id` with [Retrieve Bank Account](/accounts-and-wallets/address-book/retrieve-bank-account) to check the current `status`.
</Note>

<RequestExample dropdown>
  ```json REST request body theme={null}
  {
    "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"
  }
  ```

  ```bash cURL theme={null}
  # 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"
    }'
  ```

  ```typescript JavaScript SDK theme={null}
  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>
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.