Response reference - The Data City

A successful match returns a JSON object with the fields below.

Response fields

These fields are returned on POST /match and on each row in batch results.

Field	Type	When present
`input_name`	string	Always — echoed from the request
`id`	string \| null	Your optional row id, if you sent one
`input_url`	string \| null	Echoed if provided
`input_postcode`	string \| null	Echoed if provided
`address`	string \| null	Echoed if provided
`sic_code`	string \| null	Echoed if provided
`start_trading_date`	string \| null	Echoed if provided
`matched_company_number`	string \| null	Set when a match is found; otherwise `null`
`matched_company_name`	string \| null	Registered name for the matched CRN, when available
`matched_registered_postcode`	string \| null	Registered office postcode for the matched CRN, when available
`company_status`	string \| null	The matched company’s status as Companies House reports it; `null` when unmatched. See Company status
`active`	string \| null	Deprecated, use `company_status`. `"True"` when the matched company is not dissolved, `"False"` when it is; `null` when unmatched
`confidence`	string	Always — `high`, `medium`, `low`, or `none`
`rigorous_match`	boolean	Always
`route`	string \| null	`"fast"`, `"slow"`, or `null` when unmatched

A 200 with matched_company_number: null means the engine finished without a confident match. That is not an error. In that case confidence is none and route is null.

Confidence

confidence tells you how strong the match evidence is. It is not a percentage probability.

Value	Typical meaning
`high`	Exact name match on the fast path, or a slow-path match that passed the stricter scoring check (`rigorous_match: true`)
`medium`	Slow-path match that did not pass the stricter check (`rigorous_match: false`)
`low`	Weak evidence for the chosen company, or a band reduced as described below
`none`	No CRN returned, or the match failed for that row

If part of the pipeline was unavailable for that row (for example a website lookup), the band may drop one notch (e.g. high → medium). Use confidence to triage results — for example auto-accept high, review medium or low. Always check matched_company_number to see whether a CRN was returned.

Route

route records which stage produced the match:

Value	Meaning
`fast`	Exact (normalised) name match against company data — usually quick and strong
`slow`	Full multi-source pipeline (search, scoring, optional website signals)
`null`	No match

Rigorous match

rigorous_match is true when the slow path cleared the stricter scoring check for the chosen company.

A fast-path match does not need that check, so it can be confidence: high with rigorous_match: false.
On the slow path, rigorous_match: true is what lifts a result to confidence: high, subject to the band reduction noted above.

Treat rigorous_match as a technical signal; prefer confidence for product decisions unless you are debugging match quality.

Company status

company_status is the matched company’s status exactly as Companies House reports it. The values you will see:

Value	Meaning
`Active`	Registered and filing normally
`Active - but in an unusual state (Active with Dormant Accounts)`	Registered but filing dormant accounts, so it is unlikely to be the trading business
`Active - but in an unusual state (Active - Proposal To Strike Off)`	Companies House has proposed removing it from the register
`Active - but in an unusual state (Liquidation)`, `(In Administration)`, and other unusual states	Still registered, in an insolvency or similar process
`Struck off (Dissolved)`	No longer registered
`null`	No match, or the status is not known for this row

When several registered companies share a name, the match prefers the one in the healthiest status, in the order above. active is kept for compatibility and will be removed in the next API version. It is "True" when company_status is anything other than dissolved, and "False" when the company is dissolved.

Example (matched)

{
  "input_name": "Sainsbury's Supermarkets Ltd",
  "id": "demo-sainsburys",
  "input_url": null,
  "input_postcode": null,
  "address": null,
  "sic_code": null,
  "start_trading_date": null,
  "matched_company_number": "3261722",
  "matched_company_name": "SAINSBURY'S SUPERMARKETS LTD",
  "matched_registered_postcode": "EC1N 2HT",
  "company_status": "Active",
  "active": "True",
  "confidence": "high",
  "rigorous_match": true,
  "route": "fast"
}

Example (unmatched)

{
  "input_name": "Completely Unknown Trading Style XYZ",
  "id": "row-42",
  "matched_company_number": null,
  "matched_company_name": null,
  "matched_registered_postcode": null,
  "company_status": null,
  "active": null,
  "confidence": "none",
  "rigorous_match": false,
  "route": null
}

Example (with address)

{
  "input_name": "Holmes Joinery Partners LLP",
  "id": "demo-holmes",
  "input_postcode": null,
  "address": "Unit 4, Industrial Estate, Leeds LS1 4DY",
  "matched_company_number": "OC123456",
  "matched_company_name": "HOLMES JOINERY PARTNERS LLP",
  "company_status": "Active",
  "active": "True",
  "confidence": "high",
  "rigorous_match": true,
  "route": "slow"
}

Request body fields

Field	Required	Notes
`input_name`	Yes	1–512 characters
`input_url`	No	Website URL (up to 2048 characters)
`input_postcode`	No	Improves match scoring. Takes precedence over a postcode found in `address`
`address`	No	Full address (up to 512 characters). If `input_postcode` is omitted, a UK postcode found in the address is used for scoring
`sic_code`	No	Improves match scoring
`start_trading_date`	No	Improves match scoring; a year string is enough
`id`	No	Your correlation id (up to 128 characters)

Null optional fields may be omitted from the request; the API does not require them.

​Response fields

​Confidence

​Route

​Rigorous match

​Company status

​Example (matched)

​Example (unmatched)

​Example (with address)

​Request body fields