Batch matching - The Data City

Use the batch API when you have a list. One submit request queues the work; matching runs asynchronously.

1. Submit

curl -sS -X POST "https://datamatcher-api.thedatacity.com/api/v1/match/batch" \
  -H "Authorization: Bearer dm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companies": [
      {"input_name": "Sainsbury'\''s Supermarkets Ltd", "id": "demo-001"},
      {"input_name": "John Lewis plc", "id": "demo-002"},
      {"input_name": "Holmes Joinery Partners LLP", "id": "demo-003"}
    ]
  }'

Response (202 Accepted):

{
  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "queued",
  "total": 3
}

Maximum batch size: 1,000 companies. Larger payloads return 422. Jobs are retained for 30 days from creation (expires_at on the status payload).

2. Poll status

curl -sS "https://datamatcher-api.thedatacity.com/api/v1/match/batch/{job_id}" \
  -H "Authorization: Bearer dm_live_YOUR_KEY"

{
  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "running",
  "total": 3,
  "completed_count": 1,
  "error_count": 0,
  "error_message": null,
  "created_at": "2026-08-17T12:00:00Z",
  "started_at": "2026-08-17T12:00:01Z",
  "finished_at": null,
  "expires_at": "2026-09-16T12:00:00Z"
}

Status	Meaning
`queued`	Accepted, not started
`running`	Matching in progress (partial results may already be available)
`completed`	Finished
`failed`	Job-level failure — see `error_message`

Poll every few seconds. Avoid tight polling loops.

3. Fetch results

Results are available once status is running, completed, or failed. Requesting them while still queued returns 409.

curl -sS "https://datamatcher-api.thedatacity.com/api/v1/match/batch/{job_id}/results?skip=0&limit=100" \
  -H "Authorization: Bearer dm_live_YOUR_KEY"

Query	Default	Notes
`skip`	`0`	Offset into the result list
`limit`	`100`	Page size, max 1000

Each item in data uses the same fields as POST /match. See Response reference.

4. Completion webhook

Optional. Pass callback_url on submit to receive one POST when the job reaches completed or failed. Polling still works.

curl -sS -X POST "https://datamatcher-api.thedatacity.com/api/v1/match/batch" \
  -H "Authorization: Bearer dm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://example.com/hooks/datamatcher",
    "webhook_secret": "at-least-16-chars",
    "companies": [
      {"input_name": "Sainsbury'\''s Supermarkets Ltd", "id": "demo-001"}
    ]
  }'

callback_url must be https (http is allowed only in local development). Private, loopback, and link-local hosts are rejected outside local development. Cloud metadata addresses such as 169.254.169.254 are always rejected. The webhook body is the same shape as GET /match/batch/{job_id}, plus event:

{
  "event": "job.completed",
  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "completed",
  "total": 3,
  "completed_count": 3,
  "error_count": 0,
  "error_message": null,
  "created_at": "2026-08-17T12:00:00Z",
  "started_at": "2026-08-17T12:00:01Z",
  "finished_at": "2026-08-17T12:00:10Z",
  "expires_at": "2026-09-16T12:00:00Z"
}

event is job.completed or job.failed. If you set webhook_secret (16–128 characters), the request includes:

X-DataMatcher-Signature: sha256=<hex>

The hex digest is HMAC-SHA256 of the raw JSON body using your secret. Verify against the bytes you received; do not re-serialise the JSON first. Respond with 2xx. Delivery is attempted once. A failed webhook does not fail the job — poll status if you miss it. Retrying misses on a finished job queues it again; a second webhook fires when that run finishes.

Ownership

Jobs are scoped to the user who owns the API key. Another account’s job_id returns 404.

​1. Submit

​2. Poll status

​3. Fetch results

​4. Completion webhook

​Ownership

1. Submit

2. Poll status

3. Fetch results

4. Completion webhook

Ownership