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.
New here? Start with the Executive Summary for a one-page overview, or view the Toolkit Overview presentation for a detailed walkthrough.
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 Zodios TypeScript clients |
npm run clients:validate |
Type-check generated clients |
npm run postman:generate |
Generate Postman collection |
npm run mock:reset |
Reset database to example data |
npm test |
Run unit tests |
npm run test:integration |
Run integration tests (includes Postman/newman) |
- 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