Sumsub Developer Hub

# Applicant actions

# Introduction

Applicant actions are events that typically happen 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, these 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 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. 0
# 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 whose 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 the submission 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 Applicant actions type and Action type - Face auth in 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 can follow:

  • 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 the accessToken you generated in step 2.

# 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 information 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 txn should not be set at all or set to null.
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 specific 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 txn should not be set at all or set to null.
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 connections.

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 in 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: 5/25/2023, 2:46:55 PM