# 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
curl -X GET \
'https://api.sumsub.com/resources/applicantActions/-;applicantId=5e5f9ab10a975a6e224dc286?limit=100&order=-createdAt'
# 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
{
"list" : {
"items" : [ {
"id" : "5dd3f15704f9404c41307c85", // applicant action id
"createdAt" : "2019-11-19 13:42:47",
"applicantId" : "5dd3d58304f9404c412f1665",
// ...
}, {
"id" : "5dd3d94153d4864d5aa98f21", // applicant action id
"createdAt" : "2019-11-19 12:00:01",
"applicantId" : "5dd3d58304f9404c412f1665",
// ...
} ],
// total items (even if a limit is provided)
"totalItems" : 213
}
}
# 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
{
// applicant action id - that's what you should get from WebSDK or MobileSDK
"id" : "5d9f76507edd7d8162bfcea8",
"createdAt" : "2019-10-10 18:20:00",
"applicantId" : "5d9f74a27edd7d813405fe07",
"type" : "selfieAuth",
"review": {
"reviewResult" : {
"reviewAnswer" : "GREEN"
},
}
// checks performed: liveness and comparison with the relevant document
// NOTE: if liveness check didn't pass, we won't perform a face match check
"checks" : [ {
"answer" : "GREEN",
"checkType" : "FACE_LIVELINESS",
"createdAt" : "2019-10-10 18:19:57",
"livenessInfo": {
"livenessData": {
"images": [
{
"imageId": 1368276695
},
{
"imageId": 1060469685
},
{
"imageId": 2074791000
},
{
"imageId": 810045545
},
{
"imageId": 1328042852
}
]
},
"livenessResult": {
"answer": "GREEN"
}
}
},
{
"answer" : "GREEN",
"checkType" : "FACE_MATCH",
"createdAt" : "2019-10-10 18:20:00",
"faceMatchInfo" : {
"answer" : "GREEN",
}
} ]
}
# Payment method
This action is intended to validate payment methods, e.g. a credit card.
# Submission
POST /resources/applicantActions/-/forApplicant/{applicantId}/paymentMethod
# Example request
curl -X POST \
'https://api.sumsub.com/resources/applicantActions/-/forApplicant/5df0d3fb0a975a6bbe186028/paymentMethod?requireSelfie=false' \
-H 'X-External-Action-Id: action-5df0d3fb0a975a6bbe186028-1'
# 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
{
//Action Id
"id": "5e022e0f0a975a45325c7ff5",
"createdAt": "2019-12-24 15:26:07",
"applicantId": "5df0d3fb0a975a6bbe186028",
"type": "paymentMethod",
"review": {
"createDate": "2019-12-24 15:26:07+0000",
"reviewStatus": "init",
},
"requiredIdDocs": {
"docSets": [
{
"idDocSetType": "PAYMENT_METHODS",
"types": ["PAYMENT_METHOD"]
}
]
}
}
# 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
curl -X POST \
'https://api.sumsub.com/resources/applicantActions/5e022e0f0a975a45325c7ff5/images' \
-H 'Content-Type: multipart/form-data' \
-F 'metadata={"idDocType":"PAYMENT_METHOD","country":"GBR"}' \
-F 'content=@/SumSub/Example/name.jpg'
# Requesting an applicant action check
POST /resources/applicantActions/{actionId}/review/status/pending
# Example request
curl -X POST \
'https://api.sumsub.com/resources/applicantActions/5e022e0f0a975a45325c7ff5/review/status/pending'
# 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
{
"id" : "5dc2d80ce3cc9b1c1e389c4c",
"createdAt" : "2019-11-06 14:26:20",
"applicantId" : "5dc158b109494c3cbf431e28",
"type" : "paymentMethod",
// main result
"review" : {
"createDate" : "2019-11-06 14:35:06",
"reviewResult" : {
"moderationComment" : "",
"reviewAnswer" : "GREEN"
},
"reviewStatus" : "completed"
},
// checks performed for the applicant actions
"checks" : [ {
"answer" : "GREEN",
"checkType" : "FACE_LIVELINESS",
"createdAt" : "2019-11-06 14:34:27",
"id" : "a1f096a8-a9c0-419a-a117-51312506931f",
"livenessInfo" : {
"livenessData" : {
"sessionId" : "d5ff4c12-4616-44fe-86ab-ad4fd73174fc",
"images" : [ {
"imageId" : 866303241
},
//...
]
},
"livenessResult" : {
"answer" : "GREEN"
},
}
}, {
"answer" : "GREEN",
"checkType" : "FACE_MATCH",
"createdAt" : "2019-11-07 09:07:02",
"id" : "79983099-b0cf-4b5d-882a-67f25a174041",
"faceMatchInfo" : {
"answer" : "GREEN"
},
"imageIds" : [ 935595818, 1567323303 ]
}],
"requiredIdDocs" : {
"docSets" : [ {
"idDocSetType" : "PAYMENT_METHODS",
"types" : [ "PAYMENT_METHOD" ]
}, {
"idDocSetType" : "SELFIE",
"types" : [ "SELFIE" ]
} ]
},
"paymentMethod" : {
"type" : "bankCard",
"subType" : "VISA",
"data" : {
"firstName" : "JOHN SMITH",
"validUntil" : "2021-01-01",
"number" : "411111****1111"
},
// check for the risk score
"checks" : [ {
"answer" : "GREEN",
"checkType" : "bankCardRiskScore",
"inputData" : {
"firstName" : "JOHN SMITH",
"validUntil" : "2021-01-01",
"number" : "4111111111"
},
"bankCardRiskScoreInfo" : {
"riskScore" : 0.01
}
} ]
},
// images uploaded for the action
"images" : [ {
"addedDate" : "2019-11-06 14:26:37",
"imageFileName" : "creditCard.png",
"resizedImageId" : 1545333812,
"mimeType" : "png",
"imageId" : 66881456
}, {
/// ...
} ]
}
# 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 setAction type
that you'd like to use - Step 2: [Backend] Generate an Access token with
externalActionId
anduserId
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
curl -X POST \
'https://api.sumsub.com/resources/accessTokens?userId=JamesBond007&externalActionId=JamesBond007Action1&levelName=action-liveness&ttlInSecs=600' \
-H 'Accept: application/json'
# Example response
{
"token": "_act-80bbf59b-98e6-4aa5-9310-82f2df5fe211",
"userId": "JamesBond007",
"externalActionId": "JamesBond007Action1"
}
# 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
[
{
"currency": "BTC",
"issuer": null,
"name": "Bitcoin",
"symbol": "btc",
"tokenId": 0
},
{
"currency": "BTC",
"issuer": "32TLn1WLcu8LtfvweLzYUYU6ubc2YV9eZs",
"name": "TetherUS",
"symbol": "USDT",
"tokenId": 1
},
{
"currency": "BSV",
"issuer": null,
"name": "Bitcoin SV",
"symbol": "bsv",
"tokenId": 0
},
{
"currency": "BCH",
"issuer": null,
"name": "Bitcoin Cash",
"symbol": "bch",
"tokenId": 0
},
{
"currency": "BSC",
"issuer": null,
"name": "Binance Smart Chain",
"symbol": "bsc",
"tokenId": 0
},
{
"currency": "BSC",
"issuer": "0x7130d2a12b9bcbfae4f2634d864a1ee1ce3ead9c",
"name": "Bitcoin BEP2",
"symbol": "BTCB",
"tokenId": 3
},
{
"currency": "LTC",
"issuer": null,
"name": "Litecoin",
"symbol": "ltc",
"tokenId": 0
},
{
"currency": "ETH",
"issuer": null,
"name": "Ethereum",
"symbol": "eth",
"tokenId": 0
},
{
"currency": "ETH",
"issuer": "0x497baef294c11a5f0f5bea3f2adb3073db448b56",
"name": "DEX",
"symbol": "DEX",
"tokenId": 7318
},
{
"currency": "ETH",
"issuer": "0xf293d23bf2cdc05411ca0eddd588eb1977e8dcd4",
"name": "Sylo",
"symbol": "SYLO",
"tokenId": 99705
},
{
"currency": "ETH",
"issuer": "0xf29992d7b589a0a6bd2de7be29a97a6eb73eaf85",
"name": "DMScript",
"symbol": "DMST",
"tokenId": 26063
},
{
"currency": "ETH",
"issuer": "0xf29e46887ffae92f1ff87dfe39713875da541373",
"name": "UniCrypt",
"symbol": "UNC",
"tokenId": 84904
},
{
"currency": "ETH",
"issuer": "0xf3586684107ce0859c44aa2b2e0fb8cd8731a15a",
"name": "KaratBank Coin",
"symbol": "KBC",
"tokenId": 109448
},
{
"currency": "ETH",
"issuer": "0xf3b3cad094b89392fce5fafd40bc03b80f2bc624",
"name": "PATRON",
"symbol": "PAT",
"tokenId": 16413
},
{
"currency": "ETH",
"issuer": "0xf3db5fa2c66b7af3eb0c0b782510816cbe4813b8",
"name": "Everex",
"symbol": "EVX",
"tokenId": 80506
},
{
"currency": "ETH",
"issuer": "0xf3db7560e820834658b590c96234c333cd3d5e5e",
"name": "Poker Chips",
"symbol": "CHP",
"tokenId": 34801
},
{
"currency": "ETH",
"issuer": "0xf4134146af2d511dd5ea8cdb1c4ac88c57d60404",
"name": "SunContract",
"symbol": "SNC",
"tokenId": 110851
},
{
"currency": "ETH",
"issuer": "0xf41e5fbc2f6aac200dd8619e121ce1f05d150077",
"name": "CryCash Token",
"symbol": "CRC",
"tokenId": 26998
},
{
"currency": "ETH",
"issuer": "0xf433089366899d83a9f26a773d59ec7ecf30355e",
"name": "Metal",
"symbol": "MTL",
"tokenId": 165477
},
{
"currency": "ETH",
"issuer": "0xf453b5b9d4e0b5c62ffb256bb2378cc2bc8e8a89",
"name": "Mark",
"symbol": "MRK",
"tokenId": 99170
},
{
"currency": "ETH",
"issuer": "0xf4faea455575354d2699bc209b0a65ca99f69982",
"name": "No BS Crypto",
"symbol": "NOBS",
"tokenId": 172642
},
{
"currency": "ETH",
"issuer": "0xf51ebf9a26dbc02b13f8b3a9110dac47a4d62d78",
"name": "APIX",
"symbol": "APIX",
"tokenId": 108528
},
{
"currency": "ETH",
"issuer": "0xf5238462e7235c7b62811567e63dd17d12c2eaa0",
"name": "CACHE Gold",
"symbol": "CGT",
"tokenId": 138207
},
{
"currency": "ETH",
"issuer": "0xf53c580bc4065405bc649cc077ff4f2f28528f4b",
"name": "Bittwatt",
"symbol": "BWT",
"tokenId": 135781
},
{
"currency": "ETH",
"issuer": "0xf629cbd94d3791c9250152bd8dfbdf380e2a3b9c",
"name": "Enjin Coin",
"symbol": "ENJ",
"tokenId": 95340
},
{
"currency": "ETH",
"issuer": "0xf6bf74a97d78f2242376769ef1e79885cf1f0c1c",
"name": "Kaaso",
"symbol": "KAASO",
"tokenId": 154578
},
{
"currency": "ETH",
"issuer": "0xf6dbe88ba55f1793ff0773c9b1275300f830914f",
"name": "Asian Dragon",
"symbol": "AD",
"tokenId": 131436
},
{
"currency": "ETH",
"issuer": "0xf70a642bd387f94380ffb90451c2c81d4eb82cbc",
"name": "Starbase",
"symbol": "STAR",
"tokenId": 148336
},
{
"currency": "ETH",
"issuer": "0xae7ab96520de3a18e5e111b5eaab095312d7fe84",
"name": "stETH (Lido)",
"symbol": "STETH",
"tokenId": 229167
},
{
"currency": "XLM",
"issuer": null,
"name": "Stellar",
"symbol": "xlm",
"tokenId": 0
},
{
"currency": "XLM",
"issuer": "GBUYUAI75XXWDZEKLY66CFYKQPET5JR4EENXZBUZ3YXZ7DS56Z4OKOFU",
"name": "USD",
"symbol": "USD",
"tokenId": 29
},
{
"currency": "XLM",
"issuer": "GDXTJEK4JZNSTNQAWA53RZNS2GIKTDRPEUWDXELFMKU52XNECNVDVXDI",
"name": "BTC",
"symbol": "BTC",
"tokenId": 30
},
{
"currency": "XLM",
"issuer": "GAQEDFS2JK6JSQO53DWT23TGOLH5ZUZG4O3MNLF3CFUZWEJ6M7MMGJAV",
"name": "HODL",
"symbol": "HODL",
"tokenId": 10961
},
{
"currency": "XLM",
"issuer": "GBK4AYTOYIAYT4UJECSQGMACUWLKYOOM4VCAUUZ3Y3FG5XD2LYK3FGK2",
"name": "USDS",
"symbol": "USDS",
"tokenId": 11026
},
{
"currency": "XLM",
"issuer": "GCOXXGNBUY2GN6PI3WN5KQLTXPLZO2D76R2KHN54AZUMDGAGYLMHIIWH",
"name": "BTC",
"symbol": "BTC",
"tokenId": 11296
},
{
"currency": "XLM",
"issuer": "GAENRLBJVADCN26ISXDVF7NRJ3LYDIOMTGDSKOJJGSQVEUKGJFJCI5XR",
"name": "MOON",
"symbol": "MOON",
"tokenId": 11316
},
{
"currency": "XLM",
"issuer": "GDNKOTYBWBKAYFFMIB2ULTYXAWM2ZBEF2Z6A3PI3GEEYYJBAZW7DPLWI",
"name": "STELLARHEAD",
"symbol": "STELLARHEAD",
"tokenId": 32543
},
{
"currency": "XLM",
"issuer": "GC4NPMOBQEYZWILWVOWGNO7TCYIPIAAAI4KABJKMEKTBQRSDR2LWLMFC",
"name": "TITANIUM",
"symbol": "TITANIUM",
"tokenId": 36438
},
{
"currency": "XLM",
"issuer": "GAVUUSDCAWXROHNJEJKFBXEEMVH5ZBVKGQ4MF3NBI7FANV3A626EGNZI",
"name": "RHODIUM",
"symbol": "RHODIUM",
"tokenId": 36450
},
{
"currency": "XLM",
"issuer": "GCYWZ3P3V6YGJJP3L5XY26XQYNKAZKFRSBNDT74Z5ID7HRK6FXTPOCWA",
"name": "IRIDIUM",
"symbol": "IRIDIUM",
"tokenId": 36462
},
{
"currency": "ETH",
"issuer": "0xeec2be5c91ae7f8a338e1e5f3b5de49d07afdc81",
"name": "Dopex Governance Token",
"symbol": "DPX",
"tokenId": 286520
},
{
"currency": "ETH",
"issuer": "0xef53462838000184f35f7d991452e5f25110b207",
"name": "Knit Finance",
"symbol": "KFT",
"tokenId": 310609
},
{
"currency": "ETH",
"issuer": "0xefe2afb5f2a9ea8ec6d8a57fe88febcfe29db813",
"name": "bUKHI",
"symbol": "bUKH",
"tokenId": 300181
},
{
"currency": "ETH",
"issuer": "0xf009f5531de69067435e32c4b9d36077f4c4a673",
"name": "Unvest",
"symbol": "UNV",
"tokenId": 310583
},
{
"currency": "BSC",
"issuer": "0x8ba1940d299d3fd2d64deb9ba8c552940a8c5d3b",
"name": "AFRICUNIA BANK",
"symbol": "AFCASH",
"tokenId": 1593682
},
{
"currency": "BSC",
"issuer": "0x201b93bc77cabeb8118495ca1b1a43b066acdb8a",
"name": "Rufus Finance",
"symbol": "Rufus",
"tokenId": 489485
}
]
# 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
curl -X POST \
'https://api.sumsub.com/resources/applicantActions/-/forApplicant/5f905c29e971ff53e5ec79e5/cryptoSourceOfFunds' \
-H 'Content-Type: application/json' \
-d '{
"direction": "deposit",
"txn": "cb68af8c91b6e8ac284f7370effd176f13c62f79c8e8fb6b2f890e802f5dd191",
"address": "1JWF1vJyyxxWJ27T9G3kStyFUGp47hvKiP",
"currency": "BTC"
}’
curl -X POST \
'https://api.sumsub.com/resources/applicantActions/-/forApplicant/5f905c29e971ff53e5ec79e5/cryptoSourceOfFunds' \
-H 'Content-Type: application/json' \
-d '{
"direction": "withdrawal",
"address": "1JWF1vJyyxxWJ27T9G3kStyFUGp47hvKiP",
"currency": "BTC"
}’
curl -X POST \
'https://api.sumsub.com/resources/applicantActions/-/forApplicant/5f905c29e971ff53e5ec79e5/cryptoSourceOfFunds' \
-H 'Content-Type: application/json' \
-d '{
"direction": "deposit",
"txn": "0x977dc0c94334340a86ed7591defbfce7bbca30a0290ebf60b96388c4e56c5741",
"address": "0xe81c65a55d60021c8bd0dc269ed2732780b5d238",
"currency": "ERC-20",
"tokenId": "OMGToken"
}’
curl -X POST \
'https://api.sumsub.com/resources/applicantActions/-/forApplicant/5f905c29e971ff53e5ec79e5/cryptoSourceOfFunds' \
-H 'Content-Type: application/json' \
-d '{
"direction": "deposit",
"txn": "29a3efd3ef04f9153d47a990bd7b048a4b2d213daaa5fb8ed670fb85f13bdbcf",
"address": "1P3S1grZYmcqYDuaEDVDYobJ5Fx85E9fE9",
"currency": "BSV"
}'
curl -X POST \
'https://api.sumsub.com/resources/applicantActions/-/forApplicant/5f905c29e971ff53e5ec79e5/cryptoSourceOfFunds' \
-H 'Content-Type: application/json' \
-d '{
"direction": "deposit",
"txn": "0x1087be99d867e5e68120a3ce464661596680ded3158c7257773c03fc1bc6e351",
"address": "0x9f8622b11984afc8f0a42a394928702017c5968d",
"currency": "ETH",
"tokenId": "172805"
}'
# Example response
{
"id": "5f927ff763619b175f15dbb9",
"createdAt": "2020-10-23 07:02:15",
"applicantId": "5f927fc063619b175f15dba5",
"type": "cryptoTransaction",
"review": {
"reprocessing": true,
"reviewResult": {
"reviewAnswer": "RED"
},
"reviewStatus": "completed",
"autoChecked": false
},
"checks": [],
"paymentChecks": [
{
"id": "5f927ff763619b175f15dbb8",
"answer": "RED",
"checkType": "cryptoSourceOfFundsRiskScore",
"cryptoTxnRiskScoreInfo": {
"riskScore": 0.284,
"txnMonitorData": {
"address": "1JWF1vJyyxxWJ27T9G3kStyFUGp47hvKiP",
"txn": "cb68af8c91b6e8ac284f7370effd176f13c62f79c8e8fb6b2f890e802f5dd191",
"time": "2019-10-08 14:33:27",
"updatedAt": "2020-10-23 07:02:14",
"amount": 643000000,
"fiat": 5285897,
"fiatCode": "usd",
"direction": "deposit",
"riskscore": 0.284,
"signals": {
"atm": 0.0,
"dark_market": 0.037,
"dark_service": 0.001,
"exchange_fraudulent": 0.052,
"exchange_mlrisk_high": 0.125,
"exchange_mlrisk_low": 0.645,
"exchange_mlrisk_moderate": 0.025,
"exchange_mlrisk_veryhigh": 0.044,
"exchange": null,
"gambling": 0.002,
"illegal_service": 0.0,
"marketplace": 0.0,
"miner": 0.008,
"mixer": 0.01,
"payment": 0.021,
"ransom": 0.0,
"scam": 0.001,
"stolen_coins": 0.014,
"trusted_exchange": null,
"wallet": 0.011
},
"status": "ready",
"riskyVolume": 7.626584867075664E7,
"riskyVolumeFiat": 626957.0
}
},
"createdAt": "2020-10-23 07:02:15"
}
],
"input": {
"cryptoTxnInfo": {
"currency": "BTC",
"txn": "cb68af8c91b6e8ac284f7370effd176f13c62f79c8e8fb6b2f890e802f5dd191",
"address": "1JWF1vJyyxxWJ27T9G3kStyFUGp47hvKiP",
"direction": "deposit"
}
},
"reviewResult": {
"reviewAnswer": "RED"
}
}
# 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
curl -X POST \
'https://api.sumsub.com/resources/standalone/crypto/cryptoSourceOfFunds' \
-H 'Content-Type: application/json' \
-d '{
"direction": "deposit",
"txn": "cb68af8c91b6e8ac284f7370effd176f13c62f79c8e8fb6b2f890e802f5dd191",
"address": "1JWF1vJyyxxWJ27T9G3kStyFUGp47hvKiP",
"currency": "BTC"
}’
# Example response
{
"data": {
"address": "1JWF1vJyyxxWJ27T9G3kStyFUGp47hvKiP",
"txn": "cb68af8c91b6e8ac284f7370effd176f13c62f79c8e8fb6b2f890e802f5dd191",
"time": "2019-10-08 14:33:27",
"updatedAt": "2020-10-23 06:39:15",
"amount": 643000000,
"fiat": 5285897,
"fiatCode": "usd",
"direction": "deposit",
"riskscore": 0.284,
"signals": {
"atm": 0.0,
"dark_market": 0.037,
"dark_service": 0.001,
"exchange_fraudulent": 0.052,
"exchange_mlrisk_high": 0.125,
"exchange_mlrisk_low": 0.645,
"exchange_mlrisk_moderate": 0.025,
"exchange_mlrisk_veryhigh": 0.044,
"exchange": null,
"gambling": 0.002,
"illegal_service": 0.0,
"marketplace": 0.0,
"miner": 0.008,
"mixer": 0.01,
"payment": 0.021,
"ransom": 0.0,
"scam": 0.001,
"stolen_coins": 0.014,
"trusted_exchange": null,
"wallet": 0.011
},
"status": "ready",
"riskyVolume": 7.626584867075664E7,
"riskyVolumeFiat": 626957.0
}
}
# 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
{
"applicantId": "5dc158b109494c3cbf431e28",
"applicantActionId": "5dc2d80ce3cc9b1c1e389c4c",
"externalApplicantActionId": "id122424234-action-random-r7otyykndi",
"inspectionId": "5dc158b109494c3cbf431e29",
"applicantType": "individual",
"correlationId": "req-8fbf5a81-339f-43b6-a9a7-290080e9039c",
"externalUserId": "pid122424234",
"type": "applicantActionPending",
"reviewStatus": "completed",
"createdAtMs": "2020-02-21 13:23:16.001"
}
{
"applicantId" : "5dc158b109494c3cbf431e28",
"applicantActionId" : "5dc2d80ce3cc9b1c1e389c4c",
"externalApplicantActionId": "id122424234-action-random-r7otyykndi",
"inspectionId" : "5dc158b109494c3cbf431e29",
"correlationId" : "req-c9041677-e8dc-446b-ab8f-50b438a40aa8",
"externalUserId" : "id122424234",
// note the type of the webhook
"type" : "applicantActionReviewed",
"reviewResult" : {
"reviewAnswer" : "GREEN"
},
"reviewStatus" : "completed",
"createdAtMs": "2020-02-21 13:23:19.001"
}
# Example applicantActionOnHold webhook payload
{
"applicantId": "5ea867a9772e27d66728c64b",
"applicantActionId": "5ea867c2772e27d66728c64f",
"inspectionId": "5ea867a9772e27d66728c64c",
"correlationId": "req-2c3cce19-c723-4fd0-a2f2-527789f95bcc",
"externalUserId": "random-4gguvx1oha",
"type": "applicantActionOnHold",
"reviewStatus": "init",
"createdAtMs": "2020-04-28 18:16:09.001"
}