This toolkit helps teams build consistent, well-documented APIs for safety net programs—enabling faster integration between benefits systems and reducing the technical barriers to improving service delivery.
This is an evolving repository where Code for America stores integrated benefits API specifications for the different states we work with. The specifications are built on a common data model that captures the core concepts shared across safety net programs—applications, households, income, eligibility—while allowing for state-specific variations in terminology, program names, and data requirements.
Choose your path based on your role:
| Role | You want to... | Start here |
|---|---|---|
| Backend Developer | Design APIs, validate specs, test backend implementations | Backend Developer Guide |
| Frontend Developer | Build UIs against the APIs, use generated clients | Frontend Developer Guide |
npm install
# Set your state
export STATE=california
# Start mock server + Swagger UI
npm startVisit http://localhost:3000 for interactive API docs.
| Command | Description |
|---|---|
npm start |
Start mock server + Swagger UI |
npm run validate |
Validate base specs |
npm run validate:state |
Validate specs for current STATE |
npm run validate:all-states |
Validate all states |
npm run clients:generate |
Generate TypeScript clients |
npm run postman:generate |
Generate Postman collection |
npm run mock:reset |
Reset database to example data |
npm test |
Run unit tests |
- Creating APIs — Design new API specifications
- State Overlays — Work with state-specific variations
- Validation — Validate specs and fix errors
- Mock Server — Run and query the mock server
- Search Patterns — Search and filter syntax
- CI/CD for Backend — Contract test your API implementation
- CI/CD for Frontend — Build and test frontend apps
- API Clients — Use generated TypeScript clients
- Commands — All available npm scripts
- Project Structure — File layout and conventions
- Troubleshooting — Common issues and solutions
Node.js >= 18.0.0