Beneficial Ownership Information

Using Veem's Beneficial Ownership endpoint you are able to add beneficial ownership info for an account you just created

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 409 (Conflict) 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, 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

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