Legal Entities

Create Legal Entity

post

https://tvda-api.platform-test.tradevest.aihttps://tvda-api.platform-pretest.tradevest.ai

/entities/legal-entities

Create new legal entity

Authorizations

Bearer

OAuth2clientCredentialsRequired

Token URL:

Body

application/json

legalEntityIdentifierstring · min: 20 · max: 20Optional

Unique global identifier for legal entities participating in financial transactions

Pattern: ^\d{4}[0]{2}[A-Z\d]{12}\d{2}$

legalNamestring · max: 255Required

The legal name of the entity

legalFormstring · enumRequired

LegalFormEnum

Possible values:

registerCountrystring · enumRequired

Country code in ISO 3166-1 alpha-2 standard

Possible values:

registerNumberstring · min: 1 · max: 255Required

Number at which the company is registered

registerCourtstring · min: 1 · max: 255Required

An administrative court in which the company was registered

registerCourtZipCodestring · min: 1 · max: 255Optional

An administrative court zip code in which the company was registered

registeredOnstring · dateOptional

The date on which the entity was registered

foundedOnstring · dateRequired

The date on which the entity was founded

vatIdstring · min: 11 · max: 11Optional

The value-added tax id of the legal entity

purposestring · min: 1 · max: 255Optional

The purpose of the legal entity

searchIdstring · uuidOptional

taxNumberstring · min: 1 · max: 255Required

The tax number of the legal entity

isListedbooleanOptional

Determine whether the shares of that company are on the list (or board) of stock that are officially traded on a stock exchange

listedAtstring · min: 1 · max: 255Optional

Determine where the shares of that company are officially traded on a stock exchange. Only when entity is listed

averageProfitnumberOptional

Average profit for the year (after tax)

averageRevenuenumberOptional

Average revenue for the year

liquidAssetsnumberOptional

Liquid assets

lastAnnualFinancialStatementstring · dateOptional

Last annual financial statement date

externalIdstring · min: 1Optional

External Id in partner's system. This value has to be unique

Responses

200

OK

application/json

400

Bad Request

application/json

409

Conflict

application/json

post

/entities/legal-entities

HTTPcURLJavaScriptPython

POST /entities/legal-entities HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1212

{
  "legalEntityIdentifier": "text",
  "legalName": "text",
  "legalForm": "LIMITED_LIABILITY_COMPANY",
  "naceSectors": [
    {
      "section": "text",
      "code": "text",
      "description": "text"
    }
  ],
  "registerCountry": "AF",
  "registerNumber": "text",
  "registerCourt": "text",
  "registerCourtZipCode": "text",
  "registeredOn": "2026-01-31",
  "foundedOn": "2026-01-31",
  "vatId": "text",
  "purpose": "text",
  "mainAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "state": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "correspondenceAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "state": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "invoiceAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "state": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "contact": {
    "phone": "text",
    "email": "text",
    "fax": "text",
    "website": "text"
  },
  "searchId": "123e4567-e89b-12d3-a456-426614174000",
  "taxNumber": "text",
  "isListed": true,
  "listedAt": "text",
  "averageProfit": 1,
  "averageRevenue": 1,
  "liquidAssets": 1,
  "lastAnnualFinancialStatement": "2026-01-31",
  "fatcaCrsDeclaration": {
    "isForeignTaxResidency": true,
    "isSanctionedCountries": true,
    "fatcaClassification": "ACTIVE_NFE",
    "activeNfeType": "LE_BY_INCOME_ASSETS"
  },
  "externalId": "text"
}

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

Get Legal Entities

get

https://tvda-api.platform-test.tradevest.aihttps://tvda-api.platform-pretest.tradevest.ai

/entities/legal-entities

Get legal entities

Authorizations

Bearer

OAuth2clientCredentialsRequired

Token URL:

Query parameters

cursorstringOptional

String value used for pagination

limitinteger · min: 1Required

Maximum number of items to return

Default: 20

legalEntityStatusstring · enumOptional

Legal entity status Filter

Possible values:

Responses

200

OK

application/json

400

Bad Request

application/json

get

/entities/legal-entities

HTTPcURLJavaScriptPython

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

{
  "data": [
    {
      "legalEntityId": "123e4567-e89b-12d3-a456-426614174000",
      "globalId": "text",
      "lei": {
        "legalEntityIdentifier": "text",
        "leiStatus": "ISSUED",
        "leiValidUntil": "2026-01-31"
      },
      "createdOn": "2026-01-31T08:53:59.797Z",
      "modifiedOn": "2026-01-31T08:53:59.797Z",
      "verifiedOn": "2026-01-31T08:53:59.797Z",
      "isSanction": true,
      "riskLevel": "LOW",
      "legalEntityStatus": "CREATED",
      "legalName": "text",
      "legalForm": "LIMITED_LIABILITY_COMPANY",
      "naceSectors": [
        {
          "section": "text",
          "code": "text",
          "description": "text"
        }
      ],
      "registerCountry": "AF",
      "registerNumber": "text",
      "registerCourt": "text",
      "registerCourtZipCode": "text",
      "registeredOn": "2026-01-31",
      "foundedOn": "2026-01-31",
      "vatId": "text",
      "purpose": "text",
      "mainAddress": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "state": "text",
        "country": "AF",
        "additionalInfo": "text"
      },
      "correspondenceAddress": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "state": "text",
        "country": "AF",
        "additionalInfo": "text"
      },
      "invoiceAddress": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "state": "text",
        "country": "AF",
        "additionalInfo": "text"
      },
      "contact": {
        "phone": "text",
        "email": "text",
        "fax": "text",
        "website": "text"
      },
      "searchId": "123e4567-e89b-12d3-a456-426614174000",
      "taxNumber": "text",
      "isListed": true,
      "listedAt": "text",
      "averageProfit": 1,
      "averageRevenue": 1,
      "liquidAssets": 1,
      "lastAnnualFinancialStatement": "2026-01-31",
      "fatcaCrsDeclaration": {
        "isForeignTaxResidency": true,
        "isSanctionedCountries": true,
        "fatcaClassification": "ACTIVE_NFE",
        "activeNfeType": "LE_BY_INCOME_ASSETS"
      },
      "externalId": "text"
    }
  ],
  "pagination": {
    "cursor": "text",
    "limit": 1
  }
}

Get Legal Entity

get

https://tvda-api.platform-test.tradevest.aihttps://tvda-api.platform-pretest.tradevest.ai

/entities/legal-entities/{legalEntityId}

Get legal entity

Authorizations

Bearer

OAuth2clientCredentialsRequired

Token URL:

Path parameters

legalEntityIdstring · uuidRequired

Legal Entity ID

Responses

200

OK

application/json

400

Bad Request

application/json

404

Not Found

application/json

get

/entities/legal-entities/{legalEntityId}

HTTPcURLJavaScriptPython

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

{
  "legalEntityId": "123e4567-e89b-12d3-a456-426614174000",
  "globalId": "text",
  "lei": {
    "legalEntityIdentifier": "text",
    "leiStatus": "ISSUED",
    "leiValidUntil": "2026-01-31"
  },
  "createdOn": "2026-01-31T08:53:59.797Z",
  "modifiedOn": "2026-01-31T08:53:59.797Z",
  "verifiedOn": "2026-01-31T08:53:59.797Z",
  "isSanction": true,
  "riskLevel": "LOW",
  "legalEntityStatus": "CREATED",
  "legalName": "text",
  "legalForm": "LIMITED_LIABILITY_COMPANY",
  "naceSectors": [
    {
      "section": "text",
      "code": "text",
      "description": "text"
    }
  ],
  "registerCountry": "AF",
  "registerNumber": "text",
  "registerCourt": "text",
  "registerCourtZipCode": "text",
  "registeredOn": "2026-01-31",
  "foundedOn": "2026-01-31",
  "vatId": "text",
  "purpose": "text",
  "mainAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "state": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "correspondenceAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "state": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "invoiceAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "state": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "contact": {
    "phone": "text",
    "email": "text",
    "fax": "text",
    "website": "text"
  },
  "searchId": "123e4567-e89b-12d3-a456-426614174000",
  "taxNumber": "text",
  "isListed": true,
  "listedAt": "text",
  "averageProfit": 1,
  "averageRevenue": 1,
  "liquidAssets": 1,
  "lastAnnualFinancialStatement": "2026-01-31",
  "fatcaCrsDeclaration": {
    "isForeignTaxResidency": true,
    "isSanctionedCountries": true,
    "fatcaClassification": "ACTIVE_NFE",
    "activeNfeType": "LE_BY_INCOME_ASSETS"
  },
  "externalId": "text"
}

Update Legal Entity

patch

https://tvda-api.platform-test.tradevest.aihttps://tvda-api.platform-pretest.tradevest.ai

/entities/legal-entities/{legalEntityId}

Update legal entity

Authorizations

Bearer

OAuth2clientCredentialsRequired

Token URL:

Path parameters

legalEntityIdstring · uuidRequired

Legal Entity ID

Header parameters

Requestor-IDstring · uuidRequired

Unique requestor identification in UUID format

Body

application/json

documentIdsstring · uuid[]Optional

Document IDs in UUID format for parameters where a document upload is required (legalName, legalForm, mainAddress, correspondenceAddress, invoiceAddress)

Responses

202

Accepted

400

Bad Request

application/json

patch

/entities/legal-entities/{legalEntityId}

HTTPcURLJavaScriptPython

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

{
  "legalEntityUpdateData": {
    "legalName": "text",
    "legalForm": "LIMITED_LIABILITY_COMPANY",
    "naceSectors": [
      {
        "section": "text",
        "code": "text",
        "description": "text"
      }
    ],
    "taxNumber": "text",
    "vatId": "text",
    "isListed": true,
    "listedAt": "text",
    "legalEntityIdentifier": "text",
    "purpose": "text",
    "fatcaCrsDeclaration": {
      "isForeignTaxResidency": true,
      "isSanctionedCountries": true,
      "fatcaClassification": "ACTIVE_NFE",
      "activeNfeType": "LE_BY_INCOME_ASSETS"
    },
    "averageProfit": 1,
    "averageRevenue": 1,
    "liquidAssets": 1,
    "lastAnnualFinancialStatement": "2026-01-31",
    "mainAddress": {
      "street": "text",
      "streetNumber": "text",
      "city": "text",
      "zip": "text",
      "state": "text",
      "country": "AF",
      "additionalInfo": "text"
    },
    "correspondenceAddress": {
      "street": "text",
      "streetNumber": "text",
      "city": "text",
      "zip": "text",
      "state": "text",
      "country": "AF",
      "additionalInfo": "text"
    },
    "invoiceAddress": {
      "street": "text",
      "streetNumber": "text",
      "city": "text",
      "zip": "text",
      "state": "text",
      "country": "AF",
      "additionalInfo": "text"
    },
    "externalId": "text"
  },
  "documentIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

No content

Search Legal Entities

get

https://tvda-api.platform-test.tradevest.aihttps://tvda-api.platform-pretest.tradevest.ai

/entities/vendor/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.

Authorizations

Bearer

OAuth2clientCredentialsRequired

Token URL:

Query parameters

legalNamestringRequired

Legal name

providerIdstringOptional

provider id

Responses

200

OK

application/json

400

Bad Request

application/json

404

Not Found

application/json

get

/entities/vendor/legal-entities

HTTPcURLJavaScriptPython

GET /entities/vendor/legal-entities?legalName=text HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "address": {
      "street": "text",
      "streetNumber": "text",
      "city": "text",
      "zip": "text",
      "state": "text",
      "country": "AF",
      "additionalInfo": "text"
    },
    "businessOfficeType": "Headquarters",
    "legalForm": "GMBH",
    "name": "Hummel Dienstleistungsgesellschaft mbH",
    "providerId": 727420,
    "registerCourt": "Kassel",
    "registrationNumber": "HRB 205873"
  }
]

Prepare Legal Entity

post

https://tvda-api.platform-test.tradevest.aihttps://tvda-api.platform-pretest.tradevest.ai

/entities/vendor/legal-entities

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.

Authorizations

Bearer

OAuth2clientCredentialsRequired

Token URL:

Body

application/json

companyNamestring · min: 1 · max: 255Required

The name of the company

providerIdstring · min: 1 · max: 255Optional

The provider id of the company

Responses

200

OK

application/json

400

Bad Request

application/json

post

/entities/vendor/legal-entities

HTTPcURLJavaScriptPython

POST /entities/vendor/legal-entities HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 42

{
  "companyName": "text",
  "providerId": "text"
}

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

Get Legal Entity Search Result

get

https://tvda-api.platform-test.tradevest.aihttps://tvda-api.platform-pretest.tradevest.ai

/entities/vendor/legal-entities/{searchId}

Get legal entity search result

Authorizations

Bearer

OAuth2clientCredentialsRequired

Token URL:

Path parameters

searchIdstring · uuidRequired

Search ID

Responses

200

OK

application/json

400

Bad Request

application/json

404

Not Found

application/json

get

/entities/vendor/legal-entities/{searchId}

HTTPcURLJavaScriptPython

GET /entities/vendor/legal-entities/{searchId} HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "search": {
    "searchId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "WAITING_FOR_DATA",
    "documentTypes": [
      "KYC"
    ]
  },
  "legalEntity": {
    "legalName": "text",
    "legalForm": "LIMITED_LIABILITY_COMPANY",
    "naceSectors": [
      {
        "section": "text",
        "code": "text",
        "description": "text"
      }
    ],
    "registerCountry": "AF",
    "registerNumber": "text",
    "registerCourt": "text",
    "registerCourtZipCode": "text",
    "registeredOn": "2026-01-31",
    "foundedOn": "2026-01-31",
    "vendorRecordId": "text",
    "legalEntityIdentifier": "text",
    "purpose": "text",
    "vatId": "text",
    "mainAddress": {
      "street": "text",
      "streetNumber": "text",
      "city": "text",
      "zip": "text",
      "state": "text",
      "country": "AF",
      "additionalInfo": "text"
    },
    "correspondenceAddress": {
      "street": "text",
      "streetNumber": "text",
      "city": "text",
      "zip": "text",
      "state": "text",
      "country": "AF",
      "additionalInfo": "text"
    },
    "invoiceAddress": {
      "street": "text",
      "streetNumber": "text",
      "city": "text",
      "zip": "text",
      "state": "text",
      "country": "AF",
      "additionalInfo": "text"
    },
    "contact": {
      "phone": "text",
      "email": "text",
      "fax": "text",
      "website": "text"
    }
  },
  "legalRepresentatives": [
    {
      "firstName": "text",
      "lastName": "text",
      "gender": "MALE",
      "birthDay": "2026-01-31",
      "birthPlace": "text",
      "academicDegree": "text",
      "title": "text",
      "position": "MANAGING_DIRECTOR",
      "taxId": "text",
      "representationCompetence": "text",
      "nationalities": [
        "AF"
      ],
      "address": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "state": "text",
        "country": "AF",
        "additionalInfo": "text"
      }
    }
  ],
  "beneficialOwners": [
    {
      "firstName": "text",
      "lastName": "text",
      "gender": "MALE",
      "birthDay": "2026-01-31",
      "birthPlace": "text",
      "academicDegree": "text",
      "title": "text",
      "taxId": "text",
      "scope": "text",
      "representationCompetence": "text",
      "share": 1,
      "nationalities": [
        "AF"
      ],
      "address": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "state": "text",
        "country": "AF",
        "additionalInfo": "text"
      }
    }
  ],
  "documents": [
    {
      "contentType": "text",
      "documentId": "text",
      "documentType": "KYC",
      "length": 1,
      "name": "text",
      "timestamp": "2026-01-31T08:53:59.797Z"
    }
  ]
}