Table of contents

• Overview
• Request examples
  • Change verification level
  • Change level and reset steps
  • Reset verification steps
  • Available steps to reset
• Response explained

Overview

Use this method to change a verification level and/or reset specific verification steps.

This endpoint is useful when your verification requirements change after an applicant has already started the process. For example, if you initially required only an ID document and a selfie, but now need to collect proof of address, you can use this method to adjust the flow accordingly.

Depending on your use case, you can do the following:

• Change a verification level.
• Change a verification level and reset one or several verification steps in the new level.
• Reset a specific verification step of the level.

This method supports both individual and company applicants. Refer to the request examples below for implementation details.

🚧

Attention

Make sure to check the applicant status before applying the method. You will not be able to use it if reviewStatus of the applicant is pending, queued or onHold.

📘

Note

If you are using our SDKs, you can initialize it with suitable levelName on accessToken and SDK will change the level automatically.

Request examples

Below, you can see the request examples for different usage scenarios where the method can be applied.

Change verification level

To change a verification level for a specific applicant, submit the applicant identifier (applicantId) along with the name of a new level (name) you want to assign to the applicant as shown in the examples below.

curl -X POST \
  'https://api.sumsub.com/resources/applicants/5f80e6b7155a6336271e4677/moveToLevel?name=kyc-with-poa' \
  -H 'Content-Type: application/json' \

curl -X POST \
  'https://api.sumsub.com/resources/applicants/5f80e6b7155a6336271e4677/moveToLevel?name=basic-kyb-level' \
  -H 'Content-Type: application/json' \

In the response, pay attention to the following updated fields:

• requiredIdDocs — configuration of steps for the applicant to complete verification.
• levelName — the name of the new verification level that you have assigned for the applicant.

Change level and reset steps

You can also change a verification level and reset one or several verification steps in this new level. To do this, submit the applicant identifier (applicantId) along with the name of a new level (name) and the docSets object with all idDocSetType attributes that have the value(s) representing the step(s) to reset as shown in the examples below.

📘

Notes

• For individual applicants, you can add the “resetOnlyIfUnsuitable”: true parameter to the idDocSetType to enable flexible step reset. This parameter is only applicable to the following steps: IDENTITY, IDENTITY2, IDENTITY3, IDENTITY4, PROOF_OF_RESIDENCE, PROOF_OF_RESIDENCE2, SELFIE, SELFIE2, QUESTIONNAIRE.
• For company applicants, you may include the companyDocsGroupDefinitions object to reset only specific sub-steps.

curl -X POST \
  'https://api.sumsub.com/resources/applicants/5f80e6b7155a6336271e4677/moveToLevel?name=kyc-new-level' \
  -H 'Content-Type: application/json' \
  -d '{
        "docSets": [
          {
            "idDocSetType": "IDENTITY",
            "resetOnlyIfUnsuitable": true  // Enable flexible reset
          },
          {
            "idDocSetType": "PROOF_OF_RESIDENCE"  // Enable reset
          }
        ]
      }'

curl -X POST \
  'https://api.sumsub.com/resources/applicants/5f80e6b7155a6336271e4677/moveToLevel?name=kyb-new-level' \
  -H 'Content-Type: application/json' \
  -d '{
          "docSets": [
              {
                  "idDocSetType": "COMPANY_DATA"
              },
              {
                  "idDocSetType": "COMPANY_DOCUMENTS",
                  "companyDocsGroupDefinitions": [
                      "legalPresence",
                      "companyDetails"
                  ]
              }
          ]
      }'

Reset verification steps

To reset only a verification step or a few steps, submit the applicant identifier (applicantId) along with the current level name (name) and the docSets object with all idDocSetType attributes that have the value(s) representing the step(s) to reset as shown in the examples below.

This method differs from another dedicated endpoint in that it allows resetting multiple verification steps simultaneously. See the list of available steps for reset below.

📘

Notes

• For individual applicants, you can add the “resetOnlyIfUnsuitable”: true parameter to the idDocSetType to enable flexible step reset. This parameter is only applicable to the following steps: IDENTITY, IDENTITY2, IDENTITY3, IDENTITY4, PROOF_OF_RESIDENCE, PROOF_OF_RESIDENCE2, SELFIE, SELFIE2, QUESTIONNAIRE.
• For company applicants, you may include the companyDocsGroupDefinitions object to reset only specific sub-steps.

curl -X POST \
  'https://api.sumsub.com/resources/applicants/5f80e6b7155a6336271e4677/moveToLevel?name=kyc-new-level' \
  -H 'Content-Type: application/json' \
  -d '{
        "docSets": [
          {
            "idDocSetType": "IDENTITY",
            "resetOnlyIfUnsuitable": true  // Enable flexible reset
          },
          {
            "idDocSetType": "PROOF_OF_RESIDENCE"  // Enable reset
          }
        ]
      }'

curl -X POST \
  'https://api.sumsub.com/resources/applicants/5f80e6b7155a6336271e4677/moveToLevel?name=kyb-level-name' \
  -H 'Content-Type: application/json' \
  -d '{
          "docSets": [
              {
                  "idDocSetType": "COMPANY_DATA"
              },
              {
                  "idDocSetType": "COMPANY_DOCUMENTS",
                  "companyDocsGroupDefinitions": [
                      "legalPresence",
                      "companyDetails"
                  ]
              }
          ]
      }'

Available steps to reset

The following table details the verification steps available for reset.

📘

Note

The COMPANY_BENEFICIARIES step cannot be reset. To remove a beneficiary applicant from the company's control and ownership structure, use the following method.

Response explained

The response is a JSON object representing the applicant profile, enriched with structured data.

You can see the response structure, possible content with descriptions, and examples of response on this page.