---
title: "Create a customer"
method: POST
path: "/v1/customers"
tags: ["Customers"]
---

# Create a customer

`POST /v1/customers`

## Request

- Base URL: `https://hyperscale0.ai`
- URL: `https://hyperscale0.ai/v1/customers`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Creates a customer for your company with its underlying legal entity, capturing the entity kind, display name, and country of registration, and opens pending access to one Product. The customer starts active; the entity starts pending (unverified), and so does the Product access. Accounts and money movement stay refused until the entity clears person KYC or organization KYB and the access is activated, in both environments. In sandbox, `test: true` creates a test customer with a synthetic legal profile and active access in one call; live refuses it.

## Headers

- `X-Hyperscale-Environment` 'sandbox' | 'live'
- `Idempotency-Key` string, required

## Request body

- object
  - `productId` string, required: Hyperscale product ID
  - `entity` union, required
    - object
      - `kind` 'person', required
      - `displayName` string, required
      - `country` string, required: ISO 3166-1 alpha-2 country code
      - `profile` object
        - `kind` 'person', required
        - `nationality` string, required: ISO 3166-1 alpha-2 country code
        - `dateOfBirth` string, date, required
        - `idDocument` object, required
          - `type` 'national_id' | 'resident_id' | 'passport', required
          - `number` string, required
          - `issuingCountry` string, required: ISO 3166-1 alpha-2 country code
          - `expiresOn` string, date, required
        - `phone` string, required
        - `address` object, required
          - `line1` string, required
          - `city` string, required
          - `postalCode` string, required
          - `country` string, required: ISO 3166-1 alpha-2 country code
        - `occupation` string, required
        - `sourceOfFunds` 'salary' | 'business_income' | 'investments' | 'savings' | 'inheritance' | 'other', required
        - `politicallyExposed` boolean, required
    - object
      - `kind` 'organization', required
      - `displayName` string, required
      - `country` string, required: ISO 3166-1 alpha-2 country code
      - `profile` object
        - `kind` 'organization', required
        - `legalForm` 'llc' | 'sole_establishment' | 'joint_stock' | 'simplified_joint_stock' | 'partnership' | 'foreign_branch' | 'nonprofit' | 'other', required
        - `registrationNumber` string, required
        - `incorporatedOn` string, date, required
        - `taxNumber` string
        - `activity` string, required
        - `phone` string, required
        - `address` object, required
          - `line1` string, required
          - `city` string, required
          - `postalCode` string, required
          - `country` string, required: ISO 3166-1 alpha-2 country code
        - `signatory` object, required
          - `fullName` string, required
          - `role` string, required
          - `idDocument` object, required
            - `type` 'national_id' | 'resident_id' | 'passport', required
            - `number` string, required
            - `issuingCountry` string, required: ISO 3166-1 alpha-2 country code
            - `expiresOn` string, date, required
        - `beneficialOwners` object[], required
          - `fullName` string, required
          - `nationality` string, required: ISO 3166-1 alpha-2 country code
          - `idDocument` object, required
            - `type` 'national_id' | 'resident_id' | 'passport', required
            - `number` string, required
            - `issuingCountry` string, required: ISO 3166-1 alpha-2 country code
            - `expiresOn` string, date, required
          - `ownershipPercent` number, required
  - `test` true: Sandbox only. Fills a synthetic, clearly fake legal profile when none is given and activates Product access in the same call.

## Response `201`

Success

- CustomerCreateOutput
  - `tenantId` string, required: Organization tenant ID
  - `productId` string, required: Hyperscale product ID
  - `customerId` string, required: Tenant-local customer ID
  - `partyId` string, required
  - `customerStatus` 'active', required
  - `entityId` string, required: Hyperscale entity ID
  - `entityStatus` 'pending' | 'verified' | 'rejected' | 'disabled' | 'not_checked', required: The legal entity's verification: pending until person KYC or organization KYB clears. A test customer never runs verification, so it reads not_checked and blocks nothing; `identity` reads test and its access is active.
  - `identity` 'test' | 'pending' | 'verified' | 'rejected' | 'disabled', required: One word for the customer's identity: test for a test customer, otherwise entityStatus.
  - `customerAccessId` string, required: Hyperscale customer access ID
  - `customerAccessStatus` 'active'

## Other responses

- `default`: ErrorResponse. See x-error-codes and x-errors for codes, HTTP statuses and retry guidance.

---

[API](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api.md) · [All operations](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/revisions/e9e8faa044d5?raw)