Standard API
The mnAI Connected Data APIs are organised around REST. They have predictable resource-oriented URLs, accept form-encoded request bodies, return JSON-encoded responses, and use standard HTTP response codes and authentication. They allow only GET requests.
Introduction
We currently publish one API ⚙️:
- Companies House Appointments ⚙️
Endpoints query a graph database built and updated with the UK's company registry (Companies House) appointments dataset. This dataset contains all current and previous appointments for company officers (directors, secretaries, and some other non-typical designations). There are approximately:
- 20 million company officers
- 14 million companies
- 45 million appointments
- 50 thousand daily updates
- 100 million+ connections
We provide more historic data than the Companies House API
The Companies House Public Data API contains active companies and company officers plus dissolved companies and associated officers going back 10 years or so.
Our data contains all present and historic company/appointment data held by Companies House.
Unconnected ⚙️
We have two categories of endpoints in this API, unconnected and connected
As the name indicates, none of the unconnected endpoints leverage the connected dimension of our data, they just provide search functions on the appointments data.
So why offer similar endpoints as the Companies House Public API? Because:
- You can query more (older) data
- You can have a higher rate limit
- You can use both, one acting as a backup
- Certain response data act as input parameters for our connected data API (see below)
These endpoints rely only on unconnected appointments data
api.regulationtechnologies.com/v1/officers
demo.api.regulationtechnologies.com/v1/officers
Find UK company officersapi.regulationtechnologies.com/v1/companies
demo.api.regulationtechnologies.com/v1/companies
Find UK companiesapi.regulationtechnologies.com/v1/companies/{company_number}/officers/
demo.api.regulationtechnologies.com/v1/companies/{company_number}/officers/
Find all officers for a UK company
Connected ⚙️
A collection of endpoints that specifically leverage the connected dimension of our data. This is where the magic happens ✨✨
We have connected all UK companies to their company officers. This produces a network of over 100 million connections. Applying network analysis we can surface high-value and unique insights that are not possible using traditional methods.
You can build out networks of connected companies and officers by using the two 'Networks' endpoints. These can be chained together to expand to whatever size and direction you want.
The 'Collections' endpoint solves a normalisation problem with Companies House data. We use network features to collect together likely records of individuals which presents a more complete picture (around 20% of people have multiple records). In many use cases, this is a necessary first step before further analysis.
These endpoints leverage the connected dimension of our data
api.regulationtechnologies.com/v1/networks/officers/{officer_number}
demo.api.regulationtechnologies.com/v1/networks/officers/{officer_number}
Expand a network starting with an officerapi.regulationtechnologies.com/v1/networks/companies/{company_number}
demo.api.regulationtechnologies.com/v1/networks/companies/{company_number}
Expand a network starting with a companyapi.regulationtechnologies.com/v1/collections/officers
demo.api.regulationtechnologies.com/v1/collections/officers
Collect unlinked company officer records
2-hop network expansion in company officer > companies > director sequence seeded with the highlighted officer. To replicate, enter '09173620' in the 'officer_number' parameter at Expand a network starting with an officer
2-hop network expansion in company > company officers > companies sequence seeded with the highlighted company. To replicate, enter '10819854' in the 'company_number' parameter at Expand a network starting with a company
Bespoke queries & endpoints 🛠️
We can develop bespoke queries and endpoints using 50+ graph algorithms
[email protected]
Naming Conventions & Glossary
Endpoints are structured from larger, general entities to smaller, more specific ones. For example, our 'Expand a network starting with an officer' endpoint concludes /networks/officers/{officer_number}.
Collections - A collection of records that are linked by certain properties. For example, our Collect unlinked company officer records endpoint links officer records by date of birth, address, or network features that indicate the records relate to the same officer.
Connectors - Data properties in the response payload which are unique identifiers for companies (company_number) and officers (officer_number). Networks can be built where records contain both connector properties.
Expand/Expansion - Networks can be increased in size by adding more records through their connectors. This can be achieved by chaining together output from our 'Expand a network starting with an officer' or 'Expand a network starting with a company' endpoints.
Graph Algorithm(s) - Our dataset is maintained in a Neo4j graph database with 100+ million connections between companies and officers. We have a library of 50 graph algorithms that can surface high-value insights. This is currently bespoke work, please email [email protected] for more information or see examples at our blog.
Linked/Unlinked - Collections of records can be grouped by data properties, such as date_of_birth or by network features such as proximity or connectedness.
Networks - A structural representation of how entities are connected. In our case, how companies and company officers are connected by appointments.
Network Features - Derived from graph theory, network features help describe and analyse networks. Networks can be dense, sparse, there can be influential entities or clusters of similar entities. Graph Algorithms utilise network features.
Authorisation & Keys
See Quick Start 🚀 for details on authentication and access.
Do not embed API keys in your code
Storing keys in your application code increases the risk that they will be discovered, particularly if any of your source code is made public or it can be viewed by people who should not have access to the key. Instead, you should consider storing them inside environment variables or configuration.
Do not store API keys in your source tree
If you store API keys in files, for example, configuration or environment files, do not store them inside the application source tree. If all or part of the source is made public, the key may be compromised.
Restrict API key use by IP address and domain
Limit the use of a key to a specific IP address or domain to reduce its usefulness if it becomes compromised.
Regenerate your API keys
Ask us to regenerate your key to reduce the chance that a key will be discovered.
Delete API keys when no longer required
Remove unused keys from your registered applications page to limit the number of entry points into your account.
Status & Error Codes
We use the 'Problem Detail' standard as originally detailed here. This will provide a JSON response in the event of an error, below is an example:
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-c873035e834d9e4d85a6e0e597212a66-03e58b94ce34694e-00",
"errors": {
"RecordsReturned": [
"'Records Returned' must be less than or equal to '100'."
]
}
}
And these will trigger in the event of any 4xx or 5xx status code.
| Status Code | Meaning |
|---|---|
| 200 | Success. The request has succeeded. |
| 400 | Bad Request. The request could not be understood by the server due to malformed syntax. |
| 401 | Unauthorized. Authentication has failed either because no authentication details were sent with the request or those details were refused. |
| 404 | Not Found. The server has not found anything matching the Request-URI. |
| 500 | Internal Server Error. The server encountered an unexpected condition that prevented it from fulfilling the request. |
Rate Limiting
Paying customers' rate limits are agreed on a case-by-case basis. For customers in development, we offer 100 free calls.