Imagine one powerful API that gives you instant access to global commercial register data.

BREX API OVERVIEW

The BREX API is a lightweight RESTful webservice which can be used to search for corporate and related information, and to order and retrieve documents. Requests are sent through an HTTPS channel, the reply will be in JSON for data or PDF for report delivery – further formats may be added in future. The content and format of a response varies with the request and chosen subscription model, examples are given in the appendix.

The API is separated into logical functional groups which follow the general format of:

version/object/method/parameter1/.../parameter

It is important to note that parameter1 to parameterX may possibly include reserved URI characters, and must therefore be URL encoded to the current standard (RFC3986). Any components of the URL preceding the parameter sections will not require encoding, but will also be defined in such a way that encoding them would have no effect.

The valid 'object' values at the time of writing are:

• company used to search for and access company data
• product used to list, order and retrieve products

Valid 'method' values are:

• (none) used to access an object directly by specifying a returned BREX id – e.g. a Company record or an ordered product
• search used to return a list of objects that match the parameters following
• availability used to check the actual availability of a product for a given company
• buy used to order a product
• status get the current status of an ordered product

ONLINE DOCUMENTATION

BREX Enterprise API uses a 'live' online documentation method – this allows readers to see the format of the request URLs, any parameters, the actual URLs called and the structure of the responses. It is also synchronized with the API code, so it is always correct, and even allows the API to be driven via the website, which makes testing a much simpler operation that conventional techniques. The information supplied by this live documentation can assist greatly in writing one's own interface to the BREX API. This documentation is available to anyone with an API key and can be accessed at: http://docs.brex.io/active-docs

API AUTHENTICATION (HTTP BASIC)

BREX Enterprise API uses a simple key authentication mechanism over HTTPS - this is safe because your API key is securely encrypted by the SSL channel. The easiest way to test the API is to use the online live documentation – this is a web page which allows you to test the various API methods and handles all the communications for you, whilst showing you the appropriate URLs. Brex will provide client code in php and java in due course.

When you are ready to write code to access the API, you simply pass your API key as an HTTP header called user_key. This key is used by the API to determine who you are, your access rights and your costs - keep this key secret and safe!

REGENERATING AN API KEY

Your API key can be regenerated by clicking on the Regenerate button on your dashboard page.

Note: Only one API key may be active on an account per plan at a time. If you choose to regenerate your API key, your services will not work until you’ve updated all references to your API key. There is only one API key per plan. Regenerating the key will regenerate it for all users.

API HOST

api.brex.io

ADDITIONAL HEADERS

Brex Enterprise API currently returns results only JSON. If the accept header is specified it should be application/json, but will be ignored. Including this header, however, will future proof your client code.

Accept: application/json

CONTENT-TYPE-HEADER

Brex Enterprise API currently returns results only JSON. If the content-type header is specified it should be application/json, but will be ignored. Including this header, however, will future proof your client code.

Content-Type: application/json; charset=utf-8
  Accept: application/json

If your JSON or XML request is invalid, the API will respond with a status code 400 Bad Request. This commonly occurs when ampersands are not correctly encoded in the text of your request. Please inspect the body of the response for more details regarding the error. However, please note that at the time of writing there are no API methods that correspond to a 'create' or 'update' request -therefore this is for future reference only.

HTTP STATUS CODES

Every request includes an HTTP status code with the result. The status code should examined before the response. The online documentation provides up to date status code information, however in general the response codes can be interpreted as:

• 200–299 as success,
• 400–499 as client request errors,
• 500–599 as server errors

API OBJECT MODEL

The API method calls are documented in the online system, but the general object structure and sequence is as described below:

At the time of writing there are 4 basic objects – Company, Product, ProductOrder and ProductOrderNotifier.

A typical use case would be:

• search for a Company by name or registration number – returns an array of Company objects that match API method: /company/search/name/{country code}/{name} or /company/search/name/{country code}/{registration number}
• select the appropriate Company from the returned array and get more details – returns a populated Company object. The level of information in the object is determined by the request, but there may be pricing differences and availability differences depending on your API plan API method: /company/{company id}?dataset=mini/master/full (defaults to mini)
• search for possible Product available for that Company – returns an array of Product objects which includes the BREX SKU API method: /product/search/{company id}
• check the actual availability for the selected Product – returns an updated Product object with availability status and whether there are options available (e.g. accounts year) API method: /product/availability/{sku}/{company id}
• place an order for that product – returns a ProductOrder object API method: /product/order/{sku}/{company id} or /product/order/{sku}/{option}/{company id} (where there are options available)
• check the status of the ProductOrder object to see when it is ready. Loop here every 60 seconds until ready or the product is marked as failed for some reason API method: /product/status/{product order id}
• retrieve the ordered product – will return a byte stream containing the product in an appropriate format as per the response content-type header API method: /product/{product order id}

Note the status checking here is done via polling. There is an alternative method by using a ProductNotifier. This allows BREX to notify the customer when a product is ready. To use a ProductNotifier, replace step (6) with the following:

• 6 Create a ProductOrderNotifier passing in a URL which will be called using HTTP GET. Note – the callback URL MUST have any forward slashes (/) converted to tilde characters (~) API method: /product/notifier/{product order id}/GET/{callback url}
• 6a Wait for the callback from BREX to the URL you supplied. The URL will be called with added parameters of orderId={product order id} and notifierId={the id of the product order notifier as created in step 6)

The use of a notifier does not preclude the polling method but is more efficient for everybody.

TEST AREA

Authorzie with your API key to start testing

If you don't have an account yet check the BREX API Technical Documentation on page 10 for a sandbox key you can use for your tests.