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. 

<<KS: Is the above sufficient for a developer to know how to use this?>>

Exceptions and Error Handling

We return an error response in JSON format if an exception occurs. An example of this is as follows:

{
  "error": "Not found",
  "message": "No verification with ID: 1775",
  "status": 404
}

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

http://au.vixverify.com/vixbiz/api/v1/businessVerification/<verification_reference_id>

Input Parameters

Output

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

1. businessVerificationReference
2. Entities
3. Relationships
4. 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?

Also - there are many fields repeated for business and for individual, could they rather be defined only once?>> 

Entity Object (Business)

Address Object

<<KS: Are the fields the same for AU and NZ addresses? Need to specify which fields actually populate for businesses - seems to only be country code, and sometimes none>>

DataSource Object

<<KS: Don't think this exists anymore...>>

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.