How It Works

The Request Flow

When you submit a criminal record for evaluation, the service processes it through three stages and returns a complete compliance decision in a single API response. Stage 1 — Parse and normalize. The raw screening data (XML or mapped JSON) is parsed into a structured format. Charge descriptions, dates, and disposition values are standardized so compliance rules can be applied consistently. Stage 2 — Verify identity. The candidate you’re screening is compared against the person named in the criminal record. The service checks name, date of birth, SSN, and address to determine whether the record actually belongs to your candidate. Stage 3 — Apply compliance rules. Each charge is evaluated against federal rules, state rules (all 50 US states, DC, and territories AS / GU / MP / PR / VI), and local (county) context from the record, plus any client- / tenant-specific rules configured for your organization. The service returns reportable / not reportable / manual review and a routing recommendation (Automation* / Auditor* / Insufficient Data*). *Automation = no human review needed. Auditor = human review recommended (optional). Insufficient Data = human review required. Details: Glossary. All three stages happen behind a single POST /evaluate call. The response contains the complete decision.

Order → Search → Evaluate contract

Background screening follows a hierarchy: Orders contain Searches. Each search gets its own compliance Decision from POST /evaluate.

There is no batch evaluate API. One POST /evaluate = one search. An order with three searches requires three separate calls.

Concept	What it is	Identifier	Example
Order	Background check request for one candidate; may include multiple searches	`order_id`	`"41115779"`
Search	One criminal record lookup within that order (e.g. one county or statewide)	`order_number` + `search_id`	`"41115779.1"` + `"76190bc0-…"`
Decision	Compliance result for that search only	Response `data.decision`	`record_decision` + per-charge routing

Required identifiers on every request

Send these as top-level fields on record (never inside record_json or record_json.search):

Field	Required	What it identifies	Sample format	Where used
`order_id`	Yes	The parent order in your system	`"41115779"`	Groups multiple searches; echoed in the response for reconciliation
`order_number`	Yes	The specific sub-order / search line under that order	`"41115779.1"` (`orderID.subOrderID`)	Ties this evaluate call to one search line item
`search_id`	Yes	Your unique ID for this evaluate / search run	UUID or numeric string	Request tracking; returned as `data.search_id` and `data.decision.search_id`
`search_date`	Yes	When the search was initiated	`"2025-04-30"` (`YYYY-MM-DD`)	Lookback / compliance calculations

Relationship in practice:

order_id        = 41115779          ← same for every search on this order
order_number    = 41115779.1        ← unique per search line
search_id       = 76190bc0-…        ← your ID for this evaluate call
                ↓
         POST /evaluate  (once)
                ↓
         Decision for search 41115779.1 only

Multi-search example

Same candidate, one order, two searches → two API calls:

Call	`order_id`	`order_number`	`search_id`	Payload
1	`"41115779"`	`"41115779.1"`	`"search-harris-001"`	Harris County XML (or `record_json`)
2	`"41115779"`	`"41115779.2"`	`"search-statewide-001"`	Statewide XML (or `record_json`)

Each response is independent. You merge or route results in your system using order_id / order_number / search_id.

Common mistakes

Mistake	What happens	Fix
Putting multiple searches’ XML into one `/evaluate`	Wrong granularity — API still treats the body as one search	One call per search
Omitting `order_id` or `order_number`	HTTP 400 (`must not be empty`)	Always send both on `record`
Nesting `order_id` / `order_number` / `search_id` inside `record_json`	HTTP 400 (must be sibling fields on `record`)	Keep them on `record`, next to `xml` or `record_json`
Reusing the same `search_id` for every search in an order	Hard to reconcile responses	Use a distinct `search_id` per evaluate call
Expecting one response that covers the whole order	Not supported	Call once per search; aggregate client-side
Confusing `order_number` with `search_id`	Mapping breaks in your back office	`order_number` = your sub-order line; `search_id` = this API request’s ID

What You Send

The service accepts criminal records in two formats:

Format	When to use	Field
Raw XML	Vendor screening XML (typical first call)	`record.xml`
Mapped JSON	JSON-native first call, or a later correction pass	`record.record_json`

Companion fields on record (same for both formats):

Candidate info — required with record_json; recommended with XML (name, DOB; optional SSN/address)
Search metadata — search_id, search_date, order_id, order_number
Charge mapping (cases[], optional) — maps each charge to your court/offense IDs; omit or [] to evaluate all charges without the count gate

See Supported XML Schemas for XML formats, and Evaluate for record_json.

Resubmission — optional

Most integrations only need the first evaluate. Resubmission is optional — skip it until you have a reason to use it.

Question	Answer
What is it?	Calling `POST /evaluate` again with corrected mapped JSON (`record_json` + `submission_type: "resubmit"`) instead of re-sending the original XML. Same response shape as the first call.
Why care?	Use it when you fixed candidate identity, charge data, or mapping after the first run and want a new decision without replaying vendor XML.
Don’t care?	Ignore it. Send XML (or JSON) once, process the decision, and stop. You never have to implement resubmission.

Details when you need them: Resubmission Workflow.

What You Get Back

Every response follows the same structure, regardless of whether you submitted XML or JSON:

Charge decision and queue

For day-to-day integration, focus on two fields per charge:

Concept	Field	Values	What it means
Charge decision	`offenses[].charge_decision`	`REPORTABLE`, `NOT_REPORTABLE`, `MANUAL_REVIEW`	Whether this charge can appear on a background report
Queue	`offenses[].routing.queue`	`Automation`, `Auditor`, `Insufficient Data`*	Where work should go next

*Automation — no human review needed. Auditor — human review recommended (optional). Insufficient Data — human review required. Full matrix: Routing & Queues. Use queue or decision — one is usually enough; both only if routing and report labeling are separate jobs. Ops guide: Queue & Decision → Next Action.

Charge decision	Common queue	What to do
`NOT_REPORTABLE`	Automation*	Cleared — exclude from the report
`REPORTABLE`	Auditor*	Can be reported — verify per your process
`MANUAL_REVIEW`	Insufficient Data*	Incomplete data — investigate before finishing

Hierarchy (rollup)

The response nests Record → Courts → Cases → Charges. Parent levels roll up child queues; aggregated *_decision labels mirror those queues.

Level	Decision field	Queue field	What it means
Record	`record_decision`	`search_queue`	Overall outcome for the entire search
Court	`court_decision`	`court_queue`	Outcome for all cases in one court
Case	`case_decision`	`case_queue`	Outcome for all charges in one case
Charge	`charge_decision`	`routing.queue`	Outcome for one individual charge

Queue rollup priority: Insufficient Data > Auditor > Automation.

Response status codes

HTTP Status	`data.status`	What happened
200	`success`	All processing completed — full decision returned
206	`partial`	Some processing stages failed, but partial results were still returned
400	—	Bad request — missing or invalid fields in your payload
422	`validation_required`	Your charge mapping (`cases[]`) doesn’t match the record — fix and resubmit
500	`failed`	Processing failed entirely — retry with backoff

Data quality issues

Use data.validation when a charge lands in Insufficient Data or you need to see what was wrong with the source record.

Situation	What you see
Pipeline found problems (e.g. missing disposition, ambiguous charge type, weak identity fields)	Response includes `validation` with `issues` listing field + reason
Source data passed those checks	`validation` is omitted entirely — the key is absent (not `null`, not `{}`)

Clean data ≠ every charge is reportable. Reportability still comes from compliance rules.

End-to-End Example

Typical single-search flow:

Authenticate — Exchange your API key for a JWT token (POST /auth/token). Use the returned expires_in (currently 3600 seconds / 1 hour).
Check status (optional) — Confirm the service is up (GET /health).
Evaluate — Call POST /evaluate with either record.xml or record.record_json, plus candidate_info and search metadata.
Process the decision — For each charge in the response:
- NOT_REPORTABLE → Automation* — exclude from the background report
- REPORTABLE → Auditor* — verify per your process
- MANUAL_REVIEW → Insufficient Data* — investigate incomplete data
Resubmit (optional) — Only if you corrected mapped data or candidate info after the first run: call POST /evaluate again with record_json + submission_type: "resubmit" (no XML). Skip this if one evaluate is enough. See Resubmission — optional and Resubmission Workflow.
Handle errors — If a request fails, follow the Retry Logic guidelines.

*Automation = no human review needed. Auditor = human review recommended (optional). Insufficient Data = human review required. If your workflow uses multiple searches under one order, repeat step 3 once per search (see Order → Search → Evaluate contract).

Quickstart — Run your first evaluation in 5 minutes
Supported XML Schemas — XML formats accepted by the service
API Reference — Complete endpoint documentation
Routing & Queues — Detailed routing matrix and rollup logic

Getting Started

Resources

The Request Flow

Order → Search → Evaluate contract

Required identifiers on every request

Multi-search example

Common mistakes

What You Send

Resubmission — optional

What You Get Back

Charge decision and queue

Hierarchy (rollup)

Response status codes

Data quality issues

End-to-End Example

​The Request Flow

​Order → Search → Evaluate contract

​Required identifiers on every request

​Multi-search example

​Common mistakes

​What You Send

​Resubmission — optional

​What You Get Back

​Charge decision and queue

​Hierarchy (rollup)

​Response status codes

​Data quality issues

​End-to-End Example

​Related

The Request Flow

Order → Search → Evaluate contract

Required identifiers on every request

Multi-search example

Common mistakes

What You Send

Resubmission — optional

What You Get Back

Charge decision and queue

Hierarchy (rollup)

Response status codes

Data quality issues

End-to-End Example

Related