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

📘
Headers
Three headers are required to use this endpoint.
Required Headers
Name
Type
Required
Description
Authorization
string
Yes
Bearer token (OAuth 2.0) This header holds the bearer token required to use Veem's public API, and belongs to the owner account. Failure to use a valid bearer token will result in a 404 (Not Found) status code in the response. An example of a valid header value is as follows: Bearer c047594b-082c-4da1-be89-08fe3770f4b3
See Get Access Token section to generate your Bearer token
X-Request-Id
string
Yes
This is a unique string that identifies the current API request, and should follow the UUID format. Reusing this header without changing the value will result in a 409 (Conflict) status code in the response. An example X-request-id is as follows:
48855846-628d-4177-b071-80332a116f0a
Content-Type
string
Yes
The content type of the request. Must be application/json

Name	Type	Required	Description
`Authorization`	`string`	Yes	Bearer token (OAuth 2.0) This header holds the bearer token required to use Veem's public API, and belongs to the owner account. Failure to use a valid bearer token will result in a 404 (Not Found) status code in the response. An example of a valid header value is as follows: `Bearer c047594b-082c-4da1-be89-08fe3770f4b3` See Get Access Token section to generate your Bearer token
`X-Request-Id`	`string`	Yes	This is a unique string that identifies the current API request, and should follow the UUID format. Reusing this header without changing the value will result in a 409 (Conflict) status code in the response. An example X-request-id is as follows: `48855846-628d-4177-b071-80332a116f0a`
`Content-Type`	`string`	Yes	The content type of the request. Must be `application/json`

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

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, andonly if the account is a controlPerson)		128 (Max)
firstName	Yes* (for individualOwnership only)		64 (Max)
lastName	Yes* (for individualOwnership only)		64 (Max)
dialCode	No	Country code (such as +1 for US or Canada, +31 for Netherlands etc. More info available below the table) Note*: The + prefixmust be included in the parameter	2-5
phoneNumber	No	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	0-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	No (Will be ignored if dialCode and phoneNumber are not provided)	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

👍
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.

onBehalfAccountId is an optional parameter, this needs to be included on the request body in case of partner making an API request on behalf of their customer. This is the customer Veem account ID, e.g. 453221.

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