Overview
The Cloudcheck Document Check API service enables a reporting entity to integrate the Cloudcheck Document Check service into its website. This allows the reporting entity to perform an checks on a passports and driver licences, without the customer leaving the reporting entity’s website.
You (as reporting entity) send a passport or driver licence image to the Cloudcheck Document Check API via a secure URL, and the check is performed immediately. The results are then returned to you to handle as you need.
Check
| Path | /doc/runcheck/ | Method | POST |
|---|
When requesting a Document 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 id 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 ID document. For passports the image should be of the passport page containing the MRZ code. For driver licences the image should be of the front of the driver licence. For best results please use a high quality image, minimum of 500KB. It should capture the entire document, including all four corners. The image should be sharp and contain no glare. A dark background works best as it provides good contrast to the ID document. We recommend common image formats such as JPG or PNG. The image can not be shown on the results page for certain formats, such as PDF. |
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": "Document Check 101",
"consent": "Yes"
}
Response
The response JSON contains the details of the document check. It will include details extracted from the document, as well as outcome of the various checks we run.
Example
{
"reference": "Customer-supplied reference",
"documentCheckReference": "cab9d987-4007-4dd9-b5a6-cf547232836d",
"documentCheckType": "PASSPORT",
"requestDate": "2013-05-06 12:00",
"result": "Pass",
"notes": "Error message if applicable",
"forgeryIssues": "Error message if applicable",
"details": {
"mrz": "P<NZLSURNAME<<FIRST<MIDDLE<<<<<<<<<<<<<<<<<LT123456<3NZL6307240M2908085<<<<<<<<<<<<<<08",
"name": {
"given": "FIRST MIDDLE",
"family": "SURNAME"
},
"dateOfBirth": "1963-07-24",
"gender": "M",
"nationality": "NZL",
"documentNumber": "LT123456",
"documentVersion": "",
"issueDate": "2021-08-08",
"expiryDate": "2029-08-08",
"issuingCountry": "NZL",
"issuingState": "",
"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"
},
"resultBreakdown": {
"documentAssessment": {
"photoTampering": "Pass",
"documentTampering": "Pass",
"environmentCheck": "Pass",
"recognisedIdentityType": "Pass"
}
}
}
Results
| Path | /doc/result/ | Method | GET |
|---|
Download the results of a Document 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. |
documentCheckReference |
true | The Cloudcheck-generated |
Response
The response JSON contains the details of the MRZ check.
Example
{
"reference": "Customer-supplied reference",
"documentCheckReference": "cab9d987-4007-4dd9-b5a6-cf547232836d",
"documentCheckType": "PASSPORT",
"requestDate": "2013-05-06 12:00",
"result": "Pass",
"reviewDecision": "ACCEPT",
"reviewNotes": "This looks ok",
"reviewedBy": "API",
"whenReviewed": "2013-05-06 15:14",
"notes": "Error message if applicable",
"forgeryIssues": "Error message if applicable",
"details": {
"mrz": "P<NZLSURNAME<<FIRST<MIDDLE<<<<<<<<<<<<<<<<<LT123456<3NZL6307240M2908085<<<<<<<<<<<<<<08",
"name": {
"given": "FIRST MIDDLE",
"family": "SURNAME"
},
"dateOfBirth": "1963-07-24",
"gender": "M",
"nationality": "NZL",
"documentNumber": "LT123456",
"documentVersion": "",
"issueDate": "2021-08-08",
"expiryDate": "2029-08-08",
"issuingCountry": "NZL",
"issuingState": "",
"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"
},
"resultBreakdown": {
"documentAssessment": {
"photoTampering": "Pass",
"documentTampering": "Pass",
"environmentCheck": "Pass",
"recognisedIdentityType": "Pass"
}
}
}
Results PDF
| Path | /doc/pdf/ | Method | GET |
|---|
Once the check is complete, you can optionally download a Cloudcheck generated PDF of the Document 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. |
documentCheckReference |
true | The Cloudcheck-generated |
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 | /doc/review/ | Method | POST |
|---|
When reviewing a Document 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 Document Check as well as the decision (ACCEPT or REJECT). Review notes can also be added.
Example
{ "documentCheckReference": "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
{ "doc": { "documentCheckReference": "cab9d987-4007-4dd9-b5a6-cf547232836c", "result": "success" }}