This guide covers everything you need to migrate from the Beauhurst API v1 to v2. It is more than just a version change as we have introduced our two new data models - True Companies and legal entities - and made improvements to the data available and how you get to the data you need.
In summary
| v1 | v2 | |
|---|---|---|
| Base URL | https://platform.beauhurst.com/_api/v1/ | https://platform.beauhurst.com/_api/v2.0/ |
| Company model | One combined resource | Split into True Companies and legal entities |
| Getting data | One call with an includes parameter | One call per datatype |
| Rate limit | 1 request per second | 30 requests per second |
| Pagination | Up to 100 results per page | Same, with additional context of the request in meta |
| Currency | All values GBP | Currency code fields added for context for financial values |
The sections below go into these areas in more detail with the endpoints and parameters you will need.
New data models: True Companies and legal entities
This is the biggest change to how our API is structured and works and is worth considering before starting any changes.
In v1, a company was one record for a legal entity with additional datasets associated to it including fundraisings and patents.
A company is more than a legal entity; it's a real, operating organisation with employees, a leadership team, offices, customers, a brand, and the agency to make its own decisions.
True Companies is Beauhurst's way of representing real-world businesses; consolidating data from across legal entities, official registers, IP and innovation databases, public funding databases, news sources, company websites and more into one coherent, comprehensive profile. For more information about True Companies see our user guide here.
In v2 you now have the option to access:
-
True Companies to get one complete picture of a business, instead of data scattered across multiple legal entities. Use this when you want to understand the operating company as a whole and access a fuller view of every company’s activity including transactions, patents, consolidated financials and a better company status that reflects the business.
We have also unified our data internationally so you can more easily interact with and use data across the UK, Germany and Ireland - with more countries coming soon.
Each True Company has a unique True Company ID which represents the whole operating company which can be made up of multiple legal entities. Use the True Company ID in the True Company endpoints.
-
Legal entities to get the as-filed registry information on specific entities. As each registry requires different data, these are country specific to get the right information.
The legal entity endpoints accept the company registration number of their registry.
Use this when you are wanting to find the as-filed data on legal entities. Each legal entity will return the True Company ID it is part of if you want to find enhanced datasets that are at a True Company level such as transactions, key people, websites and patents.
If your integration currently works using the company registration number, such as the Companies House ID, you have a couple of options:
- Use the company registration number in the True Company search endpoints to find the corresponding True Company ID to use in following endpoints. Use the
corporate_register_country(gb, de or ie) to ensure you are searching over the right registry as the same ID could exist in more than one country- Go to the relevant legal entity endpoints to get the as-filed data and enhance with the True Company data if needed
If your integration currently works using the Beauhurst company IDs:
- Call the v1 Companies endpoint with the Beauhurst company IDs and
includes=companies_house_idto get each company’s Companies House ID- Use this in the UK legal entity endpoints or call
truecompany/searchwithcompany_registration_numberandcorporate_register_country=gbto get thetrue_company_id- Store the True Company ID for future calls
If a company doesn’t have a Companies House ID, search by name or website instead.
Endpoints
v1 returned most of a company’s data in one call with an includes parameter to choose the specific data points (name, registered_name, registration_date, company_status and so on).
In v2, we’ve replaced this with one endpoint per data type with a consistent response structure. It's a bigger set of URLs but each response is smaller and focused. We have also added more filtering on these more focused datasets so that you can find the data you want faster and only fetch what you actually need.
True Company (truecompany/)
truecompany/)| Data you want | v1 | v2 | Improvements |
|---|---|---|---|
| Search | companies/search | truecompany/search | |
| Overview | companies/{id} (includes=name&includes=company_status etc) | truecompany/{id}/summary | |
| Corporate structure | companies/{id} (includes=corporate_structure) | truecompany/{id}/corporatestructure | Now shows the hierarchy of subsidiary entities |
| Directors | companies/{id} (includes=directors) | truecompany/{id}/directors | Now separated out so you can filter by who is active |
| Financials | companies/{id} (includes=latest_accounts,historic_accounts) | truecompany/{id}/financials | Now has the full financial filings rather than just a summary |
| Shareholders | companies/shareholdings | truecompany/{id}/shareholders | |
| Key people | companies/{id} (includes=key_contacts) | truecompany/{id}/keypeople | Now separated out so you can filter by job function |
| Patents | companies/patents | truecompany/{id}/patents | |
| Fundraisings | transactions/company (includes=fundraisings) | truecompany/{id}/fundraisings | |
| Grants | transactions/company (includes=grants) | truecompany/{id}/grants | |
| Acquisitions | — | truecompany/{id}/acquisitions | New dataset |
| A saved collection | collections/company | truecompany/collection/{collection_id} |
There are some field names that have been updated to improve consistency and clarity in the fundraisings endpoint.
| v1 | v2 |
|---|---|
id | fundraising_id |
amount_raised_gbp | amount_raised_announcedamount_raised_verified(Each with currency and gbp) |
valuation_gbp | pre_money_valuationpost_money_valuation |
purposes_of_funding | purposes_of_fundraising |
types_of_funding | types_of_fundraising |
investor_names / investors | Now combined into one group with a list of:investor_idinvestor_namefund_typeamount_contributed |
Legal entity (legalentity/{gb,de,ie}/)
| Data you want | v1 | v2 | Coverage |
|---|---|---|---|
| Search | companies/search | legalentity/{gb,de,ie}/search | UK, Germany and Ireland |
| Overview | companies/{id} (includes=name&includes=company_status etc) | legalentity/{gb,de,ie}/{crn}/summary | UK, Germany and Ireland |
| Corporate structure | companies/{id} (includes=corporate_structure) | legalentity/{gb,de}/{crn}/corporatestructure | UK and Germany, Ireland coming soon |
| Directors | companies/{id} (includes=directors) | legalentity/{gb,de}/{crn}/directors | UK and Germany, Ireland coming soon |
| Financials | companies/{id} (includes=latest_accounts,historic_accounts) | legalentity/{gb,de,ie}/{crn}/financials | UK, Germany and Ireland |
All of the endpoints use the Company Registration Number (company_registration_number) as the parameter to get the right data.
- For the UK this is the Companies House ID
- For Ireland this is the Companies Registration Office (CRO) number
- For Germany to create a unique ID we have combined the registered court and Handelsregister number in a consistent and structured way to make using these easier across the endpoints. This includes a three letter code for the court, then the Handelsregister number without spaces. The full list of court codes can be found here. For example:
- Berlin (Charlottenburg) HRB 12300 B is BER_HRB12300B
- Frankfurt/Oder HRB 12158 FF is FRO_HRB12158FF
- Saarbrücken VR 5160 is SAA_VR5160
Person (person/)
person/)| Data you want | v1 | v2 |
|---|---|---|
| Search for a person | people | person/search |
| Overview | people/{id} | person/{id}/summary |
| A saved collection | collections/people | person/collection/{collection_id} |
The structure of the response from the person endpoint is similar, there are a couple of field name changes to improve consistency and clarity.
| v1 | v2 |
|---|---|
people_id | person_id |
currently_active | is_active |
is_a_company_founder | is_founder |
Authentication
There is no change to how you authenticate with v2. You can still use the same API key in the same way through adding the following header:
Authorization: APIkey <your-apikey>Rate limits
The rate limits of v2 are faster to work with, from 1 request per second in v1 to now being 30 requests per second. This is applied across all v2 endpoints per subscription.
Pagination and response format
The response structure is unchanged - you'll still get:
{
"meta": { "total": 128, "limit": 20, "offset": 0, "count": 20 },
"results": [ ... ]
}v2 adds one new field: meta.query, which returns the filters you searched with. It's there so you can confirm what a given page of results was actually filtered by which is useful for context of what has been returned and why.
Search and Collections
| Data you want | v1 | v2 | Improvements |
|---|---|---|---|
| Search for a Company | companies/search | For True Companies: truecompany/searchFor legal entities: legalentity/{gb,de,ie}/search | Choose what data model you want and get more insight into the results including the name of the company |
| Search for a person | people | person/search | |
| Search for a saved collection | collections/companycollections/people | collections | Same endpoint to see all collections in your subscription. Now showing who created it and when |
| Search for contents in a collection | companies/search?collection_id=123people?collection_id={collection_id} | truecompany/collection/{collection_id}person/collection/{collection_id} | Consistent way to find which entities are in collections |
Search works in a similar way. The key changes are that now you can choose the type of company data you want to get, either the operational company through the True Company search or the as filed registry data through the legal entity searches. These all return more context about the results including the name and country rather than just the ID.
To search for True Companies you can use:
- An identifier of a company: name, website or registration number
- True Company collections to find companies in lists you have saved on the Beauhurst platform
To search for legal entities you can use the registered name or:
- The Companies House ID for UK
- Companies Registration Office (CRO) number of Ireland
- The Handelsregister number and registered court for Germany. Handelsregister numbers are unique within a registered court so you can add this context to narrow down results. The full list of registered courts can be found here.
To search for people you need to use the Beauhurst person_id which can be found in the results of:
person/collection/{collection_id}truecompany/{id}/keypeopletruecompany/{id}/shareholderstruecompany/{id}/directorslegalentity/gb/{crn}/directors
Collections work in a similar way where you can access your True Company and People collections from the platform.
We have combined the endpoint to find all collections in your subscription which you can filter by entity type, when it was created and if it has been modified. This returns a list of the collections, their IDs, what type they are, who created it and when. This includes all collection types, at the moment only True Company or Person collections can be accessed through the API.
Using these IDs in the True Company or Person collection endpoint returns the entities in that collection which you can filter by when they were added to the collection and if they have been modified. Use the IDs returned in the relevant True Company or Person endpoints to get detailed data back.
If a company collection you access through v1 and want in v2 isn’t yet a True Company collection let your Account Manager know who can help migrate it.
Other changes
Contact data
We have moved contact data to a dedicated endpoint to ensure you are only getting the contact information for the people you want rather than it being returned by default.
This is now a new endpoint where you can use a person_id to find the contact details of a person and you can filter by the company: person/{person_id}/contacts
Legacy data
We have removed some of our legacy data fields.
| Category | Fields | Comments |
|---|---|---|
| Tracking | tracked_statusstarted_tracking_attracking_reasons | We no longer classify companies as tracked as we now cover all of the private companies in the UK, Ireland and Germany - not just the high growth ecosystem |
| Sectors | sectorstop_level_sector_groups | Sectors were our old classification system for what a company does. These have been replaced by our industries and top_level_industry_groups |
News
The company news endpoint hasn’t been replicated in v2. We will be adding news to v2 but are investigating the best way to surface news insights and improve on the version available in v1.
If you currently use the company news endpoint in v1 and want this in v2 please get in touch with our API Product Manager on [email protected].
Suggested migration path
- Determine where you need True Company or legal entity data
- Understand how you will identify the right record
- This could be using an identifier such as the company name, ID or website
- Or if using collections on Beauhurst identify the relevant ones. If the company collection you want isn’t yet a True Company collection let your Account Manager know who can help migrate it.
- Identify where to get the same data you need to continue your workflow
- Check if any new data available through v2 would improve your workflow. This could be new datasets such as the full financials or acquisitions data or understanding duplicates where multiple records in your systems relate to the same True Company and are the same operating business.
Any questions
If you have any questions please get in touch with your Account Manager or our API Product Manager on [email protected]