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.
All available end point

The built-in playground is a user interface that allows developers to interact with the authentication-related queries and mutations of a GraphQL API. It displays all available queries and mutations, along with the parameters that can be passed and the data that is returned. This makes it easy to test and debug authentication-related code and see the results in real-time.

The second built-in playground is another user interface for developers to interact with the non-authentication related queries and mutations of the GraphQL API, this would include all other functionality such as performing checks, managing credits, handling orders, and handling webhooks. This playground also displays all available queries and mutations and parameters and returned data, allowing for easy testing and debugging of these other functionalities.

How to Build

API

  • 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 & KYC Mutations

To perform KYB (business) verification of a fast country, you need to call the requestKybVerification mutation.

  1. requestKybVerification(input: RequestKybVerificationInput!): [EntityCheck]! - This endpoint is used to request a Know Your Business (KYB) verification. The required input is an RequestKybVerificationInput object, which contains information about the entity to be verified. The returned output is an array of EntityCheck objects, which contain information about the verification process, including the status and result of the verification.
  2. requestKycVerification(input: RequestKycVerificationInput!): [EntityCheck]! - This endpoint is used to request a Know Your Customer (KYC) verification. The required input is an RequestKycVerificationInput object, which contains information about the entity to be verified. The returned output is an array of EntityCheck objects, which contain information about the verification process, including the status and result of the verification.

KYB & KYC Queries

In order to get a list of your verifications, you need to use query folders. This query expects a PagedQueryInput and returns requested folders, as well as information about the pagination.

To get full verification tree, you should use the folder query passing the folder id as an argument.

KYB & KYC Inputs

  1. input RequestKybVerificationInput {
    name: String
    registrationCode: String!
    countryCode: String!
    }
    - This input type is used as an argument for the requestKybVerification endpoint. It requires the following fields:
  1. name: The name of the entity.
  2. registrationCode: The registration code of the entity.
  3. countryCode: The country code of the entity.
  1. input RequestKycVerificationInput {
    name: [String]!
    email: String
    dob: String
    gender: String
    country: String
    kind: RequestKycVerificationKind!
    }
    - This input type is used as an argument for the requestKycVerification endpoint. It requires the following fields:
  1. name: The name of the entity. ['first name', 'middle name', 'last name'] or ['name']
  2. email: The email of the entity.
  3. dob: The date of birth of the entity. Has effect on kind: AML
  4. gender: The gender of the entity. Has effect on kind: AML
  5. country: The country of the entity. Has effect on kind: AML
  6. kind: The kind of verification to be performed. This field is required and it can be one of the following: ID, AML, or BOTH.
  1. ID: Perform identity verification only.
  2. AML: Perform AML check only.
  3. BOTH: Perform both identity and AML check.

KYB & KYC Outputs

  1. type Folder {
    id: ID!
    name: String
    label: RiskLabel!
    metadata: JSON
    isKyc: Boolean
    rootEntityId: UUID
    status: String
    entities: [Entity]
    createdAt: DateTime
    updatedAt: DateTime
    comments: [Comment]!
    assets: [AssetView]!
    } -
    This type represents a collection of related entities and their associated data. It contains the following fields:
  1. id: The UUID of the folder.
  2. name: The name of the folder.
  3. label: The risk label of the folder, which can have one of the following values: LOW, MEDIUM, HIGH, UNSPECIFIED.
  4. metadata: Additional metadata in JSON format.
  5. isKyc: A Boolean indicating whether the folder is KYC verifications or not.
  6. rootEntityId: The UUID of the root entity in the folder.
  7. status: The status of the folder
  8. entities: An array of Entity objects related to the folder.
  9. account: The account of the check owner.
  1. type Entity {
    id: ID!    
    info: JSON    
    entityChecks: [EntityCheck]    
    createdAt: DateTime    
    updatedAt: DateTime  
    relation: [Relation]
    } -
    This type represents an individual or organization and contains the following fields:
  1. id: The UUID of the entity.
  2. info: Information about the entity in JSON format.
  3. entityChecks: An array of EntityCheck objects associated with the entity.
  4. relation: An array of Relation objects associated with the entity.
  1. type Relation {
    info: JSON    
    createdAt: DateTime    
    updatedAt: DateTime
    } -
    This type represents a relationship between two entities and contains the following fields:
  1. info: Information about the relationship in JSON format.
  1. type EntityCheck {
    id: ID!
    type: String
    status: String
    result: JSON
    dataRequestInfo: JSON
    dataRequestId: UUID
    folderId: String
    input: JSON
    createdAt: DateTime
    updatedAt: DateTime
    account: AccountDTO
    } -
    This output type represents the check of an entity. It contains the following fields:
  1. id: The UUID of the check.
  2. type: The type of check performed.
  3. status: The status of the check.
  4. result: The result of the verification in JSON format.
  5. dataRequestInfo: Additional information about the data request in JSON format.
  6. dataRequestId: The UUID of the data request.
  7. folderId: The folder id of the check.
  8. input: The input provided for the check in JSON format.
  9. createdAt: The date and time when the check was initiated.
  10. updatedAt: The date and time when the check was last updated.
  11. account: The account of the check owner.

If the country is slow, then use requestEntityChecks mutation.

Request entity checks

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

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.

AML monitoring

In order to start monitoring changes of your AML check result, you need to use the enableEntityCheckMonitoring mutation, where you need to pass the id of entity check with type AML.

In order to disable monitoring of a check result, use the disableEntityCheckMonitoring mutation, passing the id of this check.

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

type

There are currently 8 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
GOOGLE_SEARCH Find AML data of a person or company using Google search engine
ADDITIONAL_INFO Add additional information to your folder

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

Input data required to perform entityCheck.

Type Input
BUSINESS_INFO
{
name: string,
registrationCode: string,
countryCode: string
}
AML
{
name: string[],
gender?: string, (male or female)
dob?: string,
country?: string,
}
ID
{
name: string,
email: string,
sendEmailNotification: boolean
}
QUESTIONNAIRE
{
email: string,
sendEmailNotification: boolean
}
DOCUMENT
{
documents: string[],
requestDescription?: string,
filler?: {
email?: string
},
sendEmailNotification: boolean
},
VAT
{
countryCode: string,
name: string
}
GOOGLE_SEARCH
{
name: string[]
}
ADDITIONAL_INFO
{
additionalInfo: string
}

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.

PagedQueryInput

This GraphQL input is for a paged query, which allows for pagination and filtering of data.

The PagedQueryInput input type includes two fields: pageRequest and filter.

pageRequest is an input of type PageRequestInput, which has three fields:

  1. page represents the page number of the pagination.
  2. size represents the number of items per page.
  3. sort is an array of SortInput objects. Each SortInput object has two fields:
  1. field represents the field to sort by.
  2. direction represents the sort direction, which can be either ASC or DESC.

filter is an array of FilterInput objects. Each FilterInput object has two fields:

  1. comparators is an array of FilterComparatorInput objects. Each FilterComparatorInput object has three fields:
  1. field represents the field to filter by.
  2. value represents the filter value.
  3. type represents the filter comparator type (comparison operator), which can be one of the following:
  1. IS
  2. IS_NOT
  3. EQ
  4. NEQ
  5. GT
  6. GTE
  7. LT
  8. LTE
  9. LIKE
  10. NOT_LIKE
  11. I_LIKE
  12. NOT_I_LIKE
  13. IN
  14. NOT_IN
  15. BETWEEN
  1. operator represents the filter operator, which can be one of the following:
  1. AND
  2. OR

This input allows to specify a page number, page size, and sort order for the data, as well as filter criteria for one or more fields. The FilterInput and FilterComparatorInput types allow for more advanced filtering capabilities, such as filtering by multiple fields and using different comparator types (e.g. greater than, less than, equal to, etc.). The operator field in FilterInput allows for specifying logical operators (AND, OR) between different comparators. It's worth noting that AnyValue is a custom scalar type that represents any type of value. It can be interpreted as a string, number or boolean. The input allows for a flexible and powerful way to query data from a server, enabling to retrieve exactly the data you need, with the desired pagination and filtering options.

Webhook

A webhook is a way for an app to provide other applications with real-time information. They are often used to connect two different apps in order to automate certain tasks or to transmit data.

A webhook works by sending an HTTP request to a specified URL when certain events happen. The request will typically contain information about the event, such as data that has been added or changed. The receiving application can then use this information to take appropriate action.

To set up a webhook, you will need to specify the events that will trigger the webhook, as well as the URL that the webhook will send the request to.

There are currently 3 events available:

  1. event.order.created fires when a new order is created
  2. event.verificationView.built fires when there are updates in the folder
  3. event.wallet.updated fires when the wallet is updated

Webhook Mutations

  1. createWebhookSubscription(input: CreateWebhookSubscriptionInput!): WebhookSubscription! - This endpoint is used to create a new webhook subscription. The required input is the URL where the webhook will send the request. The returned output is the newly created webhook subscription object.
  2. activateWebhookSubscription(id: UUID!): WebhookSubscription! - This endpoint is used to activate an existing webhook subscription. The required input is the UUID of the subscription that needs to be activated. The returned output is the activated webhook subscription object.
  3. deactivateWebhookSubscription(id: UUID!): WebhookSubscription! - This endpoint is used to deactivate an existing webhook subscription. The required input is the UUID of the subscription that needs to be deactivated. The returned output is the deactivated webhook subscription object.
  4. subscribeOnEvent(input: SubscribeOnEventInput!): WebhookSubscription! - This endpoint is used to subscribe a webhook subscription to an event. The required input is the UUID of the subscription and the UUID of the event. The returned output is the webhook subscription object with the subscribed event.
  5. unsubscribeFromEvent(input: UnsubscribeFromEventInput!): WebhookSubscription! - This endpoint is used to unsubscribe a webhook subscription from an event. The required input is the UUID of the subscription and the UUID of the event. The returned output is the webhook subscription object with the unsubscribed event.

Overall, these GraphQL endpoints provide a way for creating, activating and deactivating webhook subscriptions, as well as subscribing and unsubscribing from events.

Webhook Queries

  1. webhookSubscriptions(input: PagedQueryInput!): WebhookSubscriptionPage! - This endpoint is used to retrieve a paginated list of webhook subscriptions. The required input is the PagedQueryInput. The returned output is a WebhookSubscriptionPage object, which contains the requested webhook subscriptions, as well as information about the pagination.
  2. events(input: PagedQueryInput!): EventPage! - This endpoint is used to retrieve a paginated list of events. The required input is the PagedQueryInput, which allows for pagination parameters such as page number and page size. The returned output is an EventPage object, which contains the requested events, as well as information about the pagination.

Overall, these additional GraphQL endpoints provide a way for developers to retrieve paginated lists of webhook subscriptions and events, and it can be useful for UI representation and easy data management.

Inputs

  1. input CreateWebhookSubscriptionInput {
    url: String!
    }
    - This input type is used as an argument for the createWebhookSubscription endpoint. It requires a single field, url, which is the URL where the webhook will send the request.
  2. input SubscribeOnEventInput {
    subscriptionId: UUID!
    eventId: UUID!
    }
    - This input type is used as an argument for the subscribeOnEvent endpoint. It requires two fields: subscriptionId, which is the UUID of the webhook subscription, and eventId, which is the UUID of the event to be subscribed.
  3. deactivateWebhookSubscription(id: UUID!): WebhookSubscription! - This endpoint is used to deactivate an existing webhook subscription. The required input is the UUID of the subscription that needs to be deactivated. The returned output is the deactivated webhook subscription object.
  4. input UnsubscribeFromEventInput {
    subscriptionId: UUID!
    eventId: UUID!
    }
    - This input type is used as an argument for the unsubscribeFromEvent endpoint. It requires two fields: subscriptionId, which is the UUID of the webhook subscription, and eventId, which is the UUID of the event to be unsubscribed.

Outputs

  1. type WebhookSubscriptionPage {
    content: [WebhookSubscription]!
    totalPages: Int!
    totalElements: Int!
    last: Boolean!
    first: Boolean!
    size: Int!
    number: Int!
    numberOfElements: Int!
    }
    - This output type represents the paginated list of webhook subscriptions.
  2. type EventPage {
    content: [Event]!
    totalPages: Int!
    totalElements: Int!
    last: Boolean!
    first: Boolean!
    size: Int!
    number: Int!
    numberOfElements: Int!
    }
    - This output type represents the paginated list of events.
  1. type WebhookSubscription {
    id: ID!
    url: String!
    isActive: Boolean!
    events: [Event]!
    createdAt: DateTime!
    updatedAt: DateTime!
    }
    - This output type represents the webhook subscription object. It contains the following fields:
  1. id: The UUID of the webhook subscription.
  2. url: The URL where the webhook sends the request.
  3. isActive: A Boolean indicating whether the subscription is active or not.
  4. events: An array of subscribed events.
  5. createdAt: The date and time when the subscription was created.
  6. updatedAt: The date and time when the subscription was last updated.
  1. type Event {
    id: ID!
    name: String!
    createdAt: DateTime!
    updatedAt: DateTime!
    }
    - This output type represents the event object. It contains the following fields:
  1. id: The UUID of the event.
  2. name: The name of the event.
  3. createdAt: The date and time when the event was created.
  4. updatedAt: The date and time when the event was last updated.
TABLE OF CONTENTS