Skip to main content
POST
Create a client

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Hevn-Account
string | null

The client account to act for, as a cl_… id. Omit it to act as yourself.

Example:

"cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

Idempotency-Key
string | null

Your own key for this write, ^[A-Za-z0-9._:-]{1,128}$. A retry with the same key replays the first answer; the same key with a different request is refused.

Example:

"po-inv-2026-114"

Body

application/json
name
string
required

Legal name of the company to open.

Required string length: 1 - 500
email
string<email>
required

Email address of the company. It must not belong to another account.

phone
string | null

Phone number in international E.164 format.

Pattern: ^\+[1-9]\d{6,14}$

Response

Successful Response

id
string
required

The X-Hevn-Account value for this client. Store it on your server and do not accept it from a browser.

Pattern: ^(?:cl_)?[A-Za-z0-9._:\-]{1,216}$
Example:

"cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

status
enum<string>
required

Current account-provisioning status.

Available options:
provisioning,
ready,
failed
createdAt
string<date-time>
required

UTC timestamp when the account was created.

name
string | null

Legal or trading name of the account. A linked account often has none. Its company name is in the KYB document.

email
string | null

Email address of the account. For a linked account, the address the holder signed in with.

phone
string | null

Phone number in international E.164 format.

baseSmartWallet
string | null

Address of the client's Base smart wallet. Routes select the client by id, sent as X-Hevn-Account.

kybStatus
enum<string>
default:notStarted

Business-verification status, the same value as status on GET /client/kyb. For an individual, read verifiedAt.

Available options:
notStarted,
pending,
approved,
rfi,
rejected
kybApplicationId
string | null

Identifier of the latest business-verification application.

Pattern: ^(?:kyb_)?[A-Za-z0-9._:\-]{1,216}$
Example:

"kyb_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

verifiedAt
string<date-time> | null

When the account was verified: identity verification for a person, KYB for a business. Poll this field to follow an individual's verification.

failure
ClientFailureResponse · object | null

Provisioning failure details. Present when status is failed.

pollUrl
string | null

Relative API URL to poll with this response's id in X-Hevn-Account.

transferPolicy
TransferPolicyResponse · object | null

Account-level controls for the ways this client may move money.