Case Management API Reference

On this page

Case management: referrals, investigations, cases, case plans, contacts, and court orders — the system of record for casework.

Endpoints

Case Plans

List case plans

GET /v1/cases/cases/{id}/plans

Table 1. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Responses

200: Case plans
401: Unauthorized
403: Forbidden
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Create a case plan

POST /v1/cases/cases/{id}/plans

Table 2. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Table 3. Request Fields
Field	Type	Required	Description
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1256) — REQUIRED. Same id + identical intent (including the case path id) replays the original plan; a different intent under the same id is a 409 `idempotency-conflict`.
needs	string (optional)	No	Free-form description of the family’s needs.
permanency_goal	enum (reunification, adoption, guardianship, long_term_foster_care, emancipation, relative_placement, not_yet_established)	Yes	Permanency goal — AFCARS element #36.
review_due_at	datetime (optional)	No	Date by which the plan must be next reviewed.
strengths	string (optional)	No	Free-form description of the family’s strengths.

Responses

200: Case plan created (or replayed — same client_request_id + intent)
401: Unauthorized
403: Forbidden
404: Case not found
409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Update a case plan

PUT /v1/cases/plans/{id}

Table 4. Parameters
Name	In	Required	Description
id	path	Yes	Case plan ID

Table 5. Request Fields
Field	Type	Required	Description
needs	string (optional)	No	New needs description.
permanency_goal	PermanencyGoal (optional)	No	Permanency goal
review_due_at	datetime (optional)	No	New review-due date.
status	string (optional)	No	New status (`draft` / `approved` / `closed`).
strengths	string (optional)	No	New strengths description.

Responses

200: Case plan updated
400: Invalid status transition
401: Unauthorized
403: Forbidden
404: Case plan not found
409: Concurrent modification — re-read and retry
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Approve (countersign) a case plan

PUT /v1/cases/plans/{id}/approve

Supervisor approval — sets plan to active and supersedes any other active plan on the case.

Table 6. Parameters
Name	In	Required	Description
id	path	Yes	Case plan ID

Responses

200: Case plan approved
401: Unauthorized
403: Forbidden — supervisor role required
404: Case plan not found or not in draft status
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

List tasks for a case plan

GET /v1/cases/plans/{id}/tasks

Table 7. Parameters
Name	In	Required	Description
id	path	Yes	Case plan ID

Responses

200: Tasks
401: Unauthorized
403: Forbidden
404: Case plan not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Add a task to a case plan

POST /v1/cases/plans/{id}/tasks

Table 8. Parameters
Name	In	Required	Description
id	path	Yes	Case plan ID

Table 9. Request Fields
Field	Type	Required	Description
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1256) — REQUIRED. Same id + identical intent (including the plan path id) replays the original task; a different intent under the same id is a 409 `idempotency-conflict`.
description	string	Yes	Free-form task description.
due_at	datetime (optional)	No	Task due date.
responsible	enum (parent, agency, provider, other)	Yes	Who is responsible for a case plan task.

Responses

200: Task created (or replayed — same client_request_id + intent)
401: Unauthorized
403: Forbidden
404: Case plan not found
409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get a task by ID

GET /v1/cases/tasks/{id}

Table 10. Parameters
Name	In	Required	Description
id	path	Yes	Task ID

Responses

200: Task
401: Unauthorized
403: Forbidden
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Update a task

PUT /v1/cases/tasks/{id}

Table 11. Parameters
Name	In	Required	Description
id	path	Yes	Task ID

Table 12. Request Fields
Field	Type	Required	Description
completed_at	datetime (optional)	No	Timestamp the task was completed.
status	string (optional)	No	New status (`pending` / `in_progress` / `complete` / `cancelled`).

Responses

200: Task updated
400: Invalid status transition
401: Unauthorized
403: Forbidden
404: Task not found
409: Concurrent modification — re-read and retry
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Delete a task

DELETE /v1/cases/tasks/{id}

Table 13. Parameters
Name	In	Required	Description
id	path	Yes	Task ID

Responses

204: Task deleted
401: Unauthorized
403: Forbidden
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Cases

Batch-lookup case numbers and person names by IDs

POST /v1/cases/batch-lookup

Table 14. Request Fields
Field	Type	Required	Description
case_ids	array of UUID	No	Case UUIDs to resolve names for.
person_ids	array of UUID	No	Person UUIDs to resolve names for.

Responses

200: Resolved names
400: Too many IDs
401: Unauthorized
403: Forbidden
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

List cases

GET /v1/cases/cases

Table 15. Parameters
Name	In	Required	Description
page	query	No	1-indexed page number (default `1`).
per_page	query	No	Page size (default `25`).
worker	query	No	Filter by assigned worker (`claims.sub` UUID, post ADR-025).
status	query	No	Filter by status: open, closed, transferred.
admin_unit	query	No	Filter by administrative unit.
search	query	No	Substring search across `case_number` and `admin_unit` (worker is UUID-typed; worker substring search was removed by ADR-025). LIKE metacharacters (`%`/`_`/`\`) match literally.
person_id	query	No	Filter to cases whose `case_household` contains this person.
sort_by	query	No	Sort column: case_number, status, admin_unit, assigned_worker, opened_at.
sort_dir	query	No	Sort direction: asc or desc (default: desc).

Responses

200: Paginated cases
401: Unauthorized
403: Forbidden
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Open a case

POST /v1/cases/cases

Table 16. Request Fields
Field	Type	Required	Description
admin_unit	string	Yes	Administrative unit (county / region) owning the case.
assigned_worker	UUID	Yes	Worker `claims.sub` UUID (post ADR-025 identity normalization). Display name is resolved at read time via `worker_identities`.
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1256) — REQUIRED. Same id + identical intent replays the original case (the case number is generated ONLY on the first execution); a different intent under the same id is a 409 `idempotency-conflict`.
icwa_flag	boolean	No	`true` when ICWA may apply.
investigation_id	UUID (optional)	No	Investigation that substantiated the case (optional for direct filing).
supervisor	UUID (optional)	No	Supervisor `claims.sub` UUID, or NULL for unsupervised cases.

Responses

200: Case created (or replayed — same client_request_id + intent; the case number is generated only on the first execution)
401: Unauthorized
403: Forbidden
409: client_request_id claimed by a different operation, replayed entity gone, or case-number retries exhausted (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get a case by ID

GET /v1/cases/cases/{id}

Table 17. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Responses

200: Case found
401: Unauthorized
404: Case not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Update a case

PUT /v1/cases/cases/{id}

Table 18. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Table 19. Request Fields
Field	Type	Required	Description
assigned_worker	UUID (optional)	No	New assigned-worker UUID (transfers a case to another caseworker).
closure_reason	ClosureReason (optional)	No	Closure reason
icwa_flag	boolean (optional)	No	New ICWA flag value.
stage	string (optional)	No	New case stage (`investigation`, `services`, `permanency`, etc.).
status	string (optional)	No	New status (`open`, `closed`, `transferred`).
supervisor	UUID (optional)	No	New supervisor UUID — reassign-only (#1368): absent keeps the current supervisor, a value reassigns, and an explicit JSON `null` is REJECTED with a 422 — no NULL-clear path exists by design. `craig_validation::double_option` makes the null arm visible as `Some(None)` so the handler can refuse it; the `skip_serializing_if` pairing is LOAD-BEARING — without it a Rust-side keep-intent `None` would serialize as an explicit `null` and every typed-client update would 422. Flip both attributes together, never one.

Responses

200: Case updated
400: Invalid status transition
401: Unauthorized
403: Forbidden
404: Case not found
409: Concurrent modification — re-read and retry
422: Validation failure (including an explicit-null supervisor — reassign-only, no NULL-clear path, #1368)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

List household members for a case

GET /v1/cases/cases/{id}/household

Table 20. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Responses

200: Household members
401: Unauthorized
403: Forbidden
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Add a household member to a case

POST /v1/cases/cases/{id}/household

Table 21. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Table 22. Request Fields
Field	Type	Required	Description
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1256) — REQUIRED. Same id + identical intent (including the case path id) replays the original membership row; a different intent under the same id is a 409 `idempotency-conflict`.
person_id	UUID	Yes	UUID of the `persons` row to add to the case household.
primary_caregiver	boolean	No	`true` if this person is the household’s primary caregiver.
role	enum (child, parent, caregiver, sibling, other)	Yes	Role of a person in a case household.

Responses

200: Household member added (or replayed — same client_request_id + intent)
401: Unauthorized
403: Forbidden
404: Case not found
409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)
422: Missing client_request_id
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

CURRENT benefit facts for the case household (#1549, D4)

GET /v1/cases/cases/{id}/ssa-benefit-facts

Table 23. Parameters
Name	In	Required	Description
id	path	Yes	Case ID
person_id	query	No	Narrow to one household member.

Responses

200: Chain heads for the active household (bounded by household size × benefit kinds — unpaginated by construction)
401: Unauthorized
403: Forbidden
404: Case not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Request an SSA screening run for the case household (#1464, ADR-066 §D5)

POST /v1/cases/cases/{id}/ssa-screening

Table 24. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Table 25. Request Fields
Field	Type	Required	Description
client_request_id	UUID	Yes	The client-held operation id (H4): minted per render by the BFF (E1), forwarded UNCHANGED by cases, claimed by exchange.

Responses

202: Screening run staged at exchange (or an idempotent replay of the stored run)
401: Unauthorized
403: Forbidden (incl. pure service callers, unassigned caseworkers, or the exchange-side FEATURE_DISABLED knob relayed verbatim)
404: Case not found
409: No active household members, members without an SSN on file (MISSING_SSN), or an exchange-side refusal relayed verbatim (SCREENING_RUN_ACTIVE / SCREENING_COHORT_STALE / DSA_NOT_ACTIVE)
503: Exchange unreachable, or its partner-configuration 503s relayed verbatim
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Screening-outcome history for the case household (#1549, D4)

GET /v1/cases/cases/{id}/ssa-screening/outcomes

Table 26. Parameters
Name	In	Required	Description
id	path	Yes	Case ID
person_id	query	No	Narrow to one household member (never combined with `run_id`).
run_id	query	No	Narrow to one screening run (never combined with `person_id`).
page	query	No	1-indexed page number (default `1`).
per_page	query	No	Page size (default `25`).

Responses

200: Outcome page (household-scoped)
400: person_id and run_id combined (H12), or page depth exceeded
401: Unauthorized
403: Forbidden
404: Case not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

The case’s latest screening-run status, relayed from exchange (#1549, D4)

GET /v1/cases/cases/{id}/ssa-screening/run

Table 27. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Responses

200: The latest run’s status view
401: Unauthorized
403: Forbidden
404: Case not found, or the case has never staged a screening run (relayed verbatim)
503: Exchange unreachable
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Operator cancel of a screening run (#1466, fork 1)

POST /v1/cases/cases/{id}/ssa-screening/runs/{run_id}/cancel

Table 28. Parameters
Name	In	Required	Description
id	path	Yes	Case ID
run_id	path	Yes	Screening run ID

Responses

200: Invalidated (or the deterministic already-invalidated replay)
401: Unauthorized
403: Forbidden (service tokens denied; BOLA)
404: Case not found, or no such run for this case
409: Quiesced run (fork-2 no-op), relayed verbatim
503: Exchange unavailable
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

The composed SSA section’s one-fetch composite (#1552, E4)

GET /v1/cases/cases/{id}/ssa-screening/summary

Everything the composed case-section renders in one call: the latest run status (relay 404 folds to null — never-screened is a 200 shape, not an error), the CURRENT household benefit facts, and the newest outcome rows. Exchange unreachability is a 503 (the fragment renders its error state).

Table 29. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Responses

200: The composite
401: Unauthorized
403: Forbidden
404: Case not found
500: The relay refused non-404 (an exchange auth/config fault)
503: Exchange unreachable
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Contact Attachments

List contact attachments

GET /v1/cases/cases/{case_id}/contacts/{contact_id}/attachments

Table 30. Parameters
Name	In	Required	Description
case_id	path	Yes	Case ID
contact_id	path	Yes	Contact ID

Responses

200: Attachments list
401: Unauthorized
403: Forbidden
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Upload a contact attachment

POST /v1/cases/cases/{case_id}/contacts/{contact_id}/attachments

Table 31. Parameters
Name	In	Required	Description
case_id	path	Yes	Case ID
contact_id	path	Yes	Contact ID

Responses

200: Attachment uploaded (a byte- and metadata-identical retry under the same client_request_id replays the SAME attachment)
400: Validation error (including a missing client_request_id / file_sha256 text field or a digest that does not match the bytes)
401: Unauthorized
403: Forbidden (including a foreign actor replaying another’s client_request_id)
404: Not found
409: Concurrent retries kept finalizing this upload; retry the request
422: client_request_id reused with a different upload (ADR-062 §U)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Download a contact attachment

GET /v1/cases/cases/{case_id}/contacts/{contact_id}/attachments/{att_id}

Table 32. Parameters
Name	In	Required	Description
case_id	path	Yes	Case ID
contact_id	path	Yes	Contact ID
att_id	path	Yes	Attachment ID

Responses

200: Attachment file
401: Unauthorized
403: Forbidden
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Delete a contact attachment

DELETE /v1/cases/cases/{case_id}/contacts/{contact_id}/attachments/{att_id}

Table 33. Parameters
Name	In	Required	Description
case_id	path	Yes	Case ID
contact_id	path	Yes	Contact ID
att_id	path	Yes	Attachment ID

Responses

204: Attachment deleted
401: Unauthorized
403: Forbidden
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Contacts

List contacts for a case

GET /v1/cases/cases/{id}/contacts

Table 34. Parameters
Name	In	Required	Description
id	path	Yes	Case ID
page	query	No	1-indexed page number (default `1`).
per_page	query	No	Page size (default `25`).

Responses

200: Paginated contacts
401: Unauthorized
403: Forbidden
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Record a contact / visitation

POST /v1/cases/cases/{id}/contacts

Table 35. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Table 36. Request Fields
Field	Type	Required	Description
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1256) — REQUIRED. Same id + identical intent (including the case path id) replays the original contact; a different intent under the same id is a 409 `idempotency-conflict`.
contact_type	enum (home_visit, office_visit, phone_call, video_call, school_visit, collateral)	Yes	Type of case contact.
contact_with	string	Yes	Who was contacted (person name or role).
duration_minutes	integer (optional)	No	Duration of the contact in minutes.
narrative	string (optional)	No	Free-form contact narrative.
occurred_at	datetime	Yes	When the contact occurred (timezone-aware).

Responses

200: Contact recorded (or replayed — same client_request_id + intent)
401: Unauthorized
403: Forbidden
404: Case not found
409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get a contact by ID

GET /v1/cases/contacts/{id}

Table 37. Parameters
Name	In	Required	Description
id	path	Yes	Contact ID

Responses

200: Contact
401: Unauthorized
403: Forbidden
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Update a contact (requires If-Match)

PUT /v1/cases/contacts/{id}

Table 38. Parameters
Name	In	Required	Description
id	path	Yes	Contact ID
If-Match	header	Yes	REQUIRED (#1266): the contact’s `version` from your last read, bare or RFC 7232-quoted (e.g. `"3"`)

Table 39. Request Fields
Field	Type	Required	Description
contact_type	ContactType (optional)	No	Contact type
contact_with	string (optional)	No	New `contact_with` value.
duration_minutes	integer (optional)	No	New duration in minutes.
narrative	string (optional)	No	New narrative.
occurred_at	datetime (optional)	No	New `occurred_at` value.

Responses

200: Contact updated
400: Missing or malformed If-Match
401: Unauthorized
403: Forbidden
404: Not found (including soft-deleted)
409: Version moved — concurrent modification; re-read and retry
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Delete a contact

DELETE /v1/cases/contacts/{id}

Table 40. Parameters
Name	In	Required	Description
id	path	Yes	Contact ID

Responses

204: Contact deleted
401: Unauthorized
403: Forbidden
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Court Orders

Download a court order document

GET /v1/cases/cases/{case_id}/court-orders/{order_id}/document

Table 41. Parameters
Name	In	Required	Description
case_id	path	Yes	Case ID
order_id	path	Yes	Court order ID

Responses

200: Document file
401: Unauthorized
403: Forbidden
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Upload a court order document

POST /v1/cases/cases/{case_id}/court-orders/{order_id}/document

Table 42. Parameters
Name	In	Required	Description
case_id	path	Yes	Case ID
order_id	path	Yes	Court order ID

Responses

200: Document uploaded (a byte-identical retry under the same client_request_id replays; a superseded attempt answers with the CURRENT document — the pointer never regresses)
400: Validation error (including a missing client_request_id / file_sha256 text field or a digest that does not match the bytes)
401: Unauthorized
403: Forbidden (including a foreign actor replaying another’s client_request_id)
404: Not found
409: Concurrent retries kept finalizing this upload; retry the request
422: client_request_id reused with a different upload (ADR-062 §U)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

List court orders for a case

GET /v1/cases/cases/{id}/court-orders

Table 43. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Responses

200: Court orders
401: Unauthorized
403: Forbidden
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Record a court order

POST /v1/cases/cases/{id}/court-orders

Table 44. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Table 45. Request Fields
Field	Type	Required	Description
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1256) — REQUIRED. Same id + identical intent (including the case path id) replays the original order; a different intent under the same id is a 409 `idempotency-conflict`.
court_name	string (optional)	No	Name of the issuing court.
effective_date	date (optional)	No	Date the order takes effect (defaults to `order_date` server-side).
findings	object	No	Judicial findings (e.g. contrary-to-welfare, reasonable-efforts).
judge	string (optional)	No	Presiding judge’s name.
next_hearing_date	date (optional)	No	Date of the next scheduled hearing.
order_date	date	Yes	Date the order was issued.
order_type	enum (removal, shelter_care, adjudication, disposition, review_hearing, permanency_hearing, termination_of_parental_rights)	Yes	Type of court order.

Responses

200: Court order recorded (or replayed — same client_request_id + intent)
401: Unauthorized
403: Forbidden
404: Case not found
409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get a court order by ID

GET /v1/cases/court-orders/{id}

Table 46. Parameters
Name	In	Required	Description
id	path	Yes	Court order ID

Responses

200: Court order
401: Unauthorized
403: Forbidden
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Update a court order (requires If-Match)

PUT /v1/cases/court-orders/{id}

Table 47. Parameters
Name	In	Required	Description
id	path	Yes	Court order ID
If-Match	header	Yes	REQUIRED (#1266): the order’s `version` from your last read, bare or RFC 7232-quoted (e.g. `"3"`)

Table 48. Request Fields
Field	Type	Required	Description
court_name	string (optional)	No	New court name.
effective_date	date (optional)	No	New effective date.
findings	object	No	New findings JSON.
judge	string (optional)	No	New presiding judge.
next_hearing_date	date (optional)	No	New next-hearing date.
order_date	date (optional)	No	New `order_date`.
order_type	CourtOrderType (optional)	No	Order type

Responses

200: Court order updated
400: Missing or malformed If-Match
401: Unauthorized
403: Forbidden
404: Not found (including soft-deleted)
409: Version moved — concurrent modification; re-read and retry
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Delete a court order

DELETE /v1/cases/court-orders/{id}

Table 49. Parameters
Name	In	Required	Description
id	path	Yes	Court order ID

Responses

204: Court order deleted
401: Unauthorized
403: Forbidden
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

IV-E Determination

The case’s latest IV-E determination of record (#1557)

GET /v1/cases/cases/{id}/ive-determination

Table 50. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Responses

200: The latest determination
401: Unauthorized
403: Forbidden
404: Case not found, or no determination exists
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Assemble + persist an IV-E eligibility determination (UD1, #1557)

POST /v1/cases/cases/{id}/ive-determination

The authoritative assembly: verifies the screening witness (completed, un-invalidated, H1-fresh, cohort byte-current), derives the SSA evidence token server-side from CURRENT benefit facts (callers cannot supply it — any ssa_-prefixed input key is refused), evaluates the jurisdiction IV-E ruleset, and persists the determination of record in one claimed transaction that re-validates the witness under the case lock. No money path consumes the record (the #1054 fence; #1313 stays open).

Table 51. Parameters
Name	In	Required	Description
id	path	Yes	Case ID

Table 52. Request Fields
Field	Type	Required	Description
attested_inputs	object	Yes	The worker-entered documented inputs (deprivation type, income, judicial facts, …) — provenance: worker self-attestation, recorded verbatim on the determination row. The SSA witness key (and any `ssa_`-prefixed key) is refused: that evidence is server-derived.
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B) — REQUIRED.

Responses

200: The determination of record (a replay returns the original)
400: Malformed body
401: Unauthorized
403: Forbidden (pure service callers, unassigned caseworkers)
404: Case not found
409: ive-witness-not-current (categorical token in detail: screening-missing | run-pending | run-invalidated | run-stale | cohort-drift | facts-changed), MISSING_SSN / empty-household from the cohort recompute, or an ADR-062 idempotency conflict
422: Validation failure — including an ssa_-prefixed input key (SSA evidence is server-derived; ADR-066 §D7) or a missing client_request_id
500: Internal error (including a ruleset output missing a decision key)
503: Rules evaluation timed out, or exchange unreachable
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Open screening-review worklist items (UD5, #1557)

GET /v1/cases/screening-reviews

Post-determination SSA-signal notifications, scoped by the parent case’s assignment: caseworkers see their own cases' items, supervisors their supervised cases', admins all. One open item per case; occurrences count coalesced triggers.

Table 53. Parameters
Name	In	Required	Description
page	query	No	Page number (1-based).
per_page	query	No	Items per page.

Responses

200: The scoped open items, newest event first
400: Page depth past the cap
401: Unauthorized
403: Forbidden
500: Internal error
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Claim a screening-review item for triage (#1557)

POST /v1/cases/screening-reviews/{id}/assign

Assigns the OPEN item to the acting worker (self-claim; single triage slot — the deliberate v1 asymmetry with dismissal is recorded in the ADR). Naturally idempotent: re-assigning overwrites the slot.

Table 54. Parameters
Name	In	Required	Description
id	path	Yes	Worklist item ID

Responses

200: The item, assigned
401: Unauthorized
403: Forbidden
404: Item (or its case) not found, or already dismissed
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Dismiss a screening-review item, with the audited reason (#1557)

POST /v1/cases/screening-reviews/{id}/dismiss

The human decision that new SSA data does not warrant re-determination: who/when/why land on the row AND on the case.screening_review_dismissed audit event, staged in the same transaction. A dismissed case re-notifies as a NEW item on the next trigger.

Table 55. Parameters
Name	In	Required	Description
id	path	Yes	Worklist item ID

Table 56. Request Fields
Field	Type	Required	Description
reason	string	Yes	Why the new SSA signal does not warrant re-determination — mandatory, recorded in-row AND on the audit event.

Responses

200: The item, dismissed
401: Unauthorized
403: Forbidden
404: Item (or its case) not found, or already dismissed
422: Missing/empty reason
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Investigations

List investigations

GET /v1/cases/investigations

Table 57. Parameters
Name	In	Required	Description
page	query	No	1-indexed page number (default `1`).
per_page	query	No	Page size (default `25`).
worker	query	No	Filter by assigned worker (`claims.sub` UUID, post ADR-025).
status	query	No	Filter by status: open, pending_review, closed.
search	query	No	Full-text search across assignment_area (worker is UUID-typed; substring search disabled).
person_id	query	No	Filter to investigations whose referral has any allegation involving this person (victim or perpetrator).
sort_by	query	No	Sort column: status, response_due_at, assigned_worker, assignment_area.
sort_dir	query	No	Sort direction: asc or desc (default: desc).

Responses

200: Paginated investigations
401: Unauthorized
403: Forbidden
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Open an investigation from a referral

POST /v1/cases/investigations

Table 58. Request Fields
Field	Type	Required	Description
assigned_worker	UUID	Yes	Worker `claims.sub` UUID (post ADR-025 identity normalization).
assignment_area	string	Yes	Geographic or organizational area assignment.
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1255) — REQUIRED. Same id + identical intent replays the original investigation; a different intent under the same id is a 409 `idempotency-conflict`.
referral_id	UUID	Yes	Referral the investigation is opened from.
response_due_at	datetime	Yes	Deadline by which first contact must occur.

Responses

200: Investigation created (or replayed — same client_request_id + intent)
401: Unauthorized
403: Forbidden
404: Referral not found
409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get an investigation by ID

GET /v1/cases/investigations/{id}

Table 59. Parameters
Name	In	Required	Description
id	path	Yes	Investigation ID

Responses

200: Investigation found
401: Unauthorized
404: Investigation not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Update an investigation

PUT /v1/cases/investigations/{id}

Table 60. Parameters
Name	In	Required	Description
id	path	Yes	Investigation ID

Table 61. Request Fields
Field	Type	Required	Description
disposition	Disposition (optional)	No	Disposition
first_contact_at	datetime (optional)	No	Timestamp the investigator first made contact.
status	string (optional)	No	New status: `open`, `pending_review`, `closed`.

Responses

200: Investigation updated
400: Invalid status transition
401: Unauthorized
403: Forbidden
404: Investigation not found
409: Concurrent modification — re-read and retry
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Submit a safety assessment (calls Rules Engine)

POST /v1/cases/investigations/{id}/safety-assessment

Table 62. Parameters
Name	In	Required	Description
id	path	Yes	Investigation ID

Table 63. Request Fields
Field	Type	Required	Description
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1255) — REQUIRED. Same id + identical intent (including the investigation path id) replays the original assessment — the Rules Engine is NOT re-consulted on a replay; a different intent under the same id is a 409 `idempotency-conflict`.
protective_capacities	object	Yes	JSON array of protective capacities (jurisdiction-specific shape).
threats	object	Yes	JSON array of identified safety threats (jurisdiction-specific shape).
worker_override	SafetyDecision (optional)	No	Worker override
worker_override_reason	string (optional)	No	Free-form reason for the override.

Responses

200: Safety assessment recorded (or replayed — same client_request_id + intent; the Rules Engine is not re-consulted on a replay)
401: Unauthorized
403: Forbidden
404: Investigation not found
409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

NCANDS Export

Service-to-service: collect NCANDS Child File rows for a Federal Fiscal Year (#651)

GET /v1/cases/ncands-export

Table 64. Parameters
Name	In	Required	Description
ffy	query	Yes	Federal Fiscal Year (the year the FFY ends in)

Responses

200: Collected rows for the FFY
400: FFY out of range
403: Caller is not the craig-reporting service identity
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Persons

Search persons

GET /v1/cases/persons

Table 65. Parameters
Name	In	Required	Description
page	query	No	1-indexed page number (default `1`).
per_page	query	No	Page size (default `25`).
name	query	No	Search by name (case-insensitive partial match over the full `"first last"` name, so a term may span the first/last boundary — e.g. `"than Smith"` matches `"Johnathan Smithson"`).
date_of_birth	query	No	Filter by exact date of birth.
ssn_last_four	query	No	Filter by last four digits of SSN (exactly four ASCII digits — the blind index hashes raw bytes, so a non-canonical filter could only ever match nothing; #1023 rejects it up front).

Responses

200: Search results
401: Unauthorized
403: Forbidden
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Create a person record

POST /v1/cases/persons

Table 66. Request Fields
Field	Type	Required	Description
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1255) — REQUIRED. Retrying with the same id + identical intent replays the original outcome instead of creating a second person; the same id with a DIFFERENT intent (or another caller’s id) is a 409 `idempotency-conflict`. Mint a fresh UUID per logical operation.
date_of_birth	date (optional)	No	Date of birth, calendar-date precision.
ethnicity	Ethnicity (optional)	No	Ethnicity
first_name	string	Yes	First name.
gender	Gender (optional)	No	Gender
icwa_eligible	boolean	No	`true` when the child meets ICWA eligibility criteria.
last_name	string	Yes	Last name.
race	Race (optional)	No	Race
ssn	string (optional)	No	Full SSN (#1064 / ADR-051) — WRITE-ONLY: never returned by any read surface. Accepts digits with optional space/dash separators; the service canonicalizes, range-validates, derives `ssn_last_four`, and stores ciphertext + blind index. Non-clearable here (the audited `DELETE /persons/{id}/ssn` is the removal path).
ssn_last_four	string (optional)	No	Last 4 digits of SSN (server stores hashed; exactly four ASCII digits, #1023 — non-canonical bytes would poison the blind index). Rejected with `SSN_LAST_FOUR_MANAGED` when a full SSN is on file OR [`Self::ssn`] is also present — the last-four is DERIVED from the full SSN then.
tribal_affiliation	string (optional)	No	Tribe affiliation (free-form, paired with [`Self::icwa_eligible`]).

Responses

200: Person created (or replayed — same client_request_id + intent)
401: Unauthorized
403: Forbidden
409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Service-to-service: person demographics + SSN state for federal reporting (#1064, ADR-051)

POST /v1/cases/persons/federal-export

Table 67. Request Fields
Field	Type	Required	Description
include_full_ssn	boolean	No	When `true`, rows that are `ssn_verified` carry the decrypted full SSN. Unverified SSNs NEVER leave cases through this purpose (a future #162 verification-purpose mode is a distinct, separately-audited exception — ADR-051).
person_ids	array of UUID	Yes	Persons to export (≤ [`FEDERAL_EXPORT_MAX_IDS`]; unknown ids are absent from the response).

Responses

200: Export rows (unknown ids absent); Cache-Control: no-store
400: Over the id cap (BATCH_TOO_LARGE)
403: Caller is not the craig-reporting service identity
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get a person by ID

GET /v1/cases/persons/{id}

Table 68. Parameters
Name	In	Required	Description
id	path	Yes	Person ID

Responses

200: Person found
401: Unauthorized
404: Person not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Update a person record

PUT /v1/cases/persons/{id}

Table 69. Parameters
Name	In	Required	Description
id	path	Yes	Person ID

Table 70. Request Fields
Field	Type	Required	Description
date_of_birth	date (optional)	No	New date of birth.
ethnicity	Ethnicity (optional)	No	Ethnicity
first_name	string (optional)	No	New first name.
gender	Gender (optional)	No	Gender
icwa_eligible	boolean (optional)	No	New ICWA eligibility flag.
last_name	string (optional)	No	New last name.
race	Race (optional)	No	Race
ssn	string (optional)	No	New full SSN (#1064 / ADR-051) — write-only; every write resets the verification state (same-value included, deliberately). Absent = keep; non-clearable here (the audited `DELETE /persons/{id}/ssn` clears).
ssn_last_four	string (optional)	No	New `ssn_last_four` (exactly four ASCII digits, #1023). Rejected with `SSN_LAST_FOUR_MANAGED` when a full SSN is on file OR [`Self::ssn`] is also present (derived then).
tribal_affiliation	string (optional)	No	New tribal affiliation.

Responses

200: Person updated
401: Unauthorized
403: Forbidden
404: Person not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Audited SSN clear — removes all four SSN columns (#1064, ADR-051)

DELETE /v1/cases/persons/{id}/ssn

Table 71. Parameters
Name	In	Required	Description
id	path	Yes	Person ID

Table 72. Request Fields
Field	Type	Required	Description
reason	string	Yes	Why the SSN is being removed.

Responses

200: Cleared — idempotent: a replayed clear on an already-clear row is a no-op and stages no duplicate audit event (#1266)
401: Unauthorized
403: Forbidden (non-admin, incl. pure service callers)
404: Person not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Service-to-service: value-bound SSN custody release for SSA screening (#1463, ADR-065 §D2)

POST /v1/cases/persons/{id}/ssn-release

Table 73. Parameters
Name	In	Required	Description
id	path	Yes	Person ID

Table 74. Request Fields
Field	Type	Required	Description
expected_digest	string	Yes	The staged screening digest in `SsnDigest` canonical `v{n}:{base64}` form (construction-validated; a malformed value dies at the serde boundary as the fleet’s categorical 422 body-rejection).
purpose	enum (ssa_solq_screening)	Yes	The closed purpose vocabulary for the value-bound custody release (#1463 / ADR-065 §D2). Serde refuses unknown tokens (400), so a new purpose is a code change with its own allowlist review — never a free string.
requested_by	UUID	Yes	The caseworker who requested the screening run (the run’s `created_by`, captured from the live actor at stage time).
screening_member_id	UUID	Yes	The screening member this release feeds (`ssa_screening_members.id`).
screening_run_id	UUID	Yes	The requesting screening run (`ssa_screening_runs.id`).

Responses

200: Digest matched — plaintext released (unverified emission permitted for this purpose); Cache-Control: no-store
401: Unauthorized
403: Caller is not the craig-exchange service identity
404: Person not found
409: No SSN on file (MISSING_SSN), staged digest under a rotated-away version (SSN_DIGEST_VERSION_ROTATED), or digest bytes no longer match (SSN_DIGEST_MISMATCH) — each audited, none releasing plaintext
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

SSN verification status + attestation digest (#1064, ADR-051)

GET /v1/cases/persons/{id}/ssn-verification

Table 75. Parameters
Name	In	Required	Description
id	path	Yes	Person ID

Responses

200: Verification status
401: Unauthorized
403: Forbidden (incl. pure service callers)
404: Person not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Attest the stored SSN (value-bound; #1064, ADR-051)

POST /v1/cases/persons/{id}/ssn-verification

Table 76. Parameters
Name	In	Required	Description
id	path	Yes	Person ID

Table 77. Request Fields
Field	Type	Required	Description
digest	string	Yes	The digest the attester reviewed (from the digest GET), in [`SsnDigest`] canonical `v{n}:{base64}` form (construction-validated — a non-canonical value dies at the serde boundary as the fleet’s categorical 422 body-rejection, #1435; was a free-form 1..=500-char String).
method	string	Yes	Evidence source (e.g. `ssa_card`, `shines_record`, `gateway_record`).

Responses

200: Attested — or a replayed same-digest attestation, which is a no-op: the original record stands, nothing is re-stamped (#1266)
401: Unauthorized
403: Forbidden (incl. pure service callers)
404: Person not found
409: No SSN on file (MISSING_SSN), digest stamped under a rotated-away blind-index version (SSN_DIGEST_VERSION_ROTATED — re-fetch, #1435), digest mismatch (STALE_ATTESTATION), or verification state moved concurrently (CONCURRENT_MODIFICATION)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Revoke SSN verification (#1064, ADR-051)

DELETE /v1/cases/persons/{id}/ssn-verification

Table 78. Parameters
Name	In	Required	Description
id	path	Yes	Person ID

Table 79. Request Fields
Field	Type	Required	Description
reason	string	Yes	Why the verification is being revoked.

Responses

200: Revoked — idempotent: a replayed revoke on an already-unverified row is a no-op and stages no duplicate audit event (#1266)
401: Unauthorized
403: Forbidden (incl. pure service callers)
404: Person not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Service-to-service: record one SSA screening member outcome atomically (#1466, ADR-066 §OT)

POST /v1/cases/ssa-screening-outcomes

Table 80. Request Fields
Field	Type	Required	Description
authority	enum (gateway, non_authoritative_stub)	Yes	The caller-asserted send-authority discriminator (see the module doc: defense-in-depth, not a lock).
echo_matched	boolean	Yes	See the module doc — the transient echo assertion.
expected_digest	string	Yes	The digest the run bound — the value-binding the CAS enforces in its own WHERE (a moved digest means facts may still commit but verification never fires).
outcome	object	Yes	The member’s categorical outcome. `Screened` with zero entries is legal (SSA matched the identity but asserted no in-taxonomy benefits) — the projection row is what distinguishes it from `NoMatch`/`Unmappable`, which is why the projection exists.
person_id	UUID	Yes	The person screened.
requested_by	UUID	Yes	Stage-time actor attribution (the run creator’s sub).
run_id	UUID	Yes	The screening run (provenance pointer; validity re-checked exchange-side under the claim fence, carried here for the projection row).
screening_member_id	UUID	Yes	The screening member this outcome resolves.
transaction_id	UUID	Yes	The member’s transaction id — the claim key (see module doc).

Responses

200: Idempotent replay — the ORIGINAL outcome re-derived from the projection row
201: Outcome recorded (facts + optional ssn_verified CAS + projection row, one transaction)
401: Unauthorized
403: Caller is not the craig-exchange service identity
404: Person not found
409: Digest-class refusal (MISSING_SSN / SSN_DIGEST_VERSION_ROTATED / SSN_DIGEST_MISMATCH — zero writes), or a non-Gateway authority (NON_AUTHORITATIVE_SOURCE)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Referrals

List referrals

GET /v1/cases/referrals

Table 81. Parameters
Name	In	Required	Description
page	query	No	1-indexed page number (default `1`).
per_page	query	No	Page size (default `25`).
worker	query	No	Filter by creating worker.
admin_unit	query	No	Filter by administrative unit.
search	query	No	Substring search across the plaintext `reporter_type`, `admin_unit`, and `created_by` (worker) columns — per-column, so a term must match within a single column. The encrypted reporter name/phone columns are opaque ciphertext at rest and are deliberately NOT searchable (ADR-049). LIKE metacharacters are escaped and matched literally.
person_id	query	No	Filter to referrals where this person appears as victim or perpetrator on any allegation.
sort_by	query	No	Sort column: received_at, priority, reporter_type, admin_unit.
sort_dir	query	No	Sort direction: asc or desc (default: desc).

Responses

200: Paginated list of referrals
401: Unauthorized
403: Forbidden
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Create a hotline referral

POST /v1/cases/referrals

Table 82. Request Fields
Field	Type	Required	Description
admin_unit	string	Yes	Administrative unit (county / region) that owns the referral.
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1255) — REQUIRED. Same id + identical intent replays the original referral; a different intent under the same id is a 409 `idempotency-conflict`.
icwa_flag	boolean	No	`true` when ICWA may apply (Native American heritage flag).
priority	enum (immediate, 24_hour, 72_hour)	Yes	Referral/investigation priority level.
reporter_first_name	string (optional)	No	Reporter’s first name (omitted for anonymous referrals).
reporter_last_name	string (optional)	No	Reporter’s last name (omitted for anonymous referrals).
reporter_phone	string (optional)	No	Reporter’s contact phone.
reporter_relation	RelationshipToChild (optional)	No	Reporter relation
reporter_type	enum (mandated, professional, anonymous, self_report, law_enforcement, concerned_citizen)	Yes	Who reported the allegation — NCANDS reporter source.
screen_out_reason	string (optional)	No	Reason given when `screened_in = false`.
screened_in	boolean	No	`true` when the referral is accepted for investigation (default).

Responses

200: Referral created (or replayed — same client_request_id + intent)
401: Unauthorized
403: Forbidden
409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get a referral with its allegations

GET /v1/cases/referrals/{id}

Table 83. Parameters
Name	In	Required	Description
id	path	Yes	Referral ID

Responses

200: Referral found
401: Unauthorized
404: Referral not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Add an allegation to a referral

POST /v1/cases/referrals/{id}/allegations

Table 84. Parameters
Name	In	Required	Description
id	path	Yes	Referral ID

Table 85. Request Fields
Field	Type	Required	Description
abuse_type	enum (physical_abuse, sexual_abuse, neglect, emotional_abuse, medical_neglect)	Yes	Type of maltreatment — the NCANDS maltreatment-type category. Maps to a CRAIG-internal NCANDS short code via [`crate::ncands::abuse_type_to_ncands`]; the literal federal `Mal*Type` codebook values are deferred to export build time (#644).
child_fatality	boolean	No	Whether this maltreatment allegation was fatal to the child — the NCANDS Child File #34 (Maltreatment Death) source. Defaults to `false` when omitted; usually set during the investigation via the update path.
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1255) — REQUIRED. Same id + identical intent (including the referral path id) replays the original allegation; a different intent under the same id is a 409 `idempotency-conflict`.
description	string (optional)	No	Free-form narrative description of the allegation.
disposition	Disposition (optional)	No	Disposition
perpetrator_id	UUID (optional)	No	Person ID of the alleged perpetrator (optional).
victim_id	UUID	Yes	Person ID of the child victim.

Responses

200: Allegation created (or replayed — same client_request_id + intent)
401: Unauthorized
403: Forbidden
404: Referral not found
409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Update an allegation’s maltreatment disposition

PUT /v1/cases/referrals/{id}/allegations/{allegation_id}

Table 86. Parameters
Name	In	Required	Description
id	path	Yes	Referral ID
allegation_id	path	Yes	Allegation ID

Table 87. Request Fields
Field	Type	Required	Description
child_fatality	boolean (optional)	No	Updated child-fatality indicator (NCANDS #34); `None` leaves it unchanged (the fatality determination is often reached during the investigation).
disposition	Disposition (optional)	No	Disposition
version	integer	Yes	The allegation `version` from the caller’s last read — REQUIRED (#1266, ADR-062 §G1 version CAS). The update only applies to a row still at this version; a stale value (a replay, or a lost race against a concurrent disposition write) is a 409 `concurrent-modification` — re-read and re-review, never a silent clobber of a newer disposition.

Responses

200: Allegation updated
401: Unauthorized
403: Forbidden
404: Referral or allegation not found
409: Version moved — concurrent modification; re-read and retry (#1266)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Report Attachments

List attachments for a report

GET /v1/cases/reports/{id}/attachments

Table 88. Parameters
Name	In	Required	Description
id	path	Yes	Report ID

Responses

200: Attachments
404: Report not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Upload an attachment to a report (ADR-018)

POST /v1/cases/reports/{id}/attachments

Table 89. Parameters
Name	In	Required	Description
id	path	Yes	Report ID

Responses

200: Attachment uploaded (a byte- and metadata-identical retry under the same client_request_id replays the SAME attachment)
400: Validation error (too large, disallowed MIME, missing file, missing client_request_id / file_sha256, or a digest that does not match the bytes)
401: Unauthorized
403: Forbidden (including a foreign actor replaying another’s client_request_id)
404: Report not found
409: Concurrent retries kept finalizing this upload; retry the request
422: client_request_id reused with a different upload (ADR-062 §U)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Delete a report attachment (soft-delete + object-store blob removed)

DELETE /v1/cases/reports/{id}/attachments/{att_id}

Table 90. Parameters
Name	In	Required	Description
id	path	Yes	Report ID
att_id	path	Yes	Attachment ID

Responses

204: Deleted
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Download an attachment blob

GET /v1/cases/reports/{id}/attachments/{att_id}/download

Table 91. Parameters
Name	In	Required	Description
id	path	Yes	Report ID
att_id	path	Yes	Attachment ID

Responses

200: Attachment file
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Report Persons

Confirm a person link for a report entry (ADR-019)

POST /v1/cases/reports/{id}/person-links

Table 92. Parameters
Name	In	Required	Description
id	path	Yes	Report ID

Table 93. Request Fields
Field	Type	Required	Description
client_request_id	UUID	Yes	ADR-062 §B (#1257): client-minted idempotency key. REQUIRED — an own-retry with the same key + identical intent replays the stored link (200) instead of tripping the natural-key 409; the `UNIQUE (report_id, person_id, role)` backstop still refuses different-key duplicates.
jsonb_index	integer (optional)	No	Index into the report’s `children[]` or `adults[]` array. Optional for forward-compat — when present, validated against the array length.
person_id	UUID	Yes	UUID of the `craig_cases.persons` row to link.
role	string	Yes	`child` or `adult`.
ruleset_name	string (optional)	No	`Some(name + version)` when the worker confirmed a suggestion; `None` when the worker bypassed via "Link existing person" picker. The orchestration layer’s audit signal that no rules ran.
ruleset_version	string (optional)	No	Companion to [`Self::ruleset_name`] — version string of the ruleset that produced the confirmed suggestion.

Responses

200: Link created (or replayed — same client_request_id + intent)
400: Bogus role or jsonb_index
401: Unauthorized
403: Forbidden
404: Report or person not found
409: Natural-key duplicate under a DIFFERENT client_request_id, a client_request_id claimed by a different operation, or a replayed entity gone (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Unlink a person from a report entry (ADR-019)

DELETE /v1/cases/reports/{id}/person-links/{link_id}

Table 94. Parameters
Name	In	Required	Description
id	path	Yes	Report ID
link_id	path	Yes	report_persons row ID

Responses

200: Link removed
401: Unauthorized
403: Forbidden
404: Link not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Rank candidate persons per child/adult JSONB entry (ADR-019)

GET /v1/cases/reports/{id}/person-suggestions

Table 95. Parameters
Name	In	Required	Description
id	path	Yes	Report ID
seed_case_id	query	No	Optional case id whose `case_household` joins the candidate seed when the active jurisdiction’s ruleset declares `case_household` in `metadata.seed_sources`. Omitted → degraded mode for that source (zero contribution).

Responses

200: Ranked candidates per entry
401: Unauthorized
403: Forbidden
404: Report not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Reports

List reports (summary projection)

GET /v1/cases/reports

Table 96. Parameters
Name	In	Required	Description
page	query	No	1-indexed page number (default `1`).
per_page	query	No	Page size (default `25`).
partner_id	query	No	Filter by submitting partner UUID.
admin_unit	query	No	Filter by administrative unit (county / region).
person_id	query	No	Filter to reports that have at least one `report_persons` link to this person id.
search	query	No	Substring search over the plaintext `admin_unit` + `reporter_type` columns. The encrypted `narrative` and reporter-name columns are opaque ciphertext at rest and are deliberately NOT searchable (ADR-049) — under `EncryptionMode=Required` a search over them would silently match nothing.
sort_by	query	No	Sort column: received_at, admin_unit, reporter_type.
sort_dir	query	No	Sort direction: asc or desc (default: desc).

Responses

200: Paginated report summaries (#1158): six keys per item — id, received_at, reporter_type, reporter_relation, admin_unit, narrative_preview (first 160 chars + U+2026 iff truncated). The full report shape is detail-GET / create-echo only.
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Submit a report (service-to-service; called by craig-intake after partner auth)

POST /v1/cases/reports

Table 97. Request Fields
Field	Type	Required	Description
admin_unit	string	Yes	Administrative unit owning the report.
adults	object	No	JSONB array of `Adult` entries (PII; server stores encrypted).
children	object	No	JSONB array of `Child` entries (PII; server stores encrypted).
narrative	string	Yes	Free-text narrative (PII; server stores encrypted).
partner_context	object	Yes	Tagged-enum form: `{"type":"anonymous"}` or `{"type":"authenticated","id":"<uuid>"}`. Cases-side handler maps `Anonymous` → `partner_id = NULL` and `Authenticated{id}` → `partner_id = id`. Authz is unaffected (it keys on per-record fields populated by Plan A). Audit attribution is unaffected (it keys on `claims.sub` via Plan E).
raw_submission	object	Yes	Verbatim partner payload for audit/replay.
received_ip_hash	string (optional)	No	HMAC-SHA256 hash of the originating IP (Plan B F-003).
received_request_id	UUID	Yes	Idempotency key surfaced from the intake edge. UNIQUE per submission.
reporter_first_name	string (optional)	No	Reporter’s first name (PII; server stores encrypted per Plan B F-001).
reporter_last_name	string (optional)	No	Reporter’s last name (PII; server stores encrypted).
reporter_phone	string (optional)	No	Reporter’s phone (PII; server stores encrypted).
reporter_relation	RelationshipToChild (optional)	No	Reporter relation
reporter_type	enum (mandated, professional, anonymous, self_report, law_enforcement, concerned_citizen)	Yes	Who reported the allegation — NCANDS reporter source.

Responses

200: Report submitted (or replayed — duplicate received_request_id with a matching intent digest, or a grandfathered pre-#1257 row)
409: Duplicate received_request_id with a DIFFERENT intent digest (ADR-062 LIFETIME class)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get a report with its effective disposition and follow-ups

GET /v1/cases/reports/{id}

Table 98. Parameters
Name	In	Required	Description
id	path	Yes	Report ID

Responses

200: Report found
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Convert a screened-in report into a referral (internal cases-side transition)

POST /v1/cases/reports/{id}/convert

Table 99. Parameters
Name	In	Required	Description
id	path	Yes	Report ID

Table 100. Request Fields
Field	Type	Required	Description
icwa_flag	boolean	No	`true` when ICWA may apply.
priority	enum (immediate, 24_hour, 72_hour)	Yes	Referral/investigation priority level.
seed_case_id	UUID (optional)	No	Optional case id whose household persons join the auto-link candidate seed set.

Responses

200: Referral created (idempotent: returns the existing referral if already converted). Person auto-link runs ASYNC via the case.report_converted consumer (ADR-062 §G4) — 200 means the referral committed; links land shortly after.
400: Invalid priority or report not in a convertible disposition
404: Report not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

List the full decision chain for a report, newest first

GET /v1/cases/reports/{id}/decisions

Table 101. Parameters
Name	In	Required	Description
id	path	Yes	Report ID

Responses

200: Decision chain
404: Not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Record a screening decision (initial or override)

POST /v1/cases/reports/{id}/screening-decisions

Table 102. Parameters
Name	In	Required	Description
id	path	Yes	Report ID

Table 103. Request Fields
Field	Type	Required	Description
actor_role	string	Yes	Role of the worker recording the decision (`screener`, `supervisor`, etc.).
client_request_id	UUID	Yes	ADR-062 §B (#1257): client-minted idempotency key. REQUIRED — a retry with the same key + identical intent replays the first execution’s decision instead of appending to the chain.
disposition_kind	string	Yes	Decision outcome (`accept_for_investigation`, `screen_out`, etc.).
rationale	string (optional)	No	Free-form rationale text.
supersedes_id	UUID (optional)	No	If overriding a prior decision, the decision_id being superseded.

Responses

200: Decision recorded (or replayed — same client_request_id + intent)
400: Invalid role/kind or unauthorized override
404: Report not found
409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

List follow-up actions attached to a specific decision

GET /v1/cases/reports/{id}/screening-decisions/{decision_id}/follow-ups

Table 104. Parameters
Name	In	Required	Description
id	path	Yes	Report ID
decision_id	path	Yes	Screening decision ID

Responses

200: Follow-ups for decision
404: Decision not found
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Attach a follow-up action (external referral, LE assist, info packet) to a decision

POST /v1/cases/reports/{id}/screening-decisions/{decision_id}/follow-ups

Table 105. Parameters
Name	In	Required	Description
id	path	Yes	Report ID
decision_id	path	Yes	Screening decision ID

Table 106. Request Fields
Field	Type	Required	Description
action_kind	string	Yes	Action kind (`schedule_contact`, `request_records`, etc.).
client_request_id	UUID	Yes	ADR-062 §B (#1257): client-minted idempotency key. REQUIRED — a retry with the same key + identical intent replays the first execution’s follow-up instead of recording it twice.
notes	string (optional)	No	Free-form notes.
target	string (optional)	No	Optional target entity (person UUID, agency, etc.).

Responses

200: Follow-up recorded (or replayed — same client_request_id + intent)
400: Invalid action_kind
404: Decision not found
409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)
422: Validation failure (including a missing client_request_id)
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Search Capabilities

Advertise per-entity, per-field search capabilities

GET /v1/cases/_meta/search-capabilities

Responses

200: Advertised capabilities for every entity: effective-scheme capability intersected with the entity descriptor’s declared operations
401: Unauthorized
503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.
504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Edit this page · latest