Understanding record types
A developer must never be left guessing whether a record is an arrest, a charge, a conviction, a warrant or something else. Here is how to tell.
Two fields: the source's label and the closed category
| Field | Vocabulary | Use |
|---|---|---|
recordCategory | Closed: court, jail, prison, warrant, registry, exclusion, other | Branch on this. It is also a filter (filters.recordCategory) and a facet. |
recordType | Open — the source's own label. Most common today: jail, court_case, jail_booking, arrest, doc_inmate, registry, criminal_record, warrant, wanted_fugitive, federal_wanted, healthcare_exclusion, plus rarer registry-specific labels | Show it to a reviewer; never branch on exact strings. |
currentStatus | Open — the source's status text passed through. Usually one of in_custody, released, on_parole, on_probation, active_warrant, wanted, registered, disposed, absconder, deceased, excluded, unknown; sources also write booked, scheduled, arrested, incarcerated, filed, indicted, pending | Display. For logic use normalized.custodyStatus. |
normalized.custodyStatus | Closed: the twelve values above (unknown when the source said nothing) | Branch and filter on this (filters.custodyStatus). |
Important. The
normalized object is where every closed vocabulary lives: recordCategory, custodyStatus, topSeverity, hasConviction, convictionCount, chargeCategories[], outcomes[] and a per-case, per-charge classification. The top-level fields keep the source's own words. Read Record normalization.The record categories
| `recordCategory` | Comes from | What one record is | Key fields |
|---|---|---|---|
jail | County jail rosters and booking logs | One person booked into a jail: when, on what charges, and release where published. An arrest-stage record. | booking (bookingNumber, bookingDate, arrestDate, arrestingAgency, bond, holds[]), dateIncarcerated, releaseDate, custodyFacility, charges usually without a disposition, mugshotUrl |
prison | State departments of corrections and the Federal Bureau of Prisons | A person serving or having served a sentence. Charges on a prison record are offenses of conviction. | sentence, parole, custody, custodyFacility, releaseDates, supervision, normalized.hasConviction |
court | Criminal court dockets and dispositions | One case: filing, charges, pleas, dispositions, sentence. The record kind that decides conviction. | cases[].caseNumber, court, filedDate, status, charges[].disposition, normalized.outcomes[] |
warrant | Warrant and wanted-person systems | An open matter: an active warrant or a wanted notice. | warrant (issuedDate, issuedBy, type, outstanding, captured), normalized.custodyStatus active_warrant / wanted |
registry | Statewide registries published through this product | A registration. | registry (name, registeredOn, compliance, offenderType), custodyStatus: "registered" |
exclusion | Federal and state exclusion lists | An administrative or conviction-based exclusion; returned with include: ["exclusions"] when the basis is administrative. | exclusion (program, authority, convictionBased, excludedOn, reinstatedOn) |
other | Anything the category map does not place | Read recordType and the fields present. | — |
Four vocabularies that all say "kind"
| Where | Field | Vocabulary | Maps to `recordCategory` |
|---|---|---|---|
| A record | recordCategory | Closed: the seven values above | — |
| A record | recordType | Open: the source's label (jail_booking, court_case, doc_inmate, wanted_fugitive, healthcare_exclusion, …) | Via the category map; normalized.recordCategory is the same value |
GET /v1/criminal/jurisdictions | recordKind | jail-roster, court, doc-inmate, warrant, registry, exclusion | jail, court, prison, warrant, registry, exclusion |
GET /v1/criminal/sources | recordType | Human labels: County jail roster, Court records, Prison system, Warrant system, Statewide registry, Exclusion list, Records | Same order; Records → other |
When normalized is null the record could not be classified: treat its outcome as unknown, keep recordCategory (always present) and read the source words.
Reading one record
{
"recordType": "court_case",
"recordCategory": "court",
"currentStatus": "disposed",
"matchConfidence": 0.82,
"matchState": "dob_match",
"name": { "first": "Jordan", "middle": "", "last": "Rivera", "suffix": "" },
"dob": { "date": "1988-04-12", "birthYear": 1988, "birthMonth": 4, "age": 38, "ageAsOf": "2026-10-24", "dobPrecision": "full" },
"state": "TX", "county": "Harris",
"cases": [
{ "caseNumber": "123456701010", "court": "Harris County District Court", "county": "Harris", "state": "TX", "level": "county",
"filedDate": "2021-03-02", "status": "closed",
"charges": [ { "statute": "31.03", "description": "THEFT PROP >=$2,500<$30K", "severity": "felony",
"disposition": "convicted", "dispositionDate": "2021-11-18", "offenseDate": "2021-02-20", "plea": "", "counts": 1 } ] }
],
"normalized": {
"recordCategory": "court", "custodyStatus": "disposed", "topSeverity": "felony",
"hasConviction": true, "convictionCount": 1, "chargeCategories": ["theft"], "outcomes": ["convicted"],
"cases": [ { "stage": "closed", "caseClass": "felony",
"charges": [ { "category": "theft", "severity": "felony", "severityBasis": "published", "outcome": "convicted", "convicted": true } ] } ]
},
"sources": [ { "code": "TX-HARRIS", "level": "county", "recordUrl": "https://…", "lastCheckedAt": "2026-10-24T03:10:00+00:00", "live": false } ],
"lifecycle": { "firstSeen": "…", "lastSeen": "…", "presentInLastSweep": true, "droppedOut": false, "droppedOutDetected": null, "dropInterpretation": "unknown", "sourceLastUpdated": null }
}A court record (recordCategory: "court"), decided (custodyStatus: "disposed"), one charge, convicted (normalized.hasConviction: true). A jail record for the same arrest would carry booking.*, dateIncarcerated and a custodyFacility, its charges usually with an empty disposition, and normalized.hasConviction: null or false. Every field: the Record object.