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

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

## 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](/docs/guides/criminal/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

```json
{
  "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](/docs/criminal/record-object).

## Related

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