Request Verification

Hands a customer's verification record to the verification provider. The record moves to in_review, and the provider's verdict, approved or rejected, lands on it later: read it with Get KYC Record. The provider never answers needs_update: that status comes only from a BlockWyre staff review, which can also settle the record.

The provider takes a record once, so this checks everything first. It refuses the request unless the record has first_name, last_name, date_of_birth, identity_document.number and identity_document.type (see ready), and confirmed (ready) documents in the face and document-front slots.

Requesting again while the record is in_review or approved is a retry, not an error: it answers 200 with already_running: true and starts nothing.

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

Replaces POST /api/v2/kyc/banking-verification/individual/{accountId}/request-verification.

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/request-verification

Path parameters

Parameter	Type	Description
customer_id	string (cst_…)	Required. The customer. Its record must be pending.

No request body.

Response Sample

{
  "kyc": {
    "id": "kyc_01k8x494z0e2escqpt6bde8hag",
    "customer_id": "cst_01k8x40x9gfx6sv8a99hswy9bd",
    "type": "banking",
    "status": "in_review",
    "status_reason": "verification requested",
    "email": "samantha@example.com",
    "first_name": "Samantha",
    "last_name": "Reyes",
    "phone": "+14155550123",
    "date_of_birth": "1990-04-12",
    "nationality": "US",
    "address": {
      "line1": "742 Evergreen Terrace",
      "line2": "Apt 2",
      "city": "Springfield",
      "state": "OR",
      "postal_code": "97477",
      "country": "US"
    },
    "identity_document": {
      "number": "X1234567",
      "type": "passport",
      "issue_date": "2018-03-01",
      "expiry_date": "2028-03-01",
      "country_of_issue": "US"
    },
    "ready": true,
    "event_history": [
      {
        "status": "in_review",
        "status_reason": "verification requested",
        "date": "2025-10-31T12:47:10Z"
      },
      {
        "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:47:10Z"
  },
  "already_running": false
}

Response Schema

Field	Type	Description
kyc	object	The record after the request. See Open KYC Record.
already_running	boolean	true when the record was already in_review or approved (or a verification was already under way) and nothing new was started.

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.
404	kyc_not_found	The customer has no record: open one first.
409	kyc_needs_update	The record is needs_update: it was sent back for changes and cannot be requested again here.
409	kyc_rejected	The record is rejected. It cannot be resubmitted.
422	kyc_incomplete_applicant	A required applicant field is missing (see above).
422	kyc_missing_documents	The face or document-front document is missing or its upload was never completed.
422	kyc_business_not_supported	The customer is a business: verify it through KYB.

When several apply, the first check in this order answers: customer_not_found; kyc_business_not_supported; kyc_not_found; the record's status (200 with already_running: true when in_review or approved, 409 kyc_needs_update, 409 kyc_rejected); then kyc_incomplete_applicant and kyc_missing_documents, in that order.

Coming from v2

v2 (POST …/individual/{accountId}/request-verification)	v3
accountId (uuid)	customer_id (cst_…)
response { accountId, verificationUrl }	{ kyc, already_running }; no verification link
documents uploaded by the applicant afterwards, through the link	documents uploaded first (Presign); refused without them (422 kyc_missing_documents)
400 when the details were not submitted	422 kyc_incomplete_applicant
an approved or in_review record returned as is	the same, with already_running: true

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!