# API Integration Guide

# Introduction

Please, contact us in advance before using this method of integration. The verification flow can be quite challenging to implement since it may have lots of tricky 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 on 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 your users are happy. If you think that this flow would be hard to implement or time-consuming, please, 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 creating 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 the list of restricted countries at the applicant level, we suggest rewriting it for applicants that were created before the change with this method.

# Requesting check for an applicant

Once all required documents are properly uploaded you can notify 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 tricky 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 block the user, and let him resolve the issue via support. Don't worry, there are only 1-2% of such cases, and it can happen 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.
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.
Reupload documents from the problematic step to the same applicant, move the 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 the user to fix the 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, make sure that the user is aware that the ID document should be uploaded with 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.