API Versions
This documentation relates to Version 1, the current version of the greenID Business API. This POST functionality became available to customers as of
Overview
The greenID Business API 'businessVerification' endpoint, when accessed via an HTTP 'POST' command, allows you to programatically create a verification in the greenID Business system.
Accessing businessVerification via 'POST'
The greenID Business API endpoint 'businessVerification' is available as a RESTful endpoint. To utilise this to automatically create a verification in the greenID Business system, the following URL should be called using the HTTP POST method:
https://au.vixverify.com/vixbiz/api/v1/businessVerification
If you wish to access the API in the TEST environment, then the following URL should be used instead:
https://test-au.vixverify.com/vixbiz/api/v1/businessVerification
Unlike the corresponding GET call, information is not passed in using parameters in the request URL. Instead, when using the POST call the system expects information to be passed in using the JSON format, transmitted via the HTTP request body.
Input Parameters
Creating a Verification Using a Business Number Lookup
A sample call using the "curl" program:
curl -u <customer_id>:<web_service_password> -H "Content-Type: application/json" -d '{"businessNumber":"123456789", "businessNumberType":"NZBN", "dataSourceCountry":"NZ" }' https://test-au.vixverify.com/vixbiz/api/v1/businessVerification
Here we can see that authentication information is passed in via the -u parameter. For authentication requirements when using the greenID Business API, see Version 1 greenID Business API - Authentication.
The content type of the request body is specified as JSON, and the body contains a JSON string, which specifies the details to look up in order to create the verification. Details on the input parameters for this business lookup call are as follows:
| Name | Type | Required | Description | Valid Values | Example(s) |
|---|---|---|---|---|---|
| businessNumber | String | Yes | The business number to lookup in the appropriate register | Must be numeric value and of the required length for the specified businessNumberType. | '123456789' |
| businessNumberType | String | Yes | The type of the business number to be used to perform the lookup. The type specified will determine the register used to lookup the specified business number The businessNumberType specified must be a valid type for the dataSourceCountry specified. | For dataSourceCountry = 'AU': 'ABN' - Search the Australian Business Register (ABR) for the specified ABN (Australian Business Number) 'ACN' - Search ASIC's Business Register for the specified ACN (Australian Company Number) / ARBN (Australian Registered Body Number) / ARSN (Australian Registered Scheme Number) For dataSourceCountry = 'NZ': 'NZBN' - Search the NZBN Register (New Zealand Business Number Register) with the specified NZBN 'NZCN' - Search the NZBN Register (New Zealand Business Number Register) with the specified New Zealand Company Number or other Organisation Number | 'ACN' |
| dataSourceCountry | String | Yes | The country relevant to the data source (Business Register) to be searched. Note: Your account must be configured for businesses in the specified country. | 'AU' - Australia. 'NZ' - New Zealand | 'AU', 'NZ' |
Creating a Verification by Specifying Business Details
A sample call using curl:
curl -u <customer_id>:<web_service_password> -H "Content-Type: application/json" -d '{"manual":true, "countryCode": "AU", "business":{"name":"Griffith Trust","businessType":"trust","subtype":"Regulated Trust", "businessNumber":"1234"}}' https://test-au.vixverify.com/vixbiz/api/v1/businessVerification
Details on the input parameters in the JSON are as follows:
| Name | Type | Required | Description | Valid Values | Example(s) |
|---|---|---|---|---|---|
| manual | String | Yes | If present (and set to "true") then the system knows that a manual creation of a business verification is being requested | true (if false or no value sent, it is assumed a create via a business lookup is required. Inputs expected are then as per 'Creating a business via business number lookup' above.) | true |
| countryCode | String | Yes | The ISO 1366 country code of the country in which this business is registered or located | A 2 letter country code as per ISO 1366 country codes. (Please note: the code for the United Kingdom is 'GB') | 'AU', 'NZ', 'GB' etc. |
| business | Business | Yes | A JSON structure which describes how particular business fields should be populated. More details on this are given in the 'Business Object' table below | See Business Object table below |
Business Object
| Name | Type | Required | Description | Valid Values | Example(s) |
|---|---|---|---|---|---|
| name | String | Yes | The name of the business to be created | Alphabetic, numeric and certain special characters | "ACME Trust" |
| businessType | String | Yes | The type of the business to be created | The valid Business Types are dependent on the countryCode provided: AU or NZ: 'company', 'partnership', 'sole trader', 'trust', 'other' Any other country code: 'company', 'other' Note: These are the default valid values. If your account has been configured to remove any of the default types, then they will not be valid via the API either. | "trust" |
| subtype | String | No | If applicable, the subtype of the business. There are standard, recommended subtypes for each businessType within a country (as listed in valid values), but you are not restricted to only these options. You can submit your own subtype if required. Certain business types may not have a subtype, such as a Sole Trader - therefore this field is optional. It is recommended that you always provide a subtype if you specify a businessType of 'other'. | Any textual value may be provided (apart from certain restricted special characters). It is however recommended that you use the below standard subtypes where relevant. The default standard types per country / business type are : AU - Company: AU - Partnership: AU - Trust: AU - Other: NZ - Company: NZ - Partnership: NZ - Trust: NZ - Other: Any other country - Company: Any other country - Other: | "Regulated Trust" |
| businessNumber | String | No | If applicable, a single business number for this manually created business. | Must be a numeric value | "123456789" |
Output
The output of a successful call to the endpoint will be a single verification ID / reference number ('verificationId') which identifies the verification that has just been created. You can then use a /wiki/spaces/~karen.soesman/pages/393805869 to the endpoint to get the full details for this verification, using this verification ID.
Exceptions and Error Handling
In addition to the types of standard exceptions thrown by the API (as documented on the main API page), the following exceptions are specific to the POST call:
| HTTP Status Code | Error | Error Message | Conditions |
|---|---|---|---|
| 400 | Bad Request | Manual creation requires a business structure to be passed in | The "manual" field is set to true, but no business structure has been passed in |
| 400 | Bad Request | Unable to perform business lookup for country code | A country code was provided for which business register lookups are not supported on your account |
| 400 | Bad Request | Data source business lookups must include a business number | A business register lookup was requested but no business number to search for was input |
| 400 | Bad Request | Business number parameter must be a numeric value | The input business number contains non-numeric characters |
| 400 | Bad Request | Business number parameter must be of length ... | The business number does not correspond to the expected length for the specified business number type |
| 400 | Bad Request | businessNumberType cannot be empty | A business register lookup was requested but an empty string was input for the business number type |
| 400 | Bad Request | Input business type: <businessType> not found for country code: <countryCode> | The given businessType is not supported for the given country code |
| 400 | Bad Request | Missing required business type parameter | For a manual creation the required business type was not input |
| 400 | Bad Request | Missing required business name parameter | For a manual creation the required business name was not input |
| 400 | Bad Request | Missing country code parameter | No countryCode (manual creation) or dataSourceCountry (lookup) was provided |
| 400 | Bad Request | Invalid country code parameter | The input country code does not match any of the ISO country codes known about by the system |
| 400 | Bad Request | countryCode cannot be empty | An empty string was input for the country code |
| 400 | Bad Request | No matching customer configuration for input countryCode | This customer does not have the input country code enabled on their account |
| 400 | Bad Request | Only one business number is supported for manual creation of a business | More than one business number was input |
Home | greenID API | greenID Web | greenID Mobile | greenID Business | greenID Additional Services | Notification of Verification | Admin Panel Guide
If you can't find what you need here, email us at customer.support@gbgplc.com or log a ticket via our portal