greenID Business API: businessVerification - GET
API Versions
This documentation relates to Version 1, the current version of the greenID Business API. Version 1 became available to customers as of Aug 23, 2018.
Overview
The greenID Business API 'businessVerification' endpoint, when accessed via an HTTP 'GET' command, allows you to extract the current details of a business verification, including its verification status. Given a greenID Business reference number, the API call returns information about the business to be verified (i.e. the 'top level' or 'root business'), its sub-businesses (for example shareholder businesses), and all associated individuals (including their verification status).
Accessing businessVerification via 'GET'
The greenID Business API endpoint 'businessVerification' is available as a RESTful endpoint. To utilise this to extract details of a business verification from the greenID Business system, the following URL should be called using the HTTP GET method:
https://au.vixverify.com/vixbiz/api/v1/businessVerification/<verification_reference_id>If you wish to access the API in the TEST environment, then the following URL should be used instead:
https://test-au.vixverify.com/vixbiz/api/v1/businessVerification/<verification_reference_id>For authentication requirements when using the greenID Business API, see Version 1 greenID Business API - Authentication.
Input Parameters
Name | Type | Required | Description |
|---|---|---|---|
verification_reference_id | String | Yes | The <verification_reference_id> is the unique 'Ref. No' of the business verification within the greenID Business system. This must be obtained from the greenID Admin Panel version of the system. It can be found on the greenID Business Admin page where all your business verifications are listed, or on the 'Verify a business' details page of the required business verification. |
Output
The output from the get BusinessVerification call will be in JSON format, and contains five main sections:
businessVerificationReference: This is the reference number of the business verification you returned. This should match the reference number you requested.
confirmedDone: This indicates if the user confirmed all activity is complete and the business can be 'verified'.
entities: This contains details of the businesses and individuals that exist within the business structure. Each of these will have a unique ID.
relationships: This contains details of the relationships between the entities within the business structure e.g. Individual A is a shareholder of Business X
rootBusiness: This contains the summary details about the 'root business' that this overall business verification pertains to. This would be the business that you are aiming to verify and originally searched for or manually created. If you simply require the summary details for the business you are aiming to verify (i.e. the root business or top level business), and do not require full details of the business structure, then this is the section to refer to.
Please note that the fields within each section are ordered in alphabetical order, which is the order in which we will extract them.
businessVerificationReference
Field Name | Description | Type | Example |
|---|---|---|---|
businessVerificationReference | The value of the verification_reference_id that was requested | Integer | 1097 |
confirmedDone
The final step in the business verification process is for the user to confirm that they have completed all checks and activities required by their business processes, and that they are happy for the business to be marked as 'verified'. The 'confirmedDone' flag indicates whether this confirmation has been provided. Verifications where existence has been verified, and all required individuals and related businesses have been verified may still be in a 'not yet verified' state due to the user confirmation being outstanding.
Note: The confirmation step only applies to the overall verification of the top level / root business, not to the verification of each related business within the business structure.
Field Name | Description | Type | Example |
|---|---|---|---|
confirmedDone | Whether or not this verification has been confirmed as "Done" by the user (i.e. whether the user has confirmed all required activity has been completed and they are satisfied the business can be 'verified'). This confirmation check was introduced on 25 June 2019 (into Production). As such:
| Boolean | "true" or "false" |
Entities
The 'entities' section contains details of the relevant parties within the business. There are two types of entities which can be contained within this section - individuals and businesses. The type of entity is specified by the 'entityType'. A particular entity may be present within multiple 'relationships' within the business (for example as a director and as a shareholder), but they should only be represented once within the entities section. For example: If individual 'Jack Black' is both a director and shareholder, there will only be one entity returned for him*
*Note: For an individual occurring in multiple places within a business structure to be recognised as the same 'entity', their name and address as retrieved from the business register (or manually captured for manually added individuals) must be identical - else they will be assumed to be different 'entities' (i.e. different people) and there will then be more than one entry in the entities section for them.
The following section provides details of the fields in each entity structure.
entities Structure - Individual
Field Name | Description | Type | Example |
|---|---|---|---|
addresses | An array of the addresses for the entity. Each address contains a number of components - see Addresses. For individuals, only a single address will be provided | - | |
dataSource | The name of the data source (e.g. a company register) from which this individual's details were retrieved. Will only be returned if 'fromDataSource' is true | String | "the New Zealand Business Number Register" |
dob | Date of birth for this individual - provided in format DD/MM/YYYY | String | "25/05/1947" |
entityType | The type of this entity. This will be set to "individual" for entities that are individuals. (Possible values are 'individual' and 'business') | String | "individual" |
fromDataSource | Whether or not details about this entity were obtained from a business register* (i.e. this will be 'true' if if the results from a lookup of a business on a business register included details of this individual. Example: The results of lookup of a company included details of an individual who is a director). If true, the name of the business register from which the details were obtained will be provided in the 'dataSource' field. *Note that the details returned may have been edited by a user. | Boolean | "true" or "false" |
givenName | The given name of this individual | String | "John" |
id | The unique ID of this entity | Integer | 789112 |
middleNames | Middle name(s) for this individual | String | "Clive" |
notes | A list of notes associated with this entity | List of Notes | - |
surname | The surname of this individual | String | "Smith" |
verification | A structure encoding verification details for the entity | - | |
verificationNeverRequired | Whether or not verification is required for this entity If 'true', then this entity does not need to be verified within any relationship within the business structure in order for the overall business verification to be 'verified'. For additional information see Understanding Verification Status | Boolean | "true" or "false" |
entities Structure - Business
Field Name | Description | Type | Example |
|---|---|---|---|
addresses | An array of the addresses for the entity. Each address contains a number of components - see Addresses. The following applies to Business Entity Addresses: For verifications created on or after 9 January 2019:
For verifications created prior to 9 January 2019:
| - | |
businessNumbers | An array of business numbers which apply to this business. If the business was retrieved from a business register (e.g. NZBN or ASIC), then the number used to retrieve the business details from the register will be designated as the 'primary' number. Example: if the business was retrieved from the NZBN Register, then the primary business number will be the NZBN. | - | |
businessStatus | The status of the business as returned from a business register. (Possible values will differ dependent on the business register) | String | "Registered" |
businessSubtype | The business subtype (Possible values will differ dependent on the business register) | String | "AU Limited Company" |
businessType | The type of business. Possible values may differ dependent on country. For Australia and New Zealand these are company, partnership, trust, sole trader, other For all other countries these are company, other | String | "company" |
countryOfRegistration | The country where the business is registered (i.e. the country of the business register used to retrieve the business details), in the form of a two-letter country code. This will only be populated if the business is registered on the stated business register (see dataSource). Example: If a business is registered on the NZBN register, countryOfRegistration will be NZ | String | "AU" |
dataSource | Details of the data source (i.e. business register) from which this entity's details were retrieved. | String | "the New Zealand Business Number Register" |
documents | A list of documents associated with this business | List of Documents | - |
entityNames | An array of the entity names which apply to this business. There will always be one current entity name, and there may be multiple previous entity names. Only returned for businesses created from 9 January 2019 onwards. Note: The current entity name will also be returned in the 'name' field. | - | |
entityType | The type of this entity. This will be set to "business" for entities that are businesses. (Possible values are 'individual' and 'business') | String | "business" |
existenceVerified | Whether or not the existence of this business has been verified. Existence is verified either by the business being found on a business register (see foundInRegister), or by the upload and verification of supporting documents. | Boolean | true or false |
fields | An array of additional data items associated with this business, presented as name/value pairs. These 'fields' provide extra information about the business. The items presented depend on the country and business type. Examples are registrationDate, industryClassification, class, subClass, gstEffectiveDate | - | |
foundInRegister | Whether or not this business was found on a business register (i.e. this will be 'true' if a lookup was performed against a business register using the business number, the business was successfully found and its details retrieved) | Boolean | true or false |
fromDataSource | Whether or not details about this entity were obtained from a business register (i.e. this will be 'true' if:
| Boolean | true or false |
id | The unique ID of this entity | Integer | 1096 |
name | The name of this business (i.e. the legal entity name) | String | "Acme Pty Ltd" |
notes | A list of notes associated with this entity | List of Notes | - |
searchRestricted | Whether or not this entity was search restricted. If 'true' then we did not search for this entity on a business register due to search restrictions on your account, and so full details for this business will not be available. | Boolean | true or false |
tradingNames | An array of the names under which a business may operate. For New Zealand businesses this will contain the 'trading names' of the business. For Australian businesses, it will contain the registered 'business names' of the business (For Australian businesses, 'trading names' can no longer be registered, they were superseded by 'business names' in 2012.) Only supported for businesses created from 9 January 2019 onwards. |
|
|
verification | A structure encoding verification details for the entity | - | |
verificationNeverRequired | Whether or not verification is required for this entity If 'true', then this entity does not need to be verified within any relationship within the business structure in order for the overall business verification to be 'verified'. For additional information see Understanding Verification Status | Boolean | true or false |
addresses Structure
The 'addresses' structure contains an array of addresses for the entity.
For individual entities:
If the address was not validated by the user, then only the country and the 'full address' will be provided. If the address was validated, then the individual address fields populated will depend on the country and the type of address. Only a single address will be returned for an individual.
For business entities:
For verifications created from 9 January 2019 onwards, there may be multiple business addresses provided - each address will have an address type.
For verifications created prior to 9 January 2019 Business addresses are not fully supported. There may be a single address, no address, or only a country code provided.
Business addresses are not validated by the user, therefore only the country and 'full address' will be provided for these.
Field Name | Description | Type | Example |
|---|---|---|---|
addressType | Indicates the type of address. Valid types are as follows: For Business entities:
A type of 'ADDRESS' is used when the specific type of the address is not known For Individual entities: ADDRESS addressType is only provided for verifications created from 9 January 2019 onwards | String | "REGISTERED_ADDRESS" |
countryCode | The address ISO 1366 two digit country code | String | "NZ" |
countryName | The human-readable version of the country name This may not always be populated for verifications created prior to 9 January 2019. | String | "New Zealand" |
fullAddress | The full address in a single String | String | "67 HAVEN ROAD, NELSON 7010, NEW ZEALAND" |
postcode | The address postcode (only available if address has been validated) | String | "7010" |
streetName | The address street name (only available if address has been validated) | String | "HAVEN" |
streetNumber | The street number (only available if address has been validated) | String | "67" |
streetType | The type of street (only available if address has been validated) | String | "ROAD" |
townCity | The town or city of the address (only available if address has been validated) Only applicable to New Zealand addresses | String | "NELSON" |
suburb | The suburb of the address (only available if address has been validated) | String | "PAPAMOA BEACH" |
state | The abbreviation for the state (only available if address has been validated) Only applicable to Australian addresses | String | "NSW" |
businessNumbers Structure
The 'businessNumbers' structure contains an array of business numbers for the business.
For verifications created from 9 January 2019 onwards, there may be multiple business numbers provided (if applicable).
For verifications created prior to 9 January 2019 only a single business number applies - this is the number used to retrieve the details of the business from the business register.
For manually created businesses (i.e. businesses not retrieved from a business register), the businessNumbers array will be empty.
Field Name | Description | Type | Example |
|---|---|---|---|
type | Indicates the type of the business number. Currently the following business number types apply: For Australian Businesses:
|