Cloudcheck Live API1.0

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



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

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 captureReference provided in the Live Request call.

Response

Example


The following fields may not be included in some cases:

  • completedDate is only provided if completed is true
  • matchPercentage is only provided if a comparison has been performed
  • notes are only provided if an image doesn't match for a specific reason
  • cleansed is only provided once images have been removed per the Data Retention Policy
  • cleansedStatus is only provided if cleansed is true

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

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 captureReference provided in the Live Request call.

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

Response

The response JSON contains the captureReference as well as a result element indicating whether the operation was successful.

Example