API v3 Introduction

The Red Flag Alert API provides advanced search capabilities and access to detailed information on millions of UK businesses. With full integration into the Companies House filing history document API, PDFs of submitted documentation can also be obtained from one easy point.

This documentation site provides an introduction on how to use it and details of its capabilities.

Versions

At this present time, the current version of the API is v3. As new features are added, any that have the potential to break backwards compatibility will always be introduced on a new version number of the API, leaving the existing API version untouched.

However, any new features introduced in this way will only be available in the new version of the API, i.e. version v4.

Authentication

API users are provided with an API key and secret. Please contact us for prices.

Authentication is handled using HTTP Basic Authentication:

Authorisation: Basic xxxxxx

where 'xxxxx' is the result of base64 encoding the api key and secret.

Most programming languages will have a library to handle this. For example, in Python the requests library can make an authenticated request by doing:

requests.get('https://api2.redflagalert.net/v3/companies/', auth=('key', 'secret'))

If you have any problems with authentication in your chosen language, please contact us for assistance.

Format/ Pagination

The Red Flag Alert API follows the JSON API (http://jsonapi.org) format and uses the REST architectural style with JSON throughout.

All responses will be returned as JSON, with the requested data being returned in the 'data' key of the response.

When performing a search, pagination links will be available as per the JSONAPI standard in a field called 'links', with 'first', 'previous', 'next' and 'last' links allowing navigation.

MIME Types

JSON API has been properly registered with the IANA. Its media type designation is application/vnd.api+json.

Generating PDF Responses

In addition to the standard JSON response, companies can be requested formatted as PDF documents. In order to request this, change the 'Accept' header of your request to 'application/pdf'. Currently, this is only supported by the company/ endpoint.

The PDF document will also include any extra resources requested in the '?include=' GET parameter and therefore can be used to construct a full company report by appending '?include=all' to the URL (See 'Including Additional Resources').

Browsable API

To assist developers, a browsable API is available enabling the viewing and navigation of records in the browser. This can be accessed by visiting the corresponding URL in a browser; the API will detect that a browser is being used and displays records accordingly. A username and password will be requested; this is simply the API key and secret.