{
  "openapi": "3.1.0",
  "info": {
    "title": "Assistance Applications API",
    "version": "1.0.0",
    "description": "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.\n\nReference 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.",
    "contact": {
      "name": "Iron Brick LLC",
      "email": "info@ironbrick.us",
      "url": "https://dev.ironbrick.us"
    }
  },
  "servers": [
    {
      "url": "https://dev.ironbrick.us/sandbox/applications/v1",
      "description": "Iron Brick sandbox (synthetic data; free developer account)"
    },
    {
      "url": "https://{agency-gateway}/applications/v1",
      "description": "Agency deployment (behind the agency API gateway)"
    }
  ],
  "security": [
    {
      "oauth2": [
        "applications:read",
        "applications:write"
      ]
    }
  ],
  "paths": {
    "/applications": {
      "post": {
        "operationId": "submitApplication",
        "summary": "Submit an application",
        "tags": [
          "Applications"
        ],
        "description": "Creates an application. Use an `Idempotency-Key` so retries never create duplicates.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique key per submission attempt."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "programCode",
                  "channel",
                  "applicantRef"
                ],
                "properties": {
                  "programCode": {
                    "type": "string"
                  },
                  "channel": {
                    "type": "string"
                  },
                  "declarationId": {
                    "type": "string"
                  },
                  "applicantRef": {
                    "type": "string"
                  },
                  "answers": {
                    "type": "object",
                    "description": "Program-specific answers, validated against the program schema."
                  }
                }
              },
              "example": {
                "programCode": "IA-HOUSING",
                "channel": "web",
                "declarationId": "DR-4790",
                "applicantRef": "APL-7f3c21",
                "answers": {
                  "householdSize": 3,
                  "primaryResidence": true
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Application accepted",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Application"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Caller lacks the required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict (duplicate or stale version)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Business rule violation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listApplications",
        "summary": "List applications",
        "tags": [
          "Applications"
        ],
        "parameters": [
          {
            "name": "programCode",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Pagination cursor from a previous response."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            },
            "description": "Maximum items to return."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of applications",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Application"
                      }
                    },
                    "page": {
                      "$ref": "#/components/schemas/Page"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Caller lacks the required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/applications/{applicationId}": {
      "get": {
        "operationId": "getApplication",
        "summary": "Get an application",
        "tags": [
          "Applications"
        ],
        "parameters": [
          {
            "name": "applicationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Application identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "The application",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Application"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Caller lacks the required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/applications/{applicationId}/status": {
      "get": {
        "operationId": "getApplicationStatus",
        "summary": "Get applicant-facing status",
        "tags": [
          "Applications"
        ],
        "description": "Plain-language status suitable for applicant portals and call-center scripts.",
        "parameters": [
          {
            "name": "applicationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Application identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "Status",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "validating"
                    },
                    "message": {
                      "type": "string",
                      "example": "We received your application and are checking your information."
                    },
                    "nextStep": {
                      "type": "string",
                      "example": "No action needed. We will contact you if we need more information."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Caller lacks the required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/applications/{applicationId}/withdraw": {
      "post": {
        "operationId": "withdrawApplication",
        "summary": "Withdraw an application",
        "tags": [
          "Applications"
        ],
        "parameters": [
          {
            "name": "applicationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Application identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "Withdrawn application",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Application"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Caller lacks the required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Business rule violation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 client credentials for system-to-system calls. Agency deployments federate with the agency identity provider (PIV/CAC-backed for user-delegated access).",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://dev.ironbrick.us/oauth/token",
            "scopes": {
              "applications:read": "Read applications",
              "applications:write": "Submit and withdraw applications"
            }
          }
        }
      }
    },
    "headers": {
      "X-Request-Id": {
        "description": "Unique request identifier; include it when contacting support.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "requestId"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "validation_error"
          },
          "message": {
            "type": "string",
            "example": "status must be one of: received, in_review, decided, closed"
          },
          "requestId": {
            "type": "string",
            "format": "uuid",
            "example": "3f1c9a52-7c1e-4f3e-9d2a-0b8e5f6a1c44"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "Page": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true,
            "example": "eyJvZmZzZXQiOjUwfQ"
          },
          "limit": {
            "type": "integer",
            "example": 50
          }
        }
      },
      "Application": {
        "type": "object",
        "properties": {
          "applicationId": {
            "type": "string",
            "example": "APP-2026-118204"
          },
          "programCode": {
            "type": "string",
            "example": "IA-HOUSING"
          },
          "status": {
            "type": "string",
            "enum": [
              "submitted",
              "validating",
              "eligible",
              "ineligible",
              "awarded",
              "withdrawn"
            ],
            "example": "validating"
          },
          "submittedAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-12T09:41:00Z"
          },
          "channel": {
            "type": "string",
            "enum": [
              "web",
              "mobile",
              "call_center",
              "in_person"
            ],
            "example": "web"
          },
          "declarationId": {
            "type": "string",
            "nullable": true,
            "example": "DR-4790"
          },
          "applicantRef": {
            "type": "string",
            "description": "Opaque reference to the applicant record; never a direct identifier.",
            "example": "APL-7f3c21"
          },
          "caseId": {
            "type": "string",
            "nullable": true,
            "example": "CASE-2026-004817"
          }
        }
      }
    }
  }
}