Overview
The Cloudcheck Live API service enables a reporting entity to automatically generate URLs for Cloudcheck Live.
You (as reporting entity) send basic request data to the Cloudcheck Live API via a secure URL, and a URL is returned for you to provide to your customer.
Live Verification
Path | /live/ | Method | POST |
---|
When sending a verification request to the Cloudcheck Live API, you must include the following parameters as part of the call.
Please note all these parameters must be included as form data, and not set into the POST
body, which is not used. As such, the request should contain a Content-Type
header of application/x-www-form-urlencoded
.
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 Live request information, as shown in the Request example below. |
Request
The details to be verified must be supplied as a JSON object, included in the POST as the data
parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.
Example
{ "reference": "1", "callback": "https://yoursite.com/thanks-url", "verificationReference" : "dac9d987-4007-4dd9-b5a6-cf547232836c", "notificationUrl": "https://www.mycompany.com/capture-notification?id=yourUniqueId", "webhookUrl": "https://www.mycompany.com/live-webhook" }
Optional Fields:
reference
- A reference for your records. This field is optional but recommended.callback
- The URL to return your customer to after the capture is completed. Include the protocol at the start of the URL (https:// or http://).verificationReference
- The Cloudcheck reference from an existing Verification to link this capture to. A verification reference should be linked to a maximum of one Live request.notificationUrl
- A call will be made to this URL once the user completed the Live process, which can be used as a trigger in your code. This URL code should include a unique parameter that you can use to identify the request that it relates to. You must include the protocol at the start of the URL (https:// or http://).webhookUrl
- A call will be made to this URL whenever the Live request changes. The results API can then be called to fetch the current information for this request. You must include the protocol at the start of the URL (https:// or http://). We call this webhook using the POST method, passing a json payload that looks like this:{
"requestType": "CAPTURE",
"eventType": "STATUS_CHANGE",
"reference": "<reference>"
}
where:
<reference>
is the reference or token used to fetch the results using an API call. Note that this webhook functionality may be extended in the future, e.g. different event types and fields may be added.
Response
Example
A sample JSON response might look like this:
{ "capture" : { "reference": "1", "captureReference" : "cab9d987-4007-4dd9-b5a6-cf547232836c", "createdDate": "2013-05-06 12:02", "completed": false, "url": "...", "status":"PENDING",
"recognizedDocuments": [], "images": [],
"ipAddresses": [
"127.0.0.1"
], } }
The url
in the response is where your customer should be directed to, in order to perform the Live check. Once the Live check is completed, cancelled, or failed, Cloudcheck will redirect the customer to the callback
URL parameter provided in the request call above or to a generic completion page if no callback
is provided.
This call will include the following URL parameters:
Parameter | Required | Description |
---|---|---|
liveCaptured |
Yes | ‘true’ if Live images were successfully captured, ‘false’ otherwise. |
liveReference |
Yes | The reference that you provided in the request. |
liveToken |
Yes | A token used to identify the Live request. |
captureReference |
Yes | A reference used to retrieve results of the Live identification. |
Live Result
Path | /live/response/ | Method | GET |
---|
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. |
captureReference |
true | The |
Response
Example
A sample JSON response might look like this:
{
"capture": {
"reference": "SJ Run 343555621",
"matchPercentage": 76,
"recognizedDocuments": [
{
"number": "AX123456",
"documentType": "NZ_DRIVER_LICENCE",
"imageRecognized": "Photo Identification",
"imageUrl": "https://api.cloudcheck.co.nz/live/download/4surMyHIfA4s87BtFVuY6bm7ivS8SRqMF038AbSgrvBvAka8/331/",
"familyName": "Smith",
"givenName": "Michael",
"issueCountry": "NZL",
"dateIssued": "2018-11-22",
"dateExpires": "2028-11-21",
"dateOfBirth": "1975-10-30",
"middleName": "",
"version": "709"
}
],
"images": [
{
"whenCaptured": "2019-08-29 16:20",
"type": "Face and Head",
"url": "https://api.cloudcheck.co.nz/live/download/4surMyHIfA4s87BtFVuY6bm7ivS8SRqMF038AbSgrvBvAka8/332/",
"reviewIssues": "Head not turned enough",
"notes": "...",
"failureMessage": ""
},
{
"matchPercentage": 76,
"whenCaptured": "2019-08-29 16:21",
"type": "Face and Head Turned",
"url": "https://api.cloudcheck.co.nz/live/download/4surMyHIfA4s87BtFVuY6bm7ivS8SRqMF038AbSgrvBvAka8/519/"
},
{
"matchPercentage": 91,
"whenCaptured": "2019-08-29 16:21",
"type": "Photo Identification",
"url": "https://api.cloudcheck.co.nz/live/download/4surMyHIfA4s87BtFVuY6bm7ivS8SRqMF038AbSgrvBvAka8/331/"
}
],
"createdDate": "2019-08-29 16:19",
"captureReference": "5e8136d6-568a-418f-a076-85fe1d79fdd1",
"device": {
"type": "Samsung SM-G935F",
"os": "Android 8",
"browser": "Samsung Internet 14",
},
"ipAddresses": [
"103.14.71.185"
],
"completed": true,
"completedDate": "2019-08-29 16:21",
"status": "MATCH_REVIEW",
"reviewDecision": "ACCEPT",
"reviewNotes": "User did not turn their head in the correct way but is acceptable",
"reviewedBy": "Rebecca White",
"whenReviewed": "2019-08-30 09:30",
"resultBreakdown": {
"documentAssessment": {
"photoTampering": "Pass",
"documentTampering": "Pass",
"environmentCheck": "Pass",
"acceptableIdentityType": "N/A",
"recognisedIdentityType": "Pass"
},
"liveness": {
"livenessCheck": "Pass",
"environmentCheck": "Fail"
}
}
}
}
The following fields may not be included in some cases:
completedDate
is only provided ifcompleted
istrue
matchPercentage
is only provided if a comparison has been performednotes
are only provided if an image doesn't match for a specific reasoncleansed
is only provided once images have been removed per the Data Retention PolicycleansedStatus
is only provided ifcleansed
istrue
The possible values for the status
field and their meaning is as follows:
Code | Description |
---|---|
PENDING | The end user hasn't completed the Live process yet. |
MATCH | The process was completed by the end user, and the Match % comparing the face on their ID document to the captured face of the end user is above your requested threshold for a Match result. |
REVIEW | The process was completed by the end user, and the Match % comparing the face on their ID document to the captured face of the end user was below your requested threshold for a Match result, but above your requested Review threshold. |
MATCH_REVIEW | The process was completed by the end user, and the Match % comparing the face on their ID document to the captured face of the end user is above your requested threshold for a Match result, but there are potential issues for you to review. |
NO_MATCH | The process was completed by the end user, and the Match % comparing the face on their ID document to the captured face of the end user is below your requested threshold for a Review result. |
FAILED | The process was completed by the end user, but there were issues with the image collection. Other fields in the response should clarify what the failure was caused by. |
ABANDONED | The user did not complete the Live process before it timed out. |
COMPLETED | Live is configured to skip the live facial images and the user has completed the requested image collection process. |
We OCR three types of ID: NZ driver licences, Australian driver licences (all states) and passports (any country). Here are examples of these other types of recognizedDocuments
.
Example
{
"number": "1234EN",
"documentType": "AU_DRIVER_LICENCE",
"imageRecognized": "Photo Identification",
"imageUrl": "https://api.cloudcheck.co.nz/live/download/5surMyHIfA4s87BtFVuY6bm7ivS8SRqMF038AbSgrvBvAka8/331/",
"familyName": "Smith",
"givenName": "Michael",
"middleName": "",
"issueCountry": "AUS",
"state": "NSW",
"dateExpires": "2029-12-21",
"dateOfBirth": "1975-10-30"
}
{
"number": "AB123456",
"documentType": "PASSPORT",
"imageRecognized": "Photo Identification",
"imageUrl": "https://api.cloudcheck.co.nz/live/download/6surMyHIfA4s87BtFVuY6bm7ivS8SRqMF038AbSgrvBvAka8/331/",
"familyName": "Smith",
"givenName": "Michael",
"middleName": "",
"issueCountry": "USA",
"dateExpires": "2029-12-21",
"dateOfBirth": "1975-10-30",
"gender": "M",
"mrzResult": "NEEDS_REVIEW",
"mrzCheckFailures": "Passport number in MRZ is present on the passport"
}
Live Result PDF
Path | /live/pdf/ | Method | GET |
---|
Once verification is complete, you can optionally download a Cloudcheck generated PDF of the capture 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. |
captureReference |
true | The |
Response
Calls to 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.
Live Images
Path | /live/download/<imgKey> | Method | GET |
---|
Once verification is complete, you can optionally download the images captured from Cloudcheck. The complete URLs, including the <imgKey>,
are included in the Live Result response JSON. Here is an example from the Live Result response example given earlier:
/live/download/4surMyHIfA4s87BtFVuY6bm7ivS8SRqMF038AbSgrvBvAka8/331/
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. |
Response
Calls to this method will either return an image file (JPEG or PNG) or a 403 error if you do not have permission to access the image.
Live Review
Path | /live/review/ | Method | POST |
---|
Performs a review on a Live request.
When sending a review request to the Cloudcheck Live API, you must include the following parameters as part of the call. Please note all these parameters must be included as form data, and not set into the POST
body, which is not used. As such, the request should contain a Content-Type
header of application/x-www-form-urlencoded
.
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 decision and/or notes must be supplied as a JSON object, included in the POST as the data
parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.
The reviewDecision
is mandatory for MATCH_REVIEW requests.
Example
{
"captureReference": "dac9d987-4007-4dd9-b5a6-cf547232836c",
"reviewDecision": "ACCEPT",
"reviewNotes": "The user did not turn their head enough but is acceptable."
}
Response
The response JSON contains the captureReference
as well as a result
element indicating whether the operation was successful.
Example
{
"capture" : {
"captureReference" : "cab9d987-4007-4dd9-b5a6-cf547232836c",
"result": "success"
}
}