Introduction - JSON API

Introduction
Versioning
Authentication
Handling errors
Rate Limiting Requests

1.0 Introduction

The eFiling JSON API runs on two main protocols: GET and POST, all responses will return a JSON Object.

Users will be given an API key which they need to use on every request.

2.0 Versioning

Versions will increment in whole numbers and users will be informed prior to release.

'None breaking' changes will not receive a version increment. An example of a minor change would be adding a new value to the response values or a new optional values to the request.

'Breaking changes' will require a version increment. A breaking change will result either the request or response no longer being compatible due to the removal or changes to the request/responses.

3.0 Authentication

An API key must be sent with every request made against the API, an authentication header would look like this:

curl --header "Authorization: Basic [your auth key]" https://json.efiling.co.uk/2/[endpoint]

All request are encrypted. HTTPS protocol should be used on every request made to the api.

4.0 Handling errors

All json end-points will return and error value. 0 means that the end-point was successfully completed anything other than 0 would mean an error has occurred.

5.0 Rate Limiting Requests

During the hours of 08:00 and 18:00 every day we limit the number of requests per Brand to 120 every 60 seconds. During the hours of 18:01 and 07:59 every day we limit the number of requests per Brand to 180 every 60 seconds.

These restriction are per brand.