Skip to main content

Open a Business Verification

Opens a business customer's verification record (KYB). Every other KYB call needs it, so this one comes first. Opening a record that already exists returns that record unchanged, so a retry is safe. Only a business customer can have one; an individual is refused.

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

Replaces the record-creating half of POST /api/v2/kyb/banking-verification/business.

The verification flow​

  1. Open the record (this page).
  2. Write the business's details with Submit Business Details. Save as often as you like: nothing is checked for completeness until step 5.
  3. Upload at least one business document: presign, upload, complete.
  4. Add every beneficial owner with Add a Beneficial Owner, and upload each owner's selfie and identity document with Beneficial Owner Documents. If you already verified an owner with your own provider, attach the result with External Owner Verification.
  5. Request verification. The business and all its owners go to the verification provider together. Follow the outcome with Get Business 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

Path parameters​

ParameterTypeDescription
customer_idstring (cst_…)Required. The business customer.

No request body.

Response Sample​

201 Created for a new record:

{
  "id": "kyb_01m24es440fqxr7z5xsphsmvqm",
  "customer_id": "cst_01m24bb8g0f28rhegcwp8rfbqd",
  "status": "pending",
  "status_reason": "verification record created",
  "ready": false,
  "event_history": [
    {
      "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:20:00Z"
}

Response Schema​

201 Created with the new record, or 200 OK with the one already there. Fields as in Get Business Verification.

Errors​

StatusmessageWhen
400failed to parse requestcustomer_id is not a cst_… TypeID.
401unauthorizedMissing or invalid signature, or an account-scoped key or customer session.
403forbiddenA dashboard member whose role does not allow this. A workspace-scoped key always may.
404customer_not_foundNo such customer in the workspace.
422kyb_individual_not_supportedThe customer is an individual.

Coming from v2​

v2 (POST /api/v2/kyb/banking-verification/business)v3
one call creates the record and saves the detailsPOST …/kyb opens it, PATCH …/kyb writes the details
accountId (body, uuid)customer_id (path, cst_…)
reading the status creates a blank record when there is noneonly this call creates one; reading answers 204

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:

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!