# API Integration Guide

# Introduction

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

API Flow

# Create an applicant with their documents

All API requests must be authenticated as described in this section. For testing purposes make sure to use App token and Secret key pair that was created on Sandbox for request authorization headers.

Firstly you need to create an applicant

Set up steps that an applicant must go through by created applicant level from the dashboard, e.g. uploading an identity document, selfie and proof of address. More info about supported documents here.
Provide as much information as you have already, e.g. email, phone, etc. - it helps us with our anti-fraud checks

# Uploading documents

Then upload applicant documents

Make sure to upload all documents that you require.
If a document is double-sided submit two images and set up idDocSubType properly (FRONT_SIDE and BACK_SIDE)
Make sure to send BACK_SIDE if FRONT_SIDE was already sent otherwise verification step won't be completed, and you won't be able to initiate a check.

If you've changed a list of restricted countries at the applicant level we suggest rewriting it for particular applicants with that method if they were created before that change

# Requesting check for an applicant

Once all required documents are properly uploaded you can signal to us that an applicant is ready to be reviewed by moving it to pending calling that endpoint (POST /resources/applicants/{applicantId}/status/pending)

NOTE: if you don't submit documents correctly, the applicant will be rejected or 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 GREEN result, 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 RED answer and rejectType is FINAL you 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 RED answer and rejectType is RETRY, a user has some issues with their documents. Refer to the next section of how to guide a user to fix those.

# 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 moderationComment field 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 to the same applicant, send that applicant to pending status 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_DATA reject 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:
- FINAL reject 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 blocklist. We will send a RED result to your webhook endpoint, and you should react on the status change accordingly.