Overview

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

Output

The output from the get BusinessVerification call will be in JSON format, and contains four five main sections:

1. Copy of greenID Business API: businessVerification - GET: businessVerificationReference: This is the reference number of the business verification you returned. This should match the reference number you requested.Copy of greenID Business API: businessVerification - GET
2. confirmedDone: This indicates if the user confirmed all activity is complete and the business can be 'verified'.
3. entities: This contains details of the businesses and individuals that exist within the business structure. Each of these will have a unique ID.
4. Copy of greenID Business API: businessVerification - GET: relationships: This contains details of the relationships between the entities within the business structure e.g. Individual A is a shareholder of Business X
5. Copy of greenID Business API: businessVerification - GET: 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

Anchor

#confirmedDone

#confirmedDone

confirmedDone

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

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

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 type of this entity. This will be set to "individual" for entities that are individuals.

(Possible values are 'individual' and 'business')

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.

List of Notes

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'.

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.

Anchor
#Entities #Entities

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

entities Structure - Business

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:

• Multiple addresses may be returned, each with a specified address type

For verifications created prior to 9 January 2019:

• Business addresses are not fully supported. This may contain a single address, no address, or only a country code

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. 

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

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 

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 <<DATE>> onwards.

Note: The current entity name will also be returned in the 'name' field.

(Possible values are 'individual' and 'business')

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)

Whether or not details about this entity were obtained from a business register (i.e. this will be 'true' if:

• this business was found via a lookup against a business register (in this case 'foundInRegister' will also be true) OR
• the results from a lookup of a business on a business register included a reference to this business. Example: The results of lookup of a company included details of this business as a shareholder.

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.

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

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.

Indicates the type of address. Valid types are as follows:

For Business entities:

• REGISTERED_ADDRESS
• PHYSICAL_ADDRESS
• PRINCIPAL_PLACE_OF_BUSINESS
• POSTAL_ADDRESS, ADDRESS

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

The human-readable version of the country name

This may not always be populated for verifications created prior to 9 January 2019 onwards.

The town or city of the address (only available if address has been validated)

Only applicable to New Zealand addresses

The abbreviation for the state (only available if address has been validated)

Only applicable to Australian addresses 

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.

Indicates the type of the business number. Currently the following business number types apply:

For Australian Businesses:

• 'ACN' - Australian Company Number
• 'ABN' - Australian Business Number
• 'ARSN' - Australian Registered Scheme Number
• 'ARBN' - Australian Registered Body Number
• 'Number' - other number provided by ASIC

For New Zealand Businesses:

• 'NZBN' - New Zealand Business Number
• 'company number' - New Zealand company number (i.e. the 'source register number' held on the NZBN register for a company)
• 'organisation number' - the 'source register number' held on the NZBN register for businesses with a type other than company. (This indicates the number held for the business on the originating register e.g. charitable trusts register)
• 'ACN' - Australian Company Number (only applicable for 'Overseas ASIC Company' on the NZBN Register)
• 'ABN' - Australian Business Number (only applicable for 'Overseas ASIC Company' on the NZBN Register)

Indicates whether this business number is the primary/main business number for the business. There will only be one primary business number for a business.

A business number is designated as the primary business number (i.e. 'primary' = true) if the business details were retrieved from the business register (e.g. NZBN or ASIC) using this number. The primary number for each business register is as follows:

ASIC Business Register: ACN / ARSN / ARBN

Australian Business Register (ABR): ABN

NZBN Register: NZBN

true

false

document Structure

entityNames Structure 

Entity names are the main name or legal name by which a business is known. Also known as organisation name.

The 'entityNames' structure contains an array of entity names for the business. This may contain both current and previous entity names. The current entity name will have no end date, and may optionally have a start date. (The current entity name is also returned in the 'name' field for a business) 

entities Structure - Business

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.

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.

document Structure

tradingNames Structure 

The tradingNames structure returns an array of additional names by which the business may be known, or may trade under.

It should be noted that for Australian Businesses, this will contain details of registered 'Business Names'. ('Trading Names' can no longer be registered for Australian Businesses, these have essentially been replaced by 'Business Names'. The greenID Business system will only return Business Names, NOT the legacy Trading Names).

For New Zealand businesses, this section will contain the Trading Names for the business.

entityNames Structure 

Entity names are the main name or legal name by which a business is known. Also known as organisation name.

The 'entityNames' structure contains an array of entity names for the business. This may contain both current and previous entity names. The current entity name will have no end date, and may optionally have a start date. (The current entity name is also returned in the 'name' field for a business) 

Note: tradingNames entityNames will only be returned for verifications created from 9 January 2019 onwards.

fields Structure

'Fields' are a collection of name / value pairs providing additional information about a business entity. The fields will vary depending on the country and business type of the business. 

For example:

A business entity that is a company in Australia may have entity fields for say  "class" and "subClass" but a partnership in New Zealand may only have a field for "registrationDate". 

Note: fields will only be returned as part of business 'entities' for verifications created from 9 January 2019 onwards.

"class", "registrationDate" etc

Provides the value of this field. 

Note: If the value is a date (e.g. registrationDate) then it will be a String in the format "DD/MM/YYYY"

"Limited By Shares", "23/11/1971" etc

Note: 'fields' are also used within a 'Relationship' structure - these have been defined separately as a 'fields Structure' within the 'Relationships' section.

note Structure

If present, the context in which the note was added e.g. when exempting an entity from verification.  

Possible values: "exemptFromVerification", "externallyVerified".

tradingNames Structure 

The tradingNames structure returns an array of additional names by which the business may be known, or may trade under.

It should be noted that for Australian Businesses, this will contain details of registered 'Business Names'. ('Trading Names' can no longer be registered for Australian Businesses, these have essentially been replaced by 'Business Names'. The greenID Business system will only return Business Names, NOT the legacy Trading Names).

For New Zealand businesses, this section will contain the Trading Names for the business.

The 'tradingNames' array may contain both current and previous trading names (for NZ businesses) or business names (for AU businesses). There may be multiple current names, and multiple previous names returned. Current names will have no end date, and may optionally have a start date.

Note: tradingNames will only be returned for verifications created from 9 January 2019 onwards.

fields Structure

'Fields' are a collection of name / value pairs providing additional information about a business entity. The fields will vary depending on the country and business type of the business. 

For example:

A business entity that is a company in Australia may have entity fields for say  "class" and "subClass" but a partnership in New Zealand may only have a field for "registrationDate". 

Note: fields will only be returned as part of business 'entities' for verifications created from 9 January 2019 onwards.

Note: 'fields' are also used within a 'Relationship' structure - these have been defined separately as a 'fields Structure' within the 'Relationships' section.

note Structure

Valid Values for Verification Status 

The following provides the possible values for the 'status' field found as part of the 'verification' object. A 'verification' object can exist for a business, individual or document. The below table indicates which statuses could occur for each.

the greenID verification for the individual is 'pending'. The individual has been verified against the rule set, but they changed data in a way that is not considered acceptable without further action. An administrator needs to review and action the verification before the individual can be treated as verified. 

(Note: this is not treated as 'verified') 

Relationships

Within a business structure, there are numerous 'relationships' between the entities (individuals and businesses). Each of the entities are defined within the 'Entities' structure, and then details of how they are related to each other will be provided in this section. A single entity (e.g. a particular individual or business) may be involved in multiple relationships within the business.

Each relationship has a relationship 'type', and the two participants in that relationship - the 'relatedEntity' and the 'businessRelatedTo. These fields contain the unique ID of the entity, which corresponds to the ID used to identify the entity within the 'Entities' section.

For example: 

A business 'Superclean Windows' has two shareholders 'Peter Jones' and 'Wonderful Windows'. 'Wonderful Windows' in turn has a shareholder of 'Jack Jones'. The relationships will be as follows:

• a relationship with a type of' 'shareholder', Peter Jones will be the 'relatedEntity' and Superclean Windows will be the 'businessRelatedTo'. 
• a relationship with a type of' 'shareholder', Wonderful Windows will be the 'relatedEntity' and Superclean Windows will be the 'businessRelatedTo'.
• a relationship with a type of' 'shareholder', Jack Jones will be the 'relatedEntity' and Wonderful Windows will be the 'businessRelatedTo'.

relationship Structure

The following section gives details on the fields in each relationship structure.

The entity ID of the business entity in which this relationship exists.  An example would be the company that is owned by a shareholder (specified as the 'relatedEntity') in a shareholding relationship.

This entity id corresponds to the ID used to identify the entity within the 'Entities' section.

The entity ID of the entity which is related to the business specified in the "businessRelatedTo" field. An example would be the shareholder that owns shares in a company (specified as the 'businessRelatedTo) in a shareholding relationship. A related entity can be a business or an individual.

This entity id corresponds to the ID used to identify the entity within the 'Entities' section.

Whether or not the 'related entity' requires verification within the context of this relationship.

Note: an entity may be 'verificationNotRequired' in one relationship within the business, but still require verification due to their involvement in another relationship.

For example: Peter as a 10% shareholder does not require verification, but Peter as a director does require verification

For additional information see Understanding Verification Status

If 'verificationNotRequired' is true, this will detail why the entity is exempt from verification within the context of this relationship.

Possible values are:  

fields Structure

'Fields' are a collection of name / value pairs providing additional information about a relationship. The fields will vary depending on the country and business type

For example:

A shareholder relationship for an Australian company may have fields for "allocationNumber", "ownershipPercentage" and "shareClassTitle", but a company office holder relationship may just have "type".

"controllerType", "additionalInformation",   "ownershipPercentage" etc.

If present, gives the value of this field. If a field is not populated, then 'value' will not be present or will be empty. <<CHECK>> Do we return a name for every value in config even if no value for it?? This does not sound accurate...

"Director"

"23/11/1971"

If present, gives the verification threshold for this field. Any value less than the verificationThreshold will result in the relationship defaulting to 'verification not required'.

Generally this only exists in relation to an ownership percentage field.

Note: 'fields' are also used within an 'Entity' structure - these have been defined separately as a 'fields Structure' within the 'Entities' section.)

rootBusiness

This object provides 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. 

Please note that this business is also contained within the 'entities' section of the results. It is has been extracted to this 'rootBusiness' section for ease of reference if you simply require the summary details for the business you are aiming to verify (i.e. the root business or top level business). 

rootBusiness Structure <<CHECK Francis - is this identical to entity?? Update this>>

verification Structure

Valid Values for Verification Status 

The following provides the possible values for the 'status' field found as part of the 'verification' object. A 'verification' object can exist for a business, individual or document. The below table indicates which statuses could occur for each.

Relationships

Within a business structure, there are numerous 'relationships' between the entities (individuals and businesses). Each of the entities are defined within the 'Entities' structure, and then details of how they are related to each other will be provided in this section. A single entity (e.g. a particular individual or business) may be involved in multiple relationships within the business.

Each relationship has a relationship 'type', and the two participants in that relationship - the 'relatedEntity' and the 'businessRelatedTo. These fields contain the unique ID of the entity, which corresponds to the ID used to identify the entity within the 'Entities' section.

For example: 

A business 'Superclean Windows' has two shareholders 'Peter Jones' and 'Wonderful Windows'. 'Wonderful Windows' in turn has a shareholder of 'Jack Jones'. The relationships will be as follows:

• a relationship with a type of' 'shareholder', Peter Jones will be the 'relatedEntity' and Superclean Windows will be the 'businessRelatedTo'. 
• a relationship with a type of' 'shareholder', Wonderful Windows will be the 'relatedEntity' and Superclean Windows will be the 'businessRelatedTo'.
• a relationship with a type of' 'shareholder', Jack Jones will be the 'relatedEntity' and Wonderful Windows will be the 'businessRelatedTo'.

relationship Structure

The following section gives details on the fields in each relationship structure.

fields Structure

'Fields' are a collection of name / value pairs providing additional information about a relationship. The fields will vary depending on the country and business type

For example:

A shareholder relationship for an Australian company may have fields for "allocationNumber", "ownershipPercentage" and "shareClassTitle", but a company office holder relationship may just have "type".

Note: 'fields' are also used within an 'Entity' structure - these have been defined separately as a 'fields Structure' within the 'Entities' section.)

rootBusiness

This object provides 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. 

Please note that this business is also contained within the 'entities' section of the results. It is has been extracted to this 'rootBusiness' section for ease of reference if you simply require the summary details for the business you are aiming to verify (i.e. the root business or top level business). 

rootBusiness Structure 

The rootBusiness structure contains a single instance of the 'entities' structure for a Business - see entities Structure - Business. 

Exceptions and Error Handling

In addition to the types of standard exceptions thrown by the API (as documented on the main API page), the following exceptions are specific to the GET call:

Understanding Verification Status

For a business to be 'verified' overall (i.e. the 'root business' to be verified), the business' existence must have been verified (see rootBusiness.existenceVerified) and all entities (i.e. individuals and businesses) that require verification must have been verified. As such, each entity must either have a verification status of 'verified', or be indicated as 'verificationNeverRequired'.

Entity - 'verificationNeverRequired'

If 'verificationNeverRequired is set to 'true' for a particular entity, then it means that the entity does not need to be verified within any relationship within the business structure in order for the overall business verification to be 'verified'.

You may notice that 'verificationNeverRequired' could be set to true even if the entity exists as the 'relatedEntity' within a relationship that is indicated as requiring verification (i.e. verificationNotRequired is false. See below for information on 'verificationNotRequired'). This can occur if a relationship further up the 'business structure tree' is verification not required - this then overrides the relationship's own verification status. This is best explained via an example:

Example:

Superclean windows has 2 shareholders:

• Peter Jones - 80% shares
• Wonder Windows - 20% shares. Wonder Windows has a shareholder:
  • Jack Jones - 100% shares

In this case the following relationships exist:

• Peter Jones as shareholder of Superclean Windows - requires verification (since he owns more than 25% of the shares in Superclean Windows)
• Wonder Windows as a shareholder of Superclean Windows -verification not required (since they own less than 25% of the shares in Superclean Windows)
• Jack Jones as a shareholder of Wonder Windows - requires verification (since he owns more than 25% of the shares in Wonder Windows

However, because Wonder Windows does not require verification in the above relationship structure - this overrides the need for Jack Jones to be verified. In this example, Jack Jones would therefore be 'verificationNeverRequired' even though the relationship in which he is found is indicated as requiring verification.

(If however, in the above example Jack Jones was also a Director of Superclean Windows, then he WOULD require verification due to this relationship. 'verificationNeverRequired' would then be false for him.)

Relationship - 'VerificationNotRequired' 

For each relationship in the business, the 'verificationNotRequired' indicator will indicate where the entity needs to be verified within the context of that particular relationship i.e. the relationship between the 'relatedEntity' and the 'businessRelatedTo'. Reasons that verification may not be required for an entity within the context of a particular relationship are:

• the user manually marked it as verification not required
• verification not required was defaulted due to the relationship type being deemed as one that doesn't generally require verification
• verification not required was defaulted due to the ownership percentage being less than the defined verification threshold