# Profile Match: integration specification

| | |
|---|---|
| API | v1 |
| Specification version | 2.0 |
| Last updated | 2026-11-12 |
| Base URL | `{BASE_URL}/api/v1` |
| Format | JSON over HTTPS, UTF-8 |
| Authentication | `X-API-Key` header |

This document describes how another system uses the Profile Match engine in two
ways:

- **Match:** send two to six person records and get back, for every pair, a
  verdict, a match probability and the evidence field by field.
- **Search:** send one person and get back the people in the **population** (the
  people the matcher holds) most likely to be them, ranked, with the same
  verdict, probability and evidence. Your system can also keep the population up
  to date through the API.

Every person in the population belongs to one or more **population types**
(Citizens, Residents, Visa Holders, Confirmed Identities, …). A search can look
in every type or only in the types you name; adding a person needs at least one.

The same engine and settings serve the Profile Match console.

## Contents

1. [Before you start](#1-before-you-start)
2. [Conventions](#2-conventions)
3. [Endpoints](#3-endpoints)
4. [The person record](#4-the-person-record)
5. [Reading match and search results](#5-reading-match-and-search-results)
6. [Errors](#6-errors)
7. [Code samples](#7-code-samples)
8. [Operational notes](#8-operational-notes)
9. [Changelog](#9-changelog)

## 1. Before you start

### Base URL

Every path in this document is relative to `{BASE_URL}`, the address where the
service is hosted for your environment, for example:

| Environment | `{BASE_URL}` |
|---|---|
| Local development | `http://localhost:8000` |
| Your test or production host | the address your administrator gives you, e.g. `https://matching.example.org` |

Paths do not change between environments; only `{BASE_URL}` does. Keep it in
your configuration, not in code.

### API key

1. An administrator opens `{BASE_URL}/api-reference` **on the server itself**,
   goes to the *API keys* tab and creates a key for your system.
2. The key is shown once. Store it in your secret store, never in source code or
   logs.
3. Send it on every call (except `GET /health`) in the `X-API-Key` header.

| Scope | Can |
|---|---|
| `match` | Run matches and searches; read saved matches, the population, settings and reference data |
| `registry` | Everything `match` can, plus add, change, import and remove people in the population |
| `admin` | Everything `registry` can, plus change the server's match settings and clear the population |

Give each system its own key so one can be revoked without stopping the others.
A revoked key gets `401` at once. Saved runs show the name of the key that made
them.

## 2. Conventions

- Requests with a body send `Content-Type: application/json`.
- Dates are `YYYY-MM-DD`. Timestamps are ISO 8601 in UTC, e.g.
  `2026-10-22T09:18:04.512Z`.
- Probabilities are numbers from 0 to 1.
- Unknown values: send an empty string `""` or leave the field out.
- Unknown fields in a request body are ignored.
- Errors use an HTTP 4xx status and a JSON body with `detail` (see
  [Errors](#6-errors)).
- Breaking changes will be published under a new version path (`/api/v2`).
  Within v1, new response fields may be added; ignore fields you do not know.

## 3. Endpoints

| Method | Path | Key | Purpose |
|---|---|---|---|
| `GET` | `/api/v1` | none | What the API offers: every endpoint and the key it needs |
| `GET` | `/api/v1/health` | none | Check the service is up |
| `GET` | `/api/v1/reference` | any | Fields and codes a record accepts |
| `GET` | `/api/v1/population-types` | any | The population types a person can belong to |
| `POST` | `/api/v1/match` | any | Compare two to six records |
| `GET` | `/api/v1/matches` | any | Search saved matches |
| `GET` | `/api/v1/matches/{match_id}` | any | One saved match |
| `GET` | `/api/v1/settings` | any | Current match settings |
| `PATCH` | `/api/v1/settings` | admin | Change match settings |
| `POST` | `/api/v1/search` | any | Search the population for one person |
| `GET` | `/api/v1/searches` | any | The search log |
| `GET` | `/api/v1/performance` | any | Counts and timings of matches, searches and imports |
| `GET` | `/api/v1/registry` | any | Population summary |
| `GET` | `/api/v1/registry/people` | any | Find people by attribute |
| `GET` | `/api/v1/registry/people/{person_id}` | any | One person |
| `GET` | `/api/v1/registry/people/ref/{ref}` | any | One person, by your ref |
| `POST` | `/api/v1/registry/people` | registry | Add a person |
| `PUT` | `/api/v1/registry/people/ref/{ref}` | registry | Add or replace a person, by your ref |
| `PUT` | `/api/v1/registry/people/{person_id}` | registry | Replace a person |
| `DELETE` | `/api/v1/registry/people/{person_id}` | registry | Remove a person |
| `POST` | `/api/v1/registry/imports` | registry | Add or update up to 5,000 people as one import |
| `GET` | `/api/v1/registry/imports` | any | Every import |
| `POST` | `/api/v1/registry/imports/{import_id}/undo` | registry | Undo an import |
| `POST` | `/api/v1/registry/clear` | admin | Remove everyone from the population |

"registry" means a key with the `registry` or `admin` scope.

The base URL itself, `GET /api/v1` (with or without a final `/`), needs no key.
It answers with the service name, how to authenticate, where the documentation
is, and every endpoint with its method, path, the key it needs (`none`, `any`,
`registry` or `admin`) and a summary:

```json
{
  "service": "Profile Match", "version": "2.0.0", "api": "v1", "status": "ok",
  "authentication": "Send an API key in the X-API-Key header on every call except GET /api/v1 and GET /api/v1/health.",
  "documentation": { "integration_spec": "/api-reference/integration-spec.md", "reference": "/api-reference",
                     "openapi": "/openapi.json" },
  "endpoints": [
    { "method": "GET", "path": "/api/v1/health", "key": "none", "summary": "Check the service is up" },
    { "method": "POST", "path": "/api/v1/match", "key": "any", "summary": "Compare two to six person records" }
  ]
}
```

`GET /api` lists the API versions (`{"versions": {"v1": "/api/v1"}, …}`).

### 3.1 `GET /api/v1/health`

Answers without a key. Use it for uptime checks.

```json
{ "status": "ok", "api": "v1", "version": "2.0.0", "commit": "e8e5546", "engine": "Splink 5.0.0 · DuckDB" }
```

| Field | Meaning |
|---|---|
| `status` | `"ok"` when the model is loaded |
| `api` | API version |
| `version` | Release of the service (MAJOR.MINOR.PATCH), raised with each release |
| `commit` | Short git commit of the code running; empty when unknown |
| `engine` | Matching engine and backend |

### 3.2 `GET /api/v1/reference`

The fields the model compares and the codes it understands. Read it once to
build your field mapping.

```json
{
  "max_records": 6,
  "fields": { "given_name": "Given name", "surname": "Surname", "dob": "Date of birth",
              "gender": "Gender", "nationality": "Nationality", "document": "Document" },
  "genders": { "M": "Male", "F": "Female", "X": "X (unspecified)" },
  "doc_types": { "P": "Passport", "V": "Visa", "I": "National ID" },
  "countries": [ { "code": "AFG", "name": "Afghanistan" }, "…" ],
  "population_types": { "citizens": "Citizens", "residents": "Residents", "visa_holders": "Visa Holders",
                        "confirmed_identities": "Confirmed Identities" }
}
```

`countries` lists every ISO 3166 country with its alpha-3 code.
`population_types` maps each type's code to its name; [3.12](#312-get-apiv1population-types) has the details.

### 3.3 `POST /api/v1/match`

Scores every pair of records with the trained model and links pairs at or above
the match threshold into people.

**Request**

```json
{
  "records": [
    { "ref": "CRM-20417", "given_name": "Sara", "surname": "Al-Haddad", "dob": "1990-04-12",
      "gender": "F", "nationality": "JOR", "doc_type": "P", "doc_number": "R4419027",
      "doc_country": "JOR", "doc_expiry": "2031-08-30" },
    { "ref": "VISA-88812", "given_name": "Sarah", "surname": "Haddad", "dob": "1990-04-12",
      "gender": "F", "nationality": "Jordan", "doc_type": "P", "doc_number": "R 441 9027",
      "doc_country": "JOR", "doc_expiry": "2031-08-30" }
  ],
  "settings": { "save": true }
}
```

| Field | Type | Required | Meaning |
|---|---|---|---|
| `records` | array | yes | 2 to 6 person records ([section 4](#4-the-person-record)). They are lettered `A`, `B`, `C`… in the order sent. |
| `settings.match_threshold` | number | no | Overrides the server setting for this call only. Between 0 and 1. |
| `settings.review_threshold` | number | no | Overrides the server setting for this call only. Must be below the match threshold. |
| `settings.save` | boolean | no | Save this run to the match history. Defaults to the server's `save_api_runs`. |

**Response** `200`

```json
{
  "id": 42,
  "created_at": "2026-10-22T09:18:04.512Z",
  "saved": true,
  "settings": { "match_threshold": 0.95, "review_threshold": 0.5 },
  "records": [ { "key": "A", "ref": "CRM-20417" }, { "key": "B", "ref": "VISA-88812" } ],
  "groups": [ ["A", "B"] ],
  "pairs": [
    {
      "a": "A", "b": "B", "a_ref": "CRM-20417", "b_ref": "VISA-88812",
      "match_probability": 0.9999999213875321,
      "match_weight": 23.600666505902517,
      "verdict": "Match",
      "found_by": ["document number"],
      "fields": [
        { "key": "prior", "name": "Starting odds", "values": null,
          "level": "1 in 8,012 random pairs is a match", "detail": "learned prior",
          "weight": -12.967773478705709, "percent_of_max": null },
        { "key": "given_name", "name": "Given name", "values": ["SARA", "SARAH"],
          "level": "Jaro-Winkler ≥ 0.90", "detail": "Jaro-Winkler 0.960 · SARA / SARAH",
          "weight": 4.551511998811198, "percent_of_max": 37.713780830086634 },
        { "key": "surname", "name": "Surname", "values": ["AL HADDAD", "HADDAD"],
          "level": "Jaro ≥ 0.70", "detail": "Jaro 0.778 · AL HADDAD / HADDAD",
          "weight": 2.078808625909562, "percent_of_max": 17.188698244608005 },
        { "key": "dob", "name": "Date of birth", "values": ["1990-04-12", "1990-04-12"],
          "level": "Exact match", "detail": "1990-04-12",
          "weight": 11.860377824088783, "percent_of_max": 100.0 },
        { "key": "gender", "name": "Gender", "values": ["F", "F"],
          "level": "Same", "detail": "F",
          "weight": 0.37629967574802825, "percent_of_max": 100.0 },
        { "key": "nationality", "name": "Nationality", "values": ["JOR", "JOR"],
          "level": "Same", "detail": "JOR",
          "weight": 5.791320866869512, "percent_of_max": 97.64417992424072 },
        { "key": "document", "name": "Document",
          "values": [ { "type": "P", "number": "R4419027", "country": "JOR", "expiry": "2031-08-30" },
                      { "type": "P", "number": "R4419027", "country": "JOR", "expiry": "2031-08-30" } ],
          "level": "Same document (number, country, expiry)", "detail": "R4419027 / R4419027 · JOR",
          "weight": 11.910120993181142, "percent_of_max": 96.36577765349236 }
      ]
    }
  ],
  "processing_ms": 6.49
}
```

| Field | Meaning |
|---|---|
| `id`, `created_at` | The saved run; both `null` when the run was not saved |
| `saved` | Whether the run was saved to the match history |
| `settings` | The thresholds this call used |
| `records[]` | The letter given to each record and your `ref` (`null` if none sent) |
| `groups` | Records linked into the same person, by letter ([5.3](#53-groups)) |
| `pairs[]` | Every pair, strongest first ([5.1](#51-pairs)) |
| `processing_ms` | Time the engine took, in milliseconds |

**Errors:** `400`, `401`, `422`. See [section 6](#6-errors).

### 3.4 `GET /api/v1/matches`

Saved runs from the console and the API, newest first. Filters combine.

| Query parameter | Type | Meaning |
|---|---|---|
| `name` | string | Part of a given name or surname. Ignores accents, case and word order. |
| `document` | string | Part of a document number. Ignores spaces and punctuation. |
| `nationality` | string | ISO alpha-3 code, e.g. `JOR` |
| `verdict` | string | Verdict of the strongest pair: `Match`, `Review` or `No match` |
| `source` | string | `console` or `api` |
| `since` | timestamp | Saved at or after, ISO 8601 UTC |
| `until` | timestamp | Saved before, ISO 8601 UTC |
| `page` | integer | From 1. Default 1. |
| `page_size` | integer | 1 to 100. Default 20. |

```json
{
  "total": 1, "page": 1, "page_size": 20,
  "items": [
    { "id": 42, "created_at": "2026-10-22T09:18:04.512Z", "records": 2, "people": 1,
      "verdict": "Match", "match_probability": 0.9999999213875321, "processing_ms": 6.49,
      "summary": [ { "key": "A", "name": "SARA AL HADDAD", "nationality": "JOR" },
                   { "key": "B", "name": "SARAH HADDAD", "nationality": "JOR" } ],
      "source": "api", "key_name": "Border control gateway" }
  ]
}
```

`people` is the number of groups. `verdict` and `match_probability` are those of
the strongest pair. `processing_ms` is the engine time and `request_ms` the whole
request (reading, scoring and saving), recorded when the request finished; it is
`null` for runs saved before version 1.3.

### 3.5 `GET /api/v1/matches/{match_id}`

One saved run: the records as they were sent and the full result.

```json
{
  "id": 42,
  "created_at": "2026-10-22T09:18:04.512Z",
  "records": [ { "key": "A", "ref": "CRM-20417", "given_name": "Sara", "…": "…" } ],
  "result": { "records": 2, "pairs": [ "…" ], "groups": [ ["A", "B"] ], "processing_ms": 6.49 },
  "source": "api",
  "key_name": "Border control gateway"
}
```

`result.pairs` have the same shape as in the match response, without `a_ref`
and `b_ref`; take the refs from `records`. **Errors:** `401`, `404`.

### 3.6 `GET /api/v1/settings`

```json
{ "match_threshold": 0.95, "review_threshold": 0.5, "save_api_runs": true, "updated_at": null }
```

| Field | Meaning |
|---|---|
| `match_threshold` | Pairs at or above it are a `Match` and are linked into one person. Default 0.95. |
| `review_threshold` | Pairs at or above it, but below the match threshold, are `Review`. Default 0.5. |
| `save_api_runs` | Whether API runs are saved when a call does not say. Default true. |
| `updated_at` | Last change, or `null` while the defaults apply |

### 3.7 `PATCH /api/v1/settings` (admin key)

Changes the server-wide settings for the console and every API caller. Send
only the settings to change; the response is the full settings after the change.

```json
{ "match_threshold": 0.97 }
```

**Errors:** `400` (review threshold would not be below match threshold), `401`,
`403` (the key has the `match` or `registry` scope), `422` (no setting sent, or a
value out of range).

### 3.8 `POST /api/v1/search`

Finds the people in the population most likely to be this person. How it
works and how to read the answer: [5.4](#54-search-results).

**Request**

```json
{
  "person": { "given_name": "Tom", "surname": "Chudleigh", "dob": "1630-08-01",
              "nationality": "Egypt", "doc_type": "P", "doc_number": "K08059204", "doc_country": "EGY" },
  "population_types": ["citizens", "residents"],
  "settings": { "top_k": 5 }
}
```

| Field | Type | Required | Meaning |
|---|---|---|---|
| `person` | object | yes | The person to find, with the fields of [section 4](#4-the-person-record) (`ref` is not used). Needs a given name or a surname. |
| `population_types` | array of strings | no | Look only at people of these types (codes, or names in any case); someone of any one of them counts. Empty or left out: every type, including people with no type yet. |
| `settings.top_k` | integer | no | Most results to return, 1 to 50. Default 10. |
| `settings.min_probability` | number | no | Leave out results below this probability, 0 to 1. Default 0. |
| `settings.match_threshold` | number | no | Overrides the server setting for this call only. |
| `settings.review_threshold` | number | no | Overrides the server setting for this call only. Must be below the match threshold. |

**Response** `200`

```json
{
  "id": 214,
  "created_at": "2026-10-22T11:02:41.318Z",
  "searched": { "given_name": "TOM", "surname": "CHUDLEIGH", "dob": "1630-08-01", "gender": null,
                "nationality": "EGY", "doc_type": "P", "doc_number": "K08059204", "doc_country": "EGY", "doc_expiry": null },
  "settings": { "match_threshold": 0.95, "review_threshold": 0.5, "top_k": 5, "min_probability": 0.0 },
  "population": 50578,
  "population_types": ["citizens", "residents"],
  "candidates": { "found": 16, "scored": 16, "limited": false },
  "results": [
    {
      "rank": 1,
      "person": { "id": 7, "ref": "Q2296770-7", "population_types": ["citizens"], "entered": { "given_name": "TOM", "…": "…" },
                  "cleaned": { "given_name": "TOM", "…": "…" }, "batch_id": 1, "created_at": "2026-10-22T07:12:33.284Z" },
      "match_probability": 0.9999999776802952,
      "match_weight": 25.42,
      "verdict": "Match",
      "found_by": ["document number", "given name + surname", "dob + surname", "dob + given name"],
      "shared_keys": 19,
      "fields": [ { "key": "prior", "…": "…" }, { "key": "given_name", "…": "…" } ]
    }
  ],
  "processing_ms": 35.7
}
```

| Field | Meaning |
|---|---|
| `id`, `created_at` | The search's entry in the search log ([3.10](#310-get-apiv1searches)) |
| `searched` | The person as the engine read them, after cleaning |
| `settings` | What this search used |
| `population` | People in the population at the time of the search (all types) |
| `population_types` | The type codes the search looked in; empty for every type |
| `candidates.found` | People who share at least one lookup key with the person (only in those types, when given) |
| `candidates.scored` | How many of them the model scored: at most 500, the ones sharing the rarest keys |
| `candidates.limited` | `true` when `found` was more than 500, so some were not scored |
| `results[]` | Strongest first, at most `top_k` |
| `results[].person` | The person in the population: `id`, `ref`, `population_types` (codes), `entered` (as stored), `cleaned` (as the engine reads them), `batch_id`, `created_at` |
| `results[].match_probability`, `match_weight`, `verdict`, `found_by`, `fields` | As for a pair in a match ([5.1](#51-pairs), [5.2](#52-evidence-per-field)); in `fields`, `values[0]` is the person searched and `values[1]` the person found |
| `results[].shared_keys` | How many lookup keys the two share |
| `processing_ms` | Time the search took, in milliseconds |

Narrowing to types never changes a score: each person found gets the same
probability, weight and rank order as in a search of every type; people of
other types are only left out (and the 500 scored are the 500 sharing the
rarest keys within those types).

Each search is logged with its counts, timings and the types searched, but the
person searched is not kept. **Errors:** `400` (no name, a population type that
does not exist, or threshold conflict), `401`, `422`.

### 3.9 The population: `/api/v1/registry/…`

The population is the set of people searches are compared against. Each person
has an `id` given by the service and, optionally, your own `ref` (up to 64
characters, unique in the population). People are stored as sent (`entered`)
and as the engine reads them (`cleaned`); a value that cannot be read is kept,
counts as missing, and is listed in the person's `issues`. Changes are
searchable at once.

Each person belongs to **one or more population types**: send
`population_types`, a list of type codes (or names) from
[3.12](#312-get-apiv1population-types), with every add, replace and import. A
person sent with no type, or with a type that does not exist, is refused
(`400`, or rejected in an import). People stored before types existed have none
(`[]`) until a type is given to them on the server's Settings page; a search of
every type still finds them, a search narrowed to types does not.

**A person, as returned by every call below**

```json
{
  "id": 50583, "ref": "CRM-20417", "population_types": ["citizens", "confirmed_identities"],
  "entered": { "given_name": "Sara", "surname": "Al-Haddad", "dob": "1990-04-12", "gender": null,
               "nationality": "Jordan", "doc_type": "P", "doc_number": "R 441 9027", "doc_country": "JOR", "doc_expiry": null },
  "cleaned": { "given_name": "SARA", "surname": "AL HADDAD", "dob": "1990-04-12", "gender": null,
               "nationality": "JOR", "doc_type": "P", "doc_number": "R4419027", "doc_country": "JOR", "doc_expiry": null },
  "batch_id": null, "batch_file": null,
  "created_at": "2026-10-22T09:30:12.004Z", "updated_at": "2026-10-22T09:30:12.004Z",
  "issues": []
}
```

`batch_id` is the import that added the person (`null` when added one at a
time). `batch_file` and `issues` come with single-person reads; lists leave
them out.

| Call | Key | Body | Answer |
|---|---|---|---|
| `GET /api/v1/registry` | any | | `{people, imports, last_import_at}`; `imports` counts imports not undone and not cleared |
| `GET /api/v1/registry/people` | any | | `{total, page, page_size, items[]}` (see filters below) |
| `GET /api/v1/registry/people/{person_id}` | any | | the person, or `404` |
| `GET /api/v1/registry/people/ref/{ref}` | any | | the person, or `404` |
| `POST /api/v1/registry/people` | registry | a person (`ref` + the fields of section 4 + `population_types`) | `201` and the person; `400` with no type or an unknown one; `409` if the ref is taken |
| `PUT /api/v1/registry/people/ref/{ref}` | registry | the whole person, with `population_types` | `{created, person}`: adds the person, or replaces every field (types included) of the person with this ref |
| `PUT /api/v1/registry/people/{person_id}` | registry | the whole person, `ref` and `population_types` included | the person; `404`, or `409` if the ref belongs to someone else |
| `DELETE /api/v1/registry/people/{person_id}` | registry | | `{deleted: id}`, or `404` |
| `POST /api/v1/registry/imports` | registry | `{people: [...], on_existing}` | see below |
| `GET /api/v1/registry/imports` | any | | every import and clear, newest first (see below) |
| `POST /api/v1/registry/imports/{import_id}/undo` | registry | | `{id, removed, restored}`; `409` if already undone, or cleared since |
| `POST /api/v1/registry/clear` | admin | `{confirm}` | `{id, created_at, removed, backup}`; see below |

In the population, a document number without a `doc_type` is taken as a
passport; an empty `doc_type` with no number stays empty.

**Filters for `GET /api/v1/registry/people`** (query parameters, combined):
`q` (name, document number or ref), `dob` (`YYYY-MM-DD` or a year),
`nationality`, `doc_country` (ISO alpha-3), `gender` (`M`, `F`, `X`),
`document` (part of a number), `doc_type` (`P`, `V`, `I`), `ref` (part of a
ref), `batch_id`, `population_type` (a type code, or `-` for people with no type
yet), `since` and `until` (date added, ISO 8601 UTC), `sort`
(`name`, `dob`, `added`), `direction` (`asc`, `desc`), `page`, `page_size` (1
to 100, default 25). This is an exact filter for someone you know; to find
people who look like someone, use `POST /search`.

**Keeping the population in step with your system.** Use
`PUT /registry/people/ref/{ref}` for each change, with your own id as the ref,
and `DELETE` for removals. For a first load or a large change, use
`POST /registry/imports`:

```json
{
  "people": [
    { "ref": "CRM-20417", "given_name": "Sara", "surname": "Al-Haddad", "dob": "1990-04-12", "nationality": "JOR",
      "population_types": ["citizens"] },
    { "ref": "CRM-20418", "given_name": "Omar", "surname": "Khaled", "dob": "1985-03-07", "nationality": "EGY",
      "population_types": ["residents", "visa_holders"] }
  ],
  "on_existing": "update"
}
```

- Up to 5,000 people per call. Each call is one import, saved in one
  transaction, which can be undone.
- `on_existing`: `update` (default) replaces people whose ref is already in the
  population, their types included; `skip` leaves them as they are.
- A person with an error (no name, no population type or an unknown one, or a
  ref used earlier in the same call) is not saved. Everyone else is. A value of the wrong type, or a ref longer than
  64 characters, fails the whole call with `422`.

```json
{
  "import": { "id": 3, "file_name": "API · Border control gateway", "created_at": "2026-10-22T09:41:07.120Z",
              "added": 1, "updated": 1, "skipped": 0, "rejected": 0 },
  "rejected": [],
  "warnings": []
}
```

`rejected[]` and `warnings[]` list `{index, ref, issues}`, where `index` is the
position in `people` (from 0); `warnings` are people saved with a value the
engine cannot read.

**The imports log.** `GET /registry/imports` lists every import and every clear,
newest first. Each entry has `id`, `kind` (`import` or `clear`), `file_name`,
`created_at`, `rows_in_file`, `added`, `updated`, `skipped`, `rejected`,
`processing_ms`, `people_now` (people it added who are still there),
`undone_at`, and `cleared_at` (when a later clear removed its people, or
`null`). A `clear` entry also has `removed` (how many people it removed) and
`backup` (where the server saved the population as it was); the import fields
are `0`.

**Clearing the population** (admin key). `POST /registry/clear` removes every
person, with their lookup keys, in one transaction:

```json
{ "confirm": 54161 }
```

- `confirm` must be the number of people in the population now (from
  `GET /registry`). If it differs, nothing is removed and the answer is `409`,
  so a clear sent on an out-of-date count never runs. An empty population also
  answers `409`.
- Before anything is removed, the server saves a copy of the whole population,
  and `backup` says where: a database file under `data/backups/` when the
  population is kept in DuckDB, or a schema named `pm_backup_<time>` in the
  same database when it is kept in PostgreSQL. An administrator restores it as
  the server's README describes. A clear cannot be undone through the API.
- Imports made before the clear can no longer be undone. Match history, the
  search log, settings and API keys are kept. Ids are not reused: people added
  afterwards get new ids.

```json
{ "id": 10, "created_at": "2026-11-12T06:06:59.256Z", "removed": 54161,
  "backup": "data/backups/registry-before-clear-20261112-100659/registry.duckdb" }
```

With PostgreSQL, `backup` is e.g. `"PostgreSQL schema pm_backup_20261112_100659"`.

### 3.10 `GET /api/v1/searches`

The search log, newest first: every search from the search page and the API.
The person searched is not kept; only the strongest person found
(`top_person_id`, an id in the population).

Query parameters: `source` (`console`, `api`), `verdict` (`Match`, `Review`,
`No match`, or `none` for searches that found no one), `since`, `until` (ISO
8601 UTC), `page`, `page_size` (1 to 100, default 20).

```json
{
  "total": 1, "page": 1, "page_size": 20,
  "items": [
    { "id": 214, "created_at": "2026-10-22T11:02:41.318Z", "source": "api", "key_name": "Border control gateway",
      "processing_ms": 35.7, "request_ms": 41.2, "population": 50578,
      "candidates_found": 16, "candidates_scored": 16, "results": 5,
      "top_verdict": "Match", "top_probability": 0.9999999776802952, "top_person_id": 7,
      "top_k": 5, "min_probability": 0.0, "excluded_id": null, "population_types": "citizens,residents" }
  ]
}
```

`processing_ms` is the engine time; `request_ms` is the whole request, recorded
when it finished. `excluded_id` is set for searches the console started from a
person in the population ("find similar people"). `population_types` is the
type codes the search looked in, comma separated, or `null` for every type.

### 3.11 `GET /api/v1/performance`

How many matches, searches and imports ran over the last `days` (1 to 365,
default 7), and how long they took.

```json
{
  "since": "2026-10-15T11:05:00.000Z", "until": "2026-10-22T11:05:00.000Z", "days": 7,
  "summary": {
    "match":  { "count": 120, "by_source": { "console": 80, "api": 40 },
                "engine_ms": { "median": 9.1, "p95": 15.4, "max": 31.0 },
                "request_ms": { "median": 21.7, "p95": 36.2, "max": 64.9 },
                "size": { "median": 2, "p95": 4, "max": 6 } },
    "search": { "count": 310, "by_source": { "console": 12, "api": 298 },
                "engine_ms": { "median": 41.3, "p95": 96.0, "max": 170.2 },
                "request_ms": { "median": 47.9, "p95": 104.8, "max": 181.6 },
                "size": { "median": 87, "p95": 354, "max": 500 } },
    "import": { "count": 2, "by_source": { "api": 2 }, "rows": 1500,
                "processing_ms": { "median": 412.0, "p95": 530.4, "max": 530.4 } }
  },
  "daily": [
    { "day": "2026-10-22", "kind": "search", "count": 52,
      "engine_ms": { "median": 40.2, "p95": 92.1, "max": 120.4 },
      "request_ms": { "median": 46.8, "p95": 101.0, "max": 133.7 } }
  ]
}
```

- Times are in milliseconds: `median`, `p95` (95th percentile) and `max`, or
  `null` when nothing ran.
- `size` is records per match, or people weighed (scored) per search.
- Matches count only saved runs: an API match with `settings.save: false`
  leaves no record.
- `daily` lists UTC days, newest first, one row per day and kind.
- An import's `processing_ms` covers reading, checking and saving its rows.

### 3.12 `GET /api/v1/population-types`

The population types a person can belong to, oldest first. They are managed by
the service's administrators (on its Settings page); read this list to know the
codes to send.

```json
[
  { "code": "citizens", "name": "Citizens", "description": "", "people": 41250 },
  { "code": "residents", "name": "Residents", "description": "", "people": 9020 },
  { "code": "visa_holders", "name": "Visa Holders", "description": "", "people": 3110 },
  { "code": "confirmed_identities", "name": "Confirmed Identities", "description": "", "people": 781 }
]
```

| Field | Meaning |
|---|---|
| `code` | What you send in `population_types`. Lower case letters, digits and `_`; it never changes. |
| `name` | The name to show; it can change. Names are accepted in place of codes, in any case. |
| `description` | Free text, may be empty |
| `people` | How many people belong to the type now; a person of two types counts in both |

Types can be added, renamed and deleted on the server. A type cannot be deleted
while people belong to it. **Errors:** `401`.

## 4. The person record

| Field | Type | Meaning | Cleaning applied before comparing |
|---|---|---|---|
| `ref` | string, ≤ 64 | Your own reference, returned with each pair. Not compared. | none |
| `given_name` | string | Given names | Accents removed, upper case, punctuation becomes a space, titles (MR, MRS, MS, MISS, DR, PROF, SIR, SHEIKH, ENG) removed |
| `surname` | string | Family name | as `given_name` |
| `dob` | date | Date of birth, `YYYY-MM-DD` | First 10 characters read as a date |
| `gender` | string | `M`, `F` or `X` | First letter, upper case |
| `nationality` | string | Country name, ISO alpha-2 or alpha-3 code, e.g. `JOR`, `JO` or `Jordan` | Mapped to ISO alpha-3 |
| `doc_type` | string | `P` passport, `V` visa, `I` national ID. Default `P`. | First letter, upper case |
| `doc_number` | string | Document number | Upper case, everything except letters and digits removed |
| `doc_country` | string | Issuing country, as `nationality` | Mapped to ISO alpha-3 |
| `doc_expiry` | date | Expiry date, `YYYY-MM-DD` | First 10 characters read as a date |

In the population, a person also carries `population_types` (one or more type
codes; see [3.9](#39-the-population-apiv1registry) and
[3.12](#312-get-apiv1population-types)). A match record has no types.

Rules:

- Each record needs a `given_name` or a `surname`, otherwise the call returns
  `400`.
- **A value that cannot be read is treated as missing, not rejected.** An
  invalid date, an unknown country or a gender other than M, F or X counts as
  "missing", which gives no evidence either way. Validate on your side if you
  need to catch these.
- Missing values never count against a match; they add no evidence.
- Document numbers are only compared between documents of the same type.
- The values the engine compared, after cleaning, are returned in each field's
  `values`, so you can see how your input was read.

## 5. Reading match and search results

### 5.1 Pairs

Every pair of records is scored; with *n* records there are *n(n−1)/2* pairs,
sorted from strongest to weakest.

| Field | Meaning |
|---|---|
| `a`, `b` | Letters of the two records |
| `a_ref`, `b_ref` | Your refs for them |
| `match_probability` | Probability (0 to 1) that the two records are the same person |
| `match_weight` | The same evidence on a log₂ scale: the sum of every field's `weight`. Above 0 favours a match. |
| `verdict` | `Match` if `match_probability` ≥ match threshold; `Review` if ≥ review threshold; otherwise `No match` |
| `found_by` | Which candidate rules the pair satisfies: `document number`, `given name + surname`, `dob + surname`, `dob + given name`. Informational only; every pair is scored. |
| `fields[]` | The evidence, field by field ([5.2](#52-evidence-per-field)) |

Probability and weight are related by
`match_probability = 2^match_weight / (1 + 2^match_weight)`.

**Recommended handling:** act automatically on `Match`, queue `Review` for a
person to decide, and treat `No match` as different people.

### 5.2 Evidence per field

`fields[0]` is always the starting odds (`key: "prior"`): how likely two random
records are to match before any field is compared. It is followed by one entry
per compared field.

| Field | Meaning |
|---|---|
| `key` | `prior`, `given_name`, `surname`, `dob`, `gender`, `nationality` or `document` |
| `name` | Display name of the field |
| `values` | The two cleaned values compared (for `document`: `type`, `number`, `country`, `expiry` on each side); `null` for the prior |
| `level` | Which comparison level the pair reached (table below) |
| `detail` | Short human-readable explanation, e.g. a similarity score |
| `weight` | Evidence in log₂ odds: positive for a match, negative against, 0 for none |
| `percent_of_max` | `weight` as a percentage of the strongest evidence this field can give in the same direction (negative against). `null` for the prior. |

Comparison levels, from strongest to weakest:

| Field | Levels |
|---|---|
| `given_name` | Exact match · Swapped with surname · Jaro-Winkler ≥ 0.90 · Jaro-Winkler ≥ 0.70 · Different · Missing on one side |
| `surname` | Exact match · Swapped with given name · Jaro ≥ 0.90 · Jaro ≥ 0.70 · Different · Missing on one side |
| `dob` | Same year (01-01 placeholder) · Exact match · One-digit typo · Day and month swapped · Within 1 month · Within 1 year · Within 10 years · Different · Missing on one side |
| `gender` | Same · Different · Missing on one side |
| `nationality` | Same (weighted by how common the nationality is: rarer counts more) · Different · Missing on one side |
| `document` | Same document (number, country, expiry) · Same number and country, expiry differs · Number one edit apart, same country · Different number, same country · Different issuing country · Not comparable (missing, or different document types) |

Level labels are for display and logging. Base decisions on `verdict` or
`match_probability`, not on label text.

### 5.3 Groups

Pairs that reach the match threshold are linked, and links chain: if A matches
B and B matches C, then A, B and C are one group even if A and C alone fall
short. `groups` lists every record exactly once; a record with no match is a
group of one.

### 5.4 Search results

A search does not compare the person with everyone in the population. It works
in four steps:

1. **Clean** the person as in [section 4](#4-the-person-record).
2. **Find candidates:** people who share at least one *lookup key* with them.
   The keys are built from: the document number, and the number with any one
   character missing (one typo apart); the given name and surname in either
   order; each name with the date of birth, and its first letter with the date
   of birth; the sound of each name (Soundex) with the birth year; the sounds of
   the given name and surname together; the sound of the surname alone; and,
   for surnames that differ only at the end (CHUDLEY, CHUDLEIGH), the start of
   the surname's sound or its first four letters with the given name.
   When the search names `population_types`, only people of those types are
   candidates. The rarity of each key is still counted over the whole
   population, so a person's score and order do not depend on the types asked for.
3. **Score** each candidate with the model, exactly as in a match: the same
   person pair gets the same probability, weight and evidence in a search and in
   a match. When more than 500 people share a key, the 500 sharing the rarest
   keys are scored.
4. **Rank** by match weight, strongest first; equal weights in id order.

So a true match can be missed when it shares no lookup key with the person: for
example a different given name, a different surname sound and no date of birth
or document in common. On the demo population (50,578 records), 86.4% of true
matches reach the model, the top result is a true match for 95.7% of searches,
and a search takes 44 ms (median).

**Match percentage.** Show `match_probability × 100` as the percentage. It is the
probability that the two are the same person, so a strong partial match can read
low (for example 30%). Use `verdict` to decide, and `rank` to order.

## 6. Errors

```json
{ "detail": "Add a given name or surname to record CRM-20417." }
```

| Status | When |
|---|---|
| `400` | A record or person has no name (the message names it by `ref`, or by letter), or `review_threshold` is not below `match_threshold` |
| `401` | The `X-API-Key` header is missing, or the key is not valid or was revoked |
| `403` | The key's scope does not allow the call: changing the population needs `registry` or `admin`; changing settings or clearing the population needs `admin` |
| `404` | No saved match, person or import with that id or ref |
| `409` | The ref is already used by another person; the import was already undone or was removed by a clear; or a clear's `confirm` is not the number of people now, or the population is already empty |
| `422` | The body or a parameter has the wrong type or is out of range, e.g. fewer than 2 or more than 6 records, or a threshold outside 0 to 1 |
| `5xx` | Server problem. Safe to retry `GET` calls; retry `POST /match` with `settings.save: false` if a duplicate saved run matters. |

For `422`, `detail` is a list with one entry per problem:

```json
{ "detail": [ { "type": "too_short", "loc": ["body", "records"],
                "msg": "List should have at least 2 items after validation, not 1", "input": ["…"] } ] }
```

## 7. Code samples

Set `PM_BASE_URL` to `{BASE_URL}` and `PM_API_KEY` to your key.

**curl**

```bash
curl -X POST "$PM_BASE_URL/api/v1/match" \
  -H "X-API-Key: $PM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"records": [
        {"ref": "CRM-20417", "given_name": "Sara", "surname": "Al-Haddad", "dob": "1990-04-12"},
        {"ref": "VISA-88812", "given_name": "Sarah", "surname": "Haddad", "dob": "1990-04-12"}]}'
```

**Python**

```python
import os
import requests

BASE_URL = os.environ["PM_BASE_URL"]
API_KEY = os.environ["PM_API_KEY"]

response = requests.post(
    f"{BASE_URL}/api/v1/match",
    headers={"X-API-Key": API_KEY},
    json={
        "records": [
            {"ref": "CRM-20417", "given_name": "Sara", "surname": "Al-Haddad", "dob": "1990-04-12"},
            {"ref": "VISA-88812", "given_name": "Sarah", "surname": "Haddad", "dob": "1990-04-12"},
        ]
    },
    timeout=10,
)
response.raise_for_status()
for pair in response.json()["pairs"]:
    print(pair["a_ref"], pair["b_ref"], pair["verdict"], round(pair["match_probability"], 4))
```

**Python: search the population**

```python
response = requests.post(
    f"{BASE_URL}/api/v1/search",
    headers={"X-API-Key": API_KEY},
    json={"person": {"given_name": "Sarah", "surname": "Haddad", "dob": "1990-04-12", "nationality": "JOR"},
          "population_types": ["citizens", "residents"],  # leave out to search every type
          "settings": {"top_k": 5}},
    timeout=10,
)
response.raise_for_status()
for r in response.json()["results"]:
    print(r["rank"], r["person"]["ref"], r["verdict"], f'{r["match_probability"]:.1%}')
```

**Python: keep one person in step (needs a registry key)**

```python
requests.put(
    f"{BASE_URL}/api/v1/registry/people/ref/CRM-20417",
    headers={"X-API-Key": REGISTRY_KEY},
    json={"given_name": "Sara", "surname": "Al-Haddad", "dob": "1990-04-12", "nationality": "JOR",
          "population_types": ["citizens"]},
    timeout=10,
).raise_for_status()
```

**JavaScript**

```js
const response = await fetch(`${process.env.PM_BASE_URL}/api/v1/match`, {
  method: 'POST',
  headers: { 'X-API-Key': process.env.PM_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    records: [
      { ref: 'CRM-20417', given_name: 'Sara', surname: 'Al-Haddad', dob: '1990-04-12' },
      { ref: 'VISA-88812', given_name: 'Sarah', surname: 'Haddad', dob: '1990-04-12' },
    ],
  }),
});
if (!response.ok) throw new Error((await response.json()).detail);
const { pairs } = await response.json();
```

## 8. Operational notes

- **Speed.** A match call usually takes 4 to 10 ms of engine time
  (`processing_ms`), plus network time. The server runs up to 4 matches at once;
  further calls wait their turn. Use a client timeout of a few seconds.
- **Search speed.** A search usually takes 30 to 130 ms of engine time on a
  population of 50,000 people; more people sharing the person's keys means more
  candidates to score.
- **Batches.** One match call compares up to 6 records. To check one person
  against everyone the matcher holds, use `POST /search` instead.
- **Saving.** Saved runs keep the records as sent, including personal data, in
  the server's match history. Send `settings.save: false` when you do not need
  the run kept. Searches are logged with their counts and timings
  ([3.10](#310-get-apiv1searches)), but the person searched is not kept.
- **The population holds personal data.** Give the `registry` scope only to the
  systems that own the data, and a `match` key to systems that only search.
- **Clearing.** `POST /registry/clear` empties the population for every caller
  at once; searches return no results until people are added again. Each clear
  leaves a full copy of the population on the server (a file in
  `data/backups/`, or a `pm_backup_<time>` schema in PostgreSQL), so remove old
  copies when they are no longer needed.
- **Where the population is kept.** The server keeps it in DuckDB or in
  PostgreSQL, as its administrator chooses. Requests, answers and results are
  the same either way; only a clear's `backup` differs, as above.
- **Settings are shared.** `PATCH /settings` changes the thresholds for the
  console and every caller. To use other thresholds for your system only, send
  them in each match call's `settings`.
- **Security.** Use HTTPS outside a local machine. Keep keys out of URLs, logs
  and browser code. Rotate a key by creating a new one, switching to it, then
  revoking the old one.
- **Machine-readable schema.** OpenAPI is at `{BASE_URL}/openapi.json`; the
  interactive reference is at `{BASE_URL}/api-reference`.

## 9. Changelog

| Version | Date | Changes |
|---|---|---|
| 1.0 | 2026-10-22 | First edition: API v1 with health, reference, match, saved matches and settings. |
| 1.1 | 2026-10-22 | Person search (`POST /search`, [5.4](#54-search-results)); the population under `/registry` (people, imports, undo); the `registry` key scope; `409` errors. |
| 1.2 | 2026-10-22 | Search also finds surnames that differ only at the end (two more lookup keys); measured figures in [5.4](#54-search-results) updated. No request or response changes. |
| 1.3 | 2026-10-22 | Performance records: `GET /searches` (the search log) and `GET /performance` (counts and timings); search responses gain `id` and `created_at`; saved matches gain `request_ms`; imports record `processing_ms`. |
| 1.4 | 2026-11-12 | Clearing the population: `POST /registry/clear` (admin key, confirmed by the number of people). The imports log gains `kind`, `removed`, `backup` and `cleared_at`; imports made before a clear cannot be undone (`409`); `GET /registry` counts only imports not cleared; `GET /performance` counts imports only, not clears. |
| 1.5 | 2026-11-12 | The population can be kept in PostgreSQL as well as DuckDB, chosen on the server. No request or response changes and identical results; with PostgreSQL, a clear's `backup` names a backup schema instead of a file. |
| 1.6 | 2026-11-12 | The base URL answers: `GET /api/v1` (no key) lists every endpoint with the key it needs and where the documentation is, and `GET /api` lists the API versions. Before, both answered `404`. |
| 1.7 | 2026-11-12 | The service has a release version: `GET /api/v1/health` gains `version` and `commit`, and `GET /api/v1` and `GET /api` gain `version`. Added fields only. |
| 2.0 | 2026-11-12 | **Population types.** Every person belongs to one or more types (Citizens, Residents, Visa Holders, Confirmed Identities, managed on the server). New `GET /population-types`. **Breaking:** adding, replacing and importing people now needs `population_types` (one or more codes); a person without one is refused (`400`) or rejected in an import. `POST /search` takes `population_types` to look only in those types (left out: every type, as before; scores unchanged). People, search results and `GET /reference` carry `population_types`; `GET /registry/people` filters by `population_type`; the search log records the types searched. Service release 2.0.0. |
