Overview

Use this method to get the information about the documents or separate verification step results. The method works both for individuals and company applicants.

📘
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.

Object	Description
`COMPANY`	This object is only dedicated for company applicants (KYB 1.0). It represents the Company required step for verification. The existence of certain included fields depends on the step configuration in the associated verification level. ⚠️ Mind that for KYB 2.0, there are three objects instead: `COMPANY_DATA`, `COMPANY_DOCUMENTS`, `COMPANY_BENEFICIARIES` (see response examples below).
`APPLICANT_DATA`	Type 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.
`IDENTITY`	ID 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.
`IDENTITY2`	Same as IDENTITY. Used in case you decide to add a separate required step to the verification level for each document or some of them.
`IDENTITY3`	Same as IDENTITY. Used in case you decide to add a separate required step to the verification level for each document or some of them.
`IDENTITY4`	Same as IDENTITY. Used in case you decide to add a separate required step to the verification level for each document or some of them.
`SELFIE`	Type of verification where an applicant needs to complete either of the following Selfie options: Go through the advanced liveness check. Provide a short video fragment. Submit a selfie with a document. Create and submit a web camera photo. If you need an applicant to pass two steps of those above, add the 2nd selfie step to the verification level.
`SELFIE2`	Same as SELFIE. Used in case you need to add another Selfie option to the verification level.
`PROOF_OF_RESIDENCE`	Address 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_RESIDENCE2`	Similar 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.
`QUESTIONNAIRE`	Type 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_VERIFICATION`	Type 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_VERIFICATION`	Type 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_METHODS`	Type 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_KYC`	This 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.

Field	Type	Description
`reviewResult`	Object	Includes the details of the applicant verification steps review result. The object does not exist if a document was not provided.
`country`	String	Alpha-3 code of the country that issued the provided document (for example, `DEU`, `GBR`, `ARG`, and so on).
`idDocType`	String	Type of document that was uploaded by the applicant to pass the verification step. For example, `PASSPORT`, `UTILITY_BILL`, `SELFIE`, and so on.
`imageIds`	Array of strings	Image 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.
`imageReviewResults`	Object	This is a map that includes a key element (imageId) and a tailored object (reviewResult) that explains the review results of the uploaded document image.
`forbidden`	Boolean	If 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.
`partialCompletion`	Boolean	Indicates 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.
`stepStatuses`	Array of objects	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.
`imageStatuses`	Array of objects	Returns 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.

Field	Type	Description
`reviewAnswer`	String	Explains the verification step review result. `GREEN` — the verification step is approved. `RED` — the verification step is rejected. See `reviewRejectType` for clarification.
`moderationComment`	String	A human-readable comment that explains the reasons for rejection, and that can be shown to the applicant.
`clientComment`	String	A human-readable comment that explains the reasons for rejection, and that must not be shown to the applicant.
`reviewRejectType`	String	Indicates 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.

`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.

Field	Type	Description
`moderationComment`	String	A human-readable comment that explains the reasons for rejection, and that can be shown to the applicant.
`clientComment`	String	A human-readable comment that explains the reasons for rejection, and that must not be shown to the applicant.
`reviewAnswer`	String	Explains the document review result. `GREEN` — the document is approved. `RED` — the document is rejected. See `reviewRejectType` for clarification.
`rejectLabels`	Array of strings	Includes one or more reasons for rejection. The field is available if `reviewAnswer` returns `RED`. For more details, see Temporary rejection and Final rejection clarification.
`reviewRejectType`	String	Indicates 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.
`buttonIds`	Array of strings	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.

Field	Type	Description
`name`	String	Name of the company beneficiary group (`company`, `ubos`, `shareholders`, `representatives`, `directors`).
`reviewStatus`	String	Current status of the step.
`reviewResult`	Object	Includes the details of the step review result. The object does not exist if a document was not provided.
`images`	Array of objects	Includes 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.

Field	Type	Description
`imageId`	String	Unique identifier of the document image.
`idDocType`	String	Type of document that was uploaded to pass the verification step. Usually, it is `COMPANY_DOC` for a company applicant.
`idDocSubType`	String	Subtype of the `COMPANY_DOC` provided (for example, `INCORPORATION_CERT`, `INCORPORATION_ARTICLES`, `SHAREHOLDER_REGISTRY`, and so on).
`reviewResult`	Object	Includes 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"]
      }
    }
  }
}

{
    "COMPANY_DATA": {
        "reviewResult": {
            "moderationComment": "Please provide the following additional corporate documents:\n - a company's register of directors / officers\n - a recent excerpt from the company register\n\nAccording to the provided documents, the data in the profile is incorrect. Please make amendments to the declared information exactly as they are written in your corporate document: the company's registration number is incorrect.",
            "reviewAnswer": "RED",
            "reviewRejectType": "RETRY"
        },
        "country": null,
        "idDocType": null,
        "imageIds": [],
        "imageReviewResults": null,
        "forbidden": null,
        "partialCompletion": null,
        "stepStatuses": null
    },
    "COMPANY_DOCUMENTS": {
        "reviewResult": {
            "moderationComment": "Please provide the following additional corporate documents:\n - a company's register of directors / officers\n - a recent excerpt from the company register\n\nAccording to the provided documents, the data in the profile is incorrect. Please make amendments to the declared information exactly as they are written in your corporate document: the company's registration number is incorrect.",
            "reviewAnswer": "RED",
            "reviewRejectType": "RETRY"
        },
        "country": null,
        "idDocType": "COMPANY_DOC",
        "imageIds": [
            123456789
        ],
        "imageReviewResults": {
            "123456789": {
                "reviewAnswer": "GREEN"
            }
        },
        "forbidden": null,
        "partialCompletion": null,
        "stepStatuses": null,
        "imageStatuses": [
            {
                "imageId": 123456789,
                "idDocSubType": "INFORMATION_STATEMENT",
                "reviewResult": {
                    "reviewAnswer": "GREEN"
                }
            }
        ]
    },
    "COMPANY_BENEFICIARIES": {
        "reviewResult": {
            "reviewAnswer": "GREEN"
        },
        "country": null,
        "idDocType": null,
        "imageIds": null,
        "imageReviewResults": null,
        "forbidden": null,
        "partialCompletion": null,
        "stepStatuses": [
            {
                "name": "ubos",
                "reviewStatus": "completed",
                "reviewResult": null,
                "images": null
            },
            {
                "name": "shareholders",
                "reviewStatus": "completed",
                "reviewResult": null,
                "images": null
            },
            {
                "name": "directors",
                "reviewStatus": "completed",
                "reviewResult": null,
                "images": null
            }
        ]
    }
}

Get status of verification steps

Table of contents

Overview

📘
Note

Example request

Response explained

📘
Note

Root variables

Root variable attributes and element fields

📘
Note

`reviewResult` attributes

`imageReviewResults` attributes

`stepStatuses` element fields

`images` element fields

Response examples

Table of contents

Overview

📘Note

Example request

Response explained

📘Note

Root variables

Root variable attributes and element fields

📘Note

reviewResult attributes

imageReviewResults attributes

stepStatuses element fields

images element fields

Response examples

📘
Note

📘
Note

📘
Note

`reviewResult` attributes

`imageReviewResults` attributes

`stepStatuses` element fields

`images` element fields