Skip to main content

List Beneficial Owners

The business's beneficial owners, oldest first, each with its own status and its own ready. Verification can be requested only once every owner is ready, so check them one by one here.

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

New in v3: in v2, owners were part of GET /api/v2/kyb/banking-verification/business/{accountId}, as owners.

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

GET

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

Path parameters​

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

The whole set is returned at once: this list is not paginated. A customer with no record answers 204 No Content, with no body. An id that names no customer of the workspace answers 404 customer_not_found, not 204.

Response Sample​

{
  "owners": [
    {
      "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": true,
      "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"
    },
    {
      "id": "kyc_01m24nmvc0f8zvyabp5bhg4gtg",
      "status": "pending",
      "status_reason": "owner added",
      "first_name": "Daniel",
      "last_name": "Okafor",
      "email": "daniel@acmerobotics.example.com",
      "title": "CTO",
      "ownership_percentage": 49,
      "ready": false,
      "event_history": [
        { "status": "pending", "status_reason": "owner added", "date": "2026-09-09T15:10:00Z" }
      ],
      "created_at": "2026-09-09T15:10:00Z",
      "updated_at": "2026-09-09T15:10:00Z"
    }
  ]
}

Response Schema​

FieldTypeDescription
ownersarrayThe owners, oldest first. Each has the fields of an owner.

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.

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!