# Understanding dispositions

> The disposition is the outcome of a charge in the source's words; `normalized…outcome` is the same outcome in twelve words. It is the field that separates an accusation from a conviction.

- **HTML:** https://offendersearch.app/docs/guides/criminal/dispositions
- **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

## As published and as classified

`cases[].charges[].disposition` is kept exactly as the court or agency published it, because vocabularies differ by jurisdiction. `normalized.cases[].charges[].outcome` maps it onto a closed set, and `normalized…convicted` answers the one question most workflows ask. Record-level: `normalized.outcomes[]`, `normalized.hasConviction`, `normalized.convictionCount`.

## The outcome vocabulary

| `outcome` | Means | `convicted` |
| --- | --- | --- |
| `convicted` | A finding or plea of guilt was entered. | `true` |
| `pending` | No outcome yet; the case is open. Typical for booking records. | `null` |
| `dismissed` | The charge was dismissed. | `false` |
| `nolle_prosequi` | The prosecutor declined to proceed. | `false` |
| `acquitted` | Not guilty. | `false` |
| `deferred_or_diverted` | Deferred adjudication or a diversion program. | `false` |
| `vacated` | Vacated, expunged or sealed; `normalized.vacatedOrSealed` is set and the record is still returned unless `filters.excludeVacatedOrSealed`. | `false` |
| `warrant` | The record is a warrant, not a court outcome. | `null` |
| `transferred` | Transferred to another court or jurisdiction. | `null` |
| `closed_unspecified` | Closed without a published outcome. | `null` |
| `administrative` | An administrative action (exclusion lists). | `null` |
| `unknown` | The source published nothing usable. | `null` |

Common published texts behind them: `convicted`, `adjudicated`, `guilty` and court abbreviations such as `GA` → `convicted`; `DISM/RELEASED TO AUTHORITIES` → `dismissed`; `""` on an open case → `pending`; `wanted` → `warrant`. Where an abbreviation is unclear, `sources[].recordUrl` opens the source's own page.

## Outcome and status

`normalized.custodyStatus` is the record's state (`disposed`, `in_custody`, `released`, `active_warrant`, …); `outcome` is per charge. A `disposed` case can hold one `convicted` charge and one `dismissed` charge; `normalized.outcomes[]` lists both and `hasConviction` is `true`. Filter on `filters.outcome` or `filters.convictedOnly` to narrow a search by outcome.

## Related

- [Understanding charges](https://offendersearch.app/docs/guides/criminal/charges)
- [Arrests vs. charges vs. convictions](https://offendersearch.app/docs/guides/criminal/arrests-charges-convictions)