Overview
The Company API provides various company related services.
Company Roles
| Path | /companyroles/ | Method | POST |
|---|
This service returns a list of companies that the specified individual is potentially associated with, as well as their role within each company.
| 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.
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.
Example
{
"name": {
"given": "Vincent",
"middle": "Joseph",
"family": "McCartney"
},
"reference": "Companies Test 1"
}
Optional Fields:
reference- A reference for your records. This field is optional but recommended.middle- The middle name of the person being queried.
Response
The response JSON contains the details of the company role search, including individual as well as company data.
Example
{
"response": {
"roles": [
{
"individual": {
"name": {
"given": "Vincent",
"family": "MCCARTNEY"
},
"role": "Director",
"appointmentDate": "2017-10-18"
},
"company": {
"name": "VERIFI INTERNATIONAL LIMITED",
"companyNumber": "6507113",
"nzbn": "9429046417510",
"status": "Registered",
"type": "NZ Limited Company",
"incorporationDate": "2017-10-18",
"registeredOfficeAddress": {
"street": "Level 1, 220 Queen Street",
"city": "Auckland",
"postcode": "1010"
}
}
},
{
"individual": {
"name": {
"given": "Vincent",
"middle": "Joseph",
"family": "MCCARTNEY"
},
"role": "DirectorShareholder"
},
"company": {
"name": "VERIFI IDENTITY SERVICES LIMITED",
"companyNumber": "3716996",
"nzbn": "9429030806313",
"status": "Registered",
"type": "NZ Limited Company",
"incorporationDate": "2012-02-07",
"registeredOfficeAddress": {
"street": "Level 1, 220 Queen Street",
"city": "Auckland",
"postcode": "1010"
}
}
},
{
"individual": {
"name": {
"given": "Vincent",
"middle": "Joseph",
"family": "MCCARTNEY"
},
"role": "Director",
"appointmentDate": "2019-05-02"
},
"company": {
"name": "BLACK BULL GROUP LIMITED",
"companyNumber": "5463921",
"nzbn": "9429041417799",
"status": "Registered",
"type": "NZ Limited Company",
"incorporationDate": "2014-09-18",
"registeredOfficeAddress": {
"street": "Level 22, 120 Albert Street",
"suburb": "Auckland Central",
"city": "Auckland",
"postcode": "1010"
}
}
}
],
"transactionReference": "d4621752-35f7-4c31-a24d-e906d861ec21"
}
}
It also returns a transactionReference, which is a unique reference for this API call.