Get status of verification steps

Returns the information about the documents or separate verification step results. The method works both for individuals and company applicants.

Table of contents

Overview

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

📘

Note

Some rejection types may not affect the 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.

ObjectDescription
COMPANY⚠️ This object is dedicated for company applicants only.

It represents the Company required step for verification. The existence of certain included fields depends on the step configuration in the associated verification level.
APPLICANT_DATAType of verification where an applicant needs to provide personal data in the fields pre-configured when adding the Applicant data step to the verification level.

For example, you could select the field types from the predefined list and request such data as the first name, last name, phone number, date of birth, tax residence country, and so on, or add custom fields to request additional information.
IDENTITYID verification where an applicant has to submit a photo of identity document to be verified. This type is added to the verification level as the Identity document step.

When adding this step, you can request to submit an ID card, passport, driver’s license, and residence permit as an identity document either all or some of them at one step, or configure additional steps (IDENTITY2, IDENTITY3, IDENTITY4) for each document.

⚠️ Mind that if you have selected all the available document types in one step, you will not be able to add another IDENTITY step to the level.
IDENTITY2Same as IDENTITY. Used in case you decide to add a separate required step to the verification level for each document or some of them.
IDENTITY3Same as IDENTITY. Used in case you decide to add a separate required step to the verification level for each document or some of them.
IDENTITY4Same as IDENTITY. Used in case you decide to add a separate required step to the verification level for each document or some of them.
SELFIEType of verification where an applicant needs to complete either of the following Selfie options:If you need an applicant to pass two steps of those above, add the 2nd selfie step to the verification level.
SELFIE2Same as SELFIE. Used in case you need to add another Selfie option to the verification level.
PROOF_OF_RESIDENCEAddress verification where an applicant is required to provide proof of residency. At this step the option of using geolocation is available.

If you need an applicant to provide one more document for residence confirmation, add the 2nd proof of address step to the verification level.
PROOF_OF_RESIDENCE2Similar to PROOF_OF_RESIDENCE. Used in case you need to add another Proof of address step to the verification level.

Mind that the option of using geolocation for PoA is unavailable at this step.
QUESTIONNAIREType of verification where an applicant is required to fill in the pre-configured questionnaire.

Note that you cannot add this step to the verification level if no questionnaire is created in your system.
PHONE_VERIFICATIONType of verification where the applicant’s phone number is checked to verify whether it is blocklisted or not, and how much risk the specified phone number poses.
EMAIL_VERIFICATIONType of verification where the applicant's email address is checked to verify its credibility, whether it is blocklisted or not, and how much risk the specified email address poses.
PAYMENT_METHODSType of verification where an applicant should provide a document type to verify the payment methods used. Bank cards and crypto-wallets can be checked.

Mind that the Payment methods step is available only for the Applicant actions type of verification level.
E_KYCThis is a non-doc type of verification where an applicant is verified through government databases and official bank verification systems without documents.

For more information, see Non-Doc Verification.

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.

FieldTypeDescription
reviewResultObjectIncludes the details of the applicant verification steps review result. The object does not exist if a document was not provided.
countryStringAlpha-3 code of the country that issued the provided document (for example, DEU, GBR, ARG, and so on).
idDocTypeStringType of document that was uploaded by the applicant to pass the verification step. For example, PASSPORT, UTILITY_BILL, SELFIE, and so on.
imageIdsArray of stringsImage IDs that represent the uploaded document. The array may contain more than one image ID, for example, if two sides of the document were uploaded. If this is the case, the first ID would be the front side and others — back sides.

To obtain images with IDs, use the following method.
imageReviewResultsObjectThis is a map that includes a key element (imageId) and a tailored object (reviewResult) that explains the review results of the uploaded document image.
forbiddenBooleanIf the field returns true, it means the type or country of the document provided cannot be accepted and approved on our side in accordance with your settings.
partialCompletionBooleanIndicates if the minimum required number of images/documents is uploaded to pass the step.
  • true — minimum number of images is uploaded.
  • false — minimum number of images is not uploaded.
stepStatusesArray of objectsThe 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.
imageStatusesArray of objectsReturns the review results on each active image at the step: imageId, idDocSubType, reviewResult.

reviewResult attributes

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

FieldTypeDescription
reviewAnswerStringExplains the verification step review result.
  • GREEN — the verification step is approved.
  • RED — the verification step is rejected. See reviewRejectType for clarification.
moderationCommentStringA human-readable comment that explains the reasons for rejection, and that can be shown to the applicant.
clientCommentStringA human-readable comment that explains the reasons for rejection, and that must not be shown to the applicant.
reviewRejectTypeStringIndicates the type of rejection.
  • FINAL — final rejection in case of major violations. For example, some data of the document was modified, the document has been physically tampered with, and so on. If this is the case, you need to take a decision regarding the applicant on the basis of the rest data in the profile.
  • RETRY — temporary rejection in case of minor violations. For example, a screenshot was uploaded instead of a photo, a part of the document is invisible, and so on. The applicant is sent a resubmission request to upload a new document or resubmit correct data.
For more details, see Temporary rejection and Final rejection clarification.
rejectLabelsArray of stringsIncludes one or more reasons for rejection. The field is available if reviewAnswer returns RED.

For more details, see Temporary rejection and Final rejection clarification.

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.

FieldTypeDescription
moderationCommentStringA human-readable comment that explains the reasons for rejection, and that can be shown to the applicant.
clientCommentStringA human-readable comment that explains the reasons for rejection, and that must not be shown to the applicant.
reviewAnswerStringExplains the document review result.
  • GREEN — the document is approved.
  • RED — the document is rejected. See reviewRejectType for clarification.
rejectLabelsArray of stringsIncludes one or more reasons for rejection. The field is available if reviewAnswer returns RED.

For more details, see Temporary rejection and Final rejection clarification.
reviewRejectTypeStringIndicates the type of rejection.
  • FINAL — final rejection in case of major violations. For example, some data of the document was modified, the document has been physically tampered with, and so on. If this is the case, you need to take a decision regarding the applicant on the basis of the rest data in the profile.
  • RETRY — temporary rejection in case of minor violations. For example, a screenshot was uploaded instead of a photo, a part of the document is invisible, and so on. The applicant is sent a resubmission request to upload a new document or resubmit correct data.
For more details, see Temporary rejection d Final rejection clarification.
buttonIdsArray of stringsA list of button IDs that have been used for rejection.

A specific buttonId is automatically assigned to each rejection. For more details, see Temporary rejection d Final rejection clarification.

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.

FieldTypeDescription
nameStringName of the company beneficiary group (company, ubos, shareholders, representatives, directors).
reviewStatusStringCurrent status of the step.
reviewResultObjectIncludes the details of the step review result. The object does not exist if a document was not provided.
imagesArray of objectsIncludes information about each document image provided, and the review result regarding the specified image.

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.

FieldTypeDescription
imageIdStringUnique identifier of the document image.
idDocTypeStringType of document that was uploaded to pass the verification step. Usually, it is COMPANY_DOC for a company applicant.
idDocSubTypeStringSubtype of the COMPANY_DOC provided (for example, INCORPORATION_CERT, INCORPORATION_ARTICLES, SHAREHOLDER_REGISTRY, and so on).
reviewResultObjectIncludes the details of the image review result. The object does not exist if a document image was not provided.

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"]
      }
    }
  }
}
Language
Authorization
Header
Click Try It! to start a request and see the response here!