Search API Reference

All endpoints are served on port 8400 of the appliance container. There is no authentication layer built into the appliance itself — it is designed to sit inside your own VPC, reachable only by services you control; put it behind your own network policy, gateway, or auth proxy if it needs to be reachable more broadly.

GET /healthz

Liveness/readiness check. Suitable as a Docker HEALTHCHECK or an orchestrator (Kubernetes, ECS) liveness/readiness probe.

curl -s http://localhost:8400/healthz

{
  "ok": true,
  "dataVersion": "2026-08-02T03:00:00Z",
  "epoch": 4
}

Field	Type	Meaning
`ok`	boolean	`true` once the appliance has a fully-loaded, checksum-verified dataset and is ready to serve `/v1/search` and `/v1/batch`.
`dataVersion`	string	The version identifier of the currently-loaded dataset, from the update manifest (see Updates & synchronization).
`epoch`	number	The schema/resolver epoch the loaded data was built against — see Updates & synchronization.

GET /v1/status

Fuller operational status: what's loaded, per-dataset entity counts, and sync timing.

curl -s http://localhost:8400/v1/status

{
  "dataVersion": "2026-08-02T03:00:00Z",
  "epoch": 4,
  "datasets": [
    { "id": "us_ofac_sdn", "entityCount": 17842 },
    { "id": "un_sc_sanctions", "entityCount": 941 },
    { "id": "eu_fsf", "entityCount": 2603 }
  ],
  "lastSyncAt": "2026-08-02T03:00:00Z",
  "nextSyncAt": "2026-08-02T09:00:00Z",
  "updateUrl": "https://www.proofaml.com/updates/v1"
}

Field	Type	Meaning
`dataVersion`	string	Same as `/healthz`.
`epoch`	number	Same as `/healthz`.
`datasets`	array	One entry per dataset with at least one loaded entity: `id` and `entityCount`. Selection is entity-level — a loaded entity keeps all of its co-listings — so this list can include ids beyond what `DATASETS` requested; see Dataset selection & reference.
`lastSyncAt`	string (ISO 8601)	When the appliance last completed a sync (successful or not).
`nextSyncAt`	string (ISO 8601)	When the appliance will next attempt a sync, per `SYNC_INTERVAL`. Absent/meaningless when `OFFLINE=true`.
`updateUrl`	string	The configured `UPDATE_URL` the appliance syncs from.

datasets only lists datasets your DATASETS configuration actually loaded — a dataset you excluded won't appear here even if it exists upstream.

POST /v1/search

Screen a single subject.

curl -s -X POST http://localhost:8400/v1/search \
  -H 'content-type: application/json' \
  -d '{
    "name": "Viktor Bout",
    "dob": "1967-01-13",
    "country": "RU",
    "identifiers": ["passport:RU1234567"],
    "datasets": ["us_ofac_sdn", "un_sc_sanctions"],
    "limit": 5,
    "threshold": 70
  }'

Request body

Field	Type	Required	Meaning
`name`	string	yes	The subject name to screen.
`dob`	string (ISO 8601 date)	no	Date of birth, used to score/disambiguate candidate matches.
`country`	string	no	ISO country code (or country name), used to score/disambiguate candidate matches.
`identifiers`	string[]	no	Structured identifiers (e.g. passport, national ID, LEI) to match against entity identifiers.
`datasets`	string[]	no	Restrict this search to specific dataset ids (see Dataset selection & reference). Omit to search every dataset the appliance has loaded (its `DATASETS` configuration).
`limit`	number	no	Maximum number of matches to return. Omit to use the appliance's default.
`threshold`	number	no	Minimum match score (0–100) required for a candidate to be returned. Omit to use the appliance's default.

Response

{
  "query": {
    "name": "Viktor Bout",
    "dob": "1967-01-13",
    "country": "RU",
    "identifiers": ["passport:RU1234567"],
    "datasets": ["us_ofac_sdn", "un_sc_sanctions"],
    "limit": 5,
    "threshold": 70
  },
  "dataVersion": "2026-08-02T03:00:00Z",
  "matches": [
    {
      "score": 98,
      "entity": {
        "id": "NK-a1b2c3d4",
        "schema": "Person",
        "name": "Viktor Anatolyevich Bout",
        "aliases": ["Viktor But", "Boris Grigorov"],
        "datasets": ["us_ofac_sdn", "un_sc_sanctions"],
        "properties": {
          "birthDate": ["1967-01-13"],
          "country": ["ru"]
        }
      },
      "matchedOn": ["name", "dob", "country"]
    }
  ]
}

Field	Type	Meaning
`query`	object	Echo of the request, useful for correlating async logging/auditing.
`dataVersion`	string	The dataset version this search was evaluated against — record this alongside any match for audit purposes.
`matches`	array	Zero or more scored candidates, highest `score` first.
`matches[].score`	number	Match confidence, 0–100.
`matches[].entity`	object	The matched entity (same shape as an entity record in a `/sources/` dataset).
`matches[].matchedOn`	string[]	Which submitted fields contributed to the match (`name`, `dob`, `country`, `identifiers`).

An empty matches array is a valid, complete response — it means no candidate cleared threshold, not an error.

Search API Reference

Search API Reference

GET /healthz

GET /v1/status

POST /v1/search

See also

More Screening Appliance docs