# 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)

# Submitting an applicant action

If you use WebSDK or MobileSDK, submission is taken care for you. You just need to record an action id from there, and retrieve it via API if needed.

POST /resources/applicantActions/-/forApplicant/#{applicantId}/#{actionType}

# REQUEST ARGUMENTS

Name Type Required Description
applicantId String Yes Applicant id
actionType String Yes One of faceAuth, cryptoTransaction, paymentMethod
#{body} Object Yes Data required for the action (see the corresponding section)

# RESPONSE

Name Type Required Description
#{body} Object Yes Action created (note its id to reference later on)

# 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.

# 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

# Crypto transaction

This action is intended to get a risk score and some additional information about crypto transactions.

# Submission

POST /resources/applicantActions/-/forApplicant/#{applicantId}/cryptoTransaction

# Example request
curl -X POST \
  https://test-api.sumsub.com/resources/applicantActions/-/forApplicant/#{applicantId}/cryptoTransaction \
  -H 'Content-Type: application/json' \
  -d '{
    "direction": "deposit",
    "txn": "cb68af8c91b6e8ac284f7370effd176f13c62f79c8e8fb6b2f890e802f5dd191",
    "address": "1JWF1vJyyxxWJ27T9G3kStyFUGp47hvKiP"
  }
# Request body
Name Type Required Description Default
currency String No BTC or ETH BTC
direction String Yes withdrawal or deposit
txn String Yes Transaction hash
address String Yes Target address hash

# 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://test-api.sumsub.com/resources/applicantActions/5e022e0f0a975a45325c7ff5/paymentMethod' \
  -d '{"type":"bankCard","subType":"VISA","data":{"requiredIdDoc":{"firstName":"Bond","lastName":"James","number":"4321432143314321"}}}'
# Request arguments
Name Type Required Description
actionId String Yes Applicant action id
#{body} Object Yes An object representing a payment method (see example)
# body attribute
Name Type Required Description
type String Yes bankCard, eWallet, wireTransfer or cryptoWallet
subType String No VISA, MASTERCARD, BTC, ...
data String Yes An object representing a payment method. requiredIdDoc contains information for comparison with data from the end user.

# 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 applicant flow with Applicant action type
  • 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 flow you picked on the first step

# Generating an access token for Applicant Actions

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

# 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.
# RESPONSE
Name Type Description
token String A newly generated access token for an applicant.
# Creating an access token for applicant action
# Example response

# Webhooks

When applicant action check has been completed we send a applicantActionReviewed webhook and applicantActionOnHold webhook when processing of the applicant action is paused for an agreed reason. More info can be found here

# Example applicantActionReviewed webhook payload
# Example applicantActionOnHold webhook payload
Last Updated: 9/8/2020, 10:32:09 AM