# Beneficial Owners

## Create Beneficial Owner

> Create new beneficial owner

```json
{"openapi":"3.0.1","info":{"title":"Entities","version":"1.0"},"tags":[{"name":"Beneficial Owners","description":"Beneficial Owners"}],"servers":[{"url":"https://tvda-api.platform-test.tradevest.ai","description":"Test"},{"url":"https://tvda-api.platform-pretest.tradevest.ai","description":"Pretest"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://tvdcustomauthdomain.auth.eu-central-1.amazoncognito.com/oauth2/token","scopes":{}}}}},"schemas":{"CreateBeneficialOwnerResult":{"title":"CreateBeneficialOwnerResult","type":"object","properties":{"beneficialOwnerId":{"type":"string","format":"uuid","description":"Unique beneficial owner identification number in UUID format","readOnly":true}},"required":["beneficialOwnerId"]},"ErrorMessage":{"title":"ErrorMessage","type":"object","properties":{"message":{"type":"string"},"responseType":{"type":"string"},"validationString":{"minLength":1,"type":"string"},"requestId":{"type":"string"},"errorCode":{"type":"string","maxLength":255},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}},"required":["message","responseType","requestId"]},"ErrorDetails":{"title":"ErrorDetails","type":"object","properties":{"field":{"type":"string","maxLength":255},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailsExplanation"}}},"required":["field"]},"ErrorDetailsExplanation":{"title":"ErrorDetailsExplanation","type":"object","properties":{"code":{"type":"string","maxLength":255},"parameter":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"BeneficialOwnerData":{"title":"BeneficialOwnerData","type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":255,"pattern":"^\\S+( \\S+)*$","description":"All first names of the person according to the identification document"},"lastName":{"type":"string","minLength":1,"maxLength":255,"description":"Natural person last name"},"birthDay":{"type":"string","format":"date"},"birthPlace":{"type":"string","minLength":1,"description":"Location ","maxLength":255},"birthCountry":{"$ref":"#/components/schemas/CountryEnum"},"taxDetails":{"type":"array","items":{"$ref":"#/components/schemas/TaxDetail"}},"isUsNationality":{"type":"boolean","description":"FATCA - Question whether the customer is subject to US tax liability (nationality or other references due to a green card, registration address, etc.)."},"mainAddress":{"$ref":"#/components/schemas/Address"},"nationalities":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/CountryEnum"}},"uboRelationship":{"$ref":"#/components/schemas/UboRelationshipEnum"},"share":{"type":"number","multipleOf":0.01,"minimum":0,"exclusiveMinimum":true,"maximum":100},"votingRights":{"type":"number","multipleOf":0.01,"minimum":0,"exclusiveMinimum":true,"maximum":100},"fatcaControllingPerson":{"type":"boolean","description":"Indication of whether this person is a controlling person under FATCA. \\\n`TRUE` = if **fatcaClassification** = `PASSIVE_NFE`\n"}},"required":["firstName","lastName","birthDay","birthPlace","birthCountry","isUsNationality","nationalities","taxDetails","uboRelationship","share","votingRights"]},"CountryEnum":{"title":"CountryEnum","type":"string","description":"Country code in **ISO 3166-1 alpha-2** standard","enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","VG","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","HK","MO","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MK","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","AN","NC","NZ","NI","NE","NG","NU","NF","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VI","WF","EH","YE","ZM","ZW","XK"]},"TaxDetail":{"title":"TaxDetail","type":"object","properties":{"taxId":{"type":"string","minLength":1,"maxLength":255},"taxResidency":{"$ref":"#/components/schemas/CountryEnum"},"noTinConfirmation":{"description":"Indicates that the customer does not have a Tax Identification Number (TIN), which should only be used in exceptional cases where no TIN exists. If this field is set to true, the customer must provide supporting document (docType: TIN_NA_CONFIRMATION) confirming that no TIN is available.","type":"boolean","default":false}},"required":["taxResidency"]},"Address":{"title":"Address","type":"object","description":"Address","properties":{"street":{"type":"string","minLength":1,"maxLength":255},"streetNumber":{"type":"string","minLength":1,"maxLength":20},"city":{"type":"string","minLength":1,"maxLength":255},"zip":{"type":"string","minLength":3,"maxLength":10},"state":{"type":"string","minLength":1,"maxLength":35},"country":{"$ref":"#/components/schemas/CountryEnum"},"additionalInfo":{"type":"string","minLength":1}},"required":["street","streetNumber","city","zip","country"]},"UboRelationshipEnum":{"title":"UboRelationshipEnum","type":"string","description":"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:\n- `DIRECTLY_HOLDING_25` - a person directly holds shares in the capital or voting rights of a company.\n- `INDIRECTLY_HOLDING_25`- a person indirectly holds shares in the capital or voting rights through intermediary entities or trust arrangements.\n- `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.\n","enum":["DIRECTLY_HOLDING_25","INDIRECTLY_HOLDING_25","DOMINANT_INFLUENCE_OVER_SHARE_CAPITAL"]}}},"paths":{"/entities/{legalEntityId}/beneficial-owners":{"post":{"summary":"Create Beneficial Owner","operationId":"create-beneficial-owner","description":"Create new beneficial owner","tags":["Beneficial Owners"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBeneficialOwnerResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeneficialOwnerData"}}}}}}}}
```

## Get Beneficial Owners

> Get beneficial owners

```json
{"openapi":"3.0.1","info":{"title":"Entities","version":"1.0"},"tags":[{"name":"Beneficial Owners","description":"Beneficial Owners"}],"servers":[{"url":"https://tvda-api.platform-test.tradevest.ai","description":"Test"},{"url":"https://tvda-api.platform-pretest.tradevest.ai","description":"Pretest"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://tvdcustomauthdomain.auth.eu-central-1.amazoncognito.com/oauth2/token","scopes":{}}}}},"schemas":{"BeneficialOwners":{"title":"BeneficialOwners","type":"object","properties":{"data":{"type":"array","description":"Array of beneficial owners","items":{"$ref":"#/components/schemas/BeneficialOwner"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]},"BeneficialOwner":{"title":"BeneficialOwner","type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":255,"pattern":"^\\S+( \\S+)*$","description":"All first names of the person according to the identification document"},"lastName":{"type":"string","minLength":1,"maxLength":255,"description":"Natural person last name"},"birthDay":{"type":"string","format":"date"},"birthPlace":{"type":"string","minLength":1,"description":"Location ","maxLength":255},"birthCountry":{"$ref":"#/components/schemas/CountryEnum"},"taxDetails":{"type":"array","items":{"$ref":"#/components/schemas/TaxDetail"}},"isUsNationality":{"type":"boolean","description":"FATCA - Question whether the customer is subject to US tax liability (nationality or other references due to a green card, registration address, etc.)."},"mainAddress":{"$ref":"#/components/schemas/Address"},"nationalities":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/CountryEnum"}},"uboRelationship":{"$ref":"#/components/schemas/UboRelationshipEnum"},"share":{"type":"number","multipleOf":0.01,"minimum":0,"exclusiveMinimum":true,"maximum":100},"votingRights":{"type":"number","multipleOf":0.01,"minimum":0,"exclusiveMinimum":true,"maximum":100},"fatcaControllingPerson":{"type":"boolean","description":"Indication of whether this person is a controlling person under FATCA. \\\n`TRUE` = if **fatcaClassification** = `PASSIVE_NFE`\n"},"deathDay":{"type":"string","format":"date"},"beneficialOwnerId":{"type":"string","format":"uuid","readOnly":true},"globalId":{"type":"string","minLength":12,"maxLength":12,"description":"Global ID of the beneficial owner"},"status":{"$ref":"#/components/schemas/BeneficialOwnerStatusEnum"},"boType":{"$ref":"#/components/schemas/BeneficialOwnerTypeEnum"},"isPep":{"type":"boolean","description":"Indication of whether the person is a politically exposed person."},"isPepRelated":{"type":"boolean","description":"Indication of whether the person is directly related to a politically exposed person."},"isSanction":{"type":"boolean","description":"Indication of whether the person is on sanction list."},"riskLevel":{"$ref":"#/components/schemas/RiskLevelEnum"},"createdOn":{"type":"string","format":"date-time","readOnly":true},"modifiedOn":{"type":"string","format":"date-time","readOnly":true},"verifiedOn":{"type":"string","format":"date-time","description":"The date on which the Beneficial Owner was verified","readOnly":true}},"required":["firstName","lastName","birthDay","birthPlace","birthCountry","isUsNationality","nationalities","taxDetails","share","votingRights","beneficialOwnerId","globalId","status","boType","createdOn","modifiedOn"]},"CountryEnum":{"title":"CountryEnum","type":"string","description":"Country code in **ISO 3166-1 alpha-2** standard","enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","VG","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","HK","MO","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MK","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","AN","NC","NZ","NI","NE","NG","NU","NF","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VI","WF","EH","YE","ZM","ZW","XK"]},"TaxDetail":{"title":"TaxDetail","type":"object","properties":{"taxId":{"type":"string","minLength":1,"maxLength":255},"taxResidency":{"$ref":"#/components/schemas/CountryEnum"},"noTinConfirmation":{"description":"Indicates that the customer does not have a Tax Identification Number (TIN), which should only be used in exceptional cases where no TIN exists. If this field is set to true, the customer must provide supporting document (docType: TIN_NA_CONFIRMATION) confirming that no TIN is available.","type":"boolean","default":false}},"required":["taxResidency"]},"Address":{"title":"Address","type":"object","description":"Address","properties":{"street":{"type":"string","minLength":1,"maxLength":255},"streetNumber":{"type":"string","minLength":1,"maxLength":20},"city":{"type":"string","minLength":1,"maxLength":255},"zip":{"type":"string","minLength":3,"maxLength":10},"state":{"type":"string","minLength":1,"maxLength":35},"country":{"$ref":"#/components/schemas/CountryEnum"},"additionalInfo":{"type":"string","minLength":1}},"required":["street","streetNumber","city","zip","country"]},"UboRelationshipEnum":{"title":"UboRelationshipEnum","type":"string","description":"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:\n- `DIRECTLY_HOLDING_25` - a person directly holds shares in the capital or voting rights of a company.\n- `INDIRECTLY_HOLDING_25`- a person indirectly holds shares in the capital or voting rights through intermediary entities or trust arrangements.\n- `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.\n","enum":["DIRECTLY_HOLDING_25","INDIRECTLY_HOLDING_25","DOMINANT_INFLUENCE_OVER_SHARE_CAPITAL"]},"BeneficialOwnerStatusEnum":{"title":"BeneficialOwnerStatusEnum","type":"string","enum":["CREATED","ACTIVE","INACTIVE","RECEIVED","INVALID","REJECTED","REVIEW","PENDING","SUSPENDED_COMPLIANCE"]},"BeneficialOwnerTypeEnum":{"title":"BeneficialOwnerTypeEnum","type":"string","description":"Indication of the type of beneficial owner:\\\nIn the context of legal entity customers:\\\n`REAL_UBO_25` = person who holds more than 25% of the company shares\\\n`FICTIVE_UBO` = Legal Representative, if no person exists who holds more than 25% of the company shares\n","enum":["FICTIVE_UBO","REAL_UBO_25"]},"RiskLevelEnum":{"title":"RiskLevelEnum","type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"Pagination":{"title":"Pagination","type":"object","properties":{"cursor":{"type":"string","description":"String value used for pagination, which should be set in next page request."},"limit":{"type":"integer","description":"Maximum number of returned items"}},"required":["cursor","limit"]},"ErrorMessage":{"title":"ErrorMessage","type":"object","properties":{"message":{"type":"string"},"responseType":{"type":"string"},"validationString":{"minLength":1,"type":"string"},"requestId":{"type":"string"},"errorCode":{"type":"string","maxLength":255},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}},"required":["message","responseType","requestId"]},"ErrorDetails":{"title":"ErrorDetails","type":"object","properties":{"field":{"type":"string","maxLength":255},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailsExplanation"}}},"required":["field"]},"ErrorDetailsExplanation":{"title":"ErrorDetailsExplanation","type":"object","properties":{"code":{"type":"string","maxLength":255},"parameter":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"parameters":{"cursor":{"schema":{"type":"string"},"in":"query","name":"cursor","description":"String value used for pagination"},"limit":{"schema":{"type":"integer","default":20,"minimum":1},"in":"query","name":"limit","description":"Maximum number of items to return","required":true},"beneficialOwnerStatus":{"schema":{"$ref":"#/components/schemas/BeneficialOwnerStatusEnum"},"in":"query","name":"beneficialOwnerStatus","description":"Beneficial owner status Filter"},"startDate":{"schema":{"type":"string","format":"date-time"},"name":"startDate","in":"query","description":"Beginning of the range"},"endDate":{"schema":{"type":"string","format":"date-time"},"in":"query","name":"endDate","description":"End of the range"}}},"paths":{"/entities/{legalEntityId}/beneficial-owners":{"get":{"summary":"Get Beneficial Owners","operationId":"get-beneficial-owners","description":"Get beneficial owners","tags":["Beneficial Owners"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeneficialOwners"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/beneficialOwnerStatus"},{"$ref":"#/components/parameters/startDate"},{"$ref":"#/components/parameters/endDate"}]}}}}
```

## Get Beneficial Owner

> Get beneficial owner

```json
{"openapi":"3.0.1","info":{"title":"Entities","version":"1.0"},"tags":[{"name":"Beneficial Owners","description":"Beneficial Owners"}],"servers":[{"url":"https://tvda-api.platform-test.tradevest.ai","description":"Test"},{"url":"https://tvda-api.platform-pretest.tradevest.ai","description":"Pretest"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://tvdcustomauthdomain.auth.eu-central-1.amazoncognito.com/oauth2/token","scopes":{}}}}},"schemas":{"BeneficialOwner":{"title":"BeneficialOwner","type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":255,"pattern":"^\\S+( \\S+)*$","description":"All first names of the person according to the identification document"},"lastName":{"type":"string","minLength":1,"maxLength":255,"description":"Natural person last name"},"birthDay":{"type":"string","format":"date"},"birthPlace":{"type":"string","minLength":1,"description":"Location ","maxLength":255},"birthCountry":{"$ref":"#/components/schemas/CountryEnum"},"taxDetails":{"type":"array","items":{"$ref":"#/components/schemas/TaxDetail"}},"isUsNationality":{"type":"boolean","description":"FATCA - Question whether the customer is subject to US tax liability (nationality or other references due to a green card, registration address, etc.)."},"mainAddress":{"$ref":"#/components/schemas/Address"},"nationalities":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/CountryEnum"}},"uboRelationship":{"$ref":"#/components/schemas/UboRelationshipEnum"},"share":{"type":"number","multipleOf":0.01,"minimum":0,"exclusiveMinimum":true,"maximum":100},"votingRights":{"type":"number","multipleOf":0.01,"minimum":0,"exclusiveMinimum":true,"maximum":100},"fatcaControllingPerson":{"type":"boolean","description":"Indication of whether this person is a controlling person under FATCA. \\\n`TRUE` = if **fatcaClassification** = `PASSIVE_NFE`\n"},"deathDay":{"type":"string","format":"date"},"beneficialOwnerId":{"type":"string","format":"uuid","readOnly":true},"globalId":{"type":"string","minLength":12,"maxLength":12,"description":"Global ID of the beneficial owner"},"status":{"$ref":"#/components/schemas/BeneficialOwnerStatusEnum"},"boType":{"$ref":"#/components/schemas/BeneficialOwnerTypeEnum"},"isPep":{"type":"boolean","description":"Indication of whether the person is a politically exposed person."},"isPepRelated":{"type":"boolean","description":"Indication of whether the person is directly related to a politically exposed person."},"isSanction":{"type":"boolean","description":"Indication of whether the person is on sanction list."},"riskLevel":{"$ref":"#/components/schemas/RiskLevelEnum"},"createdOn":{"type":"string","format":"date-time","readOnly":true},"modifiedOn":{"type":"string","format":"date-time","readOnly":true},"verifiedOn":{"type":"string","format":"date-time","description":"The date on which the Beneficial Owner was verified","readOnly":true}},"required":["firstName","lastName","birthDay","birthPlace","birthCountry","isUsNationality","nationalities","taxDetails","share","votingRights","beneficialOwnerId","globalId","status","boType","createdOn","modifiedOn"]},"CountryEnum":{"title":"CountryEnum","type":"string","description":"Country code in **ISO 3166-1 alpha-2** standard","enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","VG","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","HK","MO","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MK","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","AN","NC","NZ","NI","NE","NG","NU","NF","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VI","WF","EH","YE","ZM","ZW","XK"]},"TaxDetail":{"title":"TaxDetail","type":"object","properties":{"taxId":{"type":"string","minLength":1,"maxLength":255},"taxResidency":{"$ref":"#/components/schemas/CountryEnum"},"noTinConfirmation":{"description":"Indicates that the customer does not have a Tax Identification Number (TIN), which should only be used in exceptional cases where no TIN exists. If this field is set to true, the customer must provide supporting document (docType: TIN_NA_CONFIRMATION) confirming that no TIN is available.","type":"boolean","default":false}},"required":["taxResidency"]},"Address":{"title":"Address","type":"object","description":"Address","properties":{"street":{"type":"string","minLength":1,"maxLength":255},"streetNumber":{"type":"string","minLength":1,"maxLength":20},"city":{"type":"string","minLength":1,"maxLength":255},"zip":{"type":"string","minLength":3,"maxLength":10},"state":{"type":"string","minLength":1,"maxLength":35},"country":{"$ref":"#/components/schemas/CountryEnum"},"additionalInfo":{"type":"string","minLength":1}},"required":["street","streetNumber","city","zip","country"]},"UboRelationshipEnum":{"title":"UboRelationshipEnum","type":"string","description":"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:\n- `DIRECTLY_HOLDING_25` - a person directly holds shares in the capital or voting rights of a company.\n- `INDIRECTLY_HOLDING_25`- a person indirectly holds shares in the capital or voting rights through intermediary entities or trust arrangements.\n- `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.\n","enum":["DIRECTLY_HOLDING_25","INDIRECTLY_HOLDING_25","DOMINANT_INFLUENCE_OVER_SHARE_CAPITAL"]},"BeneficialOwnerStatusEnum":{"title":"BeneficialOwnerStatusEnum","type":"string","enum":["CREATED","ACTIVE","INACTIVE","RECEIVED","INVALID","REJECTED","REVIEW","PENDING","SUSPENDED_COMPLIANCE"]},"BeneficialOwnerTypeEnum":{"title":"BeneficialOwnerTypeEnum","type":"string","description":"Indication of the type of beneficial owner:\\\nIn the context of legal entity customers:\\\n`REAL_UBO_25` = person who holds more than 25% of the company shares\\\n`FICTIVE_UBO` = Legal Representative, if no person exists who holds more than 25% of the company shares\n","enum":["FICTIVE_UBO","REAL_UBO_25"]},"RiskLevelEnum":{"title":"RiskLevelEnum","type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"ErrorMessage":{"title":"ErrorMessage","type":"object","properties":{"message":{"type":"string"},"responseType":{"type":"string"},"validationString":{"minLength":1,"type":"string"},"requestId":{"type":"string"},"errorCode":{"type":"string","maxLength":255},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}},"required":["message","responseType","requestId"]},"ErrorDetails":{"title":"ErrorDetails","type":"object","properties":{"field":{"type":"string","maxLength":255},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailsExplanation"}}},"required":["field"]},"ErrorDetailsExplanation":{"title":"ErrorDetailsExplanation","type":"object","properties":{"code":{"type":"string","maxLength":255},"parameter":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"paths":{"/entities/beneficial-owners/{beneficialOwnerId}":{"get":{"summary":"Get Beneficial Owner","operationId":"get-beneficial-owner","description":"Get beneficial owner","tags":["Beneficial Owners"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeneficialOwner"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}}}}
```

## Update Beneficial Owner

> Update beneficial owner

```json
{"openapi":"3.0.1","info":{"title":"Entities","version":"1.0"},"tags":[{"name":"Beneficial Owners","description":"Beneficial Owners"}],"servers":[{"url":"https://tvda-api.platform-test.tradevest.ai","description":"Test"},{"url":"https://tvda-api.platform-pretest.tradevest.ai","description":"Pretest"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://tvdcustomauthdomain.auth.eu-central-1.amazoncognito.com/oauth2/token","scopes":{}}}}},"parameters":{"requestorId":{"schema":{"type":"string","format":"uuid"},"name":"Requestor-ID","in":"header","required":true,"description":"Unique requestor identification in UUID format"}},"schemas":{"ErrorMessage":{"title":"ErrorMessage","type":"object","properties":{"message":{"type":"string"},"responseType":{"type":"string"},"validationString":{"minLength":1,"type":"string"},"requestId":{"type":"string"},"errorCode":{"type":"string","maxLength":255},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}},"required":["message","responseType","requestId"]},"ErrorDetails":{"title":"ErrorDetails","type":"object","properties":{"field":{"type":"string","maxLength":255},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailsExplanation"}}},"required":["field"]},"ErrorDetailsExplanation":{"title":"ErrorDetailsExplanation","type":"object","properties":{"code":{"type":"string","maxLength":255},"parameter":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"BeneficialOwnerUpdate":{"title":"BeneficialOwnerUpdate","type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":255,"pattern":"^\\S+( \\S+)*$","description":"All first names of the person according to the identification document"},"lastName":{"type":"string","minLength":1,"maxLength":255,"description":"Natural person last name"},"birthDay":{"type":"string","format":"date"},"birthPlace":{"type":"string","minLength":1,"description":"Location ","maxLength":255},"birthCountry":{"$ref":"#/components/schemas/CountryEnum"},"taxDetails":{"type":"array","items":{"$ref":"#/components/schemas/TaxDetail"}},"isUsNationality":{"type":"boolean","description":"FATCA - Question whether the customer is subject to US tax liability (nationality or other references due to a green card, registration address, etc.)."},"mainAddress":{"$ref":"#/components/schemas/Address"},"nationalities":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/CountryEnum"}},"uboRelationship":{"$ref":"#/components/schemas/UboRelationshipEnum"},"share":{"type":"number","multipleOf":0.01,"minimum":0,"exclusiveMinimum":true,"maximum":100},"votingRights":{"type":"number","multipleOf":0.01,"minimum":0,"exclusiveMinimum":true,"maximum":100},"fatcaControllingPerson":{"type":"boolean","description":"Indication of whether this person is a controlling person under FATCA. \\\n`TRUE` = if **fatcaClassification** = `PASSIVE_NFE`\n"}}},"CountryEnum":{"title":"CountryEnum","type":"string","description":"Country code in **ISO 3166-1 alpha-2** standard","enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","VG","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","HK","MO","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MK","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","AN","NC","NZ","NI","NE","NG","NU","NF","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VI","WF","EH","YE","ZM","ZW","XK"]},"TaxDetail":{"title":"TaxDetail","type":"object","properties":{"taxId":{"type":"string","minLength":1,"maxLength":255},"taxResidency":{"$ref":"#/components/schemas/CountryEnum"},"noTinConfirmation":{"description":"Indicates that the customer does not have a Tax Identification Number (TIN), which should only be used in exceptional cases where no TIN exists. If this field is set to true, the customer must provide supporting document (docType: TIN_NA_CONFIRMATION) confirming that no TIN is available.","type":"boolean","default":false}},"required":["taxResidency"]},"Address":{"title":"Address","type":"object","description":"Address","properties":{"street":{"type":"string","minLength":1,"maxLength":255},"streetNumber":{"type":"string","minLength":1,"maxLength":20},"city":{"type":"string","minLength":1,"maxLength":255},"zip":{"type":"string","minLength":3,"maxLength":10},"state":{"type":"string","minLength":1,"maxLength":35},"country":{"$ref":"#/components/schemas/CountryEnum"},"additionalInfo":{"type":"string","minLength":1}},"required":["street","streetNumber","city","zip","country"]},"UboRelationshipEnum":{"title":"UboRelationshipEnum","type":"string","description":"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:\n- `DIRECTLY_HOLDING_25` - a person directly holds shares in the capital or voting rights of a company.\n- `INDIRECTLY_HOLDING_25`- a person indirectly holds shares in the capital or voting rights through intermediary entities or trust arrangements.\n- `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.\n","enum":["DIRECTLY_HOLDING_25","INDIRECTLY_HOLDING_25","DOMINANT_INFLUENCE_OVER_SHARE_CAPITAL"]}}},"paths":{"/entities/beneficial-owners/{beneficialOwnerId}":{"patch":{"summary":"Update Beneficial Owner","operationId":"update-beneficial-owner","description":"Update beneficial owner","tags":["Beneficial Owners"],"parameters":[{"$ref":"#/components/parameters/requestorId"}],"responses":{"202":{"description":"Accepted","content":{}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeneficialOwnerUpdate"}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tradevest.ai/api-reference/entities/beneficial-owners.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.