# Legal Entities ## Create Legal Entity > Create new legal entity ```json {"openapi":"3.0.1","info":{"title":"Entities","version":"1.0"},"tags":[{"name":"Legal Entities","description":"Legal Entities"}],"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":{"CreateLegalEntityResult":{"title":"CreateLegalEntityResult","type":"object","properties":{"legalEntityId":{"type":"string","format":"uuid","description":"Unique legal entity identification number in UUID format","readOnly":true}},"required":["legalEntityId"]},"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"]},"CreateLegalEntityData":{"type":"object","properties":{"legalEntityIdentifier":{"type":"string","minLength":20,"maxLength":20,"description":"Unique global identifier for legal entities participating in financial transactions","pattern":"^\\d{4}[0]{2}[A-Z\\d]{12}\\d{2}$"},"legalName":{"type":"string","description":"The legal name of the entity","pattern":"^[^,]*$","maxLength":255},"legalForm":{"$ref":"#/components/schemas/LegalFormEnum"},"naceSectors":{"type":"array","description":"Specification of the sector in which the company is mainly economically active. The information should be provided according to the groups of the NACE codes (Sections A-V, Groups 01.11 - 99.00) without subclasses. (Level 4)","items":{"$ref":"#/components/schemas/LegalEntityNaceSector"}},"registerCountry":{"$ref":"#/components/schemas/CountryEnum"},"registerNumber":{"type":"string","minLength":1,"maxLength":255,"description":"Number at which the company is registered"},"registerCourt":{"type":"string","minLength":1,"maxLength":255,"description":"An administrative court in which the company was registered"},"registerCourtZipCode":{"type":"string","minLength":1,"maxLength":255,"description":"An administrative court zip code in which the company was registered"},"registeredOn":{"type":"string","format":"date","description":"The date on which the entity was registered"},"foundedOn":{"type":"string","format":"date","description":"The date on which the entity was founded"},"vatId":{"type":"string","minLength":11,"maxLength":11,"description":"The value-added tax id of the legal entity"},"purpose":{"type":"string","minLength":1,"maxLength":255,"description":"The purpose of the legal entity"},"mainAddress":{"$ref":"#/components/schemas/Address"},"correspondenceAddress":{"$ref":"#/components/schemas/Address"},"invoiceAddress":{"$ref":"#/components/schemas/Address"},"contact":{"$ref":"#/components/schemas/Contact"},"searchId":{"type":"string","format":"uuid"},"taxNumber":{"type":"string","minLength":1,"maxLength":255,"description":"The tax number of the legal entity"},"isListed":{"type":"boolean","description":"Determine whether the shares of that company are on the list (or board) of stock that are officially traded on a stock exchange"},"listedAt":{"type":"string","minLength":1,"maxLength":255,"description":"Determine where the shares of that company are officially traded on a stock exchange. Only when entity is listed"},"averageProfit":{"type":"number","multipleOf":0.01,"description":"Average profit for the year (after tax)"},"averageRevenue":{"type":"number","multipleOf":0.01,"description":"Average revenue for the year"},"liquidAssets":{"type":"number","multipleOf":0.01,"description":"Liquid assets"},"lastAnnualFinancialStatement":{"type":"string","format":"date","description":"Last annual financial statement date"},"fatcaCrsDeclaration":{"$ref":"#/components/schemas/FatcaCrsDeclaration"},"externalId":{"type":"string","minLength":1,"description":"External Id in partner's system. This value has to be unique"}},"title":"CreateLegalEntityData","required":["legalName","legalForm","registerCountry","naceSectors","registerNumber","registerCourt","foundedOn","mainAddress","contact","taxNumber","fatcaCrsDeclaration"]},"LegalFormEnum":{"title":"LegalFormEnum","type":"string","description":"LegalFormEnum","enum":["LIMITED_LIABILITY_COMPANY","PUBLIC_LIMITED_COMPANY","PRIVATE_CORPORATION","FOUNDATION","ASSOCIATION","REGISTERED_BUSINESSMAN","REGISTERED_COMPANY","LIMITED_PARTNERSHIP","GENERAL_PARTNERSHIP","LIMITED_LIABILITY_COMPANY_AND_LIMITED_PARTNERSHIP","PARTNERSHIP","SINGLE_PARTNERSHIP","OTHER","UNACCEPTABLE"]},"LegalEntityNaceSector":{"title":"LegalEntityNaceSector","type":"object","properties":{"section":{"type":"string"},"code":{"type":"string","minLength":2},"description":{"type":"string","maxLength":255}},"required":["code"]},"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"]},"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"]},"Contact":{"title":"Contact","type":"object","properties":{"phone":{"type":"string","description":"Mobile telephone number","minLength":3,"maxLength":20,"pattern":"^[\\+\\-\\(\\)\\d ]{3,20}$"},"email":{"type":"string","description":"E-mail address","maxLength":255,"pattern":"^[a-zA-Z0-9.!#$%&'*+\\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$"},"fax":{"type":"string","description":"Fax number","minLength":3,"maxLength":20,"pattern":"^[\\+\\-\\(\\)\\d ]{3,20}$"},"website":{"type":"string","description":"website address","maxLength":320}},"required":["phone","email"]},"FatcaCrsDeclaration":{"title":"FatcaCrsDeclaration","type":"object","properties":{"isForeignTaxResidency":{"type":"boolean","description":"Indication of whether the legal entity is resident for tax purposes outside Germany"},"isSanctionedCountries":{"type":"boolean","description":"Indication of whether the company conducts business activities with parties from a country that is on a sanctions list of Germany, the EU, or the USA or has been categorized as a high-risk country by one of the aforementioned, e.g. Iran, Ukraine, Russia or Belarus"},"fatcaClassification":{"$ref":"#/components/schemas/FatcaClassificationEnum"},"activeNfeType":{"$ref":"#/components/schemas/ActiveNfeTypeEnum"}},"required":["isForeignTaxResidency","isSanctionedCountries","fatcaClassification"]},"FatcaClassificationEnum":{"title":"FatcaClassificationEnum","type":"string","enum":["ACTIVE_NFE","PASSIVE_NFE"],"description":"FATCA/CRS classification of the legal entity. Active NFE = Entity that derives less than half of its total income from passive income and is not a Financial Institution. Possible passive income would be, for example, interest, dividends, license fees or rents - if not generated as part of an active business - as well as gains from the sale of assets that were used to generate passive income. Passive NFE = the Entity derives more than half of its total income from passive income and is not a Financial Institution."},"ActiveNfeTypeEnum":{"title":"ActiveNfeTypeEnum","type":"string","enum":["LE_BY_INCOME_ASSETS","NON_PROFIT_ORGANISATION","OTHER"],"description":"Its required only if fatcaClassification = ACTIVE_NFE"}}},"paths":{"/entities/legal-entities":{"post":{"summary":"Create Legal Entity","operationId":"create-legal-entity","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLegalEntityResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"description":"Create new legal entity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLegalEntityData"}}}},"tags":["Legal Entities"]}}}} ``` ## Get Legal Entities > Get legal entities ```json {"openapi":"3.0.1","info":{"title":"Entities","version":"1.0"},"tags":[{"name":"Legal Entities","description":"Legal Entities"}],"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":{"LegalEntities":{"title":"LegalEntities","type":"object","properties":{"data":{"type":"array","description":"Array of legal entities","items":{"$ref":"#/components/schemas/LegalEntity"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]},"LegalEntity":{"type":"object","properties":{"legalEntityId":{"type":"string","format":"uuid","description":"Unique legal entity identification number in UUID format"},"globalId":{"type":"string","minLength":12,"maxLength":12},"lei":{"$ref":"#/components/schemas/Lei"},"createdOn":{"type":"string","format":"date-time","description":"The date on which the natural person was created"},"modifiedOn":{"type":"string","format":"date-time","description":"The date on which the natural person was modified the last time"},"verifiedOn":{"type":"string","format":"date-time","description":"The date on which the natural person was verified"},"isSanction":{"type":"boolean","description":"Indication of whether the person is on sanction list."},"riskLevel":{"$ref":"#/components/schemas/RiskLevelEnum"},"legalEntityStatus":{"$ref":"#/components/schemas/LegalEntityStatusEnum"},"legalName":{"type":"string","description":"The legal name of the entity","pattern":"^[^,]*$","maxLength":255},"legalForm":{"$ref":"#/components/schemas/LegalFormEnum"},"naceSectors":{"type":"array","description":"Specification of the sector in which the company is mainly economically active. The information should be provided according to the groups of the NACE codes (Sections A-V, Groups 01.11 - 99.00) without subclasses. (Level 4)","items":{"$ref":"#/components/schemas/LegalEntityNaceSector"}},"registerCountry":{"$ref":"#/components/schemas/CountryEnum"},"registerNumber":{"type":"string","minLength":1,"maxLength":255,"description":"Number at which the company is registered"},"registerCourt":{"type":"string","minLength":1,"maxLength":255,"description":"An administrative court in which the company was registered"},"registerCourtZipCode":{"type":"string","minLength":1,"maxLength":255,"description":"An administrative court zip code in which the company was registered"},"registeredOn":{"type":"string","format":"date","description":"The date on which the entity was registered"},"foundedOn":{"type":"string","format":"date","description":"The date on which the entity was founded"},"vatId":{"type":"string","minLength":11,"maxLength":11,"description":"The value-added tax id of the legal entity"},"purpose":{"type":"string","minLength":1,"maxLength":255,"description":"The purpose of the legal entity"},"mainAddress":{"$ref":"#/components/schemas/Address"},"correspondenceAddress":{"$ref":"#/components/schemas/Address"},"invoiceAddress":{"$ref":"#/components/schemas/Address"},"contact":{"$ref":"#/components/schemas/Contact"},"searchId":{"type":"string","format":"uuid"},"taxNumber":{"type":"string","minLength":1,"maxLength":255,"description":"The tax number of the legal entity"},"isListed":{"type":"boolean","description":"Determine whether the shares of that company are on the list (or board) of stock that are officially traded on a stock exchange"},"listedAt":{"type":"string","minLength":1,"maxLength":255,"description":"Determine where the shares of that company are officially traded on a stock exchange. Only when entity is listed"},"averageProfit":{"type":"number","multipleOf":0.01,"description":"Average profit for the year (after tax)"},"averageRevenue":{"type":"number","multipleOf":0.01,"description":"Average revenue for the year"},"liquidAssets":{"type":"number","multipleOf":0.01,"description":"Liquid assets"},"lastAnnualFinancialStatement":{"type":"string","format":"date","description":"Last annual financial statement date"},"fatcaCrsDeclaration":{"$ref":"#/components/schemas/FatcaCrsDeclaration"},"externalId":{"type":"string","minLength":1,"description":"External Id in partner's system. This value has to be unique"}},"required":["contact","createdOn","fatcaCrsDeclaration","foundedOn","globalId","legalEntityId","legalEntityStatus","legalForm","legalName","mainAddress","modifiedOn","naceSectors","registerCountry","registerCourt","registerNumber","taxNumber"],"title":"LegalEntity"},"Lei":{"title":"Lei","properties":{"legalEntityIdentifier":{"type":"string","minLength":20,"maxLength":20,"description":"Unique global identifier for legal entities participating in financial transactions","pattern":"^\\d{4}[0]{2}[A-Z\\d]{12}\\d{2}$"},"leiStatus":{"$ref":"#/components/schemas/LeiStatusEnum"},"leiValidUntil":{"type":"string","format":"date"}},"required":["legalEntityIdentifier"]},"LeiStatusEnum":{"title":"LeiStatusEnum","type":"string","enum":["ISSUED","LAPSED","MERGED","RETIRED","PENDING_TRANSFER","PENDING_ARCHIVAL","DUPLICATE","ANNULLED"]},"RiskLevelEnum":{"title":"RiskLevelEnum","type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"LegalEntityStatusEnum":{"title":"LegalEntityStatusEnum","type":"string","enum":["CREATED","REVIEW","REJECTED","INACTIVE","PENDING","ACTIVE","SUSPENDED","ARCHIVED","RECEIVED","INVALID","SUSPENDED_COMPLIANCE"]},"LegalFormEnum":{"title":"LegalFormEnum","type":"string","description":"LegalFormEnum","enum":["LIMITED_LIABILITY_COMPANY","PUBLIC_LIMITED_COMPANY","PRIVATE_CORPORATION","FOUNDATION","ASSOCIATION","REGISTERED_BUSINESSMAN","REGISTERED_COMPANY","LIMITED_PARTNERSHIP","GENERAL_PARTNERSHIP","LIMITED_LIABILITY_COMPANY_AND_LIMITED_PARTNERSHIP","PARTNERSHIP","SINGLE_PARTNERSHIP","OTHER","UNACCEPTABLE"]},"LegalEntityNaceSector":{"title":"LegalEntityNaceSector","type":"object","properties":{"section":{"type":"string"},"code":{"type":"string","minLength":2},"description":{"type":"string","maxLength":255}},"required":["code"]},"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"]},"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"]},"Contact":{"title":"Contact","type":"object","properties":{"phone":{"type":"string","description":"Mobile telephone number","minLength":3,"maxLength":20,"pattern":"^[\\+\\-\\(\\)\\d ]{3,20}$"},"email":{"type":"string","description":"E-mail address","maxLength":255,"pattern":"^[a-zA-Z0-9.!#$%&'*+\\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$"},"fax":{"type":"string","description":"Fax number","minLength":3,"maxLength":20,"pattern":"^[\\+\\-\\(\\)\\d ]{3,20}$"},"website":{"type":"string","description":"website address","maxLength":320}},"required":["phone","email"]},"FatcaCrsDeclaration":{"title":"FatcaCrsDeclaration","type":"object","properties":{"isForeignTaxResidency":{"type":"boolean","description":"Indication of whether the legal entity is resident for tax purposes outside Germany"},"isSanctionedCountries":{"type":"boolean","description":"Indication of whether the company conducts business activities with parties from a country that is on a sanctions list of Germany, the EU, or the USA or has been categorized as a high-risk country by one of the aforementioned, e.g. Iran, Ukraine, Russia or Belarus"},"fatcaClassification":{"$ref":"#/components/schemas/FatcaClassificationEnum"},"activeNfeType":{"$ref":"#/components/schemas/ActiveNfeTypeEnum"}},"required":["isForeignTaxResidency","isSanctionedCountries","fatcaClassification"]},"FatcaClassificationEnum":{"title":"FatcaClassificationEnum","type":"string","enum":["ACTIVE_NFE","PASSIVE_NFE"],"description":"FATCA/CRS classification of the legal entity. Active NFE = Entity that derives less than half of its total income from passive income and is not a Financial Institution. Possible passive income would be, for example, interest, dividends, license fees or rents - if not generated as part of an active business - as well as gains from the sale of assets that were used to generate passive income. Passive NFE = the Entity derives more than half of its total income from passive income and is not a Financial Institution."},"ActiveNfeTypeEnum":{"title":"ActiveNfeTypeEnum","type":"string","enum":["LE_BY_INCOME_ASSETS","NON_PROFIT_ORGANISATION","OTHER"],"description":"Its required only if fatcaClassification = ACTIVE_NFE"},"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},"legalEntityStatus":{"schema":{"$ref":"#/components/schemas/LegalEntityStatusEnum"},"in":"query","name":"legalEntityStatus","description":"Legal entity status Filter"}}},"paths":{"/entities/legal-entities":{"get":{"summary":"Get Legal Entities","tags":["Legal Entities"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalEntities"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"operationId":"get-legal-entities","description":"Get legal entities","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/legalEntityStatus"}]}}}} ``` ## Get Legal Entity > Get legal entity ```json {"openapi":"3.0.1","info":{"title":"Entities","version":"1.0"},"tags":[{"name":"Legal Entities","description":"Legal Entities"}],"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":{"LegalEntity":{"type":"object","properties":{"legalEntityId":{"type":"string","format":"uuid","description":"Unique legal entity identification number in UUID format"},"globalId":{"type":"string","minLength":12,"maxLength":12},"lei":{"$ref":"#/components/schemas/Lei"},"createdOn":{"type":"string","format":"date-time","description":"The date on which the natural person was created"},"modifiedOn":{"type":"string","format":"date-time","description":"The date on which the natural person was modified the last time"},"verifiedOn":{"type":"string","format":"date-time","description":"The date on which the natural person was verified"},"isSanction":{"type":"boolean","description":"Indication of whether the person is on sanction list."},"riskLevel":{"$ref":"#/components/schemas/RiskLevelEnum"},"legalEntityStatus":{"$ref":"#/components/schemas/LegalEntityStatusEnum"},"legalName":{"type":"string","description":"The legal name of the entity","pattern":"^[^,]*$","maxLength":255},"legalForm":{"$ref":"#/components/schemas/LegalFormEnum"},"naceSectors":{"type":"array","description":"Specification of the sector in which the company is mainly economically active. The information should be provided according to the groups of the NACE codes (Sections A-V, Groups 01.11 - 99.00) without subclasses. (Level 4)","items":{"$ref":"#/components/schemas/LegalEntityNaceSector"}},"registerCountry":{"$ref":"#/components/schemas/CountryEnum"},"registerNumber":{"type":"string","minLength":1,"maxLength":255,"description":"Number at which the company is registered"},"registerCourt":{"type":"string","minLength":1,"maxLength":255,"description":"An administrative court in which the company was registered"},"registerCourtZipCode":{"type":"string","minLength":1,"maxLength":255,"description":"An administrative court zip code in which the company was registered"},"registeredOn":{"type":"string","format":"date","description":"The date on which the entity was registered"},"foundedOn":{"type":"string","format":"date","description":"The date on which the entity was founded"},"vatId":{"type":"string","minLength":11,"maxLength":11,"description":"The value-added tax id of the legal entity"},"purpose":{"type":"string","minLength":1,"maxLength":255,"description":"The purpose of the legal entity"},"mainAddress":{"$ref":"#/components/schemas/Address"},"correspondenceAddress":{"$ref":"#/components/schemas/Address"},"invoiceAddress":{"$ref":"#/components/schemas/Address"},"contact":{"$ref":"#/components/schemas/Contact"},"searchId":{"type":"string","format":"uuid"},"taxNumber":{"type":"string","minLength":1,"maxLength":255,"description":"The tax number of the legal entity"},"isListed":{"type":"boolean","description":"Determine whether the shares of that company are on the list (or board) of stock that are officially traded on a stock exchange"},"listedAt":{"type":"string","minLength":1,"maxLength":255,"description":"Determine where the shares of that company are officially traded on a stock exchange. Only when entity is listed"},"averageProfit":{"type":"number","multipleOf":0.01,"description":"Average profit for the year (after tax)"},"averageRevenue":{"type":"number","multipleOf":0.01,"description":"Average revenue for the year"},"liquidAssets":{"type":"number","multipleOf":0.01,"description":"Liquid assets"},"lastAnnualFinancialStatement":{"type":"string","format":"date","description":"Last annual financial statement date"},"fatcaCrsDeclaration":{"$ref":"#/components/schemas/FatcaCrsDeclaration"},"externalId":{"type":"string","minLength":1,"description":"External Id in partner's system. This value has to be unique"}},"required":["contact","createdOn","fatcaCrsDeclaration","foundedOn","globalId","legalEntityId","legalEntityStatus","legalForm","legalName","mainAddress","modifiedOn","naceSectors","registerCountry","registerCourt","registerNumber","taxNumber"],"title":"LegalEntity"},"Lei":{"title":"Lei","properties":{"legalEntityIdentifier":{"type":"string","minLength":20,"maxLength":20,"description":"Unique global identifier for legal entities participating in financial transactions","pattern":"^\\d{4}[0]{2}[A-Z\\d]{12}\\d{2}$"},"leiStatus":{"$ref":"#/components/schemas/LeiStatusEnum"},"leiValidUntil":{"type":"string","format":"date"}},"required":["legalEntityIdentifier"]},"LeiStatusEnum":{"title":"LeiStatusEnum","type":"string","enum":["ISSUED","LAPSED","MERGED","RETIRED","PENDING_TRANSFER","PENDING_ARCHIVAL","DUPLICATE","ANNULLED"]},"RiskLevelEnum":{"title":"RiskLevelEnum","type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"LegalEntityStatusEnum":{"title":"LegalEntityStatusEnum","type":"string","enum":["CREATED","REVIEW","REJECTED","INACTIVE","PENDING","ACTIVE","SUSPENDED","ARCHIVED","RECEIVED","INVALID","SUSPENDED_COMPLIANCE"]},"LegalFormEnum":{"title":"LegalFormEnum","type":"string","description":"LegalFormEnum","enum":["LIMITED_LIABILITY_COMPANY","PUBLIC_LIMITED_COMPANY","PRIVATE_CORPORATION","FOUNDATION","ASSOCIATION","REGISTERED_BUSINESSMAN","REGISTERED_COMPANY","LIMITED_PARTNERSHIP","GENERAL_PARTNERSHIP","LIMITED_LIABILITY_COMPANY_AND_LIMITED_PARTNERSHIP","PARTNERSHIP","SINGLE_PARTNERSHIP","OTHER","UNACCEPTABLE"]},"LegalEntityNaceSector":{"title":"LegalEntityNaceSector","type":"object","properties":{"section":{"type":"string"},"code":{"type":"string","minLength":2},"description":{"type":"string","maxLength":255}},"required":["code"]},"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"]},"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"]},"Contact":{"title":"Contact","type":"object","properties":{"phone":{"type":"string","description":"Mobile telephone number","minLength":3,"maxLength":20,"pattern":"^[\\+\\-\\(\\)\\d ]{3,20}$"},"email":{"type":"string","description":"E-mail address","maxLength":255,"pattern":"^[a-zA-Z0-9.!#$%&'*+\\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$"},"fax":{"type":"string","description":"Fax number","minLength":3,"maxLength":20,"pattern":"^[\\+\\-\\(\\)\\d ]{3,20}$"},"website":{"type":"string","description":"website address","maxLength":320}},"required":["phone","email"]},"FatcaCrsDeclaration":{"title":"FatcaCrsDeclaration","type":"object","properties":{"isForeignTaxResidency":{"type":"boolean","description":"Indication of whether the legal entity is resident for tax purposes outside Germany"},"isSanctionedCountries":{"type":"boolean","description":"Indication of whether the company conducts business activities with parties from a country that is on a sanctions list of Germany, the EU, or the USA or has been categorized as a high-risk country by one of the aforementioned, e.g. Iran, Ukraine, Russia or Belarus"},"fatcaClassification":{"$ref":"#/components/schemas/FatcaClassificationEnum"},"activeNfeType":{"$ref":"#/components/schemas/ActiveNfeTypeEnum"}},"required":["isForeignTaxResidency","isSanctionedCountries","fatcaClassification"]},"FatcaClassificationEnum":{"title":"FatcaClassificationEnum","type":"string","enum":["ACTIVE_NFE","PASSIVE_NFE"],"description":"FATCA/CRS classification of the legal entity. Active NFE = Entity that derives less than half of its total income from passive income and is not a Financial Institution. Possible passive income would be, for example, interest, dividends, license fees or rents - if not generated as part of an active business - as well as gains from the sale of assets that were used to generate passive income. Passive NFE = the Entity derives more than half of its total income from passive income and is not a Financial Institution."},"ActiveNfeTypeEnum":{"title":"ActiveNfeTypeEnum","type":"string","enum":["LE_BY_INCOME_ASSETS","NON_PROFIT_ORGANISATION","OTHER"],"description":"Its required only if fatcaClassification = ACTIVE_NFE"},"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/legal-entities/{legalEntityId}":{"get":{"summary":"Get Legal Entity","tags":["Legal Entities"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalEntity"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"operationId":"get-legal-entity","description":"Get legal entity"}}}} ``` ## Update Legal Entity > Update legal entity ```json {"openapi":"3.0.1","info":{"title":"Entities","version":"1.0"},"tags":[{"name":"Legal Entities","description":"Legal Entities"}],"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"]},"LegalEntityUpdate":{"title":"LegalEntityUpdate","type":"object","properties":{"legalEntityUpdateData":{"$ref":"#/components/schemas/LegalEntityUpdateData"},"documentIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Document IDs in UUID format for parameters where a document upload is required. When updating any of legalName, legalForm, mainAddress, correspondenceAddress, invoiceAddress, registerCountry, registerNumber, registerCourt, registerCourtZipCode, registeredOn — proper document must be included.\n"}},"required":["legalEntityUpdateData"]},"LegalEntityUpdateData":{"title":"LegalEntityUpdateData","type":"object","properties":{"legalName":{"type":"string","description":"The legal name of the entity","maxLength":255},"legalForm":{"$ref":"#/components/schemas/LegalFormEnum"},"naceSectors":{"type":"array","description":"Specification of the sector in which the company is mainly economically active. The information should be provided according to the groups of the NACE codes (Sections A-V, Groups 01.11 - 99.00) without subclasses. (Level 4)","items":{"$ref":"#/components/schemas/LegalEntityNaceSector"}},"taxNumber":{"type":"string","minLength":1,"maxLength":255,"description":"The tax number of the legal entity"},"vatId":{"type":"string","minLength":11,"maxLength":11,"description":"The value-added tax id of the legal entity"},"isListed":{"type":"boolean","description":"Determine whether the shares of that company are on the list (or board) of stock that are officially traded on a stock exchange"},"listedAt":{"type":"string","minLength":1,"maxLength":255,"description":"Determine where the shares of that company are officially traded on a stock exchange. Only when entity is listed"},"legalEntityIdentifier":{"type":"string","minLength":20,"maxLength":20,"description":"Unique global identifier for legal entities participating in financial transactions","pattern":"^\\d{4}[0]{2}[A-Z\\d]{12}\\d{2}$"},"purpose":{"type":"string","minLength":1,"maxLength":255,"description":"The purpose of the legal entity"},"fatcaCrsDeclaration":{"$ref":"#/components/schemas/FatcaCrsDeclaration"},"averageProfit":{"type":"number","multipleOf":0.01,"description":"Average profit for the year (after tax)"},"averageRevenue":{"type":"number","multipleOf":0.01,"description":"Average revenue for the year"},"liquidAssets":{"type":"number","multipleOf":0.01,"description":"Liquid assets"},"lastAnnualFinancialStatement":{"type":"string","format":"date","description":"Last annual financial statement date"},"mainAddress":{"$ref":"#/components/schemas/Address"},"correspondenceAddress":{"$ref":"#/components/schemas/Address"},"invoiceAddress":{"$ref":"#/components/schemas/Address"},"registerCountry":{"$ref":"#/components/schemas/CountryEnum"},"registerNumber":{"type":"string","minLength":1,"maxLength":255,"description":"Number at which the company is registered"},"registerCourt":{"type":"string","minLength":1,"maxLength":255,"description":"An administrative court in which the company was registered"},"registerCourtZipCode":{"type":"string","minLength":1,"maxLength":255,"description":"An administrative court zip code in which the company was registered"},"registeredOn":{"type":"string","format":"date","description":"The date on which the entity was registered"},"contact":{"$ref":"#/components/schemas/Contact"},"externalId":{"type":"string","minLength":1,"description":"External Id in partner's system. This value has to be unique"}}},"LegalFormEnum":{"title":"LegalFormEnum","type":"string","description":"LegalFormEnum","enum":["LIMITED_LIABILITY_COMPANY","PUBLIC_LIMITED_COMPANY","PRIVATE_CORPORATION","FOUNDATION","ASSOCIATION","REGISTERED_BUSINESSMAN","REGISTERED_COMPANY","LIMITED_PARTNERSHIP","GENERAL_PARTNERSHIP","LIMITED_LIABILITY_COMPANY_AND_LIMITED_PARTNERSHIP","PARTNERSHIP","SINGLE_PARTNERSHIP","OTHER","UNACCEPTABLE"]},"LegalEntityNaceSector":{"title":"LegalEntityNaceSector","type":"object","properties":{"section":{"type":"string"},"code":{"type":"string","minLength":2},"description":{"type":"string","maxLength":255}},"required":["code"]},"FatcaCrsDeclaration":{"title":"FatcaCrsDeclaration","type":"object","properties":{"isForeignTaxResidency":{"type":"boolean","description":"Indication of whether the legal entity is resident for tax purposes outside Germany"},"isSanctionedCountries":{"type":"boolean","description":"Indication of whether the company conducts business activities with parties from a country that is on a sanctions list of Germany, the EU, or the USA or has been categorized as a high-risk country by one of the aforementioned, e.g. Iran, Ukraine, Russia or Belarus"},"fatcaClassification":{"$ref":"#/components/schemas/FatcaClassificationEnum"},"activeNfeType":{"$ref":"#/components/schemas/ActiveNfeTypeEnum"}},"required":["isForeignTaxResidency","isSanctionedCountries","fatcaClassification"]},"FatcaClassificationEnum":{"title":"FatcaClassificationEnum","type":"string","enum":["ACTIVE_NFE","PASSIVE_NFE"],"description":"FATCA/CRS classification of the legal entity. Active NFE = Entity that derives less than half of its total income from passive income and is not a Financial Institution. Possible passive income would be, for example, interest, dividends, license fees or rents - if not generated as part of an active business - as well as gains from the sale of assets that were used to generate passive income. Passive NFE = the Entity derives more than half of its total income from passive income and is not a Financial Institution."},"ActiveNfeTypeEnum":{"title":"ActiveNfeTypeEnum","type":"string","enum":["LE_BY_INCOME_ASSETS","NON_PROFIT_ORGANISATION","OTHER"],"description":"Its required only if fatcaClassification = ACTIVE_NFE"},"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"]},"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"]},"Contact":{"title":"Contact","type":"object","properties":{"phone":{"type":"string","description":"Mobile telephone number","minLength":3,"maxLength":20,"pattern":"^[\\+\\-\\(\\)\\d ]{3,20}$"},"email":{"type":"string","description":"E-mail address","maxLength":255,"pattern":"^[a-zA-Z0-9.!#$%&'*+\\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$"},"fax":{"type":"string","description":"Fax number","minLength":3,"maxLength":20,"pattern":"^[\\+\\-\\(\\)\\d ]{3,20}$"},"website":{"type":"string","description":"website address","maxLength":320}},"required":["phone","email"]}}},"paths":{"/entities/legal-entities/{legalEntityId}":{"patch":{"summary":"Update Legal Entity","operationId":"update-legal-entity","parameters":[{"$ref":"#/components/parameters/requestorId"}],"responses":{"202":{"description":"Accepted"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"description":"Update legal entity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalEntityUpdate"}}}},"tags":["Legal Entities"]}}}} ``` ## Search Legal Entities > This operation requests a fuzzy search for a legal entity by the company name and the country in which it was registered. The name does not have to be complete and will return a list of companies that most closely match the search criteria. ```json {"openapi":"3.0.1","info":{"title":"Entities","version":"1.0"},"tags":[{"name":"Legal Entities","description":"Legal Entities"}],"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":{"legalName":{"schema":{"type":"string"},"in":"query","required":true,"description":"Legal name","name":"legalName"},"providerId":{"schema":{"type":"string"},"in":"query","description":"provider id","name":"providerId"}},"schemas":{"LegalEntitySearchLiteResult":{"type":"object","required":["address"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"businessOfficeType":{"type":"string","enum":["Branch","Headquarters","Unknown"]},"legalForm":{"type":"string"},"name":{"type":"string"},"providerId":{"type":"string"},"registerCourt":{"type":"string"},"registrationNumber":{"type":"string"}}},"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"]},"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"]},"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/vendor/legal-entities":{"get":{"summary":"Search Legal Entities","operationId":"search-legal-entities","description":"This operation requests a fuzzy search for a legal entity by the company name and the country in which it was registered. The name does not have to be complete and will return a list of companies that most closely match the search criteria.","tags":["Legal Entities"],"parameters":[{"$ref":"#/components/parameters/legalName"},{"$ref":"#/components/parameters/providerId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LegalEntitySearchLiteResult"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}}}} ``` ## Prepare Legal Entity > This operation requests preparation of data for a legal entity by its full name and the country in which was registered. As a result of the operation, a unique search id is returned, which can be used on other endpoints. The outcome of the matching will be presented for review on the \*\*Get Legal Entity By Search Id\*\* endpoint. The result can be discarded and all company details can be filled in manually or the result can be accepted and the company can be created on the \*\*Create Legal Entity Customer - search based\*\* endpoint. This endpoint will, among others, automatically pull company documents from public registers. As this might not always succeed, it is recommended to call this endpoint multiple times in case of failure. ```json {"openapi":"3.0.1","info":{"title":"Entities","version":"1.0"},"tags":[{"name":"Legal Entities","description":"Legal Entities"}],"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":{"PrepareLegalEntityResult":{"title":"PrepareLegalEntityResult","type":"object","properties":{"searchId":{"type":"string","format":"uuid","description":"Unique identification number in UUID format","readOnly":true}},"required":["searchId"]},"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"]},"PrepareLegalEntityData":{"title":"PrepareLegalEntityData","type":"object","properties":{"companyName":{"type":"string","description":"The name of the company","minLength":1,"maxLength":255},"providerId":{"type":"string","description":"The provider id of the company","minLength":1,"maxLength":255}},"required":["companyName"]}}},"paths":{"/entities/vendor/legal-entities":{"post":{"summary":"Prepare Legal Entity","operationId":"prepare-legal-entity","description":"This operation requests preparation of data for a legal entity by its full name and the country in which was registered. As a result of the operation, a unique search id is returned, which can be used on other endpoints. The outcome of the matching will be presented for review on the **Get Legal Entity By Search Id** endpoint. The result can be discarded and all company details can be filled in manually or the result can be accepted and the company can be created on the **Create Legal Entity Customer - search based** endpoint. This endpoint will, among others, automatically pull company documents from public registers. As this might not always succeed, it is recommended to call this endpoint multiple times in case of failure.","tags":["Legal Entities"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareLegalEntityResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareLegalEntityData"}}}}}}}} ``` ## Get Legal Entity Search Result > Get legal entity search result ```json {"openapi":"3.0.1","info":{"title":"Entities","version":"1.0"},"tags":[{"name":"Legal Entities","description":"Legal Entities"}],"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":{"LegalEntityCompoundSearchResult":{"title":"LegalEntityCompoundSearchResult","type":"object","properties":{"search":{"$ref":"#/components/schemas/LegalEntitySearchDetails"},"legalEntity":{"$ref":"#/components/schemas/LegalEntitySearchResult"},"legalRepresentatives":{"type":"array","items":{"$ref":"#/components/schemas/LegalRepresentativeSearchResult"}},"beneficialOwners":{"type":"array","items":{"$ref":"#/components/schemas/BeneficialOwnerSearchResult"}},"documents":{"type":"array","items":{"$ref":"#/components/schemas/LegalEntityDocumentSearchResult"}}},"required":["search"]},"LegalEntitySearchDetails":{"title":"LegalEntitySearchDetails","type":"object","properties":{"searchId":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/LegalEntitySearchStatusEnum"},"documentTypes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentTypeEnum"}}},"required":["searchId","status"]},"LegalEntitySearchStatusEnum":{"title":"LegalEntitySearchStatusEnum","type":"string","enum":["WAITING_FOR_DATA","WAITING_FOR_DOCUMENTS","READY_DATA","READY_DOCUMENTS","PREPARING","COMPLETED","FAILED","ERROR"],"description":"status of the search"},"DocumentTypeEnum":{"title":"DocumentTypeEnum","type":"string","description":"This list may change in the future.","enum":["KYC","OTHER","PROOF_OF_SINGLE_CUSTODY","PROOF_OF_CUSTODY","PROOF_OF_RESIDENCE","BIRTH_CERTIFICATE","IDENTIFICATION_CERTIFICATE","CURRENT_REGISTRY_EXTRACT","CHRONOLOGICAL_REGISTRY_EXTRACT","SHAREHOLDER_LIST","PARTNERSHIP_AGREEMENT","TRANSPARENCY_REGISTER_EXTRACT","BUSINESS_REGISTRATION","STATUTE","INHERITANCE_LEGITIMATION","INSOLVENCY_ORDER","TIN_NA_CONFIRMATION","SOURCE_OF_INCOME","SOURCE_OF_FUNDS","DEATH_CERTIFICATE","W_8BEN_E","CRYPTO_RECEIPT","TRADE_INVOICE","TOK_TRADE_INVOICE","EX_ANTE","TOK_EX_ANTE","CORPORATE_ACTION","TRANSFER_RECEIPT"]},"LegalEntitySearchResult":{"title":"LegalEntitySearchResult","type":"object","properties":{"legalName":{"type":"string","description":"The legal name of the entity","maxLength":255},"legalForm":{"$ref":"#/components/schemas/LegalFormEnum"},"naceSectors":{"type":"array","description":"Specification of the sector in which the company is mainly economically active. The information should be provided according to the groups of the NACE codes (Sections A-V, Groups 01.11 - 99.00) without subclasses. (Level 4)","items":{"$ref":"#/components/schemas/LegalEntityNaceSector"}},"registerCountry":{"$ref":"#/components/schemas/CountryEnum"},"registerNumber":{"type":"string","description":"Number at which the company is registered","maxLength":255},"registerCourt":{"type":"string","minLength":1,"maxLength":255,"description":"An administrative court in which the company was registered"},"registerCourtZipCode":{"type":"string","minLength":1,"maxLength":255,"description":"An administrative court zip code in which the company was registered"},"registeredOn":{"type":"string","format":"date","description":"The date on which the entity was registered"},"foundedOn":{"type":"string","format":"date","description":"The date on which the entity was founded"},"vendorRecordId":{"type":"string","minLength":1,"maxLength":255,"description":"The vendor record id of the entity"},"legalEntityIdentifier":{"type":"string","minLength":1,"maxLength":20,"description":"Unique global identifier for legal entities participating in financial transactions","pattern":"^\\d{4}[0]{2}[A-Z\\d]{12}\\d{2}$"},"purpose":{"type":"string","minLength":1,"maxLength":255,"description":"The purpose of the legal entity"},"vatId":{"type":"string","minLength":11,"maxLength":11,"description":"The value-added tax id of the legal entity"},"mainAddress":{"$ref":"#/components/schemas/Address"},"correspondenceAddress":{"$ref":"#/components/schemas/Address"},"invoiceAddress":{"$ref":"#/components/schemas/Address"},"contact":{"$ref":"#/components/schemas/Contact"}},"required":["legalName","vendorRecordId"]},"LegalFormEnum":{"title":"LegalFormEnum","type":"string","description":"LegalFormEnum","enum":["LIMITED_LIABILITY_COMPANY","PUBLIC_LIMITED_COMPANY","PRIVATE_CORPORATION","FOUNDATION","ASSOCIATION","REGISTERED_BUSINESSMAN","REGISTERED_COMPANY","LIMITED_PARTNERSHIP","GENERAL_PARTNERSHIP","LIMITED_LIABILITY_COMPANY_AND_LIMITED_PARTNERSHIP","PARTNERSHIP","SINGLE_PARTNERSHIP","OTHER","UNACCEPTABLE"]},"LegalEntityNaceSector":{"title":"LegalEntityNaceSector","type":"object","properties":{"section":{"type":"string"},"code":{"type":"string","minLength":2},"description":{"type":"string","maxLength":255}},"required":["code"]},"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"]},"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"]},"Contact":{"title":"Contact","type":"object","properties":{"phone":{"type":"string","description":"Mobile telephone number","minLength":3,"maxLength":20,"pattern":"^[\\+\\-\\(\\)\\d ]{3,20}$"},"email":{"type":"string","description":"E-mail address","maxLength":255,"pattern":"^[a-zA-Z0-9.!#$%&'*+\\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$"},"fax":{"type":"string","description":"Fax number","minLength":3,"maxLength":20,"pattern":"^[\\+\\-\\(\\)\\d ]{3,20}$"},"website":{"type":"string","description":"website address","maxLength":320}},"required":["phone","email"]},"LegalRepresentativeSearchResult":{"title":"LegalRepresentativeSearchResult","type":"object","properties":{"firstName":{"type":"string","maxLength":255,"description":"All first names of the person received from the provider"},"lastName":{"type":"string","maxLength":255},"gender":{"$ref":"#/components/schemas/GenderEnum"},"birthDay":{"type":"string","format":"date"},"birthPlace":{"type":"string","minLength":1},"academicDegree":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"position":{"$ref":"#/components/schemas/LegalRepresentativeFunctionEnum"},"taxId":{"type":"string","minLength":1},"representationCompetence":{"type":"string","minLength":1},"nationalities":{"type":"array","items":{"$ref":"#/components/schemas/CountryEnum"}},"address":{"$ref":"#/components/schemas/Address"}},"required":["firstName","lastName"]},"GenderEnum":{"title":"GenderEnum","type":"string","description":"Gender","enum":["MALE","FEMALE","DIVERSE"]},"LegalRepresentativeFunctionEnum":{"title":"LegalRepresentativeFunctionEnum","type":"string","enum":["MANAGING_DIRECTOR","SUPERVISORY_BOARD","SHAREHOLDER","OTHER"]},"BeneficialOwnerSearchResult":{"title":"BeneficialOwnerSearchResult","type":"object","properties":{"firstName":{"type":"string","maxLength":255,"description":"All first names of the person received from the provider"},"lastName":{"type":"string","maxLength":255},"gender":{"$ref":"#/components/schemas/GenderEnum"},"birthDay":{"type":"string","format":"date"},"birthPlace":{"type":"string","minLength":1},"academicDegree":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"taxId":{"type":"string","minLength":1},"scope":{"type":"string","minLength":1},"representationCompetence":{"type":"string","minLength":1},"share":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":100},"nationalities":{"type":"array","items":{"$ref":"#/components/schemas/CountryEnum"}},"address":{"$ref":"#/components/schemas/Address"}},"required":["firstName","lastName","share","nationalities"]},"LegalEntityDocumentSearchResult":{"title":"LegalEntityDocumentSearchResult","type":"object","properties":{"contentType":{"type":"string","minLength":1},"documentId":{"type":"string","minLength":1},"documentType":{"$ref":"#/components/schemas/DocumentTypeEnum"},"length":{"type":"integer"},"name":{"type":"string","minLength":1},"timestamp":{"type":"string","format":"date-time"}}},"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/vendor/legal-entities/{searchId}":{"get":{"summary":"Get Legal Entity Search Result","operationId":"get-legal-entity-search-result","description":"Get legal entity search result","tags":["Legal Entities"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalEntityCompoundSearchResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}}}} ``` --- # 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/legal-entities.md?ask= ``` 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.