> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedatacity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get an API key and match your first company in a few minutes.

## 1. Get an API key

Company Matching uses **customer API keys**, not login JWTs, on the match endpoints.

Contact [support@thedatacity.com](mailto:support@thedatacity.com) for a key. Keys look like:

```text theme={null}
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](/company-matching/guides/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.

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```

  ```python Python theme={null}
  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()
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

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:

```json theme={null}
{
  "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](/company-matching/guides/batch): submit the list, then poll status or receive a completion webhook.

## What's next

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/company-matching/guides/authentication">
    How keys work and how to send them.
  </Card>

  <Card title="Response reference" icon="brackets-curly" href="/company-matching/guides/response-reference">
    Every field in the response, and when it is empty.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/company-matching/guides/errors">
    Status codes and retry guidance.
  </Card>

  <Card title="Endpoint reference" icon="code" href="/company-matching">
    Full request/response schema with the interactive playground.
  </Card>
</CardGroup>

<Snippet file="need-help.mdx" />