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

Overview

📘
Note

Request example

Response explained

Root variables (`requiredIdDocs` attributes)

`docSets` element fields

`steps` element fields

Response examples

Overview

📘Note

Request example

Response explained

Root variables (requiredIdDocs attributes)

docSets element fields

steps element fields

Response examples

📘
Note

Root variables (`requiredIdDocs` attributes)

`docSets` element fields

`steps` element fields