Add a Beneficial Owner
Adds one beneficial owner to the business, in one call: personal details, residential address, identity document, title and ownership share. BlockWyre creates the owner's id (kyc_…) and returns it as id; you do not send one. There is no owner update: to change an owner, remove it and add it again.
Every field is optional, so an owner can be saved partly filled. An owner is complete (ready) once it has a name, a date of birth and an identity document, and its selfie and document front are uploaded with Beneficial Owner Documents. The owner is verified together with the business when you request verification.
Owners can be added while the business record is pending, ready_for_review or needs_update.
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/ownership.
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
/v3/customers/{customer_id}/kyb/owners
Path parameters
| Parameter | Type | Description |
|---|---|---|
customer_id | string (cst_…) | Required. The business customer. Its record must be open. |
Request Body Sample
{
"first_name": "Samantha",
"last_name": "Reyes",
"email": "samantha@acmerobotics.example.com",
"phone": "+14155550187",
"date_of_birth": "1990-04-12",
"nationality": "US",
"address": {
"line1": "742 Valencia St",
"line2": "Apt 3",
"city": "San Francisco",
"state": "CA",
"postal_code": "94110",
"country": "US"
},
"identity_document": {
"number": "X1234567",
"type": "passport",
"issue_date": "2018-03-01",
"expiry_date": "2028-03-01",
"country_of_issue": "US"
},
"title": "CEO",
"ownership_percentage": 51,
"is_primary": true
}
Request Body Schema
"Needed for ready" marks what an owner must have before you can request verification.
| Field | Type | Description |
|---|---|---|
first_name | string | Up to 255 characters. Needed for ready. |
last_name | string | Up to 255 characters. Needed for ready. |
email | string | Email. |
phone | string | E.164 format, e.g. +14155550187. |
date_of_birth | string | YYYY-MM-DD. Needed for ready. |
nationality | string | ISO 3166-1 alpha-2, e.g. US. |
address | address | Residential address. Same fields and rule as the business's address. |
identity_document | object | The owner's government identity document. Once any of its fields is set, number and type are required. |
identity_document.number | string | 2 to 20 characters. Needed for ready. |
identity_document.type | string | passport, driver_license, national_id, ssn, itin, ein or other. Needed for ready. |
identity_document.issue_date | string | YYYY-MM-DD. |
identity_document.expiry_date | string | YYYY-MM-DD. |
identity_document.country_of_issue | string | ISO 3166-1 alpha-2. |
title | string | The owner's role in the business, free text, e.g. CEO. Up to 255 characters. |
ownership_percentage | number | The owner's share, 1 to 100. Leave it out when not known yet. Shares are not checked to add up to 100. |
is_primary | boolean | This owner is the business's principal contact for the verification provider. |
Response Sample
201 Created:
{
"id": "kyc_01m24j6zr0eb8b8d54kgcyp194",
"status": "pending",
"status_reason": "owner added",
"first_name": "Samantha",
"last_name": "Reyes",
"email": "samantha@acmerobotics.example.com",
"phone": "+14155550187",
"date_of_birth": "1990-04-12",
"nationality": "US",
"address": {
"line1": "742 Valencia St",
"line2": "Apt 3",
"city": "San Francisco",
"state": "CA",
"postal_code": "94110",
"country": "US"
},
"identity_document": {
"number": "X1234567",
"type": "passport",
"issue_date": "2018-03-01",
"expiry_date": "2028-03-01",
"country_of_issue": "US"
},
"title": "CEO",
"ownership_percentage": 51,
"is_primary": true,
"ready": false,
"event_history": [
{
"status": "pending",
"status_reason": "owner added",
"date": "2026-09-09T15:02:00Z"
}
],
"created_at": "2026-09-09T15:02:00Z",
"updated_at": "2026-09-09T15:02:00Z"
}
ready is false here: the owner's documents are not uploaded yet.
Response Schema
Fields with no value are omitted.
| Field | Type | Description |
|---|---|---|
id | string (kyc_…) | The owner. |
status | string | The owner's own status, with the same values as the business's. It moves to in_review, then to a verdict, when you request verification. |
status_reason | string | Why the status last changed. |
provider | string | The verification provider, once the owner has been handed to it. |
first_name … is_primary | As sent. | |
ready | boolean | The owner is complete: first_name, last_name, date_of_birth, identity_document.number and identity_document.type are set, and a selfie (face) and document front (document-front) are uploaded and completed. An owner already approved needs no documents. Request Verification is refused while any owner is not ready. |
external_verification_provider | string | What External Owner Verification last recorded. |
external_verification_raw | object or array | The same. |
event_history | array | Every status change, newest first, with status, status_reason and date. |
created_at | string (RFC 3339) | When the owner was added. |
updated_at | string (RFC 3339) | When it last changed. |
Errors
| Status | message | When |
|---|---|---|
400 | failed to parse request | The body is not valid JSON, identity_document.type is not one of its values, or customer_id is not a cst_… TypeID. |
400 | invalid_address | The address is only partly filled in. |
400 | invalid_country | The address has other fields but no country. |
400 | invalid_id_number | identity_document has fields but no valid number. |
400 | invalid_id_document_type | identity_document has fields but no type. |
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_verification_in_flight | The business record is in_review. |
409 | kyb_already_approved | The business record is approved. |
409 | kyb_rejected | The business record is rejected. |
422 | Validation failed | A value has the wrong format, length or range (email, phone, a date, a country, postal_code, ownership_percentage outside 1 to 100); details names the field. |
Coming from v2
v2 (POST /api/v2/kyb/banking-verification/business/ownership) | v3 |
|---|---|
accountId and ownerId (body, uuid) | customer_id (path, cst_…); the owner's id is created for you and returned as id (kyc_…) |
| every field required | every field optional; completeness shows in ready and is checked at request verification |
documentId.idNumber, idDocumentType, idIssueDate, idExpiryDate, idCountryOfIssue | identity_document.number, type, issue_date, expiry_date, country_of_issue |
documentId.nationality | nationality, at the top level |
role | title |
address1, address2, postalCode | line1, line2, postal_code |
| no primary owner | is_primary |
| then Request Ownership Verification for each owner | no per-owner request: owners are verified with the business |
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!