LogoLogo
  • Home Page
  • Documentation
    • API Overview
    • Partner API Authentication
    • Onboarding
    • Partner Webhooks
    • Status Codes for Financial Operations
    • Prices
  • WEBSOCKETS
    • Websocket Prices
      • Prices
      • Schemas
  • API REFERENCE
    • Authorization
      • Schemas
    • User Management
      • Users
      • Schemas
    • Customers
      • General
      • Legal Entities
      • Natural Persons
      • Customer Labels
      • Search Nace Sectors
      • Onboarding Wizard
      • Schemas
    • Documents
      • Documents
      • Schemas
    • Onboardings
      • Onboarding
      • Offboarding
      • Schemas
    • Products
      • General
      • Schemas
    • Asset Management
      • Trading
        • Assets
        • Schemas
      • Digital assets
        • Create Order
        • General
        • Assets
        • Schemas
      • Strategy
        • Schemas
    • Transaction History
      • Schemas
    • Transfers
      • General
      • Create Incoming Test Transfer
      • Schemas
    • Partner Documents
      • Schemas
    • Webhooks
      • Schemas
  • PARTNER APIS
    • Partner Webhooks
      • Schemas
Powered by GitBook
On this page
  1. API REFERENCE
  2. Customers

Legal Entities

Last updated 6 days ago

Get Legal Entity By Search Id

get

Ready to test

Get legal entity by search id

Authorizations
Path parameters
searchIdstring · uuidRequired

Unique search identification number in UUID format

Responses
200
OK
application/json
400
Bad Request
application/json
404
Not Found
application/json
get
GET /customers/vendor/prepare/legal-entities/{searchId} HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Accept: */*
{
  "search": {
    "searchId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "WAITING_FOR_DATA",
    "documentTypes": [
      "GENERAL"
    ]
  },
  "legalEntity": {
    "legalName": "text",
    "legalForm": "LIMITED_LIABILITY_COMPANY",
    "naceSectors": [
      {
        "section": "text",
        "code": "text",
        "description": "text"
      }
    ],
    "registerCountry": "AF",
    "registerNumber": "text",
    "registerCourt": "text",
    "registerCourtZipCode": "text",
    "registeredOn": "2025-05-23",
    "foundedOn": "2025-05-23",
    "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-05-23",
      "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-05-23",
      "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": "GENERAL",
      "length": 1,
      "name": "text",
      "timestamp": null
    }
  ]
}

Get Legal Entity Customer

get

Ready to test

Get legal entity type customer

Authorizations
Path parameters
customerIdstring · uuidRequired

Unique customer identification number in UUID format

Responses
200
OK
application/json
400
Bad Request
application/json
404
Not Found
application/json
get
GET /customers/legal-entities/{customerId} HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Accept: */*
{
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "customerStatus": "CREATED",
  "customerType": "NATURAL_PERSON",
  "signedDocumentsRelatedToCustomer": [
    {
      "partnerDocumentId": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "documentType": "TERMS_AND_CONDITIONS",
      "version": 1,
      "naturalPersonId": "123e4567-e89b-12d3-a456-426614174000",
      "naturalPersonFullName": "text",
      "createdOn": "2025-05-23T00:48:50.385Z",
      "modifiedOn": "2025-05-23T00:48:50.385Z"
    }
  ],
  "createdOn": "2025-05-23T00:48:50.385Z",
  "modifiedOn": "2025-05-23T00:48:50.385Z",
  "approvedOn": "2025-05-23T00:48:50.385Z",
  "cancellationDate": "2025-05-23T00:48:50.385Z",
  "legalName": "text",
  "legalForm": "LIMITED_LIABILITY_COMPANY",
  "naceSectors": [
    {
      "section": "text",
      "code": "text",
      "description": "text"
    }
  ],
  "registerCountry": "AF",
  "registerNumber": "text",
  "registerCourt": "text",
  "registerCourtZipCode": "text",
  "registeredOn": "2025-05-23",
  "foundedOn": "2025-05-23",
  "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",
  "legalEntityIdentifier": "text",
  "averageProfit": 1,
  "averageRevenue": 1,
  "liquidAssets": 1,
  "lastAnnualFinancialStatement": "2025-05-23",
  "fatcaCrsDeclaration": {
    "isForeignTaxResidency": true,
    "isSanctionedCountries": true,
    "fatcaClassification": "ACTIVE_NFE",
    "activeNfeType": "LE_BY_INCOME_ASSETS"
  },
  "externalId": "text",
  "legalRepresentatives": [
    {
      "taxDetails": [
        {
          "taxId": "text",
          "taxResidency": "AF"
        }
      ],
      "firstName": "text",
      "lastName": "text",
      "middleName": "text",
      "birthDay": "2025-05-23",
      "birthPlace": "text",
      "birthCountry": "AF",
      "isUsNationality": true,
      "mainAddress": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "country": "AF",
        "additionalInfo": "text"
      },
      "nationalities": [
        {
          "countryCode": "AF",
          "nationalIdentifier": "text",
          "nationalIdentifierType": "CONCAT"
        }
      ],
      "function": "MANAGING_DIRECTOR",
      "soleSignatureAuthorized": true,
      "fatcaControllingPerson": true,
      "globalId": "text",
      "deathDay": "2025-05-23"
    }
  ],
  "refAccounts": [
    {
      "bankName": "text",
      "iban": "text",
      "bic": "text",
      "type": "PRIMARY",
      "ownerName": "text"
    }
  ],
  "labels": [
    "text"
  ],
  "globalId": "text",
  "isSanction": true,
  "verifiedOn": "2025-05-23T00:48:50.385Z"
}
  • GETSearch Legal Entities
  • POSTPrepare Legal Entity
  • GETGet Legal Entity By Search Id
  • POSTCreate Legal Entity Customer
  • PATCHUpdate Legal Entity Customer
  • GETGet Legal Entity Customer

Search Legal Entities

get

Ready to test

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
companyNamestringRequired

Company name

providerIdstringOptional

provider id

Responses
200
OK
application/json
400
Bad Request
application/json
404
Not Found
application/json
get
GET /customers/vendor/search/legal-entities HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
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

Ready to test

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
400
Bad Request
application/json
post
POST /customers/vendor/prepare/legal-entities HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Content-Type: application/json
Accept: */*
Content-Length: 42

{
  "companyName": "text",
  "providerId": "text"
}
{
  "searchId": "123e4567-e89b-12d3-a456-426614174000"
}

Create Legal Entity Customer

post

Ready to test

Create new legal entity type customer

Authorizations
Body
legalNamestring · min: 1 · max: 255Required

The legal name of the entity

legalFormstring · enumRequired

The legal form of the entity

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

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}$
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

labelsstring[] · max: 16Optional

Up to 16 user-defined labels can be provided to allow grouping of customers as per required logic

Responses
200
OK
application/json
400
Bad Request
application/json
409
Conflict
application/json
post
POST /customers/legal-entities HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Content-Type: application/json
Accept: */*
Content-Length: 1820

{
  "legalName": "text",
  "legalForm": "LIMITED_LIABILITY_COMPANY",
  "naceSectors": [
    {
      "section": "text",
      "code": "text",
      "description": "text"
    }
  ],
  "registerCountry": "AF",
  "registerNumber": "text",
  "registerCourt": "text",
  "registerCourtZipCode": "text",
  "registeredOn": "2025-05-23",
  "foundedOn": "2025-05-23",
  "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",
  "legalEntityIdentifier": "text",
  "averageProfit": 1,
  "averageRevenue": 1,
  "liquidAssets": 1,
  "lastAnnualFinancialStatement": "2025-05-23",
  "fatcaCrsDeclaration": {
    "isForeignTaxResidency": true,
    "isSanctionedCountries": true,
    "fatcaClassification": "ACTIVE_NFE",
    "activeNfeType": "LE_BY_INCOME_ASSETS"
  },
  "externalId": "text",
  "legalRepresentatives": [
    {
      "taxDetails": [
        {
          "taxId": "text",
          "taxResidency": "AF"
        }
      ],
      "firstName": "text",
      "lastName": "text",
      "middleName": "text",
      "birthDay": "2025-05-23",
      "birthPlace": "text",
      "birthCountry": "AF",
      "isUsNationality": true,
      "mainAddress": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "country": "AF",
        "additionalInfo": "text"
      },
      "nationalities": [
        {
          "countryCode": "AF",
          "nationalIdentifier": "text",
          "nationalIdentifierType": "CONCAT"
        }
      ],
      "function": "MANAGING_DIRECTOR",
      "soleSignatureAuthorized": true,
      "fatcaControllingPerson": true
    }
  ],
  "refAccounts": [
    {
      "bankName": "text",
      "iban": "text",
      "bic": "text",
      "type": "PRIMARY",
      "ownerName": "text"
    }
  ],
  "labels": [
    "text"
  ]
}
{
  "customerId": "123e4567-e89b-12d3-a456-426614174000"
}

Update Legal Entity Customer

patch

Ready to test

Update existing legal entity type customer

Authorizations
Path parameters
customerIdstring · uuidRequired

Unique customer identification number in UUID format

Header parameters
Requestor-IDstring · uuidRequired

Unique requestor identification in UUID format

Body
labelsstring[] · max: 16Optional

Up to 16 user-defined labels can be provided to allow grouping of customers as per required logic

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
400
Bad Request
application/json
patch
PATCH /customers/legal-entities/{customerId} HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Requestor-ID: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 1145

{
  "labels": [
    "text"
  ],
  "averageProfit": 1,
  "averageRevenue": 1,
  "liquidAssets": 1,
  "lastAnnualFinancialStatement": "2025-05-23",
  "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"
  },
  "legalRepresentatives": [
    {
      "taxDetails": [
        {
          "taxId": "text",
          "taxResidency": "AF"
        }
      ],
      "firstName": "text",
      "lastName": "text",
      "middleName": "text",
      "birthDay": "2025-05-23",
      "birthPlace": "text",
      "birthCountry": "AF",
      "isUsNationality": true,
      "mainAddress": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "country": "AF",
        "additionalInfo": "text"
      },
      "nationalities": [
        {
          "countryCode": "AF",
          "nationalIdentifier": "text",
          "nationalIdentifierType": "CONCAT"
        }
      ],
      "function": "MANAGING_DIRECTOR",
      "soleSignatureAuthorized": true,
      "fatcaControllingPerson": true
    }
  ],
  "refAccounts": [
    {
      "bankName": "text",
      "iban": "text",
      "bic": "text",
      "type": "PRIMARY",
      "ownerName": "text"
    }
  ],
  "externalId": "text"
}

No content