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 15 Nov 2018

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: 'Proprietary Company', 'Public Company' AU - Partnership: 'Standard Partnership', 'Limited Liability Partnership' AU - Trust: 'Regulated Trust', 'Discretionary Trust', 'Testamentary Trust', 'Unit Trust', 'Self Managed Super Fund' AU - Other: 'Association', 'Co-Operative', 'Foreign Business' NZ - Company: 'NZ limited company', 'NZ unlimited company', 'NZ co-operative company', 'Overseas ASIC company', 'Overseas non-ASIC Company' NZ - Partnership: 'Partnership', 'Limited partnership (NZ)', 'Limited partnership (Overseas)' NZ - Trust: 'Trading trust', 'Charitable trust', 'Testamentary trust', 'Discretionary trust', 'Family trust', 'Unit trust', 'Foreign trust' NZ - Other: 'Association', 'Co-Operative', 'Government agency', 'Foreign Business' Any other country - Company: 'Listed company', 'Private company', 'Public company' Any other country - Other: 'Partnership', 'Trust', 'Association', 'Co-operative', 'Government agency'	"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 'GET' call greenID Business API: businessVerification - GET 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