Legal Entities

Create Legal Entity

post

Create new legal entity

Authorizations
Body
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
post
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: 1167

{
  "legalEntityIdentifier": "text",
  "legalName": "text",
  "legalForm": "LIMITED_LIABILITY_COMPANY",
  "naceSectors": [
    {
      "section": "text",
      "code": "text",
      "description": "text"
    }
  ],
  "registerCountry": "AF",
  "registerNumber": "text",
  "registerCourt": "text",
  "registerCourtZipCode": "text",
  "registeredOn": "2025-08-30",
  "foundedOn": "2025-08-30",
  "vatId": "text",
  "purpose": "text",
  "mainAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "correspondenceAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "invoiceAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "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": "2025-08-30",
  "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

Get legal entities

Authorizations
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
get
GET /entities/legal-entities 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": "2025-08-30"
      },
      "createdOn": "2025-08-30T17:48:40.388Z",
      "modifiedOn": "2025-08-30T17:48:40.388Z",
      "verifiedOn": "2025-08-30T17:48:40.388Z",
      "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": "2025-08-30",
      "foundedOn": "2025-08-30",
      "vatId": "text",
      "purpose": "text",
      "mainAddress": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "country": "AF",
        "additionalInfo": "text"
      },
      "correspondenceAddress": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "country": "AF",
        "additionalInfo": "text"
      },
      "invoiceAddress": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "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": "2025-08-30",
      "fatcaCrsDeclaration": {
        "isForeignTaxResidency": true,
        "isSanctionedCountries": true,
        "fatcaClassification": "ACTIVE_NFE",
        "activeNfeType": "LE_BY_INCOME_ASSETS"
      },
      "externalId": "text"
    }
  ],
  "pagination": {
    "cursor": "text",
    "limit": 1
  }
}

Get Legal Entity

get

Get legal entity

Authorizations
Path parameters
legalEntityIdstring · uuidRequired

Legal Entity ID

Responses
200

OK

application/json
get
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": "2025-08-30"
  },
  "createdOn": "2025-08-30T17:48:40.388Z",
  "modifiedOn": "2025-08-30T17:48:40.388Z",
  "verifiedOn": "2025-08-30T17:48:40.388Z",
  "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": "2025-08-30",
  "foundedOn": "2025-08-30",
  "vatId": "text",
  "purpose": "text",
  "mainAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "correspondenceAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "invoiceAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "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": "2025-08-30",
  "fatcaCrsDeclaration": {
    "isForeignTaxResidency": true,
    "isSanctionedCountries": true,
    "fatcaClassification": "ACTIVE_NFE",
    "activeNfeType": "LE_BY_INCOME_ASSETS"
  },
  "externalId": "text"
}

Update Legal Entity

patch

Update legal entity

Authorizations
Path parameters
legalEntityIdstring · uuidRequired

Legal Entity ID

Header parameters
Requestor-IDstring · uuidRequired

Unique requestor identification in UUID format

Body
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
202

Accepted

No content
patch
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: 492

{
  "averageProfit": 1,
  "averageRevenue": 1,
  "liquidAssets": 1,
  "lastAnnualFinancialStatement": "2025-08-30",
  "mainAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "correspondenceAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "invoiceAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "externalId": "text"
}
No content

Search Legal Entities

get

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
Query parameters
legalNamestringRequired

Legal name

providerIdstringOptional

provider id

Responses
200

OK

application/json
get
GET /entities/vendor/legal-entities 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",
      "country": "AF",
      "additionalInfo": "text"
    },
    "businessOfficeType": "Headquarters",
    "legalForm": "GMBH",
    "name": "Hummel Dienstleistungsgesellschaft mbH",
    "providerId": 727420,
    "registerCourt": "Kassel",
    "registrationNumber": "HRB 205873"
  }
]

Prepare Legal Entity

post

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
Body
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
post
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

Get legal entity search result

Authorizations
Path parameters
searchIdstring · uuidRequired

Search ID

Responses
200

OK

application/json
get
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": "2025-08-30",
    "foundedOn": "2025-08-30",
    "vendorRecordId": "text",
    "legalEntityIdentifier": "text",
    "purpose": "text",
    "vatId": "text",
    "mainAddress": {
      "street": "text",
      "streetNumber": "text",
      "city": "text",
      "zip": "text",
      "country": "AF",
      "additionalInfo": "text"
    },
    "correspondenceAddress": {
      "street": "text",
      "streetNumber": "text",
      "city": "text",
      "zip": "text",
      "country": "AF",
      "additionalInfo": "text"
    },
    "invoiceAddress": {
      "street": "text",
      "streetNumber": "text",
      "city": "text",
      "zip": "text",
      "country": "AF",
      "additionalInfo": "text"
    },
    "contact": {
      "phone": "text",
      "email": "text",
      "fax": "text",
      "website": "text"
    }
  },
  "legalRepresentatives": [
    {
      "firstName": "text",
      "lastName": "text",
      "gender": "MALE",
      "birthDay": "2025-08-30",
      "birthPlace": "text",
      "academicDegree": "text",
      "title": "text",
      "position": "MANAGING_DIRECTOR",
      "taxId": "text",
      "representationCompetence": "text",
      "nationalities": [
        "AF"
      ],
      "address": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "country": "AF",
        "additionalInfo": "text"
      }
    }
  ],
  "beneficialOwners": [
    {
      "firstName": "text",
      "lastName": "text",
      "gender": "MALE",
      "birthDay": "2025-08-30",
      "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",
        "country": "AF",
        "additionalInfo": "text"
      }
    }
  ],
  "documents": [
    {
      "contentType": "text",
      "documentId": "text",
      "documentType": "KYC",
      "length": 1,
      "name": "text",
      "timestamp": null
    }
  ]
}

Last updated