Create Customer

Creates a customer in the workspace (v2 called it an account). A new customer starts pending, with verification_status incomplete: verify an individual through KYC.

Takes a workspace-scoped API key or a dashboard session. An account-scoped key is refused with 401.

Replaces POST /api/v2/accounts.

Authorization:

Every request is signed with your API key: a short-lived JWT, signed with your private key, sent in one header on /v3/* and /api/v2/* alike.

Headers:
  Authorization: APIKey {SIGNED_JWT}

How to build and sign the JWT: Authentication.

Endpoint

POST

/v3/customers

Headers

Header	Description
Idempotency-Key	Required, for every caller. One key per intended customer: any printable-ASCII string of 1 to 255 characters (a UUID is recommended), sent again unchanged on every retry of it. A retry answers the first response, with Idempotency-Replayed: true, instead of creating the customer twice. See API v3 overview.

Request Body Sample

{
  "customer_type": "individual",
  "name": "Samantha Reyes",
  "email": "samantha@example.com"
}

Request Body Schema

Field	Type	Description
customer_type	string	Required. individual or business.
name	string	Required. 3 to 255 characters, surrounding spaces trimmed.
email	string	Required. A valid email, at most 255 characters, not used by another customer of the workspace.

Response Sample

{
  "id": "cst_01k8x40x9gfx6sv8a99hswy9bd",
  "reference": "019a3a40-7530-7f4d-9da1-494c73cf256d",
  "name": "Samantha Reyes",
  "email": "samantha@example.com",
  "customer_type": "individual",
  "status": "pending",
  "verification_status": "incomplete",
  "created_at": "2025-10-31T12:31:34Z",
  "updated_at": "2025-10-31T12:31:34Z"
}

Answers 200 with the new customer.

Response Schema

A customer, with the fields of a List Customers item. reference is the UUID form of id.

Errors

Status	message	When
400	invalid_customer_name	name is shorter than 3 or longer than 255 characters.
400	invalid_email	email is longer than 255 characters or cannot be read as an address.
400	failed to parse request	The body is not valid JSON, or customer_type is not individual or business.
400	idempotency_key_required	No Idempotency-Key header, or an empty one.
400	idempotency_key_invalid	The Idempotency-Key is longer than 255 characters, or not printable ASCII.
401	unauthorized	Missing or invalid signature, or the caller is an account-scoped key or a customer session.
403	forbidden	A dashboard member whose role does not allow this. A workspace-scoped key always may.
409	customer_email_exists	A customer of this workspace already has this email.
409	idempotency_in_progress	The same Idempotency-Key is still running. Retry after Retry-After seconds with the same key.
422	Validation failed	A required field is missing or email is not an email; details names it.
413	body_too_large	The signed body is over 1 MiB.
422	idempotency_key_conflict	The same Idempotency-Key was used for a different request.
503	idempotency_unavailable	The retry store could not be reached. Nothing was created: retry later with the same key.

Coming from v2

v2 (POST /api/v2/accounts)	v3
no idempotency header	Idempotency-Key required
accountType	customer_type
accountName	name
firstName, lastName	not taken; the applicant's names go on the KYC record
reference (your own value)	not taken; v3 sets reference to the id's UUID
id (uuid) in the response	id (cst_…)
createdAt, updatedAt	created_at, updated_at

Support and Resources

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

• Instagram: BlockWyre Instagram
• Twitter: BlockWyre Twitter
• Facebook: BlockWyre Facebook
• LinkedIn: BlockWyre LinkedIn

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!