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

# Create Account

> Create an account for one of your end customers, with its identity and associated persons in one call

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](/fx/api-reference/virtual-account-groups/create-group).

Requires an API key with `write` access on the `accounts` scope.

## Path Parameters

<ParamField path="customer_id" type="string" required>
  Your customer's external ID (starts with `cus_`)
</ParamField>

## Headers

<ParamField header="Idempotency-Key" type="string" required>
  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](/fx/api-reference/idempotency).
</ParamField>

## Request Body

The body is the account's identity profile, with the same fields as [Update Account](/fx/api-reference/accounts/update-account-identity). Every field that Update Account marks as required on the first call is required here.

<ParamField body="type" type="string" required>
  Entity type: `business` or `individual`. It selects the field group, and cannot be changed later.
</ParamField>

<ParamField body="...identity fields" type="object" required>
  The business or individual fields for the chosen `type`, as documented on [Update Account](/fx/api-reference/accounts/update-account-identity). Unknown keys are rejected with `422 VALIDATION_ERROR`.
</ParamField>

<ParamField body="associated_persons" type="object[]">
  Business accounts only. The people behind the entity, such as owners, directors and signers, each with the same body as [Create Associated Person](/fx/api-reference/associated-persons/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](/fx/api-reference/associated-persons/list-associated-persons).
</ParamField>

## Response

Returns `201` with the new account, in the same shape as [Get Account](/fx/api-reference/accounts/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, 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 |
| `404` | `RESOURCE_NOT_FOUND` | `customer_id` is not your customer, or your customer is not a platform customer |

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

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

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

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

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

## Next steps

Open a group for the account with [Create Virtual Account Group](/fx/api-reference/virtual-account-groups/create-group), then clear its requirements as described in [Virtual Account Onboarding](/fx/flows/va-onboarding). To correct the identity later, use [Update Account](/fx/api-reference/accounts/update-account-identity).