Skip to main content

Assistance Applications API Reference

Submit and track applications for benefit and assistance programs, including disaster assistance intake.

Benefits & assistanceIntakev1.0.0OpenAPI 3.1

Accepts applications from web, mobile, call-center, and partner channels, validates them against program rules, and hands eligible applications to case management. Applicant personal data is held in the system of record and referenced by opaque IDs in API responses.

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/applications/v1 Iron Brick sandbox (synthetic data; free developer account)
  • https://{agency-gateway}/applications/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
applications:readRead applications
applications:writeSubmit and withdraw applications

POST /applications

Submit an application · requires scope applications:write

Creates an application. Use an Idempotency-Key so retries never create duplicates.

Parameters
NameInTypeDescription
Idempotency-Key requiredheaderstringUnique key per submission attempt.
Request body application/json
json
{
  "programCode": "IA-HOUSING",
  "channel": "web",
  "declarationId": "DR-4790",
  "applicantRef": "APL-7f3c21",
  "answers": {
    "householdSize": 3,
    "primaryResidence": true
  }
}
Responses
201Application accepted
400Invalid request
401Missing or invalid access token
403Caller lacks the required scope
409Conflict (duplicate or stale version)
422Business rule violation
Example request
curl -X POST "https://dev.ironbrick.us/sandbox/applications/v1/applications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 7" \
  -H "Content-Type: application/json" \
  -d '{"programCode": "IA-HOUSING", "channel": "web", "declarationId": "DR-4790", "applicantRef": "APL-7f3c21", "answers": {"householdSize": 3, "primaryResidence": true}}'
Response 201
{
  "applicationId": "APP-2026-118204",
  "programCode": "IA-HOUSING",
  "status": "validating",
  "submittedAt": "2026-09-12T09:41:00Z",
  "channel": "web",
  "declarationId": "DR-4790",
  "applicantRef": "APL-7f3c21",
  "caseId": "CASE-2026-004817"
}

GET /applications

List applications · requires scope applications:read

Parameters
NameInTypeDescription
programCodequerystring
statusquerystring
cursorquerystringPagination cursor from a previous response.
limitqueryintegerMaximum items to return.
Responses
200A page of applications
401Missing or invalid access token
403Caller lacks the required scope
Example request
curl -X GET "https://dev.ironbrick.us/sandbox/applications/v1/applications" \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "data": [
    {
      "applicationId": "APP-2026-118204",
      "programCode": "IA-HOUSING",
      "status": "validating",
      "submittedAt": "2026-09-12T09:41:00Z",
      "channel": "web",
      "declarationId": "DR-4790",
      "applicantRef": "APL-7f3c21",
      "caseId": "CASE-2026-004817"
    }
  ],
  "page": {
    "nextCursor": "eyJvZmZzZXQiOjUwfQ",
    "limit": 50
  }
}

GET /applications/{applicationId}

Get an application · requires scope applications:read

Parameters
NameInTypeDescription
applicationId requiredpathstringApplication identifier.
Responses
200The application
401Missing or invalid access token
403Caller lacks the required scope
404Resource not found
Example request
curl -X GET "https://dev.ironbrick.us/sandbox/applications/v1/applications/{applicationId}" \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "applicationId": "APP-2026-118204",
  "programCode": "IA-HOUSING",
  "status": "validating",
  "submittedAt": "2026-09-12T09:41:00Z",
  "channel": "web",
  "declarationId": "DR-4790",
  "applicantRef": "APL-7f3c21",
  "caseId": "CASE-2026-004817"
}

GET /applications/{applicationId}/status

Get applicant-facing status · requires scope applications:read

Plain-language status suitable for applicant portals and call-center scripts.

Parameters
NameInTypeDescription
applicationId requiredpathstringApplication identifier.
Responses
200Status
401Missing or invalid access token
403Caller lacks the required scope
404Resource not found
Example request
curl -X GET "https://dev.ironbrick.us/sandbox/applications/v1/applications/{applicationId}/status" \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "status": "validating",
  "message": "We received your application and are checking your information.",
  "nextStep": "No action needed. We will contact you if we need more information."
}

POST /applications/{applicationId}/withdraw

Withdraw an application · requires scope applications:write

Parameters
NameInTypeDescription
applicationId requiredpathstringApplication identifier.
Responses
200Withdrawn application
401Missing or invalid access token
403Caller lacks the required scope
404Resource not found
422Business rule violation
Example request
curl -X POST "https://dev.ironbrick.us/sandbox/applications/v1/applications/{applicationId}/withdraw" \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "applicationId": "APP-2026-118204",
  "programCode": "IA-HOUSING",
  "status": "validating",
  "submittedAt": "2026-09-12T09:41:00Z",
  "channel": "web",
  "declarationId": "DR-4790",
  "applicantRef": "APL-7f3c21",
  "caseId": "CASE-2026-004817"
}

Schemas

Application

FieldTypeDescription
applicationIdstring
programCodestring
statusstring (submitted | validating | eligible | ineligible | awarded | withdrawn)
submittedAtstring (date-time)
channelstring (web | mobile | call_center | in_person)
declarationIdstring
applicantRefstringOpaque reference to the applicant record; never a direct identifier.
caseIdstring