Safety Net Blueprint — Eligibility Service API

▶ GET /determinations List determinations #

Retrieve a paginated list of determinations. Filter by applicationId to get the determination for a specific application.

Parameters

Name Type In Req Description

applicationId

string

query

Filter by application identifier.

▶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 list of determinations.

▶ DeterminationList

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[Determination] required

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

applicationId string (uuid) required The application this determination belongs to.

▶ status DeterminationStatus required Lifecycle status of the determination. `pending` — created at submission, awaiting processing. `in_progress` — at least one Decision has been resolved. `completed` — all Decisions have reached a terminal state. `withdrawn` — the application was withdrawn before determination completed.

No additional fields

expeditedFlagged boolean required Whether the application was flagged for expedited SNAP processing (7 CFR § 273.2(i)). Set at submission based on the rules engine expedited screening call.

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

updatedAt string (date-time) read-only When the determination record was last updated.

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.

▶ GET /determinations/{determinationId} Get determination #

Retrieve a single determination by identifier.

Parameters

Name	Type	In	Req	Description
determinationId	string	path	✓	Unique identifier of the determination.

Responses

200 Determination retrieved successfully.

▶ Determination

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

applicationId string (uuid) required The application this determination belongs to.

▶ status DeterminationStatus required Lifecycle status of the determination. `pending` — created at submission, awaiting processing. `in_progress` — at least one Decision has been resolved. `completed` — all Decisions have reached a terminal state. `withdrawn` — the application was withdrawn before determination completed.

No additional fields

expeditedFlagged boolean required Whether the application was flagged for expedited SNAP processing (7 CFR § 273.2(i)). Set at submission based on the rules engine expedited screening call.

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

updatedAt string (date-time) read-only When the determination record was last updated.

404 The requested resource was not found.

▶ NotFound

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.

▶ GET /determinations/{determinationId}/decisions List decisions #

Retrieve all decisions for a determination.

Parameters

Name Type In Req Description

determinationId

string

path

✓

Unique identifier of the determination.

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 list of decisions.

▶ DecisionList

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[Decision] required

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

determinationId string (uuid) required The determination this decision belongs to.

applicationId string (uuid) The application this decision belongs to.

memberId string (uuid) required The household member this decision covers.

program string required The program this decision covers.

enumsnap medicaid chip tanf aca

▶ status DecisionStatus required Outcome status of a single program eligibility decision. `pending` — not yet evaluated, or deferred to caseworker review by the rules engine. `approved` — member meets program requirements. `denied` — member does not meet requirements based on provided information. `ineligible` — member cannot qualify for this program (e.g., citizenship bar, age limit).

No additional fields

▶ path DecisionPath Whether the decision was made automatically or by a caseworker.

No additional fields

decidedAt string (date-time) When the decision reached a terminal state.

denialReasonCode string Machine-readable reason code when status is denied or ineligible.

▶ electronicChecks array[ElectronicCheckSummary] Summary of electronic checks that informed this decision.

serviceType string The data exchange service that performed the check.

result string The outcome of the check (e.g., conclusive, inconclusive).

checkedAt string (date-time) When the check result was received.

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

updatedAt string (date-time) read-only When the decision record was last updated.

404 The requested resource was not found.

▶ NotFound

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.

▶ GET /determinations/{determinationId}/decisions/{decisionId} Get decision #

Retrieve a single decision by identifier.

Parameters

Name	Type	In	Req	Description
determinationId	string	path	✓	Unique identifier of the determination.
decisionId	string	path	✓	Unique identifier of the decision.

Responses

200 Decision retrieved successfully.

▶ Decision