# 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.

- **HTML:** https://offendersearch.app/docs/guides/criminal/arrests-charges-convictions
- **Base URL (live):** https://api.offendersearch.app — live keys (`os_live_…`)
- **Base URL (sandbox):** https://sandbox.offendersearch.app — test keys (`os_test_…`), never billed
- **Authentication:** `X-API-Key` request header
- **OpenAPI:** https://offendersearch.app/openapi.json · https://offendersearch.app/openapi.yaml
- **Docs index for agents:** https://offendersearch.app/llms.txt

## 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 `jail` records as convictions. Their charges are accusations at arrest.
- Reading `custodyStatus: "disposed"` as convicted. Disposed means decided; the decision is in each charge's `outcome`.
- Reading a `null` severity or an empty disposition as information. Both mean the source did not publish it; `normalized` says `unknown` when it cannot classify.
- Merging records across sources into one story. The same event can appear as a `jail` record and a `court` record; `sources[].code` says which is which and `personRef` is scoped to one source.
- Showing `description` without `outcome` beside it, to a reviewer or to a model.

## Presenting a record honestly

```plain
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 record
```

Kind, court, dates, each charge with its outcome, and the source. Nothing summarised into a verdict the data did not state.

## Related

- [Understanding record types](https://offendersearch.app/docs/guides/criminal/record-types)
- [Understanding dispositions](https://offendersearch.app/docs/guides/criminal/dispositions)
- [Handling false positives](https://offendersearch.app/docs/guides/criminal/false-positives)