Table of contents
Overview
Use this method to create an applicant action for a certain applicant with the required steps configured in the specified verification level.
You can create an applicant action to check:
Additionally, you can enable auto-parser to search for a matching transaction in a bank statement.
Mind the following
- At least one body parameter is required to create an applicant action. Submitting an empty request will return an error (see the error example).
- Any check specified in the request body must also be configured as a required step in the verification level; otherwise, it will not be performed. For example, if you add the
Auto-parser for bank statement transactions
The system can automatically search for a matching transaction in a bank statement (PDF or screenshot) uploaded by an applicant as proof of account or payment. The search is based on transaction details that you provide via API when creating an applicant action.
How it works
The auto-parser works as follows:
- You submit transaction data in
paymentSource.checksum.txns(see the auto-parsing request example). - The applicant uploads a bank statement (PDF or screenshot) as proof of account or payment.
- The system automatically searches the statement for a matching transaction.
Note
If you submit an empty
paymentSource.checksum.txnsarray, no check will be performed.
How to enable
To enable this functionality, submit transaction data in paymentSource.checksum.txns. Matching is performed using the following parameters from your API request:
date— transaction date.amount— transaction amount.currencyCode— currency code of the transaction.
How to view results
The results of the automatic parsing are displayed in the Dashboard as cross-check indicators:
- Green — a matching transaction was found.
- Red — no matching transaction was found or the values do not match.
Specifics of questionnaire action
If you want to include the answers to your questionnaire into the action request, add the questionnaire properties to the body parameters. The questionnaire object should be added to the questionnaires array (see the example below).
Questionnaire object example:
{
"id": "Example_Questionnaire",
"sections": {
"section_id_1": { // Section ID
"items": {
"item_id_0": { // Item ID
"values": [ // Item values
"EUR",
"USD"
]
},
"item_id_1": { // Item ID
"value": "String Value", // Item values, string
}
}
},
"section_id_2": { // Section ID
"items": {
"item_id_3": { // Item ID
"value": null // Item values, null
}
}
}
}
}
Request examples
curl -X POST \ 'https://api.sumsub.com/resources/applicantActions/-/forApplicant/63e096c51b6b4030f2e01154?levelName=some-level-name' \
-H 'Content-Type: application/json' \
-d '{
"externalActionId": "yourActionId",
"email": "[email protected]",
"phone": "+49 123456789"
}'
curl -X POST \ 'https://api.sumsub.com/resources/applicantActions/-/forApplicant/63e096c51b6b4030f2e01154/?levelName=action%20paymentSource%20level-name' \
-H 'content-type: application/json' \
-d '{
"paymentSource": {
"fixedInfo": {
"accountIdentifier": "XXX000333",
"email": "[email protected]",
"fullName": "John Doe",
"type": "bankCard",
"institutionName": "someBank"
}
},
"externalActionId": "yourActionId"
}'
curl -X POST \
'https://api.sumsub.com/resources/applicantActions/-/forApplicant/63e096c51b6b4030f2e01154/?levelName=action%20paymentSource%20level-name' \
-H 'content-type: application/json' \
-d '{
"paymentSource": {
"fixedInfo": {
"type": "bankStatement"
},
"checksum": {
"txns": [
{
"date": "2024-01-23 23:00:00",
"amount": 9.99,
"currencyCode": "USD"
},
{
"date": "2024-01-22 23:00:00",
"amount": 10.00,
"currencyCode": "USD"
},
{
"date": "2023-08-08 23:00:00",
"amount": 15.00,
"currencyCode": "USD"
}
]
}
},
"externalActionId": "123"
}'
curl -X POST \ 'https://api.sumsub.com/resources/applicantActions/-/forApplicant/63e096c51b6b4030f2e01154?levelName=questionnaire-level' \
-H 'Content-Type: application/json' \
-d '{
"questionnaires": [
{
"id": "Example_Questionnaire",
"sections": {
"section_id_1": { // Section ID
"items": {
"item_id_0": { // Item ID
"values": [ // Item values
"EUR",
"USD"
]
},
"item_id_1": { // Item ID
"value": "String Value", // Item values, string
}
}
},
"section_id_2": { // Section ID
"items": {
"item_id_3": { // Item ID
"value": null // Item values, null
}
}
}
}
}
],
"externalActionId": "yourActionId",
"email": "[email protected]",
"phone": "+49 123456789"
}'
Response explained
The response is a JSON file that represents the structured information of the created action. You can see the response structure and possible content with descriptions on the following page.
Response examples
Successful example
If the request is successfully sent and processed, you will get a response like the one below.
{
"id": "6855288fd81d19bd5d6065e9",
"createdAt": "2025-06-20 09:23:27",
"clientId": "your_cool_id",
"externalActionId": "yourActionId",
"applicantId": "63e096c51b6b4030f2e01154",
"type": "paymentMethod",
"review": {
"reviewId": "oaEgS",
"attemptId": "UHQzN",
"attemptCnt": 0,
"levelName": "paymentSource",
"createDate": "2025-06-20 09:23:27+0000",
"reviewStatus": "init"
},
"requiredIdDocs": {
"docSets": [
{
"idDocSetType": "PAYMENT_METHODS",
"types": [
"PAYMENT_SOURCE"
]
}
]
},
"paymentSource": {
"id": "b50c1d57-f603-480f-ae34-e9372d75612d",
"createdAt": "2025-06-20 09:23:27",
"fixedInfo": {
"type": "bankCard",
"institutionName": "cool_institution_name",
"institutionNameEn": {
"value": "cool_institution_name",
"originalValue": null
},
"fullName": "John Doe",
"fullNameEn": {
"value": "John Doe",
"originalValue": null
},
"accountIdentifier": "XXX000333"
}
}
}
Error example
If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example:
// This error occurs when an empty applicant action is submitted (no body parameters or only empty fields).
{
"code": 400,
"correlationId": "9272f926091b22d247022257f58e9f43",
"description": "Applicant action should not be empty",
"type": "de. smtdp.commons. service. exceptions. ServiceException"
}