Create Bank Account

Overview

The Create Bank Account API allows you to add a new bank account to a business. Bank accounts are used for various financial operations including deposits, withdrawals, and transfers. Newly created accounts will typically require verification before they can be used for transactions.

Resource Access

• HTTP Method: POST
• Endpoint: /v1/businesses/{business_id}/bank_accounts
• Authentication: Bearer token required

Path Parameters

Parameter	Type	Required	Description
business_id	string (UUID)	Yes	Unique identifier for the business

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication

Request Body

The request body should contain a JSON object with the following structure:

{
  "account_number": "1234567",
  "account_type": "checking",
  "bank_name": "Chase",
  "routing_number": "123456789",
  "user_data": {
    "nickname": "Primary Checking",
    "purpose": "Operations"
  }
}

Request Fields

Field	Type	Required	Description
account_number	string	Yes	Bank account number
account_type	string	Yes	Type of account. Allowed values: checking, savings, business_checking, business_savings
bank_name	string	Yes	Name of the bank or financial institution
routing_number	string	Yes	9-digit ABA routing number
user_data	object	No	Additional user-defined data (optional)

Response

Success Response (201 Created)

{
  "id": "urn:uuid:bank-account-123",
  "business_id": "urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc",
  "account_number": "****4567",
  "account_type": "checking",
  "bank_name": "Chase",
  "routing_number": "123456789",
  "status": "pending_verification",
  "user_data": {
    "nickname": "Primary Checking",
    "purpose": "Operations"
  },
  "created_at": "2022-01-01T00:00:00.000Z",
  "updated_at": "2022-01-01T00:00:00.000Z"
}

Response Fields

Field	Type	Description
id	string (UUID)	Unique identifier for the bank account
business_id	string (UUID)	Business ID this account belongs to
account_number	string	Masked account number for security
account_type	string	Type of bank account
bank_name	string	Name of the bank
routing_number	string	ABA routing number
status	string	Account status
user_data	object	Additional user-defined data
created_at	string (date-time)	Creation timestamp
updated_at	string (date-time)	Last update timestamp

Account Status Values

• pending_verification: Account created but not yet verified
• verified: Account verified and ready for use
• active: Account is active and can be used for transactions
• suspended: Account temporarily suspended
• closed: Account has been closed

Error Responses

• 400 Bad Request: Invalid input data (invalid routing number format, unsupported account type)
• 401 Unauthorized: Invalid or missing authentication token
• 404 Not Found: Business not found
• 409 Conflict: Bank account already exists for this business

Code Examples

cURL

curl -X POST \
  'https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/bank_accounts' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "account_number": "1234567",
    "account_type": "checking",
    "bank_name": "Chase",
    "routing_number": "123456789",
    "user_data": {
      "nickname": "Primary Checking",
      "purpose": "Operations"
    }
  }'

Python

import requests

url = "https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/bank_accounts"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
data = {
    "account_number": "1234567",
    "account_type": "checking",
    "bank_name": "Chase",
    "routing_number": "123456789",
    "user_data": {
        "nickname": "Primary Checking",
        "purpose": "Operations"
    }
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/bank_accounts';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};
const data = {
  account_number: '1234567',
  account_type: 'checking',
  bank_name: 'Chase',
  routing_number: '123456789',
  user_data: {
    nickname: 'Primary Checking',
    purpose: 'Operations'
  }
};

axios.post(url, data, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Usage Notes

• Account numbers are masked in responses for security
• New accounts typically start with pending_verification status
• Verification may be required before accounts can be used for transactions
• Routing numbers must be exactly 9 digits
• Duplicate account numbers for the same business will be rejected
• The user_data field can store additional metadata about the account

Interactive API Explorer