Sumsub Developer Hub

# Applicant actions

# Introduction

Applicant actions are events that typically happening to an applicant that got approved, and don't reflect on his/her status. E.g. it could be a crypto transaction of an approved applicant or access to some resource using his face. In any case those actions are recorded and attached to the applicant in question.

# General methods

All API requests must be authenticated as described in this section.

Submitting data of the applicant action depends on its type. However, getting the result is quite generic.

# Getting an applicant action

GET /resources/applicantActions/{actionId}/one

# REQUEST ARGUMENTS

Name Type Required Description
actionId String Yes Applicant action id

You can get applicant action id in response of action submission or by calling special method

# RESPONSE

Name Type Required Description
review Object Yes Object representing an answer with additional information
checks Array No List of checks that were performed within this action
images Array No List of images attached to the action
# review
Name Type Required Description
reviewStatus String Yes Status of the action review
reviewResult String Yes when completed Review result
# reviewResult
Name Type Required Description
reviewAnswer String Yes GREEN, RED or ERROR
rejectLabels Array No List of reject labels, if applicable (see them here)

# Getting applicant actions for an applicant

GET /resources/applicantActions/-;applicantId={applicantId}?limit={limit}&offset={offset}&order=-createdAt

# REQUEST ARGUMENTS

Name Type Required Description Default
applicantId String Yes Applicant id
limit Integer No Limit of applicant actions to be returned 1000
offset Integer No Offset of applicant actions to be returned 10
# Example request

# RESPONSE

Name Type Required Description
#{body} Object Yes List of applicant actions together with the total count

In the list attribute there are applicant actions which structure is described here

# Example response

# Getting images

# Original image

GET /resources/applicantActions/{actionId}/images/{imageId}?preview={isPreview}

# Request body
Name Type Required Description Default
actionId String Yes Applicant action id
imageId String Yes Image id from images[].imageId
isPreview Boolean No Whether to return an image thumbnail false

# Masked image

Returns a masked image. The most common scenario: return a bank card image with hidden middle digits from a bank card number.

GET /resources/applicantActions/{actionId}/images/{imageId}/masked

# Request body
Name Type Required Description
actionId String Yes Applicant action id
imageId String Yes Image id from images[].imageId

# Face authentication

# Submission

WebSDK or MobileSDK does it for you. Since it requires our face liveness module, it's not possible to submit this type of applicant action via API. To submit such action the SDK level being initialized should have type of Applicant actions and Action type - Face auth at its settings.

# Result

GET /resources/applicantActions/{actionId}/one

Below you can find an example response with the comments explaining the fields. Most likely, the most important field for you is review.reviewResult.reviewAnswer

Actually the response contains more fields that is listed below. We list only the relevant ones.

# Example response

# Payment method

This action is intended to validate payment methods, e.g. a credit card.

# Submission

POST /resources/applicantActions/-/forApplicant/{applicantId}/paymentMethod

# Example request
# Request headers
Name Type Value
X-External-Action-Id String externalActionId if you intend to initialize SDK for that particular action
# Request arguments
Name Type Required Description Default
applicantId String Yes Applicant id
requireSelfie Boolean No Sets video selfie at requiredIdDocs for action true
# Example response

# Adding information about the payment method

If you need to request a specific payment method from the user, you can send the data that will be shown to the user as a hint:

POST /resources/applicantActions/{actionId}/paymentMethod

# Example request
curl -X POST \
  'https://api.sumsub.com/resources/applicantActions/5e022e0f0a975a45325c7ff5/paymentMethod' \
  -H 'Content-Type: application/json' \
  -d '{"type":"bankCard","subType":"VISA","data":{"requiredIdDoc":{"firstName":"Bond","lastName":"James","number":"4321434321"}}}'
# Request arguments
Name Type Required Description
actionId String Yes Applicant action id
#{body} Object Yes An object representing a payment method (see example)
# body attributes
Name Type Required Description
type String Yes bankCard, eWallet, wireTransfer
subType String No VISA, MASTERCARD, ...
data Object No An object representing a payment method. requiredIdDoc contains information for comparison with recognized image data from the end user.
# requiredIdDoc of data object attributes
Name Type Required Description
firstName String No First name.
lastName String No Last name.
middleName String No Middle name.
number String No Payment/card/transfer number.
issuedDate Date No Document/card date of issue.
txnAmount String No Transaction amount if applicable to the document.

# Adding an image

POST /resources/applicantActions/{actionId}/images

# REQUEST HEADERS
Name Type Value
Content-Type String multipart/form-data
# FORM DATA
Name Type Required Description
content Binary Yes A photo of a document
metadata Object Yes An object representing a payment method
# RESPONSE

JSON representing added document information.

# Example request

# Requesting an applicant action check

POST /resources/applicantActions/{actionId}/review/status/pending

# Example request

# Result

GET /resources/applicantActions/{actionId}/one

Below you can find an example response with the comments explaining the fields. Most likely, the most important field for you is review.reviewResult.reviewAnswer

# Example response

# WebSDK Initialization for Applicant Actions

# Steps overview

Here are 3 simple steps that you should do:

  • Step 1: [Dashboard] Set up your level with Applicant actions type and set Action type that you'd like to use
  • Step 2: [Backend] Generate an Access token with externalActionId and userId to pass it later on to the WebSDK
  • Step 3: [Frontend] Install an NPM package or use CDN version of the script and launch it with an accessToken you generated on the second step

# Generating an access token for Applicant Actions

POST /resources/accessTokens?userId={externalUserId}&externalActionId={externalActionId}&levelName={levelName}

# REQUEST ARGUMENTS
Name Type Required Description
ttlInSecs Integer No Lifespan of a token in seconds. Default value is equal to 10 mins.
userId String Yes An external user ID which will be bound to the token.
externalActionId String Yes An external action ID which will be bound to the token.
levelName String Yes A name of the level configured in the dashboard.
# RESPONSE
Name Type Description
token String A newly generated access token for an applicant.
# Creating an access token for applicant action
# Example response

# Crypto source of funds analysis

These actions are intended to get a risk score and some additional information about crypto transactions.

# Getting the list of available tokens

It's better to cache response of the method below for about a day since answer value is quite big and is not changed often

GET /resources/standalone/crypto/availableCurrencies

# Example request
curl -X GET \
  'https://api.sumsub.com/resources/standalone/crypto/availableCurrencies'

Response payload represents the list of available currencies and tokens for a check

# Example response

# Submission

This endpoint will create an action with info about transaction for the specified applicant

POST /resources/applicantActions/-/forApplicant/{applicantId}/cryptoSourceOfFunds

# Request body
Name Type Required Description Default
currency String Yes BTC, ETH, BCH, LTC, USDT, ERC-20, BSV, XLM, ...
direction String Yes withdrawal or deposit
txn String Yes Transaction hash. For withdrawals you can set txn as an empty string (e.g. "txn": "")
address String Yes Target address hash
tokenId String Yes Check out method above to get the full list of available currencies and tokenIds 0

For deposit checks please make sure that you're sending wallet address that receives funds.

# Example requests
# Example response

# Standalone crypto analysis

It's better to create an applicant action to perform the crypto check for particular applicants. But if there is no way to bind a crypto transaction to an applicant then you should use standalone methods.

# Crypto source of funds

POST /resources/standalone/crypto/cryptoSourceOfFunds

# REQUEST BODY
Name Type Required Description
currency String Yes BTC, ETH, BCH, LTC, USDT, ERC-20, BSV, XLM, ...
direction String Yes withdrawal or deposit
txn String Yes Transaction hash. For withdrawals you can set txn as an empty string (e.g. "txn": "")
address String Yes Target address hash
tokenId String Yes Check out method above to get the full list of available currencies and tokenIds
# Example request
# Example response

# Signal attributes

Shows current percentage of transactions/exchanges with particular connexions.

Name Description
exchange_mlrisk_low Exchange With Low ML Risk
exchange_mlrisk_moderate Exchange With Moderate ML Risk
marketplace Marketplace
miner Mined Coins
payment Payment Processor
wallet Online Wallet
atm ATM
exchange_fraudulent Fraudulent Exchange
exchange_mlrisk_high Exchange With High ML Risk
exchange_mlrisk_veryhigh Exchange With Very High ML Risk
ransom Ransom
dark_market Darknet Marketplace
dark_service Darknet Service
gambling Gambling
illegal_service Illegal Service
mixer Mixing Service
scam Scam
stolen_coins Stolen Coins
p2p_exchange_mlrisk_low P2P Exchange With Low ML Risk
p2p_exchange_mlrisk_high P2P Exchange With High ML Risk
child_exploitation Child Exploitation
terrorism_financing Terrorism Financing
liquidity_pools Liquidity Pools
other Other

# Webhooks

The types of webhooks we send depend on the settings at the dashboard.

Value Description
applicantActionPending User passed all required steps and action was sent to pending status for a check.
applicantActionReviewed Applicant action check has been completed.
applicantActionOnHold Processing of the applicant action is paused for an agreed reason.

More info can be found here

# Example applicantActionPending webhook payload
# Example applicantActionOnHold webhook payload
Last Updated: 1/23/2023, 2:58:50 PM