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.

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`

📌
Effective April 29, 2026: Beneficial Ownership Information payloads supportdocumentIds, to link account documents to each owner.

What's New: `documentIds & hierarchical BOI payload`

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": "Michael",
                "lastName": "Anderson",
                "ownershipPercentage": 1.0,
                "dateOfBirth": "12/31/1990",
                "citizenshipIsoCountryCode": "US",
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "taxId": "121-12-1212",
                "isControlPerson": true,
                "title": "CEO of the company",
                "email": "[email protected]",
                "documentIds": [10001, 10002]
            },
            {
                
                "firstName": "Sarah",
                "lastName": "Mitchell",
                "ownershipPercentage": 2.0,
                "dateOfBirth": "12/31/1990",
                "citizenshipIsoCountryCode": "US",
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "taxId": "121-12-1213",
                "isControlPerson": false,
                "title": "CFO",
                "email": "[email protected]",
                "documentIds": [10003]
            }
        ],
        "businessOwnerShip": [
            {
               
                "businessName": "Anderson Holdings LLC",
                "taxId": "33-1000001",
                "ownershipPercentage": 3.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10004]
            },
            {
               
                "businessName": "Mitchell Investments Inc",
                "taxId": "33-1000002",
                "ownershipPercentage": 4.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10005]
            },
            {
               
                "businessName": "Carter Group LLC",
                "taxId": "33-1000003",
                "ownershipPercentage": 5.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10006],
                "individualOwnerShip": [
                    {
                       
                        "firstName": "David",
                        "lastName": "Thompson",
                        "ownershipPercentage": 6.0,
                        "dateOfBirth": "12/31/1990",
                        "citizenshipIsoCountryCode": "US",
                        "addressLine1": "Address line 1",
                        "addressLine2": "Address line 2",
                        "addressCity": "San Francisco",
                        "addressState": "CA",
                        "addressPostalCode": "94111",
                        "addressIsoCountryCode": "US",
                        "taxId": "121-12-1214",
                        "isControlPerson": false,
                        "title": "Director",
                        "email": "[email protected]",
                        "documentIds": [10007,10008] 
                    },
                    {
                        
                        "firstName": "Emily",
                        "lastName": "Carter",
                        "ownershipPercentage": 7.0,
                        "dateOfBirth": "12/31/1990",
                        "citizenshipIsoCountryCode": "US",
                        "addressLine1": "Address line 1",
                        "addressLine2": "Address line 2",
                        "addressCity": "San Francisco",
                        "addressState": "CA",
                        "addressPostalCode": "94111",
                        "addressIsoCountryCode": "US",
                        "taxId": "121-12-1215",
                        "isControlPerson": false,
                        "title": "Manager",
                        "email": "[email protected]",
                        "documentIds": [10011]
                    }
                ],
                "businessOwnerShip": [
                    {
                       
                        "businessName": "Thompson Ventures LLC",
                        "taxId": "33-1000004",
                        "ownershipPercentage": 8.0,
                        "addressLine1": "Address line 1",
                        "addressLine2": "Address line 2",
                        "addressCity": "San Francisco",
                        "addressState": "CA",
                        "addressPostalCode": "94111",
                        "addressIsoCountryCode": "US",
                        "documentIds": [10014]
                    }
                ]
            }
        ]
    },
     "onBehalfAccountId": 412312 // see 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 beneficialOwnerShip 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)
individualOwnerShip	One of `individualOwnerShip` `or beneficialOwnerShip` is required	Array of objects, each representing information about one individual beneficial owner. Veem requires to have information on all owners with 25%+ ownership.
beneficialOwnerShip	One of `individualOwnerShip` or `beneficialOwnerShip` is required	Array of objects, each representing information about one business beneficial owner. Veem requires to have information on all owners with 25%+ ownership. Each object in this array may have an optional `individualOwnerShip` and/or `beneficialOwnerShip` array representing hierarchical ownership structure, in case there is an owner with 25%+ ownership.
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
documentIds	No (optional for individualOwnership and businessOwnership)	Array of Long values (document IDs from Account Document API response)	N/A
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

Request Validation

Beneficial Ownership Information request payload is validated using these rules:

Root ownership cap
Total ownership at the root level must be 100% or less.

Nested business levels
Business structure can only go up to 3 levels deep.

Control person
Each control person must have a title.

Unique taxId
Every tax ID must be unique with no duplicates.

Unique names
Root individuals and businesses must each have unique names.

How `documentIds` is Processed by Endpoint

POST /veem/v1.2/beneficial-ownership:
If documentIds is provided and non-empty for an owner, Veem first creates the owner, then links the specified document IDs.
If documentIds is null or empty, no documents are linked.
PATCH /veem/v1.2/beneficial-ownership/{id}:

Veem compares the owner’s currently linked documents with the provided documentIds:
- IDs in the request but not currently linked are added.
- IDs currently linked but missing from the request are removed.
- If documentIds is null, no changes are made to document links.
PUT /veem/v1.2/beneficial-ownership/{id}:
Follows the same compare-and-sync logic as PATCH.
If documentIds is null, no changes are made to document links.
GET /veem/v1.2/beneficial-ownership:
Returns the list of documentIds currently linked to each owner in the response.

For additional 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.

Response Payload

After a valid response is returned, expect a hierarchical payload structured with parent businesses and their nested child entities in the following format:

{
    "beneficialOwnerShip": {
        "hasAttestation": true,
        "individualOwnerShip": [
            {
                "id": 1279,
                "firstName": "Michael",
                "lastName": "Anderson",
                "ownershipPercentage": 1.0,
                "dateOfBirth": "12/31/1990",
                "citizenshipIsoCountryCode": "US",
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "taxId": "121-12-1212",
                "isControlPerson": true,
                "title": "CEO of the company",
                "email": "[email protected]",
                "documentIds": [10001, 10002]
            },
            {
                "id": 1280,
                "firstName": "Sarah",
                "lastName": "Mitchell",
                "ownershipPercentage": 2.0,
                "dateOfBirth": "12/31/1990",
                "citizenshipIsoCountryCode": "US",
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "taxId": "121-12-1213",
                "isControlPerson": false,
                "title": "CFO",
                "email": "[email protected]",
                "documentIds": [10003]
            }
        ],
        "businessOwnerShip": [
            {
                "id": 1273,
                "businessName": "Anderson Holdings LLC",
                "taxId": "33-1000001",
                "ownershipPercentage": 3.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10004]
            },
            {
                "id": 1274,
                "businessName": "Mitchell Investments Inc",
                "taxId": "33-1000002",
                "ownershipPercentage": 4.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10005]
            },
            {
                "id": 1275,
                "businessName": "Carter Group LLC",
                "taxId": "33-1000003",
                "ownershipPercentage": 5.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10006],
                "individualOwnerShip": [
                    {
                        "id": 1276,
                        "parentId": 1275,
                        "firstName": "David",
                        "lastName": "Thompson",
                        "ownershipPercentage": 6.0,
                        "dateOfBirth": "12/31/1990",
                        "citizenshipIsoCountryCode": "US",
                        "addressLine1": "Address line 1",
                        "addressLine2": "Address line 2",
                        "addressCity": "San Francisco",
                        "addressState": "CA",
                        "addressPostalCode": "94111",
                        "addressIsoCountryCode": "US",
                        "taxId": "121-12-1214",
                        "isControlPerson": false,
                        "title": "Director",
                        "email": "[email protected]",
                        "documentIds": [10007,10008] 
                    },
                    {
                        "id": 1277,
                        "parentId": 1275,
                        "firstName": "Emily",
                        "lastName": "Carter",
                        "ownershipPercentage": 7.0,
                        "dateOfBirth": "12/31/1990",
                        "citizenshipIsoCountryCode": "US",
                        "addressLine1": "Address line 1",
                        "addressLine2": "Address line 2",
                        "addressCity": "San Francisco",
                        "addressState": "CA",
                        "addressPostalCode": "94111",
                        "addressIsoCountryCode": "US",
                        "taxId": "121-12-1215",
                        "isControlPerson": false,
                        "title": "Manager",
                        "email": "[email protected]",
                        "documentIds": [10011]
                    }
                ],
                "businessOwnerShip": [
                    {
                        "id": 1278,
                        "parentId": 1275,
                        "businessName": "Thompson Ventures LLC",
                        "taxId": "33-1000004",
                        "ownershipPercentage": 8.0,
                        "addressLine1": "Address line 1",
                        "addressLine2": "Address line 2",
                        "addressCity": "San Francisco",
                        "addressState": "CA",
                        "addressPostalCode": "94111",
                        "addressIsoCountryCode": "US",
                        "documentIds": [10014]
                    }
                ]
            }
        ]
    }
}

Get Beneficial Ownership Information

Use this endpoint fetch the beneficial ownership information of an existing account.

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.

The response payload has the same structure as the POST endpoint response described in the Response Payload section above.

Edit Beneficial Ownership Information

Partial update of one existing BOI record, either individual or business.

PATCH https://sandbox-api.veem.com/veem/v1.2/beneficial-ownership/{id}

Request Parameters

Pass a valid id of an exiting beneficial owner as a path parameter to update the BOI record.

{
  "individualOwnerShip": {
      "firstName": "Jane",
      "ownershipPercentage": 25.5
  },
  "onBehalfAccountId": 412312
}

The response payload has the same structure as the PATCH endpoint response described in the Response Payload section above with the updated values.

{
    "beneficialOwnerShip": {
        "hasAttestation": true,
        "individualOwnerShip": [
            {
                "id": 1279,
                "firstName": "Jane",
                "lastName": "Anderson",
                "ownershipPercentage": 25.5,
                "dateOfBirth": "12/31/1990",
                "citizenshipIsoCountryCode": "US",
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "taxId": "121-12-1212",
                "isControlPerson": true,
                "title": "CEO of the company",
                "email": "[email protected]",
                "documentIds": [10001, 10002]
            },
            {
                "id": 1280,
                "firstName": "Sarah",
                "lastName": "Mitchell",
                "ownershipPercentage": 2.0,
                "dateOfBirth": "12/31/1990",
                "citizenshipIsoCountryCode": "US",
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "taxId": "121-12-1213",
                "isControlPerson": false,
                "title": "CFO",
                "email": "[email protected]",
                "documentIds": [10003]
            }
        ],
        "businessOwnerShip": [
            {
                "id": 1273,
                "businessName": "Anderson Holdings LLC",
                "taxId": "33-1000001",
                "ownershipPercentage": 3.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10004]
            },
            {
                "id": 1274,
                "businessName": "Mitchell Investments Inc",
                "taxId": "33-1000002",
                "ownershipPercentage": 4.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10005]
            },
            {
                "id": 1275,
                "businessName": "Carter Group LLC",
                "taxId": "33-1000003",
                "ownershipPercentage": 5.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10006],
                "individualOwnerShip": [
                    {
                        "id": 1276,
                        "parentId": 1275,
                        "firstName": "David",
                        "lastName": "Thompson",
                        "ownershipPercentage": 6.0,
                        "dateOfBirth": "12/31/1990",
                        "citizenshipIsoCountryCode": "US",
                        "addressLine1": "Address line 1",
                        "addressLine2": "Address line 2",
                        "addressCity": "San Francisco",
                        "addressState": "CA",
                        "addressPostalCode": "94111",
                        "addressIsoCountryCode": "US",
                        "taxId": "121-12-1214",
                        "isControlPerson": false,
                        "title": "Director",
                        "email": "[email protected]",
                        "documentIds": [10007,10008] 
                    },
                    {
                        "id": 1277,
                        "parentId": 1275,
                        "firstName": "Emily",
                        "lastName": "Carter",
                        "ownershipPercentage": 7.0,
                        "dateOfBirth": "12/31/1990",
                        "citizenshipIsoCountryCode": "US",
                        "addressLine1": "Address line 1",
                        "addressLine2": "Address line 2",
                        "addressCity": "San Francisco",
                        "addressState": "CA",
                        "addressPostalCode": "94111",
                        "addressIsoCountryCode": "US",
                        "taxId": "121-12-1215",
                        "isControlPerson": false,
                        "title": "Manager",
                        "email": "[email protected]",
                        "documentIds": [10011]
                    }
                ],
                "businessOwnerShip": [
                    {
                        "id": 1278,
                        "parentId": 1275,
                        "businessName": "Thompson Ventures LLC",
                        "taxId": "33-1000004",
                        "ownershipPercentage": 8.0,
                        "addressLine1": "Address line 1",
                        "addressLine2": "Address line 2",
                        "addressCity": "San Francisco",
                        "addressState": "CA",
                        "addressPostalCode": "94111",
                        "addressIsoCountryCode": "US",
                        "documentIds": [10014]
                    }
                ]
            }
        ]
    }
}

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

Replace Beneficial Ownership Information

Replaces one existing BOI record with the new BOI record, either individual or business. Replaces if record exists; creates new record if not, respecting the parentId.

PUT https://sandbox-api.veem.com/veem/v1.2/beneficial-ownership/{id}

Pass a valid id of an exiting beneficial owner as a path parameter to replace the BOI record.

{
  "businessOwnerShip": {
      "businessName": "Carter Group 2 LLC",
      "taxId": "30-1000004",
      "ownershipPercentage": 15.0,
      "addressLine1": "Address line 1",
      "addressLine2": "Address line 2",
      "addressCity": "San Francisco",
      "addressState": "CA",
      "addressPostalCode": "94111",
      "addressIsoCountryCode": "US",
      "documentIds": [10098],
  }
  "onBehalfAccountId": 412312
}

The response payload has the same structure as the POST endpoint response described in the Response Payload section above with replacement record if id already exists / new record if it doesn't exist.

{
    "beneficialOwnerShip": {
        "hasAttestation": true,
        "individualOwnerShip": [
            {
                "id": 1279,
                "firstName": "Jane",
                "lastName": "Anderson",
                "ownershipPercentage": 25.5,
                "dateOfBirth": "12/31/1990",
                "citizenshipIsoCountryCode": "US",
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "taxId": "121-12-1212",
                "isControlPerson": true,
                "title": "CEO of the company",
                "email": "[email protected]",
                "documentIds": [10001, 10002]
            },
            {
                "id": 1280,
                "firstName": "Sarah",
                "lastName": "Mitchell",
                "ownershipPercentage": 2.0,
                "dateOfBirth": "12/31/1990",
                "citizenshipIsoCountryCode": "US",
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "taxId": "121-12-1213",
                "isControlPerson": false,
                "title": "CFO",
                "email": "[email protected]",
                "documentIds": [10003]
            }
        ],
        "businessOwnerShip": [
            {
                "id": 1273,
                "businessName": "Anderson Holdings LLC",
                "taxId": "33-1000001",
                "ownershipPercentage": 3.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10004]
            },
            {
                "id": 1274,
                "businessName": "Mitchell Investments Inc",
                "taxId": "33-1000002",
                "ownershipPercentage": 4.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10005]
            },
            {
                "id": 1275,
                "businessName": "Carter Group 2 LLC",
                "taxId": "30-1000004",
                "ownershipPercentage": 15.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10098],
                "individualOwnerShip": [
                    {
                        "id": 1276,
                        "parentId": 1275,
                        "firstName": "David",
                        "lastName": "Thompson",
                        "ownershipPercentage": 6.0,
                        "dateOfBirth": "12/31/1990",
                        "citizenshipIsoCountryCode": "US",
                        "addressLine1": "Address line 1",
                        "addressLine2": "Address line 2",
                        "addressCity": "San Francisco",
                        "addressState": "CA",
                        "addressPostalCode": "94111",
                        "addressIsoCountryCode": "US",
                        "taxId": "121-12-1214",
                        "isControlPerson": false,
                        "title": "Director",
                        "email": "[email protected]",
                        "documentIds": [10007,10008] 
                    },
                    {
                        "id": 1277,
                        "parentId": 1275,
                        "firstName": "Emily",
                        "lastName": "Carter",
                        "ownershipPercentage": 7.0,
                        "dateOfBirth": "12/31/1990",
                        "citizenshipIsoCountryCode": "US",
                        "addressLine1": "Address line 1",
                        "addressLine2": "Address line 2",
                        "addressCity": "San Francisco",
                        "addressState": "CA",
                        "addressPostalCode": "94111",
                        "addressIsoCountryCode": "US",
                        "taxId": "121-12-1215",
                        "isControlPerson": false,
                        "title": "Manager",
                        "email": "[email protected]",
                        "documentIds": [10011]
                    }
                ],
                "businessOwnerShip": [
                    {
                        "id": 1278,
                        "parentId": 1275,
                        "businessName": "Thompson Ventures LLC",
                        "taxId": "33-1000004",
                        "ownershipPercentage": 8.0,
                        "addressLine1": "Address line 1",
                        "addressLine2": "Address line 2",
                        "addressCity": "San Francisco",
                        "addressState": "CA",
                        "addressPostalCode": "94111",
                        "addressIsoCountryCode": "US",
                        "documentIds": [10014]
                    }
                ]
            }
        ]
    }
}

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

Delete Beneficial Ownership Information

Deletes a single BOI record by id. In case of hierarchical ownership structure, if the record has child records, all child records are deleted as well.

DELETE https://sandbox-api.veem.com/veem/v1.2/beneficial-ownership/{id}

DELETE https://sandbox-api.veem.com/veem/v1.2/beneficial-ownership/{id}?onBehalfAccountId={accountId}

Pass a valid id of an exiting beneficial owner as a path parameter to delete the BOI record.

👍
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 query string parameter, this needs to be included in the request URL in case of partner making an API request on behalf of their customer. This is the customer Veem accountId.

The response payload has the same structure as the POST endpoint response described in the Response Payload section above without the deleted records.

{
    "beneficialOwnerShip": {
        "hasAttestation": true,
        "individualOwnerShip": [
            {
                "id": 1279,
                "firstName": "Jane",
                "lastName": "Anderson",
                "ownershipPercentage": 25.5,
                "dateOfBirth": "12/31/1990",
                "citizenshipIsoCountryCode": "US",
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "taxId": "121-12-1212",
                "isControlPerson": true,
                "title": "CEO of the company",
                "email": "[email protected]",
                "documentIds": [10001, 10002]
            },
            {
                "id": 1280,
                "firstName": "Sarah",
                "lastName": "Mitchell",
                "ownershipPercentage": 2.0,
                "dateOfBirth": "12/31/1990",
                "citizenshipIsoCountryCode": "US",
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "taxId": "121-12-1213",
                "isControlPerson": false,
                "title": "CFO",
                "email": "[email protected]",
                "documentIds": [10003]
            }
        ],
        "businessOwnerShip": [
            {
                "id": 1273,
                "businessName": "Anderson Holdings LLC",
                "taxId": "33-1000001",
                "ownershipPercentage": 3.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10004]
            },
            {
                "id": 1274,
                "businessName": "Mitchell Investments Inc",
                "taxId": "33-1000002",
                "ownershipPercentage": 4.0,
                "addressLine1": "Address line 1",
                "addressLine2": "Address line 2",
                "addressCity": "San Francisco",
                "addressState": "CA",
                "addressPostalCode": "94111",
                "addressIsoCountryCode": "US",
                "documentIds": [10005]
            }
        ]
    }
}

Headers

What's New: documentIds & hierarchical BOI payload

Request Payload

Request Parameters

Request Validation

How documentIds is Processed by Endpoint

Response Payload

Get Beneficial Ownership Information

Edit Beneficial Ownership Information

Request Parameters

Replace Beneficial Ownership Information

Delete Beneficial Ownership Information

What's New: `documentIds & hierarchical BOI payload`

How `documentIds` is Processed by Endpoint