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 theIDENTITY
step if it exists, soPROOF_OF_RESIDENCE
may not have been checked untilIDENTITY
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 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_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:
|
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.
|
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
reviewResult
attributesThe 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.
|
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.
|
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. |
imageReviewResults
attributes
imageReviewResults
attributesThe 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.
|
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.
|
buttonIds | Array of strings | A 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
stepStatuses
element fieldsThe 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
images
element fieldsThe 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"]
}
}
}
}