# Understanding charges

> Every case carries `charges[]` in the source's words, and `normalized.cases[].charges[]` carries the classification. Read both.

- **HTML:** https://offendersearch.app/docs/guides/criminal/charges
- **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 charge as published: `cases[].charges[]`

| Field | Type | Meaning |
| --- | --- | --- |
| `description` | string (`""` when none) | The charge as the source wrote it: `"COCAINE - POSSESSION"`, `"BURG HABIT INTEND OTH FELONY"`. Some court sources put a case caption or a court name here; the normalized charge then carries `notACharge: true`. |
| `statute` | string (`""`) | The citation as published: `"35-43-2-1"`, `"2903.02"`, `"22990003"`. Formats differ by state. |
| `severity` | `felony` · `misdemeanor` · `infraction` · `null` | As published. `null` means not published — not minor. |
| `disposition` | string (`""`) | The outcome as published: `"convicted"`, `"adjudicated"`, `"GA"`, `"DISM/RELEASED TO AUTHORITIES"`, `"wanted"`. [Understanding dispositions](/docs/guides/criminal/dispositions). |
| `dispositionDate`, `offenseDate` | ISO date · `null` | When the outcome was entered; when the offense is alleged to have occurred. |
| `plea` | string (`""`) | Where published. |
| `counts` | integer · `null` | Number of counts where published; `null` when unstated. |

## The charge classified: `normalized.cases[].charges[]`

| Field | Vocabulary | Meaning |
| --- | --- | --- |
| `category` | `supervision`, `homicide`, `sex_offense`, `robbery`, `domestic_violence`, `dui`, `assault`, `weapons`, `burglary`, `fraud`, `theft`, `drug_distribution`, `drug_possession`, `traffic`, `public_order`, `other` | What kind of offense the charge text describes. Also a filter (`filters.chargeCategories`) and a facet. |
| `severity` | `felony`, `misdemeanor`, `infraction`, `unknown` | The class, from the source where published or derived — `severityBasis` says how: `published`, `statute_code`, `statute_table`, `case_type`, `charge_text`. |
| `outcome` | `convicted`, `pending`, `dismissed`, `nolle_prosequi`, `acquitted`, `deferred_or_diverted`, `vacated`, `warrant`, `transferred`, `closed_unspecified`, `administrative`, `unknown` | The disposition text mapped to a closed outcome. |
| `convicted` | `true`, `false`, `null` | `true` for `convicted`; `false` for acquitted, dismissed, nolle prosequi, deferred/diverted, vacated; `null` when the outcome does not decide it. |
| `degree`, `custodyEvent` | degree text; `booked`, `released`, `bonded`, `held`, `transferred`, `null` | Extra detail where the source gives it. |
| `notACharge` | boolean | The source's `description` was a caption or a court name, not a charge. |
| `rule` | string | Which rule produced the classification — only with `include: ["normalizedDetail"]`. |

Record-level roll-ups sit beside them: `normalized.topSeverity`, `normalized.chargeCategories[]`, `normalized.outcomes[]`, `normalized.hasConviction`, `normalized.convictionCount`, `normalized.latestOffenseDate` / `latestDispositionDate` / `latestFiledDate`.

## Searching by charge

The `filters` object narrows a search on the normalized fields: `recordCategory`, `severity` (with `severityBasis`), `outcome`, `convictedOnly`, `chargeCategories`, `custodyStatus`, `offenseDate` / `filedDate` / `dispositionDate` ranges, `lookbackYears`, `hasPhoto`, `sources`, `statute`, `chargeText`, `excludeVacatedOrSealed`. `include: ["facets"]` returns counts per value. Full reference: [Filtering & locations](/docs/criminal/filtering).

```json
{ "query": { "lastName": "Rivera", "firstName": "Jordan", "state": "TX" },
  "filters": { "chargeCategories": ["theft", "fraud"], "severity": ["felony"], "convictedOnly": true, "lookbackYears": 7 },
  "include": ["facets"] }
```

## What to expect in the data

- Published `severity` is missing more often than present; `normalized…severity` fills it where a statute table or case type allows and says so in `severityBasis`.
- Dates in the core charge fields are ISO or `null`. Dates in the extended groups (`booking.*`, `warrant.*`, `cases[].offenseDate` …) are ISO when they parse and otherwise the source's own text — parse defensively.
- One case can carry several charges with different outcomes; `normalized.outcomes[]` lists them all.

## Related

- [Understanding dispositions](https://offendersearch.app/docs/guides/criminal/dispositions)
- [Filtering & locations](https://offendersearch.app/docs/criminal/filtering)
- [Record normalization](https://offendersearch.app/docs/guides/criminal/normalization)