# Actions

# Introduction

Actions are separate verification processes that are performed independently of the main applicant verification and do not affect its outcome. Applicant actions can be selected in the verification level settings.

Actions can be triggered by specific events. For example, when you need to verify that the account owner is the one currently using the account. In this case, the action «Face Authorization» is initiated.

Currently, we offer the following types of action verifications:

• Face authorization For successful verification, the face in the selfie (liveness or webcam photo) must match the face from the main profile.
• Email verification
• Source check
• Questionnaire

# Setting up a verification level

To use actions:

1. In the Dashboard, open the «Integration» page, tab «Individuals».
2. Click «Create Level».
3. In the «General» section, select «Applicant actions» from the «Type» dropdown.
4. In the «Required Steps» section, remove all verification steps except «Selfie».
5. In the «Action type» dropdown, select the type of action.
6. Complete the verification level setup and save the changes.

The results of actions can be obtained from the applicant or via webhooks.

# API Requests for actions

# POST Create applicant action

Use this request to create applicant actions.

POST /resources/applicantActions/-/forApplicant/{applicantId}?levelName={levelName}

Request parameters

Query parameters

Request body

Example

curl  -X  POST  \ 'https://api.idngo.kz/resources/applicantActions/-/forApplicant/63e096c51b6b4030f2e01154?levelName=some-level-name'  \
    -H 'Content-Type: application/json' \
    -d  '{
    "externalActionId": "yourActionId",
    "email": "example@email.com",
    "phone": "+49 123456789"
    }'

curl  -X  POST  \ 'https://api.idngo.kz/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": "example@email.com",
        "phone": "+49 123456789"
    }'

# POST Generate external WebSDK link for applicant action

POST /resources/sdkIntegrations/levels/{levelName}/websdkLink?externalUserId={externalUserId}&externalActionId={externalActionId}

Request parameters

Query parameters

Response

Example

curl  -X  POST  \
    'https://api.idngo.kz/resources/sdkIntegrations/levels/action-level/websdkLink?externalUserId=304775ty&externalActionId=actionID123'

{
    "url": "https://api.idngo.kz/idensic/l/#/lPDnIKwzmxPfDohk"
}

# POST Add image to applicant action

This endpoint adds an image to an action (for example, a face photo for “Face Authorization”).

POST /resources/applicantActions/{actionId}/images

Request parameters

You can obtain the action ID when creating a new action or by using the “GET Get actions of an applicant” request.

Request headers

Request body

Fields of the metadata object

Response

If the request is successfully processed, the response contains a JSON file with image information.

Fields of the idDocDef object

Example

curl  -X  POST  \
    'https://api.idngo.kz/resources/applicantActions/5e022e0f0a975a45325c7ff5/images' \
    -H  'Content-Type: multipart/form-data'  \
    -F 'metadata={"idDocType":"SELFIE","country":"GBR"}' \
    -F  'content=@/Sumsub/Example/name.jpg'

{
    "id": "66bb6c71546bfc57cffe92a8",
    "addedDate": "2024-08-13 14:23:45",
    "creatorClientId": "API",
    "imageHash": "64d2f3aa8da8a98fffaf751a9c323981474f6375",
    "imageFileName": "name.jpg",
    "resizedImageId": 603758274,
    "mimeType": "jpg",
    "sigHash": "3809bc3c-831d-4be3-8cee-1684553beffe",
    "imageId": 1411431805,
    "fileSize": 1362,
    "actualResolution": {
        "width": 192,
        "height": 192
    },
    "answer": "GREEN",
    "idDocDef": {
        "country": "GBR",
        "idDocType": "SELFIE"
    },
    "reviewResult": {},
    "attemptId": "teinm"
}

# POST Submit action for review

Use this endpoint to request a verification of an action.

The status of the action is set to pending, after which the action is ready for processing.

POST /resources/applicantActions/{actionId}/review/status/pending

Request parameters

You can obtain the action ID when creating a new action or by using the “GET Get actions of an applicant” request.

Example

curl  -X  POST  \
    'https://api.idngo.kz/resources/applicantActions/5e022e0f0a975a45325c7ff5/review/status/pending'

# GET Get action review result

GET /resources/applicantActions/{actionId}/one

Request parameters

You can obtain the action ID when creating a new action or by using the “GET Get actions of an applicant” request.

Response

Fields of review object

Fields of reviewResult object

Example

{
    // 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": {
                    "sessionId": "512deb48-bb6b-438c-ae7c-f8953351cc57",
                    "images": [
                        {
                            "imageId": 1368276695
                        },
                        {
                            "imageId": 1060469685
                        },
                        {
                            "imageId": 2074791000
                        },
                        {
                            "imageId": 810045545
                        },
                        {
                            "imageId": 1328042852
                        }
                    ]
                },
                "livenessResult": {
                    "answer": "GREEN",
                    "glasses": false,
                    "retryReason": 0
                }
            }
        },
        {
            "answer" : "GREEN",
            "checkType" : "FACE_MATCH",
            "createdAt" : "2019-10-10 18:20:00",
            "faceMatchInfo" : {
                "answer" : "GREEN",
            }
        } 
    ]
}

# GET Get actions of an applicant

This endpoint allows you to retrieve a list of actions that belong to an applicant.

GET /resources/applicantActions/-;applicantId={applicantId}?limit={limit}&offset={offset}&order=-createdAt

Request parameters

Query parameters

Response

The response contains a list of actions and the total count.

The list element contains the actions, whose structure is described in the section “GET Get action review result”.

Example

curl  -X  GET  \
    'https://api.idngo.kz/resources/applicantActions/-;applicantId=5e5f9ab10a975a6e224dc286?limit=100&order=-createdAt'

{
    "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
    }
}

# GET Get original image

GET /resources/applicantActions/{actionId}/images/{imageId}?preview={isPreview}

Request body

Query parameters

# Applicant actions in WebSDK

Initialize WebSDK with externalActionId as described in the sections WebSDK and Getting Started.

Generate access token for actions:
POST /resources/accessTokens?userId={externalUserId}&externalActionId={externalActionId}&levelName={levelName}

Example

curl  -X  POST  \
    'https://api.idngo.kz/resources/accessTokens?userId=JamesBond007&externalActionId=JamesBond007Action1&levelName=action-liveness&ttlInSecs=600' \
    -H  'Accept: application/json'

{
    "token": "_act-80bbf59b-98e6-4aa5-9310-82f2df5fe211",
    "userId": "JamesBond007",
    "externalActionId": "JamesBond007Action1"
}

# Applicant actions for Android SDK

Initialize the Android SDK with externalActionId as described in the sections Android SDK and Getting Started.

When processing the «Face Authorization» action, the user is taken to the FaceScan (Liveness) screen, and after the check is completed, the SDK automatically closes.

val onSDKStateChangedHandler: (CBRSDKState, CBRSDKState) -> Unit = { newState, prevState ->
    Timber.d("onSDKStateChangedHandler: $prevState -> $newState")
    // Completion of the face authentication process
    if (newState is CBRSDKState.ActionCompleted) {
        val actionId = newState.actionId
        val type = newState.type
        val answer = newState.answer
        val payload = newState.payload
    }
}

CBRStateChangedHandler  stateChangedHandler  = (prevState, newState) -> {
    Timber.d("The SDK state was changed: "  + prevState +  " -> "  + newState);
    // Completion of the face authentication process
    if (newState instanceof  CBRSDKState.ActionCompleted) {
        CBRSDKState.ActionCompleted  actionState  = (CBRSDKState.ActionCompleted) newState;
        String  actionId  =  actionState.getActionId();
        FlowActionType  type  =  actionState.getType();
        String  answer  =  actionState.getAnswer();
        Map<String, Object> payload  =  actionState.getPayload();
    }
};

# Notification of action results

To receive the result of an action and manage the action process, you can use this handler.

The handler accepts two parameters:

• actionId : String — ID of the action.
• answer : String — response from the liveness check module.

Possible values:

• GREEN
• YELLOW
• RED
• ERROR
• null

The handler should return CBRActionResult. The following values are supported:

• CBRActionResult.Continue — continue the default action scenario (show result screen, etc.).
• CBRActionResult.Cancel — cancel the default action scenario (close SDK without showing the result screen).

val onActionResultHandler: CBRActionResultHandler = object : CBRActionResultHandler {
    override fun onActionResult(actionId: String, actionType: String, answer: String?, allowContinuing: Boolean): CBRActionResult {
        Timber.d("Face Auth action result: actionId: $actionId answer: $answer")
        // Using the default scenario
        return CBRActionResult.Continue
    }
}
val cbrSdk = CBRMobileSDK.Builder(this).withActionResultHandler(onActionResult)

CBRActionResultHandler  actionResultHandler  = (actionId, actionType, answer, allowContinuing) -> {
    Timber.d("Action Result: actionId: "  + actionId +  ", answer: "  + answer);
    return  CBRActionResult.Continue;
    };

CBRMobileSDK.SDK  cbrSdk  =  new CBRMobileSDK.Builder(requireActivity()).withActionResultHandler(actionResultHandler).build();

# Applicant actions for iOS SDK

Initialize the iOS SDK with externalActionId as described in the iOS SDK and Getting Started sections.

The «Face Authorization» actions are handled as follows:

• During the «Face Authorization» action, the user is taken to the FaceScan (Liveness) screen, and after the check is completed, the SDK automatically closes.
• After the process is completed, the sdk.status property is set to .actionCompleted, and sdk.actionResult contains the result of the last performed action.
• To determine the SDK status and get the action result, you can use one of the following callbacks: onDidDismiss, dismissHandler, or onStatusDidChange.

sdk.onDidDismiss { (sdk) in
    switch sdk.status {
    case .failed:
        print("failReason: [\(sdk.description(for: sdk.failReason))] - \(sdk.verboseStatus)")
    case .actionCompleted:
        // the Face authentication action was performed or cancelled
        if  let result = sdk.actionResult {
            print("Face Auth action result: actionId=\(result.actionId) answer=\(result.answer  ??  "<none>")")
        } else {
            print("Face Auth action was cancelled")
        }
    default:
        // in case of Face authentication action, the other statuses are not used for now,
        // but you could see them if the user closes the sdk before the level is loaded
        break
    }
}

# Notification of action results

The result of the «Face Authorization» action is represented by the sdk.actionResult property, which includes the following fields:

The absence of sdk.actionResult means that the user canceled the verification process.

# Handling the action check result

For «Face Authorization» actions, an optional handler actionResultHandler is available, which allows processing the result after it is received from the server. At this point, the user sees the processing screen (Processing).

sdk.actionResultHandler { (sdk, result, onComplete) in
    print("Face Auth action result handler: actionId=\(result.actionId) answer=\(result.answer  ??  "<none>")")
    // you are allowed to process the result asynchronously, just don't forget to call `onComplete` when you finish,
    // you could pass `.cancel` to force the user interface to close, or `.continue` to proceed as usual
    onComplete(.continue)
}

# Webhooks

The types of webhooks we send depend on the settings in the «Dev space» section.

For more information about webhooks, see here.

Example of 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.098"
}

{
    "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.987"
}

{
    "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.888"
}