Beneficial Owners

Create Beneficial Owner

post

Create new beneficial owner

Authorizations
Path parameters
legalEntityIdstring · uuidRequired

Legal Entity ID

Header parameters
Requestor-IDstring · uuidRequired

Unique requestor identification in UUID format

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

OK

application/json
post
POST /entities/{legalEntityId}/beneficial-owners 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: 443

{
  "firstName": "text",
  "lastName": "text",
  "birthDay": "2025-08-29",
  "birthPlace": "text",
  "birthCountry": "AF",
  "taxDetails": [
    {
      "taxId": "text",
      "taxResidency": "AF",
      "noTinConfirmation": false
    }
  ],
  "isUsNationality": true,
  "mainAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "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

Get beneficial owners

Authorizations
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

OK

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

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

Get Beneficial Owner

get

Get beneficial owner

Authorizations
Path parameters
beneficialOwnerIdstring · uuidRequired

Beneficial Owner ID

Responses
200

OK

application/json
get
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": "2025-08-29",
  "birthPlace": "text",
  "birthCountry": "AF",
  "taxDetails": [
    {
      "taxId": "text",
      "taxResidency": "AF",
      "noTinConfirmation": false
    }
  ],
  "isUsNationality": true,
  "mainAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "nationalities": [
    "AF"
  ],
  "uboRelationship": "DIRECTLY_HOLDING_25",
  "share": 1,
  "votingRights": 1,
  "fatcaControllingPerson": true,
  "deathDay": "2025-08-29",
  "beneficialOwnerId": "123e4567-e89b-12d3-a456-426614174000",
  "globalId": "text",
  "status": "CREATED",
  "boType": "FICTIVE_UBO",
  "isPep": true,
  "isPepRelated": true,
  "isSanction": true,
  "riskLevel": "LOW",
  "createdOn": "2025-08-29T14:40:48.593Z",
  "modifiedOn": "2025-08-29T14:40:48.593Z",
  "verifiedOn": "2025-08-29T14:40:48.593Z"
}

Update Beneficial Owner

patch

Update beneficial owner

Authorizations
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

patch
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: 443

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

Last updated