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

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. 

DataSource Object

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

Document Object

Note Object

Verification Object

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.

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

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.