IDnGO Documentation

# API Integration

With the IDnGO API, you can process the applicant data and documents submitted for verification through simple RESTful APIs.

Please contact us in advance before selecting this integration method. Direct API integration can be complex to implement on your own and may cause issues that are already handled automatically by our WebSDK and MobileSDK. In the future, additional fees for API integration support may apply.

# Introduction

All endpoints referenced in this section are described in detail in the API Requests section. This page provides a high-level overview of the integration process and highlights key areas that require special attention.

Warning:

  • All API requests must be made over HTTPS. Requests sent via plain HTTP will be rejected.
  • API responses are returned in JSON format (unless otherwise specified). When sending data, requests must include valid JSON (unless otherwise specified) with the Content-Type: application/json header.

# API requests

Before starting work with the IDnGO API, all clients must complete authentication as described in the Getting Started section.

On the Dashboard, you can configure verification steps, define which documents are allowed, and specify the order of checks within a verification level.

For more details about verification steps and supported documents, see here.

The scheme and order of applicant verification are described in detail in the About Verification section. Below is the recommended sequence of actions to ensure the applicant is processed correctly by the system.

# Applicant verification workflow

# 1. Create an applicant

When creating an applicant, its status becomes init.

Send the user data you already have (for example, email, phone number, etc.). This helps improve anti-fraud checks.
Create applicant: POST /resources/applicants?levelName={levelName}

# 2. Upload user documents

Upload all required images and data:

  • User documents and selfie.
    If a document has two sides, send two images and correctly specify idDocSubType (FRONT_SIDE and BACK_SIDE).

It is mandatory to send both sides: if only FRONT_SIDE is provided and BACK_SIDE is missing, verification will not be completed.
Add identity document: POST /resources/applicants/{applicantId}/info/idDoc

If you submit user data for verification against document data, make sure the user can correct it on your side. We will return the rejection tag PROBLEMATIC_APPLICANT_DATA if the data provided by the user differs from the data in the documents.

# 3. Request applicant verification

Automatic status change to pending only works in our SDKs. Once all required documents and data are uploaded, notify the system that the applicant is ready for verification.
Change the profile status to pending:
Request applicant verification: POST /resources/applicants/{applicantId}/status/pending

Warning:

The applicant will be rejected and will not pass verification if the documents are uploaded incorrectly or incompletely.

# 4. Retrieving verification results

Once the verification is complete, the applicant's status will change to completed.

The recommended way to receive results is via webhooks. They can be configured in the “Webhooks” section of the Dashboard.

Provide the user with a message containing their verification result:

  • GREEN — verification was successful.
  • RED:FINAL — final rejection, the user cannot upload new photos.
  • RED:RETRY — temporary rejection, the user can upload new photos or data.

Warning:

You must be able to respond to changes in the verification status. For example, if an applicant was approved but ends up on a blacklist a week later, we will send a new RED result to your webhook endpoint, and your system should respond accordingly.

To retrieve applicant information recognized from documents during verification, use this API request:

Get applicant data:

GET /resources/applicants/{applicantId}/one or GET /resources/applicants/-;externalUserId={externalUserId}/one

5. Request documents again:

A temporary rejection RED:RETRY allows uploading images for re-verification.

If only part of the uploaded images had issues during verification, the user does not need to redo all verification steps and re-upload all documents. You only need to upload the images/data that had problems:

  1. Retrieve the list of problematic images and detailed verification information.

Get statuses for individual verification steps (API): GET /resources/applicants/{applicantId}/requiredIdDocsStatus

  1. The moderationComment field contains a comment that can be shown to the user (for example, «The text on your identity document is unclear. Please upload a new photo.»).

  2. Re-upload the new images to the same applicant, then change its status to pending and wait for the new verification results.

# Important details for successful API Integration

  • If you don’t have specific requirements for documents, it is recommended to:
    • send 1 image of the main page for book-style documents: passport, residence permit, etc.;
    • send 2 images for card-style documents: ID card, driver’s license, etc.
  • For selfie verification, make sure the user knows to hold their ID within the frame and that the document is clearly visible.