Request Verification

Hands the business and all its beneficial owners to the verification provider, together: there is no separate request per owner. The record moves to in_review and the verification runs in the background. Follow it with Get Business Verification and List Beneficial Owners.

The provider gets one attempt per business, so nothing incomplete is sent. The request is refused, with one code per missing piece, unless:

1. the business's own details are complete (ready on the record): otherwise kyb_incomplete_applicant;
2. at least one business document is uploaded and completed: otherwise kyb_missing_documents;
3. the business has at least one owner: otherwise kyb_no_owners;
4. every owner is ready, with its details complete and its selfie and document front completed: otherwise kyb_owner_not_approved. Despite its name, this code is about completeness: owners are approved by this verification, not before it.

Requesting again is safe. While a verification is under way, or once the record is approved, the call starts nothing and answers 200 with already_running: true.

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

Replaces POST /api/v2/kyb/banking-verification/business/request-verification and, for owners, POST /api/v2/kyb/banking-verification/business/ownership/{ownerId}/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}/kyb/request-verification

Path parameters

Parameter	Type	Description
customer_id	string (cst_…)	Required. The business customer.

No request body.

Response Sample

{
  "kyb": {
    "id": "kyb_01m24es440fqxr7z5xsphsmvqm",
    "customer_id": "cst_01m24bb8g0f28rhegcwp8rfbqd",
    "status": "in_review",
    "status_reason": "verification requested",
    "name": "Acme Robotics Inc",
    "dba_name": "Acme Robotics",
    "entity_type": "corporation",
    "phone": "+14155550123",
    "email": "ops@acmerobotics.example.com",
    "website": "https://acmerobotics.example.com",
    "id_number": "12-3456789",
    "id_document_type": "ein",
    "tax_number": "12-3456789",
    "formation_date": "2019-06-01",
    "incorporation_state": "DE",
    "address": {
      "line1": "500 Terry A Francois Blvd",
      "line2": "Suite 400",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94158",
      "country": "US"
    },
    "operation_address": {
      "line1": "1 Market St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "ready": true,
    "event_history": [
      { "status": "in_review", "status_reason": "verification requested", "date": "2026-09-10T09:05:00Z" },
      { "status": "pending", "status_reason": "verification record created", "date": "2026-09-09T14:20:00Z" }
    ],
    "created_at": "2026-09-09T14:20:00Z",
    "updated_at": "2026-09-09T14:32:10Z"
  },
  "already_running": false
}

Response Schema

Field	Type	Description
kyb	object	The record after the request, with the fields of Get Business Verification. Its updated_at is still the value from before the request: read the record again for the new one.
already_running	boolean	true when nothing was started, because a verification was already under way or the record is already approved.

Errors

Status	message	When
400	failed to parse request	customer_id is not a cst_… TypeID.
401	unauthorized	Missing or invalid signature, or an account-scoped key or 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 the workspace.
404	kyb_not_found	This customer has no record. Open it first.
409	kyb_needs_update	The record is needs_update: it was sent back for changes.
409	kyb_rejected	The record is rejected. It cannot be verified again.
422	kyb_individual_not_supported	The customer is an individual.
422	kyb_incomplete_applicant	The business's own details are not complete.
422	kyb_missing_documents	No business document is completed.
422	kyb_no_owners	The business has no owner.
422	kyb_owner_not_approved	An owner is not ready. List Beneficial Owners shows which.

When several apply, the first check in this order answers: customer_not_found; kyb_individual_not_supported; kyb_not_found; the record's status (200 with already_running: true when in_review or approved, 409 kyb_needs_update, 409 kyb_rejected); then kyb_incomplete_applicant, kyb_missing_documents, kyb_no_owners and kyb_owner_not_approved, in that order.

Coming from v2

v2	v3
accountId (body, uuid)	customer_id (path, cst_…), no body
every owner had to be approved first, through Request Ownership Verification and its verification link	no per-owner request: every owner must be ready, and is verified in this same run
answers the record	answers kyb and already_running
an already approved verification answers the record	already_running: true
400 for a record needs_update or rejected	409 kyb_needs_update or 409 kyb_rejected

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!