Beneficial Ownership Information

This endpoint is used to add or get beneficial ownership information to a newly created Veem account.

POST https://sandbox-api.veem.com/veem/v1.2/beneficial-ownership

📌

Effective April 15th, 2026: Beneficial Ownership Information payloads support a new optional field, documentIds, to link account documents to each owner.

What's New: documentIds

documentIds is an optional array of Long values available in both individualOwnerShip[] and businessOwnerShip[] objects.

This field is used to link uploaded documents to a specific beneficial owner for verification compliance and KYC/KYB processes.

You should use document IDs returned by the Account Document API response. For reference, see Account Document.

Request Payload

When adding beneficial ownership information to an account using Veem's API, one must follow the format as shown in the following example:

{
    "beneficialOwnerShip": {
        "hasAttestation": true,
        "individualOwnerShip": [
            {
                "firstName": "John",
                "lastName": "Duenas",
                "ownershipPercentage": 25,
                "dateOfBirth": "12/31/1990",
                "citizenshipIsoCountryCode": "US",
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "phoneNumberType": "mobile",
                "dialCode": "+1",
                "phoneNumber": "4152306359",
                "taxId": "121-31-2321",
                "isControlPerson" : true,
                "title" : "CEO of the company",
                "documentIds": [10001, 10002]
            }
        ],
        "businessOwnerShip": [
            {
                "businessName": "Another business name",
                "taxId": "33-1867308",
                "ownershipPercentage": 25,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [20001]
            }
        ]
    },
    "onBehalfAccountId": 412312 // se Partner Notes
}

Note: When adding beneficial ownership information, you can add details for individual ownership, business ownership or both simultaneously, like in the above example

Request Parameters

The following table contains detailed information on the payload's parameters, such as the parameter name, whether it is mandatory or not, formatting (if applicable), and size of the parameter

How documentIds Is Processed by Endpoint

• POST (/veem/v1.2/beneficial-ownership):
  If documentIds is provided and not empty for an owner, Veem creates the owner first, then links those document IDs to that owner.
  If documentIds is null or empty, document linking is skipped.

• PATCH (/veem/v1.2/beneficial-ownership/{id}):
  Veem compares the current owner's linked documents vs. the incoming documentIds.

  • IDs present in request but not currently linked are linked.
  • IDs currently linked but missing from request are unlinked.
  • If documentIds is null, no document link/unlink changes are applied.

• PUT (/veem/v1.2/beneficial-ownership/{id}):
  Uses the same compare-and-sync behavior as PATCH for documentIds.
  If documentIds is null, no document link/unlink changes are applied.

• GET (/veem/v1.2/beneficial-ownership):
  Returns the current documentIds linked to each owner in the response payload.

For extra information, you can find some resources here: ISO 3166-1 alpha-2 standard: https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes Dial codes: https://en.wikipedia.org/wiki/List_of_country_calling_codes

Response Payload

Once a valid response has been sent, a response payload of this format should be expected:

{
    "beneficialOwnerShip": {
        "individualOwnerShip": [
            {
                 “Id” : 1
                "firstName": "John",
                "lastName": "Duenas",
                "ownershipPercentage": 25,
                "documentIds": [10001, 10002],
                …..
            }
        ],
        "businessOwnerShip": [
            {
                “Id” : 2,
                "businessName": "Another business name",
                "taxId": "33-1867308",
                "ownershipPercentage": 25,
                "documentIds": [20001],
                …
            }
        ]
    }
}

Get Beneficial Ownership Information

If, instead of adding beneficial ownership information to a new account, one wants to fetch the beneficial ownership information of an existing account, one can use the following endpoint:

GET https://sandbox-api.veem.com/veem/v1.2/beneficial-ownership

👍

Partner Notes:

• A partner account can be configured to make this API request on behalf of their customers. This requires internal configuration for the partner account by Veem. Once the internal configuration is enabled, the API request can be made using partner account bearer token.

One can expect to get the a response payload of the same type as the above response