API Integration Guide
Please, contact us in advance before choosing this method of integration. The verification flow can be quite challenging to implement yourself since it may have lots of corner cases that our WebSDK handles for you. In the future, we may decide to charge additionally for support when you chose this type of integration. Additionally, the pricing model may change to charge per transaction, not per user.
All API methods mentioned here are described in the API Reference section. The goal of this page is to give you an idea how the whole flow should look like and what to pay attention to. We also provide a check list of what you need to take care of to ensure that your integration is smooth and you users are happy. If you think that this flow could be hard to implement properly or time-consuming, please, rather choose our WebSDK.
API Integration Phases
Create an applicant with their documents
- First of all you need to create an applicant
- Provide as much information as you have already, e.g. email, phone, etc. - it helps us with our anti-fraud checks
- Set up steps that an applicant must go through, e.g. uploading an identity document, selfie and proof of address. More info about supported documents here.
- Then upload applicant documents
- Make sure to upload all documents that you require
- If a document is double-side submit two images and set up
- If all is good and all required documents are properly uploaded an applicant will go the
pendingstate, which means it will be checked soon
- NOTE: if you don't submit documents correctly, the applicant will stay in the
initstate and won't be checked. Please, check all the corner cases on your side to avoid having incomplete applicants
Getting verification results
- Set up webhooks to get the results
- Receive results and show appropriate message to your users.
- If you received a
GREENresult, all is fine. Congratulations with one more verified user! You can also fetch its data in a separate API call if needed.
- If you got a
FINALyou just block a user, and let him resolve the issue via support. Don't worry, there are only 1-2% of such cases, when e.g. there is a fake account or forged documents were used.
- If you got a
RETRY, a user has some issues with their documents. Refer to the next section of how to guide a user to fix those.
- If you received a
Resubmitting problematic documents
- First of all, there is no need to make a user upload all the documents again. Only those that have problems.
- You read the images that have problems via this endpoint and show
moderationCommentfield to inform a user about the exact problem. E.g. The text on your identity document is not clearly visible. Please, upload a new photo.
- You reupload documents from the problematics step and wait for verification results again.
Checklist for a smooth API integration
- If you send user data to us and want them to be cross-checked with the data from the documents, make sure that you allow a user to fix those data
on your side. We will send you a
PROBLEMATIC_APPLICANT_DATAreject label in this case. Note: this scenario is not encouraged. To avoid confusion we recommend getting "clean" data from our side.
- If you don't have sophisticated rules for the documents we recommend to send just 1 image for passports, and 2 sides for id cards, driving licenses and residence permits.
- For selfies, please, make sure that a user is aware that the id document should also be present on the selfie and be clearly readable.
- Verifications statuses are handled correctly:
FINALreject does not allow user to submit new documents and the user is notified about that.
- You should be able to react on the status change. E.g. we approved a user, but 1 week later he appeared on the blacklist. We will send a
REDresult to your webhook endpoint and you should react on the status change accordingly.