Entity lookup (PREVIEW)

Note

This endpoint is currently in preview and is subject to breaking changes. It is based on a different request format from the rest of the bronID API.

Authentication

Read the authentication guide at API Authentication (PREVIEW)

Request format

Method

GET

Parameters

Name	Type	Description
`country` (required)	string	3 letter country ISO
`id` (required)	string	The unique identifier of the entity to look up. This is a identifier that is specific to the country. For example, in Australia, this would be an ABN or ACN, in New Zealand it would be a NZBN.

Response

The response is a JSON object.

Name	Type	Description
`match`	boolean	Indicates if the entity was found.
`country`	string	3 letter country ISO
`name`	string	The main name of the entity.
`names`	array	An array of objects containing the different names the entity is known by.
`entityNumber`	string	The main entity number of the entity found based on the lookup.
`entityNumbers`	array	An array of objects containing the different entity numbers (ABN, ACN, NZBN etc.) the entity is known by. These are dependent on the country.
`entityStatus`	string	Text description of the entity status as found in the registry.
`entityType`	string	Text description of the bronID entity type. See entity types
`entityTypeCode`	string	The value of the entity type as it should be submitted to bronID verifications. See entity types
`address`	object or null	The address of the entity.

Names array

The names array contains the different names the entity is known by.

Name	Type	Options	Description
`value`	string		The name of the entity.
`type`	string	businessName, tradingName, formerName	The type of the name.

Entity numbers array

The entity numbers array contains the different entity numbers the entity is known by.

Name	Type	Options	Description
`value`	string		The entity number.
`type`	string	ABN, ACN, NZBN, etc.	The type of the entity number. The options are dependent on the country.

Address object

The address object contains the address of the entity.

Name	Type	Description
`text`	string or null	The address of the entity as a single line of text.
`state`	string or null	The state of the address.
`postcode`	string or null	The postcode of the address.

API call

GET

/v5/lookup

// api endpoint
const apiEndpoint = 'https://dev.bronid.com/v5/lookup';
// lookup parameters
const queryParams = {
	country: 'AUS',
	id: '33051775556',
};

// Convert the query parameters to a query string
const queryString = new URLSearchParams(queryParams).toString();
// add the query string with a "?" prefix e.g. ?country=AUS&id=33051775556
const urlWithQuery = `${apiEndpoint}?${queryString}`;

// API authentication
const headers = {
	Authorization: 'ApiKey XL7ULiU6B4QE9Y2iWFZnhtMDKFN2:api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314',
};

// Perform the fetch request
fetch(urlWithQuery, {
	method: 'GET',
	headers: headers,
})
	.then(response => {
		if (!response.ok) {
			throw new Error(`HTTP error! Status: ${response.status}`);
		}

		return response.json(); // Parse JSON response
	})
	.then(data => {
		console.log('Response data:', data);
	})
	.catch(error => {
		console.error('Fetch error:', error);
	});

Sample response (matched):

HTTP Status 200

{
	"match": true,
	"country": "AUS",
	"name": "TELSTRA CORPORATION LIMITED",
	"names": [
		{
			"value": "TELSTRA INFRACO",
			"type": "businessName"
		},
		{
			"value": "TELECOM AUSTRALIA",
			"type": "businessName"
		},
		{
			"value": "TELSTRA",
			"type": "tradingName"
		},
		{
			"value": "TELSTRA CORPORATION LIMITED",
			"type": "tradingName"
		}
	],
	"entityNumber": "33051775556",
	"entityNumbers": [
		{
			"value": "33051775556",
			"type": "ABN"
		},
		{
			"value": "051775556",
			"type": "ACN"
		}
	],
	"entityStatus": "Active",
	"entityType": "Australian Public Company",
	"entityTypeCode": "publicCompany",
	"address": {
		"text": "VIC 3000",
		"state": "VIC",
		"postcode": "3000"
	}
}

Sample response (not matched):

HTTP Status 404

{
	"match": false,
	"message": "Could not find entity."
}