Safety Net Blueprint — Intake Service API

REST API for managing public assistance applications. Covers the full intake lifecycle: applications, household members, household data, income, jobs, assets, expenses, health plans, health enrollments, contacts, organizations, person relationships, authorized representatives, tax filers, sponsors, signatures, verifications, and interviews.

Status: Alpha — Breaking changes expected.

Base URL: https://api.example.com/intake

Applications

Manage public assistance applications.

▶ GET /applications List applications #

Retrieve a paginated list of applications.

Parameters

Name Type In Req Description

▶q string query Search query using field:value syntax. Multiple conditions separated by

Search query using field:value syntax. Multiple conditions separated by spaces are ANDed together.

URL Encoding: This parameter must be URL-encoded when sent over HTTP. Most HTTP clients handle this automatically. Examples in this documentation show human-readable syntax for clarity.

Syntax

Pattern	Description	Example
`term`	Full-text exact match	`john`
`term`	Full-text contains	`john`
`term*`	Full-text starts with	`john*`
`*term`	Full-text ends with	`*smith`
`field:value`	Exact match on field	`status:approved`
`field:value`	Contains (case-insensitive)	`name:john`
`field:value*`	Starts with	`name:john*`
`field:*value`	Ends with	`email:*@example.com`
`field:"value"`	Quoted value (for spaces)	`name:"john doe"`
`field.nested:value`	Nested field (dot notation)	`address.state:CA`
`field:>value`	Greater than	`income:>1000`
`field:>=value`	Greater than or equal	`income:>=1000`
`field:<value`	Less than	`income:<5000`
`field:<=value`	Less than or equal	`income:<=5000`
`field:val1,val2`	Match any value (OR)	`status:approved,pending`
`-field:value`	Exclude / negate	`-status:denied`
`field:*`	Field exists (not null)	`email:*`
`-field:*`	Field does not exist	`-deletedAt:*`

Examples

john — exact match for "john" in searchable fields
john — contains "john" in searchable fields
name:smith — name contains "smith" (case-insensitive)
email:*@example.com — email ends with "@example.com"
status:approved — exact match on status field
status:approved,pending — status is "approved" OR "pending"
income:>=1000 — income greater than or equal to 1000
created:>2024-01-01 — created after January 1, 2024
status:approved income:>=1000 — approved AND income >= 1000 (multiple conditions)
-status:denied — exclude records with status "denied"
-deletedAt:* — only records where deletedAt does not exist
applicant.state:CA — nested field filter

URL Encoding Reference

When manually constructing URLs, encode these characters:

Character	Encoded
(space)	`%20` or `+`
`"`	`%22`
`:`	`%3A`
`>`	`%3E`
`<`	`%3C`
`,`	`%2C`

Example: `` Human-readable: q=status:approved income:>=1000 URL-encoded: q=status%3Aapproved%20income%3A%3E%3D1000 ``

limit

integer

query

Maximum number of items to return (1-100).

offset

integer

query

Number of items to skip before collecting results.

▶sort string query Comma-separated list of fields to sort the response by. Prefix a field

Comma-separated list of fields to sort the response by. Prefix a field with - for descending order. The first field is the primary sort; subsequent fields are tie-breakers in declaration order.

URL Encoding: This parameter must be URL-encoded when sent over HTTP. Most HTTP clients handle this automatically. Examples below show human-readable syntax for clarity.

Which fields a given list endpoint allows is declared in the operation's x-sortable.fields extension. Sending a field name not present in that list returns 400 FIELD_NOT_SORTABLE. Sending a field name that doesn't exist on the resource schema returns 400 INVALID_SORT_FIELD. When this parameter is omitted, the operation's x-sortable.default (if declared) is applied; otherwise no client-driven sort is applied. A configured tie-breaker (default id) is always appended for stable pagination.

See api-patterns.yaml#sorting for the full convention and docs/architecture/x-extensions.md for the extension shape.

Syntax

Pattern	Description	Example
`fieldName`	Ascending	`sort=createdAt`
`-fieldName`	Descending	`sort=-createdAt`
`field1,field2`	Multi-field	`sort=status,-priority`
`nested.field`	Nested field via dot notation	`sort=name.lastName`

Examples

sort=createdAt — oldest first
sort=-createdAt — newest first
sort=-priority,dueDate — highest priority first, then oldest due date
sort=name.lastName,name.firstName — alphabetical by surname, then given name

Responses

200 A paginated collection of applications.

▶ ApplicationList

total integer required Total number of items available.

limit integer required Maximum number of items requested.

offset integer required Number of items skipped before the current page.

hasNext boolean Whether more items are available beyond the current page.

▶ items array[Application] required

programsAppliedFor array[string] Programs the household is applying for. At least one required at submission.

channel string How the application was filed.

enumonline in_person phone mail

▶ ebt Ebt EBT card preferences collected at the application level.

needsCard boolean Whether the household needs a new EBT card issued.

deliveryPreference string How the household prefers to receive their EBT card.

enumby_mail in_person

registerToVote boolean Whether any household member would like to register to vote.

deniesIevsConsent boolean Whether the household denies consent for IEVS income verification.

▶ expeditedSnap ExpeditedSnap Financial information used for the SNAP expedited processing screening at application submission (7 CFR § 273.2(i)). This data is collected once and passed to the eligibility adapter; it is not updated during caseworker review.

totalMoneyExpectedThisMonth number (float) Total money the household expects to receive this month from all sources.

totalCashOnHand number (float) Total cash on hand and in bank accounts available to the household.

monthlyMortgage number (float) Monthly mortgage payment. Used in the expedited screening shelter cost calculation.

monthlyRent number (float) Monthly rent payment. Used in the expedited screening shelter cost calculation.

monthlyUtilities number (float) Monthly utility costs. Used in the expedited screening shelter cost calculation.

receivedSnapInLast30Days boolean Whether the household received SNAP benefits in the last 30 days. Affects expedited eligibility under 7 CFR § 273.2(i).

▶ utilities Utilities Utility information at the application level. Used to determine which SNAP standard utility allowance (SUA) applies. States set their own SUA amounts; the method of heating/cooling determines which SUA tier the household qualifies for (7 CFR § 273.9(d)(6)).

heatCoolMethod string Primary method used to heat or cool the home. Determines which utility standard applies.

enumgas electric oil propane other

heatCoolMethodOther string Free-text description when heatCoolMethod is other.

receivesLiheap boolean Whether the household receives Low Income Home Energy Assistance Program (LIHEAP) benefits. Households receiving LIHEAP may be eligible for the full SUA.

id string (uuid) required read-only Unique identifier for the application.

status string required read-only Current lifecycle status of the application.

enumdraft submitted under_review pending_approval withdrawn closed

isExpedited boolean read-only Whether the application qualifies for expedited processing (e.g., SNAP 7-day track). Set during caseworker expedited screening after submission. Null until screening is complete.

submittedAt string (date-time) read-only When the application was formally submitted. Null until submitted.

withdrawnAt string (date-time) read-only When the application was withdrawn. Null unless withdrawn.

closedAt string (date-time) read-only When the intake phase closed. Null until closed.

createdAt string (date-time) required read-only When the application record was created.

updatedAt string (date-time) required read-only When the application record was last modified.

_links object read-only Generated composition links.

applicationReview object Link to the applicationReview composition.

href string (uri-reference) read-only

400 The request is malformed or contains invalid parameters.

▶ BadRequest

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

500 An unexpected error occurred on the server.

▶ InternalError

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

▶ POST /applications Create an application #

Create a new public assistance application in draft status.

Request body required

▶ ApplicationCreate