| 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: Is the above sufficient for a developer to know how to use this?>>
Exceptions and Error Handling
...
| Code Block |
|---|
{
"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)
...
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).
...
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... >>
| Code Block |
|---|
http://au.vixverify.com/vixbiz/api/v1/businessVerification/<verification_reference_id> |
...
The output from the get BusinessVerification call will be in JSON format, and contains four main sections:
- businessVerificationReference
- Entities
- Relationships
- rootBusiness
...
- : This is the reference number of the business verification you returned. This should match the reference number you requested.
- Entities: This contains details of the businesses and individuals that exist within the business structure. Each of these will have a unique ID.
...
- Relationships: This contains details of the relationships between the entities within the business structure e.g. Individual A is a shareholder of Business X
- rootBusiness: This contains the summary 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. If you simply require the summary details for the business you are aiming to verify (i.e. the root business or top level business), and do not require full details of the business structure, then this is the section to refer to.
businessVerificationReference
...
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?. all name fields together?>>
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 were obtained from a business register* (i.e. this will be 'true' if if the results from a lookup of a business on a business register 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" |
...
| Field Name | Description | Type | Example |
|---|---|---|---|
| address | A structure encoding the address of the entity For a business entity, only the country will be provided. If however the 'countryOfRegistration' is populated, then no address details will be populated. <<KS: Clarify this... if a business, does it only have country code? Doesn't always seem to have this thoughis this working as intended? Why isn't country always populated?>> | 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" |
...
| 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) Only applicable to New Zealand addresses | String | "NELSON" |
| 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 |
|---|---|---|---|
| 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 |
|---|---|---|---|
| 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" |
...
| 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
...