| Info | ||
|---|---|---|
| ||
This documentation relates to Version 1, the current version of the greenID Business API. Version 1 became available to customers as of . |
Authentication
HTTP basic authentication is used for accessing the endpoint. The username is your greenID customer account ID that you use for greenID Business, and the password is your greenID web services password for that account.
...
Additional methods will be made available in future, for example a method to create a new business verification via the API.
get BusinessVerification. <<KS - I think this needs to be split out to a new page?>>
<<KS: Add this text as an 'excerpt on the new page'>>
The greenID Business API ‘get Business Verification’ method allows you to extract the current details of a business verification, including it's 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'), it's sub-businesses (for example shareholder businesses), and all associated individuals (including their verification status).
The 'get BusinessVerification' method is available as a RESTful endpoint. The URL to call is as follows:
<<KS: Do we need to specify something in the above text about using 'get' in conjunction with the below url?? Jo to advise... >>
| Code Block |
|---|
http://au.vixverify.com/vixbiz/api/v1/businessVerification/<verification_reference_id> |
Input Parameters
...
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 four main sections:
- businessVerificationReference: This is the reference number of the business verification you returned. This should match the reference number you requested.
- 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.
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.
Entity Object (individual)
<<KS: since order of the fields returned is not guaranteed, should we order them logically within the docs e.g. all name fields together?>>
Also - there are many fields repeated for business and for individual, could they rather be defined only once?>>
...
Details of the data source (e.g. a company register) from which this entity's details were retrieved.
<<KS: I can't see that a 'Datasource' structure is being returned. Has this changed? 'dataSource' seems to just have the description of the data source now - no 'type'>>
...
<<??>>
...
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).
...
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'.
...
Entity Object (Business)
...
A structure encoding the address of the entity
For a business entity, only the country will be provided. If however the 'countryOfRegistration' is populated, then no address details will be populated.
<<KS: Clarify this... is this working as intended? Why isn't country always populated?>>
...
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 it's details retrieved)
...
Whether or not this entity came from a data source (e.g. a lookup of a company register).
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.
...
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'.
...
Address Object
For business entities: if the business was not found on a business register via a search, then the 'location' of the business is indicated by the country code within the Address. No other address fields are currently provided for a business. If the business was found on a business register, then the Address will be empty but the 'country of registration' will be provided.
For individual entities: If the address was not validated, 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.
...
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
...
DataSource Object
<<KS: Don't think this exists anymore...>>
...
Document Object
...
Note Object
...
If present, the context in which the note was added e.g. when exempting an entity from verification etc.
<<KS: Do we know the possible values? If so, we should list these here>>
...
Verification Object
...
The status of this verification
<<KS: Can we list all possible values and what object types applicable to?>>
...
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 2 participants in that relationship - the 'relatedEntity' and the 'businessRelatedTo.
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 Object
The following section gives details on the fields in each relationship structure.
...
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
...
Field Object
'Fields' are a collection of name / value pairs providing information about a relationship. The fields will vary depending on the country, business type, and the type of the relationship.
For example: A shareholder relationship may have fields for "allocationNumber", "ownershipPercentage" and "shareClassTitle", but a company office holder relationship may just have "type".
...
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.
...
rootBusiness Object
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).
...
The country where the business is registered, 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).
...
Whether or not the existence of this entity 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.
...
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 it's 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.
...
Contents
| Child pages (Children Display) |
|---|