Companies House

Companies House is the UK register of companies. The SAFE Billing Platform uses it to pull profile details (registered address, incorporation date, employee count, asset totals and similar fields) onto your UK Limited and UK PLC customer records.

Out of the box, the platform uses a shared default key to run a one-off Companies House lookup the first time you put a customer into a class with the Check Companies House flag set, for example when you change a new customer’s class to UK Limited (see Customer Classes). This works without any setup on your part, but the shared key only covers that initial lookup. Later edits to a customer will not re-fetch Companies House data, so the profile fields stay frozen at whatever was pulled when the class was first set.

Configuring your own Companies House API key changes that. Once your key is in place, it takes over from the shared key for all Companies House traffic from the platform - the initial lookup and the new periodic background refresh of existing UK Limited and UK PLC customer profiles. The refresh keeps data current as Companies House records change, and all the traffic counts against your own Companies House rate limits rather than the shared pool.

What you need

• A Companies House account (free to set up)
• Elevated access in the SAFE Billing Platform

Step 1 - Sign up for a Companies House account

If you already use Companies House to file or search records, you can reuse that account and skip to Step 2.

Steps:

1. Go to https://find-and-update.company-information.service.gov.uk/signin
2. Click Register and enter your email address
3. Open the single-use link sent to your inbox
4. Set a password to finish creating the account

Step 2 - Create a Live application

Companies House groups API keys under “applications”, so first create one for the platform.

Steps:

1. Go to https://developer.company-information.service.gov.uk/manage-applications/add
2. Give the application a name, for example “SAFE Billing Platform”
3. Add a short description, for example “Customer profile lookup”
4. Choose the Live environment

Step 3 - Generate a REST API key

Once the application is created, generate a key for it.

Steps:

1. Open the application from your list of applications
2. Click Create New Key
3. Choose REST as the key type
4. Give the key a name, for example “Production”
5. Copy the key and store it somewhere safe

Companies House will not show the full key again later. If you lose it, generate a new key and update the platform.

Step 4 - Enter the key in the platform

Steps:

1. Go to Main Menu > Advanced tab > Companies House
2. Paste the key into the Companies House API key field
3. Click Save API Key

The page then shows the current status as “Configured (ends XXXX)”, where XXXX is the last four characters of the key. The full key is never displayed again.

To replace a key: Paste the new key and click Save API Key. The old key is overwritten.

To remove the key: Tick Clear current key and click Save API Key.

What happens next

• Once your key is saved, the platform uses it for all Companies House traffic, replacing the shared default key.
• The initial lookup when a customer is first put into a class with Check Companies House enabled continues to run as before, now using your key.
• On top of that, the platform refreshes existing UK Limited and UK PLC customer profiles in the background on a regular basis. Changes such as a new registered address or updated filed accounts flow through to the customer record automatically.
• All Companies House traffic now counts against your own rate limits rather than the shared pool.

See Customer Classes for which classes trigger the lookup and what fields get populated.