Open KYC Record

Opens an individual customer's verification record, empty and pending. A customer has one: opening it again returns the existing record with 200 instead of a conflict, so a retry is safe and needs no Idempotency-Key.

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

Replaces, with Submit KYC Details, POST /api/v2/kyc/banking-verification/individual.

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/{customer_id}/kyc

Path parameters

Parameter	Type	Description
customer_id	string (cst_…)	Required. The customer to verify. Must be an individual.

No request body.

Response Sample

{
  "id": "kyc_01k8x494z0e2escqpt6bde8hag",
  "customer_id": "cst_01k8x40x9gfx6sv8a99hswy9bd",
  "type": "banking",
  "status": "pending",
  "status_reason": "verification record created",
  "ready": false,
  "event_history": [
    {
      "status": "pending",
      "status_reason": "verification record created",
      "date": "2025-10-31T12:36:04Z"
    }
  ],
  "created_at": "2025-10-31T12:36:04Z",
  "updated_at": "2025-10-31T12:36:04Z"
}

Answers 201 when the record was created, 200 when it already existed (with the record as it is).

Response Schema

Field	Type	Description
id	string (kyc_…)	The record.
customer_id	string (cst_…)	Its customer.
type	string	Always banking.
status	string	pending, in_review, approved, needs_update or rejected. See Verification Flow.
status_reason	string	Why the record has its status. Omitted when empty.
provider	string	The provider verifying it, e.g. braid. Omitted until there is one.
email, first_name, last_name, phone, date_of_birth, nationality	string	The applicant's details. See Submit KYC Details. Each is omitted while empty.
address	object	line1, line2, city, state, postal_code, country. Omitted while empty.
identity_document	object	number, type, issue_date, expiry_date, country_of_issue. Omitted while empty.
occupation, employed_company_name, employed_job_title	string	Employment. Omitted while empty.
source_of_funds	array of string	Omitted while empty.
ready	boolean	true once the record has what a provider needs to identify the applicant: first_name, last_name, date_of_birth, identity_document.number and identity_document.type. Documents are not counted.
event_history	array	Status changes, newest first.
event_history[].status	string	The status set.
event_history[].status_reason	string	Why.
event_history[].date	string (RFC 3339)	When.
created_at	string (RFC 3339)	When the record was opened.
updated_at	string (RFC 3339)	When it last changed.

Every KYC endpoint that returns a record returns this shape.

Errors

Status	message	When
400	failed to parse request	customer_id is not a cst_… TypeID.
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.
404	customer_not_found	No such customer in this workspace.
422	kyc_business_not_supported	The customer is a business: verify it through KYB.

Coming from v2

v2 (POST /api/v2/kyc/banking-verification/individual)	v3
one call that saves the details	two: open the record here, then write the details with Submit KYC Details
accountId in the body	customer_id in the path
response verificationUrl	none: upload documents through the API (Presign)

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!