Safety Net Blueprint — Case Management Service API

▶ GET /cases List cases #

Retrieve a paginated list of cases.

Parameters

Name Type In Req Description

▶q string query Search query using field:value syntax. Multiple conditions separated by

Search query using field:value syntax. Multiple conditions separated by spaces are ANDed together.

URL Encoding: This parameter must be URL-encoded when sent over HTTP. Most HTTP clients handle this automatically. Examples in this documentation show human-readable syntax for clarity.

Syntax

Pattern	Description	Example
`term`	Full-text exact match	`john`
`term`	Full-text contains	`john`
`term*`	Full-text starts with	`john*`
`*term`	Full-text ends with	`*smith`
`field:value`	Exact match on field	`status:approved`
`field:value`	Contains (case-insensitive)	`name:john`
`field:value*`	Starts with	`name:john*`
`field:*value`	Ends with	`email:*@example.com`
`field:"value"`	Quoted value (for spaces)	`name:"john doe"`
`field.nested:value`	Nested field (dot notation)	`address.state:CA`
`field:>value`	Greater than	`income:>1000`
`field:>=value`	Greater than or equal	`income:>=1000`
`field:<value`	Less than	`income:<5000`
`field:<=value`	Less than or equal	`income:<=5000`
`field:val1,val2`	Match any value (OR)	`status:approved,pending`
`-field:value`	Exclude / negate	`-status:denied`
`field:*`	Field exists (not null)	`email:*`
`-field:*`	Field does not exist	`-deletedAt:*`

Examples

john — exact match for "john" in searchable fields
john — contains "john" in searchable fields
name:smith — name contains "smith" (case-insensitive)
email:*@example.com — email ends with "@example.com"
status:approved — exact match on status field
status:approved,pending — status is "approved" OR "pending"
income:>=1000 — income greater than or equal to 1000
created:>2024-01-01 — created after January 1, 2024
status:approved income:>=1000 — approved AND income >= 1000 (multiple conditions)
-status:denied — exclude records with status "denied"
-deletedAt:* — only records where deletedAt does not exist
applicant.state:CA — nested field filter

URL Encoding Reference

When manually constructing URLs, encode these characters:

Character	Encoded
(space)	`%20` or `+`
`"`	`%22`
`:`	`%3A`
`>`	`%3E`
`<`	`%3C`
`,`	`%2C`

Example: `` Human-readable: q=status:approved income:>=1000 URL-encoded: q=status%3Aapproved%20income%3A%3E%3D1000 ``

limit

integer

query

Maximum number of items to return (1-100).

offset

integer

query

Number of items to skip before collecting results.

▶sort string query Comma-separated list of fields to sort the response by. Prefix a field

Comma-separated list of fields to sort the response by. Prefix a field with - for descending order. The first field is the primary sort; subsequent fields are tie-breakers in declaration order.

URL Encoding: This parameter must be URL-encoded when sent over HTTP. Most HTTP clients handle this automatically. Examples below show human-readable syntax for clarity.

Which fields a given list endpoint allows is declared in the operation's x-sortable.fields extension. Sending a field name not present in that list returns 400 FIELD_NOT_SORTABLE. Sending a field name that doesn't exist on the resource schema returns 400 INVALID_SORT_FIELD. When this parameter is omitted, the operation's x-sortable.default (if declared) is applied; otherwise no client-driven sort is applied. A configured tie-breaker (default id) is always appended for stable pagination.

See api-patterns.yaml#sorting for the full convention and docs/architecture/x-extensions.md for the extension shape.

Syntax

Pattern	Description	Example
`fieldName`	Ascending	`sort=createdAt`
`-fieldName`	Descending	`sort=-createdAt`
`field1,field2`	Multi-field	`sort=status,-priority`
`nested.field`	Nested field via dot notation	`sort=name.lastName`

Examples

sort=createdAt — oldest first
sort=-createdAt — newest first
sort=-priority,dueDate — highest priority first, then oldest due date
sort=name.lastName,name.firstName — alphabetical by surname, then given name

Responses

200 A paginated collection of cases.

▶ CaseList

total integer required Total number of items available.

limit integer required Maximum number of items requested.

offset integer required Number of items skipped before the current page.

hasNext boolean Whether more items are available beyond the current page.

▶ items array[Case] required

status string Current status of the case. Will be driven by x-enum-source once a case-management state machine is defined.

enumactive closed

effectiveStartDate string (date) Date when coverage or the case relationship begins.

effectiveEndDate string (date) Date when the case was closed. Null while active.

primaryApplicantId string (uuid) Reference to the Person record for the primary applicant.

▶ members array[CaseMember] Household members associated with this case.

personId string (uuid) required Reference to the Person record.

relationship string required Relationship to the primary applicant.

assignedToId string (uuid) Reference to the User record for the assigned case worker.

id string (uuid) read-only Unique identifier (server-generated).

createdAt string (date-time) read-only Timestamp when the case was created.

updatedAt string (date-time) read-only Timestamp when the case was last updated.

400 The request is malformed or contains invalid parameters.

▶ BadRequest

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

500 An unexpected error occurred on the server.

▶ InternalError

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

▶ POST /cases Create a case #

Create a new case record.

Request body required

▶ CaseCreate