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
`active`	string \| null	Active / inactive (or equivalent) when known
`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.

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",
  "active": "Active",
  "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,
  "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",
  "active": "Active",
  "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

​Example (matched)

​Example (unmatched)

​Example (with address)

​Request body fields