Cloudcheck Integrated API v1.0

Overview

The Cloudcheck Integrated API service enables a reporting entity to integrate the Cloudcheck service into its website. This allows the reporting entity to perform electronic verification (EV) on a customer, without the customer leaving the reporting entity’s website.

You (as reporting entity) send the data to the Cloudcheck Integrated API via a secure URL, and EV is performed on the data immediately. The results are then returned to you to handle as you need. This process ensures the security of your data, and preserves the integrity of the EV process.

Verification

Path /verify/ Method POST

When requesting a verification from the Cloudcheck API, you must include the following parameters as part of the call.

Please note all these parameters must be posted as URL encoded form data. 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.

username false

Optional value to link this request to a user in your organisation.

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

To check with additional data sources, more information may be required in the details section of the JSON. 

Additional Data Sources

Response

The response JSON contains the details of the verification, including individual data sources that were checked, and the results for each as well as for the overall check.

Example

The contents of verificationSuccess and verificationPartialSuccess returned by the API are as follows. Note the Read As column indicates how the results should be interpreted, and is not included in the response.

Checking Name, Date of Birth and Address

Verified Partial Success Allowed* Partial Success Not Allowed
Name Date of Birth Address Success Partial Success Read As Success Read As
false false false Fail false Fail
true false false false Fail false Fail
true true false true true Partial false Fail
true true true true false Pass true Pass

*Partial Success only applies if the key in use is configured to allow a pass without a verified address.

Checking Name and Date of Birth

Note no partial success is possible in this case.

Name Verified Date of Birth Verified Success Read As
false false Fail
true false false Fail
true true true Pass

Checking Name and Address

Note no partial success is possible in this case.

Name Verified Address Verified Success Read As
false false Fail
true false false Fail
true true true Pass

Result PDF

Path /verify/pdf/ Method GET

Once verification is complete, you can optionally download a Cloudcheck generated PDF of the verification 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.

reference true

The verificationReference as supplied in the JSON response received from the Verification Request call.

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.

Reports

Path /verify/report/:type 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.

startDate true

Format yyyy-mm-dd. The first date to show records for (inclusive).

endDate true

Format yyyy-mm-dd. The last date to show records for (inclusive).

maxResults false

detail report only. The maximum number of results to return per page. Defaults to 50 and cannot be greater than 100.

page false

detail report only. The page of results to return. Default value is 1.

format false

json or xml. Default is JSON

Request

Report Types

Code Description
summary A count of verifications performed through each service, with a breakdown of successful, partial and failed verifications.
detail Results of all verifications, including results for each data source checked. Note this report is paginated automatically, and can only be run for a single calendar month at a time.
source A summary of the number of checks for each data source, listed by service, including a breakdown of successful, partial and failed verifications.

Example

Status

Path /status/ Method GET

Request

The format of the response depends on the Accept header of the request.

Accept Response Format
text/html HTML
application/json JSON
*/xml XML

Note the table above is in priority order. If the Accept header contains multiple formats the selected option will be HTML first, JSON second, or XML if nothing else matches.

Response

Example