❗️
Warning
This API method is experimental and may change or be deprecated in the future. It is not guaranteed to remain stable, and its use may require adjustments over time.

Overview

Use this method to get a list of documents required from a particular applicant to pass verification.

📘
Note
To change the set of required documents, use this method.

Request example

curl -X POST \
     'https://api.sumsub.com/resources/applicants/63620c095cc65d0001ffc8d7/requiredIdDocs'

Response explained

The response is a JSON file that represents the requiredIdDocs object — configuration of steps for the applicant to complete verification. It includes a set of required documents and data to provide.

Root variables (`requiredIdDocs` attributes)

The requiredIdDocs object represents the configuration of steps for the applicant to complete verification. It includes a set of required documents and data to provide.

Field	Type	Description
`videoIdent`	Boolean	Specifies if the video identification is required (`true`) or not required (`false`) to pass verification.
`videoIdentUploadTypes`	Array of strings	Lists the document types that can be uploaded during a video interview, if such documents are specified in the level settings. The field is available if the video identification is required on the level.
`stepsOutsideVideoId`	Array of strings	Lists the verification steps that can be passed outside the video identification. The field is available if the video identification is required on the level.
`docSets`	Array of objects	Includes the objects representing specific document sets and their attributes.

`docSets` element fields

The following table explains the element fields of the docSets array representing specific document sets and their attributes.

Field	Type	Description
`idDocSetType`	String	A human-readable identifier of the document set type, for example, `IDENTITY`, `SELFIE`, `PROOF_OF_RESIDENCE`, and so on. For details, refer to the following table with descriptions of each type.
`fields`	Array of objects	Includes the objects describing the document data fields that should be filled with personal information to verify the applicant. Each object contains the following attributes: `name` (String) — the field name, for example, `firstName`, `lastName`, `email`, and so on. `required` (Boolean) — `true` if the field is required for verification, `false` if not (still, it can be optionally filled in the SDK).
`types`	Array of strings	Includes the types of documents that are required for a particular `idDocSetType` to pass verification. See the following tables with supported document types for individuals and for companies.
`videoRequired`	String	Method of passing the document upload step that can be set up when configuring a verification level. `disabled` — selfie with a document. `enabled` — video selfie with a phrase. `photoRequired` — web camera photo (still face image). `passiveLiveness` — liveness check. `docapture` — enables the camera for the steps with ID documents, so applicants can take pictures of their documents in real time.
`captureMode`	String	This mode is applied in case the `docapture` method is used (see the table row above). `manualAndAuto` — allows both to automatically capture the photo of a document when the camera is initialized, and for the applicant to hit a button to take a photo. `manualOnly` — allows only manually hitting a button to take a photo.
`uploaderMode`	String	This mode is applied in case the `docapture` method is used. `always` — always allows uploading a ready-made photo instead of using a camera. `never` — does not allow uploading a ready-made photo. `fallback` — allows uploading a ready-made photo only if a camera is not available.
`paymentMethods`	Array of objects	Describes the configuration details of the payment method added to the level.
`questionnaireDefId`	String	Identifier of the questionnaire that is added to the verification level and is to be or has already been filled by the applicant.
`steps`	Array of objects	This field is available for company applicants, and includes the documents and data a company along with beneficiaries have to provide to pass verification.

`steps` element fields

The following table explains the element fields available in the steps array objects.

Field	Type	Description
`name`	String	Indicates whose documents and data must be provided to pass the step, the company or its beneficiaries. Available values: `company`, `ubos`, `shareholders`, `representatives`, `directors`.
`minDocsCnt`	Integer	Minimum number of documents an applicant should provide at the company data step.
`applicantLevelName`	String	Name of the verification level an applicant has to pass.
`idDocTypes`	String	Type of the corporate document to be provided for verification.
`idDocSubTypes`	String	Subtype of the corporate document to be provided for verification.
`fields`	Array of objects	Includes the objects describing the document data fields that should be filled with personal information to verify the applicant. Each object contains the following attributes: `name` (String) — the field name, for example, `firstName`, `lastName`, `email`, and so on. `required` (Boolean) — `true` if the field is required for verification, `false` if not (still, it can be optionally filled in the SDK).
`customFields`	Array of objects	Custom data fields to be filled for verification.
`captureMode`	String	This mode is applied in case the `docapture` method is used (see the table row above). `manualAndAuto` — allows both to automatically capture the photo of a document when the camera is initialized, and for the applicant to hit a button to take a photo. `manualOnly` — allows only manually hitting a button to take a photo.

Response examples

If the request is successfully sent and processed, you will get a response like the following.

{
  "videoIdent": true,
  "stepsOutsideVideoId": [
    "APPLICANT_DATA",
    "QUESTIONNAIRE",
    "EMAIL_VERIFICATION"
  ],
  "docSets": [
    {
      "idDocSetType": "IDENTITY",
      "types": [
        "ID_CARD"
      ]
    },
    {
      "idDocSetType": "SELFIE",
      "types": [
        "SELFIE"
      ],
      "videoRequired": "passiveLiveness"
    },
    {
      "idDocSetType": "APPLICANT_DATA",
      "fields": [
        {
          "name": "firstName",
          "required": true
        },
        {
          "name": "lastName",
          "required": true,
          "prefill": null
        },
        {
          "name": "placeOfBirth",
          "required": true
        },
        {
          "name": "nationality",
          "required": false
        },
        {
          "name": "gender",
          "required": false
        },
        {
          "name": "taxResidenceCountry",
          "required": false
        },
        {
          "name": "postCode",
          "required": false
        }
      ]
    },
    {
      "idDocSetType": "IDENTITY2",
      "types": [
        "PASSPORT"
      ]
    },
    {
      "idDocSetType": "IDENTITY3",
      "types": [
        "DRIVERS"
      ]
    },
    {
      "idDocSetType": "IDENTITY4",
      "types": [
        "RESIDENCE_PERMIT"
      ]
    },
    {
      "idDocSetType": "SELFIE2",
      "types": [
        "VIDEO_SELFIE"
      ],
      "videoRequired": "enabled"
    },
    {
      "idDocSetType": "PROOF_OF_RESIDENCE",
      "types": [
        "UTILITY_BILL"
      ],
      "fields": [
        {
          "name": "country",
          "required": false
        },
        {
          "name": "town",
          "required": false
        },
        {
          "name": "street",
          "required": false
        }
      ],
      "poaStepSettingsId": "64a57ec5ee8c75121acf2c83"
    },
    {
      "idDocSetType": "PROOF_OF_RESIDENCE2",
      "types": [
        "UTILITY_BILL2"
      ],
      "poaStepSettingsId": "64a57ec5ee8c75121acf2c83"
    },
    {
      "idDocSetType": "QUESTIONNAIRE",
      "questionnaireDefId": "1"
    },
    {
      "idDocSetType": "PHONE_VERIFICATION"
    },
    {
      "idDocSetType": "EMAIL_VERIFICATION"
    },
    {
      "idDocSetType": "E_KYC"
    }
  ]
}

{
  "docSets": [
    {
      "idDocSetType": "COMPANY",
      "types": [
        "COMPANY_DOC"
      ],
      "steps": [
        {
          "name": "company",
          "minDocsCnt": 1,
          "applicantLevelName": "Beneficiary_level",
          "idDocTypes": [
            "COMPANY_DOC"
          ],
          "idDocSubTypes": [
            "INCORPORATION_CERT",
            "INCORPORATION_ARTICLES",
            "SHAREHOLDER_REGISTRY",
            "DIRECTORS_REGISTRY",
            "STATE_REGISTRY",
            "INCUMBENCY_CERT",
            "PROOF_OF_ADDRESS",
            "TRUST_AGREEMENT",
            "INFORMATION_STATEMENT",
            "GOOD_STANDING_CERT",
            "OTHER"
          ],
          "fields": [
            {
              "name": "companyName",
              "required": true
            },
            {
              "name": "country",
              "required": true
            },
            {
              "name": "registrationNumber",
              "required": true
            }
          ],
          "customFields": null,
          "captureMode": null
        },
        {
          "name": "ubos",
          "minDocsCnt": 0,
          "applicantLevelName": "basic-kyc-level",
          "idDocTypes": null,
          "idDocSubTypes": null,
          "fields": null,
          "customFields": null,
          "captureMode": null
        },
        {
          "name": "shareholders",
          "minDocsCnt": 0,
          "applicantLevelName": "basic-kyc-level",
          "idDocTypes": null,
          "idDocSubTypes": null,
          "fields": null,
          "customFields": null,
          "captureMode": null
        },
        {
          "name": "representatives",
          "minDocsCnt": 0,
          "applicantLevelName": "basic-kyc-level",
          "idDocTypes": null,
          "idDocSubTypes": null,
          "fields": null,
          "customFields": null,
          "captureMode": null
        },
        {
          "name": "directors",
          "minDocsCnt": 0,
          "applicantLevelName": "basic-kyc-level",
          "idDocTypes": null,
          "idDocSubTypes": null,
          "fields": null,
          "customFields": null,
          "captureMode": null
        }
      ]
    },
    {
      "idDocSetType": "QUESTIONNAIRE",
      "questionnaireDefId": "KYB_1"
    },
    {
      "idDocSetType": "EMAIL_VERIFICATION"
    },
    {
      "idDocSetType": "PHONE_VERIFICATION"
    }
  ]
}

If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example:

{
  "description": "HTTP 404 Not Found",
  "code": 404,
  "correlationId": "f5beafa748d54d4afb1c51b11370481e"
}

Get required ID documents

❗️
Warning

Overview

📘
Note

Request example

Response explained

Root variables (`requiredIdDocs` attributes)

`docSets` element fields

`steps` element fields

Response examples

❗️Warning

Overview

📘Note

Request example

Response explained

Root variables (requiredIdDocs attributes)

docSets element fields

steps element fields

Response examples

❗️
Warning

📘
Note

Root variables (`requiredIdDocs` attributes)

`docSets` element fields

`steps` element fields