| 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.
...
<<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?>>
| Field Name | Description | Type | Example |
|---|---|---|---|
| address | A structure encoding the address of the entity | Address | - |
| dataSource | 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'>> | <<??>> | - |
| 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 details about this entity was retrieved were obtained from a data source (e.g. a lookup business register* (i.e. this will be 'true' if if the results from a lookup of a business on a business register ).(Note: the individual's details retrieved may have subsequently been edited by a user)included details of this individual. Example: The results of lookup of a company included details of an individual who is a director). | 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 | |||||
|---|---|---|---|---|---|---|---|---|
| address | A structure encoding the address of the entity | Address | - | businessNumber | The business number for this entity. 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. g. a company 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 entitybusiness | List of Documents | - | |||||
| entityType | The type of this entity | String | "business" | |||||
| existenceVerified | Whether or not the existence of this entity business has been verified or not. 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 entitybusiness was found inon a company register | Boolean | "true" or "false" | fromDataSource | 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 |
| Boolean | "true" or "false" | id | The ID of this entity | 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 | - | |||||
| verificationNeverRequiredWhether or not verification is required for this entity | 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 ObjectObject
<<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>>
| 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" |
DataSource Object
<<KS: Don't think this exists anymore...>>
| Field Name | Description | Type | Example |
|---|---|---|---|
| name | The human-readable name of this data source | String | "the New Zealand Business Number Register" |
| type | The type of the business returned | String | "company (nzco)" |
...
| Field Name | Description | Type | Example |
|---|---|---|---|
| creationTime | The date and time when this document was created (uploaded). Format is UTC (Universal Time Coordinated) | String | "2018-08-15 06:18:19.929+0000" |
| documentURL | A URL where this document can be downloaded from | String | "https://au.vixverify.com/vixbiz/api/v1/document/1854" |
| evidenceType | The type of evidence that this document isprovides | String | "Statutory declaration" |
| fileSize | The size of the document file, in bytes. | Integer | 297054 |
| name | The original document filename | String | "file.pdf" |
| verification | The verification associated with this document | Verification | - |
...
| Field Name | Description | Type | Example |
|---|---|---|---|
| author | The author of a note | String | john.doe@example.com |
| context | If present, the context thatin which the note is associated withwas added e.g. when exempting an itementity 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" |
...
| 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 |
| greenIDVerificationIdIf | present, gives the GreenID verification ID for this verificationOnly applicable 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?>> | String | "Verified" |
Relationships
...