Beneficial Owner Documents

An owner's identity evidence: a selfie and the front and back of the identity document named in its identity_document. They are uploaded with the same three steps as a business document: presign, upload the file to the returned url, complete. An owner is ready once its face and document-front are completed.

slot	Is	Required
face	A selfie of the owner.	Yes
document-front	The front of the identity document.	Yes
document-back	The back of the identity document.	No: not every document has one.

Each slot holds one file, and presigning a slot that has one replaces it. On top of the per-file limit, an owner's documents share a total (remaining_bytes), because they travel to the verification provider together. They are locked once the owner is in_review, approved or rejected.

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

New in v3: in v2, an owner's files went in the multipart/form-data body of Submit External Ownership 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.

All four endpoints take these path parameters:

Parameter	Type	Description
customer_id	string (cst_…)	Required. The business customer.
owner_id	string (kyc_…)	Required. The owner, from List Beneficial Owners.

Every endpoint can also answer:

Status	message	When
400	failed to parse request	A path id is not a TypeID of its kind, or the body is not valid JSON.
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.
404	kyb_owner_not_found	No such owner on this business.

List

Endpoint

GET

/v3/customers/{customer_id}/kyb/owners/{owner_id}/documents

The owner's documents, the per-file limit and what is left of the owner's total. Not paginated.

Response Sample

{
  "documents": [
    {
      "document_id": "doc_01m24zye80ezv85v7bb8jgzhtt",
      "slot": "face",
      "state": "ready",
      "size_bytes": 412337,
      "content_type": "image/jpeg",
      "file_name": "selfie.jpg"
    },
    {
      "document_id": "doc_01m253c9w0fhqv64yccqpwsdne",
      "slot": "document-front",
      "state": "ready",
      "size_bytes": 1048576,
      "content_type": "image/jpeg",
      "file_name": "passport-front.jpg"
    }
  ],
  "max_document_bytes": 3145728,
  "remaining_bytes": 5879119
}

Response Schema

Field	Type	Description
documents	array	One entry per slot on file, with the fields of a business document; slot is face, document-front or document-back.
max_document_bytes	integer	The largest file accepted, in bytes.
remaining_bytes	integer	What the owner's documents may still add up to, in bytes. Pending documents count.

Presign

Endpoint

POST

/v3/customers/{customer_id}/kyb/owners/{owner_id}/documents/presign

Request Body Sample

{
  "slot": "document-back",
  "content_type": "image/jpeg",
  "size_bytes": 987654,
  "file_name": "passport-back.jpg"
}

Request Body Schema

Field	Type	Description
slot	string	Required. face, document-front or document-back.
content_type	string	Required. application/pdf, image/jpeg or image/png. The upload must carry exactly this type.
size_bytes	integer	Required. The file's size in bytes: at most max_document_bytes, and within remaining_bytes. A file being replaced does not count against the total.
file_name	string	The file's name on the uploader's machine, shown back in listings. Display only.

Response Sample

{
  "document_id": "doc_01m256t5g0es2rzt92346h4xbn",
  "url": "https://uploads.example.com/kyb-documents",
  "fields": {
    "key": "kyb/owner/01a08923-7f00-72d0-b434-a49c19eb0524/01a08a6d-1600-7645-8fe9-22190d127575.jpg",
    "policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0wOS0wOVQxNTozNTowMFoi…",
    "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
    "X-Amz-Credential": "ASIA…/20260909/us-east-1/s3/aws4_request",
    "X-Amz-Date": "20260909T152000Z",
    "X-Amz-Security-Token": "IQoJb3JpZ2luX2Vj…",
    "X-Amz-Signature": "9e41d7…",
    "Content-Type": "image/jpeg"
  },
  "remaining_bytes": 4891465
}

Response Schema

Field	Type	Description
document_id	string (doc_…)	The document. Use it to complete or delete it.
url	string	Where to POST the upload, exactly as for a business document.
fields	object	Form fields to send with the upload, verbatim and before the file part (named file). Treat them as opaque.
remaining_bytes	integer	What is left of the owner's total once this document is counted.

Errors

Status	message	When
400	failed to parse request	slot is not one of the three.
400	unsupported_document_content_type	content_type is not PDF, JPEG or PNG.
400	document_too_large	size_bytes is over max_document_bytes, or negative.
409	document_budget_exceeded	The file fits the per-file limit but not what is left of the owner's total.
409	kyb_verification_in_flight	The owner is in_review.
409	kyb_already_approved	The owner is approved.
409	kyb_rejected	The owner is rejected.
422	Validation failed	slot, content_type or size_bytes is missing, or size_bytes is 0; details names it.

Complete

Endpoint

POST

/v3/customers/{customer_id}/kyb/owners/{owner_id}/documents/{document_id}/complete

Call it once the upload succeeded. It reads the file's real size and type from storage and marks the document ready. Takes document_id (doc_…, from the presign) in the path and no body.

Response

204 No Content, with no body.

Errors

Status	message	When
404	document_not_found	No such document on this owner.
409	document_not_uploaded	Nothing arrived in storage for this document. Upload it, or presign again.

Delete

Endpoint

DELETE

/v3/customers/{customer_id}/kyb/owners/{owner_id}/documents/{document_id}

Removes a document, which frees its slot for a different file. Takes document_id (doc_…) in the path. Deleting one that is already gone answers 404.

Response

204 No Content, with no body.

Errors

Status	message	When
404	document_not_found	No such document on this owner, or it was already deleted.
409	kyb_verification_in_flight	The owner is in_review.
409	kyb_already_approved	The owner is approved.
409	kyb_rejected	The owner is 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!