Veriff is acquiring Vespia.
Read more here

API documentation

Api

General information

There are two environments for working with Vespia API: Development and Production.
Development environment dedicated to supporting the development of your application. It uses two endpoints for additional security measures - one for authentication and the other for data exchange.
The production environment, as the name says, is for using Vespia API on the production.
To switch from Development to production, you must change endpoints and repeat the SignIn step from authentication to get a new access token.
All requests to this API must contain the authorization token:
Authorization: Bearer $token
In this documentation, we are using the Development environment in the examples.
You can test data exchange API using the ApolloGraphQL client using this link. Alternatively, you can use Postman for tests. In this case, please make sure you use GraphQL Explorer to test the API, more details on how to use GraphQL with Postman: https://blog.postman.com/announcing-postmans-new-graphql-client/

Authentication

To access the data exchange endpoint (https://dev-api.vespia.io/my/graphql) you must send the access token in the Authorization header of each request.
Access token and its update
  • Start with registering in the system. For development purposes, please create an account at https://dev-my.vespia.io/sign-up. Remember your login email and password.
    ‍
  • To receive the access token, you should use the signIn mutation in GraphQL or HTTP request way.
    ‍
    ⚠️Important: Your request must include the HTTP header - "Origin: https://vespia.io", when calling the signIn mutation. In backend scripts, CLI tools, or API clients (e.g. Postman, curl), you must add it manually. Requests without this header will be rejected.
    ‍
  • When you switch from the Development to the Production environment, please use your account created at https://my.vespia.io/sign-up
Operation example
Authorization: Bearer $token
Variables example
{
 "input": {
   "email": "john@example.com",
   "password": "E4Wd9Rdos-wij+$38weEE"
 }
}
Operation example
{
  "data": {
    "refreshTokenPair": {
      "refreshToken": "refresh-session:f82ec32d-e0c9-4846-8b64-8ca2d76514d1",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50SWQiOiIwZGI
      4MTY1NS04OTNlLTRjZjUtYTMzOS0yMjM1YjY1YTE3NjkiLCJlbWFpbCI6ImFsb3ppbnNre
      UBtZS5jb20iLCJpc0FkbWluIjpmYWxzZSwiYWNjb3VudEdyb3VwcyI6W10sImlhdCI6MTcwNzkyNz
      M2MywiZXhwIjoxNzA4NTI3MzYzfQ.27w7yo496JwQshA3MyHQ37OyeGdE3yR0XCg2047CDAQ"
    }
  }
}
Object types and field descriptions.
Object type Field Description
SignInInput email : String Account email
password : String Account password
refreshTokenPair refreshToken : String Use its value as an argument in the refreshTokenPair mutation
token : String Use its value as the access token in the Authorization header of each request
For security reasons, the access token expires within 10 minutes. After that time, you have to refresh it using the refreshTokenPair mutation.
Operation example
mutation refreshTokenPair ($input: RefreshTokenPairInput!) {
 refreshTokenPair(input: $input) {
   refreshToken
   token
 }
}
Variables example
{
 "input": {
   "email": "john@example.com",
   "password": "E4Wd9Rdos-wij+$38weEE"
 }
}
Object types and field descriptions
Object type Field Description
RefreshTokenPairInput refreshToken : String RefreshToken value from previous refreshTokenPair or signIn request, depending on which was the latest
refreshTokenPair refreshToken : String Use its value as an argument in the refreshTokenPair mutation
token : String Use its value as the access token in the Authorization header of each request
Diagram
auth
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.
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.
Playground

Verification procedure

Companies search

Company search is an essential step before performing KYB verification. A company search should be conducted for the following reasons: 
‍
 • It is necessary to ensure that the company's data exists in the registrar's records so that a request for detailed     company information can be made in the next step;
‍
  • When requesting KYB verification, it is mandatory to provide the company's registration code. Therefore, if you     do not know the exact registration code or are unsure of its correctness, you need to perform a company     search. The response will return the exact registration code for further use;
A company search can be performed using either the company name or the registration code.
You can perform a search using both the company name and the registration code simultaneously. However, if you do not use one of the parameters, simply omit this field from the request instead of passing an empty string.
The countryCode parameter is required for all company search requests. It must follow the ISO 3166 standard:
  • Use ISO 3166-1 alpha-2 codes for countries (e.g., DE, FR, US, GB, CA)
  • Use ISO 3166-2 codes for sub-national jurisdictions when applicable (e.g., US states or Canadian provinces).
Country code examples
Country code Country / Jurisdiction
EE Estonia
DE Germany
US United States
US-CA United States – California
US-NY United States – New York
CA Canada
CA-ON Canada – Ontario
CA-QC Canada – Quebec
To perform a company search, use the SearchLegalEntities query. The response will contain a searchLegalEntities field, which is an array that includes all matching company search results. You will then need to select the most suitable result for your needs.
⚠️Important: When selecting a company from the searchLegalEntities array, you must choose the correct company based on its registrationCode. Once selected, you should pass the entire object from the array, as it contains all relevant company data. This is crucial because the object may include additional details required for the KYB request, such as an extra kybResponseId.

The selected company object must be passed as an input parameter for the mutation RequestKybVerification. This ensures that all necessary company details, including possible additional kybResponseId fields, are included in the KYB verification request (Example is in the KYB verification (Business) section).
Operation example
query SearchLegalEntities($input: SearchLegalEntitiesInput!) {
  searchLegalEntities(input: $input) {
    name
    registrationCode
    countryCode
    kybResponseId
  }
}
Variables example
{
  "input": {
    "name": "Vespia",
    "registrationCode": "16017942",
    "countryCode": "EE",
  }
}

---OR---

{
  "input": {
    "name": "Vespia",
    "countryCode": "EE",
  }
}

---OR---

{
  "input": {
    "registrationCode": "16017942",
    "countryCode": "EE",
  }
}
Response example
{
  "data": {
    "searchLegalEntities": [
      {
        "name": "Vespia OÜ",
        "registrationCode": "16017942",
        "countryCode": "EE",
        "kybResponseId": null
      },
      .......
    ]
  }
}
Object types and field descriptions
Object type Field Description
Country code : ID! The country's two-symbol Code
name : String! The country name
isBusinessAvailable : Boolean! true if the country is fast
isVatAvailable : Boolean! true if the VAT number available
isUboAvailable : Boolean! true if UBO information available
isDocumentAvailable : Boolean! true if company registration documents are available. the isBusinessAvailable field is false and isDocumentAvailable is true, then the country is slow.
isDemo : Boolean! true if the country is available in the Demo environment

KYB verification (Business)

Note: Registry responses are dependent on the data available from each national business register. The structure, fields, and level of detail returned may vary by jurisdiction.
‍
To perform business verification (KYB), you must start with the requestKybVerification mutation. It returns an array of EntityCheck objects
Operation example
mutation RequestKybVerification($input: RequestKybVerificationInput!) {
 requestKybVerification(input: $input) {
   id
   type
   status
   result
   dataRequestInfo
   dataRequestId
   folderId
   comment
   input
   createdAt
   updatedAt
   expiredAt
   account {
     id
     groupId
   }
 }
}
Variables example
{
 "input": {
   "countryCode": "EE",
   "name": "Vespia",
   "registrationCode": "EE102360253",
   "kybResponseId": null
 }
}
Response example
{
 "data": {
   "requestKybVerification": [
     {
       "id": "09130a7e-a06c-4256-a83e-390431ffb294",
       "type": "BUSINESS_INFO",
       "status": "AWAITING_CHECK",
       "result": null,
       "dataRequestInfo": null,
       "dataRequestId": "32689c3b-3bf3-483f-9825-44d4961d8cbb",
       "folderId": "21831f3d-ca25-44a0-9096-f77d34340d1f",
       "comment": null,
       "input": {
         "name": "Vespia",
         "countryCode": "EE",
         "registrationCode": "EE102360253",
         "account": {
           "accountId": "0db81655-893e-4cf5-a339-2235b65a1769"
         },
         "folderId": "21831f3d-ca25-44a0-9096-f77d34340d1f",
         "isCorporate": true
       },
       "createdAt": "2024-02-18T10:51:30.320Z",
       "updatedAt": "2024-02-18T10:51:30.320Z",
       "expiredAt": null,
       "account": {
         "id": "0db81655-893e-4cf5-a339-2235b65a1769",
         "groupId": null
       }
     },
     {
       "id": "584779fd-908e-4ff3-9c74-c4fa7b7014dd",
       "type": "UBO",
       "status": "AWAITING_CHECK",
       "result": null,
       "dataRequestInfo": null,
       "dataRequestId": "7afd17cb-99b3-4c07-bd16-3838e8d9366c",
       "folderId": "21831f3d-ca25-44a0-9096-f77d34340d1f",
       "comment": null,
       "input": {
         "name": "Vespia",
         "countryCode": "EE",
         "registrationCode": "EE102360253",
         "account": {
           "accountId": "0db81655-893e-4cf5-a339-2235b65a1769"
         },
         "folderId": "21831f3d-ca25-44a0-9096-f77d34340d1f",
         "isCorporate": true
       },
       "createdAt": "2024-02-18T10:51:30.320Z",
       "updatedAt": "2024-02-18T10:51:30.320Z",
       "expiredAt": null,
       "account": {
         "id": "0db81655-893e-4cf5-a339-2235b65a1769",
         "groupId": null
       }
     },
     {
       "id": "fd5f3a0a-f8a8-42db-afcc-916c1bd5dcf9",
       "type": "VAT",
       "status": "AWAITING_CHECK",
       "result": null,
       "dataRequestInfo": null,
       "dataRequestId": "eaa13b12-d577-4d71-8df7-70b366420407",
       "folderId": "21831f3d-ca25-44a0-9096-f77d34340d1f",
       "comment": null,
       "input": {
         "countryCode": "EE",
         "name": "Vespia"
       },
       "createdAt": "2024-02-18T10:51:30.320Z",
       "updatedAt": "2024-02-18T10:51:30.320Z",
       "expiredAt": null,
       "account": {
         "id": "0db81655-893e-4cf5-a339-2235b65a1769",
         "groupId": null
       }
     }
   ]
 }
}
Object types and field descriptions
Object type Field Description
RequestKybVerificationInput name : String Entity name. Can be a partial name. Should contain at least one symbol.
registrationCode : String! Entity registration number.
countryCode : String! Country code of the entity. You can get the complete list by using the Countries query.
EntityCheck id : ID! The UUID of the check.
type : String The type of check performed. See details below.
status : String The status of the check.
result : JSON The result of the verification in JSON format.
dataRequestId : UUID The UUID of the data request.
dataRequestInfo : JSON Additional information about the data request in JSON format.
folderId : String The folder ID of the check.
comment : String The check comment
input : JSON The input provided for the check, JSON format.
input: {isCorporate : Boolean} Determines what type of entity checked: legal entity (true) or private person (false)
createdAt : DateTime The date and time when the check was initiated.
updatedAt : DateTime The date and time when the check was last updated.
expiredAt : DateTime The date and time when the check will expire
account : AccountDTO The account of the check owner.
Diagram
kyb/kyc
BUSINESS_INFO response example
{
   "name": "Vespia OÜ",
   "registrationCode": 16017942,
   "country": "Estonia",
   "address": "Harju maakond, Tallinn, Põhja-Tallinna linnaosa, Niine tn 11, 10414",
   "isCorporate": true,
   "kmkr": "EE102360253",
   "legalForm": "OÜ",
   "businessActivity": "62.10 - Computer programming activities",
   "status": "Entered into the register",
   "incorporateDate": "2020-07-28T00:00:00.000Z",
   "capital": "10350.66 EUR",
   "financialYear": {
      "date": {
         "start": "2024-01-01T00:00:00.000Z",
         "end": "2024-12-31T00:00:00.000Z"
      }
   },
   "numberOfEmployees": 2,
   "predecessors": [
      "Kanne on tehtud äriregistri seaduse § 70 lõike 1 alusel."
   ],
   "contacts": {
      "emails": [
         "info@vespia.io"
      ],
      "websites": [
         "https://vespia.io/"
      ],
      "phoneNumbers": [
      ],
      "faxes": [
      ]
   },
   "rights": {
      "representation": [
         "Every member of the Management Board may represent the private limited company in concluding all transactions."
      ]
   },
   "extraData": {
      "kmkr": "EE102360253"
   },
   "relatedEntities": [
      {
         "name": "Kaarel Kotkas",
         "registrationCode": "39409301919",
         "isCorporate": false,
         "relation": {
            "roles": [
               "Management board member"
            ],
            "date": {
               "start": "2026-03-03T00:00:00.000Z"
            }
         }
      },
      {
         "name": "Julia Ront",
         "registrationCode": "49202210286",
         "country": "Estonia",
         "isCorporate": false,
         "share": {
            "size": 2500,
            "currency": "EUR",
            "type": "Sole property"
         },
         "relation": {
            "roles": [
               "Founder"
            ],
            "date": {
               "start": "2020-07-28T00:00:00.000Z"
            }
         }
      },
      {
         "name": "Veriff OÜ",
         "registrationCode": "12932944",
         "country": "Estonia",
         "isCorporate": true,
         "share": {
            "size": 10350.66,
            "currency": "EUR",
            "type": "Sole property",
            "percentage": 100
         },
         "relation": {
            "roles": [
               "Shareholder"
            ],
            "date": {
               "start": "2026-02-13T00:00:00.000Z"
            }
         }
      }
   ]
}
BUSINESS_INFO JSON Schema
{
    "type": "object",
    "properties": {
        "legalForm": {
            "type": "string"
        },
        "businessActivity": {
            "type": "string"
        },
        "status": {
            "type": "string"
        },
        "incorporateDate": {
            "type": "string"
        },
        "relatedEntities": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "registrationCode": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "country": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "address": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "isCorporate": {
                        "type": "boolean"
                    },
                    "share": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "properties": {
                            "type": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "size": {
                                "type": [
                                    "string",
                                    "number",
                                    "null"
                                ]
                            },
                            "currency": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "percentage": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            }
                        }
                    },
                    "personalData": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "properties": {
                            "birthDay": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "date-time"
                            },
                            "localName": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "contacts": {
                                "type": [
                                    "object",
                                    "null"
                                ],
                                "properties": {
                                    "emails": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "websites": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "phoneNumbers": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "faxes": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "socialNetworks": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                }
                            },
                            "nation": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            }
                        }
                    },
                    "relation": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "properties": {
                            "roles": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "representationRights": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "rights": {
                                "type": [
                                    "object",
                                    "null"
                                ],
                                "properties": {
                                    "representation": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "signature": {
                                        "type": [
                                            "boolean",
                                            "null"
                                        ]
                                    }
                                }
                            },
                            "date": {
                                "type": [
                                    "object",
                                    "null"
                                ],
                                "properties": {
                                    "start": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "format": "date-time"
                                    },
                                    "end": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "format": "date-time"
                                    }
                                }
                            }
                        }
                    },
                    "personStatus": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            }
        },
        "registerCourt": {
            "type": [
                "string",
                "null"
            ]
        },
        "capital": {
            "type": [
                "string",
                "null"
            ]
        },
        "extraData": {
            "type": [
                "object",
                "null"
            ],
            "properties": {
                "otherName": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "translatedAddress": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "oldName": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "lei": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "englishName": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "dissolutionDate": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "format": "date-time"
                },
                "predecessors": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "kmkr": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "registrationInstitution": {
                    "type": [
                        "string",
                        "null"
                    ]
                }
            }
        },
        "assignees": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "financialYear": {
            "type": [
                "object",
                "null"
            ],
            "properties": {
                "date": {
                    "type": [
                        "object",
                        "null"
                    ],
                    "properties": {
                        "start": {
                            "type": [
                                "string",
                                "null"
                            ],
                            "format": "date-time"
                        },
                        "end": {
                            "type": [
                                "string",
                                "null"
                            ],
                            "format": "date-time"
                        }
                    }
                }
            }
        },
        "contacts": {
            "type": [
                "object",
                "null"
            ],
            "properties": {
                "emails": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "websites": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "phoneNumbers": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "faxes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "socialNetworks": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "rights": {
            "type": [
                "object",
                "null"
            ],
            "properties": {
                "representation": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "signature": {
                    "type": [
                        "boolean",
                        "null"
                    ]
                }
            }
        },
        "numberOfEmployees": {
            "type": [
                "string",
                "number",
                "null"
            ]
        },
        "liquidated": {
            "type": [
                "boolean",
                "null"
            ]
        },
        "hasInsolvencyHistory": {
            "type": [
                "boolean",
                "null"
            ]
        },
        "registeredOfficeIsInDispute": {
            "type": [
                "boolean",
                "null"
            ]
        },
        "source": {
            "type": [
                "object",
                "null"
            ],
            "properties": {
                "sourceName": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "sourceUrl": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "dateOfData": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "format": "date-time"
                }
            }
        },
        "mostRecentData": {
            "type": [
                "object",
                "null"
            ],
            "properties": {
                "mostRecent": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "previousNames": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "companyName": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "startDate": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "endDate": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    }
                }
            }
        },
        "alternativeNames": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "companyName": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "language": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "startDate": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    }
                }
            }
        },
        "officeType": {
            "type": [
                "string",
                "null"
            ]
        },
        "companyBranchStatus": {
            "type": [
                "string",
                "null"
            ]
        },
        "companyIdentifiers": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "companyIdentifierCodeName": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "companyIdentifierUID": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            }
        },
        "mainSourceName": {
            "type": [
                "string",
                "null"
            ]
        },
        "requestTime": {
            "type": [
                "string",
                "null"
            ],
            "format": "date-time"
        },
        "lastUpdate": {
            "type": [
                "string",
                "null"
            ],
            "format": "date-time"
        },
        "currency": {
            "type": [
                "string",
                "null"
            ]
        },
        "mainSourceAdditionnalInfo": {
            "type": [
                "string",
                "null"
            ]
        },
        "taxCode": {
            "type": [
                "string",
                "null"
            ]
        },
        "ownershipType": {
            "type": [
                "string",
                "null"
            ]
        },
        "dateOfLicense": {
            "type": [
                "string",
                "null"
            ],
            "format": "date-time"
        },
        "managingDirectors": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "additionalBusinessPurpose": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "reportUrl": {
            "type": [
                "string",
                "null"
            ]
        }
    },
    "required": [
        "legalForm",
        "businessActivity",
        "status",
        "incorporateDate",
        "name",
        "isCorporate"
    ]
}

KYC verification (Person)

To perform customer verification (KYC), you must start with the requestKycVerification mutation. It returns an array of EntityCheck objects
Operation example
{
 "input": {
   "country": "UK",
   "gender": "male",
   "kind": "ID",
   "name": [
     "Boris",
     "Johnson"
   ],
   "dob": "June 19, 1964",
   "email": "boris.johnson@example.com"
 }
}
Variables example
{
 "data": {
   "requestKycVerification": [
     {
       "id": "90b75ea3-0bc6-4f80-a633-6bf79c01616a",
       "type": "ID",
       "status": "AWAITING_CHECK",
       "result": null,
       "dataRequestInfo": null,
       "dataRequestId": "d3c56dbf-4d52-4b97-b75c-a3fb59bee3cd",
       "folderId": "878e1dae-6601-4f76-a33d-376fb0136929",
       "comment": null,
       "input": {
         "sendEmailNotification": true,
         "name": "Boris Johnson",
         "email": "boris.johnson@example.com",
         "dob": "June 19, 1964",
         "gender": "male",
         "country": "UK",
         "account": {
           "accountId": "0db81655-893e-4cf5-a339-2235b65a1769"
         },
         "folderId": "878e1dae-6601-4f76-a33d-376fb0136929",
         "isCorporate": false
       },
       "createdAt": "2024-02-18T13:35:34.137Z",
       "updatedAt": "2024-02-18T13:35:34.137Z",
       "expiredAt": null,
       "account": {
         "id": "0db81655-893e-4cf5-a339-2235b65a1769",
         "groupId": null
       }
     }
   ]
 }
}
Object types and field descriptions
Object type Field Description
RequestKycVerificationInput _amlBindingId : String
name : [String]! The name of the entity. ['first name', 'middle name', 'last name'] or ['name']
kind : RequestKycVerificationKind! The kind of verification to be performed. This field is required, and it can be one of the following: "ID", "AML", or "BOTH": ID: Perform identity verification only. AML: Perform AML and Google Search checks only. BOTH: Perform identity, AML, and Google Search checks.
country : String The country of the entity. Is necessary for kind = AML.
dob : String The date of birth of the entity. Is necessary for kind = AML.
email : String The email of the entity. Mandatory if kind = "ID" or "BOTH". Otherwise, the ID check will not start.
gender : String The gender of the entity. Is necessary for kind = AML.
EntityCheck type : String The type of check performed. See details below.
dataRequestInfo : JSON Additional information about the data request in JSON format.
folderId : String The folder ID of the check.
comment : String The check comment
input : JSON The input provided for the check, JSON format.
input: {isCorporate : Boolean} Determines what type of entity checked: legal entity (true) or private person (false)
createdAt : DateTime The date and time when the check was initiated.
updatedAt : DateTime The date and time when the check was last updated.
expiredAt : DateTime The date and time when the check will expire
account : AccountDTO The account of the check owner.
Diagram
kyb/kyc
Playground

More information about checks

To get more information about every check from the array EntityCheck, use the query Folder with the correspondent value of folderId as the argument. In this context, a folder should be considered a global entity that contains all the information about your verification.

When all entity checks are completed in a Folder, the status field in the response to the query Folder should be Completed. Accordingly, you will be able to find the results of all checks, such as AML, in the response.

When you make a folder request, the response contains one of the fields, which is called entities, it contains an array. Entities are all persons and companies that belong to the company you are checking. Accordingly, in this array of entities, each entity contains entityChecks, these are checks that you performed on the entity, for example, AML or ID.
Operation example
query Folder($folderId: UUID!) {
  folder(id: $folderId) {
    id
    name
    subCustomerEmail
    account {
      id
      email
      createdAt
      updatedAt
      profile
      accountGroups {
        id
        name
        domain
        isProPlan
        isAmlMonitoringAvailable
        isRiskScoringAvailable
      }
    }
    metadata
    isKyc
    isArchived
    rootEntityId
    status
    entities {
      id
      info
      idMonitoring
      dataRequestInfo
      createdBy
      entityChecks {
        id
        type
        status
        result
        dataRequestInfo
        dataRequestId
        folderId
        comment
        input
        createdAt
        updatedAt
        expiredAt
        createdBy
      }
      createdAt
      updatedAt
    }
    createdAt
    updatedAt
    comments {
      id
      createdAt
      body


      name
    }
    folderOnboardingLink
  }
}
Variables example
{
  "folderId": "7aafc693-c27f-4dd6-a5d1-93fe30f4f8fd"
}
Object types and field descriptions
Object type Field Description
Folder id : ID The UUID of the folder.
account : Account The account of the check owner.
assets : [AssetView]! An array of added assets.
comments : [Comment]! An array of comments to the folder.
createdAt : DateTime
entities : [Entity] An array of Entity objects related to the folder.
isArchived : Boolean A Boolean indicating whether the folder was archived or not.
isKyc : Boolean A Boolean indicates whether the folder is KYC verifications or not.
metadata : JSON Additional metadata in JSON format.
name : String The name of the folder.
rootEntityId : UUID The UUID of the root entity in the folder.
status : String The status of the folder.
subCustomerEmail : String
updatedAt : DateTime
folderOnboardingLink : String The URL is manually generated in the Dashboard for onboarding. The URL is generated only once and does not change again.
AssetView id : ID! The UUID of the asset.
label : String A label of the asset.
name : String A name of the asset.
createdAt : DateTime
file : File A file details (extension, path, URL).
Comment id : String
name : String Subject of the comment.
author : AccountPreview The comment author account details (email, group, isAdmin).
body : String The comment itself.
createdAt : String
Entity id : ID! The UUID of the entity.
info : JSON The entity information.
idMonitoring : Boolean A Boolean indicating whether the monitoring for the entity switched on {true} or off {false}.
entityChecks : [EntityCheck] An array of EntityCheck objects associated with the entity.
createdAt : DateTime
updatedAt : DateTime
relation : [Relation] An array of Relation objects associated with the entity. Stores data in JSON format.
comments : [Comment]! An array of comments to the entity.

Entity checks

To apply additional checks for entities from fast countries or to proceed with checks for entities from slow countries, you must use the requestEntityChecks mutation that takes the RequestEntityCheckInput scalar type as argument. For more details, look at the explanation in the Variables example part.
How to get entity check results, for example for AML:
1. When you perform an AML entityCheck, you get a verification ID
2. When there is an update in the verification, the webhook provides your verification ID. Webhooks are described in the section Real-time updates (Webhook)
3. You take this ID and query Folder data by ID.
Operation example
mutation RequestEntityChecks($input: RequestEntityCheckInput!) {
 requestEntityChecks(input: $input) {
   id
   status
   result
   dataRequestInfo
   dataRequestId
   folderId
   comment
   input
   createdAt
   updatedAt
   expiredAt
   type
   account {
     id
     groupId
   }
 }
}
Variables example
{
"input": [
  {"type": "BUSINESS_INFO",
   "folderId": "21831f3d-ca25-44a0-9096-f77d34340d1f",
   "isCorporate": true,
   "input": {
     "countryCode": "EE",
     "name": "Vespia",
     "registrationCode": "EE102360253"}
  },
  {"type": "AML",
   "entityId": "88e9540e-9e96-419d-9e8f-9670e2a80fd3",
   "isCorporate": false,
   "input": {
     "name": ["Boris", null, "Johnson"],
     "dob": "06/14/1946",
     "gender": "male",
     "country": "UK"}
  }]}
To pass correctly formatted scalar RequestEntityCheckInput! you must use an array containing elements that include
{
 "type": string!,
 "folderId": string!,
 "entityId": string!?,
 "isCorporate": boolean?,
 "input": {depends on the type value, see table below}!,
}
Use the following pairs of corresponding “type” and “input” as arguments
“type” value (mandatory) “input” arguments (mandatory) Description Applicable To
BUSINESS_INFO {
"name": string,
"registrationCode": string,
"countryCode": string
}		 Business check of the company Company
AML {
"name": string[],
"gender"?: string (male or female),
"dob"?: string,
"country"?: string
}		 AML check of the company or person.
The name property must be an array containing three elements: [firstName, middleName, surname]. If there is no middle name, set the second element to null.		 Company / Person
EIN {
"name": string,
"searchValue": string (EIN)
} 		Search and validation of an Employer Identification Number (EIN).
The name field is the legal name of the company, and searchValue is the EIN number to validate. 		Company
TIN {
"name": string,
"searchValue": string (TIN/SSN)
} 		Search and validation of a Tax Identification Number (TIN).
In the frontend, this type is represented as SSN. 		Person
ID {
"name": string,
"email": string,
"sendEmailNotification": boolean
}		 ID check of the person that will be sent to the provided email. Person
QUESTIONNAIRE {
"email": string,
"sendEmailNotification": boolean
}		 Questionnaire sent to the specified email. Requires "entityId". Person
DOCUMENT {
"documents": string[],
"requestDescription"?: string,
"filler"?: { "email"?: string },
"sendEmailNotification": boolean
}		 Request for additional documents. Requires "entityId". Person
VAT {
"countryCode": string,
"name": string
}		 VAT check of the company. Company
GOOGLE_SEARCH {
"name": string[]
}		 Find AML data of a person or company via Google search. Company / Person
ADDITIONAL_INFO {
"additionalInfo": string
}		 Requires "entityId". Person / Company
metadata : JSON Additional metadata in JSON format. —
name : String The name of the folder. —
rootEntityId : UUID The UUID of the root entity. —
status : String The status of the folder. —
subCustomerEmail : String —
updatedAt : DateTime —
AssetView id : ID! The UUID of the asset. —
label : String A label of the asset. —
name : String A name of the asset. —
createdAt : DateTime —
file : File File details (extension, path, URL). —
Comment id : String —
name : String Subject of the comment. —
author : AccountPreview Author details (email, group, isAdmin). —
body : String The comment text. —
createdAt : String —
Entity id : ID! UUID of the entity. —
info : JSON Entity information. —
idMonitoring : Boolean Monitoring on/off state. —
entityChecks : [EntityCheck] Checks associated with the entity. —
createdAt : DateTime —
updatedAt : DateTime —
relation : [Relation] JSON array of related entities. —
comments : [Comment]! Entity comments. —
Response example
{
 "data": {
   "requestEntityChecks": [
     {
       "id": "abacba50-61e5-4e18-8cc8-da17419c9dcd",
       "status": "AWAITING_CHECK",
       "result": null,
       "dataRequestInfo": null,
       "dataRequestId": "f261fd1e-8a26-41bb-b70e-5aeefd11b7f5",
       "folderId": "21831f3d-ca25-44a0-9096-f77d34340d1f",
       "comment": null,
       "input": {
         "name": "Vespia",
         "countryCode": "EE",
         "registrationCode": "EE102360253",
         "account": {
           "accountId": "0db81655-893e-4cf5-a339-2235b65a1769"
         },
         "folderId": "21831f3d-ca25-44a0-9096-f77d34340d1f",
         "isCorporate": true
       },
       "createdAt": "2024-02-23T11:58:29.382Z",
       "updatedAt": "2024-02-23T11:58:29.382Z",
       "expiredAt": null,
       "type": "BUSINESS_INFO",
       "account": {
         "id": "0db81655-893e-4cf5-a339-2235b65a1769",
         "groupId": null
       }
     },
     {
       "id": "c3a22e14-4cdc-41a9-9856-a8a45fe70f85",
       "status": "AWAITING_CHECK",
       "result": null,
       "dataRequestInfo": null,
       "dataRequestId": "3abe9135-de87-42c3-ae5c-db93db592dd8",
       "folderId": "21831f3d-ca25-44a0-9096-f77d34340d1f",
       "comment": null,
       "input": {
         "isCorporate": false,
         "name": "Boris Johnson",
         "gender": "male",
         "dob": "June 19, 1964",
         "country": "UK"
       },
       "createdAt": "2024-02-23T11:58:29.382Z",
       "updatedAt": "2024-02-23T11:58:29.382Z",
       "expiredAt": null,
       "type": "AML",
       "account": {
         "id": "0db81655-893e-4cf5-a339-2235b65a1769",
         "groupId": null
       }
     }
   ]
 }
}

AML Monitoring

To enable AML monitoring use mutation EnableEntityCheckMonitoring with enableEntityCheckMonitoringId argument corresponding to the entity check with "type": "AML"
To disable AML monitoring, use mutation disableEntityCheckMonitoring using the same argument

Page queries

In some cases, you will need pagination and filtering of data. To do so, use input: PagedQueryInput type. Below is an example query to get a list of your verifications i.e. Folders.
Operation example
query Folders($input: PagedQueryInput) {
  folders(input: $input) {
    content {
      id
      isKyc
      name
    }
    totalPages
    totalElements
    last
    first
    size
    number
    numberOfElements
  }
}
Variables example
{
 "input": {
   "pageRequest": {
     "page": 2,
     "size": 10,
     "sort": [
       {
         "direction": "ASC",
         "field": "Id"
       }
     ]
   },
   "filter": [
     {
       "comparators": [
         {
           "field": "isActive",
           "type": "IS",
           "value": "true"
         }
       ],
       "operator": "AND"
     }
   ]
 }
}
Response example
{
  "data": {
    "folders": {
      "content": [
        {
          "id": "08e7b3d9-6eeb-4f39-8844-52f15664f160",
          "isKyc": false,
          "name": "Vespia OÜ"
        },
        {
          "id": "e68c6e98-753e-45ed-a91d-4c71d85720b1",
          "isKyc": false,
          "name": "Vespia OÜ"
        },
        {
          "id": "ef9104bf-f12e-44b9-bb82-8a190b7dfe9c",
          "isKyc": false,
          "name": "Vespia OÜ"
        },
        {
          "id": "75ba70cd-6327-46d5-a509-e1c2b321bd14",
          "isKyc": false,
          "name": "Vespia OÜ"
        },
        {
          "id": "273eceba-90b6-427a-9d45-da9984d578a9",
          "isKyc": false,
          "name": "Vespia OÜ"
        }
      ],
      "totalPages": 63,
      "totalElements": 313,
      "last": false,
      "first": true,
      "size": 5,
      "number": 1,
      "numberOfElements": 5
    }
  }
}
Input structure, types, and field descriptions
Object type Field Description
pageRequest : PageRequestInput page : Int The page number of the pagination
size : Int The number of items per page
sort : [SortInput!] sort field defines sorting rules
SortInput direction : SortDirection Enum, the sort direction, which can be either "ASC" or "DESC"
field : String The field to sort by
filter : [FilterInput] operator : FilterOperator Enum, the filter operator, which can be either "AND" or "OR"
comparators : [FilterComparatorInput] Defines separate comparator
FilterComparatorInput field : String The field to filter by
type : FilterComparatorType Enum type = {IS, IS_NOT, EQ, NEQ, GT, GTE, LT, LTE, LIKE, NOT_LIKE, I_LIKE, NOT_I_LIKE, IN, NOT_IN, BETWEEN}
value : AnyValue 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 you to retrieve the data you need with the desired pagination and filtering options.
rootEntityId : UUID The UUID of the root entity in the folder.
status : String The status of the folder.
subCustomerEmail : String
updatedAt : DateTime
AssetView id : ID! The UUID of the asset.
label : String A label of the asset.
name : String A name of the asset.
createdAt : DateTime
file : File A file details (extension, path, URL).
Comment id : String
name : String Subject of the comment.
author : AccountPreview The comment author account details (email, group, isAdmin).
body : String The comment itself.
createdAt : String
Entity id : ID! The UUID of the entity.
info : JSON The entity information.
idMonitoring : Boolean A Boolean indicating whether the monitoring for the entity switched on {true} or off {false}.
entityChecks : [EntityCheck] An array of EntityCheck objects associated with the entity.
createdAt : DateTime
updatedAt : DateTime
relation : [Relation] An array of Relation objects associated with the entity. Stores data in JSON format.
comments : [Comment]! An array of comments to the entity.

Subscription for real-time information updates (Webhook)

To get access to real-time information updates, we use webhooks. To start using it, you must create a subscription and link it with specific events. This flow is shown in the diagram above.
Please note that you only need to create a subscription once. You do not need to create multiple subscriptions. After creating a subscription as shown below, all the necessary data will be sent to your URL, when events occur.
Diagram
webhooks
Below is a three-step process (with a sample query and sample input parameters) that will help you subscribe to an event and use the subscription in your project. For example, you can track changes that occur in your checks in a dashboard, and the example below demonstrates this:
1. Let's get the list of events - query Events. You need to get the event "id" with the name "event.verificationView.built" from the response:
Operation example
query Events($input: PagedQueryInput!) {
  events(input: $input) {
    content {
      id
      name
      createdAt
      updatedAt
    }
  }
}
Variables example
{
  "input": {
    "pageRequest": {
      "page": 1,
      "size": 10,
      "sort": []
    }
  }
}
Output example
{
  "data": {
    "events": {
      "content": [
        {
          "id": "af6918ac-2322-4aba-9341-19e711609289",
          "name": "event.order.created",
          "createdAt": "2022-05-17T06:51:45.317Z",
          "updatedAt": "2022-05-17T06:51:45.317Z"
        },
        {
          "id": "060756a2-0843-404f-96de-7ff48933ed16",
          "name": "event.verificationView.built",
          "createdAt": "2022-05-17T06:51:45.317Z",
          "updatedAt": "2022-05-17T06:51:45.317Z"
        },
        {
          "id": "766f5720-b995-4dfd-95c2-0e4e5d20a03a",
          "name": "event.wallet.updated",
          "createdAt": "2022-05-17T06:51:45.317Z",
          "updatedAt": "2022-05-17T06:51:45.317Z"
        }
      ]
    }
  }
}
2. Create subscription - mutation CreateWebhookSubscription. By default, the subscription is activated immediately after creation.

You need to pass your URL as an input parameter, to which our server will automatically send HTTP POST requests.

From the response, you need to get the "id" of the createWebhookSubscription.
Operation example
mutation CreateWebhookSubscription($input: CreateWebhookSubscriptionInput!) {
  createWebhookSubscription(input: $input) {
    id
    url
    isActive
    events {
      id
      name
      createdAt
      updatedAt
    }
    createdAt
    updatedAt
  }
}
Variables example
{
  "input": {
    "url": "https://yourdomain.com/webhook-endpoint"
  }
}
Output example
{
  "data": {
    "createWebhookSubscription": {
      "id": "9e3a7978-1040-49c3-979f-6485986779f2",
      "url": "https://vespia-webhook-url.com",
      "isActive": true,
      "events": [],
      "createdAt": "2025-01-02T14:31:17.299Z",
      "updatedAt": "2025-01-02T14:31:17.299Z"
    }
  }
}
3. In the input parameters, we specify both identifiers obtained in the first and second steps, which we assign to the property names accordingly - "eventId" and "subscriptionId"
Operation example
mutation SubscribeOnEvent($input: SubscribeOnEventInput!) {
  subscribeOnEvent(input: $input) {
    id
    url
    isActive
    events {
      id
      name
      createdAt
      updatedAt
    }
  }
}
Variables example
{
  "input": {
    "subscriptionId": "9e3a7978-1040-49c3-979f-6485986779f2",
    "eventId": "060756a2-0843-404f-96de-7ff48933ed16"
  }
}
Example of deactivating a subscription
In the input parameter, you must pass the subscription "id" that was created earlier in the first step.
Operation example
mutation DeactivateWebhookSubscription($deactivateWebhookSubscriptionId: UUID!) {
  deactivateWebhookSubscription(id: $deactivateWebhookSubscriptionId) {
    id
    url
    isActive
    events {
      id
      name
      createdAt
      updatedAt
    }
    createdAt
    updatedAt
  }
}
Variables example
{
  "deactivateWebhookSubscriptionId": "0a68dc26-1afb-4dd1-ba64-3a196321cf41"
}
There are 3 events available currently:
  • event.order.created - fires when a new order is created.
  • event.verificationView.built - fires when there are updates in the folder.
  • event.wallet.updated - fires when the wallet is updated
  • To get an actual list of events and their IDs use query Events
There are 3 events To manage subscriptions, use the following mutations:
The mutation name Description Description
CreateWebhookSubscription(input: CreateWebhookSubscriptionInput!): WebhookSubscription! Used to create a subscription. The required input is the URL where the webhook will send the request. The returned output is the newly created webhook subscription WebhookSubscription object. The page number of the pagination
ActivateWebhookSubscription( activateWebhookSubscriptionId: UUID!): WebhookSubscription! 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 WebhookSubscription object. Please note that you can Activate only subscriptions with "isActive": false The number of items per page
DeactivateWebhookSubscription( deactivateWebhookSubscriptionId: UUID!): WebhookSubscription! 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 WebhookSubscription object. Please note that you can Deactivate only subscriptions with "isActive": true sort field defines sorting rules
SortInput direction : SortDirection Enum, the sort direction, which can be either "ASC" or "DESC"
field : String The field to sort by
filter : [FilterInput] operator : FilterOperator Enum, the filter operator, which can be either "AND" or "OR"
comparators : [FilterComparatorInput] Defines separate comparator
FilterComparatorInput field : String The field to filter by
type : FilterComparatorType Enum type = {IS, IS_NOT, EQ, NEQ, GT, GTE, LT, LTE, LIKE, NOT_LIKE, I_LIKE, NOT_I_LIKE, IN, NOT_IN, BETWEEN}
value : AnyValue 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 you to retrieve the data you need with the desired pagination and filtering options.
rootEntityId : UUID The UUID of the root entity in the folder.
status : String The status of the folder.
subCustomerEmail : String
updatedAt : DateTime
AssetView id : ID! The UUID of the asset.
label : String A label of the asset.
name : String A name of the asset.
createdAt : DateTime
file : File A file details (extension, path, URL).
Comment id : String
name : String Subject of the comment.
author : AccountPreview The comment author account details (email, group, isAdmin).
body : String The comment itself.
createdAt : String
Entity id : ID! The UUID of the entity.
info : JSON The entity information.
idMonitoring : Boolean A Boolean indicating whether the monitoring for the entity switched on {true} or off {false}.
entityChecks : [EntityCheck] An array of EntityCheck objects associated with the entity.
createdAt : DateTime
updatedAt : DateTime
relation : [Relation] An array of Relation objects associated with the entity. Stores data in JSON format.
comments : [Comment]! An array of comments to the entity.