Skip to content

Core API

Look up a UK company by company number

Fetch a normalised company profile and assess what the response can—and cannot—tell you.

Updated 7 September 2026 5 min read

Start with the company number, not a display name. A single entity request returns the normalised profile plus the source-accountability fields that tell you whether the result is complete enough for your workflow.

Make the request

curl "https://api.rotuli.co.uk/v1/entity/00445790" \
  -H "Authorization: Bearer $ROTULI_API_KEY"

The public endpoint is GET /entity/{company_number}. Send a bearer key from a server, worker, or command-line environment; do not put it in browser code. The example number is Tesco PLC, used only as a reproducible format example.

Read the response in two passes

  1. Establish identity from company_number, name, status, and the ch profile object.
  2. Establish evidence from sources_checked and sources_failed before treating any absence as meaningful.

sources_checked is every source the API attempted for the request. sources_failed is an object keyed by the checked sources that could not be queried. A failed source remains in both places. Successful sources are therefore sources_checked minus the keys in sources_failed.

Request only the records you need

The optional sources query parameter can restrict the entity request. The current contract names ch, ch_psc, insolvency, charges, and officers. Use it when a step only needs a subset, but record that a skipped source was not assessed.

https://api.rotuli.co.uk/v1/entity/00445790?sources=ch,officers

Do not turn unknown into none

The charges.status and officers.status fields are tri-state. none is a confirmed absence; present means records exist; unknown means the source was not requested or could not be fetched. Treat unknown as missing evidence, never as a negative result.

Lists may also be incomplete. When charges.truncated or officers.truncated is true, the items array is shorter than the upstream total and must not be read as the whole record.

Use risk signals carefully

Entity responses can include risk_signals, but it is a paid feature and is omitted for free-tier keys. Its absence means the caller is not entitled to the feature—not that the company has no risk. For screening logic, use the dedicated risk-screening guide.

Continue from a small client

The dependency-free example client keeps the key in ROTULI_API_KEY, exposes an entity() method, and returns the JSON untouched. See examples/company-lookup.mjs in this repository and the bulk enrichment pattern when you have more than one number.