IDnGO Documentation

# Additional API requests

# GET Retrieve duplicate check results (similar applicants)

This request allows you to get a list of profiles with data similar to an applicant. All response fields can be empty (null).

GET /resources/checks/latest?type=SIMILAR_SEARCH&applicantId={applicantId}

Query parameters

Name Type Required Description
applicantId String Yes Unique identifier of the applicant in our system.
type String Yes The value SIMILAR_SEARCH.

Response

The response is a list of duplicate check results containing information about the found similar applicants.

Name Type Description
answer String Duplicate check result (GREEN/RED/YELLOW).
createdAt Date Date and time of the last check in GMT (YYYY-MM-dd hh:mm:ss.fff).
similarSearchInfo Object Information about the performed similar applicant search.

Fields of the similarSearchInfo object

Name Type Description
answer String Duplicate check result (GREEN/RED/YELLOW).
duplicateApplicantHits List of Objects List of data about a specific match.

Fields of the duplicateApplicantHits object

Name Type Description
applicantId String Unique identifier of the applicant in our system.
matchedFields List of Strings List of matching JSON fields containing applicant information.
types List of Strings Match type (Data - text, Face - image).

Example

Request Response

# GET Retrieve TIN check result

This request allows you to obtain data extracted from external sources using the user's TIN.

GET /resources/checks/latest?type=TIN&applicantId={applicantId}

Query parameters

Name Type Required Description
applicantId String Yes Unique identifier of the applicant in our system.
type String Yes The value TIN.

Response

The response is a single list of checks called checks.

Name Type Description
answer String User TIN check result (GREEN/RED/YELLOW).
createdAt Date Date and time of the last TIN check result (GMT).
extractedDoc Object External verification of source data.

Fields of the extractedDoc object

Name Type Description
addresses List of Objects List of addresses extracted from external TIN verification sources.

Fields of the addresses object

Name Type Description
country String Three-letter country code Alpha-3 (for example, RUS).
postCode String Postal code.
town String City or locality name.
street String Street name or full address, depending on the document format.
buildingNumber String Building number.
subStreet String Additional street information.
state String Region name (province/state/republic, etc.).
startDate Date Start date of residence at the address.
endDate Date Date when the address was changed.

Example

Request Response

# POST Generate external WebSDK link

POST /resources/sdkIntegrations/levels/{levelName}/websdkLink?externalUserId={externalUserId}

Request parameters

Name Type Required Description
levelName String Yes The name of the verification level, as configured in the «Application Levels» section of the Dashboard.

Query parameters

Name Type Required Description
externalUserId String No External applicant identifier — the unique identifier of the user in your system. Required if you need to create a link for an applicant.
externalActionId String No External action identifier. Required only to create a link for an applicant action.
locale String No WebSDK language in ISO 639-1 format.
ttlInSecs Integer No Connection lifetime in seconds (default — 1800).

Response

Name Type Description
url String Link to complete verification.

Example

Request Response

# POST Send verification status email to user

The method below sends an email with the current verification status to the email address specified in the applicant.

POST /resources/applicants/{applicantId}/verificationStatusEmail

Request parameters

Name Type Required Description
applicantId String Yes Unique identifier of the applicant in our system.

Example

Request Response

# GET Retrieve applicant activity log

This request allows you to track the activity of an applicant.

GET /resources/applicantTimeline/{applicantId}

Request parameters

Name Type Required Description
applicantId String Yes Unique identifier of the applicant in our system.

Response

Name Type Description
applicantId String Unique identifier of the applicant in our system.
items Array of objects Activity event data.

Fields of the items object

Name Type Description
ts String Event timestamp.
activity String Type of event that affected the profile status.
ipInfo Object IP address and location.
trackingData Object IP address and source of activity (WebSDK, MobileSDK, Dashboard).

Example

Request Response

# GET Retrieve applicant verification report in PDF

This request allows you to generate and download an applicant verification report in PDF format. Make sure you have received a response from the first request before making a new one.

GET /resources/applicants/{applicantId}/summary/report?report={reportType}&lang={en}

Request parameters

Name Type Required Description
applicantId String Yes Unique identifier of the applicant in our system.

Query parameters

Name Type Required Description
reportType Integer Yes The report type, which depends on the applicant's type (for individuals - applicantReport, for companies - companyReport).
lang String Yes Language for the verification report in ISO 639-1 format (default: en).

Response

The response is a binary PDF file containing the generated report.

Example

Request

# GET Retrieve list of available verification levels

To obtain a complete and structured list of verification levels via API, use the following endpoint.

GET /resources/applicants/-/levels

Response

JSON representation of the verification levels list along with their settings.

Name Type Required Description
items Array of objects Yes Each object corresponds to a specific verification level.
totalItems Integer Yes Total number of all verification levels.

Fields of the items object

The table below lists the fields inside each items object, which describe the configuration parameters of the verification levels. The presence of some fields depends on the type and settings of a specific level.

# Translation Options for Terms with Explanations

Field Type Description
id String Unique identifier of the level.
name String Level name set during creation (cannot be changed later).
desc String Level description (if added during creation).
requiredIdDocs Object Set of documents and data required for verification (for example, steps IDENTITY, SELFIE and corresponding documents: PASSPORT, ID_CARD, etc.).
websdkFlowId String WebSDK customization identifier (if added to the level).
msdkFlowId String MobileSDK customization identifier (if added to the level).
createdAt Date Level creation date and time (GMT).
createdBy String Account that created the level. Value Service means the level was created by IDnGO support.
modifiedAt Date Date and time of the last modification of the level (GMT).
customPrivacyNoteText String User data processing consent text displayed in WebSDK (if specified).
watchListCheckSettings Object Level settings related to AML checks.
useCustomWatchListCheckSettings Boolean Whether custom AML check settings are used.
useCustomIdDocSettings Boolean Whether custom settings for supported documents are used.
applicantInsightSettings Array of booleans Includes fields: advancedEmailCheckEnabled, advancedPhoneCheckEnabled, advancedIpCheckEnabled, advancedIdentityEnrichmentEnabled. Indicates whether the corresponding checks are enabled.
type Enum Type of the level defined at creation: standalone — standard check; actions — additional actions; module — only Liveness and Face match check.
actionType Enum Available if level type is actions. Possible values: paymentMethod, faceEnrollment.
applicantType Enum Applicant type: individual (natural person), company (legal entity).

Fields of the requiredIdDocs object

The requiredIdDocs object describes the steps needed for verification as well as the required documents and data.

Field Type Description
docSets Array of objects A set of document types and their parameters.

Fields of the docSets array

Field Type Description
idDocSetType String Identifier of the document type, for example, IDENTITY, SELFIE, PROOF_OF_RESIDENCE, etc.
fields Array of objects Describes fields that must be filled in. Each object contains: name (field name), required (whether the field is mandatory).
types Array of strings Types of documents required for the specific idDocSetType.
videoRequired String Method of completing the document upload step:
disabled — selfie with document.
photoRequired — photo via webcam (static face image).
passiveLiveness — liveness check.
docapture — camera enabled during document verification for real-time photo capture of documents.
captureMode String Capture mode when using docapture:
manualAndAuto — document photo is taken automatically or manually via button.
manualOnly — photo taken only manually via button.
uploaderMode String Photo upload mode:
always — allows uploading a photo from the gallery instead of using the camera.
never — disallows uploading from the gallery.
fallback — allows gallery upload only if camera is unavailable.
paymentMethods Array of objects Settings for payment method verification (if present in the level).
questionnaireDefId String Questionnaire identifier (if present in the level).

Example

Request Response

# PATCH Update applicant data

If you want to update an applicant's data, use the PATCH method instead of creating a new applicant. This endpoint modifies fields within the applicant's info object.

PATCH /resources/applicants/{applicantId}/info

Request parameters

The body should contain only the fields you want to update. Missing fields will be ignored. To reset certain fields, include them in the unsetFields query parameter.

Name Type Required Description
applicantId String Yes Unique identifier of the applicant in our system.
unsetFields String No Comma-separated list of fields to reset.

Request body

Fields within the info object that need to be updated.

Response

Modifying applicant info data may cause issues if used incorrectly. Please ensure that the endpoint returns the expected results in the Sandbox environment.

Example

Request Response

# GET Retrieve face Liveness check result

If you want to get the result of an applicant's face liveness check, use this request.

GET /resources/checks/latest?type=FACE_LIVELINESS&applicantId={applicantId}

Query parameters

Name Type Required Description
applicantId String Yes Unique identifier of the applicant in our system.
type String Yes Value FACE_LIVELINESS.

Response

Contains a list of real-time face liveness checks.

Name Type Description
checks Array of objects A list of objects containing face liveness check results.

Fields of checks element

Name Type Description
answer String The result of the face liveness check. Possible values: GREEN / RED / ERROR.
id String The face liveness check identifier.
createdAt Date The date and time the applicant was created (GMT).
checkType String The type of check: FACE_LIVELINESS.

Example

Request Response

# GET Retrieve applicant Liveness

If you need a video snippet of the user's face (liveness) from the check, use this endpoint.

GET /resources/applicants/{applicantId}/info/facemap/video?checkId={checkId}

Request parameters

Name Type Required Description
applicantId String Yes Unique identifier of the applicant in our system.

Query parameters

Name Type Required Description
checkId String Yes Identifier of the face liveness check.

Response

Binary content representing the video (in most cases video/mp4 format). The Content-Type response header precisely describes the media type of the response.

If only one frame or fewer were captured during the liveness check, the request will result in an error.

Example

Request

# GET Retrieve similar applicants

Using this request, you can get a list of applicants with similar data or face to the applicant.

GET /resources/applicants/{applicantId}/similar/byTextAndFace

If you want to get a list of similar applicants found only by text information, you can call:

GET /resources/applicants/{applicantId}/similar/byText

Make sure to consider the rate limit for these endpoints:

  • /similar/byTextAndFace - 7 requests per 10 seconds
  • /similar/byText - 10 requests per 10 seconds

Request parameters

Name Type Required Description
applicantId String Yes Unique identifier of the applicant in our system.

Response

Name Type Description
applicant Object Contains data of the similar applicant.
matchedFields Array Matching applicant data fields (for example, info.lastName).
exactMatch Boolean If the data exactly matches — true.
blacklisted Boolean Whether this applicant is on our blacklist or not.
types Array Type of match (text – text data match, image – face match).

Example

Request Response

# POST Import applicant from ZIP archive

This request allows importing applicant data, images, questionnaire verification results, etc., from a *.zip archive.

Request rate limit: 10 requests per 10 seconds.

POST /resources/applicants/-/applicantImport

Request body

Name Type Description
RAW_BODY file *.zip archive with data for import.

Request headers

Name Type Value
Content-Type String application/zip

Contents of the ZIP-archive

  • applicant.json file containing the result of the applicant verification.
  • Folders containing data for individual verification steps:
    • images (in .jpeg/.jpg/.png format) or video (.mp4) for face liveness detection,
    • applicantIdDoc.json file containing information about the verification step.

The number and type of folders depend on the required steps configured for the verification level.

Warning:

The applicantIdDoc.json file must always include the idDocType and country parameters.

Example structure of the archive for creating an applicant with identity verification steps (two pages) and a selfie.

ArchiveStructureExample

Contents of applicant.json

Name Type Required Description
externalUserId String Yes External applicant identifier — the unique identifier of the user in your system.
info Object Yes Applicant data extracted from the user's documents.
review Object Yes Detailed information about the verification result.

Fields of the info object

Name Type Required Description
firstName String Yes First name.
lastName String Yes Last name.
middleName String No Middle name or patronymic.
legalName String No Name as per passport.
gender String No Gender (M or F).
dob String No Date of birth (YYYY-mm-dd).
placeOfBirth String No Place of birth.
countryOfBirth String No Country of birth.
stateOfBirth String No State/region of birth.
country String Yes Three-letter country code Alpha-3 (for example, RUS).
nationality String No Three-letter country code Alpha-3 (for example, RUS).
addresses Array No List of addresses.
tin String No Taxpayer Identification Number (TIN).

Fields of the addresses object

Name Type Required Description
country String No Three-letter country code Alpha-3 (for example, RUS).
postCode String No Postal code.
town String No City or locality name.
street String No Street name or full address depending on the document format.
subStreet String No Additional street information.
state String No Region/state/province name.
buildingName String No Building name or number.
flatNumber String No Apartment number.
buildingNumber String No Building number.

Fields of the review object

Name Type Required Description
createDate Date Yes Date the applicant was created (yyyy-MM-dd HH:mm:ss+0000).
reviewDate Date No Date the verification was completed (yyyy-MM-dd HH:mm:ss+0000).
levelName String Yes The name of the verification level, as configured in the «Application Levels» section of the Dashboard.
reviewResult Object Yes Additional information about the verification result.
reviewStatus String Yes Current verification status of the applicant.

Fields of the reviewResult object

Name Type Description
moderationComment String Optional. Human-readable comment that may be shown to the end user.
clientComment String Optional. Human-readable comment that should not be shown to the end user.
reviewAnswer String Verification result. Must be GREEN.

Warning:

The value of reviewAnswer must be GREEN, as this endpoint is used for importing only approved applicants.

Example content of the applicant.json file

applicant.json

Contents of the applicantIdDoc.json file

Name Type Required Description
idDocType String Yes Type of document.
idDocSubType String No FRONT_SIDE, BACK_SIDE, or null.
country String Yes Three-letter country code Alpha-3 (for example, RUS).
firstName String No First name.
middleName String No Middle name or patronymic.
lastName String No Last name.
issuedDate String No Issue date (format YYYY-mm-dd).
validUntil String No Expiration date (format YYYY-mm-dd).
number String No Document number.
dob String No Date of birth.
placeOfBirth String No Place of birth.

Example content of the applicantIdDoc.json file

applicantIdDoc.json

Response

The response is a JSON object containing information about the applicant.

Example

Request

# PATCH Deactivate applicant

This endpoint is used to deactivate (remove) an applicant.

The applicant remains in the database, but its data will be ignored during duplicate checks when registering new applicants.

You can always reactivate an applicant later by setting {status} to activated.

The system does not allow deactivating profiles that are currently under review (statuses pending, queued, or prechecked).

PATCH /resources/applicants/{applicantId}/presence/{status}

Request parameters

Name Type Required Description
applicantId String Yes Unique identifier of the applicant in our system.
status String Yes Assigned status: deactivated (default) — remove the profile, activated — restore the profile to active status.

Response

The response is a JSON object containing an array of applicant data objects. The returned data depends on your system access rights.

Warning:

The deleted parameter indicates the result of the request:

  • true — the applicant has been deactivated.
  • false — the applicant is active.

Example

Request Response