# Sign the request first — see Authentication for X-Timestamp, X-Nonce and X-Signature
curl -X POST "https://api.sbx.hopnow.io/v1/customers/cus_x7k2m9p4q1w8e5r3t6y0u2i4/accounts" \
-H "X-API-Key: $API_KEY" \
-H "X-Timestamp: $TIMESTAMP" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIGNATURE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"type": "business",
"business_legal_name": "Acme Pte Ltd",
"business_type": "limited_liability_company",
"business_industry": [
"Marketplace Merchant"
],
"business_registration_number": "200912345A",
"incorporation_date": "2009-04-17",
"registered_address": {
"address_line": "10 Marina Boulevard, #23-01",
"city": "Singapore",
"region": "Central Region",
"postal_code": "018983",
"country": "SG"
},
"operating_address_same_as_registered": true,
"business_operations_start_date": "2009-06-01",
"tax_identification_number": "200912345A",
"tax_residence_country_code": "SG",
"business_description": "Cross-border payouts for marketplace sellers",
"website": "https://acme.example",
"expected_monthly_volume": "from_10k_to_50k",
"source_of_funds": "commercial_activities",
"intended_use_of_account": "supplier_vendor_payments",
"is_regulated": false,
"associated_persons": [
{
"role": "director",
"is_signer": true,
"first_name": "Maya",
"last_name": "Chen",
"email": "maya@acme.example",
"date_of_birth": "1985-06-21",
"country_code": "SG",
"nationality": "SG",
"birth_country_code": "SG",
"tax_identification_number": "S1234567D",
"tax_residence_country_code": "SG",
"position": "Director",
"residential_address": {
"address_line": "8 Marina View, #12-04",
"city": "Singapore",
"postal_code": "018960",
"country": "SG"
}
}
]
}'
{
"type": "business",
"business_legal_name": "Acme Pte Ltd",
"business_type": "limited_liability_company",
"business_industry": [
"Marketplace Merchant"
],
"business_registration_number": "200912345A",
"incorporation_date": "2009-04-17",
"registered_address": {
"address_line": "10 Marina Boulevard, #23-01",
"city": "Singapore",
"region": "Central Region",
"postal_code": "018983",
"country": "SG"
},
"operating_address_same_as_registered": true,
"business_operations_start_date": "2009-06-01",
"tax_identification_number": "200912345A",
"tax_residence_country_code": "SG",
"business_description": "Cross-border payouts for marketplace sellers",
"website": "https://acme.example",
"expected_monthly_volume": "from_10k_to_50k",
"source_of_funds": "commercial_activities",
"intended_use_of_account": "supplier_vendor_payments",
"is_regulated": false,
"associated_persons": [
{
"role": "director",
"is_signer": true,
"first_name": "Maya",
"last_name": "Chen",
"email": "maya@acme.example",
"date_of_birth": "1985-06-21",
"country_code": "SG",
"nationality": "SG",
"birth_country_code": "SG",
"tax_identification_number": "S1234567D",
"tax_residence_country_code": "SG",
"position": "Director",
"residential_address": {
"address_line": "8 Marina View, #12-04",
"city": "Singapore",
"postal_code": "018960",
"country": "SG"
}
}
]
}
{
"type": "individual",
"first_name": "Jane",
"last_name": "Mueller",
"email": "jane@example.com",
"phone_number": "+49301234567",
"date_of_birth": "1988-02-11",
"place_of_birth": "Berlin",
"nationality": "DE",
"birth_country_code": "DE",
"address": {
"address_line": "Friedrichstrasse 43",
"city": "Berlin",
"region": null,
"postal_code": "10117",
"country": "DE"
},
"tax_identification": {
"number": "12345678901",
"tax_residence_country_code": "DE"
},
"employment_status": "salaried",
"source_of_funds": "salary",
"intended_use_of_account": "transfers_own_wallet",
"pep_status": "not_pep",
"expected_monthly_volume": {
"amount": "5000.00",
"currency": "EUR"
}
}
{
"id": "acct_3mnq7c1e6a2b4f3c9b8d2e5a",
"object": "account",
"customer_id": "cus_x7k2m9p4q1w8e5r3t6y0u2i4",
"name": "Acme Pte Ltd",
"status": "active",
"legal_name": "Acme Pte Ltd",
"business_registration_number": "200912345A",
"address": {
"address_line": "10 Marina Boulevard, #23-01",
"city": "Singapore",
"region": "Central Region",
"postal_code": "018983",
"country": "SG"
},
"type": "business",
"profile": {
"type": "business",
"business_legal_name": "Acme Pte Ltd",
"business_type": "limited_liability_company",
"business_industry": [
"Marketplace Merchant"
],
"business_registration_number": "200912345A",
"incorporation_date": "2009-04-17",
"registered_address": {
"address_line": "10 Marina Boulevard, #23-01",
"city": "Singapore",
"region": "Central Region",
"postal_code": "018983",
"country": "SG"
},
"operating_address_same_as_registered": true,
"business_operations_start_date": "2009-06-01",
"tax_identification_number": "200912345A",
"tax_residence_country_code": "SG",
"business_description": "Cross-border payouts for marketplace sellers",
"website": "https://acme.example",
"expected_monthly_volume": "from_10k_to_50k",
"source_of_funds": "commercial_activities",
"intended_use_of_account": "supplier_vendor_payments",
"is_regulated": false
},
"balances": [],
"created": "2026-09-29T08:00:00Z",
"updated": "2026-09-29T08:00:00Z",
"created_by": "ak_0d5c8b2e7f1a3946c8e2b5d7",
"updated_by": "ak_0d5c8b2e7f1a3946c8e2b5d7"
}
{
"id": "acct_9wkq2m5r8t1y4u7i0p3a6s9d",
"object": "account",
"customer_id": "cus_x7k2m9p4q1w8e5r3t6y0u2i4",
"name": "Jane Mueller",
"status": "active",
"legal_name": "Jane Mueller",
"business_registration_number": null,
"address": {
"address_line": "Friedrichstrasse 43",
"city": "Berlin",
"region": null,
"postal_code": "10117",
"country": "DE"
},
"type": "individual",
"profile": {
"type": "individual",
"first_name": "Jane",
"last_name": "Mueller",
"email": "jane@example.com",
"phone_number": "+49301234567",
"date_of_birth": "1988-02-11",
"place_of_birth": "Berlin",
"nationality": "DE",
"birth_country_code": "DE",
"address": {
"address_line": "Friedrichstrasse 43",
"city": "Berlin",
"region": null,
"postal_code": "10117",
"country": "DE"
},
"tax_identification": {
"number": "12345678901",
"tax_residence_country_code": "DE"
},
"employment_status": "salaried",
"source_of_funds": "salary",
"intended_use_of_account": "transfers_own_wallet",
"pep_status": "not_pep",
"expected_monthly_volume": {
"amount": "5000.00",
"currency": "EUR"
}
},
"balances": [],
"created": "2026-09-29T08:00:00Z",
"updated": "2026-09-29T08:00:00Z",
"created_by": "ak_0d5c8b2e7f1a3946c8e2b5d7",
"updated_by": "ak_0d5c8b2e7f1a3946c8e2b5d7"
}
Accounts
Create Account
Create an account for one of your end customers, with its identity and associated persons in one call
POST
/
v1
/
customers
/
{customer_id}
/
accounts
# Sign the request first — see Authentication for X-Timestamp, X-Nonce and X-Signature
curl -X POST "https://api.sbx.hopnow.io/v1/customers/cus_x7k2m9p4q1w8e5r3t6y0u2i4/accounts" \
-H "X-API-Key: $API_KEY" \
-H "X-Timestamp: $TIMESTAMP" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIGNATURE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"type": "business",
"business_legal_name": "Acme Pte Ltd",
"business_type": "limited_liability_company",
"business_industry": [
"Marketplace Merchant"
],
"business_registration_number": "200912345A",
"incorporation_date": "2009-04-17",
"registered_address": {
"address_line": "10 Marina Boulevard, #23-01",
"city": "Singapore",
"region": "Central Region",
"postal_code": "018983",
"country": "SG"
},
"operating_address_same_as_registered": true,
"business_operations_start_date": "2009-06-01",
"tax_identification_number": "200912345A",
"tax_residence_country_code": "SG",
"business_description": "Cross-border payouts for marketplace sellers",
"website": "https://acme.example",
"expected_monthly_volume": "from_10k_to_50k",
"source_of_funds": "commercial_activities",
"intended_use_of_account": "supplier_vendor_payments",
"is_regulated": false,
"associated_persons": [
{
"role": "director",
"is_signer": true,
"first_name": "Maya",
"last_name": "Chen",
"email": "maya@acme.example",
"date_of_birth": "1985-06-21",
"country_code": "SG",
"nationality": "SG",
"birth_country_code": "SG",
"tax_identification_number": "S1234567D",
"tax_residence_country_code": "SG",
"position": "Director",
"residential_address": {
"address_line": "8 Marina View, #12-04",
"city": "Singapore",
"postal_code": "018960",
"country": "SG"
}
}
]
}'
{
"type": "business",
"business_legal_name": "Acme Pte Ltd",
"business_type": "limited_liability_company",
"business_industry": [
"Marketplace Merchant"
],
"business_registration_number": "200912345A",
"incorporation_date": "2009-04-17",
"registered_address": {
"address_line": "10 Marina Boulevard, #23-01",
"city": "Singapore",
"region": "Central Region",
"postal_code": "018983",
"country": "SG"
},
"operating_address_same_as_registered": true,
"business_operations_start_date": "2009-06-01",
"tax_identification_number": "200912345A",
"tax_residence_country_code": "SG",
"business_description": "Cross-border payouts for marketplace sellers",
"website": "https://acme.example",
"expected_monthly_volume": "from_10k_to_50k",
"source_of_funds": "commercial_activities",
"intended_use_of_account": "supplier_vendor_payments",
"is_regulated": false,
"associated_persons": [
{
"role": "director",
"is_signer": true,
"first_name": "Maya",
"last_name": "Chen",
"email": "maya@acme.example",
"date_of_birth": "1985-06-21",
"country_code": "SG",
"nationality": "SG",
"birth_country_code": "SG",
"tax_identification_number": "S1234567D",
"tax_residence_country_code": "SG",
"position": "Director",
"residential_address": {
"address_line": "8 Marina View, #12-04",
"city": "Singapore",
"postal_code": "018960",
"country": "SG"
}
}
]
}
{
"type": "individual",
"first_name": "Jane",
"last_name": "Mueller",
"email": "jane@example.com",
"phone_number": "+49301234567",
"date_of_birth": "1988-02-11",
"place_of_birth": "Berlin",
"nationality": "DE",
"birth_country_code": "DE",
"address": {
"address_line": "Friedrichstrasse 43",
"city": "Berlin",
"region": null,
"postal_code": "10117",
"country": "DE"
},
"tax_identification": {
"number": "12345678901",
"tax_residence_country_code": "DE"
},
"employment_status": "salaried",
"source_of_funds": "salary",
"intended_use_of_account": "transfers_own_wallet",
"pep_status": "not_pep",
"expected_monthly_volume": {
"amount": "5000.00",
"currency": "EUR"
}
}
{
"id": "acct_3mnq7c1e6a2b4f3c9b8d2e5a",
"object": "account",
"customer_id": "cus_x7k2m9p4q1w8e5r3t6y0u2i4",
"name": "Acme Pte Ltd",
"status": "active",
"legal_name": "Acme Pte Ltd",
"business_registration_number": "200912345A",
"address": {
"address_line": "10 Marina Boulevard, #23-01",
"city": "Singapore",
"region": "Central Region",
"postal_code": "018983",
"country": "SG"
},
"type": "business",
"profile": {
"type": "business",
"business_legal_name": "Acme Pte Ltd",
"business_type": "limited_liability_company",
"business_industry": [
"Marketplace Merchant"
],
"business_registration_number": "200912345A",
"incorporation_date": "2009-04-17",
"registered_address": {
"address_line": "10 Marina Boulevard, #23-01",
"city": "Singapore",
"region": "Central Region",
"postal_code": "018983",
"country": "SG"
},
"operating_address_same_as_registered": true,
"business_operations_start_date": "2009-06-01",
"tax_identification_number": "200912345A",
"tax_residence_country_code": "SG",
"business_description": "Cross-border payouts for marketplace sellers",
"website": "https://acme.example",
"expected_monthly_volume": "from_10k_to_50k",
"source_of_funds": "commercial_activities",
"intended_use_of_account": "supplier_vendor_payments",
"is_regulated": false
},
"balances": [],
"created": "2026-09-29T08:00:00Z",
"updated": "2026-09-29T08:00:00Z",
"created_by": "ak_0d5c8b2e7f1a3946c8e2b5d7",
"updated_by": "ak_0d5c8b2e7f1a3946c8e2b5d7"
}
{
"id": "acct_9wkq2m5r8t1y4u7i0p3a6s9d",
"object": "account",
"customer_id": "cus_x7k2m9p4q1w8e5r3t6y0u2i4",
"name": "Jane Mueller",
"status": "active",
"legal_name": "Jane Mueller",
"business_registration_number": null,
"address": {
"address_line": "Friedrichstrasse 43",
"city": "Berlin",
"region": null,
"postal_code": "10117",
"country": "DE"
},
"type": "individual",
"profile": {
"type": "individual",
"first_name": "Jane",
"last_name": "Mueller",
"email": "jane@example.com",
"phone_number": "+49301234567",
"date_of_birth": "1988-02-11",
"place_of_birth": "Berlin",
"nationality": "DE",
"birth_country_code": "DE",
"address": {
"address_line": "Friedrichstrasse 43",
"city": "Berlin",
"region": null,
"postal_code": "10117",
"country": "DE"
},
"tax_identification": {
"number": "12345678901",
"tax_residence_country_code": "DE"
},
"employment_status": "salaried",
"source_of_funds": "salary",
"intended_use_of_account": "transfers_own_wallet",
"pep_status": "not_pep",
"expected_monthly_volume": {
"amount": "5000.00",
"currency": "EUR"
}
},
"balances": [],
"created": "2026-09-29T08:00:00Z",
"updated": "2026-09-29T08:00:00Z",
"created_by": "ak_0d5c8b2e7f1a3946c8e2b5d7",
"updated_by": "ak_0d5c8b2e7f1a3946c8e2b5d7"
}
A platform customer uses one account per end customer. This call creates that account and stores the end customer’s identity profile on it. For a business, you can add its associated persons in the same call.
Only platform customers can create accounts. For any other customer the endpoint returns
404.
Creating an account does not start virtual account onboarding. Open a group afterwards with Create Virtual Account Group.
Requires an API key with write access on the accounts scope.
Path Parameters
Headers
A UUID for this account. Scoped to your customer: a key you have used before returns the account it created with
200, and the request body is not compared, so a replay with different details still returns the original account. Use a new key for each new account. See Idempotency.Request Body
The body is the account’s identity profile, with the same fields as Update Account. Every field that Update Account marks as required on the first call is required here. Send these fields directly in the request body; unknown keys return422 VALIDATION_ERROR.
Entity type:
business or individual. It selects the field group, and cannot be changed later.Business accounts only. The people behind the entity, such as owners, directors and signers, each with the same body as Create Associated Person. Include at least one person with
is_signer: true so the business can sign its agreements. You can also add people later.They are stored as separate resources. Read them with List Associated Persons.Response
Returns201 with the new account, in the same shape as Get Account. The stored profile is in profile, and status is active. A replayed Idempotency-Key returns 200 with the account it created.
A new account also sends an account.created webhook to any endpoint subscribed to it.
Errors
| Status | code | When |
|---|---|---|
422 | VALIDATION_ERROR | A required identity field is missing, a field is malformed (including a US address whose region is missing or is not a two-letter state code (e.g. California instead of CA)), or a key is unknown. validation_errors names each field, including fields of an entry in associated_persons |
422 | VALIDATION_ERROR | Idempotency-Key is missing or is not a UUID |
422 | INVALID_FIELD_FORMAT | business_registration_number is not an EIN although registered_address.country or jurisdiction_of_incorporation is US |
422 | BUSINESS_RULE_VIOLATION | An entry in associated_persons uses the reserved account_holder role |
422 | DUPLICATE_RESOURCE | Two entries in associated_persons use the same email, or share the same first_name, last_name and date_of_birth |
422 | VALIDATION_ERROR | The ownership_percentage of the entries in associated_persons adds up to more than 100 |
404 | RESOURCE_NOT_FOUND | customer_id is not your customer, or your customer is not a platform customer |
# Sign the request first — see Authentication for X-Timestamp, X-Nonce and X-Signature
curl -X POST "https://api.sbx.hopnow.io/v1/customers/cus_x7k2m9p4q1w8e5r3t6y0u2i4/accounts" \
-H "X-API-Key: $API_KEY" \
-H "X-Timestamp: $TIMESTAMP" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIGNATURE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"type": "business",
"business_legal_name": "Acme Pte Ltd",
"business_type": "limited_liability_company",
"business_industry": [
"Marketplace Merchant"
],
"business_registration_number": "200912345A",
"incorporation_date": "2009-04-17",
"registered_address": {
"address_line": "10 Marina Boulevard, #23-01",
"city": "Singapore",
"region": "Central Region",
"postal_code": "018983",
"country": "SG"
},
"operating_address_same_as_registered": true,
"business_operations_start_date": "2009-06-01",
"tax_identification_number": "200912345A",
"tax_residence_country_code": "SG",
"business_description": "Cross-border payouts for marketplace sellers",
"website": "https://acme.example",
"expected_monthly_volume": "from_10k_to_50k",
"source_of_funds": "commercial_activities",
"intended_use_of_account": "supplier_vendor_payments",
"is_regulated": false,
"associated_persons": [
{
"role": "director",
"is_signer": true,
"first_name": "Maya",
"last_name": "Chen",
"email": "maya@acme.example",
"date_of_birth": "1985-06-21",
"country_code": "SG",
"nationality": "SG",
"birth_country_code": "SG",
"tax_identification_number": "S1234567D",
"tax_residence_country_code": "SG",
"position": "Director",
"residential_address": {
"address_line": "8 Marina View, #12-04",
"city": "Singapore",
"postal_code": "018960",
"country": "SG"
}
}
]
}'
{
"type": "business",
"business_legal_name": "Acme Pte Ltd",
"business_type": "limited_liability_company",
"business_industry": [
"Marketplace Merchant"
],
"business_registration_number": "200912345A",
"incorporation_date": "2009-04-17",
"registered_address": {
"address_line": "10 Marina Boulevard, #23-01",
"city": "Singapore",
"region": "Central Region",
"postal_code": "018983",
"country": "SG"
},
"operating_address_same_as_registered": true,
"business_operations_start_date": "2009-06-01",
"tax_identification_number": "200912345A",
"tax_residence_country_code": "SG",
"business_description": "Cross-border payouts for marketplace sellers",
"website": "https://acme.example",
"expected_monthly_volume": "from_10k_to_50k",
"source_of_funds": "commercial_activities",
"intended_use_of_account": "supplier_vendor_payments",
"is_regulated": false,
"associated_persons": [
{
"role": "director",
"is_signer": true,
"first_name": "Maya",
"last_name": "Chen",
"email": "maya@acme.example",
"date_of_birth": "1985-06-21",
"country_code": "SG",
"nationality": "SG",
"birth_country_code": "SG",
"tax_identification_number": "S1234567D",
"tax_residence_country_code": "SG",
"position": "Director",
"residential_address": {
"address_line": "8 Marina View, #12-04",
"city": "Singapore",
"postal_code": "018960",
"country": "SG"
}
}
]
}
{
"type": "individual",
"first_name": "Jane",
"last_name": "Mueller",
"email": "jane@example.com",
"phone_number": "+49301234567",
"date_of_birth": "1988-02-11",
"place_of_birth": "Berlin",
"nationality": "DE",
"birth_country_code": "DE",
"address": {
"address_line": "Friedrichstrasse 43",
"city": "Berlin",
"region": null,
"postal_code": "10117",
"country": "DE"
},
"tax_identification": {
"number": "12345678901",
"tax_residence_country_code": "DE"
},
"employment_status": "salaried",
"source_of_funds": "salary",
"intended_use_of_account": "transfers_own_wallet",
"pep_status": "not_pep",
"expected_monthly_volume": {
"amount": "5000.00",
"currency": "EUR"
}
}
{
"id": "acct_3mnq7c1e6a2b4f3c9b8d2e5a",
"object": "account",
"customer_id": "cus_x7k2m9p4q1w8e5r3t6y0u2i4",
"name": "Acme Pte Ltd",
"status": "active",
"legal_name": "Acme Pte Ltd",
"business_registration_number": "200912345A",
"address": {
"address_line": "10 Marina Boulevard, #23-01",
"city": "Singapore",
"region": "Central Region",
"postal_code": "018983",
"country": "SG"
},
"type": "business",
"profile": {
"type": "business",
"business_legal_name": "Acme Pte Ltd",
"business_type": "limited_liability_company",
"business_industry": [
"Marketplace Merchant"
],
"business_registration_number": "200912345A",
"incorporation_date": "2009-04-17",
"registered_address": {
"address_line": "10 Marina Boulevard, #23-01",
"city": "Singapore",
"region": "Central Region",
"postal_code": "018983",
"country": "SG"
},
"operating_address_same_as_registered": true,
"business_operations_start_date": "2009-06-01",
"tax_identification_number": "200912345A",
"tax_residence_country_code": "SG",
"business_description": "Cross-border payouts for marketplace sellers",
"website": "https://acme.example",
"expected_monthly_volume": "from_10k_to_50k",
"source_of_funds": "commercial_activities",
"intended_use_of_account": "supplier_vendor_payments",
"is_regulated": false
},
"balances": [],
"created": "2026-09-29T08:00:00Z",
"updated": "2026-09-29T08:00:00Z",
"created_by": "ak_0d5c8b2e7f1a3946c8e2b5d7",
"updated_by": "ak_0d5c8b2e7f1a3946c8e2b5d7"
}
{
"id": "acct_9wkq2m5r8t1y4u7i0p3a6s9d",
"object": "account",
"customer_id": "cus_x7k2m9p4q1w8e5r3t6y0u2i4",
"name": "Jane Mueller",
"status": "active",
"legal_name": "Jane Mueller",
"business_registration_number": null,
"address": {
"address_line": "Friedrichstrasse 43",
"city": "Berlin",
"region": null,
"postal_code": "10117",
"country": "DE"
},
"type": "individual",
"profile": {
"type": "individual",
"first_name": "Jane",
"last_name": "Mueller",
"email": "jane@example.com",
"phone_number": "+49301234567",
"date_of_birth": "1988-02-11",
"place_of_birth": "Berlin",
"nationality": "DE",
"birth_country_code": "DE",
"address": {
"address_line": "Friedrichstrasse 43",
"city": "Berlin",
"region": null,
"postal_code": "10117",
"country": "DE"
},
"tax_identification": {
"number": "12345678901",
"tax_residence_country_code": "DE"
},
"employment_status": "salaried",
"source_of_funds": "salary",
"intended_use_of_account": "transfers_own_wallet",
"pep_status": "not_pep",
"expected_monthly_volume": {
"amount": "5000.00",
"currency": "EUR"
}
},
"balances": [],
"created": "2026-09-29T08:00:00Z",
"updated": "2026-09-29T08:00:00Z",
"created_by": "ak_0d5c8b2e7f1a3946c8e2b5d7",
"updated_by": "ak_0d5c8b2e7f1a3946c8e2b5d7"
}