> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docketstream.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Roster API: Query Live Georgia Inmate Booking Records

> GET /roster returns live inmate booking records. Filter by county, date, or name. GET /roster/{id} returns a single inmate's full record.

The Roster endpoints return live booking data aggregated from Georgia county jails. Records are refreshed every **30–60 minutes** directly from source jail management systems, giving you near-real-time visibility into new bookings, active holds, and recent releases. Use these endpoints to power inmate lookup tools, automate monitoring workflows, or feed downstream analytics pipelines.

***

## GET /roster

List and filter inmate booking records across all available counties. Results are paginated and sorted by `booking_date` descending by default.

```bash theme={null}
GET https://api.docketstream.org/v1/roster?county=clayton&limit=50
Authorization: Bearer YOUR_API_KEY
```

### Query Parameters

<ParamField query="county" type="string">
  The county name slug to filter results by (e.g., `"clayton"`, `"fulton"`).
  Omit this parameter to search across all available counties.
</ParamField>

<ParamField query="name" type="string">
  Partial name search applied against the inmate's full name. Case-insensitive.
  For example, `"john doe"` will match `"JOHN DOE"` and `"Doe, John"`.
</ParamField>

<ParamField query="status" type="string">
  Filter by inmate booking status. Accepted values: `"booked"` or `"released"`.
</ParamField>

<ParamField query="from_date" type="string">
  Return only records with a `booking_date` on or after this date. Must be a
  valid ISO 8601 date string, e.g. `"2024-01-15"`.
</ParamField>

<ParamField query="to_date" type="string">
  Return only records with a `booking_date` on or before this date. Must be a
  valid ISO 8601 date string, e.g. `"2024-06-30"`.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Maximum number of records to return per page. Minimum: `1`. Maximum: `200`.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of records to skip before returning results. Use with `limit` to
  paginate through large result sets.
</ParamField>

### Response

```json theme={null}
{
  "total": 1284,
  "limit": 50,
  "offset": 0,
  "records": [
    {
      "id": "cltn-2024-00123",
      "name": "John Doe",
      "dob": "1985-03-22",
      "county": "Clayton",
      "booking_date": "2024-06-10T14:32:00Z",
      "release_date": null,
      "charges": ["Theft by Taking", "Obstruction"],
      "bond_amount": 5000,
      "status": "booked",
      "mugshot_url": "https://api.docketstream.org/v1/mugshots/cltn-2024-00123"
    }
  ]
}
```

### Response Fields

<ResponseField name="total" type="integer">
  The total number of records matching your query across all pages.
</ResponseField>

<ResponseField name="limit" type="integer">
  The `limit` value applied to this response.
</ResponseField>

<ResponseField name="offset" type="integer">
  The `offset` value applied to this response.
</ResponseField>

<ResponseField name="records" type="array">
  An array of inmate booking objects. May be empty if no records match your
  filters.

  <ResponseField name="records[].id" type="string">
    The unique DocketStream identifier for this booking record (e.g.,
    `"cltn-2024-00123"`).
  </ResponseField>

  <ResponseField name="records[].name" type="string">
    The inmate's full name as reported by the county jail.
  </ResponseField>

  <ResponseField name="records[].dob" type="string">
    Date of birth in `YYYY-MM-DD` format.
  </ResponseField>

  <ResponseField name="records[].county" type="string">
    Display name of the county where the individual is or was booked.
  </ResponseField>

  <ResponseField name="records[].booking_date" type="string">
    ISO 8601 timestamp of when the individual was booked.
  </ResponseField>

  <ResponseField name="records[].release_date" type="string | null">
    ISO 8601 timestamp of release, or `null` if the individual is still booked.
  </ResponseField>

  <ResponseField name="records[].charges" type="array of strings">
    List of charge descriptions associated with this booking.
  </ResponseField>

  <ResponseField name="records[].bond_amount" type="number | null">
    Total bond amount in USD, or `null` if no bond has been set.
  </ResponseField>

  <ResponseField name="records[].status" type="string">
    Current booking status: `"booked"` or `"released"`.
  </ResponseField>

  <ResponseField name="records[].mugshot_url" type="string | null">
    Fully-qualified URL to the inmate's mugshot image, or `null` if unavailable.
    Requests to this URL must also include your `Authorization` header.
  </ResponseField>
</ResponseField>

***

## GET /roster/{id}

Retrieve the complete booking record for a single inmate by their DocketStream record ID. This endpoint returns all fields from the list response plus an additional `gdc_match` object when a corresponding Georgia Department of Corrections record is found.

```bash theme={null}
GET https://api.docketstream.org/v1/roster/cltn-2024-00123
Authorization: Bearer YOUR_API_KEY
```

### Path Parameter

<ParamField path="id" type="string" required>
  The unique DocketStream record ID for the inmate booking. IDs are returned by
  `GET /roster` and follow the format `{county-slug}-{year}-{sequence}`.
</ParamField>

### Response

The response includes all fields from the `/roster` list response, plus:

<ResponseField name="gdc_match" type="object | null">
  When DocketStream identifies a matching GDC record, this object contains
  details of that match. Returns `null` if no GDC record is linked.

  <ResponseField name="gdc_match.gdc_id" type="string">
    The GDC offender identifier for the matched record.
  </ResponseField>

  <ResponseField name="gdc_match.confidence" type="string">
    Match confidence level: `"high"`, `"medium"`, or `"low"`.
  </ResponseField>

  <ResponseField name="gdc_match.mugshot_match" type="boolean">
    `true` if DocketStream's facial recognition confirmed a mugshot match
    between the roster record and the GDC record.
  </ResponseField>

  <ResponseField name="gdc_match.corrections_url" type="string">
    URL to the full GDC record via `GET /corrections/{gdc_id}`.
  </ResponseField>
</ResponseField>

<Note>
  Roster data refreshes every **30–60 minutes**. If you query a record
  immediately after a booking or release event, the `status` and `release_date`
  fields may not yet reflect the latest source data. For real-time notifications
  on status changes, configure a [webhook](/api/alerts-webhooks) instead.
</Note>