Table of contents

• Overview
  • Example request
• Response explained
  • Root variables
  • Root variable attributes and element fields
    • reviewResult
    • imageReviewResults
    • stepStatuses
    • images
  • Response examples

Overview

Use this method to fetch information about the documents or separate verification step results.

📘

Note

Some rejection types may not affect document status; do not forget to check the overall applicant review status and answer.

Example request

curl -X GET \
  'https://api.sumsub.com/resources/applicants/5bb8cca10a975a624903cf65/requiredIdDocsStatus'

Response explained

The response is a JSON file that represents a breakdown for each required step an applicant has to complete to pass verification. It includes the documents and data provided as well as review results.

If an applicant is rejected with the FINAL rejection label within the webhook payload or at the answer from this endpoint, the response from requiredIdDocsStatus may not provide much useful information. If you need to access moderationComment or clientComment for a FINAL rejection, retrieve this information from the webhook or applicant data payload.

📘

Note

Some steps may not have review results. It depends on the review of other steps. e.g. PROOF_OF_RESIDENCE step depends on the IDENTITY step if it exists, so PROOF_OF_RESIDENCE may not have been checked until IDENTITY is approved.

Root variables

Root variables are the objects representing the step identifiers (verification types an applicant has to complete). These objects nest their own attributes and element fields. The existence of some objects depends on the required steps added to verification levels.

Root variable attributes and element fields

The following table describes possible attributes and element fields of the root variables that represent the applicant verification steps, and are specified in the table above.

📘

Note

The null value for a field means that the required step has no data to display because it was not completed during verification. For example, an applicant has not yet reached this step and therefore has not provided necessary data.

reviewResult attributes

The following table explains the reviewResult object attributes that represent the review result details including reject types and comments.

imageReviewResults attributes

The following table describes the imageReviewResult object which is a map that includes a key element (imageId) and a tailored object (reviewResult) that explains the review results of the uploaded document image.

stepStatuses element fields

The following table describes the substeps that are used for the COMPANY required step only, and represents the statuses of these substeps based on the provided information for beneficiaries, UBOs, and representatives.

images element fields

The following table explains the images element fields. It includes information about each document image provided, and the review result regarding the specified image.

Response examples

{
  "IDENTITY": {
   // a step identifier
    "reviewResult": {
    // if exists, that means that a document was uploaded
      "moderationComment": "Please upload a photo of the front of your ID card.",
      "reviewAnswer": "RED"
    },
    "country": "LVA", // document country
    "idDocType": "ID_CARD", // specific document type for the step
    "imageIds": [122352326,34246467], // image IDs that represent a document
    //If imageIds array contains more than one element, the first one would be front side and others - back sides
    "imageReviewResults": {
      "34246467": {
        "reviewAnswer": "GREEN"
      },
      "122352326": {
        "moderationComment": "Please upload a photo of the front of your ID card.", // A human-readable comment that can be shown to your end user
        "clientComment": "One side of the document is missing.",  //A human-readable comment that should not be shown to an end user, and is meant to be read by a client
        "reviewAnswer": "RED",
        "rejectLabels": ["DOCUMENT_PAGE_MISSING","FRONT_SIDE_MISSING"],
        "reviewRejectType": "RETRY"
      }
    }
  },
  "SELFIE": {
    "reviewResult": {
      "reviewAnswer": "GREEN"
    },
    "country": "LVA",
    "idDocType": "SELFIE",
    "imageIds": [181314576],
    "imageReviewResults": {
      "181314576": {
        "reviewAnswer": "GREEN"
      }
    }
  }
}

{
  "COMPANY": {
    "reviewResult": {
      "moderationComment": "Please provide in addition a document, such as the shareholder registry, allowing to establish all the ultimate beneficial owners (natural persons possessing over 25% of the company) and to confirm that the previously declared data on beneficial ownership matches this document.",
      "reviewAnswer": "RED"
    },
    "country": "MLT",
    "idDocType": "COMPANY_DOC",
    "imageIds": [1473345488],
    "imageReviewResults": {
      "1473345488": {
        "moderationComment": "Please provide in addition a document, such as the shareholder registry, allowing to establish all the ultimate beneficial owners (natural persons possessing over 25% of the company) and to confirm that the previously declared data on beneficial ownership matches this document.",
        "reviewAnswer": "RED",
        "rejectLabels": ["ADDITIONAL_DOCUMENT_REQUIRED"]
      }
    }
  }
}