Quickstart

Prefer a UI? Use the runnable demo: clone Theary-AI/quick-start, set PUBLIC_RECORDS_API_KEY, and open /public-records. See that repo’s PUBLIC_RECORDS.md for the first successful evaluate path. More payloads: Sample Pack.

Prerequisites

Staging API key from Account Setup
cURL or your preferred HTTP client

Public Records is synchronous — the decision returns in the same /evaluate response. No webhooks required.

One search per call. order_id, order_number, and search_id identify the order line and this evaluate run. There is no batch API. See Order → Search → Evaluate contract.

Step 1: Configure Environment

Use staging for your first evaluate:

export PR_API_BASE=https://cra.pr.stg.snh-ai.com
export PR_API_KEY="eval-api-key-<your-unique-key>"

$env:PR_API_BASE = "https://cra.pr.stg.snh-ai.com"
$env:PR_API_KEY = "eval-api-key-<your-unique-key>"

Step 2: Verify Connectivity

Confirm the API is up before proceeding:

curl "$PR_API_BASE/health"

import requests, os

base = os.environ["PR_API_BASE"]
resp = requests.get(f"{base}/health")
print(resp.json())

const base = process.env.PR_API_BASE;

const resp = await fetch(`${base}/health`);
console.log(await resp.json());

Expected response:

{
  "status": "healthy",
  "service": "eval-framework",
  "services": {
    "xml_transformer": true,
    "compliance_engine": true
  }
}

Step 3: Get Auth Token

Exchange your API key for a JWT token. Lifetime is in expires_in (currently 3600 seconds / 1 hour). See Authentication for the full guide.

curl -X POST "$PR_API_BASE/auth/token" \
  -H "X-API-Key: $PR_API_KEY" \
  -H "Content-Type: application/json"

import requests, os

base = os.environ["PR_API_BASE"]
api_key = os.environ["PR_API_KEY"]

resp = requests.post(
    f"{base}/auth/token",
    headers={"X-API-Key": api_key}
)
token = resp.json()["access_token"]
print(f"Token: {token[:20]}...")

const base = process.env.PR_API_BASE;
const apiKey = process.env.PR_API_KEY;

const resp = await fetch(`${base}/auth/token`, {
  method: "POST",
  headers: { "X-API-Key": apiKey }
});
const { access_token } = await resp.json();
console.log(`Token: ${access_token.slice(0, 20)}...`);

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Save the access_token — you’ll use it in the next step:

export PR_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Step 4: Evaluate a Record

This smoke test uses mapped JSON (record_json) with no cases[], so every offense in the payload is evaluated and the count-reconciliation gate is not applied. For the XML path, see Supported XML Schemas. After the smoke test, see Optional: map charges with cases[] when you need your own court/offense IDs. Save the following as record.json:

record.json

{
  "record": {
    "search_id": "test-123",
    "search_date": "2025-04-30",
    "order_id": "12345",
    "order_number": "12345.1",
    "submission_type": "resubmit",
    "applicant_state": "CA",
    "customer_state": "CA",
    "candidate_info": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-05-15"
    },
    "record_json": {
      "criminal_search_results": [
        {
          "court_search_id": "CS40929433A",
          "search_date": "2025-04-30",
          "criminal_records": [
            {
              "case_number": "MJ-05003-TR-0006023-2020",
              "jurisdiction_state": "PA",
              "file_date": "2020-03-10",
              "subject_name": "JOHN DOE",
              "sub_first_name": "John",
              "sub_middle_name": "",
              "sub_last_name": "Doe",
              "subject_dob": "1990-05-15",
              "subject_ssn": "UNKNOWN",
              "subject_address": "123 Main St, Austin, TX 78701",
              "offenses": [
                {
                  "offense_id": "34789896",
                  "charge": "DRIVING WHILE OPERATOR PRIVILEGES SUSPENDED",
                  "disposition": "GUILTY",
                  "type": "SUMMARY"
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Then submit it:

curl -X POST "$PR_API_BASE/evaluate" \
  -H "Authorization: Bearer $PR_TOKEN" \
  -H "Content-Type: application/json" \
  --data @record.json

import requests, json, os

base = os.environ["PR_API_BASE"]
token = os.environ["PR_TOKEN"]

with open("record.json") as f:
    payload = json.load(f)

resp = requests.post(
    f"{base}/evaluate",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    },
    json=payload
)
result = resp.json()
decision = result["data"]["decision"]
print(f"Search queue: {decision['search_queue']}")
for court in decision["court_decisions"]:
    for case in court["case_decisions"]:
        for offense in case["offenses"]:
            print(offense["offense_id"], offense["charge_decision"], offense["routing"]["queue"])

import { readFileSync } from "fs";

const base = process.env.PR_API_BASE;
const token = process.env.PR_TOKEN;

const payload = JSON.parse(readFileSync("record.json", "utf-8"));

const resp = await fetch(`${base}/evaluate`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
const result = await resp.json();
const decision = result.data.decision;
console.log(`Search queue: ${decision.search_queue}`);

Response:

{
  "success": true,
  "data": {
    "search_id": "test-123",
    "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "success",
    "errors": [],
    "decision": {
      "search_id": "test-123",
      "decision_date": "2026-05-11T14:30:19Z",
      "record_decision": "NOT_REPORTABLE",
      "search_queue": "Automation",
      "order_id": "12345",
      "court_decisions": [
        {
          "court_search_id": "CS40929433A",
          "court_queue": "Automation",
          "case_decisions": [
            {
              "case_number": "MJ-05003-TR-0006023-2020",
              "case_queue": "Automation",
              "jurisdiction_state": "PA",
              "id_match": {
                "is_match": true,
                "match_score": 0.85,
                "name_score": 1,
                "dob_score": 1,
                "ssn_score": 0,
                "address_score": 0
              },
              "offenses": [
                {
                  "offense_id": "34789896",
                  "charge": "DRIVING WHILE OPERATOR PRIVILEGES SUSPENDED",
                  "charge_decision": "NOT_REPORTABLE",
                  "rationale": "The traffic violations are not reportable, unless it's a felony.",
                  "type": "SUMMARY",
                  "disposition": "GUILTY",
                  "needs_human_review": false,
                  "cited_rules": ["GENERAL_TRAFFIC_NON_REPORT", "EXCLUSION_FILTER_CHARGE"],
                  "citations": [],
                  "routing": {
                    "queue": "Automation",
                    "is_automatable": true,
                    "identity_level": "High",
                    "identity_score": 0.85
                  }
                }
              ]
            }
          ]
        }
      ]
    },
    "timing": {
      "xml_transformer_ms": 1200.5,
      "compliance_ms": 330.7,
      "total_ms": 1850.3
    }
  },
  "meta": {
    "api_version": "2.0.0",
    "process_time_ms": 1855,
    "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Optional: map charges with `cases[]`

Omit cases[] for the simplest path. When you need your court_search_id / offense_id values (or is_excluded), send a full mapping — one row per charge, in XML/record_json order. Partial subsets return HTTP 422. Same traffic XML as the sample pack, with mapping:

{
  "record": {
    "search_id": "sample-cases-001",
    "search_date": "2026-04-10",
    "order_id": "90010001",
    "order_number": "90010001.1",
    "applicant_state": "TX",
    "candidate_info": {
      "first_name": "Ebony",
      "last_name": "Ferrell",
      "date_of_birth": "1992-08-12",
      "ssn": "123-45-6789",
      "address": "100 Main St, Austin, TX 78701"
    },
    "cases": [
      {
        "court_search_id": "CS-TRAVIS-001",
        "offense_id": "OFF-90010001-1",
        "is_excluded": false
      }
    ],
    "xml": "<ScreeningResults>...</ScreeningResults>"
  }
}

Full bodies:

One charge: samples/with-cases-mapping.json
Multi-charge (2 courts / 5 offenses): samples/with-cases-multi-charge.json

curl -X POST "$PR_API_BASE/evaluate" \
  -H "Authorization: Bearer $PR_TOKEN" \
  -H "Content-Type: application/json" \
  --data @samples/with-cases-multi-charge.json

Rule	Detail
Full set	One `cases[]` row per charge, in XML / `record_json` order
IDs	Your `court_search_id` / `offense_id` — same court ID may repeat across offenses
Count gate	Partial subsets → HTTP 422

Details: Evaluate — cases[].

Step 5: Understand the Response

Every response is wrapped in a { success, data, meta } envelope. The evaluation result is at data.decision. Start here — per charge:

Concept	Path	Values
Charge decision	`...offenses[].charge_decision`	`REPORTABLE`, `NOT_REPORTABLE`, `MANUAL_REVIEW`
Queue	`...offenses[].routing.queue`	`Automation`, `Auditor`, `Insufficient Data`

Rolled up to the search:

Concept	Path	Description
Record decision	`data.decision.record_decision`	Overall reportability for the search
Search queue	`data.decision.search_queue`	Overall routing queue for the search

Court/case levels expose the same pair (court_decision / court_queue, case_decision / case_queue). See How It Works and Routing. What to do next — pick queue or decision (one is usually enough; both only if routing and report labeling are separate steps):

Queue	Decision (rollup)	Action
`Automation`	`NOT_REPORTABLE`	Handle automatically (typically clear not-reportable charges)
`Auditor`	`REPORTABLE`	Route to a human auditor before including in a report
`Insufficient Data`	`MANUAL_REVIEW`	Investigate missing fields or resubmit with corrections

Full ops guide: Queue & Decision → Next Action. Queue rollup priority: Insufficient Data > Auditor > Automation. One charge lacking data can mark the whole case (and court / search) as Insufficient Data. When the source record has data-quality issues (e.g., missing SSN or disposition), the response also includes a structured validation object alongside decision. When the data is clean, validation is omitted entirely.

Next Steps

Queue & Decision → Next Action

One signal is usually enough; both only for separate jobs

API Reference

Explore all available endpoints and options

Code Examples

Working examples in Python, JavaScript, and cURL

Error Handling

Retry logic, failure handling, and troubleshooting

Environments

Production, staging, and dev environment URLs

Getting Started

Resources

Prerequisites

Step 1: Configure Environment

Step 2: Verify Connectivity

Step 3: Get Auth Token

Step 4: Evaluate a Record

Optional: map charges with `cases[]`

Step 5: Understand the Response

Next Steps

Queue & Decision → Next Action

API Reference

Code Examples

Error Handling

Environments

Need Help?

​Prerequisites

​Step 1: Configure Environment

​Step 2: Verify Connectivity

​Step 3: Get Auth Token

​Step 4: Evaluate a Record

​Optional: map charges with cases[]

​Step 5: Understand the Response

​Next Steps

Queue & Decision → Next Action

API Reference

Code Examples

Error Handling

Environments

​Need Help?

Prerequisites

Step 1: Configure Environment

Step 2: Verify Connectivity

Step 3: Get Auth Token

Step 4: Evaluate a Record

Optional: map charges with `cases[]`

Step 5: Understand the Response

Next Steps

Need Help?