API Versions

This documentation relates to Version 1, the current version of the greenID Business API. Version 1 became available to customers as of 23 Aug 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.

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: For verifications which became 'verified' prior to this date, confirmedDone will be 'false'. For verifications which became 'verified' after this date, confirmedDone will always be 'true'. Any verifications which are not 'verified', confirmedDone will always be false.	Boolean	"true" or "false"

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:

For verifications which became 'verified' prior to this date, confirmedDone will be 'false'.
For verifications which became 'verified' after this date, confirmedDone will always be 'true'.
Any verifications which are not 'verified', confirmedDone will always be false.

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	Addresses	-
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	Verification	-
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: 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	Addresses	-
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.	BusinessNumbers	-
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.	entityNames	-
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	fields	-
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: 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.	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	Verification	-
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: 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	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: '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)	String	"ACN", "NZBN"
number	The business number e.g. the NZBN, ACN as per specified businessNumberType	String	"9429033703534"
primary	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	Boolean	true false

Field Name

Description

Type

Example

type

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)

String

"ACN", "NZBN"

number

The business number e.g. the NZBN, ACN as per specified businessNumberType

String

"9429033703534"

primary

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

Boolean

true

false

document Structure

Field Name	Description	Type	Example
creationTime	The date and time when this document was created (uploaded). Format is UTC (Universal Time Coordinated)	String	"2018-08-15 06:18:19.929+0000"
documentURL	A URL where this document can be downloaded from	String	"https://au.vixverify.com/vixbiz/api/v1/document/1854"
evidenceType	The type of evidence that this document provides	String	"Statutory declaration"
fileSize	The size of the document file, in bytes.	Integer	297054
name	The original document filename	String	"file.pdf"
verification	The verification associated with this document	Verification	-

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.

Field Name	Description	Type	Example
name	The entity name of the business	String	"Vix Verify"
startDate	The start date from which this entity name applied (may not always be available for the current name) Date format: "DD/MM/YYYY"	String	"16/11/1999"
endDate	The date when this entity name ceased to apply. The current entity name will not have an endDate. Date format: "DD/MM/YYYY"	String	"21/11/2018"

Field Name

Description

Type

Example

name

The entity name of the business

String

"Vix Verify"

startDate

The start date from which this entity name applied (may not always be available for the current name)

Date format: "DD/MM/YYYY"

String

"16/11/1999"

endDate

The date when this entity name ceased to apply.

The current entity name will not have an endDate.

Date format: "DD/MM/YYYY"

String

"21/11/2018"

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.

Field Name	Description	Type	Example
name	The trading name (for NZ) or business name (for AU) used by the business	String	"My Secure ID"
startDate	The start date from which this name applied (may not always be available for current names)	String	"16/11/1999"
endDate	The date when this name ceased to apply If the name is a current name, then it will not have an endDate.	String	"21/11/2018"

Field Name

Description

Type

Example

name

The trading name (for NZ) or business name (for AU) used by the business

String

"My Secure ID"

startDate

The start date from which this name applied (may not always be available for current names)

String

"16/11/1999"

endDate

The date when this name ceased to apply

If the name is a current name, then it will not have an endDate.

String

"21/11/2018"

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.

Field Name	Description	Type	Example
name	The name of this field	String	"class", "registrationDate" etc
value	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"	String	"Limited By Shares", "23/11/1971" etc

Field Name

Description

Type

Example

name

The name of this field

String

"class", "registrationDate" etc

value

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"

String

"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

Field Name	Description	Type	Example
author	The author of a note	String	"john.doe@example.com"
context	If present, the context in which the note was added e.g. when exempting an entity from verification. Possible values: "exemptFromVerification", "externallyVerified".	String	"exemptFromVerification"
creationTime	A timestamp for when this note was created. Format is UTC (Universal Time Coordinated)	String	"08/08/2018 00:00:09.217+0000"
text	The note text	String	"A note"

verification Structure

Field Name	Description	Type	Example
dateDue	The due date for this verification. Format is UTC (Universal Time Coordinated)	String	"12/08/2018 00:00:09.217+0000"
dateNominated	The date that this verification was nominated (created). Format is UTC (Universal Time Coordinated)	String	"08/08/2018 23:16:47.065+0000"
greenIDVerificationId	Only returned if the verification is for an Individual, and the individual is being verified via greenID. This is the verification identifier within the greenID core system for the individual.	String	"pnP7urdr"
status	The status of this verification. See 'Valid Values for Verification Status' for possible values and when they may occur For additional information see Understanding Verification Status	String	"Verified"

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.

Status	Description	Valid for
Verified	Has been verified	Business, Individual, Document
Not yet verified	Has not been verified as yet. Verification may have not started, or may be in progress	Business, Individual, Document
Failed	User has 'failed' the verification for the overall business	Root Business
Abandoned	User has 'abandoned' the verification for the overall business	Root Business
Verified externally	User has indicated that the entity was verified externally (i.e. outside of greenID)	Business, Individual
Verified by an administrator	the greenID verification for the individual was verified by an administrator within greenID	Individual
Verified, with minor changes	the greenID verification for the individual was verified against the specified rule set, however some minor changes were made to the data. These changes are included in your greenID rule set as acceptable changes.	Individual
Verified, pending review	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')	Individual
Locked out	the greenID verification for the individual has been locked out. This occurs depending on the lock out rules defined for your account. (By default there are no lockout rules)	Individual
Rejected	the document uploaded has been rejected by the user	Document

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.

Field Name	Description	Type	Example
businessRelatedTo	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.	Integer	789587
fields	A list of fields associated with this relationship. These provide information about the relationship, for example the percentage of shares held in a 'shareholder' relationship.	List of Fields	-
id	The ID of this relationship	Integer	789557
relatedEntity	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.	Integer	789558
type	The type of this relationship	String	"Company office holder", "Shareholder", "Ultimate Holding Company" etc.
verificationNotRequired	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	Boolean	"true" or "false"
verificationNotRequiredReason	If 'verificationNotRequired' is true, this will detail why the entity is exempt from verification within the context of this relationship. Possible values are:	String	"Ownership percentage is below threshold of 25"

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

Field Name	Description	Type	Example
name	The name of this field	String	"controllerType", "additionalInformation", "ownershipPercentage" etc.
value	Provides the value of this field.	String	"Director" "23/11/1971"
verificationThreshold	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.	String	"25"

Field Name

Description

Type

Example

name

The name of this field

String

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

value

Provides the value of this field.

String

"Director"

"23/11/1971"

verificationThreshold

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.

String

"25"

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:

HTTP Status Code	Error	Error Message	Conditions
404	Not found	"No verification with id <verification_reference_id>	A business verification was not found on your account for the input verification reference number
400	Bad request	"Invalid number used as id"	The input verification reference number was not a numeric value

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

If you can't find what you need here, email us at customer.support@gbgplc.com or log a ticket via our portal

greenID Business A-Z

Page:

Business Verification Workflow
Page:

greenID Business
Page:

greenID Business Admin Panel User Guide
Page:

greenID Business API
Page:

greenID Business Constraints and Known Issues
Page:

greenID Business Release Notes
Page:

greenID Business Search Restrictions
Page:

Manage Business Verifications
Page:

Verify a business

Overview

Accessing businessVerification via 'GET'

Input Parameters

Output

businessVerificationReference

confirmedDone

Entities

entities Structure - Individual

entities Structure - Business

addresses Structure

businessNumbers Structure

document Structure

entityNames Structure

tradingNames Structure

fields Structure

note Structure

verification Structure

Valid Values for Verification Status

Relationships

relationship Structure

fields Structure

rootBusiness

rootBusiness Structure

Exceptions and Error Handling

Understanding Verification Status

Entity - 'verificationNeverRequired'

Relationship - 'VerificationNotRequired'

On this page

greenID Business A-Z

Browser not supported