Criminal Watchlist Screening API for Interpol and FBI

curl -X POST https://screenveritai.com/api/v1/search \
  -H "X-API-Key: svai_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_name": "Test Person",
    "entity_type": "person",
    "search_type": "sanctions_check"
  }'

# HTTP/1.1 202 Accepted
# {
#   "search_id": "a1c9f4e7-3b62-48d0-9c15-2f7e6a8b0d33",
#   "status": "processing",
#   "message": "Search queued successfully. Poll the GET endpoint for results.",
#   "estimated_time_seconds": 15
# }

# Enumerate the watchlist sources that were actually in place:
curl https://screenveritai.com/api/v1/coverage \
  -H "X-API-Key: svai_your_key_here"

// No watchlist listing found — criminal_watchlists is null, not a block.
{
  "id": "a1c9f4e7-3b62-48d0-9c15-2f7e6a8b0d33",
  "entity_name": "Test Person",
  "entity_type": "person",
  "status": "completed",
  "search_type": "sanctions_check",
  "criminal_watchlists": null,
  "pep": null,
  "ofac_sanctions": "## OFAC Sanctions Findings\n\n**Status:** *No relevant listing found* ...",
  "created_at": "2026-09-04T10:02:18.640000+00:00",
  "completed_at": "2026-09-04T10:02:33.915000+00:00"
}

// Potential match on the public Red Notice extract.
{
  "id": "d5e30b18-7c44-4a91-8b02-91ff5c6d7e20",
  "entity_name": "Second Test Person",
  "entity_type": "person",
  "status": "completed",
  "search_type": "sanctions_check",
  "criminal_watchlists": "## Interpol Red Notices Findings\n\n**Status:** *Potential watchlist match*\n\n**Details:**\n- **Matched entity:** SECOND TEST PERSON\n- **Identification:** 1979-04-11 | Example nationality\n- **Case details:** 2019/12345\n- **Authority:** Interpol\n- **Evidence URL:** https://www.interpol.int/How-we-work/Notices/Red-Notices/View-Red-Notices\n\n**Source:** *Interpol*",
  "pep": null,
  "created_at": "2026-09-04T10:11:02.311000+00:00",
  "completed_at": "2026-09-04T10:11:19.774000+00:00"
}

{
  "status": "ok",
  "checkedAt": "2026-09-04T10:14:51.220000+00:00",
  "domains": {
    "criminal_watchlists": {
      "domain": "criminal_watchlists",
      "expected_tables": null,
      "available_tables": 3,
      "tables": [
        "criminal_gb_nca_most_wanted",
        "criminal_us_fbi_most_wanted",
        "criminal_za_saps_most_wanted"
      ],
      "latest_updated_at": "2026-09-03T02:14:07.118000+00:00"
    }
  }
}

// available_tables and tables reflect what is on disk at request time, so this
// is the assertion to file with an audit: which watchlist sources were in
// place, and when each was last refreshed. Interpol Red Notices are a live
// lookup rather than a stored table, so they do not appear in this list.

import os
import time
import requests

BASE = "https://screenveritai.com/api/v1"
HEADERS = {"X-API-Key": os.environ["SCREENVERITAI_API_KEY"]}

created = requests.post(
    f"{BASE}/search",
    headers=HEADERS,
    json={
        "entity_name": "Test Person",
        "entity_type": "person",
        "search_type": "sanctions_check",
    },
    timeout=30,
)
created.raise_for_status()
search_id = created.json()["search_id"]

while True:
    response = requests.get(f"{BASE}/search/{search_id}", headers=HEADERS, timeout=30)
    response.raise_for_status()
    result = response.json()
    if result["status"] == "completed":
        break
    if result["status"].startswith("error"):
        raise RuntimeError(f"search {search_id} ended in {result['status']}")
    time.sleep(3)

# criminal_watchlists is null when nothing was found in the checked sources.
watchlists = result["criminal_watchlists"]
if not watchlists:
    print(search_id, "no listing found in the checked watchlist sources")
else:
    # One "## <Source> Findings" section per matched source.
    sections = [block.strip() for block in watchlists.split("## ") if block.strip()]
    for section in sections:
        heading = section.splitlines()[0]
        print(search_id, "->", heading)      # e.g. "Interpol Red Notices Findings"
    print("route to manual review; a watchlist entry is not a designation")