API documentation

Vespia provides GraphQL API. If you want to receive all the benefits of GraphQL, you have to set up your GraphQL-client, or you could only send basic HTTP requests. Our suggestion is to use GraphQL client, as this will save integration time, and it will be easier to parse the responses.

How to Build


  • Stands for "Application Programming Interface"
  • Exchange data structures over HTTP protocol or GraphQL client via https://dev-api.vespia.io/my/graphql endpoint
  • Perform authentication procedures through HTTP protocol or GraphQL client via https://dev-api.vespia.io/auth/graphql endpoint
  • Use API as a way of exchanging data between your custom application and Vespia
  • An API can be used by existing web, server-side, or native applications to load and save Vespia data.

Auth procedure

First of all, you need to be authorized. You have to pass the access token in each request in Authorization header.

To receive the access token you should use the signIn mutation in GraphQL or HTTP request way. The token would expire within 10 minutes.

To update access token use refreshToken and refreshTokenPair mutation.

All available queries and mutations with arguments and returned fields can be viewed by following this link or by pressing the Expand button in the sandbox.

Verification procedure

KYB Verification

To perform KYB (business) verification of a fast country, you need to call the requestKybVerification mutation passing the name and registrationCode of the company, as well as the countryCode of the country where the company is registered.

If the country is slow, then you additionally need to describe the entityChecks field by passing an array with an object in which the type property is "DOCUMENT" and the input property is an object with the description property in which the desired documents are described.

KYC Verification

To perform KYC verification, you need to call the requestKycVerification mutation passing into the arguments the KIND property, in which you specify which checks to perform: ID, AML, BOTH, the name of the person being verified (this should be an array ["first name", "middle name", "last name"] or ["first name", "last name"] or a string) and/or email where to send ID verification letter (if kind is set to ID or BOTH)

Request entity checks

To apply additional checks, you need to use the requestEntityChecks mutation that takes the entityChecks argument.

Verification result

To get the verification result, you should use the folder query.

Filter AML result

In order to filter the AML check result and select the right people from the amlList list (this array is stored in the result field of the completed check), you need to use the transformEntityCheckResult mutation. This mutation takes 3 arguments: entityCheckId, transformerName (for AML check filtering, the value will be AMLEntityFilter) and an input object that contains one property: keepIndexes. This is an array that contains the indexes of those objects from the amlList that need to be left.

All available queries and mutations with arguments and returned fields can be viewed by following this link or by pressing the Expand button in the sandbox.

Fast and slow countries

Countries are divided into fast and slow. For fast countries business information is available immediately, for slow countries we only provide original incorporation documents and commercial register extracts.

To find out which country is fast or slow, use countries query (try this sandbox).

In this list, each country has isBusinessAvailable and isDocumentAvailable fields. The country is fast if the isBusinessAvailable field is true. If the isBusinessAvailable field is false and isDocumentAvailable is true, then the country is slow.

Entity checks


There are currently 5 different entity checks available.

Type Description
BUSINESS_INFO Business check of the company
AML AML check of the company or person
ID ID check of the person that will be sent to the specified mail
QUESTIONNAIRE Questionnaire which will be sent to the specified mail
DOCUMENT Request additional documents
VAT VAT check of the company

isCorporate (optional)

Determines what type of entity will be checked: legal entity (isCorporate equals true) or private person (isCorporate equals false)

entityId (optional)

Determines for which entity the check will be performed.

folderId (optional)

Determines in which folder the entity should be created


Input data required to perform entityCheck.

Type Input
BUSINESS_INFO name, registrationCode, countryCode
AML name
ID name, email
DOCUMENT description
VAT countryCode, name

If entityId is specified, then the check will be applied to this entity. If entityId is not specified, but folderId is specified, then the new entity will be created in the given folder. If both parameters are absent, then a new folder will be created and a new entity will be created in it, to which the selected check will be applied.