API Reference
Product VideosAPI ReferenceChangelogFAQDashboard

Get information about document images

get
https://api.sumsub.com/resources/applicants//metadata/resources
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Overview

Use this method to get the information about the uploaded images from the specific applicant profile.

Required permissions

To use this method, your app token must have the following permissions:

  • View applicants
  • View applicant's personal data

Request example

curl -X GET \
     'https://api.sumsub.com/applicants/66bb9bd13158c00000223355/metadata/resources' \
     -H 'X-App-Token: <your-app-token>' \
     -H 'X-App-Access-Sig: <your-signature>' \
     -H 'X-App-Access-Ts: <unix-timestamp>'

Response explained

The response is a JSON file that contains the structured data about all uploaded images in the applicant profile. See the response example below.

FieldTypeDescription
itemsArray of objectsEach object represents the data for an individual image.
totalItemsIntegerTotal number of all uploaded images.

items element fields

The following table explains the primary data elements of an individual image.

FieldTypeDescription
idStringUnique image identifier.
previewIdStringIdentifier of the image thumbnail.
addedDateDateDate and time when the image was uploaded.
fileMetadataObjectIncludes such file metadata like name, type, size, and so on.
idDocDefObjectAdditional information about the document.
reviewResultObjectContains extra details of the image check result.
attemptIdStringUnique identifier of the current image check attempt.
Applicants may initiate several attempts to get verified if, for example, they failed once or changed/added the documents, or you could change the verification level to start another check.
sourceStringSpecifies the source from which the image was obtained and may be any of the following:
  • liveness — taken from the liveness check.
  • videoidentSnapshot — obtained during video identification.
  • docapture — captured during one of the verification steps.
  • nfc — extracted during NFC-based ID verification.
  • externaldb — retrieved from an external database.
  • fileupload — ready-made image file was uploaded into the system.
deactivatedBooleanIndicates the image status.

fileMetadata attributes

The follwoing table explains the attributes included in the fileMetadata object.

FieldTypeDescription
fileNameStringImage file name.
fileTypeStringImage file type.
See our FAQ for a full list of mime-types and acceptable file formats.
fileSizeIntegerImage file size (in bytes).
resolutionObjectIncludes the actual width and height of the image in pixels.

idDocDef attributes

The following table explains the idDocDef attributes representing the additional information about the document.

FieldTypeDescription
countryStringAlpha-3 code (for example, DEU, GBR, ARG, and so on) of the country where the document was issued.
idDocTypeStringType of document that is specified in the level to be provided for verification. For example, PASSPORT, SELFIE, VIDEO_SELFIE, PAYMENT_METHOD and so on.
See the list of supported document types for details.
idDocSubTypeStringFRONT_SIDE, BACK_SIDE or null.

reviewResult attributes

The following table explains the reviewResult attributes representing details of the image check result.

FieldTypeDescription
moderationCommentStringHuman-readable comment that explains the reasons for rejection, and that can be shown to the applicant.
clientCommentStringHuman-readable comment that explains the reasons for rejection, and that must not be shown to the applicant.
reviewAnswerStringExplains the image review result:
  • GREEN — the image is approved.
  • RED — the image 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 Resubmission requested and Rejected clarification.
reviewRejectTypeStringIndicates the type of rejection:
  • FINAL — Rejected status in case of major violations. For example, the document data was modified, the document has been tampered with, and so on. If this is the case, you need to make a decision regarding the applicant on the basis of the rest data in the profile.
  • RETRY — Resubmission requested status in case of minor violations. For example, a screenshot was uploaded instead of a photo, part of the document is not visible, and so on. The applicant is sent a resubmission request to upload a new image.

For more details, see Resubmission requested and Rejected clarification.
buttonIdsArray of stringsList of button IDs that have been used for rejection.
A specific buttonId is automatically assigned to each rejection. For more details, see Resubmission requested and Rejected clarification.

Response example

{
  "items": [
    {
      "id": "393800000",
      "previewId": "1264200000",
      "addedDate": "2024-10-01 16:31:51",
      "fileMetadata": {
        "fileName": "docapture_manual_front_side.jpg",
        "fileType": "jpeg",
        "fileSize": 255588,
        "resolution": {
          "width": 1280,
          "height": 720
        }
      },
      "idDocDef": {
        "country": "PRT",
        "idDocType": "DRIVERS",
        "idDocSubType": "FRONT_SIDE"
      },
      "reviewResult": {
        "moderationComment": "The required fields of the document are not readable. Please upload a clear photo or another suitable document to continue your verification . Make sure that all corners of the document are visible.",
        "clientComment": "Required fields of the document are not readable or visible. A new photo has been requested.",
        "reviewAnswer": "RED",
        "rejectLabels": [
          "UNSATISFACTORY_PHOTOS"
        ],
        "reviewRejectType": "RETRY",
        "buttonIds": [
          "badPhoto_dataNotVisible"
        ]
      },
      "attemptId": "eaHEj",
      "source": "docapture"
    },
    {
      "id": "931822222",
      "previewId": "1023422222",
      "addedDate": "2024-10-01 16:31:51",
      "fileMetadata": {
        "fileName": "docapture_manual_back_side.jpg",
        "fileType": "jpeg",
        "fileSize": 209354,
        "resolution": {
          "width": 1280,
          "height": 720
        }
      },
      "idDocDef": {
        "country": "PRT",
        "idDocType": "DRIVERS",
        "idDocSubType": "BACK_SIDE"
      },
      "reviewResult": {
        "moderationComment": "The required fields of the document are not readable. Please upload a clear photo or another suitable document to continue your verification . Make sure that all corners of the document are visible.",
        "clientComment": "Required fields of the document are not readable or visible. A new photo has been requested.",
        "reviewAnswer": "RED",
        "rejectLabels": [
          "UNSATISFACTORY_PHOTOS"
        ],
        "reviewRejectType": "RETRY",
        "buttonIds": [
          "badPhoto_dataNotVisible"
        ]
      },
      "attemptId": "eaHEj",
      "source": "docapture"
    },
    {
      "id": "512855555",
      "previewId": "1557055555",
      "addedDate": "2022-11-02 06:26:43",
      "fileMetadata": {
        "fileName": "file_name.jpg",
        "fileType": "jpeg",
        "fileSize": 60770,
        "resolution": {
          "width": 736,
          "height": 975
        }
      },
      "idDocDef": {
        "country": "PRT",
        "idDocType": "UTILITY_BILL"
      },
      "reviewResult": {
        "moderationComment": "The required fields of the document are not readable. Please upload a clear photo or another suitable document to continue your verification . Make sure that all corners of the document are visible.",
        "clientComment": "Required fields of the document are not readable or visible. A new photo has been requested.",
        "reviewAnswer": "RED",
        "rejectLabels": [
          "UNSATISFACTORY_PHOTOS"
        ],
        "reviewRejectType": "RETRY",
        "buttonIds": [
          "badPhoto_dataNotVisible"
        ]
      },
      "attemptId": "qwSTr",
      "source": "docapture",      
      "deactivated": true
    },
    {
      "id": "1380922222",
      "previewId": "340033333",
      "addedDate": "2022-11-02 06:26:46",
      "fileMetadata": {
        "fileName": "another-file-name.png",
        "fileType": "png",
        "fileSize": 293015,
        "resolution": {
          "width": 505,
          "height": 660
        }
      },
      "idDocDef": {
        "country": "PRT",
        "idDocType": "PASSPORT"
      },
      "reviewResult": {
        "reviewAnswer": "GREEN"
      },
      "attemptId": "thUIp",
      "source": "docapture",      
      "deactivated": false
    }    
  ],
  "totalItems": 4
}
Path Params
string
required

Unique applicant identifier in the Sumsub system.

This identifier is a random combination of 24 digits and lowercase Latin characters. It is automatically generated when the applicant is created on the Sumsub side, and can be found in the Dashboard.

If the applicantId is unknown to you, use the Get applicant data (externalUserId) method to fetch it.

Updated 1 day ago

Did this page help you?
Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here!

Updated 1 day ago

Did this page help you?