DataTools Kleber Method Description

Method:
DataTools.Capture.BusinessName.Search.Nzbr.SearchBusinessName
Use this method to search the New Zealand Business Name register of business entities. Currently this includes all entities from the Companies Register, with further types to be added in future when enabling legislation has passed. Users must create an account with MBIE in order to access this service. Visit http://api.business.govt.nz/ for more details.

Test:

Parameter	Value
BusinessName
AuthenticationToken
TestEnvironment
EntityStatus
EntityType
IndustryCode
ResultLimit
RequestId
RequestKey
DepartmentCode

Input Parameters:

Parameter	Description
BusinessName	Name to search for. Populate with the search keyword or 2-100 characters.
AuthenticationToken	The OAuth Token provided when you registered with MBIE for access to the NZBN web services. Visit http://support.api.business.govt.nz/customer/widget/emails/new to resister for a token.
TestEnvironment	Identifies if the call is to be directed to the test environment data.eat.nzbn.govt.nz. NOTE the data provided in the test environment does not match the data provided by the live environment. For production purposes please ensure you use the live environment. [Option Values]
EntityStatus	Optional filter for Business Status code. [Option Values]
EntityType	Optional filter for Entity Type code. [Option Values]
IndustryCode	Optional filter for Business Industry Code (BIC) eg. S955220, F373970.
ResultLimit	A numeric value representing the maximum results to be returned. If no value supplied a default maximum of 10 results will be returned.
RequestId	Optional user value to assist in linking DtRequests with DtResponses.
RequestKey	Required for user access verification. For client side script protect your Request Key by using the DataTools.Security.GenerateTemporaryRequestKey
DepartmentCode	Optional user value to allocate transaction usage by department. Limit of 50 unique Department codes per account.

Output Fields:

Field	Description
OrganisationName	Entity Name (current)
PartyID	A unique identifier for the party.
PartyIDType	The type of the party ID.
EntityStatus	Status codes (concatenation of primary status, secondary status).
EntityType	Entity Type
EntityIdentifier	Entity Identifier
EntityIdentifierType	Entity Identifier Type

Supported Web Service API Interfaces:

Web Service Method: ProcessQueryStringRequest (REST with QueryString)

Request Format: Url QueryString, Body (x-www-form-urlencoded), Response Formats: JSON, XML*,
Protocols: HTTP GET, HTTPS GET, HTTP POST, HTTPS POST, HTTP OPTIONS, HTTPS OPTIONS
Example Server Path: https://customname.datatoolscloud.net.au/KleberWebService/DtKleberService.svc

Sample QueryString Request:
/ProcessQueryStringRequest?Method=DataTools.Capture.BusinessName.Search.Nzbr.SearchBusinessName&BusinessName=&AuthenticationToken=&TestEnvironment=&EntityStatus=&EntityType=&IndustryCode=&ResultLimit=&RequestId=&RequestKey=&DepartmentCode=

Sample JSON Response:
{
   "DtResponse":{
      "RequestId":"",
      "ResultCount":"1",
      "ErrorMessage":"",
      "Result":[
         {
            "OrganisationName":"",
            "PartyID":"",
            "PartyIDType":"",
            "EntityStatus":"",
            "EntityType":"",
            "EntityIdentifier":"",
            "EntityIdentifierType":""
         }
      ]
   }
}

Sample Code:

Web Service Method: ProcessQueryJsonRequest (REST with JSON)

Request Format: Body (Raw JSON), Response Formats: JSON, XML*,
Protocols: HTTP GET, HTTPS GET, HTTP POST, HTTPS POST, HTTP OPTIONS, HTTPS OPTIONS
Example Server Path: https://customname.datatoolscloud.net.au/KleberWebService/DtKleberService.svc

Single Request

Sample JSON Request:
{
   "DtRequest":{
      "Method":"DataTools.Capture.BusinessName.Search.Nzbr.SearchBusinessName", 
      "BusinessName":"", 
      "AuthenticationToken":"", 
      "TestEnvironment":"", 
      "EntityStatus":"", 
      "EntityType":"", 
      "IndustryCode":"", 
      "ResultLimit":"", 
      "RequestId":"", 
      "RequestKey":"", 
      "DepartmentCode":""
   }
}

Sample JSON Response:
{
   "DtResponse":{
      "RequestId":"",
      "ResultCount":"1",
      "ErrorMessage":"",
      "Result":[
         {
            "OrganisationName":"",
            "PartyID":"",
            "PartyIDType":"",
            "EntityStatus":"",
            "EntityType":"",
            "EntityIdentifier":"",
            "EntityIdentifierType":""
         }
      ]
   }
}

Multiple Requests

Sample JSON Request:
{
   "DtRequests":{
      "DtRequest":[
         {
            "Method":"DataTools.Capture.BusinessName.Search.Nzbr.SearchBusinessName", 
            "BusinessName":"", 
            "AuthenticationToken":"", 
            "TestEnvironment":"", 
            "EntityStatus":"", 
            "EntityType":"", 
            "IndustryCode":"", 
            "ResultLimit":"", 
            "RequestId":"", 
            "RequestKey":"", 
            "DepartmentCode":""
         },
         {
            "Method":"DataTools.Capture.BusinessName.Search.Nzbr.SearchBusinessName", 
            "BusinessName":"", 
            "AuthenticationToken":"", 
            "TestEnvironment":"", 
            "EntityStatus":"", 
            "EntityType":"", 
            "IndustryCode":"", 
            "ResultLimit":"", 
            "RequestId":"", 
            "RequestKey":"", 
            "DepartmentCode":""
         }
      ]
   }
}

Sample JSON Response:
{
   "DtResponses":{
      "ErrorMessage":"",
      "DtResponse":[
         {
            "RequestId":"",
            "ResultCount":"1",
            "ErrorMessage":"",
            "Result":[
               {
                  "OrganisationName":"",
                  "PartyID":"",
                  "PartyIDType":"",
                  "EntityStatus":"",
                  "EntityType":"",
                  "EntityIdentifier":"",
                  "EntityIdentifierType":""
               }
            ]
         },
         {
            "RequestId":"",
            "ResultCount":"1",
            "ErrorMessage":"",
            "Result":[
               {
                  "OrganisationName":"",
                  "PartyID":"",
                  "PartyIDType":"",
                  "EntityStatus":"",
                  "EntityType":"",
                  "EntityIdentifier":"",
                  "EntityIdentifierType":""
               }
            ]
         }
      ]
   }
}

Web Service Method: ProcessQueryXmlRequest (REST with XML)

Request Format: Body (Raw XML), Response Formats: JSON, XML*,
Protocols: HTTP GET, HTTPS GET, HTTP POST, HTTPS POST, HTTP OPTIONS, HTTPS OPTIONS
Example Server Path: https://customname.datatoolscloud.net.au/KleberWebService/DtKleberService.svc

Single Request

Sample XML Request:
<DtRequest Method="DataTools.Capture.BusinessName.Search.Nzbr.SearchBusinessName" BusinessName="" AuthenticationToken="" TestEnvironment="" EntityStatus="" EntityType="" IndustryCode="" ResultLimit="" RequestId="" RequestKey="" DepartmentCode="" />

Sample XML Response:
<DtResponse RequestId="" ResultCount="1" ErrorMessage="">
  <Result OrganisationName="" PartyID="" PartyIDType="" EntityStatus="" EntityType="" EntityIdentifier="" EntityIdentifierType="" />
</DtResponse>

Multiple Requests

Sample XML Request:
<DtRequests>
    <DtRequest Method="DataTools.Capture.BusinessName.Search.Nzbr.SearchBusinessName" BusinessName="" AuthenticationToken="" TestEnvironment="" EntityStatus="" EntityType="" IndustryCode="" ResultLimit="" RequestId="" RequestKey="" DepartmentCode="" />
    <DtRequest Method="DataTools.Capture.BusinessName.Search.Nzbr.SearchBusinessName" BusinessName="" AuthenticationToken="" TestEnvironment="" EntityStatus="" EntityType="" IndustryCode="" ResultLimit="" RequestId="" RequestKey="" DepartmentCode="" />
</DtRequests>

Sample XML Response:
<DtResponses ErrorMessage="">
  <DtResponse RequestId="" ResultCount="1" ErrorMessage="">
    <Result OrganisationName="" PartyID="" PartyIDType="" EntityStatus="" EntityType="" EntityIdentifier="" EntityIdentifierType="" />
  </DtResponse>
  <DtResponse RequestId="" ResultCount="1" ErrorMessage="">
    <Result OrganisationName="" PartyID="" PartyIDType="" EntityStatus="" EntityType="" EntityIdentifier="" EntityIdentifierType="" />
  </DtResponse>
</DtResponses>

Web Service Method: ProcessXmlRequest (SOAP)

Request Format: XML over SOAP, Protocols: HTTP POST, HTTPS POST, Response Formats: XML, JSON*
Example Server Path: https://customname.datatoolscloud.net.au/KleberWebServiceSoap/DtKleberService.svc
SOAP WSDL: https://customname.datatoolscloud.net.au/KleberWebServiceSoap/DtKleberService.svc?wsdl

Sample XML Request:
<DtRequest Method="DataTools.Capture.BusinessName.Search.Nzbr.SearchBusinessName" BusinessName="" AuthenticationToken="" TestEnvironment="" EntityStatus="" EntityType="" IndustryCode="" ResultLimit="" RequestId="" RequestKey="" DepartmentCode="" />

Sample XML Response:
<DtResponse RequestId="" ResultCount="1" ErrorMessage="">
  <Result OrganisationName="" PartyID="" PartyIDType="" EntityStatus="" EntityType="" EntityIdentifier="" EntityIdentifierType="" />
</DtResponse>

SOAP Envelope: The XML request is passed through a single parameter in the SOAP envelope <DtXmlRequest>. Where the development language requires the SOAP envelope contents to be defined manually, the additional step of encoding the Dt XML Request is required. The encoding required needs to transform "<" of the DtRequest to "<" and ">" to ">". See example below.

Sample SOAP Envelope:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
  <soapenv:Header/>
  <soapenv:Body>
    <tem:ProcessXmlRequest>
      <!--Optional:-->
      <tem:DtXmlRequest>
        &lt;DtRequest Method="DataTools.Capture.BusinessName.Search.Nzbr.SearchBusinessName" BusinessName="" AuthenticationToken="" TestEnvironment="" EntityStatus="" EntityType="" IndustryCode="" ResultLimit="" RequestId="" RequestKey="" DepartmentCode="" /&gt;
      </tem:DtXmlRequest>
    </tem:ProcessXmlRequest>
  </soapenv:Body>
</soapenv:Envelope>

Batching Requests: Use the <DtRequests> (plural) tag to send through multiple requests in a single transaction.

<DtRequests>
    <DtRequest Method="DataTools.Capture.BusinessName.Search.Nzbr.SearchBusinessName" BusinessName="" AuthenticationToken="" TestEnvironment="" EntityStatus="" EntityType="" IndustryCode="" ResultLimit="" RequestId="" RequestKey="" DepartmentCode="" />
    <DtRequest Method="DataTools.Capture.BusinessName.Search.Nzbr.SearchBusinessName" BusinessName="" AuthenticationToken="" TestEnvironment="" EntityStatus="" EntityType="" IndustryCode="" ResultLimit="" RequestId="" RequestKey="" DepartmentCode="" />
</DtRequests>

Sample Code:

* Add the additional input parameter "OutputFormat=json" or "OutputFormat=xml" to change the response format from default.
* Add the additional input parameter "callback" to convert JSON responses to JSONP responses for across domains support.
CORS header included where callback is not defined.

Please Note:
Ensure you thoroughly test all the methods you are using and are happy with the results before going into production. DataTools is charged by the data suppliers for use of every method – therefore ALL calls to any method will incur a COST. When you register DataTools provides you with free credit to help with development and trialling of the service. Once that credit is used you will need to purchase a monthly subscription and/or top up to continue using the service, even for development purposes. Please check the Method Pricing List for all current costs. DataTools does not warrant or guarantee the quality of the results returned and will not be held responsible for any costs incurred by using a method. Should you have any questions please contact your Sales representative or the Client Services team.