Link Search Menu Expand Document
Centrapay Docs

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 /api/businesses 

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 /api/accounts/{accountId}/business 

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 /api/nzbn-search 

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 /api/nzbn/{nzbn} 

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"
      ]
    }
  ]
}

Update a Business EXPERIMENTAL

PUT /api/businesses/{id} 

curl -X PUT https://service.centrapay.com/api/businesses/DKTs3U38hdhfEqwF1JKoT2 \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "taxNumber": {
      "value": "123-456-789",
      "type": "nz-gst"
    }
  }'

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"
  }
}