Cases

A case is a matter tied to a client, identified by a case number: a criminal charge, a citation matter, or any docketed proceeding. Events and payments carry a case_number, so a case groups the records that share it; a message links to a case by its UUID. A case can have attorneys assigned to it.

This page assumes the shared API Conventions for pagination, filtering, lifecycle actions, and references. All endpoints use your region's base URL and a Bearer token.

Endpoints

Method	Path	Description
`GET`	`/v1/cases`	List cases
`GET`	`/v1/cases/total`	Count cases matching filters
`GET`	`/v1/cases/{uuid}`	Get a single case (by UUID or `case_number`)
`GET`	`/v1/cases/{uuid}/attorneys`	List attorneys assigned to a case
`GET`	`/v1/cases/{uuid}/pdf`	Get a generated PDF of the case
`POST`	`/v1/cases`	Create a case
`PATCH`	`/v1/cases/{uuid}`	Update a case
`PUT`	`/v1/cases/{uuid}`	Update a case (alias of `PATCH`)
`POST`	`/v1/cases/assign`	Queue a bulk case assignment
`PUT`	`/v1/cases/{uuid}/archive`	Archive a case
`PUT`	`/v1/cases/{uuid}/restore`	Restore an archived or deleted case
`DELETE`	`/v1/cases/{uuid}`	Delete a case (soft delete)

The Case Object

Field	Type	Description
`uuid`	string	Unique identifier, generated when the case is created.
`client`	string	UUID of the client the case belongs to.
`case_number`	string	The case number. Required on create.
`status`	string	Agency-defined case status.
`type`	string	Agency-defined case type.
`charge_number`	string	Charge number.
`codes`	string	Statute or charge codes.
`description`	string	Case description.
`offense_type`	string	Offense type.
`offense_description`	string	Offense description.
`offense_date`	string	Offense date (`YYYY-MM-DD`).
`arrest_date`	string	Arrest date (`YYYY-MM-DD`).
`arresting_agency`	string	Arresting agency.
`arrest_tracking`	string	Arrest tracking number.
`file_date`	string	Filing date (`YYYY-MM-DD`).
`judgment_date`	string	Judgment date (`YYYY-MM-DD`).
`warrant_status`	string	Warrant status for the case.
`conditions`	string	Case conditions.
`victim_name`	string	Victim name.
`offender_name`	string	Offender name.
`location`	string	UUID of the location tied to the case.
`upload`	string	UUID of the file import associated with the case, when linked to one.
`created_by`	string	Email or UUID of the creator.
`created_at`	string	Creation timestamp, UTC.
`updated_at`	string	Last update timestamp, UTC.
`archived_at`	string	Set when the case is archived, otherwise `null`.
`deleted_at`	string	Set when the case is deleted, otherwise `null`.

Case responses also include attorney, the assigned attorney's uuid, firm_name, and bar_number (when one is assigned), on both list and single-case responses.

Create a Case

POST /v1/cases

Request:

curl -X POST "$BASE_URL/v1/cases" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client": "{client_uuid}",
    "case_number": "CASE-2024-001",
    "type": "criminal",
    "status": "open",
    "offense_date": "2024-01-10",
    "description": "Traffic violation"
  }'

Response (201): the created case.

Create Behavior

case_number: required. A create without one returns 400 with Case number is required.
client: attach the case to a client by UUID.
attorneys: an optional array of attorney UUIDs (or objects with an uuid) to assign to the case. The response includes the assigned attorneys.
Creating a case with a client attached triggers a case_created auto message.

List Cases

GET /v1/cases

curl -X GET "$BASE_URL/v1/cases?client={client_uuid}&status=open&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Response (200): a JSON array of case objects.

Query Parameters

Parameter	Description
`search`	Partial match on `case_number`.
`case_number`	Exact match on case number.
`client`	Filter by client UUID.
`status`	Exact match on status.
`type`	Exact match on type.
`charge_number`	Exact match on charge number.
`arresting_agency`	Exact match on arresting agency.
`arrest_tracking`	Exact match on arrest tracking number.
`offense_type`	Exact match on offense type.
`arrest_date`	Exact match on arrest date.
`offense_date`	Exact match on offense date.
`file_date`	Exact match on file date.
`judgment_date`	Exact match on judgment date.
`description`	Partial match on description.
`offense_description`	Partial match on offense description.
`offender_name`	Partial match on offender name.
`location`	Filter by location.
`upload`	Filter by the file import (upload) UUID that created the cases.
`created_by`	Filter by the creator.

Pagination and shaping (limit, skip, sort, sortDirection, fields) follow the shared conventions.

Get a Case

GET /v1/cases/{uuid}

The path value accepts a case UUID or a case_number. Returns the case with its assigned attorney. Returns 404 with a message of Case {uuid} not found when no case matches.

Update a Case

PATCH /v1/cases/{uuid}

PUT is an accepted alias. The path value accepts a UUID or a case_number. Send only the fields you want to change. Include an attorneys array to replace the case's assigned attorneys; the response then includes the updated attorneys.

curl -X PATCH "$BASE_URL/v1/cases/{case_uuid}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed",
    "judgment_date": "2024-04-01"
  }'

Attorneys

GET /v1/cases/{uuid}/attorneys

Returns the attorneys assigned to the case, each with uuid, firm_name, bar_number, first_name, and last_name. To assign attorneys, include an attorneys array on the case create or update.

Assign Cases in Bulk

POST /v1/cases/assign

Queues a background job that assigns cases in bulk according to the request body. Returns 202 with the queued job, or 400 with Something went wrong when the job could not be queued.

Archive, Restore, and Delete

PUT /v1/cases/{uuid}/archive
PUT /v1/cases/{uuid}/restore
DELETE /v1/cases/{uuid}

Archive sets archived_at and removes the case from default lists. Returns {"message": "Case archived"}, or 404 with Case not found.
Delete is a soft delete: it sets deleted_at. Returns a 204 with no body.
Restore clears archived_at and deleted_at. Returns {"message": "Case restored"}, or 404 with Case not found.

FAQs

How does a case relate to events, payments, and messages?

Events and payments carry a case_number, and the case groups the records that share it. Set the same case_number on an event or payment as on the case to associate them, and filter events or payments by case_number. A message links to a case by its UUID through the message case field, so filter messages with ?case={case_uuid} rather than by case number.

How do I attach a case to a client?

Set the client field to the client's UUID on create. A case with a client attached also triggers a case_created auto message.

How do I look up a case by its case number?

Pass the case number in the path of a get or update (GET /v1/cases/CASE-2024-001), or filter the list with GET /v1/cases?case_number=CASE-2024-001. Use search for a partial match.

How do I assign an attorney to a case?

Include an attorneys array of attorney UUIDs when creating or updating the case, then read them back with GET /v1/cases/{uuid}/attorneys. Updating the attorneys array replaces the current assignment.

Why did creating a case return a 400?

case_number is required. A create without it returns 400 with Case number is required.

API Conventions: shared listing, filtering, and lifecycle behavior
Clients: the person a case belongs to
Events: hearings and dates that share a case number
Payments: balances that share a case number
Error Handling: status codes and error responses

Endpoints​

The Case Object​

Create a Case​

Create Behavior​

List Cases​

Query Parameters​

Get a Case​

Update a Case​

Attorneys​

Assign Cases in Bulk​

Archive, Restore, and Delete​

FAQs​

Related Documentation​