--- updatedAt: 2026-09-29T08:00:22.000Z agentTools: projectIndex: https://docs.sumsub.com/llms.txt --- # Get ID verification results # Overview Use this method to retrieve information extracted from the applicant’s documents. The method aggregates data from all documents and ignores verification levels. ### Note This method does not apply to company document verification results. Company documents are supported via the [AllDocs](https://docs.sumsub.com/sumsub/docs/alldocs-verification) model. See [this article](https://docs.sumsub.com/sumsub/reference/get-ocr-fields-from-company-documents) for details. ## Required permissions To use this method, your [app token](https://docs.sumsub.com/sumsub/docs/app-tokens) must have the following [permissions](https://docs.sumsub.com/sumsub/docs/user-roles#permissions): * **View applicants** * **View applicant's personal data** # Optional settings Use optional query parameters to modify the response behavior for specific scenarios. ## `forApprovedImages` To retrieve information extracted **only from approved documents**, set the `forApprovedImages` parameter to `true`. In this mode, the method operates exclusively for approved applicants and returns data only from approved documents. For example, when an approved applicant has a mix of Pending and approved documents, enabling `forApprovedImages=true` results in the response containing data solely from the approved documents. ### Attention When using `forApprovedImages=true`, mind the following: - If the applicant is in the **Rejected** or **Resubmission requested** [status](https://docs.sumsub.com/sumsub/docs/applicant-statuses), the method will return an error. - If all documents are in the **Pending** status, the method will return an empty array: `"idDocs": []`. For certain results, we recommend sending the request when the applicant gets the **Approved** status. ## withDeletedImages To retrieve [deactivated document images](https://docs.sumsub.com/sumsub/reference/marking-image-as-inactive), set the `withDeletedImages` parameter to `true`. By default, images marked as deleted (deactivated) are excluded from the response, and only the latest image IDs for each `(idDocType, country)` pair are returned. To retrieve image IDs for all historical submissions, including deactivated ones, pass `withDeletedImages=true`. In this mode, all matching image IDs are returned in descending `addedDate` order, with no latest-only limit. ### Note Recognition results are still stored per `(idDocType, country)` pair. Older deleted images for the same pair share the recognition entry of the most recent image. # Request examples ```curl forApprovedImages=true // This request returns data only from approved applicant documents. curl -X GET \ 'https://api.sumsub.com/resources/applicants/67b3659550a9ed51c7770000/info/idDocs?forApprovedImages=true' \ -H 'X-App-Token: ' \ -H 'X-App-Access-Sig: ' \ -H 'X-App-Access-Ts: ' ``` ```curl forApprovedImages omitted // This request returns data from all applicant documents, independent of their approval status. curl -X GET \ 'https://api.sumsub.com/resources/applicants/67b3659550a9ed51c7770000/info/idDocs' \ -H 'X-App-Token: ' \ -H 'X-App-Access-Sig: ' \ -H 'X-App-Access-Ts: ' ``` ```curl withDeletedImages=true // This request returns data including deactivated images. curl -X GET \ 'https://api.sumsub.com/resources/applicants/67b3659550a9ed51c7770000/info/idDocs?withDeletedImages=true' \ -H 'X-App-Token: ' \ -H 'X-App-Access-Sig: ' \ -H 'X-App-Access-Ts: ' ``` # Response explained The response is a JSON object containing information extracted from the applicant's documents. Its structure and content match the format of the [`idDocs` array](https://docs.sumsub.com/sumsub/reference/get-applicant-data#iddocs-element-fields) returned by the **Get applicant data** method. ## `idDocs` element fields The table below describes the fields that represent data extracted from the applicant’s documents. | Field | Type | Description | | :----------------------- | :--------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `idDocType` | String | Type of document that is specified in the level to be provided for verification. For example, `PASSPORT`, `UTILITY_BILL`, `VEHICLE_REGISTRATION_CERTIFICATE`, and so on.
See the lists of [supported document types](https://docs.sumsub.com/sumsub/reference/add-verification-documents#supported-document-types) . | | `ocrDocType` | String |

Specifies the document subtype as a full type identifier (for example, cyp.rp.type1, nga.nins.type2, and so on). The identifier typically follows this structure:

  1. Alpha-3 country code (deu, gbr, arg, and so on).
  2. Document type, (for example, ID card id, driving license drvlic, residence permit rp, and so on).
  3. Subtype category (for example, type1, type2, type3) – often used to determine different varieties of the document type.

Additional variations may be the following:

  • State-level identifiers for supported countries (for example, usa.drvlic.al.type2, can.drvlic.on.type1).
  • Unique document identifiers when supported (for example, sgp.work.type1, gbr.drvlic.provisional.type1, ind.aadhaar.type1).

If the subtype cannot be determined, the field is returned empty.

⚠️ Note: This field is intended for analytical purposes only. Do not rely on its value for critical business logic, as it may not always be determinable with full accuracy.

| | `country` | String | [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code (for example, `DEU`, `GBR`, `ARG`) of the country where the document was issued. | | `firstName` | String | Applicant first name in the original language as it is in the document. There is no length limit for this field. | | `firstNameEn` | String | Automatic transliteration of the applicant first name into Latin characters. There is no length limit for this field. | | `middleName` | String | Applicant middle name in the original language as it is in the document. There is no length limit for this field. | | `middleNameEn` | String | Automatic transliteration of the applicant middle name into Latin characters. There is no length limit for this field. | | `lastName` | String | Applicant last name in the original language as it is in the document. There is no length limit for this field. | | `lastNameEn` | String | Automatic transliteration of the applicant last name into Latin characters. There is no length limit for this field. | | `aliasName` | String | Alternative first/last name. | | `title` | String | A word or abbreviation placed before a person's name to indicate their profession, social rank, academic degree, or form of address (`Dr`, `Mr`, `Ms`, `Prof`, and so on). | | `issuedDate` | Date | Date when the identity document was issued (format `YYYY-MM-DD`). | | `issueAuthority` | String | Official name of the authority that issued the document. | | `issueAuthorityCode` | String | Code of the Issuing Authority that is in charge of issuing the uploaded document. | | `termless` | Boolean | Indicates whether the document is marked as valid indefinitely (`true`) or not (`false`); see the `validUntil` field for the expiration date.
⚠️ For now, `"validUntil": "2099-01-01"` will be returned for documents marked as indefinite (`"termless": true`). This is a temporary behavior and will be discontinued in the coming months. | | `validUntil` | Date | Date when the document validity expires. | | `extendedValidUntil` | Date | Additional date when the document validity expires, in case the document validity has been extended (format: `YYYY-MM-DD`, for example, `2029-05-20`).
⚠️ Returned only if custom rules are applied to extend `validUntil`, or if country-specific document prolongation rules are in effect. | | `dlCategoryBIssuedDate` | Date | Date when driving-licence category B was issued (format `YYYY-MM-DD`); `null` when not present. | | `dlCategoryBValidUntil` | Date | Date when driving-licence category B expires (format `YYYY-MM-DD`); `null` when not present. | | `dlCategoryAmIssuedDate` | Date | Date when driving-licence category AM was issued (format `YYYY-MM-DD`); `null` when not present. | | `number` | String | Unique registration number of the document. | | `additionalNumber` | String | Usually, it is a sort of personal number. For example, DNI in Spain, CRP in Brazil, or ARC in Cyprus. | | `serialNumber` | String | ID document serial number (up to 64 characters). For example, the INE identifier on Mexican ID cards. | | `dob` | Date | Applicant date of birth ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), in the format `yyyy-MM-dd` (for example, `2001-09-25`) as it is specified in the document. | | `maritalStatus` | String | Person’s current legal marital status. | | `address` | [Object](#address-attributes-and-addresses-element-fields) | Includes the applicant address details. | | `ethnicity` | String | Indicates the applicant's ethnic background. Presented as a custom value. | | `mrzLine1` | String | A line of MRZ (machine-readable zone) from the document. Additional lines, such as `mrzLine2` and `mrzLine3`, may also be present if available. The number indicates the line position in sequential order. | | `withNfc` | Boolean | Indicates whether the document contains NFC data (`true`), or not (`false`). | | `nfcInfo` | [Object](#nfcinfo-attributes) | Includes the data extracted from the NFC chip of an identity document. | | `imageIds` | Array of integers | Contains identifiers of ID document images.
⚠️ When `forApprovedImages` is set to `true`, only approved images are returned. | ## `address` attributes The following table explains the `address` attributes that represent the applicant address details. | Field | Type | Description | | :----------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `buildingName` | String | Building name. | | `flatNumber` | String | Flat or apartment number. | | `subStreet` | String | Additional information related to the street. This could be a house number or any other details. | | `subStreetEn` | String | Automatic transliteration of the additional information related to the street into Latin characters. | | `street` | String | Street name. | | `streetEn` | String | Automatic transliteration of the street name into Latin characters. | | `state` | String | State, region, district, county or another territorial entity inside a country. | | `stateEn` | String | Automatic transliteration of the territorial entity into Latin characters. | | `stateCode` | String | Applicant state code based on the address. A list of state codes is based on the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format (for example, `TR-34`, `AD-07`). | | `buildingNumber` | String | Building number. | | `town` | String | City, town, or another settlement. | | `townEn` | String | Automatic transliteration of the settlement into Latin characters. | | `postCode` | String | Address postal code. | | `country` | String | [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code (for example, `DEU`, `GBR`, `ARG`). | | `formattedAddress` | String | Address in a human readable format. For example, `Design Offices, Philipsbornstraße 2, 30165 Hannover, Germany`. | | `source` | String | Address data source. This information can be obtained from [Applicant data](https://docs.sumsub.com/sumsub/docs/verification-steps), [Proof of Address](https://docs.sumsub.com/sumsub/docs/document-based-poa), and [Geo as PoA](https://docs.sumsub.com/sumsub/docs/enable-poa-through-geolocation#how-poa-through-geolocation-without-documents-works). | ## `nfcInfo` attributes The following table explains the `nfcInfo` attributes representing the data extracted from the NFC chip of an identity document. | Field | Type | Description | | :-------- | :------ | :----------------------------------------------------------------------- | | `fullMrz` | String | Contains the full Machine-Readable Zone (MRZ) data from the ID document. | | `imageId` | Integer | Unique identifier of the image that represents the uploaded document. | # Response examples If the request is successfully sent and processed, you will get a response like the one below. ```json { "idDocs": [ { "idDocType": "ID_CARD", "country": "DEU", "firstName": "CHRISTIAN", "firstNameEn": "CHRISTIAN", "lastName": "SMITH", "lastNameEn": "SMITH", "aliasName": "BROOKS", "validUntil": "2028-09-04", "number": "LGXX359T8", "dob": "1989-07-16", "ocrDocType": "cyp.id.type1", "mrzLine1": "IDD<
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](https://cockpit.sumsub.com/checkus/#/applicants/individual?limit=10&page=0).

If the `applicantId` is unknown to you, use the [Get applicant data (externalUserId)](https://docs.sumsub.com/sumsub/reference/get-applicant-data-via-externaluserid) method to fetch it.", "schema": { "type": "string" }, "required": true }, { "name": "forApprovedImages", "in": "query", "description": "Set to `true` to return data only from approved documents.

If omitted or set to `false`, the method returns data recognized from all documents of the approved applicant, not just the approved ones.", "schema": { "type": "boolean" } }, { "in": "query", "name": "withDeletedImages", "schema": { "type": "boolean", "default": "" }, "description": "When `true`, includes deactivated (deleted) document images in the response and returns all matching image IDs for each `(idDocType, country)` pair, sorted by `addedDate` in descending order.

If omitted or set to `false`, deactivated (deleted) images are excluded from the response." } ], "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```