Cloudcheck Integrated API

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 `verificationReference` as supplied in the JSON response received from the Verification Request call.

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 `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.

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 `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).
`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.
`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&timestamp=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"
        },
        ...
    ]
}

Cloudcheck Integrated API1.0

Core

APIs

Overview

Verification

Request

Example

Additional Data Sources

Response

Example

Checking Name, Date of Birth and Address

Checking Name and Date of Birth

Checking Name and Address

Results

Response

Result PDF

Response

PEP Review

Request

Example

Response

Example

Reports

Request

Example

Status

Request

Response

Example

Solutions

Industries

About

Contact