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

Output

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

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

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

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

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: entityNames will only be returned for verifications created from 9 January 2019 onwards.

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

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 <<CHECK Francis - is this identical to entity?? Update this>>

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