Arrests vs. charges vs. convictions
A booking is not a charge, a charge is not a conviction, and the API keeps them apart. So must your integration.
The three events
| Event | In the API | Tell-tale fields | What it proves |
|---|---|---|---|
| Arrest / booking | recordCategory: "jail" | booking.bookingDate, booking.arrestDate, custodyFacility, charges with disposition: "" and outcome: "pending", normalized.hasConviction null/false | The person was booked on these accusations. Nothing about guilt. |
| Charge | recordCategory: "court" with normalized.cases[].stage: "open" | cases[].caseNumber, filedDate, outcome: "pending" | A prosecutor filed; the court has not decided. |
| Conviction | recordCategory: "court" with normalized…outcome: "convicted", or recordCategory: "prison" | normalized.hasConviction: true, convictionCount, dispositionDate; prison: sentence, custodyFacility, custodyStatus in_custody / released / on_parole | A finding or plea of guilt on that charge; or a sentence being served. |
normalized.hasConviction is the computed answer to "is there a conviction on this record"; filters.convictedOnly: true asks the search for only such records. Neither replaces the review of the charge itself.
Mistakes to avoid
- Counting
jailrecords as convictions. Their charges are accusations at arrest. - Reading
custodyStatus: "disposed"as convicted. Disposed means decided; the decision is in each charge'soutcome. - Reading a
nullseverity or an empty disposition as information. Both mean the source did not publish it;normalizedsaysunknownwhen it cannot classify. - Merging records across sources into one story. The same event can appear as a
jailrecord and acourtrecord;sources[].codesays which is which andpersonRefis scoped to one source. - Showing
descriptionwithoutoutcomebeside it, to a reviewer or to a model.
Presenting a record honestly
Court case · Harris County District Court · filed 2021-03-02 · closed
THEFT PROP >=$2,500<$30K (statute 31.03, felony) — outcome: convicted (2021-11-18)
Source: TX-HARRIS · last checked 2026-10-24 · open the source recordKind, court, dates, each charge with its outcome, and the source. Nothing summarised into a verdict the data did not state.