Quickstart - The Data City

1. Get an API key

Company Matching uses customer API keys, not login JWTs, on the match endpoints. Contact support@thedatacity.com for a key. Keys look like:

dm_live_…

Treat the key like a password. Store it in an environment variable or secrets manager. Never commit it to source control or ship it in a browser bundle. See Authentication for details.

2. Match one company

Send a POST to /api/v1/match with at least input_name. Include your key in the Authorization header.

curl -sS -X POST "https://datamatcher-api.thedatacity.com/api/v1/match" \
  -H "Authorization: Bearer dm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input_name":"Sainsbury'\''s Supermarkets Ltd","id":"demo-sainsburys"}'

import httpx

resp = httpx.post(
    "https://datamatcher-api.thedatacity.com/api/v1/match",
    headers={"Authorization": "Bearer dm_live_YOUR_KEY"},
    json={
        "input_name": "Sainsbury's Supermarkets Ltd",
        "id": "demo-sainsburys",
    },
    timeout=120.0,
)
data = resp.json()

const resp = await fetch(
  "https://datamatcher-api.thedatacity.com/api/v1/match",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer dm_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      input_name: "Sainsbury's Supermarkets Ltd",
      id: "demo-sainsburys",
    }),
  }
);
const data = await resp.json();

Set your client timeout to at least 60–120 seconds. Matching can call several external sources; cold runs are slower than cached ones. Optional fields that improve accuracy when you have them:

Field	Purpose
`input_url`	Company website
`postcode`	Improves match scoring
`sic_code`	Improves match scoring
`start_trading_date`	Improves match scoring (year is enough)
`id`	Your own row id, echoed in the response

3. Read the result

A successful response looks like this:

{
  "input_name": "Sainsbury's Supermarkets Ltd",
  "id": "demo-sainsburys",
  "input_url": null,
  "postcode": null,
  "sic_code": null,
  "start_trading_date": null,
  "matched_company_number": "3261722",
  "matched_company_name": "SAINSBURY'S SUPERMARKETS LTD",
  "active": "Active"
}

If no confident match is found, matched_company_number (and related fields) are null. That is still a 200 — check for a present CRN rather than assuming every call resolves.

Matching a list

For more than one company, use the batch API: submit the list, then poll status or receive a completion webhook.

What’s next

Authentication

How keys work and how to send them.

Response reference

Every field in the response, and when it is empty.

Errors

Status codes and retry guidance.

Endpoint reference

Full request/response schema with the interactive playground.

​1. Get an API key

​2. Match one company

​3. Read the result

​Matching a list

​What’s next