| 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 |
|---|---|---|---|
| address | A structure encoding the address of the entity <<KS: Clarify this... if a business, does it only have country code? Doesn't always seem to have this though?>> | Address | - |
| businessNumber | The business number for this entity. This will be the business number for the business as registered on the stated 'dataSource'. Example: if the business was retrieved from the NZBN Register, then the business number will be the NZBN. | String | "111307361" |
| businessStatus | The status of the business as returned from a business register. (Possible values will differ dependent on the business register) | String | "Registered" |
| businessSubtype | The business subtype | String | "AU Limited Company" |
| businessType | The type of business | String | "company" |
| countryOfRegistration | 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). | String | "AU" |
| dataSource | Details of the data source (i.e. business register) from which this entity's details were retrieved. | String | "the New Zealand Business Number Register" |
| documents | A list of documents associated with this business | List of Documents | - |
| entityType | The type of this entity | String | "business" |
| existenceVerified | Whether or not the existence of this business 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. | Boolean | "true" or "false" |
| foundInRegister | 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) | Boolean | "true" or "false" |
| fromDataSource |
Whether or not details about this entity were obtained from a business register (i.e. this will be 'true' if:
| Boolean | "true" or "false" |
| id | The unique ID of this entity | Integer | 1096 |
| name | The name of this business (i.e. the legal entity name) | String | "Acme Pty Ltd" |
| notes | A list of notes associated with this entity | List of Notes | - |
| 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" |
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>>
...
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.
| 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 | "677010" |
| streetTypestreetName | The type of street 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) Only applicable to New Zealand addresses | String | "NELSON" |
DataSource Object
...
| suburb | The suburb of the address (only available if address has been validated) | String | "PAPAMOA BEACH" |
| state | The abbreviation for the state (only available if address has been validated) Only applicable to Australian addresses | String | "NSW" |
DataSource Object
<<KS: Don't think this exists anymore...>>
...
| Field Name | Description | Type | Example |
|---|---|---|---|
| author | The author of a note | String | john.doe@example.com |
| context | 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>> | String | exemptFromVerification |
| creationTime | A timestamp for when this note was created. Format is UTC (Universal Time Coordinated) | String | 2018-08-08 00:00:09.217+0000 |
| text | The note text | String | "A note" |
Verification Object
...
The status of this verification
<<KS: Can we list all possible values?>>
...
Relationships
The following section gives details on the fields in each relationship structure.
Relationship Object
...
| 08 00:00:09.217+0000 | |||
| text | The note text | String | "A note" |
Verification Object
| Field Name | Description | Type | Example |
|---|---|---|---|
| dateDue | The due date for this verification | String | 2018-08-08 00:00:09.217+0000 |
| dateNominated | The date that this verification was nominated (created) | String | 2018-08-07 23:16:47.065+0000 |
| greenIDVerificationId | Only returned if the verification is for an Individual, and the individual is being verified via greenID. This is the verification identifier within the greenID core system for the individual. | String | pnP7urdr |
| status | The status of this verification <<KS: Can we list all possible values and what object types applicable to?>> | String | "Verified" |
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 Name | Description | Type | Example |
|---|---|---|---|
| businessRelatedTo | The ID of the business entity in which the relationship exists. An example would be the company that is owned by a shareholder (specified as the 'relatedEntity') in a shareholding relationship. | Integer | 789587 |
| fields | A list of fields associated with this relationship. These provide information about the relationship, for example the percentage of shares held in a 'shareholder' relationship. | List of Fields | - |
| id | The ID of this relationship | Integer | 789557 |
| relatedEntity | The ID of the entity which is related to the business specified in the "businessRelatedTo" field. An example would be the shareholder in a shareholding relationship. A related entity can be a business or an individual. | Integer | 789558 |
| type | The type of this relationship | String | "Company office holder", "Shareholder", "Ultimate Holding Company" etc. |
| verificationNotRequired | 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 | Boolean | "true" or "false" |
| verificationNotRequiredReason | If 'verificationNotRequired' is true, this will detail why the entity is exempt from verification within the context of this relationship | String | "Ownership percentage is below threshold of 25" |
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".
| Field Name | Description | Type | Example |
|---|---|---|---|
| name | The name of this field | String | "controllerType", "additionalInformation", "allocationNumber", "shareAllocation", "totalSharesInCapitalGroup", "ownershipPercentage" etc. |
| value | If present, gives |
| the value of this field. If a field is not populated, then 'value' will not be present or will be empty. | String | "Director" |
| verificationThreshold | 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. | String | "25" |
rootBusiness Object
...
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.
| Field Name | Description | Type | Example |
|---|---|---|---|
| address | A structure encoding the address of the entity entity. Only the country details will be populated. | Address | - |
| businessNumber | The business number for this entity. If the business was manually created or does not have a business number registered within the relevant country then this will not be provided. | String | "111307361" |
| businessStatus | The status of the business as returned from a business register | String | "Registered" |
| businessType | The type of business | String | "company" |
| countryOfRegistration | The country where the business is registered, in the form of a two-letter country code | String | "AU" |
| dataSource | Details on the data source (e.g. a company register) used for getting information on this entity. | DataSource | - |
| documents | A list of documents associated with this entity | List of Documents | - |
| entityType | The type of this entity | String | "business" |
| existenceVerified | Whether or not the existence of this entity has been verified or not | Boolean | "true" or "false" |
| foundInRegister | Whether or not this entity was found in a company register | Boolean | "true" or "false" |
| fromDataSource | Whether or not this entity came from a data source (e.g. a lookup of a company register). | Boolean | "true" or "false" |
| id | The ID of this entity | Integer | 1097 |
| name | The name of this business | String | "Acme Pty Ltd" |
| notes | A list of notes associated with this entity | List of Notes | - |
| verification | A structure encoding verification details for the entity | Verification | - |
| verificationNeverRequired | Whether or not verification is required for this entity | Boolean | "true" or "false" |
...