# API 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 **`v4`**. 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 **`v5`**.
# 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](http://docs.python-requests.org/en/master/) library can make an authenticated request by doing:
```python
requests.get('https://api2.redflagalert.net/v4/companies/', auth=('key', 'secret'))
```
If you have any problems with authentication in your chosen language, please contact us for assistance.
# Format & Pagination
### Format/ Pagination
The Red Flag Alert API follows the JSON API ([http://jsonapi.org](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`](http://www.iana.org/assignments/media-types/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.
# Company
The core of the Red Flag API revolves around the '`companies`' route. All searches directly relating to a company will be performed using this route.
For example, where a companies registered number is known, you can return the API's information about that company using the URL below.
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/
```
### JSON Structure:
All data is returned in the JavaScript Object Notation (JSON) format. The Red Flag Alert API is RESTful, and follows the JSON API ([http://jsonapi.org](http://jsonapi.org/)) format.
```javascript
{
"data": {
"relationships": [{
"group-company": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/group-company"
}
}
}, {
"ccjs": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/ccjs/"
}
}
}, {
"addresses": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/addresses/"
}
}
}, {
"balance_sheet": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/balance-sheet/"
}
}
}, {
"shareholders": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/shareholders/"
}
}
}, {
"cashflow": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/cashflow/"
}
}
}, {
"contacts": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/contacts/"
}
}
}, {
"directorships": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/directorships/"
}
}
}, {
"profit_loss": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/profit-loss/"
}
}
}, {
"mortgages": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/mortgages/"
}
}
}, {
"ratio_analysis": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/ratio-analysis/"
}
}
}, {
"unpaid_losses": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/unpaid-losses/"
}
}
}, {
"filing-history": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/filing-history/"
}
}
}],
"attributes": {
"dissolution_date": null,
"website": "www.britishairways.com",
"name": "BRITISH AIRWAYS PLC",
"dissolution_status": null,
"company_type": "plc",
"company_number": "01777777",
"company_aims": "A group engaged in the operation of international & domestic scheduled air services for carriage of passengers, freight & mail & the provision of ancillary services.",
"legal_status": "Quoted",
"rfa_rating": {
"health_rating_code": 5,
"credit_limit": 2000000,
"short_code": "bronze",
"trading_payment_parity": 31,
"short_description": "Bronze",
"long_description": "Bronze companies will be an average credit risk whose financial position and trading results are not as strong as Silver companies. They may even be new companies that have yet to file their accounts. It is likely that not all payments are made to terms and it is advisable to review any monitoring notices received on these companies"
},
"TPS": false,
"auditor": "Ernst&YoungLLP",
"incorporation_date": "1983-12-13",
"sic_codes": [
"62101",
"62201",
"63110",
"63230"
]
},
"type": "company",
"id": "01777777",
"links": {
"self": "https://api2.redflagalert.net/v4/companies/01777777/"
}
}
}
```
# Other Resources
Additional information about a company can be accessed using the following endpoints. These endpoints are conditionally linked in the “relationships” section of an individual company return should they be available. For example when requesting information about a company that has shareholder information available, the “shareholders” entry will be returned in the “relationships” section.
Making a request to the following endpoints that has not been linked from the company return may result in a 404 (Resource not found) error if the company does not have the relevant information.
An example of the json structure of each endpoint can be viewed by clicking on the endpoint.
| Endpoint | Description | Example |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | --------------------------- |
| [`/{company_number}/directorships/`](/directors/directorship) | A list of directors and their involvement with this company. | `/01777777/directorships/` |
| [`/{company_number}/addresses`](/company-resources/addresses) | A list of all addresses, both trading and registered, associated with the company. | `/01777777/addresses/` |
| [`/{company_number}/shareholders/`](/company-resources/shareholders) | A list of shareholders and information about the shares they hold. | `/01777777/shareholders/` |
| [`/{company_number}/ccjs/`](/company-resources/ccjs) | Information about any CCJs (County Court Judgements) found for the company. | `/01777777/ccjs/` |
| [`/{company_number}/group-company/`](/company-resources/group-company) | A list of companies that the current company is parent company of. | `/01777777/group-company/` |
| [`/{company_number}/parent-company/`](/company-resources/parent-company) | The company which is the parent company of this one. | `/01777777/parent-company/` |
| [`/{company_number}/previous-names/`](/company-resources/previous-names) | Previous names this company has been registered as at Companies House. | `/01777777/previous-names/` |
| [`/{company_number}/contacts/`](/company-resources/contacts) | Where contact information has been registered for this company, this endpoint will show those contact details. | `/01777777/contacts/` |
| [`/{company_number}/ratio-analysis/`](/company-resources/ratio-analysis) | Calculated ratios for various financial indicators for the business. | `/01777777/ratio-analysis/` |
| [`/{company_number}/profit-loss/`](/company-resources/profile-loss) | Standard profit and loss numbers for a particular year. | `/01777777/profit-loss/` |
| [`/{company_number}/cashflow/`](/company-resources/cashflow) | Cashflow report for a particular year. | `/01777777/cash-flow/` |
| [`/{company-number}/balance-sheet/`](/company-resources/balance-sheet) | Balance sheet for a particular year. | `/01777777/balance- sheet/` |
| [`/{company-number}/mortgages/`](/company-resources/mortgages) | List of mortgages found for a company. | `/01777777/mortgages/` |
| [`/{company_number}/filing-history/`](/company-resources/filing-history) | List of documents filed with Companies House. | `/01777777/filing-history/` |
| [`/{company_number}/unpaid-debt/`](/company-resources/unpaid-debt) | The value of unpaid debt associated with a debtor who has entered formal insolvency proceedings. | `/01777777/unpaid-debt/` |
| [`/{company_number}/unpaid-losses/`](/company-resources/unpaid-losses) | The amount of unpaid losses associated with a creditor entering formal insolvency proceedings. | `/01777777/unpaid-losses/` |
# Including additional resources
In order to reduce the number of requests that applications need to make, additional resources can be requested for a company in a single request. This can be achieved by appending the '?include=' GET parameter to the call followed by the list of resources separated by a comma.
For example, to retrieve the the directorships and addresses in addition to its standard company information in a single call, the following URL can be requested:
```
https://api2.redflagalert.net/v4/companies/01777777/?include=directorships,addresses
```
The directorships and addresses returned will be the same as those returned in the following endpoints:
```
https://api2.redflagalert.net/v4/companies/01777777/directorships/
https://api2.redflagalert.net/v4/companies/01777777/addresses/
```
In addition, a special ‘all’ parameter can be added to return all of the above information. For example:
```
https://api2.redflagalert.net/v4/companies/01777777/?include=all
```
All requested resources will be listed in the '`included`' section of the return that is on the same level as '`data`' for the parent company resource. Each will contain a '`type`' and '`ID`' key along with an '`attributes`' key listing the actual data.
Inside the company resource's '`data`' section, the appropriate '`relationships`' elements will also be extended with the ID and the type of the included resources following the JSON API format.
If an invalid resource name is requested or the company does not have the appropriate data, it will be ignored. If a resource name is requested multiple times, it will still only be returned once.
Please note, that due to the nature of some of the queries such as `filing-history`, not all endpoints can be included.
Those included in the '`?include=all`' parameter are:
# Attributes
The following fields are currently available:
| Field Key | Description | Notes |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `latest_action` | A dictionary consisting of the keys 'action' describing the latest action as a string and 'date' in isoformat. | |
| `dissolution_date` | Date the company was dissolved if applicable. | |
| `website` | Company website URL if known. | |
| `name` | The name we have for this business. | |
| `dissolution_status` | For companies that have been dissolved, their exact status. | See [Appendix 1](/appendix/dissolution-status-codes) for possible values. |
| `company_type` | A description of the company type, such as private limited company; public limited company, limited liability partnership etc. | |
| `company_number` | The Companies House identification number for the company. | |
| `company_aims` | Description of the sims of the company. | |
| `legal_status` | Detailed legal status of the company. | |
| `rfa_rating` | The Red Flag Alert credit rating currently assigned to this company | A JSON object containing the fields: `health_rating_code`, `credit_limit`, `short_code`, `trading_payment_parity`, `short_description`, `long_description` |
| `tps_registered` | Boolean value showing if the company has registered with the Telephone Preference Service. | |
| `auditor` | Name of the company's auditor, if any. | |
| `incorporation_date` | The date of first registration of the Company at Companies House. | |
| `sic_codes` | Array of SIC codes for this company | |
| `sic_groups` | Array of SIC groups for this company | |
| `sic_group_descriptions` | Array of SIC group descriptions for this company | |
| `sic_divisions` | Array of SIC divisions for this company | |
| `sic_division_descriptions` | Array of SIC division descriptions for this company | |
| `sic_classes` | Array of SIC classes for this company | |
| `sic_class_descriptions` | Array of SIC class descriptions for this company | |
| `sic_sub_classes` | Array of SIC sub-classes for this company | |
| `sic_sections` | Array of SIC sections for this company | |
| `sic_sections_descriptions` | Array of SIC section descriptions for this company | |
| `vat_number` | EU formatted tax number if registered for VAT | |
| `parent_company_number` | | |
| `employees` | If available, number of actual employees | |
| `estimated_employees` | If available, estimated number of employees | |
| `estimated_turnover` | If available, estimated turnover | |
| `start_date_year` | | (non limited only) |
| `gdpr` | | |
| `creditor_days` | Average time it takes a business to settle its debts with trade suppliers | |
| `group_id` | | |
| `type` | Currently, always ‘company’. | This is required by the JSONAPI format. |
| `id` | Unique identifier for this business, | For registered companies this will be the Companies House number; for others it will be a unique identifier. |
# Search
The main endpoint for retrieving businesses is `/companies/`. When called without any parameters, this will return all available businesses in the database.
In order to perform searches, various filters are added to the companies. These can all be combined together; for example, to retrieve all manufacturing (SIC section D) companies near the centre of Oldham the query would be:
```
https://api2.redflagalert.net/v4/companies/?sic_section=D&postcode=OL11HD&distance=3miles
```
#### Results per page
By default a single search response page contains 50 results. This can be overridden by sending the `results_per_page` parameter as a valid integer:
```
https://api2.redflagalert.net/v4/companies/?postcode=OL11HD&results_per_page=100
```
#### Search Parameters
Various search filters are available and we expect these to be steadily added to as the API develops. If you require a search which is not currently available, please [contact us](mailto:helpdesk@redflagalert.com) to suggest it.
| Search Parameter | Description | Examples | Notes |
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `postcode` | Search within a specified radius of a UK postcode. |
Returns businesses with postcode SW1A 2AA
| Where we have multiple addresses for a business, if any of them match the postcode filter then the business will be included in the search results. |
| `distance` | Search within a specified radius of a UK postcode. |
Returns businesses within a 3 mile radius of SW1A 2AA
| Where we have multiple addresses for a business, if any of them match the postcode filter then the business will be included in the search results. |
| has\_contact
has\_phone\_contact
has\_email\_contact
| Filter companies based on available contact information. |
Returns companies which have a contact phone number or a contact email address.
Returns companies which have a contact email address.
Returns companies with no contact email address but with a contact phone number.
| All of these filters take a boolean value; e.g. 'true' or 'false'. |
| `exclude_non_trading` | Filter out non-trading companies (rated 'Discontinued', 'Dissolved', 'Not-trading' or 'Strike Off'). | `https://api2.redflagalert.net/v4/companies/?exclude_non_trading=true` | The filter does not return only non trading companies if set to 'false'. |
| `has_filed_accounts` | Filter companies with accounting data i.e. who have filed accounts. | `https://api2.redflagalert.net/v4/companies/?has_filed_accounts=true` | Returns companies which have at least one set of figures for balance sheet, profit and loss, cashflow, or ratio analysis. Setting it to false will only return companies who have none of these data. |
| `is_limited` | Filter search results to include/exclude registered/limited companies. |
Only returns companies which are registered/limited.
| This filter takes a boolean value; e.g. 'true' or 'false'. |
| `match_name` | A simple closest text match on the name of the business. |
Will return Red Flag A!ert first, followed by other similar matches.
| |
| `auditor` | Query on the name of the business's auditor | `https://api2.redflagalert.net/v4/companies/?auditor=begbies` | |
| `auditor_match_name_prefix` | Match text at the beginning of the business's auditor | `https://api2.redflagalert.net/v4/companies/?auditor_match_name_prefix=begbies` | |
| `match_name_prefix` | Also a text match, but focuses on the beginning of the company name. | flag
Returns all businesses whose name starts with ‘red flag’.
| Most commonly used for autocomplete-style search |
| min\_birthdate
max\_birthdate
| Earliest and latest birthdays of current directors |
Returns all businesses with current directors born in January, February or March 1987.
| Exact dates are not available for data protection reasons |
| min\_employees
max\_employees
| Range search on the reported number of employees for the business. |
Returns all companies with between 5 and 50 employees.
| Can specify min or max parameters. To search within a range, specify both. |
| min\_combined\_employees
max\_combined\_employees
| Range search across the estimated or actual number of employees, according to availability. |
Returns all companies with between 50 and 100 estimated or actual employees.
| |
| min\_incorporation\_date
max\_incorporation\_date
| Retrieve companies registered in a particular date range. |
Return companies established on or after the 9th of February 1987.
Return companies established between 1977 and 1987.
| Supply valid dates in ISO-8601 standard YYYY-MM-DD format. Can specify min or max parameters. To search within a range, specify both. |
| min\_total\_assets
max\_total\_assets
| Search on the last available total assets figure. |
Returns companies with most recently reported assets of between £50k and £100k.
| Can specify min or max parameters. To search within a range, specify both. |
| min\_turnover
max\_turnover
| Search on the last available turnover figure for a business. |
Returns businesses with last reported turnovers of between £50k and £100k.
| Can specify min or max parameters. To search within a range, specify both. |
| min\_combined\_turnover
max\_combined\_turnover
| Search across the estimated or actual turnover, according to availability. |
Returns all companies with between 50,000 and 100,000 estimated or actual turnover.
| |
| `min_credit_limit` `max_credit_limit` | Range search on the `credit_limit` figure found in the `rfa_rating` section of a company | `https://api2.redflagalert.net/v4/companies/?min_credit_limit=50000&max_credit_limit=100000` | |
| `min_credit_score` `max_credit_score` | Range search on the `credit_score` figure found in the `rfa_rating` section of a company (0 to 100) | `https://api2.redflagalert.net/v4/companies/?min_credit_score=75&max_credit_score=90` | |
| `min_last_filed_accounts` `max_last_filed_accounts` | Range search on the date the company last filed their accounts in YYYY-MM-DD format | `https://api2.redflagalert.net/v4/companies/?min_last_filed_accounts=2020-05-30` | |
| `has_directorships` | Filters companies that have at least one directorship record. | `https://api2.redflagalert.net/v4/companies/?has_directorship=true` | |
| sic\_section
sic\_section\_search\_type
| Filter by the top-level SIC Section to which the company belongs. |
Returns all construction businesses in the database.
Multiple section can be searched, in which case results will containe businesses that have any of the supplied codes:
In order to only get results that match all of the supplied sectors, supply the 'sic\_section\_search\_type' parameter:
| SIC section headings and letter codes given in [Appendix 2](/appendix/sic-sections). Companies may have several SIC sections if they are active in several areas; in this case, if any of the sections match then the company will be returned. |
| sic\_code
sic\_code\_search
primary\_sic\_code
| Filter on the exact SIC codes a company has. |
Returns companies with the SIC code 51519.
Returns companies with the SIC code 51519 or 51511.
Returns companies with at least the SIC codes 51519 and 51511 assigned.
Returns companies whose primary SIC code is 51519.
Returns companies whose primary SIC code is 51519 or 51511.
| You can supply multiple search parameters, comma separated in list.
By default, a search on a sic\_code will return companies that have any of the listed SIC codes. If you would like to see only companies that have all of the supplied SIC codes, supply the 'sic\_code\_search\_type' parameter ate to 'and' (if not supplied, defaults to 'or').
SIC codes for companies are returned in order of priority, the primary SIC code being the first entry in the list. The primary SIC code itself is a searchable field. Multiple values can be supplied that will match a company that has any one of them as the primary SIC code. Only one value can be present for the 'primary\_sic\_code' therefore you cannot perform an 'and' search on this field as with 'sic code'.
|
| `rating` | The Red Flag Alert credit rating currently assigned to this company. | Returns companies with the specified Red Flag rating e.g:
Returns companies with a 'Bronze' Red Flag rating.
| See [Appendix 3](/appendix/rfa-health-ratings) for a complete list of Red Flag Alert ratings and descriptions. |
| `min_last_updated` `max_last_updated` | Minimum and maximum date filters allowing you to narrow your query down to records updated within a specified time period. | | |
| `tps_registered` | Whether or not the company is registered for the Telephone Preference Service. | | |
| filter\_name | | | |
| company\_type | | | |
| postcode\_area | | | |
| county | | | |
| town | | | |
| country | | | |
| telephone\_number | | | |
| mortgage\_type | | | |
| mortgage\_holder | | | |
| min\_last\_updated | isoformat date | | |
| max\_last\_updated | isoformat date | | |
| min\_latest\_action\_date | isoformat date | | |
| max\_latest\_action\_data | isoformat date | | |
| address\_type | "trading" or "registered" | | |
# Addresses
This endpoint returns any address associated with the business, such as registered addresses, trading address etc.
Using geolocation data, we have also incorporated latitude and longitude coordinates into our addresses. A value in decimal degrees to 5 decimal places is precise to approximately 1 metre.
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/addresses/
```
### JSON Structure:
```javascript
{
"data": [{
"attributes": {
"town": "West Drayton",
"type": "trading",
"location": {
"lat": 51.5373252879822,
"lon": -0.487355421766335
},
"county": "Middlesex",
"postcode": "UB7 0GB",
"address_line_4": null,
"address_line_2": null,
"address_line_3": null,
"address_line_1": "Po Box 365"
},
"type": "address",
"id": "645323-645323"
}]
}
```
### Attributes
| Field Key | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `town` | The town of the registered address. |
| `type` | Type of address, such as trading, registered etc. |
| `location` | A dictionary of key/value pairs containing the latitude and longitude of the business or post code. |
| `county` | The county containing the address. |
| `postcode` | The post code of the business address. |
| address\_line\_1
address\_line\_2
address\_line\_3
address\_line\_4
| Lines of the business address. `null` will be returned on empty lines. |
# Balance Sheet
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/balance-sheet/
```
### JSON Structure:
```javascript
{
"data": [{
"attributes": {
"total_current_assets": 3439000000,
"total_fixed_assets": 7945000000,
"tangible_fixed_assets": 7357000000,
"currency": "GBP",
"pl_account_reserve": 903000000,
"account_date": "2007-03-31",
"working_capital": -186000000,
"trade_debtors": 654000000,
"shareholders_funds": 2211000000,
"stocks": 76000000,
"misc_current_assets": 354000000,
"total_long_term_liabilities": 5548000000,
"creditors_amounts_falling": 3625000000,
"no_weeks": 52,
"total_assets_less_liabilities": 7759000000,
"revaluation_reserve": 0,
"share_capital_reserve": 1308000000,
"total_liabilities": 9173000000,
"total_assets": 11384000000,
"contingent_liabilities": 168000000,
"cash": 2355000000,
"net_worth": 1999000000,
"intangible_assets": 212000000
},
"type": "balance_sheet",
"id": "645323-4273833453"
}]
}
```
### Attributes
| Field Key | Description | Notes |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----- |
| `total_current_assets` | Total value of assets that would normally be converted in to cash over 12 months. | |
| `total_fixed_assets` | Total value of assets that are used by the business but would not normally be converted to cash. | |
| `tangible_fixed_assets` | Total of assets that would normally be converted in to cash over 12 months. | |
| `currency` | The currency used in the presentation of the accounts. | |
| `pl_account_reserve` | The sum of accumulated reserves from past profits. | |
| `account_date` | The date of the accounts. | |
| `working_capital` | The difference between the total current assets and total current liabilities. | |
| `trade_debtors` | The amount owed to the company by its trade debtors. | |
| `shareholders_funds` | The value of the amounts due to shareholders. | |
| `stocks` | The value of unprocessed and unsold goods held by the company. | |
| `misc_current_assets` | The value of unclassified current assets. | |
| `total_long_term_liabilities` | The total value of liabilities, other than to shareholders with a duration of greater than 12 months. | |
| `creditors_amounts_falling` | The value owing to trade creditors. | |
| `no_weeks` | The number of weeks between the start and the end of the financial period. | |
| `total_assets_less_liabilities` | The total value of the assets after deducting all liabilities, except for those owed to the shareholder. | |
| `revaluation_reserve` | The value of reserves accruing from a revaluation of business assets. | |
| `share_capital_reserve` | The value of shareholder equity. | |
| `total_liabilities` | The total value of all liabilities. | |
| `total_assets` | The total value of all assets. | |
| `contingent_liabilities` | Liabilities that may fall due but are contingent upon an outcome not know at the time of the financial statement. | |
| `cash` | The value of cash assets. | |
| `net_worth` | The value of total tangible assets minus total outside liabilities. | |
| `intangible_assets` | The value of assets that don't have a physical nature, such as Goodwill, or Patents etc. | |
# Cashflow
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/cashflow/
```
### JSON Structure:
```javascript
{
"data": [{
"attributes": {
"account_date": "2005-03-31",
"net_from_operating_activities": 1247000000,
"net_from_return_investment_servicing": -150000000,
"no_weeks": 52,
"increase_in_cash": -457000000,
"consolidated": "Y",
"net_before_financing": 694000000,
"currency": "GBP",
"net_from_financing": -1151000000
},
"type": "cashflow",
"id": "645323-2674607417"
}]
}
```
### Attributes
| Field Key | Description | Notes |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----- |
| `account_date` | The date of the accounts | |
| `net_from_operating_activities` | Cash value generated from operations | |
| `net_from_return_investment_servicing` | Cash value of returns on investments and servicing of finance | |
| `no_weeks` | The number of weeks between the start and the end of the financial period | |
| `increase_in_cash` | Gross increase in cash value | |
| `consolidated` | Some cash flow statements will be group consolidated cash flow statements as opposed to individual cash flow statements | |
| `net_before_financing` | The net cash value from operations | |
| `currency` | The currency used in the presentation of the accounts | |
| `net_from_financing` | The net cash value from external finance | |
# Contacts
If a company has a registered designated contact, this endpoint will list those contacts.
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/contacts/
```
### JSON Structure:
```javascript
{
"data": [
{
"attributes": {
"telephone": "03444930787",
"email": null
},
"type": "contact",
"id": "645323-3833508046"
}
]
}
```
### Attributes
| Field Key | Description | Notes |
| ----------- | ------------------------------------------------------------------- | ----- |
| `telephone` | The listed telephone number if known. Will return '`null`' if none. | |
| `email` | The listed email address if known. Will return '`null`' if none. | |
# CCJs
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/ccjs/
```
### JSON Structure:
```javascript
{
"meta": {
"outstanding": 7
},
"data": [{
"attributes": {
"status": null,
"court": "COUNTY COURT BUSINESS CENTRE",
"date_satisfied": null,
"amount": 506,
"address": "PO BOX 5619, S506, SUDBURY, CO10 2PG",
"date": "2014-11-25",
"type": "JG"
},
"type": "ccj",
"id": "645323-645323-A0QZ236F"
}]
}
```
### Attributes
| Field Key | Description | Notes |
| ---------------- | ----------------------------------------------------------------- | ----- |
| `status` | Indicates whether the CCJ has been registered as satisfied or not | |
| `court` | The name of the court that the CCJ is registered with. | |
| `date_satisfied` | The date that the CCJ was satisfied. | |
| `amount` | The amount/value of the CCJ, in GBP £. | |
| `address` | The defendants address | |
| `date` | The date that the CCJ was assigned. | |
| `type` | Indicates the level of the court | |
# Directorships
The directorships endpoint returns JSON objects for each directory involved and registered with the business.
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/directorships/
```
### JSON Structure:
```javascript
{
"data": [{
"relationships": {
"director": {
"links": {
"related": "https://api2.redflagalert.net/v4/directors/18206440/"
}
},
"company": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/"
}
}
},
"attributes": {
"town": "HARMONDSWORTH",
"first_name": "ANDREW IAN",
"surname": "FLEMING",
"suffix": null,
"title": "MR",
"date_resigned": null,
"locality": "SPEEDBIRD WAY",
"birthdate": "",
"county": null,
"appointment_type": "C",
"date_appointed": "2013-10-11",
"postcode": "UB70GB",
"address": "WATERSIDE PO BOX 365",
"nationality": null,
"other_appointments": "N",
"occupation": null
},
"type": "directorship",
"id": "645323-645323-18206440",
"links": {
"self": "https://api2.redflagalert.net/v4/directorships/645323-645323-18206440/"
}
}]
}
```
### Attributes
| Field Key | Description | Notes |
| -------------------- | -------------------------------------------------------------------------------------------------- | ----- |
| `town` | The town of residence of the director in question. | |
| `first_name` | The directors first name. | |
| `surname` | The directors surname. | |
| `suffix` | Honorary titles, such as OBE, MBE, CBE etc. | |
| `title` | The directors title. | |
| `date_resigned` | Date the director resigned if applicable. Will return '`null`' where the director is still active. | |
| `locality` | The equivalent of the 2nd line of address of the director. | |
| `birthdate` | The directors date of birth (month and year) if known. | |
| `county` | The county of residence of the director. | |
| `appointment_type` | The type of appointment of the director | |
| `date_appointed` | The date the director was appointed. | |
| `postcode` | The directors post code. | |
| `address` | First line of address of the director. | |
| `nationality` | The directors nationality. | |
| `other_appointments` | Any other appointments held by the director | |
| `occupation` | Listed occupation if known. Will return '`null`' if none. | |
### Search for a Directorship
Like '`/companies/`', a search can be performed on directorships by making a GET request to the '`/directorships/`' endpoint:
```
https://api2.redflagalert.net/v3/directorships/
```
Returned resources will follow the JSON API format and will contain URLs in their '`links`' section to the company they are linked to.
To filter directorship search results, append the criteria as request parameters in any order.
#### Search Parameters
The following fields can currently be searched on:
| Field Name | Notes |
| -------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `title` | The directors title |
| `first_name` | The directors first name |
| `surname` | The directors surname |
| `name` | The combination of first\_name and surname, for example ‘Peter Smith’ |
| `town` | The directors town of residence |
| `county` | The directors county of residence |
| `nationality` | The nationality of the director |
| `postcode` | The postcode of the directors residence |
| `occupation` | The occupation of the director |
| min\_birthdate
max\_birthdate
| The maximum / minimum date of birth of the director |
| `appointment_type` | The type of the appointment |
The searches can be combined. For example, to find directorships held by British nationals with the surname Morgan, the query would be:
```
https://api2.redflagalert.net/v2/directorships/?nationality=British&surname=Morgan
```
When performing name searches, the '`name`' field searches on full names. For example, the following query will only return directorships held by people called Peter Smith:
```
https://api2.redflagalert.net/v3/directorships/?first_name=Peter&surname=Smith
```
While the following search will return all directorships held by people whose name is either similar to 'Peter' or 'Smith', with the most relevant results returned first:
```
https://api2.redflagalert.net/v2/directorships/?name=Peter%20Smith
```
This means that 'Peter Smith' will rank highest, then 'Peter Smith Jones' then lastly, entries like 'James Smith’.
If an unrecognised field name is included in search parameters, it will be ignored.
To also receive the companies the directorships are linked to, append the 'company' string in the 'include=' GET parameter:
```
https://api2.redflagalert.net/v3/directorships/?include=company
```
The response will be a compound document (see documents for format) containing the original search results along with the companies. All results are paginated.
```
https://api2.redflagalert.net/v2/directorships/?include=company
```
# Filing History
This endpoint links to Companies House, allowing you to view and retrieve documents in PDF format.
### Retrieving Documents
In order to retrieve a document as a PDF from the filing history results, you should query the document link (relationships > document > links > related) but you must change the MIME Type in the header to **application/pdf**.
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/filing-history/
```
### JSON Structure:
```javascript
{
"data": [{
"relationships": {
"document": {
"links": {
"related": "https://api2.redflagalert.net/v4/documents/wW054GFYFWfdZYMIyIfTDank2njJSKJb35KaxwY9AeA/"
}
}
},
"attributes": {
"category": "mortgage",
"description": "mortgage-create-with-deed-with-charge-number",
"links": {
"self": "/company/01777777/filing-history/MzA5MTY0OTM4M2FkaXF6a2N4"
},
"barcode": "A2NMAXXV",
"text_description": "Registration of a charge",
"paper_filed": true,
"description_values": {
"charge_number": "017777770771"
},
"date": "2013-12-20",
"type": "MR01",
"pages": 6,
"document_id": "wW054GFYFWfdZYMIyIfTDank2njJSKJb35KaxwY9AeA",
"subcategory": "create"
},
"type": "filing_history",
"id": "MzA5MTY0OTM4M2FkaXF6a2N4-A2NMAXXV",
"links": {
"self": "https://api2.redflagalert.net/v4/companies/01777777/filing-history/MzA5MTY0OTM4M2FkaXF6a2N4"
}
}],
"links": {
"self": "https://api2.redflagalert.net/v4/companies/01777777/filing-history/",
"next": "https://api2.redflagalert.net/v4/companies/01777777/filing-history/?page%5Boffset%5D=2",
"last": "https://api2.redflagalert.net/v4/companies/01777777/filing-history/?page%5Boffset%5D=32",
"first": "https://api2.redflagalert.net/v4/companies/01777777/filing-history/?page%5Boffset%5D=1"
}
}
```
### Attributes
| Field Key | Description | Notes |
| -------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | The category of the document filed. | Possible values are:
accounts
address
annual-return
capital
change-of-name
incorporation
liquidation
miscellaneous
mortgage
officers
resolution
|
| `description` | A description of the filing. | For enumeration descriptions see `description` section in the [enumeration mappings.](https://github.com/companieshouse/api-enumerations/blob/master/filing_history_descriptions.yml) |
| `links` | Links to other resources associated with this filing history item. | |
| `barcode` | The barcode of the document. | |
| `text_description` | A text description of the filing. | For enumeration descriptions see `description` section in the [enumeration mappings.](https://github.com/companieshouse/api-enumerations/blob/master/filing_history_descriptions.yml) |
| `paper_filed` | If `true`, indicates this is a paper filing. | |
| `description_values` | The main description code | |
| `date` | The date the associated filing was processed. | |
| `type` | The type of the associated filing. | |
| `pages` | Number of pages within the PDF document (links.document\_metadata) | |
| `document_id` | The document id of the resolution. | |
| `subcategory` | The sub-category of the document filed. | Possible values are:
resolution
|
# Group Company
The group-company endpoint lists other businesses that share a relationship with the current business.
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/group-company/
```
### JSON Structure:
```javascript
{
"data": [{
"dissolution_date": null,
"last_updated": "2016-07-14",
"addresses": [{
"town": null,
"address_line_2": "HARMONDSWORTH",
"county": null,
"location": {
"lat": 51.5373252879822,
"lon": -0.487355421766335
},
"address_line_4": "MIDDLESEX",
"address_line_1": "WATERSIDE PO BOX 365",
"type": "registered",
"address_line_3": "WEST DRAYTON",
"postcode": "UB7 0GB"
}],
"links": {
"self": "https://api2.redflagalert.net/v4/companies/09619950/"
},
"is_limited": true,
"rfa_rating": {
"health_rating_code": 5,
"short_code": "bronze",
"short_description": "Bronze",
"long_description": "Bronze companies will be an average credit risk whose financial position and trading results are not as strong as Silver companies. They may even be new companies that have yet to file their accounts. It is likely that not all payments are made to terms and it is advisable to review any monitoring notices received on these companies"
},
"parent_company": "01777777",
"incorporation_date": "2015-06-02",
"id": "09619950",
"dissolution_status": null,
"company_name": "BA HEALTHCARE TRUST LIMITED",
"type": "company",
"sic_codes": [
"74849"
],
"tps_registered": false,
"sic_sections": [
"K"
],
"primary_sic_code": "74849",
"company_number": "09619950"
}],
"links": {
"self": "https://api2.redflagalert.net/v4/companies/01777777/group-company/?parent_company=01777777",
"last": "https://api2.redflagalert.net/v4/companies/01777777/group-company/?parent_company=01777777&page%5Boffset%5D=1",
"first": "https://api2.redflagalert.net/v4/companies/01777777/group-company/?parent_company=01777777&page%5Boffset%5D=1"
}
}
```
### Attributes
| Field Key | Description | Notes |
| -------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dissolution_date` | Date the company was dissolved if applicable. | |
| `last_updated` | The date the record was last updated. | |
| `addresses` | A list of address dictionaries or JSON objects. | |
| `links` | API url's related to this company | |
| `is_limited` | Whether the company is limited or not. | |
| `rfa_rating` | The Red Flag Alert credit rating currently assigned to this company. | See [Appendix 3](/appendix/rfa-health-ratings) for a complete list of Red Flag Alert ratings and descriptions. |
| `parent_company` | The CRO number of the parent company. | |
| `incorporation_date` | The date that the company was incorporated. | |
| `id` | CRO number of the company. | |
| `dissolution_status` | For companies that have been dissolved, their exact status. | See [Appendix 1](/appendix/dissolution-status-codes) for possible values. |
| `company_name` | The registered company name. | |
| `type` | The type of incorporated company | |
| `sic_codes` | An array containing the specific sic codes which this company is in. | |
| `tps_registered` | Boolean value showing if the company has registered with the Telephone Preference Service. | |
| `sic_sections` | The single letter SIC section code. | SIC section headings and letter codes given in [Appendix 2](/appendix/sic-sections). Companies may have several SIC sections if they are active in several areas; in this case, if any of the sections match then the company will be returned. |
| `primary_sic_code` | The primary SIC code of the business. | |
| `company_number` | CRO number of the company. | |
# Mortgages
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/mortgages/
```
### JSON Structure:
```javascript
{
"meta": {
"outstanding": 681
},
"data": [{
"attributes": {
"form_no": "MR01",
"type": null,
"satisfied": "No",
"details": "CONTAINS FIXED CHARGE.CONTAINS NEGATIVE PLEDGE.",
"date_created": "2016-07-04",
"satisfied_date": null,
"holder": "FLIP NO. 125 CO., LTD. FLIP NO. 124 CO., LTD. FLIP NO. 123 CO., LTD"
},
"type": "mortgage",
"id": "645323-1833032314-815"
}]
}
```
### Attributes
| Field Key | Description | Notes |
| ---------------- | --------------------------------------------------------------- | ----- |
| `form_no` | The document number | |
| `type` | The type of mortgage or charge, such as fixed, or floating etc. | |
| `satisfied` | An indication that the charge is no longer current | |
| `details` | Further particulars of the charge | |
| `date_created` | The date the mortgage or charge was registered | |
| `satisfied_date` | The date of satisfaction of the charge | |
| `holder` | The name of the lender holding the charge | |
# Parent Company
This endpoint lists the parent company (if any) of the originating company.
### Example URL:
```
https://api2.redflagalert.net/v4/companies/03039051/parent-company/
```
### JSON Structure
```javascript
{
"data": {
"relationships": [{
"group-company": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/02649163/group-company"
}
}
}, {
"addresses": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/02649163/addresses/"
}
}
}, {
"balance_sheet": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/02649163/balance-sheet/"
}
}
}, {
"previous_names": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/02649163/previous-names/"
}
}
}, {
"shareholders": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/02649163/shareholders/"
}
}
}, {
"cashflow": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/02649163/cashflow/"
}
}
}, {
"contacts": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/02649163/contacts/"
}
}
}, {
"directorships": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/02649163/directorships/"
}
}
}, {
"profit_loss": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/02649163/profit-loss/"
}
}
}, {
"mortgages": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/02649163/mortgages/"
}
}
}, {
"ratio_analysis": {
"links": {
"related": "https://api2.redflagalert.net/v3/companies/02649163/ratio-analysis/"
}
}
}, {
"filing-history": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/02649163/filing-history/"
}
}
}],
"attributes": {
"dissolution_date": null,
"website": "www.vixtechnology.com",
"name": "VIX AFC LIMITED",
"dissolution_status": null,
"company_type": "ltd",
"company_number": "02649163",
"company_aims": "The 30.06.15 accounts indicate that the company is either dormant or no longer trades. ",
"legal_status": "Non-Trading",
"rfa_rating": {
"health_rating_code": 9,
"credit_limit": 71300,
"short_code": "NT",
"trading_payment_parity": null,
"short_description": "Not Trading",
"long_description": "This simply indicates that according to information filed at Companies House the company had a non-trading status. Should credit be sought in the name of the company care should be taken and a full disclosure sought."
},
"TPS": false,
"auditor": "UHYHackerYoung",
"incorporation_date": "1991-09-26",
"sic_codes": [
"35500"
]
},
"type": "company",
"id": "02649163",
"links": {
"self": "https://api2.redflagalert.net/v4/companies/02649163/"
}
}
}
```
### Attributes
| Field Key | Description | Notes |
| -------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `dissolution_date` | Date the company was dissolved if applicable. | |
| `website` | Company website URL if known. | |
| `name` | The registered name for this business. | |
| `dissolution_status` | For companies that have been dissolved, their exact status. | See [Appendix 1](/appendix/dissolution-status-codes) for possible values. |
| `company_type` | The type of company, i.e. PLC, LTD etc. | |
| `company_number` | The Companies House identification number for the company. | |
| `company_aims` | Description of the aims of the company. | |
| `legal_status` | Detailed legal status of the company. | |
| `rfa_rating` | The Red Flag Alert credit rating currently assigned to this company. | See [Appendix 3](/appendix/rfa-health-ratings) for a complete list of Red Flag Alert ratings and descriptions. |
| `TPS` | Boolean value showing if the company has registered with the Telephone Preference Service. | |
| `auditor` | The registered auditor for this business. | |
| `incorporation_date` | The date that the company was incorporated. | |
| `sic_codes` | An array containing the specific sic codes which this company is in. | |
# Previous Names
If a company has previously been known by another name, this endpoint will list those previous names.
### Example URL:
```
https://api2.redflagalert.net/v4/companies/03039051/previous-names/
```
### JSON Structure:
```javascript
{
"data": [{
"attributes": {
"name": "VIX TECHNOLOGY LIMITED",
"end_date": "2015-11-11",
"start_date": "2014-07-01"
},
"type": "previous_name",
"id": "1842808"
}]
}
```
### Attributes
| Field Key | Description | Notes |
| ------------ | ----------------------------------------------------------- | ----- |
| `name` | The previous registered name for this business. | |
| `end_date` | The final date that the business was known bvy this name. | |
| `start_date` | The first date that the business became known by this name. | |
# Profit & Loss
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/profit-loss/
```
### JSON Structure:
```javascript
{
"data": [{
"attributes": {
"consolidated": "Y",
"pre_tax_profit": 2628000000,
"currency": "GBP",
"director_renum": 7000000,
"account_date": "2015-12-31",
"retained_profit": 2233000000,
"audit_fee": 1809000,
"interest_payable": 906000000,
"non_trading_income": 2295000000,
"operating_profit": 1239000000,
"no_weeks": 52,
"dividends": 260000000,
"taxation": 120000000,
"employees": 43550,
"gross_profit": null,
"non_audit_fee": 480000,
"post_tax_profit": 2508000000,
"value_added": 3034839000,
"cost_of_sales": null,
"turnover": 11333000000
},
"type": "profit_loss",
"id": "645323-7696788"
}]
}
```
### Attributes
| Field Key | Description | Notes |
| -------------------- | ------------------------------------------------------ | ----- |
| `consolidated` | Group profit & loss as opposed to individual | |
| `pre_tax_profit` | Profit before tax | |
| `currency` | The currency used to prepare the profit & loss account | |
| `director_renum` | Amounts paid to directors | |
| `account_date` | The date of the profit & loss account | |
| `retained_profit` | The amount of profit retained for the year | |
| `audit_fee` | The fee paid to the auditors | |
| `interest_payable` | Finance charges | |
| `non_trading_income` | Income from other sources | |
| `operating_profit` | Profit from operations | |
| `no_weeks` | The number of weeks included in the period | |
| `dividends` | Amounts paid to shareholders | |
| `taxation` | Amounts due in tax | |
| `employees` | The number of employees | |
| `gross_profit` | The profit after cost of sales | |
| `non_audit_fee` | Additional professional fees | |
| `post_tax_profit` | Profits after tax | |
| `value_added` | An alternative profit calculation | |
| `cost_of_sales` | The cost of goods sold | |
| `turnover` | The net value of sales, excluding local taxes | |
# Ratio Analysis
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/ratio-analysis/
```
### JSON Structure:
```javascript
{
"data": [{
"attributes": {
"total_assets_per_employee": 353065,
"profit_capital_employed": 27,
"wages_sales": 14,
"profit_sales": 23,
"working_capital_turnover": -20,
"turnover_fixed_assets": 1,
"account_date": "2015-12-31",
"current_liabilities_stocks": 41,
"total_assets_audit_fees": 8499,
"creditors_debtors": 1,
"export_sales": 51,
"sales_audit_fees": 6264,
"capital_employed_per_employee": 222181,
"turnover_total_assets": 73,
"long_term_debt_net_worth": 113,
"total_debt_working_capital": -2,
"debtors_total_assets": 3,
"interest_pre_interest_profit": 25,
"liquidity_ratio": 0,
"profit_total_assets": 17,
"current_ratio": 0,
"profit_shareholders_funds": 59,
"profit_per_employee": 60344,
"total_fixed_assets_per_employee": 274994,
"average_employee_remuneration": 37336,
"shareholders_funds_total_assets": 0,
"total_debt_net_worth": 150,
"sales_per_employee": 260229
},
"type": "ratio_analysis",
"id": "645323-1260598831"
}]
}
```
### Attributes
| Field Key | Description | Notes |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----- |
| `total_assets_per_employee` | A performance ratio that divides total assets by the number of employees | |
| `profit_capital_employed` | A performance ratio that divides pre-tax profit by the capital employed (shareholders funds plus long term debt) | |
| `wages_sales` | A performance ratio that divides the wage bill by the total sales turnover figure | |
| `profit_sales` | A performance ratio that divides profits by the total sales turnover figure to show the margin | |
| `working_capital_turnover` | A performance ratio that divides total sales turnover by working capital | |
| `turnover_fixed_assets` | A performance ratio that divides total sales turnover by fixed assets | |
| `account_date` | The end of the accounting period for the data | |
| `current_liabilities_stocks` | A performance ratio that divides liabilities due over the next 12 months by the asset value of stocks | |
| `total_assets_audit_fees` | A performance ratio that divides total assets by audit fees | |
| `creditors_debtors` | A performance ratio that divides creditors by debtors to indicate liquidity | |
| `export_sales` | The value of exports | |
| `sales_audit_fees` | Supplementary audit fees | |
| `capital_employed_per_employee` | A performance ratio that divides capital employed by the number of employees | |
| `turnover_total_assets` | A performance ratio that divides total sales turnover by total assets | |
| `long_term_debt_net_worth` | A performance ratio that divides long term debt by the net worth | |
| `total_debt_working_capital` | A performance ratio that divides total debt by net working capital | |
| `debtors_total_assets` | A performance ratio that divides debtors by total assets | |
| `interest_pre_interest_profit` | A performance ratio that shows the burden of interest payments | |
| `liquidity_ratio` | A performance ratio the divides current assets minus stocks by current liabilities | |
| `profit_total_assets` | A performance ratio that divides pre tax profits by total assets | |
| `current_ratio` | A performance ratio the divides current assets by current liabilities | |
| `profit_shareholders_funds` | A performance ratio that divides pre-tax profits by shareholders funds (net worth, plus intangible assets) | |
| `profit_per_employee` | A performance ratio that divides pre-tax profits by the number of employees | |
| `total_fixed_assets_per_employee` | A performance ratio that divides total fixed assets by the number of employees | |
| `average_employee_remuneration` | A performance ratio that divides salaries and wages by the number of employees. | |
| `shareholders_funds_total_assets` | A performance ratio that divides shareholders funds by total assets | |
| `total_debt_net_worth` | A performance ratio that divides total debt by net worth | |
| `sales_per_employee` | A performance ratio that divides total sales turnover by the number of employees. | |
# Shareholders
A list of all registered shareholders involved with the business.
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/shareholders/
```
### JSON Stucture:
```javascript
{
"data": [{
"attributes": {
"first_name": null,
"shareholder_class": "A1",
"surname": "International Consolidated Airlines Group SA",
"share_quantity": 896700,
"title": null,
"share_value": 259773990,
"company_flag": "C"
},
"type": "shareholder",
"id": "645323-3896058920"
}]
}
```
### Attributes
| Field Key | Description | Notes |
| ------------------- | ------------------------------------------------------------------- | ----- |
| `first_name` | The shareholders first name. | |
| `shareholder_class` | Needs clarification | |
| `surname` | The shareholders surname. | |
| `share_quantity` | The total number of shares held by the shareholder. | |
| `title` | The shareholders title. | |
| `share_value` | The value attributed to the shareholders shares.Needs clarification | |
| `company_flag` | Needs clarification | |
# Unpaid Debt
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/unpaid-debt/
```
### JSON Structure:
```javascript
{
"data": [{
"attributes": {
"statement_date": "2016-02-19",
"debtor_company_name": "Oyster Travel Training Services Limited T/A Oyster Training Group",
"creditor_company_name": "British Airways",
"amount": 7216,
"creditor_company_number": "01777777",
"debtor_company_number": "05413662"
},
"type": "unpaid_debt",
"id": "690773",
"links": {
"debtor": "https://api2.redflagalert.net/v4/companies/05413662/",
"creditor": "https://api2.redflagalert.net/v4/companies/01777777/"
}
}]
}
```
### Attributes
| Field Key | Description | Notes |
| ------------------------- | ------------------- | ----- |
| `statement_date` | Needs clarification | |
| `debtor_company_name` | Needs clarification | |
| `creditor_company_name` | Needs clarification | |
| `amount` | Needs clarification | |
| `creditor_company_number` | Needs clarification | |
| `debtor_company_number` | Needs clarification | |
# Unpaid Losses
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/unpaid-losses/
```
### JSON Structure:
```javascript
{
"data": [{
"attributes": {
"statement_date": "2016-02-19",
"debtor_company_name": "Oyster Travel Training Services Limited T/A Oyster Training Group",
"creditor_company_name": "British Airways",
"amount": 7216,
"creditor_company_number": "01777777",
"debtor_company_number": "05413662"
},
"type": "unpaid_debt",
"id": "690773",
"links": {
"debtor": "https://api2.redflagalert.net/v4/companies/05413662/",
"creditor": "https://api2.redflagalert.net/v4/companies/01777777/"
}
}]
}
```
### Attributes
| Field Key | Description | Notes |
| ------------------------- | ------------------- | ----- |
| `statement_date` | Needs clarification | |
| `debtor_company_name` | Needs clarification | |
| `creditor_company_name` | Needs clarification | |
| `amount` | Needs clarification | |
| `creditor_company_number` | Needs clarification | |
| `debtor_company_number` | Needs clarification | |
# Directorship
The directorships endpoint returns JSON objects for each directory involved and registered with the business.
### Example URL:
```
https://api2.redflagalert.net/v4/companies/01777777/directorships/
```
### JSON Structure:
```javascript
{
"data": [{
"relationships": {
"director": {
"links": {
"related": "https://api2.redflagalert.net/v4/directors/18206440/"
}
},
"company": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/"
}
}
},
"attributes": {
"town": "HARMONDSWORTH",
"first_name": "ANDREW IAN",
"surname": "FLEMING",
"suffix": null,
"title": "MR",
"date_resigned": null,
"locality": "SPEEDBIRD WAY",
"birthdate": "",
"county": null,
"appointment_type": "C",
"date_appointed": "2013-10-11",
"postcode": "UB70GB",
"address": "WATERSIDE PO BOX 365",
"nationality": null,
"other_appointments": "N",
"occupation": null
},
"type": "directorship",
"id": "645323-645323-18206440",
"links": {
"self": "https://api2.redflagalert.net/v4/directorships/645323-645323-18206440/"
}
}]
}
```
# Attributes
| Field Key | Description | Notes |
| -------------------- | -------------------------------------------------------------------------------------------------- | ----- |
| `town` | The town of residence of the director in question. | |
| `first_name` | The directors first name. | |
| `surname` | The directors surname. | |
| `suffix` | Honorary titles, such as OBE, MBE, CBE etc. | |
| `title` | The directors title. | |
| `date_resigned` | Date the director resigned if applicable. Will return '`null`' where the director is still active. | |
| `locality` | The equivalent of the 2nd line of address of the director. | |
| `birthdate` | The directors date of birth (month and year) if known. | |
| `county` | The county of residence of the director. | |
| `appointment_type` | The type of appointment of the director | |
| `date_appointed` | The date the director was appointed. | |
| `postcode` | The directors post code. | |
| `address` | First line of address of the director. | |
| `nationality` | The directors nationality. | |
| `other_appointments` | Any other appointments held by the director | |
| `occupation` | Listed occupation if known. Will return '`null`' if none. | |
# Search
Like '`/companies/`', a search can be performed on directorships by making a GET request to the '`/directorships/`' endpoint:
```
https://api2.redflagalert.net/v4/directorships/
```
Returned resources will follow the JSON API format and will contain URLs in their '`links`' section to the company they are linked to.
To filter directorship search results, append the criteria as request parameters in any order.
#### Search Parameters
The following fields can currently be searched on:
| Field Name | Notes |
| ------------------ | --------------------------------------------------------------------- |
| `title` | The directors title |
| `first_name` | The directors first name |
| `surname` | The directors surname |
| `name` | The combination of first\_name and surname, for example ‘Peter Smith’ |
| `town` | The directors town of residence |
| `county` | The directors county of residence |
| `nationality` | The nationality of the director |
| `postcode` | The postcode of the directors residence |
| `occupation` | The occupation of the director |
| `appointment_type` | The type of the appointment |
The searches can be combined. For example, to find directorships held by British nationals with the surname Morgan, the query would be:
```
https://api2.redflagalert.net/v4/directorships/?nationality=British&surname=Morgan
```
When performing name searches, the '`name`' field searches on full names. For example, the following query will only return directorships held by people called Peter Smith:
```
https://api2.redflagalert.net/v4/directorships/?first_name=Peter&surname=Smith
```
While the following search will return all directorships held by people whose name is either similar to 'Peter' or 'Smith', with the most relevant results returned first:
```
https://api2.redflagalert.net/v4/directorships/?name=Peter%20Smith
```
This means that 'Peter Smith' will rank highest, then 'Peter Smith Jones' then lastly, entries like 'James Smith’.
If an unrecognised field name is included in search parameters, it will be ignored.
To also receive the companies the directorships are linked to, append the 'company' string in the 'include=' GET parameter:
```
https://api2.redflagalert.net/v4/directorships/?include=company
```
The response will be a compound document (see documents for format) containing the original search results along with the companies. All results are paginated.
```
https://api2.redflagalert.net/v4/directorships/?include=company
```
# Introduction
Identity and Anti Money Laundering checks are provided through our partners, GB Group PLC. The service allows customers to check an individual's identity against a range of databases to provide assurance to customers. Politically Exposed Person (PEP) and international Sanctions checks are also available.
In order to carry out ID and AML checks through the API, customers are required to undertake an authorisation process and will be provided with separate authentication details. Please contact support for more information if you are interested in this functionality.
# ID & AML Check
All identity checks are carried out by submitting a POST request containing JSON body via a single endpoint:
```
https://api2.redflagalert.net/v4/id3/person-check/
```
Each request must contain the following parameters:
| Parameter | Description | Notes |
| ----------------- | ---------------------------------------------------- | ------------------------------------- |
| `id3_username` | ID3 username, obtained from RFA support | |
| `id3_password` | ID3 password, obtained from RFA support | |
| `id3_profile_id` | ID3 profile ID, obtained from RFA support | |
| `id3_check_level` | A string corresponding to the level of check desired | 'id\_check', 'standard' or 'advanced' |
The RFA API account requesting the check must have the necessary amount of credit available. If insufficient credits are available, an HTTP 429 response will be returned.
# Charges
Checks are charged as follows:
| Request | Cost |
| --------- | --------- |
| id\_check | 2 credits |
| standard | 3 credits |
| advanced | 4 credits |
# Search
The following fields can be sent as part of a request. For any check to be carried out, at least the 'forename' and 'surname' fields must be provided.
| Parameter | Description | Notes |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `current_address` | Single object containing the current address for the person. The subfields 'city', 'country', 'first\_date\_of\_residence', 'postcode', 'premise' and 'street' are available. | Residence dates are provided in the MM/YYYY format. |
| `day_of_birth` | The day of the year the person was born | Partial dates of birth are allowed if the full information is not available |
| `month_of_birth` | The month the person was born | |
| `year_of_birth` | The year the person was born | |
| `driving_license` | Single object containing one field, 'number' - the driving license number | |
| `forename` | The persons first name | |
| `gender` | The persons gender | |
| `national_insurance` | Single object containing one field, 'number' - the persons National Insurance number | |
| `passport` | Single object containing the following fields: 'day\_of\_expiry', 'month\_of\_expiry', 'number' and 'year\_of\_expiry' | |
| `previous_addresses` | Array of objects representing known previous addresses. Fields are the same as for 'current\_address' | |
| `reference` | User-defined field, can be set to any string | The reference is stored alongside each check to allow tagging, client-provided reference numbers or similar |
| `surname` | The persons surname | |
| `title` | Any known title for the person | 'Mr', 'Ms' etc |
# Example Request
Following is a JSON example of a typical request object. This JSON object must be submitted via POST method to the API endpoint. Please see the [JSONAPI specification](http://jsonapi.org/format/#crud-creating) for more details.
```javascript
{
"data": {
"attributes": {
"current_address": {
"city": "London",
"country": "United Kingdom",
"first_date_of_residence": "11/2014",
"last_date_of_residence": "09/2015",
"postcode": "T35ER",
"premise": "123",
"street": "Example Road"
},
"day_of_birth": "09",
"driving_license": {
"number": "exampl-123456-ab1-ab"
},
"forename": "David",
"gender": "Male",
"id3_check_level": "advanced",
"id3_password": "my_id3_account_password123",
"id3_profile_id": "12345-432j1-2342d-8259-d4bc69f40dd8",
"id3_username": "my@username.com",
"middlename": "Thomas",
"month_of_birth": "02",
"national_insurance": {
"number": "ex-01-01-01-a"
},
"passport": {
"day_of_expiry": "31",
"month_of_expiry": "12",
"number": "01232345-5-gbr-123415-m-123415-01",
"year_of_expiry": "2026"
},
"previous_addresses": [
{
"city": "LONDON",
"country": "United Kingdom",
"first_date_of_residence": null,
"last_date_of_residence": null,
"postcode": "T351ER",
"premise": "FLAT 1, BUILDING 9",
"street": "ANOTHER EXAMPLE STREET"
},
{
"city": "LONDON",
"country": "United Kingdom",
"first_date_of_residence": null,
"last_date_of_residence": null,
"postcode": "T351ER",
"premise": "FLAT 2, BUILDING 9",
"street": "ANOTHER EXAMPLE STREET"
}
],
"reference": "my testing check",
"surname": "Example",
"title": "Mr",
"year_of_birth": "1987"
},
"type": "id3-check"
}
}
```
# Response
Check responses will be returned in the standard [JSON API](http://jsonapi.org/) format. Fields are as follows:
| Parameter | Description | Notes |
| -------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `authentication_id` | | |
| `band_text` | An overall recommended result for the check | 'Pass', 'Refer' or 'Fail' |
| `country` | The country the check was carried out in | |
| `customer_reference` | | Currently for internal use |
| `profile_id` | The ID3 profile used to carry out the check | |
| `profile_name` | The name of the profile | |
| `profile_revision` | | Currently for internal use |
| `profile_state` | | Currently for internal use |
| `profile_version` | | Currently for internal use |
| `results` | An array of objects, each representing the results of a check against a particular database | See below for details |
| `score` | A numeric result score for the check | |
| `timestamp` | Timestamp for when the check was carried out | |
| `id` | | Currently for internal use |
| `type` | | For standards compliance; will always be 'id3-check' |
### Results objects
The API returns an array of result objects, one for each database check which has been performed as part of the check. Different check levels will perform different database checks. Fields are as follows:
| Parameter | Description | Notes |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `alert` | A result for this particular check. | Match, Nomatch etc |
| `address` | If provided, was there a match on the date of birth? | |
| `comments` | An array of objects containing comments provided on this particular check. These are specific to the check being performed and are used to provide information such as missing data. Fields are 'code' and 'description'. | |
| `date_of_birth` | If provided, was there a match on the date of birth? | |
| `description` | Text description of this particular check | |
| `forename` | If provided, was there a match on the forename? | |
| `id` | Check code | Currently for internal use |
| `name` | The title of this particular check | |
| `pass` | Result indicating whether this particular check has 'passed' | |
| `sanction_matches` | List of sanctions / PEPs, if this particular result contains that information | |
| `surname` | If provided, was there a match on the surname? | |
# 1: Dissolution Status Codes
These codes are used to indicate the particular current status of a company that has previously been dissolved. Available codes are as follows:
| Code | Status |
| ---- | -------------------------- |
| C | Closed company. |
| D | Dissolved company. |
| R | Restored to the register. |
| N | Not available. |
| O | Out of business indicator. |
| P | Out of business indicator. |
# 2: SIC Sections
SIC section headings and letter codes are as follows:
| SIC Section Code | SIC Section Title |
| ---------------- | ------------------------------------------ |
| A | Agriculture, hunting & forestry |
| B | Fishing |
| C | Mining, quarrying |
| D | Manufacturing |
| E | Electricity, gas and water supply |
| F | Construction |
| G | Wholesale, retail & motor trade |
| H | Hotels & restaurants |
| I | Transport, storage & communication |
| J | Financial intermediation |
| K | Real estate, renting & business activities |
| L | Public administration & defense |
| M | Education |
| N | Health & social work |
| O | Other community, social & personal |
| P | Private households with employed persons |
| Q | Extra-territorial organisations, bodies |
# 3: RFA Health Ratings
The following ratings are used to indicate Red Flag Alert's rating of a company:
| Short Code | Short Description | Long Description |
| -------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `redflag3` | Three Red Flags (Highest) | Companies are in the weakest 20% in their size category and display risk factors that might include a deteriorating financial position, sub-optimal gearing/liquidity, and/or the presence of more recent, or significant legal notices, but with additional risk factors, such as recent county court judgments of a materially significant value. Very high risk and guarantees advised, and 56% of companies with three red flags will cease to trade in the next seven days. |
| `redflag2` | Two Red Flags | Companies are in the weakest 20% in their size category and display risk factors that might include a deteriorating financial position, sub-optimal gearing/liquidity, and/or the presence of more recent, or significant legal notices, but with additional risk factors, such as recent county court judgments of a materially significant value. Very high risk and guarantees advised. |
| `redflag1` | One Red Flag | Companies are in the weakest 20% in their size category and display risk factors that might include a deteriorating financial position, sub-optimal gearing/liquidity, and/or the presence of more recent, or significant legal notices. The risk is elevated, and suppliers should seek suitable assurances or guarantees. |
| `amber` | Amber | Companies are newly incorporated or have only passed the lower threshold of the credit score algorithms, and display some financial, payment or filing characteristics that make them an elevated risk. Considered to be moderate risk and open credit is only recommended with caution. |
| `bronze` | Bronze | Companies will be in acceptable health. They may not have published accounts or are a newly formed, but nothing significantly detrimental is known. Where financials are present, gearing may be higher than normal, or liquidity may be lower than ideal. The financial trend may be down, and there may be some history of legal notices. Considered to be a fair trade risk and open credit is recommended. |
| `silver` | Silver | Companies will be stable overall. They will have healthy financials, and a normal history of filing compliance. Gearing will be within an acceptable range, with reasonable levels of liquidity. If the trend is not upward, any declines will be modest, with few if any significant or recent legal notices. Considered to be low risk and open credit is recommended. |
| `gold` | Gold | Companies will be very healthy overall. They will have sound financials, a good history of filing compliance, with ideal levels of gearing (proportion of loan capital), optimal liquidity, and a generally favourable trend, with no significant or recent legal notices. Considered to be very low risk and open credit is recommended. |
| `NT` | Not Trading | This simply indicates that according to information filed at Companies House the company had a non- trading status. Should credit be sought in the name of the company care should be taken and a full disclosure sought. |
| `INSOLV` | Insolvent | Company has undergone some form of Insolvency; please check the full record. All credit transactions should be stopped. |
| `str` | Strike Off | A Striking-Off action at Companies House has been registered against the company or limited liability partnership. This can be voluntary or instigated by Companies House. The full record should be reviewed and if credit is sought then care should be taken and a full disclosure requested to ascertain the current trading status. |
| `dissolved` | Dissolved | This company has been dissolved by Companies House and no longer exists. Should you be trading with a company in this name you should 1) review your situation immediately, 2) obtain a full disclosure of affairs before entering into any further transactions and 3) ensure you are trading with the correct company going forward. |
| `N/A` | N/A | A Health Rating is not currently available. |
| `discontinued` | Business Discontinued | This business has been discontinued |