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
This is the minimum detail required for verification.
{ "details": { "address": { "suburb": "Hillsborough", "street": "27 Indira Lane", "postcode": "8022", "city": "Christchurch", "countryCode": "NZ" }, "name": { "given": "Cooper", "middle": "John", "family": "Down" }, "dateofbirth": "1978-01-10" }, "captureReference": "1cf8ffe6-8de9-69c5-02de-bc03453499a8", "idscanReference": "2cf8afe6-0de9-45c5-92de-ac03453499a3", "akahuReference": "3cf8fce6-5de9-39c5-a2de-1c03453499a1", "credfinReference": "4cf8f2e6-9de9-40c5-9cde-fc03453499a0", "reference": "1", "consent": "Yes" }
A capturereference
is not required but can be supplied if you want to link a Live request to this verification.
An idscanReference
is not required but can be supplied if you want to link an IDscan request to this verification.
An akahuReference
is not required but can be supplied if you want to link an Akahu request to this verification.
A credfinReference
is not required but can be supplied if you want to link a Credfin request to this verification.
Only one of capturereference
, idscanReference
, akahuReference
or credfinReference
should be specified.
Note the address node can contain either street or streetnumber and streetname, as below. It must not contain both.
"address": { "suburb": "Hillsborough", "street": "27 Indira Lane", "postcode": "8022", "city": "Christchurch",
"countryCode": "NZ" }
Or:
"address": { "suburb": "Hillsborough", "streetnumber": "27", "streetname": "Indira Lane" "postcode": "8022", "city": "Christchurch",
"countryCode": "NZ" }
For Australian addresses state should be included.
"address": {
"street": "115 Murnburlu Rd",
"city": "Cossack",
"state": "NT",
"postcode": "0850",
"countryCode": "AU"
}
Note that the "countryCode" field in all of these examples is recommended but optional, and will be inferred if not supplied.
To check with additional data sources, more information may be required in the details
section of the JSON.
Additional Data Sources
Most third party data sources will require additional information. Some also provide optional fields to further improve the accuracy of the verification result.
Note not all third party data sources are available to all access keys. You will need to contact us to activate third party data sources for your access key.
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
This response includes Address, Date of Birth and PEP Watchlist verifications.
{
"verification": {
"details": {
"address": {
"suburb": "Anytown",
"street": "123 Poplar Road",
"postcode": "1234",
"city": "Somewhereville",
"state": "",
"countryCode": "NZ"
},
"dateofbirth": "1970-01-01",
"dateofbirthChanged": false,
"name": {
"given": "Jane",
"middle": "Wendy",
"family": "Smith"
},
"nameChanged": false
},
"verificationDate": "2013-05-06 12:02",
"verificationReference": "dac9d987-4007-4dd9-b5a6-cf547232836c",
"verificationSuccess": true,
"verificationPartialSuccess": false,
"validated": {
"name": true,
"namePassCount": 2,
"address": true,
"addressPassCount": 1,
"dateofbirth": true,
"dobPassCount": 1,
"pepMatched": true,
"pepPassCount": 1
},
"sources": [
{
"name": "Companies Office",
"success": true,
"error": false
},
{
"name": "NZTA (Driver‘s Licence)",
"success": true,
"error": false,
"notes": "License Match: Yes",
"data": {
"number": "AA123456",
"version": "123"
}
}
],
"pepMatches": [{
"dateOfBirth": ["1970-01-01"],
"title": "See Previous Roles",
"riskTypes": ["PEP"],
"name": "Smith, Jane",
"peid": 000000,
"score": 1,
"type": "Person",
"countries": [
{
"type": "Citizenship",
"name": "United Kingdom"
}
]
}],
"reference": "1",
"requestDate": "2013-05-06 12:00",
"ipAddress": "127.0.0.1",
}
}
Note the results will include only the sources checked in the verification process, which may not be all of the sources available to your access key.
The data
element under sources
will contain elements matching the elements passed in (see the Additional Data Sources section above).
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 |
The dateofbirthChanged
and nameChanged
elements indicate whether the date of birth (DOB) or name were changed by the user in the verification form. They will be set to true if Cloudcheck Live scanned and recognised their DOB or name and then the user subsequently changed these details on the form. These fields will only be accurate before the data has been purged.
Results
Path | /verify/result/ | Method | GET |
---|
Using a verification reference, the reporting entity can retrieve the results of a verification. Note that details entered by the customer can be retrieved for 7 days following a successful verification. After this time, Cloudcheck disposes of all personal data, but the general verification pass/fail details remain available.
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 |
Response
See the response notes and example for the Verification endpoint.
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 |
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.
PEP Review
Path | /verify/pep/review/ | Method | POST |
---|
Performs a review of one or more PEP matches.
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 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
{
"verificationReference": "eac9d981-4007-4dd9-b5a6-cf547232836c",
"reviews": [
{
"peid": 12345678,
"decision": "CLEARED",
"notes": "This person is a lot older and lives in a different country."
},
...
]
}
The valid values of the decision element are CLEARED
and OUR_CLIENT
.
Response
An example of a successful response is shown below:
Example
{
"review": {
"verificationReference": "cab9d987-4007-4dd9-b5a6-cf547232836c",
"result": "success",
"matchesUpdated": 3
}
}
The matchesUpdated element shows how many PEP matches were updated. If invalid PEID
's are passed in the request they will be ignored.
Reports
Path | /verify/report/:type | Method | GET |
---|
Run various reports with a maximum date range of one month. Only one report of a given type can be run at one time. If you attempt to start a second report of the same type as one that is already running you will receive an error explaining this limitation.
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 |
endDate |
true | Format |
format |
false |
|
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. |
live |
A summary of Cloudcheck Live requests. |
live-detail |
A detailed report of Cloudcheck Live requests. |
idscan |
A summary of IDscan requests. |
idscan-detail |
A detailed report of IDscan requests. |
akahu |
A summary of Akahu requests. |
akahu-detail |
A detailed report of Akahu requests. |
credfin |
A summary of Credfin requests. |
credfin-detail |
A detailed report of Credfin requests. |
watchlist-errors |
A list of PEP Watchlist errors that occurred during this period. |
mrz-detail |
A list of MRZ Checks that occurred during this period. |
go |
A summary of Cloudcheck Go requests that occurred during this period. |
go-detail |
Details of Cloudcheck Go requests that occurred during this period. |
Example
To view report details for May 2017, the following URL is correct using the secret key Ur7znqOTM1KuQw2gXBt0ShDqQcHVGsAq
, and the given parameters:
Parameter | Description |
---|---|
key |
lj5YozlG6cv7mm6c |
nonce |
1 |
timestamp |
1353987581461 |
startDate |
2017-05-01 |
endDate |
2017-05-31 |
maxResults |
25 |
page |
2 |
/verify/report/detail?key=lj5YozlG6cv7mm6c&nonce=1×tamp=1353987581461&startDate=2017-05-01&endDate=2017-05-31&maxResults=25&page=2&signature=774366d9170e3d0b36dbe2130c84a9958b0eecf3691f63e225d8dd48d9da3cd6
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
A sample response JSON might look like this.
{ "sources": [ { "name": "New Zealand Citizenship", "available": true, "lastChecked": "2018-06-02 14:52" }, { "name": "Australian Medicare", "available": true, "lastChecked": "2018-06-02 14:53" }, ... ] }