Sumsub Developer Hub

# Supplemental endpoints

# Getting similar applicants (duplicates) check result

Using this method, you can fetch a list of entities with similar data of one particular applicant after its check. All attributes below are nullable.

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

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant ID.
# RESPONSE

Response represents a singleton list of checks with information on similar applicants

Name Type Description
answer String Duplicates check answer (GREEN/RED/YELLOW).
createdAt Date Time and date of the latest duplicate check result.
similarSearchInfo Object Duplicate search data.
# similarSearchInfo ATTRIBUTES
Name Type Description
answer String Duplicates check answer (GREEN/RED/YELLOW).
duplicateApplicantHits List of Objects List of data about a particular match.
# duplicateApplicantHits ELEMENT ATTRIBUTES
Name Type Description
applicantId String Applicant Id of the matched applicant.
matchedFields List of Strings List of matched json fields from applicant info.
types List of Strings List of match criteria (text/image).
# Example request
# Example response

# Getting result from tin (SSN) check

Using this method, you can get data that was extracted from external sources using applicant's TIN (SSN).

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

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant ID.
# RESPONSE

Response represents a singleton list of checks

Name Type Description
answer String Сheck answer (GREEN/RED/YELLOW).
createdAt Date Time and date of the latest tin check result.
extractedDoc Object External check source data.
# extractedDoc ATTRIBUTES
Name Type Description
addresses List of Objects List of addresses extracted from external check sources.
# addresses ELEMENT ATTRIBUTES
Name Type Description
country String Alpha-3 country code.
postCode String Postal code.
town String Town or city name.
street String Street name.
buildingNumber String Building number.
subStreet String Additional street information.
state String State name if applicable.
startDate Date Date of starting using address as residential.
endDate Date Date of changing residential address.
# Example request
# Example response

POST /resources/sdkIntegrations/levels/{levelName}/websdkLink?ttlInSecs={lifetime}&externalUserId={externalUserId}&lang={lang}

# REQUEST ARGUMENTS
Name Type Required Description
levelName String Yes Applicant level name that you can set up at the dashboard.
ttlInSecs Integer Yes Link lifetime in seconds.
externalUserId String Yes External User ID - unique user identifier on your side.
lang String No WebSDK texts language in ISO 639-1 format.
# RESPONSE
Name Type Description
url String Verification link.
# Example request
# Example response

# Sending verification status email to an applicant

Method below will send email about current verification status to the indicated within applicant email address.

POST /resources/applicants/{applicantId}/verificationStatusEmail

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant ID.
# Example request
# Example response

# Getting applicant events log

Using this method, you can take a look at activity within particular applicant.

GET /resources/applicantTimeline/{applicantId}

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant ID.
# RESPONSE
Name Type Description
applicant String Contains data of a similar applicant.
items Array of Objects Array of activity events.
items.ts String Timestamp of an event
items.activity String Type of activity that affected on applicant status.
items.ipInfo Object Contains IP addresses and locations.
items.trackingData Object Contains an IP address and source of the activity (WebSDK, msdk, dashboard).
# Example request
# Example response

# Generating applicant pdf report

Allows generating and fetching Applicant Summary report in pdf format.

Make sure to get a response from the first request before you call another one.

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

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant ID.
reportType Integer Yes Type of the report. Depends on the type of an applicant can be applicantReport for individuals or companyReport for companies.
lang String Yes Language of the report (en/pt).
# RESPONSE

Binary content representing a pdf report.

# Example request:

# Getting the list of available levels

To get the full structured view of applicant levels list, via API, you should perform the following request.

GET /resources/applicants/-/levels

# RESPONSE

JSON representation of the applicant levels list with its settings.

# Example request:
# Example response:

# Changing applicant data

If you want to change an applicant's data, you can issue a PATCH request instead of creating a new applicant, which is highly discouraged. This method, patches the fields in the info key of the applicant.

PATCH /resources/applicants/{applicantId}/info

# REQUEST ARGUMENTS

The body must contain only those fields that you intend to change. Null fields will be ignored. If you want to unset some fields, provide these in the unsetFields query parameter. Check the info attribute above for the list of supported fields.

Name Type Required Description
#{body} Object Yes Field in the info attribute that should be changed.
applicantId String Yes Applicant ID.
unsetFields String No Comma-separated list of fields to unset.
# RESPONSE

A patched info entity endpoint could be quite damaging if misused, please check that it returns expected results on the test environment — it's a client's responsibility to treat their applicants well 😃

# Example request
# Example response

# Getting liveness result

If you'd like to get result of the liveness check of a particular applicant, this method may help.

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

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant ID.
# RESPONSE

Contains a list of Liveness checks.

Name Type Optional Description
checks Array of Objects No List of objects containing results of liveness check.
Name Type Optional Description Available values
answer String No Answer on overall Liveness check GREEN/YELLOW/RED/ERROR.
id String No Liveness check ID.
# Example request
# Example response

# Getting facemap video from liveness check result

If you are interested in receiving a video snippet of liveness check result, you should use this method.

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

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant ID.
checkId String No Liveness check ID (see above).
# RESPONSE

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

If only one frame or less were captured during liveness check, this method will return an exception

# Example request

# Getting current similar applicants

Using this method you can fetch a list of entities with similar data or face of one particular applicant.

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

If you'd like to get a list of similar applicant found only by text info, you can call

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

Please, make sure to consider rate limiter factor for these endpoints:

  • /similar/byTextAndFace - 7 requests per 10 seconds
  • /similar/byText - 10 requests per 10 seconds
# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant id
# RESPONSE
Name Type Description
applicant Object Contains data of a similar applicant
matchedFields Array Array of matched applicant data fields (e.g. info.lastName)
exactMatch Boolean true if the data matches exactly
blacklisted Boolean Indicates if user is in our blocklist or not
types Array The match type (text - based on textual data, image - based on face match)
# Example request
# Example response
Last Updated: 2/22/2024, 11:30:11 AM