Overview
The Cloudcheck MRZ Check API service enables a reporting entity to integrate the Cloudcheck MRZ Check service into its website. This allows the reporting entity to perform an MRZ check on a passport, without the customer leaving the reporting entity’s website.
You (as reporting entity) send a passport image to the Cloudcheck MRZ Check API via a secure URL, and the check is performed immediately. The results are then returned to you to handle as you need.
Note: this API is deprecated. Any new development should use the Document Check API instead.
Check
| Path | /mrz/runcheck/ | Method | POST |
|---|
When requesting an MRZ Check from the Cloudcheck API, you must include the following parameters as part of the call.
Please note that these parameters must be posted as form data. Because the passport image file must also be included, the request should contain a Content-Type header of multipart/form-data.
| Parameter | Required | Description |
|---|---|---|
key |
true | Your API Key. |
signature |
true | An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature. |
nonce |
true | A single-use key generated for this request. Note that each nonce may only be used once for each access key. |
timestamp |
true | The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected. |
data |
true | A JSON string containing the details to be verified. |
file |
true | An image of the passport page containing the MRZ code. For best results please use a high quality image which captures the entire page of the passport. |
Request
The data parameter is a JSON object containing an optional reference for the request as well as consent. The consent parameter is mandatory and must have a value of "Yes".
Example
{
"reference": "MRZ Check 101",
"consent": "Yes"
}
Response
The response JSON contains the details of the MRZ check. If an MRZ code was recognised it will include details extracted from the MRZ code, as well as outcome of the various checks we run.
Example
{
"reference": "MRZ Check 101",
"mrzCheckReference": "6b828f87-b18f-4e42-2v62-d5e5592b9558",
"requestDate": "2020-07-06 11:57",
"result": "Pass",
"details": {
"mrz": "P<NZLSURNAME<<FIRST<MIDDLE<<<<<<<<<<<<<<<<<<LT123456<3NZL7307200M2908085<<<<<<<<<<<<<<08",
"name": {
"given": "FIRST MIDDLE",
"family": "SURNAME"
},
"dateOfBirth": "1973-07-20",
"gender": "M",
"nationality": "NZL",
"passportNumber": "LT123456",
"passportExpiry": "2029-08-08",
"issuingCountry": "NZL",
"personalNumber": "<<<<<<<<<<<<<<"
},
"checks": {
"checkDigit1": "Pass",
"checkDigit2": "Pass",
"checkDigit3": "Pass",
"checkDigit4": "Pass",
"checkDigit5": "Pass",
"issuingCountry": "Pass",
"nationality": "Pass",
"dateOfBirth": "Pass",
"expiryDate": "Pass",
"givenNamesMatch": "Pass",
"passportNumberMatch": "Pass",
"issuingCountryMatch": "Pass",
"nationalityMatch": "Pass"
}
}
Results
| Path | /mrz/result/ | Method | GET |
|---|
Download the results of an MRZ Check in JSON format. These results take into account any changes made since the check was first done, such as review information.
| Parameter | Required | Description |
|---|---|---|
key |
true | Your API Key. |
signature |
true | An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature. |
nonce |
true | A single-use key generated for this request. Note that each nonce may only be used once for each access key. |
timestamp |
true | The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected. |
mrzCheckReference |
true | The Cloudcheck-generated reference that was returned in the response of the MRZ Check. |
Response
The response JSON contains the details of the MRZ check.
Example
{"reference": "MRZ Check 101","mrzCheckReference": "6b828f87-b18f-4e42-2v62-d5e5592b9558","requestDate": "2020-07-06 11:57","result": "Pass","reviewDecision": "NEEDS_REVIEW","reviewNotes": "The user had their finger over the passport number.","reviewedBy": "API","whenReviewed": "2013-05-06 15:14","details": {"mrz": "P<NZLSURNAME<<FIRST<MIDDLE<<<<<<<<<<<<<<<<<<LT123456<3NZL7307200M2908085<<<<<<<<<<<<<<08","name": {"given": "FIRST MIDDLE","family": "SURNAME"},"dateOfBirth": "1973-07-20","gender": "M","nationality": "NZL","passportNumber": "LT123456","passportExpiry": "2029-08-08","issuingCountry": "NZL","personalNumber": "<<<<<<<<<<<<<<"},"checks": {"checkDigit1": "Pass","checkDigit2": "Pass","checkDigit3": "Pass","checkDigit4": "Pass","checkDigit5": "Pass","issuingCountry": "Pass","nationality": "Pass","dateOfBirth": "Pass","expiryDate": "Pass","givenNamesMatch": "Pass","passportNumberMatch": "Fail","issuingCountryMatch": "Pass","nationalityMatch": "Pass",
"forgeryCheck": "Pass"}}
Results PDF
| Path | /mrz/pdf/ | Method | GET |
|---|
Once the check is complete, you can optionally download a Cloudcheck generated PDF of the MRZ check results.
| Parameter | Required | Description |
|---|---|---|
key |
true | Your API Key. |
signature |
true | An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature. |
nonce |
true | A single-use key generated for this request. Note that each nonce may only be used once for each access key. |
timestamp |
true | The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected. |
mrzCheckReference |
true | The Cloudcheck-generated reference that was returned in the response of the MRZ Check. |
Response
This method will either return a PDF file or a JSON object with an error message. You should check the response Content-Type to determine which you have received.
Review
| Path | /mrz/review/ | Method | POST |
|---|
When reviewing an MRZ Check you must include the following parameters as part of the call.
Please note that these parameters must be posted as form data. Because the passport image file must also be included, the request should contain a Content-Type header of multipart/form-data.
| Parameter | Required | Description |
|---|---|---|
key |
true | Your API Key. |
signature |
true | An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature. |
nonce |
true | A single-use key generated for this request. Note that each nonce may only be used once for each access key. |
timestamp |
true | The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected. |
data |
true | A JSON string containing the details to be verified. |
Request
The data parameter is a JSON object containing the reference of the MRZ Check as well as the decision (ACCEPT or REJECT). Review notes can also be added.
Example
{"mrzCheckReference": "dac9d987-4007-4dd9-b5a6-cf547232836c","reviewDecision": "ACCEPT","reviewNotes": "The name couldn't be matched against the passport due to a stamp on the passport partially covering the name."}
Response
The response JSON contains the outcome of the review request.
Example
{
"mrz": {
"mrzCheckReference": "cab9d987-4007-4dd9-b5a6-cf547232836c",
"result": "success"
}
}