Businesses
A Business represents a company registered with the New Zealand Companies Office.
A Business is associated with a single Account.
Contents
Models
Business
Field | Type | Description |
---|---|---|
id | String | The unique identifier. |
accountId | String | The Centrapay accountId for an org account. |
accountName | String | The Centrapay account name for an org account. |
test | Boolean | A flag which is present if the Account is test |
nzbn | String | The unique NZBN identifier. |
name | String | Legal name recorded in the Companies Register. |
tradingName | String | Trading name recorded in the Companies Register. |
companyNumber | String | Company number recorded in the Companies Register. |
createdAt | Timestamp | When the Business was created. |
updatedAt | Timestamp | When the Business was updated. |
createdBy | CRN | The User or API Key that created the Business. |
updatedBy | CRN | The User or API Key that updated the Business. |
taxNumber | Tax Number Optional | The value-added tax configuration for the Business. |
Tax Number
Field | Type | Description |
---|---|---|
value | String | The tax number. |
type | String | Type of value-added tax. Can be nz-gst . |
Operations
Create a Business EXPERIMENTAL
If accountId
is not provided when creating a business, then a new org account will be created and associated to the business.
POST /
curl -X POST https://service.centrapay.com/api/businesses \
-H "X-Api-Key: $api_key" \
-H "Content-Type: application/json" \
-d '{
"nzbn": "9429046246448",
"taxNumber": {
"value": "123-456-789",
"type": "nz-gst"
}
}'
Required Fields
Field | Type | Description |
---|---|---|
nzbn | String | The unique NZBN identifier. |
Optional Fields
Field | Type | Description |
---|---|---|
accountId | String | The Centrapay accountId. |
test | String | The created Centrapay org account will have the test flag. |
taxNumber | Tax Number | The value-added tax configuration. |
Example response payload
{
"id": "DKTs3U38hdhfEqwF1JKoT2",
"accountId": "Jaim1Cu1Q55uooxSens6yk",
"accountName": "Centrapay",
"nzbn": "9429046246448",
"name": "CENTRAPAY LIMITED",
"tradingName": "CentraPay",
"companyNumber": "6340244",
"createdAt": "2020-06-12T01:17:46.499Z",
"updatedAt": "2020-06-12T01:17:46.499Z",
"createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
"updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
"taxNumber": {
"value": "123-456-789",
"type": "nz-gst"
}
}
Error Responses
Status | Code | Description |
---|---|---|
403 | INVALID_ACCOUNT | Account does not exist, is not authorized, is of the wrong type, or is not in the NZ region. |
403 | INVALID_NZBN | The NZBN provided does not match any NZ business. |
Get a Business by Account id EXPERIMENTAL
GET /
curl https://service.centrapay.com/api/accounts/Jaim1Cu1Q55uooxSens6yk/business \
-H "X-Api-Key: $api_key"
Example response payload
{
"id": "DKTs3U38hdhfEqwF1JKoT2",
"accountId": "Jaim1Cu1Q55uooxSens6yk",
"accountName": "Centrapay",
"nzbn": "9429046246448",
"name": "CENTRAPAY LIMITED",
"tradingName": "CentraPay",
"companyNumber": "6340244",
"createdAt": "2020-06-12T01:17:46.499Z",
"updatedAt": "2020-06-12T01:17:46.499Z",
"createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
"updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
}
Search NZ Company Register EXPERIMENTAL
Returns a list of companies that match the queried param on company name, nzbn number or company number. Results are paginated and ordered by relevance.
GET /
curl -G https://service.centrapay.com/api/nzbn-search \
-H "X-Api-Key: $api_key" \
-d q=centrapay
Query Parameters
Parameter | Description |
---|---|
q | Company name, number or NZBN to search for. |
Example response payload
{
"items": [
{
"nzbn": "9429046246448",
"companyName": "CENTRAPAY LIMITED",
"companyNumber": "6340244"
}
]
}
Get Business Details from NZ Company Register EXPERIMENTAL
GET /
curl https://service.centrapay.com/api/nzbn/9429046246448 \
-H "X-Api-Key: $api_key"
Example response payload
{
"nzbn": "9429046246448",
"companyName": "CENTRAPAY LIMITED",
"tradingName": "CentraPay",
"companyNumber": "6340244",
"directors": [
{
"firstName": "John",
"lastName": "DOE",
"addressLines": [
"7 Tara Street",
"Downmore",
"Auckland"
]
},
{
"firstName": "Jane",
"lastName": "DOE",
"addressLines": [
"82 Greatwood Road",
"Northclover",
"Auckland"
]
}
]
}