Skip to main content

​
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 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 FCRA rules and state-specific laws. The service determines whether the charge is reportable, not reportable, or needs manual review — and assigns a routing recommendation. All three stages happen behind a single POST /evaluate call. The response contains the complete decision.

​
Orders, Searches, and Actions

Background screening follows a hierarchy: Orders contain Searches, and each search produces a set of Actions (decisions). Each POST /evaluate call evaluates one search. If an order has three searches (county, statewide, federal), you make three separate API calls. The response for each call is self-contained — it includes the decision for every charge in that search.

​
What You Send

The service accepts criminal records in two formats: Both formats require the same companion data:
  • Candidate info — the person being screened (name, DOB, SSN, address)
  • Search metadata — search ID, search date, order ID, order number
  • Charge mapping (optional) — maps each charge to your internal IDs and controls which charges appear in the response
See Supported XML Schemas for the XML formats accepted.

​
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:

​
Hierarchy (rollup)

The response nests Record → Courts → Cases → Charges. Parent levels roll up child queues; aggregated *_decision labels mirror those queues. Queue rollup priority: Insufficient Data > Auditor > Automation.

​
Response status codes

​
Data quality issues

When the submitted record has missing or ambiguous data (e.g., no SSN, no disposition, unclear charge type), the response includes a validation object listing the specific problems. Use this to understand why a charge was routed to Insufficient Data. When the data is clean, the validation field is omitted entirely.

​
End-to-End Example

Here’s a typical integration flow:
  1. Authenticate — Exchange your API key for a JWT token (POST /auth/token). Use the returned expires_in (currently 3600 seconds / 1 hour).
  2. Check health (optional) — Confirm the service is available (GET /health).
  3. Submit each search — For each search in the order, call POST /evaluate with the criminal record and candidate information.
  4. Process the decision — For each charge in the response:
    • NOT_REPORTABLE → Automatically exclude from the background report
    • REPORTABLE → Send to your auditor queue for final verification
    • MANUAL_REVIEW → Send to your researcher queue for investigation
  5. Handle errors — If a request fails, follow the Retry Logic guidelines.