Beneficial Owners

Create Beneficial Owner

post

/entities/{legalEntityId}/beneficial-owners

Create new beneficial owner

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

legalEntityIdstring · uuidRequired

Legal Entity ID

Body

firstNamestring · min: 1 · max: 255Required

All first names of the person according to the identification document

Pattern: ^\S+( \S+)*$

lastNamestring · min: 1 · max: 255Required

Natural person last name

birthDaystring · dateRequired

birthPlacestring · min: 1 · max: 255Required

Location

birthCountrystring · enumRequired

Country code in ISO 3166-1 alpha-2 standard

Possible values:

isUsNationalitybooleanRequired

FATCA - Question whether the customer is subject to US tax liability (nationality or other references due to a green card, registration address, etc.).

uboRelationshipstring · enumRequired

This enum is used to specify the type of relationship a person has with a company, particularly in terms of shareholding or control.The possible values are:

DIRECTLY_HOLDING_25 - a person directly holds shares in the capital or voting rights of a company.
INDIRECTLY_HOLDING_25- a person indirectly holds shares in the capital or voting rights through intermediary entities or trust arrangements.
DOMINANT_INFLUENCE_OVER_SHARE_CAPITAL - a person exercises control over the company in any other way, such as through voting agreements, special rights, or trust relationships, even without (or with only minor) direct or indirect shareholdings.

Possible values:

sharenumber · max: 100Required

votingRightsnumber · max: 100Required

fatcaControllingPersonbooleanOptional

Indication of whether this person is a controlling person under FATCA.
TRUE = if fatcaClassification = PASSIVE_NFE

Responses

200

application/json

beneficialOwnerIdstring · uuidRead-onlyRequired

Unique beneficial owner identification number in UUID format

400

Bad Request

application/json

409

Conflict

application/json

post

/entities/{legalEntityId}/beneficial-owners

POST /entities/{legalEntityId}/beneficial-owners HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 458

{
  "firstName": "text",
  "lastName": "text",
  "birthDay": "2026-03-17",
  "birthPlace": "text",
  "birthCountry": "AF",
  "taxDetails": [
    {
      "taxId": "text",
      "taxResidency": "AF",
      "noTinConfirmation": false
    }
  ],
  "isUsNationality": true,
  "mainAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "state": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "nationalities": [
    "AF"
  ],
  "uboRelationship": "DIRECTLY_HOLDING_25",
  "share": 1,
  "votingRights": 1,
  "fatcaControllingPerson": true
}

{
  "beneficialOwnerId": "123e4567-e89b-12d3-a456-426614174000"
}

Get Beneficial Owners

get

/entities/{legalEntityId}/beneficial-owners

Get beneficial owners

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

legalEntityIdstring · uuidRequired

Legal Entity ID

Query parameters

cursorstringOptional

String value used for pagination

limitinteger · min: 1Required

Maximum number of items to return

Default: 20

beneficialOwnerStatusstring · enumOptional

Beneficial owner status Filter

Possible values:

startDatestring · date-timeOptional

Beginning of the range

endDatestring · date-timeOptional

End of the range

Responses

200

application/json

400

Bad Request

application/json

get

/entities/{legalEntityId}/beneficial-owners

GET /entities/{legalEntityId}/beneficial-owners?limit=20 HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "data": [
    {
      "firstName": "text",
      "lastName": "text",
      "birthDay": "2026-03-17",
      "birthPlace": "text",
      "birthCountry": "AF",
      "taxDetails": [
        {
          "taxId": "text",
          "taxResidency": "AF",
          "noTinConfirmation": false
        }
      ],
      "isUsNationality": true,
      "mainAddress": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "state": "text",
        "country": "AF",
        "additionalInfo": "text"
      },
      "nationalities": [
        "AF"
      ],
      "uboRelationship": "DIRECTLY_HOLDING_25",
      "share": 1,
      "votingRights": 1,
      "fatcaControllingPerson": true,
      "deathDay": "2026-03-17",
      "beneficialOwnerId": "123e4567-e89b-12d3-a456-426614174000",
      "globalId": "text",
      "status": "CREATED",
      "boType": "FICTIVE_UBO",
      "isPep": true,
      "isPepRelated": true,
      "isSanction": true,
      "riskLevel": "LOW",
      "createdOn": "2026-03-17T22:18:43.469Z",
      "modifiedOn": "2026-03-17T22:18:43.469Z",
      "verifiedOn": "2026-03-17T22:18:43.469Z"
    }
  ],
  "pagination": {
    "cursor": "text",
    "limit": 1
  }
}

Get Beneficial Owner

get

/entities/beneficial-owners/{beneficialOwnerId}

Get beneficial owner

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

beneficialOwnerIdstring · uuidRequired

Beneficial Owner ID

Responses

200

application/json

firstNamestring · min: 1 · max: 255Required

All first names of the person according to the identification document

Pattern: ^\S+( \S+)*$

lastNamestring · min: 1 · max: 255Required

Natural person last name

birthDaystring · dateRequired

birthPlacestring · min: 1 · max: 255Required

Location

birthCountrystring · enumRequired

Country code in ISO 3166-1 alpha-2 standard

Possible values:

isUsNationalitybooleanRequired

FATCA - Question whether the customer is subject to US tax liability (nationality or other references due to a green card, registration address, etc.).

uboRelationshipstring · enumOptional

This enum is used to specify the type of relationship a person has with a company, particularly in terms of shareholding or control.The possible values are:

DIRECTLY_HOLDING_25 - a person directly holds shares in the capital or voting rights of a company.
INDIRECTLY_HOLDING_25- a person indirectly holds shares in the capital or voting rights through intermediary entities or trust arrangements.
DOMINANT_INFLUENCE_OVER_SHARE_CAPITAL - a person exercises control over the company in any other way, such as through voting agreements, special rights, or trust relationships, even without (or with only minor) direct or indirect shareholdings.

Possible values:

sharenumber · max: 100Required

votingRightsnumber · max: 100Required

fatcaControllingPersonbooleanOptional

Indication of whether this person is a controlling person under FATCA.
TRUE = if fatcaClassification = PASSIVE_NFE

deathDaystring · dateOptional

beneficialOwnerIdstring · uuidRead-onlyRequired

globalIdstring · min: 12 · max: 12Required

Global ID of the beneficial owner

statusstring · enumRequiredPossible values:

boTypestring · enumRequired

Indication of the type of beneficial owner:
In the context of legal entity customers:
REAL_UBO_25 = person who holds more than 25% of the company shares
FICTIVE_UBO = Legal Representative, if no person exists who holds more than 25% of the company shares

Possible values:

isPepbooleanOptional

Indication of whether the person is a politically exposed person.

isPepRelatedbooleanOptional

Indication of whether the person is directly related to a politically exposed person.

isSanctionbooleanOptional

Indication of whether the person is on sanction list.

riskLevelstring · enumOptionalPossible values:

createdOnstring · date-timeRead-onlyRequired

modifiedOnstring · date-timeRead-onlyRequired

verifiedOnstring · date-timeRead-onlyOptional

The date on which the Beneficial Owner was verified

400

Bad Request

application/json

404

Not Found

application/json

get

/entities/beneficial-owners/{beneficialOwnerId}

GET /entities/beneficial-owners/{beneficialOwnerId} HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "firstName": "text",
  "lastName": "text",
  "birthDay": "2026-03-17",
  "birthPlace": "text",
  "birthCountry": "AF",
  "taxDetails": [
    {
      "taxId": "text",
      "taxResidency": "AF",
      "noTinConfirmation": false
    }
  ],
  "isUsNationality": true,
  "mainAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "state": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "nationalities": [
    "AF"
  ],
  "uboRelationship": "DIRECTLY_HOLDING_25",
  "share": 1,
  "votingRights": 1,
  "fatcaControllingPerson": true,
  "deathDay": "2026-03-17",
  "beneficialOwnerId": "123e4567-e89b-12d3-a456-426614174000",
  "globalId": "text",
  "status": "CREATED",
  "boType": "FICTIVE_UBO",
  "isPep": true,
  "isPepRelated": true,
  "isSanction": true,
  "riskLevel": "LOW",
  "createdOn": "2026-03-17T22:18:43.469Z",
  "modifiedOn": "2026-03-17T22:18:43.469Z",
  "verifiedOn": "2026-03-17T22:18:43.469Z"
}

Update Beneficial Owner

patch

/entities/beneficial-owners/{beneficialOwnerId}

Update beneficial owner

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

beneficialOwnerIdstring · uuidRequired

Beneficial Owner ID

Header parameters

Requestor-IDstring · uuidRequired

Unique requestor identification in UUID format

Body

firstNamestring · min: 1 · max: 255Optional

All first names of the person according to the identification document

Pattern: ^\S+( \S+)*$

lastNamestring · min: 1 · max: 255Optional

Natural person last name

birthDaystring · dateOptional

birthPlacestring · min: 1 · max: 255Optional

Location

birthCountrystring · enumOptional

Country code in ISO 3166-1 alpha-2 standard

Possible values:

isUsNationalitybooleanOptional

FATCA - Question whether the customer is subject to US tax liability (nationality or other references due to a green card, registration address, etc.).

uboRelationshipstring · enumOptional

This enum is used to specify the type of relationship a person has with a company, particularly in terms of shareholding or control.The possible values are:

DIRECTLY_HOLDING_25 - a person directly holds shares in the capital or voting rights of a company.
INDIRECTLY_HOLDING_25- a person indirectly holds shares in the capital or voting rights through intermediary entities or trust arrangements.
DOMINANT_INFLUENCE_OVER_SHARE_CAPITAL - a person exercises control over the company in any other way, such as through voting agreements, special rights, or trust relationships, even without (or with only minor) direct or indirect shareholdings.

Possible values:

sharenumber · max: 100Optional

votingRightsnumber · max: 100Optional

fatcaControllingPersonbooleanOptional

Indication of whether this person is a controlling person under FATCA.
TRUE = if fatcaClassification = PASSIVE_NFE

Responses

202

Accepted

400

Bad Request

application/json

patch

/entities/beneficial-owners/{beneficialOwnerId}

PATCH /entities/beneficial-owners/{beneficialOwnerId} HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Requestor-ID: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 458

{
  "firstName": "text",
  "lastName": "text",
  "birthDay": "2026-03-17",
  "birthPlace": "text",
  "birthCountry": "AF",
  "taxDetails": [
    {
      "taxId": "text",
      "taxResidency": "AF",
      "noTinConfirmation": false
    }
  ],
  "isUsNationality": true,
  "mainAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "state": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "nationalities": [
    "AF"
  ],
  "uboRelationship": "DIRECTLY_HOLDING_25",
  "share": 1,
  "votingRights": 1,
  "fatcaControllingPerson": true
}

No content

Last updated 8 months ago

hashtagCreate Beneficial Owner

hashtagGet Beneficial Owners

hashtagGet Beneficial Owner

hashtagUpdate Beneficial Owner

Create Beneficial Owner

Get Beneficial Owners

Get Beneficial Owner

Update Beneficial Owner