Sandbox login
Guides

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.

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

📌

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.

{
  "ownershipType": "individual",
  "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.

{
  "ownershipType": "business",
  "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]
            }
        ]
    }
}

Updated 3 days ago