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.

Signal Name UI Signal Name API Description
ATM atm Cryptocurrency ATM operator.
Child Exploitation child_exploitation Organization which operates via darknets and is suspected of child abuse and exploitation.
Darknet Marketplace dark_market Online marketplace which operates via darknets and is used for trading illegal products for cryptocurrency.
Darknet Service dark_service Organization which operates via darknets and offers illegal services for cryptocurrency.
Enforcement Action enforcement_action The entity is subject to legal proceedings. Jurisdiction will be annotated as a subtype.
Exchange Fraudulent exchange_fraudulent Exchange that was involved in illegal activity.
Exchange Licensed exchange_licensed Organization that is licensed to provide exchange services.
Exchange Unlicensed exchange_unlicensed Organization that is not licensed to provide exchange services.
Gambling gambling Online resource offering gambling services using cryptocurrency.
Illegal Service illegal_service Resource offering illegal services or engaged in illegal activities.
Liquidity Pools liquidity_pools The smart contracts where tokens are locked for the purpose of providing liquidity.
Marketplace marketplace Entity offering legal services/trading goods for cryptocurrency.
Miner miner Organization which utilizes its computing power for mining cryptocurrency blocks.
Mixing Service mixer Service for mixing funds from different sources to make tracing them back harder or almost impossible. It is mostly used for money laundering.
P2P Exchange Licensed p2p_exchange_licensed Organization that is licensed to provide P2P exchange services.
P2P Exchange Unlicensed p2p_exchange_unlicensed Organization that is not licensed to provide P2P exchange services.
Payment Processor payment Service which acts as an intermediary between customers and the company which provides services for making a payment.
Ransom Extortioner ransom Extortioners demanding payment in the form of cryptocurrency
Sanctions sanctions Organization that is found in sanctions lists.
Scam scam Entities that have scammed their customers and taken possession of their cryptocurrency.
Sized Assets seized_assets In the crypto seized by the government, the default Risk Score is 0%.
Stolen Coins stolen_coins Entities which have taken possession of someone else’s cryptocurrency by hacking.
Terrorism Financing terrorism_financing Organization which operates via darknets and involved in terrorism financing with cryptocurrency.
Online Wallet wallet Service for storage and making payments with cryptocurrency.
Other other None of the specified entities above. It may include a subtype.

# 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: 9/21/2023, 8:29:49 AM