Skip to main content

Case Management API Reference

Read and update case records, status history, and linked documents in the agency case system of record.

Case managementSystem of recordv1.0.0OpenAPI 3.1

Exposes the agency case management system through a governed, versioned API. Supports case lookup, status transitions with full history, and linking of documents and notes. Every call is authorized against the caller's scopes and recorded in the Audit Log API.

Reference design by Iron Brick LLC. Not an official government system; endpoints and data models are adapted to each agency's systems of record during implementation.

Base URLs
  • https://dev.ironbrick.us/sandbox/cases/v1 Iron Brick sandbox (synthetic data; free developer account)
  • https://{agency-gateway}/cases/v1 Agency deployment (behind the agency API gateway)

OpenAPI YAML JSON

Authentication

Send an OAuth 2.0 bearer token from POST https://dev.ironbrick.us/oauth/token in the Authorization header. Your application must hold the scope listed on each operation. How authentication works.

ScopeGrants
cases:readRead case records and history
cases:writeUpdate case status and notes

GET /cases

Search cases · requires scope cases:read

Returns cases matching the filters, newest first. Results contain no personal identifiers beyond party IDs.

Parameters
NameInTypeDescription
statusquerystringFilter by status.
caseTypequerystringFilter by case type.
updatedSincequerystringOnly cases updated at or after this time.
cursorquerystringPagination cursor from a previous response.
limitqueryintegerMaximum items to return.
Responses
200A page of cases
400Invalid request
401Missing or invalid access token
403Caller lacks the required scope
429Rate limit exceeded
Example request
curl -X GET "https://dev.ironbrick.us/sandbox/cases/v1/cases" \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "data": [
    {
      "caseId": "CASE-2026-004817",
      "caseType": "benefit_request",
      "status": "in_review",
      "priority": "standard",
      "receivedDate": "2026-08-14",
      "office": "Field Office 12",
      "lastUpdated": "2026-09-30T14:22:05Z",
      "version": 7
    }
  ],
  "page": {
    "nextCursor": null,
    "limit": 50
  }
}

GET /cases/{caseId}

Get a case · requires scope cases:read

Parameters
NameInTypeDescription
caseId requiredpathstringCase identifier.
Responses
200The case
401Missing or invalid access token
403Caller lacks the required scope
404Resource not found
Example request
curl -X GET "https://dev.ironbrick.us/sandbox/cases/v1/cases/CASE-2026-004817" \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "caseId": "CASE-2026-004817",
  "caseType": "benefit_request",
  "status": "in_review",
  "priority": "standard",
  "receivedDate": "2026-08-14",
  "office": "Field Office 12",
  "assignedTo": "adjudicator-0442",
  "partyIds": [
    "PTY-88120"
  ],
  "lastUpdated": "2026-09-30T14:22:05Z",
  "version": 7
}

PATCH /cases/{caseId}

Change case status · requires scope cases:write

Applies a status transition. Invalid transitions return 422. Requires If-Match with the current version.

Parameters
NameInTypeDescription
caseId requiredpathstringCase identifier.
If-Match requiredheaderstringCurrent case version.
Request body application/json
json
{
  "status": "decided",
  "reasonCode": "approved",
  "note": "All evidence received."
}
Responses
200Updated case
400Invalid request
401Missing or invalid access token
403Caller lacks the required scope
404Resource not found
409Conflict (duplicate or stale version)
422Business rule violation
Example request
curl -X PATCH "https://dev.ironbrick.us/sandbox/cases/v1/cases/CASE-2026-004817" \
  -H "Authorization: Bearer $TOKEN" \
  -H "If-Match: 7" \
  -H "Content-Type: application/json" \
  -d '{"status": "decided", "reasonCode": "approved", "note": "All evidence received."}'
Response 200
{
  "caseId": "CASE-2026-004817",
  "caseType": "benefit_request",
  "status": "in_review",
  "priority": "standard",
  "receivedDate": "2026-08-14",
  "office": "Field Office 12",
  "assignedTo": "adjudicator-0442",
  "partyIds": [
    "PTY-88120"
  ],
  "lastUpdated": "2026-09-30T14:22:05Z",
  "version": 7
}

GET /cases/{caseId}/events

Get case history · requires scope cases:read

Chronological status and activity history for a case.

Parameters
NameInTypeDescription
caseId requiredpathstringCase identifier.
cursorquerystringPagination cursor from a previous response.
limitqueryintegerMaximum items to return.
Responses
200Case events
401Missing or invalid access token
403Caller lacks the required scope
404Resource not found
Example request
curl -X GET "https://dev.ironbrick.us/sandbox/cases/v1/cases/CASE-2026-004817/events" \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "data": [
    {
      "eventId": "EVT-77311",
      "caseId": "CASE-2026-004817",
      "type": "status_changed",
      "from": "received",
      "to": "in_review",
      "actor": "adjudicator-0442",
      "occurredAt": "2026-09-30T14:22:05Z"
    }
  ],
  "page": {
    "nextCursor": "eyJvZmZzZXQiOjUwfQ",
    "limit": 50
  }
}

GET /cases/{caseId}/documents

List linked documents · requires scope cases:read

Document references linked to the case. Retrieve content through the Document Services API.

Parameters
NameInTypeDescription
caseId requiredpathstringCase identifier.
Responses
200Linked documents
401Missing or invalid access token
403Caller lacks the required scope
404Resource not found
Example request
curl -X GET "https://dev.ironbrick.us/sandbox/cases/v1/cases/CASE-2026-004817/documents" \
  -H "Authorization: Bearer $TOKEN"
Response 200
[
  {
    "documentId": "DOC-551920",
    "category": "supporting_evidence",
    "linkedAt": "2026-10-01T12:00:00Z"
  }
]

Schemas

Error

FieldTypeDescription
code requiredstring
message requiredstring
requestId requiredstring (uuid)
detailsarray of object

Page

FieldTypeDescription
nextCursorstring
limitinteger

Case

FieldTypeDescription
caseId requiredstring
caseType requiredstring
status requiredstring (received | in_review | rfe_issued | decided | closed)
prioritystring (standard | expedited)
receivedDate requiredstring (date)
officestring
assignedTostring
partyIdsarray of string
lastUpdatedstring (date-time)
versionintegerOptimistic-concurrency version; send in If-Match when updating.

CaseEvent

FieldTypeDescription
eventIdstring
caseIdstring
typestring (status_changed | note_added | document_linked | assigned)
fromstring
tostring
actorstring
occurredAtstring (date-time)