| 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.
...
| Field Name | Description | Type | Example |
|---|---|---|---|
| businessVerificationReference | The value of the verification_reference_id that was requested | Integer | 1097 |
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 gives provides details on 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?>>
| Field Name | Description | Type | Example |
|---|---|---|---|
| address | A structure encoding the address of the entity | Address | - |
| dataSource | Details onof the data source (e.g. a company register) used for getting information onfrom 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'>> | <<??>> | - |
| dob | Date of birth for this individual | String | "25/05/1947" |
| entityType | The type of this entity. (Possible values are 'individual' and 'business') | String | "individual" |
| fromDataSource | Whether or not this entity camewas retrieved from a data source (e.g. a lookup of a company register). (Note: details may have subsequently 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'. | Boolean | "true" or "false" |
Entity Object (Business)
...
| Field Name | Description | Type | Example |
|---|---|---|---|
| countryCode | The address country code i.e. a two digit code. | String | "NZ" |
| countryName | The human-readable version of the country name. | 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) | String | "NELSON" |
...