Comment on page
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.
To complete business validation requires using 2 API's each provide a specific purpose.
1.​Find - Returns a list of valid business based on partial or complete business information.
2.​Retrieve - 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.
get
https://hosted.mastersoftgroup.com/business
/v1/find
post
https://hosted.mastersoftgroup.com/business
/v1/find
Resource 
GET/POST    https://hosted.mastersoftgroup.com/business/v1/find
Request
The request body is a BusinessRestRequest object:
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
The response body is a BusinessRestResponse object.
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.
get
https://hosted.mastersoftgroup.com/business
/v1/retrieve
post
https://hosted.mastersoftgroup.com/business
/v1/retrieve
Resource
GET/POST    https://hosted.mastersoftgroup.com/business/v1/retrieve
Request
The request body is a BusinessRestRequest object.
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
Response
The response body is a BusinessRestResponse object.
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 the clear text 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 the validated business information using the clear text NZ.
{
  "name": "9429034884508", 
  "country": "nz",
  "caseType": "TITLE"  
}
Response 3:
{
    "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"
        }
    ]
}
​
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
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
Suburb Lookup
Email Validation
Last modified 1mo ago
Business Validation and Lookup

Find

Resource

Request

Response

Examples

Retrieve

Resource

Request

Response

Examples

​
