...
...
...
...
...
...
...
...
Example errors include:
<<KS: I think we need to include details of what is validated and the status/error codes returned for each? Check std API docs>>
- Not Found (404)
- Unauthorized (401)
- Internal Server Error (500)
Methods Available
The following webservice methods are available for the greenID Business API version 1:
get BusinessVerification: <<KS - make this a link to the new page for this. Text below can be an 'excerpt' and use 'excerpt include' here?>>
The greenID Business API ‘get Business Verification’ method allows customers to extract the current details of a business verification. Given a greenID Business reference number, the API call returns information about the top-level business, sub-businesses, and all associated individuals (including their verification status).
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
- Entities
- Relationships
- rootBusiness
An entity could be an individual or business, and relationships are the connections between different entities. Each of these will have a unique ID.
<<KS: Describe rootBusiness. Should it be listed first? Think maybe we need a bit more info in this section to describe each section?>>
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? They do however generally appear in the order specified below, so perhaps we leave it?>>
...
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 this entity was retrieved from a data source (e.g. a lookup on a business register).
(Note: the individual's details retrieved may have subsequently been edited by a user)
...
List of Notes
...
Entity Object (Business)
...
Address Object
...
DataSource Object
...
Document Object
...
...
Note Object
...
Verification Object
...
Relationships
The following section gives details on the fields in each relationship structure.
Relationship Object
...
Field Object
...
rootBusiness Object
This object gives details on the root business that was originally searched for.
...