Loqate Harmony Documentation
  • GBG Loqate AU & NZ
  • Loqate Harmony API
    • Sign up for free trial
    • Login
    • API Specification
      • Authentication
      • Address
        • Address Validation & Lookup
        • Address by Geocode
        • Address Cleanse
        • Address Parse
        • Geocode Intl
      • Address Insights
        • Australian Insights
          • SEIFA Australia
          • ASGS Australia Statistical Geography Standard
          • Residential / Commercial
          • Deliverable address
      • Suburb Lookup
      • Business Validation and Lookup
      • Email Validation
      • Phone Validation
      • Matching
      • Moved Suppression
      • Deceased Suppression
      • Objects
        • Address Objects
        • Address Type Objects
        • Suburb Objects
        • Parse Objects
        • Email Objects
        • Phone Objects
        • Property Title Objects
        • Match Objects
        • Business Objects
      • Deprecated API services
        • Email Validation v1.1
        • Address v1
        • Address Cleanse v1
        • Address International
        • Address Combined
        • Address Types
    • Guides
      • Best Practices
        • Address Field Mappings
        • Finding an Address
      • User Derived Address
      • Expanded sub-premise reach
      • Parcel Locker Plus
      • Migrating to Address V2
      • Sign up/ Login
      • Support
      • Console
        • Getting your API keys
        • Getting Started
        • Add a Service
        • Dashboard
        • Subscriptions
          • Features
          • Users
          • Subscribed Plans
          • Allowlisting domains
          • Blocklist - Email Validation
        • Reports
        • Invoices
          • Paying Invoices
      • API Latency
    • Demos
      • How to use our demos
      • Address Validation Demo
      • Address by Geocode (Reverse Geocode) Demo
      • Address Cleanse Demo
      • Address Parse Demo
      • Business Validation Demo
      • Email Validation Demo
      • Phone Validation demo
    • Integrations
      • Client Libraries
        • Javascript Library v2.1.0
      • Adobe Commerce (Magento 2) Plugin
        • Magento2 User Guide
      • Woocommerce Plugin
        • Woocommerce Install Guide v2.0.0
        • Woocommerce Settings guide v2.0.0
      • Shopify Plus App
      • Gravity Forms
      • Voxco Survey Software
      • Salesforce CRM
      • Dynamics 365 CRM
      • Batch App - Lightweight
      • Deprecated Integrations
        • Harmony RightAddress c# example
        • Harmony RightAddress cURL example
        • Deprecated JS Library v2.0.1
        • Deprecated JQuery Library v1.8.1
    • Coverage
    • Address Exchange (Beta)
      • ADX Console
        • Searching Addresses in console
        • Create Address in console
        • Create Actions in console
      • ADX API Specification
        • Create Address
        • Get Address
        • Create Address Event
        • Edit Address Event
        • Create/Edit Address Attributes
        • Create/Edit Address Geopoint
        • Get Source Events
      • Reserved Attributes
    • GBG Status
  • Batch / Bulk Data Services
    • Serviced Batch
      • Bulk Address Cleanse
      • Email Serviced Batch
      • Phone Serviced Batch
      • Business Serviced Batch
  • Harmony Suite
    • Harmony Suite Overview
    • Release Notes
      • Version 3.0.0
        • New Features
        • Enhancements
        • Bug Fixes
        • Supported Platforms
    • User Guides
      • Version 3.0.0
        • Welcome to Harmony Suite
        • Glossary of terms
        • Upgrades
          • HSQL Upgrade
        • Email and Phone Validation
          • Prerequisites
          • Phone and Email PDP Configuration Setup
          • Phone Validation using Harmony Batch System
          • Phone Validation using Harmony WS
          • Email Validation using Harmony Batch
          • Email Validation using Harmony WS
          • Guides
            • Understanding Phone Data
            • Understanding Email Data
        • Business Lookup and Validation
          • Prerequisites
          • Business Lookup
          • Business Validation
            • Business Validation using Commercial Name Parser
            • Business Validation Configurations
            • Business Validation using Harmony Batch System
            • Business Validation using Harmony WS
          • Business data update guide
          • Guides
            • Understanding Business Data
            • Understanding Business Verification Code
            • Name Parse Ambiguity
        • Australia Post Parcel Locker Plus Lookup and Validation
          • Prerequisites
          • Australia Post Parcel Locker Plus Lookup
          • Australia Post Parcel Locker Plus Validation
            • PDP Configuration Setup
            • AupostValidation using Harmony Batch System
            • AupostValidation using Harmony WS
          • Guides
            • Knowledgebase Lexical Update
            • Understanding Australia Post Parcel Locker Plus Data
            • Interchangeable terms for Australia Post Parcel Lockers
        • Installation and Upgrade Reference Guide
        • Locate Reference Guide
        • Extensions Reference Guide
        • RealTime Reference Guide
        • Postmaster Reference Guide
        • Rapid Address ANZ Reference Guide
        • Post ANZ Reference Guide
        • Source of Truth Installation Reference Guide
        • Knowledgebase Configuration Reference Guide
        • Web Services Reference Guide
        • Management Console Reference Guide
        • Batch System Match Reference Guide
        • Batch System Cleanse Reference Guide
  • More from GBG
    • GBG GreenID
    • GBG Identity
    • GBG Fraud & Compliance
Powered by GitBook
On this page
  1. Loqate Harmony API
  2. API Specification

Business Validation and Lookup

Business lookup methods take partial or complete business information to search against the business Source of Truth, returning validated and enriched business information.

PreviousSuburb LookupNextEmail Validation

Last updated 1 year ago

To complete business validation requires using 2 API's each provide a specific purpose.

  1. - Returns a list of valid business based on partial or complete business information.

  2. - Uses the Id value from Find API or clear text business/company number to return the validated and enriched business information available for each country.

Supported Countries: Australia, New Zealand

Find

Lookup businesses using a partial or complete business information in a single line business field.

The name to be searched can be a business number, company or any entity names.

HTTP POST will only process the first record in the request.

Resource

GET/POST    https://hosted.mastersoftgroup.com/business/v1/find

Request

required field*

Name
Type
Example
Description

country*

string

AU

ISO 2 country AU or NZ

name*

string

"gbg aust"

partial business name being searched

nameTypes

string

"TRD,BN,OTN"

Filters for specific or multiple Entity types depending on country.

Australia

MN-->Main Entity name;

LGL-->Legal Entity Name (individuals/sole traders). Use with MN;

TRD-->Trading name in Other Entity;

BN-->Business name in Other Entity; DGR-->Deductible Gift Recipient;

OTN-->Other name in Other Entity.

New Zealand

MN-->Main Entity name;

TRD-->Trading name in Other Entity;

OTN-->Other name in Other Entity.

bnStatus

string

"ACT" default blank

Filters based on business number status. Options ACT = Active, CAN = Cancelled

taxStatus

string

"ACT" default blank

Filters based on business tax status. Options ACT = Active, CAN = Cancelled, NON = None

State

string

"NSW, QLD" default blank

Filters for specific or multiple states the business is located. Blank is all.

hits

integer

5 default 20

Number of results to be returned from the Find response.

caseType

string

"TITLE" default UP

The case type for the returned information UP,LOW,TITLE

Response

Response will be a combination of Main Entity name, Trading Name and Business names etc.

Examples

Request 1: Lookup for active business names from multiple states

{
  "name": "Mastersoft", 
  "country": "au",
  "bnStatus":"ACT", 
  "state": [
    "NSW","VIC"
  ],  
  "caseType": "TITLE"
}

Response 1: Please note that the records with the same id pertains to same business. For e.g. Mastersoft Pty. Ltd. is the Main entity name while Mastersoft Pty Ltd is the Trading Name

{
    "status": "SUCCESS",
    "messages": [],
    "payload": [
        {
            "name": "Mastersoft Superannuation Fund",
            "bn": "xxxxx2590",
            "postcode": "3006",
            "id": "UosAkx9hhtTIwxWz7n3Dng=="
        },
        {
            "name": "Mastersoft Superannuation Fund",
            "bn": "xxxxx2590",
            "postcode": "3006",
            "id": "UosAkx9hhtTIwxWz7n3Dng=="
        },
        {
            "name": "Mastersoft Pty. Ltd.",
            "bn": "xxxxx2029",
            "postcode": "3144",
            "id": "66qwO7IwxUgfyh4m3GoeIg=="
        },
        {
            "name": "Mastersoft Pty Ltd",
            "bn": "xxxxx2029",
            "postcode": "3144",
            "id": "66qwO7IwxUgfyh4m3GoeIg=="
        },
        {
            "name": "Mastersoft Group Pty Ltd",
            "bn": "xxxxx5800",
            "postcode": "2000",
            "id": "zwrNW9AAywaVsPbJmqhByg=="
        }
    ]
}

Request 2: Lookup for active business names against Main Entity names

{
  "name": "Mastersoft", 
  "country": "au",
  "bnStatus":"ACT",
  "nameTypes":["MN"],
   "state": [
    "NSW","VIC"
  ],  
  "caseType": "TITLE"
}

Response 2:

{
    "status": "SUCCESS",
    "messages": [],
    "payload": [
        {
            "name": "Mastersoft Superannuation Fund",
            "bn": "xxxxx2590",
            "postcode": "3006",
            "id": "UosAkx9hhtTIwxWz7n3Dng=="
        },
        {
            "name": "Mastersoft Pty. Ltd.",
            "bn": "xxxxx2029",
            "postcode": "3144",
            "id": "66qwO7IwxUgfyh4m3GoeIg=="
        },
        {
            "name": "Mastersoft Group Pty Ltd",
            "bn": "xxxxx5800",
            "postcode": "2000",
            "id": "zwrNW9AAywaVsPbJmqhByg=="
        }
    ]
}

Request 3: Lookup for active business names with cancelled tax status

{
  "name": "Mastersoft", 
  "country": "au",
  "bnStatus":"ACT",
  "nameTypes":["MN"],
  "taxStatus":"CAN",
   "state": [
    "NSW","VIC"
  ],  
  "caseType": "UP"
}

Response 3:

{
    "status": "SUCCESS",
    "messages": [],
    "payload": [
        {
            "name": "MASTERSOFT PTY. LTD.",
            "bn": "xxxxx2029",
            "postcode": "3144",
            "id": "66qwO7IwxUgfyh4m3GoeIg=="
        }
    ]
}

Request 4: Lookup business name using ABN number

{
  "name": "15 007 342 029", 
  "country": "au"  
  
}

Response 4:

{
    "status": "SUCCESS",
    "messages": [],
    "payload": [
        {
            "name": "MASTERSOFT PTY. LTD.",
            "bn": "xxxxx2029",
            "postcode": "3144",
            "id": "66qwO7IwxUgfyh4m3GoeIg=="
        }
    ]
}

Retrieve

Retrieves the validated and enriched business information for the supplied Id value from Find API or clear text business or company number.

Resource

GET/POST    https://hosted.mastersoftgroup.com/business/v1/retrieve

Request

required fields*

Name
Type
Example
Description

country*

string

"AU"

ISO-2 country AU or NZ

name*

string

"Ebu2PZ/Xdr3wef9MilFasw=="

Id value from Find API response OR clear text business OR clear text company number.

caseType

string

"LOW"

Case Type of text returned in the response.

selectedName

string

"AUGUSTA 4WD"

The 'selectedName' parameter utilized in the 'retrieve' request is used to assign either the business name or trading name to the 'display_name' field within the response payload. For instance, in the context of the 'Find' API, the name chosen by the user might not necessarily represent the primary entity name, it could be a trading name or business name etc.

When invoking the 'retrieve' request, users can pass on this 'selectedName,' resulting in the 'display_name' being rendered as 'main entity name trading as BN/main entity name trading as TRD'.

When 'selectedName' is not used in the retrieve request,' 'display_name' and 'name' both represent main entity name.

Response

Examples

Request 1: Retrieve the validated business information using the Id from Find API.

{
  "name": "Ebu2PZ/Xdr3wef9MilFasw==", 
  "country": "au"
  
}

Response 1:

```json
{
    "status": "SUCCESS",
    "messages": [],
    "payload": [
        {
            "display_name": "Augusta Auto Mart Pty Ltd",
            "name": "Augusta Auto Mart Pty Ltd",
            "bn": "31103593666",
            "cn": "103593666",
            "state": "SA",
            "postcode": "5700",
            "country": "au",
            "bn_status": "ACT",
            "bn_status_from_date": "20030205",
            "tax_status": "ACT",
            "tax_status_from_date": "20030210",
            "entity_type_ind": "PRV",
            "entity_type_text": "Australian Private Company",
            "other_entities": [
                {
                    "entity_name": "Augusta Auto Mart",
                    "entity_type": "TRD"
                },
                {
                    "entity_name": "Port Augusta Windscreens And Radiators",
                    "entity_type": "OTN"
                },
                {
                    "entity_name": "Augusta 4wd",
                    "entity_type": "BN"
                },
                {
                    "entity_name": "Augusta 4x4",
                    "entity_type": "BN"
                },
                {
                    "entity_name": "Auto One Port Augusta",
                    "entity_type": "BN"
                },
                {
                    "entity_name": "Drop Bear 4x4 & Leisure",
                    "entity_type": "BN"
                }
            ],
            "attributes": {
                "month_as_tax_business": "239",
                "month_in_business": "239"
            },
            "last_updated_date": "20200214"
        }
    ]
}

Request 2: Retrieve the validated business information using Australian business number.

{
  "name": "91151055800", 
  "country": "au",
  "caseType": "TITLE"  
}

Response 2:

{
    "status": "SUCCESS",
    "messages": [],
    "payload": [
        {
            "display_name": "Mastersoft Group Pty Ltd",
            "name": "Mastersoft Group Pty Ltd",
            "bn": "91151055800",
            "cn": "151055800",
            "state": "NSW",
            "postcode": "2000",
            "country": "au",
            "bn_status": "ACT",
            "bn_status_from_date": "20110523",
            "tax_status": "ACT",
            "tax_status_from_date": "20110523",
            "entity_type_ind": "PRV",
            "entity_type_text": "Australian Private Company",
            "attributes": {
                "month_as_tax_business": "140",
                "month_in_business": "140"
            },
            "last_updated_date": "20200214"
        }
    ]
}
```

Request 3: Retrieve request using 'selectedName' as Business Name. Sample for Australia.

{
  "name": "31103593666", 
  "country": "au",
  "selectedName":"Augusta 4WD"
}

Response 3:

{
    "status": "SUCCESS",
    "messages": [],
    "payload": [
        {
            "display_name": "AUGUSTA AUTO MART PTY LTD Trading As AUGUSTA 4WD",
            "name": "AUGUSTA AUTO MART PTY LTD",
            "bn": "31103593666",
            "cn": "103593666",
            "state": "SA",
            "postcode": "5700",
            "country": "au",
            "bn_status": "ACT",
            "bn_status_from_date": "20030205",
            "tax_status": "ACT",
            "tax_status_from_date": "20030210",
            "entity_type_ind": "PRV",
            "entity_type_text": "Australian Private Company",
            "other_entities": [
                {
                    "entity_name": "AUGUSTA AUTO MART",
                    "entity_type": "TRD"
                },
                {
                    "entity_name": "PORT AUGUSTA WINDSCREENS AND RADIATORS",
                    "entity_type": "OTN"
                },
                {
                    "entity_name": "AUGUSTA 4WD",
                    "entity_type": "BN"
                },
                {
                    "entity_name": "Augusta 4x4",
                    "entity_type": "BN"
                },
                {
                    "entity_name": "Auto One Port Augusta",
                    "entity_type": "BN"
                },
                {
                    "entity_name": "Drop Bear 4x4 & Leisure",
                    "entity_type": "BN"
                }
            ],
            "attributes": {
                "month_as_tax_business": "253",
                "month_in_business": "253"
            },
            "last_updated_date": "20200214"
        }
    ]
}

Request 4: Retrieve the validated business information using NewZealand business number.

{
  "name": "9429034884508", 
  "country": "nz",
  "caseType": "TITLE"  
}

Response 4:

{
    "status": "SUCCESS",
    "messages": [],
    "payload": [
        {
            "display_name": "Mastersoft (nz) Limited",
            "name": "Mastersoft (nz) Limited",
            "bn": "9429034884508",
            "cn": "1611874",
            "postcode": "6011",
            "country": "nz",
            "bn_status": "ACT",
            "bn_status_from_date": "2005-03-21T00:00:00",
            "entity_type_ind": "LTD",
            "entity_type_text": "NZ Limited Company",
            "other_entities": [
                {
                    "entity_name": "Gpic Investments Limited",
                    "entity_type": "OTN",
                    "start_date": "2005-03-21T00:00:00",
                    "end_date": "2011-06-13T15:59:46"
                }
            ],
            "addresses": [
                {
                    "type": "PhysicalAddress",
                    "fullAddress": "Moore Markhams Wellington Limited, Level 11 Aia Tower, 34-42 Manners Street, Wellington",
                    "postcode": "6011",
                    "country": "NZ",
                    "start_date": "2021-02-03T00:00:00"
                },
                {
                    "type": "PhysicalAddress",
                    "fullAddress": "Moore Stephens Markhams Wellington Limited, Level 11 Sovereign House, 34-42 Manners Street, Wellington",
                    "postcode": "6011",
                    "country": "NZ",
                    "start_date": "2014-02-25T00:00:00",
                    "end_date": "2021-02-03T00:00:00"
                },
                {
                    "type": "PhysicalAddress",
                    "fullAddress": "97 The Terrace, Wellington",
                    "country": "NZ",
                    "start_date": "2005-03-21T00:00:00",
                    "end_date": "2011-08-30T00:00:00"
                },
                {
                    "type": "PhysicalAddress",
                    "fullAddress": "Level 11 Sovereign House, 34-42 Manners Street, Wellington",
                    "postcode": "6140",
                    "country": "NZ",
                    "start_date": "2011-08-30T00:00:00",
                    "end_date": "2014-02-25T00:00:00"
                },
                {
                    "type": "RegisteredAddress",
                    "fullAddress": "Level 11 Sovereign House, 34-42 Manners Street, Wellington",
                    "postcode": "6140",
                    "country": "NZ",
                    "start_date": "2011-08-30T00:00:00",
                    "end_date": "2014-02-25T00:00:00"
                },
                {
                    "type": "RegisteredAddress",
                    "fullAddress": "Moore Markhams Wellington Limited, Level 11 Aia Tower, 34-42 Manners Street, Wellington",
                    "postcode": "6011",
                    "country": "NZ",
                    "start_date": "2019-10-01T12:00:00"
                },
                {
                    "type": "RegisteredAddress",
                    "fullAddress": "97 The Terrace, Wellington",
                    "country": "NZ",
                    "start_date": "2005-03-21T00:00:00",
                    "end_date": "2011-08-30T00:00:00"
                },
                {
                    "type": "RegisteredAddress",
                    "fullAddress": "Moore Stephens Markhams Wellington Limited, Level 11 Sovereign House, 34-42 Manners Street, Wellington",
                    "postcode": "6011",
                    "country": "NZ",
                    "start_date": "2014-02-25T00:00:00",
                    "end_date": "2019-10-01T12:00:00"
                }
            ],
            "directors": [
                {
                    "asicDirectorshipYn": "false",
                    "endDate": "2011-06-15T00:00:00",
                    "roleAddress": [],
                    "roleAsicAddress": [],
                    "rolePerson": [
                        {
                            "firstName": "David",
                            "lastName": "SHILLSON",
                            "middleNames": "Peter"
                        }
                    ],
                    "roleStatus": "INACTIVE",
                    "roleType": "Director",
                    "startDate": "2005-03-21T00:00:00"
                },
                {
                    "asicDirectorshipYn": "false",
                    "endDate": "2015-07-01T00:00:00",
                    "roleAddress": [],
                    "roleAsicAddress": [],
                    "rolePerson": [
                        {
                            "firstName": "John",
                            "lastName": "PATERSON",
                            "middleNames": "Trevett"
                        }
                    ],
                    "roleStatus": "INACTIVE",
                    "roleType": "Director",
                    "startDate": "2011-06-15T00:00:00"
                },
                {
                    "acn": "151055800",
                    "asicDirectorshipYn": "true",
                    "asicName": "MASTERSOFT GROUP PTY LTD",
                    "roleAddress": [],
                    "roleAsicAddress": [],
                    "rolePerson": [
                        {
                            "firstName": "Blair",
                            "lastName": "LUCAS",
                            "middleNames": "Andrew"
                        }
                    ],
                    "roleStatus": "ACTIVE",
                    "roleType": "Director",
                    "startDate": "2018-10-22T00:00:00"
                },
                {
                    "asicDirectorshipYn": "false",
                    "roleAddress": [],
                    "roleAsicAddress": [],
                    "rolePerson": [
                        {
                            "firstName": "David",
                            "lastName": "WARD",
                            "middleNames": "Mathew"
                        }
                    ],
                    "roleStatus": "ACTIVE",
                    "roleType": "Director",
                    "startDate": "2021-07-01T00:00:00"
                },
                {
                    "asicDirectorshipYn": "false",
                    "endDate": "2021-06-30T00:00:00",
                    "roleAddress": [],
                    "roleAsicAddress": [],
                    "rolePerson": [
                        {
                            "firstName": "David",
                            "lastName": "WILSON",
                            "middleNames": "John"
                        }
                    ],
                    "roleStatus": "INACTIVE",
                    "roleType": "Director",
                    "startDate": "2018-10-22T00:00:00"
                },
                {
                    "acn": "151055800",
                    "asicDirectorshipYn": "true",
                    "asicName": "MASTERSOFT GROUP PTY LTD",
                    "endDate": "2018-10-22T00:00:00",
                    "roleAddress": [],
                    "roleAsicAddress": [],
                    "rolePerson": [
                        {
                            "firstName": "James",
                            "lastName": "SMITH",
                            "middleNames": "Norman"
                        }
                    ],
                    "roleStatus": "INACTIVE",
                    "roleType": "Director",
                    "startDate": "2015-07-01T00:00:00"
                },
                {
                    "asicDirectorshipYn": "false",
                    "roleAddress": [],
                    "roleAsicAddress": [],
                    "rolePerson": [
                        {
                            "firstName": "Christopher",
                            "lastName": "CLARK",
                            "middleNames": "Graham"
                        }
                    ],
                    "roleStatus": "ACTIVE",
                    "roleType": "Director",
                    "startDate": "2018-10-22T00:00:00"
                },
                {
                    "asicDirectorshipYn": "false",
                    "roleAddress": [],
                    "roleAsicAddress": [],
                    "rolePerson": [
                        {
                            "firstName": "Nicholas",
                            "lastName": "BROWN",
                            "middleNames": "Richard"
                        }
                    ],
                    "roleStatus": "ACTIVE",
                    "roleType": "Director",
                    "startDate": "2018-10-22T00:00:00"
                },
                {
                    "acn": "151055800",
                    "asicDirectorshipYn": "true",
                    "asicName": "MASTERSOFT GROUP PTY LTD",
                    "endDate": "2018-10-22T00:00:00",
                    "roleAddress": [],
                    "roleAsicAddress": [],
                    "rolePerson": [
                        {
                            "firstName": "Allan",
                            "lastName": "SULLIVAN",
                            "middleNames": "Clive"
                        }
                    ],
                    "roleStatus": "INACTIVE",
                    "roleType": "Director",
                    "startDate": "2011-06-15T00:00:00"
                }
            ],
            "info": {
                "annualReturnFilingMonth": "2",
                "annualReturnLastFiled": "2022-02-21T12:18:32",
                "extensiveShareholding": "false",
                "financialReportFilingMonth": "6",
                "hasConstitutionFiled": "true",
                "overseasCompany": "false",
                "shareholding": [
                    {
                        "numberOfShares": "100",
                        "shareAllocation": [
                            {
                                "allocation": "100",
                                "shareholder": [
                                    {
                                        "appointmentDate": "2011-06-17T16:01:40",
                                        "individualShareholder": [],
                                        "otherShareholder": [
                                            {
                                                "companyNumber": "2415211",
                                                "currentEntityName": "Mastersoft Group Pty Limited"
                                            }
                                        ],
                                        "shareholderAddress": [
                                            {
                                                "address1": "58 Gipps Street",
                                                "address3": "Collingwood Vic",
                                                "countryCode": "AU"
                                            }
                                        ],
                                        "type": "other"
                                    }
                                ]
                            }
                        ]
                    }
                ]
            },
            "attributes": {
                "bn_start_date": "2005-03-21T00:00:00",
                "detailed_bn_status": "50 (Registered)",
                "month_in_business": "214",
                "registration_date": "2005-03-21T00:00:00"
            },
            "last_updated_date": "2021-08-05T15:12:09"
        }
    ]
}

Request 5: Retrieve request using 'selectedName' as Trading Name. Sample for NewZealand.

{
  "name": "9429032232776", 
  "country": "nz",
  "selectedName":"shelkam engineering ltd",
 "caseType":"TITLE"
}

Response 5:

{
    "status": "SUCCESS",
    "messages": [],
    "payload": [
        {
            "display_name": "Shelkam Engineering Limited Trading As Shelkam Engineering Ltd",
            "name": "Shelkam Engineering Limited",
            "bn": "9429032232776",
            "cn": "2248146",
            "postcode": "0992",
            "country": "nz",
            "bn_status": "ACT",
            "bn_status_from_date": "2009-05-25T00:00:00",
            "entity_type_ind": "LTD",
            "entity_type_text": "NZ Limited Company",
            "other_entities": [
                {
                    "entity_name": "Shelkam Engineering Ltd",
                    "entity_type": "TRD"
                }
            ],
            "addresses": [
                {
                    "type": "PhysicalAddress",
                    "fullAddress": "227 A Wairau Road, Wairau Valley, Auckland",
                    "postcode": "0672",
                    "country": "NZ",
                    "start_date": "2009-05-25T00:00:00",
                    "end_date": "2016-05-04T00:00:00"
                },
                {
                    "type": "PhysicalAddress",
                    "fullAddress": "137 Young Access, Rd 2, Silverdale",
                    "postcode": "0992",
                    "country": "NZ",
                    "start_date": "2016-05-04T00:00:00"
                },
                {
                    "type": "RegisteredAddress",
                    "fullAddress": "137 Young Access, Rd 2, Silverdale",
                    "postcode": "0992",
                    "country": "NZ",
                    "start_date": "2016-05-04T00:00:00"
                },
                {
                    "type": "RegisteredAddress",
                    "fullAddress": "227 A Wairau Road, Wairau Valley, Auckland",
                    "postcode": "0672",
                    "country": "NZ",
                    "start_date": "2009-05-25T00:00:00",
                    "end_date": "2016-05-04T00:00:00"
                }
            ],
            "directors": [
                {
                    "asicDirectorshipYn": "false",
                    "roleAddress": [],
                    "roleAsicAddress": [],
                    "rolePerson": [
                        {
                            "firstName": "Mohanan",
                            "lastName": "NAIR",
                            "middleNames": "Gopalakrishnan"
                        }
                    ],
                    "roleStatus": "ACTIVE",
                    "roleType": "Director",
                    "startDate": "2009-05-25T00:00:00"
                },
                {
                    "asicDirectorshipYn": "false",
                    "roleAddress": [],
                    "roleAsicAddress": [],
                    "rolePerson": [
                        {
                            "firstName": "Sheela",
                            "lastName": "NAIR",
                            "middleNames": "Mohanan"
                        }
                    ],
                    "roleStatus": "ACTIVE",
                    "roleType": "Director",
                    "startDate": "2009-05-25T00:00:00"
                }
            ],
            "info": {
                "annualReturnFilingMonth": "6",
                "annualReturnLastFiled": "2023-06-02T05:53:59",
                "extensiveShareholding": "false",
                "hasConstitutionFiled": "false",
                "overseasCompany": "false",
                "shareholding": [
                    {
                        "numberOfShares": "100",
                        "shareAllocation": [
                            {
                                "allocation": "50",
                                "shareholder": [
                                    {
                                        "appointmentDate": "2009-05-25T00:00:00",
                                        "individualShareholder": [
                                            {
                                                "firstName": "Mohanan",
                                                "fullName": "Mohanan Gopalakrishnan NAIR",
                                                "lastName": "NAIR",
                                                "middleNames": "Gopalakrishnan"
                                            }
                                        ],
                                        "otherShareholder": [],
                                        "shareholderAddress": [],
                                        "type": "individual"
                                    }
                                ]
                            },
                            {
                                "allocation": "50",
                                "shareholder": [
                                    {
                                        "appointmentDate": "2009-05-25T00:00:00",
                                        "individualShareholder": [
                                            {
                                                "firstName": "Sheela",
                                                "fullName": "Sheela Mohanan NAIR",
                                                "lastName": "NAIR",
                                                "middleNames": "Mohanan"
                                            }
                                        ],
                                        "otherShareholder": [],
                                        "shareholderAddress": [],
                                        "type": "individual"
                                    }
                                ]
                            }
                        ]
                    }
                ]
            },
            "attributes": {
                "bn_start_date": "2009-05-25T00:00:00",
                "detailed_bn_status": "50 (Registered)",
                "month_in_business": "178",
                "registration_date": "2009-05-25T00:00:00"
            },
            "last_updated_date": "2022-07-05T20:52:46"
        }
    ]
}

The request body is a object:

The response body is a object.

The request body is a object.

The response body is a object.

Find
Retrieve
BusinessRestRequest
BusinessRestResponse
BusinessRestRequest
BusinessRestResponse
get
Authorizations
Query parameters
countrystring · enumRequired

Country ISO2 code

Possible values:
namestringRequired

The name to be searched, it can be business number, company or any entity names

nameTypesstringOptional

Enity types want to search from, default will search ALL. It accepts multiple types seperated by comma e.g. MN,. MN → Main Entity Name; LGL → legal Entity Name, not applicable for NZ; TRD → trading name; BN → business name, not applicable for NZ; OTN → other name in Other Entity for AU and previous name for NZ; DGR → DGR name, not applicable for NZ. e.g. TRD, OTN -> search against trading names and other name

bnStatusstringOptional

business number status want to search, default will be empty which will search ALL. e.g For AU, ACT -> Active, CAN -> Cancelled.

taxStatusstringOptional

tax/gst status want to search, default will be empty which will search ALL. It is not applicable for NZ. e.g. for AU ACT -> Active, CAN -> Cancelled, NON -> None, not applicable for NZ

detailedBnStatusstringOptional

Detailed busines entity status codes, default will search ALL, 80-Removed, 50-Registered, 60-In Liquidation, 71-In Receivership & In Liquidation, 62-Removed & In Liquidation, 70-In Receivership, 61-In Liquidation and Receivership, 55-Voluntary Administration, 72-In Statutory Management, 91-Closed. e.g. 80,91 -> search for status removed and closed. Currently only supported for NZ

statestringOptional

The state of the entity for searching, default will search ALL, not applicable for NZ. It accept multiple states. e.g. NSW,QLD -> search against NSW and QLD entities

hitsstringOptional

The maximum number of results returned from the lookup. If empty default will be 20

caseTypestring · enumOptional

Case type for entity name, default is whatever the case in the reference data

Possible values:
Responses
200
OK
application/json
400
Bad Request
*/*
401
Unauthorized
*/*
403
Forbidden
*/*
500
Internal Server Error
*/*
get
GET /business/v1/find HTTP/1.1
Host: hosted.mastersoftgroup.com
Authorization: Basic username:password
Accept: */*
{
  "status": "SUCCESS",
  "messages": [
    "text"
  ],
  "payload": [
    {
      "id": "text",
      "name": "text",
      "bn": "text",
      "postcode": "text",
      "country": "text",
      "name_entity_type": "text",
      "cn": "text",
      "state": "text"
    }
  ]
}
  • Find
  • GET/v1/find
  • POST/v1/find
  • Resource
  • Request
  • Response
  • Examples
  • Retrieve
  • POST/v1/retrieve
  • Resource
  • Request
  • Response
  • Examples
post
Authorizations
Body
namestringOptional
hitsinteger · int32Optional
countrystringOptional
taxStatusstringOptional
bnStatusstringOptional
detailedBnStatusstring[]Optional
nameTypesstring[]Optional
statestring[]Optional
caseTypestring · enumOptionalPossible values:
selectedNamestringOptional
Responses
200
OK
application/json
400
Bad Request
*/*
401
Unauthorized
*/*
403
Forbidden
*/*
500
Internal Server Error
*/*
post
POST /business/v1/find HTTP/1.1
Host: hosted.mastersoftgroup.com
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 42

{
  "name": "name, abn or acn",
  "country": "au"
}
{
  "status": "SUCCESS",
  "messages": [
    "text"
  ],
  "payload": [
    {
      "id": "text",
      "name": "text",
      "bn": "text",
      "postcode": "text",
      "country": "text",
      "name_entity_type": "text",
      "cn": "text",
      "state": "text"
    }
  ]
}
post
Authorizations
Body
namestringOptional
hitsinteger · int32Optional
countrystringOptional
taxStatusstringOptional
bnStatusstringOptional
detailedBnStatusstring[]Optional
nameTypesstring[]Optional
statestring[]Optional
caseTypestring · enumOptionalPossible values:
selectedNamestringOptional
Responses
200
OK
application/json
400
Bad Request
*/*
401
Unauthorized
*/*
403
Forbidden
*/*
500
Internal Server Error
*/*
post
POST /business/v1/retrieve HTTP/1.1
Host: hosted.mastersoftgroup.com
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "name": "id from find e.g. 66qwO7IwxUgfyh4m3GoeIg",
  "country": "au",
  "caseType": "UP"
}
{
  "status": "SUCCESS",
  "messages": [
    "text"
  ],
  "payload": [
    {
      "display_name": "text",
      "name": "text",
      "bn": "text",
      "cn": "text",
      "state": "text",
      "postcode": "text",
      "country": "text",
      "bn_status": "text",
      "bn_status_from_date": "text",
      "tax_status": "text",
      "tax_status_from_date": "text",
      "entity_type_ind": "text",
      "entity_type_text": "text",
      "other_entities": [
        {
          "entity_name": "text",
          "entity_type": "text",
          "start_date": "text",
          "end_date": "text"
        }
      ],
      "classifications": [
        {
          "type": "text",
          "attributes": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ],
      "addresses": [
        {
          "type": "text",
          "fullAddress": "text",
          "postcode": "text",
          "country": "text",
          "id": "text",
          "start_date": "text",
          "end_date": "text",
          "attributes": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ],
      "digital_presence": [
        {
          "type": "text",
          "url": "text",
          "start_date": "text"
        }
      ],
      "phones": [
        {
          "phoneAreaCode": "text",
          "phoneCountryCode": "text",
          "phoneNumber": "text",
          "phonePurpose": "text",
          "phonePurposeDescription": {},
          "startDate": "text",
          "uniqueIdentifier": "text"
        }
      ],
      "directors": [
        {
          "acn": {},
          "asicDirectorshipYn": "text",
          "asicName": {},
          "endDate": {},
          "roleAddress": [
            {}
          ],
          "roleAsicAddress": [
            {}
          ],
          "roleEntity": {},
          "rolePerson": [
            {
              "firstName": "text",
              "lastName": "text",
              "middleNames": "text",
              "title": {}
            }
          ],
          "roleStatus": "text",
          "roleType": "text",
          "startDate": "text",
          "uniqueIdentifier": {}
        }
      ],
      "info": {
        "annualReturnFilingMonth": "text",
        "annualReturnLastFiled": "text",
        "countryOfOrigin": {},
        "extensiveShareholding": "text",
        "financialReportFilingMonth": {},
        "hasConstitutionFiled": "text",
        "nzsxCode": {},
        "overseasCompany": "text",
        "shareholding": [
          {
            "numberOfShares": "text",
            "shareAllocation": [
              {
                "allocation": "text",
                "shareholder": [
                  {
                    "appointmentDate": "text",
                    "individualShareholder": [
                      {}
                    ],
                    "otherShareholder": [
                      {
                        "companyNumber": "text",
                        "currentEntityName": "text",
                        "entityType": "text",
                        "nzbn": "text"
                      }
                    ],
                    "shareholderAddress": [
                      {
                        "address1": "text",
                        "address2": "text",
                        "address3": "text",
                        "address4": {},
                        "careOf": "text",
                        "countryCode": "text",
                        "endDate": {},
                        "pafId": "text",
                        "postCode": "text",
                        "startDate": "text",
                        "uniqueIdentifier": {}
                      }
                    ],
                    "type": "text",
                    "vacationDate": {}
                  }
                ]
              }
            ]
          }
        ],
        "stockExchangeListed": {}
      },
      "attributes": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "last_updated_date": "text"
    }
  ]
}