Beneficial Ownership Information

This endpoint is used to add or get beneficial ownership information to a newly created Veem account. To use this endpoint, you require an Oauth2 token. The endpoint is as follows:

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

Headers

There are 2 headers necessary for the use of this endpoint:

X-request-id: This is a number unique to the current API request, and follows the UUID format. Reusing this header without changing the value will result in a 500 (Internal Server Error) status. An example X-request-id is as follows:

48855846-628d-4177-b071-80332a116f0a

Authorization: This header holds the bearer token required to use Veem's public API. Failure to use a valid bearer token will result in a 404 (Not Found) status. An example of a valid token is as follows:

Bearer d49e7fd4-2600-4dd4-a572-118668febbe7

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”
            }
        ],
        "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"
            }
        ]
    }
}

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

Parameter	Mandatory?	Format	Size (in characters)
hasAttestation	Yes	true/false
isControlPerson	Yes (for individualOwnership only)	true/false One control person must be present even if this person has 0% ownership
title	Yes (for individualOwnership, and only if the account is a controlPerson)		128 (Max)
firstName	Yes (for individualOwnership only)		64 (Max)
lastName	Yes (for individualOwnership only)		64 (Max)
dialCode	Yes (for individualOwnership only)	Country code (such as +1 for US or Canada, +31 for Netherlands etc. More info available below the table) Note: The + prefix must be included in the parameter	2-5
phoneNumber	Yes (for individualOwnership only)	1234567654 Note: There is no need to include dashes (-) in the number. The format as shown is sufficient	12 (Max)
businessName	Yes (for businessOwnership only)		128 (Max)
taxId	Yes	For an individual's taxId, you can provide a Tax ID Number, National ID number, Drivers license number or Passport Number.
ownershipPercentage	Yes	Integer	25-100
dateOfBirth	Yes (for individualOwnership only)	MM/DD/YYYY
citizenshipIsoCountryCode	Yes (for individualOwnership only)	ISO 3166-1 alpha-2 standard (eg. US, BE, BT etc)	2
phoneNumberType	Yes (for individualOwnership only)	Mobile, Home or Business
addressLine1	Yes		64 (Max)
addressLine2	No		64 (Max)
addressCity	Yes		2-64
addressPostalCode	Yes		2-10
addressState	Yes		2-64
addressIsoCountryCode	Yes	ISO 3166-1 alpha-2 standard (eg. US, BE, BT etc)	2

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,
                …..
            }
        ],
        "businessOwnerShip": [
            {
                “Id” : 2,
                "businessName": "Another business name",
                "taxId": "33-1867308",
                "ownershipPercentage": 25,
                …
            }
        ]
    }
}

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

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