Migration Guide - v1 to v2

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

v1v2
Base URLhttps://platform.beauhurst.com/_api/v1/https://platform.beauhurst.com/_api/v2.0/
Company modelOne combined resourceSplit into True Companies and legal entities
Getting dataOne call with an includes parameterOne call per datatype
Rate limit1 request per second30 requests per second
PaginationUp to 100 results per pageSame, with additional context of the request in meta
CurrencyAll values GBPCurrency 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:

  1. 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
  2. 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:

  1. Call the v1 Companies endpoint with the Beauhurst company IDs and includes=companies_house_id to get each company’s Companies House ID
  2. Use this in the UK legal entity endpoints or call truecompany/search with company_registration_number and corporate_register_country=gb to get the true_company_id
  3. 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/)

Data you wantv1v2Improvements
Searchcompanies/searchtruecompany/search
Overviewcompanies/{id} (includes=name&includes=company_status etc)truecompany/{id}/summary
Corporate structurecompanies/{id} (includes=corporate_structure)truecompany/{id}/corporatestructureNow shows the hierarchy of subsidiary entities
Directorscompanies/{id} (includes=directors)truecompany/{id}/directorsNow separated out so you can filter by who is active
Financialscompanies/{id} (includes=latest_accounts,historic_accounts)truecompany/{id}/financialsNow has the full financial filings rather than just a summary
Shareholderscompanies/shareholdingstruecompany/{id}/shareholders
Key peoplecompanies/{id} (includes=key_contacts)truecompany/{id}/keypeopleNow separated out so you can filter by job function
Patentscompanies/patentstruecompany/{id}/patents
Fundraisingstransactions/company (includes=fundraisings)truecompany/{id}/fundraisings
Grantstransactions/company (includes=grants)truecompany/{id}/grants
Acquisitions—truecompany/{id}/acquisitionsNew dataset
A saved collectioncollections/companytruecompany/collection/{collection_id}

There are some field names that have been updated to improve consistency and clarity in the fundraisings endpoint.

v1v2
idfundraising_id
amount_raised_gbpamount_raised_announced
amount_raised_verified
(Each with currency and gbp)
valuation_gbppre_money_valuation
post_money_valuation
purposes_of_fundingpurposes_of_fundraising
types_of_fundingtypes_of_fundraising
investor_names / investorsNow combined into one group with a list of:
investor_id
investor_name
fund_type
amount_contributed

Legal entity (legalentity/{gb,de,ie}/)

Data you wantv1v2Coverage
Searchcompanies/searchlegalentity/{gb,de,ie}/searchUK, Germany and Ireland
Overviewcompanies/{id} (includes=name&includes=company_status etc)legalentity/{gb,de,ie}/{crn}/summaryUK, Germany and Ireland
Corporate structurecompanies/{id} (includes=corporate_structure)legalentity/{gb,de}/{crn}/corporatestructureUK and Germany, Ireland coming soon
Directorscompanies/{id} (includes=directors)legalentity/{gb,de}/{crn}/directorsUK and Germany, Ireland coming soon
Financialscompanies/{id} (includes=latest_accounts,historic_accounts)legalentity/{gb,de,ie}/{crn}/financialsUK, 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/)

Data you wantv1v2
Search for a personpeopleperson/search
Overviewpeople/{id}person/{id}/summary
A saved collectioncollections/peopleperson/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.

v1v2
people_idperson_id
currently_activeis_active
is_a_company_founderis_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 wantv1v2Improvements
Search for a Companycompanies/searchFor True Companies: truecompany/search

For 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 personpeopleperson/search
Search for a saved collectioncollections/companycollections/peoplecollectionsSame endpoint to see all collections in your subscription. Now showing who created it and when
Search for contents in a collectioncompanies/search?collection_id=123

people?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}/keypeople
  • truecompany/{id}/shareholders
  • truecompany/{id}/directors
  • legalentity/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.

CategoryFieldsComments
Trackingtracked_status
started_tracking_at
tracking_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
Sectorssectors
top_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

  1. Determine where you need True Company or legal entity data
  2. 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.
  3. Identify where to get the same data you need to continue your workflow
  4. 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]