UK Company Data API quickstart: your first call in 5 minutes

What you will have at the end

In five minutes you will have a working API key, a company number found by name, that company's balance sheet history as JSON and a watchlist that reports status changes and overdue accounts. Every example was run against the live API on 17 October 2026. The data covers the full Companies House register and figures from about 37 million machine-readable accounts filed from 2008 to 2026.

You need curl, or Python 3 with requests, or any JavaScript runtime with fetch (Node 18+, Bun, Deno or a browser).

Step 1: get a free key

Send one POST request; no card and no sign-up form are needed. Adding an email address is optional.

curl -X POST https://data.globalmindsetmarketing.co.uk/v1/keys/free \
  -H "Content-Type: application/json" \
  -d '{}'

The response is shown once, so save the key straight away:

{
  "api_key": "ukcd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "plan": "free",
  "monthly_quota": 50,
  "note": "Save this key now, it will not be shown again. Use it as: Authorization: Bearer <key>"
}

Keep it out of your code. The examples below read it from an environment variable:

export UKCD_KEY="ukcd_your_key_here"

On Windows PowerShell use $env:UKCD_KEY = "ukcd_your_key_here". You can also get a key from the button on the developer docs page.

Step 2: find a company by name

/v1/search-by-name searches all companies on the register and returns company numbers. Exact name matches and active companies come first.

curl -H "Authorization: Bearer $UKCD_KEY" \
  "https://data.globalmindsetmarketing.co.uk/v1/search-by-name?name=tesco&limit=2&format=json"

{
  "query": "tesco",
  "results": [
    {
      "company_number": "00445790",
      "name": "TESCO PLC",
      "status": "Active",
      "type": "Public Limited Company",
      "post_town": "WELWYN GARDEN CITY",
      "incorporated": "1947-11-27",
      "sic_codes": ["47110 - Retail sale in non-specialised stores with food, beverages or tobacco predominating"]
    },
    {
      "company_number": "05888925",
      "name": "TESCO PROPERTY FINANCE 1 PLC",
      "status": "Active",
      "type": "Public Limited Company",
      "post_town": "WELWYN GARDEN CITY",
      "incorporated": "2006-07-27",
      "sic_codes": ["70100 - Activities of head offices"]
    }
  ],
  "source": "Companies House register and iXBRL accounts bulk data, Open Government Licence v3.0",
  "note": "Figures as filed by the company, in GBP. Not a credit rating."
}

If you already have a number, skip this step. Company numbers are always 8 characters; see company number formats if yours is shorter.

Step 3: get the company and its accounts

/v1/company returns the register record and one entry per machine-readable accounts filing, newest first.

curl -H "Authorization: Bearer $UKCD_KEY" \
  "https://data.globalmindsetmarketing.co.uk/v1/company?number=10623966&format=json"

Abridged response:

{
  "company": {
    "company_number": "10623966",
    "name": "TESCONS LTD",
    "status": "Active",
    "type": "Private Limited Company",
    "incorporated": "2017-02-16",
    "accounts": { "category": "TOTAL EXEMPTION FULL", "last_made_up_to": "2025-05-31", "next_due": "2027-02-28" },
    "charges_outstanding": 0
  },
  "accounts": [
    {
      "balance_sheet_date": "2025-05-31",
      "figures": { "net_assets": 183, "cash": 967, "current_assets": 10818, "turnover": null }
    },
    {
      "balance_sheet_date": "2024-05-31",
      "figures": { "net_assets": 1150, "cash": 9727 }
    }
  ]
}

Values are in pounds, as filed. A field is null when the company did not file it: most small companies do not publish turnover. Companies that file only PDF accounts, such as TESCO PLC, return an empty accounts array.

The same call in Python

import os
import requests

BASE = "https://data.globalmindsetmarketing.co.uk"
HEADERS = {"Authorization": f"Bearer {os.environ['UKCD_KEY']}"}

r = requests.get(f"{BASE}/v1/company",
                 params={"number": "10623966", "format": "json"},
                 headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()

print(data["company"]["name"], data["company"]["status"])
for acc in data["accounts"]:
    f = acc["figures"]
    print(acc["balance_sheet_date"], f.get("net_assets"), f.get("cash"))

Output:

TESCONS LTD Active
2025-05-31 183 967
2024-05-31 1150 9727
2023-05-31 1147 3343

The same call in JavaScript

const BASE = "https://data.globalmindsetmarketing.co.uk";
const headers = { Authorization: `Bearer ${process.env.UKCD_KEY}` };

const res = await fetch(`${BASE}/v1/company?number=10623966&format=json`, { headers });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();

console.log(data.company.name, data.company.status);
for (const acc of data.accounts) {
  console.log(acc.balance_sheet_date, acc.figures.net_assets, acc.figures.cash);
}

Save it as company.mjs and run node company.mjs or bun company.mjs. In a browser, the API sends CORS headers, but do not ship your key in front-end code: call the API from your server.

Step 4: watch companies and read alerts

A watchlist snapshots each company's current state, and /v1/alerts reports what has changed. The free plan watches 5 companies; API Pro watches 50.

curl -X POST -H "Authorization: Bearer $UKCD_KEY" -H "Content-Type: application/json" \
  -d '{"company_numbers":["10623966","00445790"]}' \
  "https://data.globalmindsetmarketing.co.uk/v1/watchlist/add"

curl -H "Authorization: Bearer $UKCD_KEY" \
  "https://data.globalmindsetmarketing.co.uk/v1/alerts?format=json"

A fresh watchlist has nothing to report yet:

{ "since": "2026-09-17", "watched": ["00445790", "10623966"], "alerts": [] }

Alerts cover status changes (liquidation, administration, strike-off), overdue accounts, newly published accounts, new charges, negative net assets and falls of 30% or more in net assets or cash between the last two filings, sorted by severity. Overdue accounts alone affect tens of thousands of companies: on 1 October 2026, 93,785 active companies were past their accounts due date (overdue accounts statistics). GET /v1/watchlist lists what you watch and POST /v1/watchlist/remove takes the same body as add.

Step 5: use it from Claude Code with MCP

The same key works with our MCP server, so an AI assistant can call the tools for you. In Claude Code, run one command:

claude mcp add --transport http uk-company-data https://data.globalmindsetmarketing.co.uk/mcp --header "Authorization: Bearer YOUR_KEY"

Then ask, for example, "Compare the last three balance sheets of company 10623966". Setup for Claude Desktop, ChatGPT and Cursor is in the Companies House MCP server guide.

JSON or Markdown

Add format=json for one JSON field per figure. Without it, every endpoint returns the same shape as an MCP tool result: a content array whose first item is Markdown text with tables, ready to show to a person or pass to a language model. The watchlist add and remove calls always return that Markdown shape.

Errors and limits

Errors come back as JSON with an error message.

Each REST call or MCP tool call counts as one request. Free is 50 requests a month; API Pro is £39 a month for 5,000 requests and a 50-company watchlist (pricing).

Next steps

• Read why the figures need careful parsing in parsing iXBRL accounts in Python.
• See every field and coverage gap in Companies House financial data as JSON.
• Compare providers in Companies House API alternatives.
• Full endpoint reference, including screening and trigger endpoints: the developer docs and the OpenAPI spec.

FAQ

Do I need a card or an account to get a key?

No. One POST request to /v1/keys/free returns a key on the free plan, with 50 requests a month and a 5-company watchlist. You can add an email address in the request body if you want, but it is optional. The key is shown only once, so store it in an environment variable or a secrets manager straight away.

Why is the accounts array empty for some companies?

The figures come from machine-readable iXBRL accounts. Companies that file only PDF or paper accounts, which includes many large groups such as TESCO PLC, have no parsed figures, and companies that have not filed accounts yet have none either. The company record, status and filing dates are still returned for every company on the register.

Does the API return turnover and profit?

Yes, when the company filed them. Most UK companies file micro-entity or filleted accounts without a profit and loss account, so turnover is null for most small companies. Balance sheet figures such as net assets, cash, debtors and creditors are much more widely available.

Is the data free to reuse?

The underlying Companies House data is published under the Open Government Licence v3.0, which allows commercial reuse with attribution, and every response carries a source line for that purpose. Our plans charge for the parsing, storage and API, not for the public data itself.

Sources: Companies House register and accounts data (Open Government Licence v3.0), legislation.gov.uk and GOV.UK guidance where linked. This page is general information, not legal, tax or credit advice. Spotted an error? Email info@globalmindsetmarketing.co.uk.