eMRTD Result

This eMRTD Result represents data from an eMRTD and check results.
Refer to the Security Mechanisms Overview and ICAO Doc9303 (Part 10 and 11 in particular).

With the WebSocket API, the Client Validation ID will be included additionally.

Example JSON

json

{
  "emrtd_passport": {
    "sod_info": {
      "hash_algorithm": "SHA-256",
      "hash_for_data_group": {
        "1": "B7ZYsPUdx6/77hON2QpI/7Hr36tlH5m+Am0WuzWDFn4=",
        "2": "b4xR1WNjbu5DY67seOpC8OAmkwErnwbsXkJIzTiCuas=",
        "7": "Rt0gaZ1pvAnp0CEcd+ir05fWCpT+cj7ecKxH+rWUDoo=",
        "11": "/oYfYTAHXtF5oZbb6kcMrq7BGoMVtmOWsqvM0ctyBCI=",
        "12": "IXIYTHM0l3EeCpu74Z1zHTGT1HQH1KRKU+2Dhu8OuRA=",
        "14": "w62EEvLa74fLyhBYiulDtrt/2vQmueFGAJM5s+UdtMM=",
        "15": "VjBncDBu+qGAcCoZFthMNuU3pmBR8ECLXejkKhjIM+A="
      }
    },
    "mrz_info": {
      "document_type": "TD3",
      "document_code": "P",
      "issuing_state": "USA",
      "primary_identifier": "PARKER",
      "secondary_identifier": ["PETER"],
      "nationality": "USA",
      "document_number": "5S280806",
      "date_of_birth": "010810",
      "gender": "MALE",
      "date_of_expiry": "250718",
      "optional_data1": "",
      "optional_data2": null
    },
    "face_photo": "/9j/4AAQ...",
    "signature_photos": ["/9j/4AAQ..."],
    "additional_personal_details": {
      "full_name_of_holder": "PETER BENJAMIN PARKER",
      "other_names": [],
      "personal_number": null,
      "full_date_of_birth": "20010810",
      "place_of_birth": "NEW YORK USA",
      "permanent_address": null,
      "telephone": null,
      "profession": null,
      "title": null,
      "personal_summary": null,
      "proof_of_citizenship_image": null,
      "other_valid_travel_document_numbers": null,
      "custody_information": null
    },
    "additional_document_details": {
      "issuing_authority": "UNITED STATES DEPARTMENT OF STATE",
      "date_of_issue": "20091116",
      "names_of_other_persons": null,
      "endorsements_and_observations": null,
      "tax_or_exit_requirements": null,
      "image_of_front": null,
      "image_of_rear": null,
      "date_and_time_of_personalization": null,
      "personalization_system_serial_number": null
    },
    "passive_authentication": false,
    "passive_authentication_details": {
      "sod_signature_valid": true,
      "document_certificate_valid": false,
      "data_groups_checked": [1, 2, 7, 11, 12, 14, 15],
      "data_groups_with_valid_hash": [1, 2, 7, 11, 12, 14, 15],
      "error": null,
      "all_hashes_valid": true
    },
    "chip_authentication_result": "SUCCESS",
    "active_authentication_result": "UNAVAILABLE",
    "errors": [],
    "files_binary": {
      "dg7": "Z4IGqwIBAV9Dggaj/9j/4AAQSkZ...",
      "dg14": "bgIxAA...",
      "sod": "d4IKgjCCCn4GCSqGSIb3DQEHAqCCCm...",
      "dg12": "bDVcBF8ZXyZfGSFVTklURUQgU1RBVEVTIERFUEFSVE1FTlQgT0YgU1RBVEVfJggyMDA5MTExNg==",
      "dg11": "azpcBl8OXytfEV8OFVBFVEVSIEJFTkpBTUlOIFBBUktFUl8rCDIwMDEwODEwXxEMTkVXIFlPUksgVVNB",
      "dg2": "dYIGKH9hggYjAgEB...",
      "dg1": "YVtfH1hQPFVTQVBBUktFUjw8UEVURVI8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDVTMjgwODA2PDN..."
    }
  },
  "client_validation_id": "69fe774e-50d3-49fc-a285-6fab7665563e"
}

eMRTD

The field emrtd_passport contains the Result about the document.

sod_info SOD Info
mrz_info MRZ Info
face_photo Face Photo
signature_photos Signature Photos
additional_personal_detailsAdditional Personal Details
additional_document_detailsAdditional Document Details
passive_authentication Passive Authentication
passive_authentication_detailsPassive Authentication Details
chip_authentication_resultChip Authentication Result
active_authentication_resultActive Authentication Result
errors Errors
files_binary Files Binary

SOD Info

Details from the Document Security Object (SOD).

hash_algorithm: String E.g. "SHA-256"
hash_for_data_group: Object Entry for each Data Group present
- 1: String Base64 encoded hash value for Data Group 1
- 2: String Base64 encoded hash value for Data Group 2
- ...

Example JSON

json

{
  "emrtd_passport": {
    "sod_info": {
      "hash_algorithm": "SHA-256",
      "hash_for_data_group": {
        "1": "B7ZYsPUdx6/77hON2QpI/7Hr36tlH5m+Am0WuzWDFn4=",
        "2": "b4xR1WNjbu5DY67seOpC8OAmkwErnwbsXkJIzTiCuas=",
        ...
      }
    },
    ...
  }
}

MRZ Info

MRZ information from Data Group 1.

document_type: String "TD1", "TD2" or "TD3"
document_code: String "P" for passports
issuing_state: String E.g. "USA"
primary_identifier: String Usually the family name
secondary_identifier: Array<String> Usually the given names
nationality: String E.g., "USA"
document_number: String String for the document number
date_of_birth: String Format: yyMMdd
gender: String: String "FEMALE", "MALE" or "UNSPECIFIED"
date_of_expiry: String Format: yyMMdd
optional_data1: String Optional data field
optional_data2: String | null Optional data field (TD1 only)

Example JSON

json

{
  "emrtd_passport": {
    ...
    "mrz_info": {
      "document_type": "TD3",
      "document_code": "P",
      "issuing_state": "USA",
      "primary_identifier": "PARKER",
      "secondary_identifier": ["PETER"],
      "nationality": "USA",
      "document_number": "5S280806",
      "date_of_birth": "010810",
      "gender": "MALE",
      "date_of_expiry": "250718",
      "optional_data1": "",
      "optional_data2": null
    },
    ...
  }
}

Face Photo

Base64 encoded JPEG image from DataGroup 2.

Example JSON

json

{
  "emrtd_passport": {
    ...
    "face_photo": "/9j/4AAQ...",
    ...
  }
}

Signature Photos

Base64 encoded JPEG image(s) from Data Group 7.

Example JSON

json

{
  "emrtd_passport": {
    ...
    "signature_photos": ["/9j/4AAQ..."],
    ...
  }
}

Additional Personal Details

Additional Personal Details from Data Group 11.

Example JSON

json

{
  "emrtd_passport": {
    ...
    "additional_personal_details": {
      "full_name_of_holder": "PETER BENJAMIN PARKER",
      "other_names": [],
      "personal_number": null,
      "full_date_of_birth": "20010810",
      "place_of_birth": "NEW YORK USA",
      "permanent_address": null,
      "telephone": null,
      "profession": null,
      "title": null,
      "personal_summary": null,
      "proof_of_citizenship_image": null,
      "other_valid_travel_document_numbers": null,
      "custody_information": null
    },
    ...
  }
}

Additional Document Details

Additional Document Details from Data Group 12.

Example JSON

json

{
  "emrtd_passport": {
    ...
    "additional_document_details": {
      "issuing_authority": "UNITED STATES DEPARTMENT OF STATE",
      "date_of_issue": "20091116",
      "names_of_other_persons": null,
      "endorsements_and_observations": null,
      "tax_or_exit_requirements": null,
      "image_of_front": null,
      "image_of_rear": null,
      "date_and_time_of_personalization": null,
      "personalization_system_serial_number": null
    },
    ...
  }
}

Passive Authentication

Boolean indicating the overall Passive Authentication result.

Example JSON

json

{
  "emrtd_passport": {
    ...
    "passive_authentication": false,
    ...
  }
}

Passive Authentication Details

sod_signature_valid: Boolean | null Whether the Signature of the Document Security Object is verified using the Document Signer Certificate
document_certificate_valid: Boolean | null Whether the Document Signing Certificate is signed by a trusted Country Certificate
data_groups_checked: Array<Integer> | null Data Groups that were processed
data_groups_with_valid_hash: Array<Integer> | null Data Groups with valid hash value
error: String | null Error message during passive authentication
all_hashes_valid: Boolean | null Whether all checked Data Groups are authentic and unchanged

Example JSON

json

{
  "emrtd_passport": {
    ...
    "passive_authentication_details": {
      "sod_signature_valid": true,
      "document_certificate_valid": false,
      "data_groups_checked": [1, 2, 7, 11, 12, 14, 15],
      "data_groups_with_valid_hash": [1, 2, 7, 11, 12, 14, 15],
      "error": null,
      "all_hashes_valid": true
    },
    ...
  }
}

Note

Some fields are null if one of the following errorsFAILED_TO_PARSE_SOD, DATA_GROUPS_HASHED_WITH_UNSUPPORTED_ALGORITHM or SIGNATURE_VERIFY_EXCEPTION occurred.

Chip Authentication Result

Chip Authentication result, either SUCCESS, FAILED or UNAVAILABLE.

Example JSON

json

{
  "emrtd_passport": {
    ...
    "chip_authentication_result": "SUCCESS",
    ...
  }
}

Notes:

The authenticity of Data Group 14 must be verified through Passive Authentication to ensure that the Chip Authentication result is meaningful. (passive_authentication must be true!!).
This field is not present in the response of the REST API v4/validate

Active Authentication Result

Active Authentication result, either SUCCESS, FAILED or UNAVAILABLE.

Example JSON

json

{
  "emrtd_passport": {
    ...
    "active_authentication_result": "UNAVAILABLE",
    ...
  }
}

Notes:

The authenticity of Data Group 14 and 15 must be verified through Passive Authentication to ensure that the Chip Authentication result is meaningful. (passive_authentication must be true!!).
This field is not present in the response of the REST API v4/validate

Errors

Errors that might occur while processing the data.

Error Code	Description
`FAILED_TO_PARSE_SOD`	SOD is available but could not be parsed.
`FAILED_TO_PARSE_DG1`	Data Group 1 is available but could not be parsed.
`FAILED_TO_PARSE_DG2`	Data Group 2 is available but could not be parsed.
`FAILED_TO_PARSE_DG7`	Data Group 7 is available but could not be parsed.
`FAILED_TO_PARSE_DG11`	Data Group 11 is available but could not be parsed.
`FAILED_TO_PARSE_DG12`	Data Group 12 is available but could not be parsed.
`FAILED_TO_ENCODE_FACE_PHOTO_AS_JPEG`	Failed to encode Face Photo as normal JPEG.
`FAILED_TO_ENCODE_SIGNATURE_PHOTO_AS_JPEG`	Failed to encode one or multiple Signature Photos as normal JPEG(s).

Example JSON

json

{
  "emrtd_passport": {
    ...
    "errors": [],
    ...
  }
}

Notes:

If one of the images could not be encoded as normal JPEG, the field will contain the RAW image bytes. The images are supposed to be encoded as JPEG or JPEG2000 (JP2).

Files Binary

Base64 encoded files (binary) (SOD + Data Group).

sod: String Binary SOD file, base64 encoded.
dg1: String Binary Data Group 1, base64 encoded.
dg2: String Binary Data Group 2, base64 encoded.
...

Example JSON

json

{
  "emrtd_passport": {
    ...
    "files_binary": {
      "dg7": "Z4IGqwIBAV9Dggaj/9j/4AAQSkZ...",
      "dg14": "bgIxAA...",
      "sod": "d4IKgjCCCn4GCSqGSIb3DQEHAqCCCm...",
      "dg12": "bDVcBF8ZXyZfGSFVTklURUQgU1RBVEVTIERFUEFSVE1FTlQgT0YgU1RBVEVfJggyMDA5MTExNg==",
      "dg11": "azpcBl8OXytfEV8OFVBFVEVSIEJFTkpBTUlOIFBBUktFUl8rCDIwMDEwODEwXxEMTkVXIFlPUksgVVNB",
      "dg2": "dYIGKH9hggYjAgEB...",
      "dg1": "YVtfH1hQPFVTQVBBUktFUjw8UEVURVI8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDVTMjgwODA2PDN..."
    }
  }
}

Notes:

Field is only present if the WS_ENDPOINT_INCLUDE_BINARY_FILES_IN_RESULT is set to "true".
This field is not present in the response of the REST API v4/validate

Client Validation ID

A (unique) transaction id to map the result to a user/session. This is the validation_id the WebSocket client used.

Example JSON

json

{
  "emrtd_passport": {
    ...
  },
  "client_validation_id": "69fe774e-50d3-49fc-a285-6fab7665563e"
}

Notes:

This field is not present in the response of the REST API v4/validate

eMRTD Result ​

eMRTD ​

SOD Info ​

MRZ Info ​

Face Photo ​

Signature Photos ​

Additional Personal Details ​

Additional Document Details ​

Passive Authentication ​

Passive Authentication Details ​

Note ​

Chip Authentication Result ​

Notes: ​

Active Authentication Result ​

Notes: ​

Errors ​

Notes: ​

Files Binary ​

Notes: ​

Client Validation ID ​

Notes: ​

eMRTD Result

eMRTD

SOD Info

MRZ Info

Face Photo

Signature Photos

Additional Personal Details

Additional Document Details

Passive Authentication

Passive Authentication Details

Note

Chip Authentication Result

Notes:

Active Authentication Result

Notes:

Errors

Notes:

Files Binary

Notes:

Client Validation ID

Notes: