Overview
The Cloudcheck KYB API service enables a reporting entity to integrate the Cloudcheck KYB service into its website. This allows the reporting entity to search for entities (e.g. NZ Limited Company, NZ Co-operative Company), as well as analyse a company's directors and shareholders, without the customer leaving the reporting entity’s website.
Depending on the company structure, an analysis can be complex and can take several minutes to complete. For this reason the analysis is an asynchronous process. The request is sent in one request and the results are retreived in a separate request.
Entities
| Path | /tree/entities/ | Method | GET |
|---|
Search for entities. There are various types of entities, such as a NZ Limited Company, NZ Unlimited Company, NZ Co-operative Company, etc.
| 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. |
searchTerm |
true | The entity that you are searching for. A maximum of 50 entities are returned by this API so make it as specific as possible. |
entityStatus |
false | Comma-separated list of entity status that you are interested in. Possible values are: |
Response
Example
A sample JSON response might look like this:
{
"entities": [
{
"name": "VERIFICATION SERVICES LIMITED",
"registrationDate": "2017-03-07T08:44:39.000+1300",
"nzbn": "9429045996450",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "VERIFIED NZ LIMITED",
"registrationDate": "2017-09-28T12:03:09.000+1300",
"nzbn": "9429046381675",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "VERIFI INTERNATIONAL LIMITED",
"registrationDate": "2017-10-18T15:47:10.000+1300",
"nzbn": "9429046417510",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "VERIFI IDENTITY SERVICES LIMITED",
"registrationDate": "2012-02-07T09:06:17.000+1300",
"nzbn": "9429030806313",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "VERIFI TRACK AND TRACE SOLUTIONS LIMITED",
"registrationDate": "2008-09-18T00:00:00.000+1200",
"nzbn": "9429032561180",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "VERIFIED CHAMPIONS GROUP LIMITED",
"registrationDate": "2017-02-08T08:09:15.000+1300",
"nzbn": "9429045945908",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "VERIFIED CONSULTING GROUP LIMITED",
"registrationDate": "2013-07-26T12:39:59.000+1200",
"nzbn": "9429030125100",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "VERIFIED LAB SERVICES LIMITED",
"registrationDate": "2014-09-02T16:49:22.000+1200",
"nzbn": "9429041384206",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "VERIFIED LOCAL LIMITED",
"registrationDate": "2018-04-18T12:14:04.000+1200",
"nzbn": "9429046730312",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "VERIFIED TIMBER LIMITED",
"registrationDate": "2004-09-20T00:00:00.000+1200",
"nzbn": "9429035214861",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "VERIFIND LIMITED",
"registrationDate": "2009-07-31T00:00:00.000+1200",
"nzbn": "9429032076967",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "Brendon Venter",
"registrationDate": "2019-01-22T00:00:00.000+1300",
"nzbn": "9429047236776",
"type": "Sole Trader",
"status": "Registered"
},
{
"name": "Jenesh BUDHIA",
"registrationDate": "2019-07-01T00:00:00.000+1200",
"nzbn": "9429047542815",
"type": "Sole Trader",
"status": "Registered"
},
{
"name": "INDEPENDENT VERIFICATION SERVICES LIMITED",
"registrationDate": "2004-10-27T00:00:00.000+1300",
"nzbn": "9429035154112",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "PERSONAL VERIFICATION LIMITED",
"registrationDate": "2006-10-06T00:00:00.000+1300",
"nzbn": "9429033825410",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "SMT VERIFICATION LIMITED",
"registrationDate": "2019-06-25T09:04:14.000+1200",
"nzbn": "9429047531680",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "SYSTEM VERIFICATION SERVICES LIMITED",
"registrationDate": "1999-09-15T00:00:00.000+1200",
"nzbn": "9429037485801",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "TALENT VERIFIED LIMITED",
"registrationDate": "2017-12-04T11:53:06.000+1300",
"nzbn": "9429046491145",
"type": "NZ Limited Company",
"status": "Registered"
},
{
"name": "TRANSLATION VERIFICATION SERVICES LIMITED",
"registrationDate": "2014-08-19T08:19:29.000+1200",
"nzbn": "9429041365212",
"type": "NZ Limited Company",
"status": "Registered"
}
]
}
Request
| Path | /tree/request/ | Method | POST |
|---|
Request an Cloudcheck KYB analysis on a company. The analysis is an asynchronous process. This request returns a token that is used to lookup the result at a later time.
| 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 company to be analysed. |
Request
The company to be analysed 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 company name and NZBN were returned in the Entities response.
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.
The callbackUrl is optional but highly recommended and should be set to a URL on your servers. The KYB analysis is an asynchronous process. When a KYB request is made a response is returned immediately, however this response does not contain the results of the analysis. When the analysis completes Cloudcheck makes an HTTP GET call to the callbackUrl. This call contains information that identifies the request. Your code should then call the result API to fetch the KYB result. Include the protocol at the start of the URL (https:// or http://).
Example
This is an example JSON request, which is passed in the data parameter.
{
"nzbn": "9429030806313",
"companyName": "Verifi Identity Services Limited",
"callbackUrl": "...",
"consent": "Yes"
}
Response
Example
A sample JSON response might look like this:
{
"result": "success",
"requestDate": "2019-08-30 10:40",
"token": "45660c0e-3816-455a-8d59-20ddcac4edd4"
}
Result
| Path | /tree/result/ | Method | GET |
|---|
Fetch the results of the analysis. Depending on the complexity of the company being analysed, the response may not be available for several minutes. You may need to call this API more than once if the status comes back as PENDING. Please wait at least 5 seconds between calls in this scenario.
| 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. |
token |
true | A token used to retrieve results that was passed back in the analysis request. |
Response
Example
A PENDING response might look like this:
{
"company": "Verifi Identity Services Limited",
"requestDate": "2019-08-30 11:28",
"nzbn": "9429030806313",
"status": "PENDING"
}
A completed JSON response might look like this:
{
"company": "Verifi Identity Services Limited",
"requestDate": "2019-08-30 11:22",
"nzbn": "9429030806313",
"status": "Registered",
"success": "Yes",
"complexity": 4,
"address": {
"line1": "ABC Business Centre",
"line2": "123 Any Street",
"line3": "Auckland Central",
"line4": "Auckland",
"postcode": "1052"
},
"directors": [
{
"name": "Karl VON RANDOW"
},
{
"name": "Matthew Richard BUCHANAN"
},
{
"name": "Vincent Joseph MCCARTNEY"
},
{
"name": "Tyler Kenneth Alexander MCNAMEE"
}
],
"shareholders": [
{
"percentHolding": 37.45,
"name": "Vincent MCCARTNEY"
},
{
"percentHolding": 12.55,
"name": "Karl VON RANDOW"
},
{
"percentHolding": 12.55,
"name": "Matthew BUCHANAN"
},
{
"percentHolding": 12.55,
"name": "Tyler MCNAMEE"
},
{
"percentHolding": 12.45,
"name": "Catherine Sarah BUCHANAN"
},
{
"percentHolding": 12.45,
"name": "Louise VON RANDOW"
}
],
"consentWording": "By performing this search you agree that Verifi makes no representation about, and assumes no liability in respect of, any search results, the accuracy of which is dependent on the data sourced from New Zealand Business Number register that Verifi has no control over."
}
Result PDF
| Path | /tree/result/pdf/ | Method | GET |
|---|
Once analysis is complete, you can optionally download a Cloudcheck KYB generated PDF of the 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. |
token |
true | A token used to retrieve results that was passed back in the analysis request. |
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.