Captured ID

Defined in package com.scandit.datacapture.id.data

CapturedId

class CapturedId

Added in version 6.5.0

This class represents the result of a document scan. It provides commonly present information, such as the holder’s name and date of birth, directly accessible at the top level. Additional document-specific details can be accessed through properties representing different zones of the document, such as the barcode, machine-readable zone (MRZ), and visual inspection zone (VIZ).

Note that not all properties are relevant to every document type. If a property is not applicable or the corresponding data could not be read, it will be set to null.

fromJson(jsonData)

static @NonNull CapturedId fromJson(@NonNull String jsonData)

Added in version 6.12.0

Creates a captured id from the passed JSON string.

firstName

@Nullable String getFirstName()

Added in version 6.5.0

The first name of the document holder. Separated by spaces if more than one name is present. Characters can be all uppercase for document types which don’t capitalize names (for example names encoded in ICAO Machine Readable Zones).

lastName

@Nullable String getLastName()

Added in version 6.5.0

The last name of the document holder. Separated by spaces if more than one name is present. Characters can be all uppercase for document types which don’t capitalize names (for example names encoded in ICAO Machine Readable Zones).

fullName

@Nullable String getFullName()

Added in version 6.5.0

The full name of the document holder. Characters can be all uppercase for document types which don’t capitalize names (for example names encoded in ICAO Machine Readable Zones).

sexType

Sex getSexType()

Added in version 7.1.0

The sex of the document holder.

sex

@Nullable String getSex()

Added in version 6.5.0

The description of the document holder’s sex.

dateOfBirth

@Nullable DateResult getDateOfBirth()

Added in version 6.5.0

The date of birth of the document holder. If the document doesn’t provide two first digits of the year then the date of birth is always set to be earlier than or equal to the scan date. For example if the year of scanning is 2021 and the document returns that the year of birth is 14 then the returned year is set to 2014. However if the document returns that the year of birth is 24 then the returned year is set to 1924.

age

@Nullable Integer getAge()

Added in version 6.16.0

The age of the document holder. Calculated as the difference in full years between the birth date and the current local date. If null is returned it means that the full birth date is not available. The returned value depends on the device date. The same document may result in different values for devices with different dates (e.g. in different time zones, or with a date set manually by the user).

nationality

@Nullable String getNationality()

Added in version 6.5.0

The nationality of the document holder as raw OCR text from the document. The format and language vary by jurisdiction (e.g., “DEUTSCH”, “AMERICAN”, “POLSKA”, “DEU”).

For a standardized ISO 3166-1 alpha-3 country code representation, use nationalityISO.

nationalityISO

@Nullable String getNationalityISO()

Added in version 8.1.0

The holder’s nationality as an ISO 3166-1 alpha-3 country code (e.g., “DEU”, “USA”, “POL”).

Returns null if the nationality cannot be determined or is ambiguous.

address

@Nullable String getAddress()

Added in version 6.5.0

The address of the document holder.

usRealIdStatus

UsRealIdStatus getUsRealIdStatus()

Added in version 6.28.0

Indicates whether the document is REAL ID compliant.

document

@Nullable IdCaptureDocument getDocument()

Added in version 7.0.0

The document type.

issuingCountryIso

@Nullable String getIssuingCountryIso()

Added in version 6.5.0

The ISO (Alpha-3 code) abbreviation of the issuing country of the document.

issuingCountry

IdCaptureRegion getIssuingCountry()

Added in version 7.0.0

Issuing country of the document.

documentNumber

@Nullable String getDocumentNumber()

Added in version 6.5.0

The document number.

If IdCaptureSettings.anonymizationMode is enabled for the field results, the returned value might be null for certain documents.

documentAdditionalNumber

@Nullable String getDocumentAdditionalNumber()

Added in version 6.19.0

If IdCaptureSettings.anonymizationMode is enabled for the field results, the returned value might be null for certain documents.

dateOfExpiry

@Nullable DateResult getDateOfExpiry()

Added in version 6.5.0

The date of expiry of the document. Returning null with isExpired = false indicates that the document never expires.

isExpired

@Nullable Boolean isExpired()

Added in version 6.16.0

Whether this document is expired. Calculated by comparing the document’s expiration date with the current local date. true if the document is expired and false when either not expired, or never expires. null is returned if the value of this property could not be determined - for example if the date of expiry is not present, or if the date of expiry couldn’t be captured. Please note that the system time is used for computation of this field so users of the device are capable of changing the result of the field by changing the system time.

dateOfIssue

@Nullable DateResult getDateOfIssue()

Added in version 6.5.0

The date of issue of the document. Please note that some documents may specify the exact date of issue, while other the month and the year only.

barcode

@Nullable BarcodeResult getBarcode()

Added in version 7.0.0

The additional information extracted from a barcode on a document.

mobileDocument

@Nullable MobileDocumentResult getMobileDocument()

Added in version 7.5.0

The additional information extracted from a mobile identity document.

mobileDocumentOcr

@Nullable MobileDocumentOcrResult getMobileDocumentOcr()

Added in version 8.0.0

The additional information extracted from a mobile document using optical character recognition (OCR). This property is populated when scanning mobile driver licenses with OCR-based capture enabled (for example, Australian mobile driver licenses when the mobile scanner is enabled).

mrz

@Nullable MrzResult getMrz()

Added in version 6.6.0

The additional information extracted from the Machine Readable Zone (MRZ) of a Machine Readable Travel Document (MRTD).

viz

@Nullable VizResult getViz()

Added in version 6.6.0

The additional information extracted from a documents or its part intended to be read by humans (for example Visual Inspection Zone (VIZ) of a Machine-Readable Travel Document (MRTD)).

nfc

@Nullable NfcResult getNfc()
void setNfc(@Nullable NfcResult value)

Added in version 7.3.0

The additional information extracted from the NFC chip present on the document.

images

@NonNull IdImages getImages()

Added in version 7.0.0

The images extracted from a document.

isIdCard()

boolean isIdCard()

Added in version 7.0.0

Indicates whether the document is of type IdCard.

isDriverLicense()

boolean isDriverLicense()

Added in version 7.0.0

Indicates whether the document is of type DriverLicense.

isPassport()

boolean isPassport()

Added in version 7.0.0

Indicates whether the document is of type Passport.

isCitizenPassport

boolean isCitizenPassport()

Added in version 8.0.0

Indicates whether the passport was issued to a citizen of the issuing country. Returns false for travel documents such as refugee, stateless, or alien passports, and for any passports issued by organizations rather than states.

isVisaIcao()

boolean isVisaIcao()

Added in version 7.0.0

Indicates whether the document is of type VisaIcao.

isResidencePermit()

boolean isResidencePermit()

Added in version 7.0.0

Indicates whether the document is of type ResidencePermit.

isHealthInsuranceCard()

boolean isHealthInsuranceCard()

Added in version 7.0.0

Indicates whether the document is of type HealthInsuranceCard.

isRegionSpecific(subtype)

boolean isRegionSpecific(RegionSpecificSubtype subtype)

Added in version 7.0.0

Indicates whether the document is of type RegionSpecificSubtype.

verificationResult

@NonNull VerificationResult getVerificationResult()

Added in version 7.1.0

Results of verifications automatically performed when IdCaptureSettings.rejectInconsistentData or IdCaptureSettings.rejectForgedAamvaBarcodes are enabled.

isAnonymized(field)

boolean isAnonymized(IdFieldType field)

Added in version 8.0.0

Checks whether the specified field has been anonymized.

Returns true if the field was present in the captured document and was anonymized according to the IdCaptureSettings.anonymizationMode setting, false otherwise.

A field that is not present in the document always returns false, even if anonymization is enabled for that field type.

This method is useful for determining which fields have been redacted, particularly when using IdCaptureSettings.anonymizationMode set to IdAnonymizationMode.FIELDS_ONLY or IdAnonymizationMode.FIELDS_AND_IMAGES.

Param IdFieldType field: The field type to check for anonymization.

anonymizedFields

@NonNull Set<IdFieldType> getAnonymizedFields()

Added in version 8.0.0

Returns all fields that have been anonymized in this captured document.

Only fields that were actually present in the captured document and were subsequently anonymized are included.

rejectionDiagnosticJSON

@NonNull String getRejectionDiagnosticJSON()

Added in version 8.0.0

Attention

This property is experimental and its format is subject to change in future releases. We recommend using it for debugging and diagnostics purposes only, and not relying on its structure in production code.

Returns diagnostic information about why a document was rejected, serialized as a JSON string.

This property is only populated when a document is rejected with RejectionReason.TIMEOUT and contains detailed information about document quality issues that prevented successful capture, such as detected blur, glare, occlusion, or lighting problems.

For all other rejection reasons, this property returns an empty string.

JSON Structure

The diagnostic JSON contains aggregated information from frames captured during the timeout period. It includes diagnostics from one or more zones (VIZ, MRZ, or Barcode). For zones that were expected but not captured, the JSON includes information about what issues prevented successful capture.

Example 1 - All zones detected:

{
  "rejectionReason": "timeout",
  "side": "front",
  "zones": [
    {
      "captured": false,
      "expectation": "optional",
      "issues": [
        {
          "category": "blur"
        }
      ],
      "localized": true,
      "zone": "viz"
    },
    {
      "captured": false,
      "expectation": "optional",
      "localized": true,
      "zone": "mrz"
    },
    {
      "captured": false,
      "expectation": "optional",
      "localized": true,
      "zone": "barcode"
    }
  ]
}

Example 2 - Partial success (one zone captured, one failed):

{
  "rejectionReason": "timeout",
  "side": "back",
  "zones": [
    {
      "captured": false,
      "expectation": "required",
      "issues": [
        {
          "category": "mandatoryFieldsMissing",
          "issue": ["issuingAuthority"]
        }
      ],
      "localized": true,
      "zone": "viz"
    },
    {
      "captured": true,
      "localized": true,
      "zone": "mrz"
    }
  ]
}

Field Descriptions

side: The side of the document being scanned ("front" or "back").
rejectionReason: The reason for rejection, always "timeout" for this diagnostic JSON.
zones: Array of zone-level diagnostics. Each zone represents a different detector (VIZ, MRZ, or Barcode).
- zone: The zone identifier ("viz", "mrz", or "barcode").
- captured: Boolean indicating whether this zone was successfully captured (true) or not (false).
- localized: Boolean indicating whether this zone was detected during the timeout period.
- expectation: Indicates whether this zone is "required" or "optional". Only present for zones that were not successfully captured.
- issues: Array of diagnostic issues detected for this zone. Each issue is an object with a category field and optionally an issue field:
  - Simple issues (no additional details):
    
    {"category": "blur"}: Blur was detected in the zone.
    
    {"category": "glare"}: Glare was detected in the zone.
    
    {"category": "occlusion"}: Occlusion (covering/blocking) was detected in the zone.
  - Lighting issues (with issue field):
    
    {"category": "lighting", "issue": "tooDark"}: Document is underexposed.
    
    {"category": "lighting", "issue": "tooBright"}: Document is overexposed.
  - Missing fields (with issue array):
    
    {"category": "mandatoryFieldsMissing", "issue": ["field1", "field2"]}: Array of mandatory field names that could not be read. Examples: "dateOfBirth", "documentNumber", "fullName".

Notes

Successfully captured zones ("captured": true) only include the zone, captured, and localized fields. They do not include expectation or issues fields.
The issues array will be empty if the zone was localized but no quality issues were detected.
Diagnostic information is aggregated across multiple frames during the timeout period.
Zones that were not detected during the timeout ("localized": false) will only appear if they are required. Optional zones that were not detected are omitted from the output.

toJson()

@NonNull String toJson()

Added in version 6.6.0

Returns the JSON representation of the captured id.

toJsonWithoutImages()

@NonNull String toJsonWithoutImages()

Added in version 7.6.0

Returns the JSON representation of the captured ID without embedding image data. This variant avoids image compression and serialization, making it significantly more performant when image data is not required.