Financial & Claims API Reference

On this page

Foster care payments, kinship and guardianship subsidies, payment adjustments, rate schedules, and Title IV-E fiscal claiming under the Social Security Act.

Endpoints

Adjustments

List payment adjustments

GET /v1/financial/adjustments

Table 1. Parameters
Name In Required Description

page

query

No

Page

per_page

query

No

Per page

search

query

No

Full-text search across reason, status, requested_by.

sort_by

query

No

Sort column: status, reason, amount (default: created_at).

sort_dir

query

No

Sort direction: asc or desc (default: desc).
Responses

  • 200: Page of adjustments

  • 401: Unauthorized

  • 403: Forbidden

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get a payment adjustment

GET /v1/financial/adjustments/{id}

Table 2. Parameters
Name In Required Description

id

path

Yes

Adjustment ID
Responses

  • 200: Payment adjustment

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Delete a pending payment adjustment

DELETE /v1/financial/adjustments/{id}

Table 3. Parameters
Name In Required Description

id

path

Yes

Adjustment ID
Responses

  • 204: Adjustment deleted

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 409: Adjustment is not pending

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Approve a payment adjustment

PUT /v1/financial/adjustments/{id}/approve

Table 4. Parameters
Name In Required Description

id

path

Yes

Adjustment ID
Responses

  • 200: Adjustment approved

  • 400: Invalid state transition

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 409: Status moved concurrently since your read (ADR-062 §G3), or the parent payment is aggregated by a submitted/accepted claim — claimed-payment-frozen (#1357)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Deny a payment adjustment

PUT /v1/financial/adjustments/{id}/deny

Table 5. Parameters
Name In Required Description

id

path

Yes

Adjustment ID
Responses

  • 200: Adjustment denied (terminal — the resolver is recorded in the approved_by/approved_at columns, which record the RESOLVER for both outcomes)

  • 400: Invalid state transition

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 409: Status moved concurrently since your read — re-read and retry (ADR-062 §G3)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Create a payment adjustment

POST /v1/financial/payments/{id}/adjustments

Table 6. Parameters
Name In Required Description

id

path

Yes

Payment ID
Table 7. Request Fields
Field Type Required Description

amount

string

Yes

Signed adjustment amount (negative for a clawback; rides the wire as a string via serde-str). #773: at most 2 dp (sub-cent money refuses, never rounds — the pre-#773 shape let Postgres round it silently at the bind, diverging from the ADR-062 intent hash) and plausibly bounded; sign-agnostic.

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1263) — REQUIRED. Same id + identical intent replays the original adjustment; a different intent under the same id is a 409 idempotency-conflict.

reason

string

Yes

Free-text justification for the adjustment.
Responses

  • 200: Adjustment created (or replayed — same client_request_id + intent)

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Payment not found

  • 409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)

  • 422: Validation failure (including a missing client_request_id)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Claims

List claiming records

GET /v1/financial/claims

Table 8. Parameters
Name In Required Description

page

query

No

Page

per_page

query

No

Per page

claiming_period

query

No

Claiming period

payment_type

query

No

Payment type

status

query

No

Status

search

query

No

Full-text search across claiming_period, payment_type.

sort_by

query

No

Sort column: claiming_period, status, payment_type (default: created_at).

sort_dir

query

No

Sort direction: asc or desc (default: desc).
Responses

  • 200: Page of claiming records

  • 401: Unauthorized

  • 403: Forbidden

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Generate a claiming record from disbursed (issued or cleared) payments

POST /v1/financial/claims/generate

Table 9. Request Fields
Field Type Required Description

ccwis_operations_cost

string

No

CCWIS operations cost rolled into the claim (defaults to zero; rides the wire as a string via serde-str). #773: non-negative, at most 2 dp (sub-cent money refuses, never rounds), plausibly bounded.

claiming_period

string

Yes

Claiming-period label (e.g. 2025-Q1).

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1263) — REQUIRED. Same id + identical intent replays the ORIGINAL claiming record (its aggregated money as of the first execution — never recomputed); a different intent under the same id is a 409 idempotency-conflict.

payment_type

string

Yes

Payment type the claim covers.

period_end

date

Yes

Last day of the claiming period (inclusive).

period_start

date

Yes

First day of the claiming period (inclusive).
Responses

  • 200: Claiming record generated (a replay returns the ORIGINAL record — same client_request_id + intent; the money is never recomputed)

  • 401: Unauthorized

  • 403: Forbidden

  • 409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)

  • 422: Validation failure (including a missing client_request_id)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get claiming record by ID

GET /v1/financial/claims/{id}

Table 10. Parameters
Name In Required Description

id

path

Yes

Claiming record ID
Responses

  • 200: Claiming record details

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Record federal acceptance of a submitted claiming record

PUT /v1/financial/claims/{id}/accept

Table 11. Parameters
Name In Required Description

id

path

Yes

Claiming record ID
Responses

  • 200: Federal acceptance recorded (actor + timestamp frozen onto the record)

  • 400: Invalid state transition

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 409: Status moved concurrently since your read — re-read and retry (ADR-062 §G3)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Submit a draft claiming record

PUT /v1/financial/claims/{id}/submit

Table 12. Parameters
Name In Required Description

id

path

Yes

Claiming record ID
Responses

  • 200: Claiming record submitted

  • 400: Invalid state transition

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 409: Status moved concurrently since your read (ADR-062 §G3), or the draft’s totals are stale / its window unrecorded — claim-totals-stale: regenerate before submitting (#1357)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Payments

List payments

GET /v1/financial/payments

Table 13. Parameters
Name In Required Description

page

query

No

Page

per_page

query

No

Per page

case_id

query

No

Case id

foster_home_id

query

No

Foster home id

agreement_id

query

No

#1068: narrow to one subsidy agreement’s payment stream.

child_id

query

No

#1068: narrow to one child (spans both origins).

status

query

No

Status

period_start

query

No

Period start

period_end

query

No

Period end

ive_eligible

query

No

Ive eligible

search

query

No

Full-text search across status, payment_type, created_by.

sort_by

query

No

Sort column: status, period_start, payment_type (default: created_at).

sort_dir

query

No

Sort direction: asc or desc (default: desc).
Responses

  • 200: Page of payments

  • 401: Unauthorized

  • 403: Forbidden

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Calculate a payment preview

POST /v1/financial/payments/calculate

Looks up the applicable rate and calculates a payment preview without persisting.

Table 14. Request Fields
Field Type Required Description

case_id

UUID

Yes

Case the payment belongs to.

child_age

integer

Yes

Child’s age, used to select the matching rate band (#775: 0..=21 — the extended-IV-E ceiling; out-of-band ages refuse typed instead of silently matching no rate).

child_id

UUID

Yes

Child the payment is for.

foster_home_id

UUID

Yes

Foster home receiving the payment.

jurisdiction

string

Yes

Jurisdiction whose rate table applies.

payment_type

string

Yes

Payment type (e.g. ive_maintenance).

period_end

date

Yes

Last day of the payment period (inclusive).

period_start

date

Yes

First day of the payment period (inclusive).

placement_id

UUID

Yes

Placement the payment derives from.
Responses

  • 200: Payment preview

  • 401: Unauthorized

  • 403: Forbidden

  • 404: No applicable rate found

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get payment by ID

GET /v1/financial/payments/{id}

Table 15. Parameters
Name In Required Description

id

path

Yes

Payment ID
Responses

  • 200: Payment details

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Approve a pending payment

PUT /v1/financial/payments/{id}/approve

Advances pending → approved atomically and stages financial.payment_approved in the same transaction.

Table 16. Parameters
Name In Required Description

id

path

Yes

Payment ID
Responses

  • 200: Payment approved

  • 400: Invalid state transition

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 409: Concurrent modification

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Clear an issued payment

PUT /v1/financial/payments/{id}/clear

Records reconciliation clearance: advances issued → cleared atomically and stages financial.payment_cleared in the same transaction.

Table 17. Parameters
Name In Required Description

id

path

Yes

Payment ID
Responses

  • 200: Payment cleared

  • 400: Invalid state transition

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 409: Concurrent modification

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Issue an approved payment

PUT /v1/financial/payments/{id}/issue

Records disbursement: advances approved → issued atomically and stages financial.payment_issued in the same transaction. Issued payments enter Title IV-E claim aggregation.

Table 18. Parameters
Name In Required Description

id

path

Yes

Payment ID
Responses

  • 200: Payment issued

  • 400: Invalid state transition

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 409: Concurrent modification

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Void an undisbursed payment (deliberate manual void)

PUT /v1/financial/payments/{id}/void

Voids a single pending/approved payment atomically, stamping who/when/why on the row and staging financial.payment_voided in the same transaction. issued/cleared payments are refused (typed 400 disbursed-payment-void): disbursed IV-E funds are corrected via payment adjustments, never clawed back — the same policy boundary as the system bulk voids (#776). The reason stays on the row; it never rides the event.

Table 19. Parameters
Name In Required Description

id

path

Yes

Payment ID
Table 20. Request Fields
Field Type Required Description

reason

string

Yes

Why this payment is being voided (data-entry error, duplicate, …). Must contain at least one non-whitespace character.
Responses

  • 200: Payment voided

  • 400: Already voided (invalid-state-transition), disbursed (disbursed-payment-void), or validation failure

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 409: Defensive arm: a still-voidable row after a zero-row CAS miss — unreachable today (no writer reverses payment status)

  • 422: Validation failure (blank/oversized reason)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Run subsidy payment generation for one month

POST /v1/financial/subsidy-payments/generate

Reconcile-then-generate the monthly subsidy payment stream (ADR-053). Bounded to the last 12 months; one run at a time (409 when the lease is held); Georgia-only policy (400 elsewhere). Partial success: per-child failures increment errors and the run still returns 200.

Table 21. Request Fields
Field Type Required Description

month

string (optional)

No

Target month as a canonical YYYY-MM token. Omitted → the current month. Bounded server-side to [current − 12 months, current] (bounded historical repair; out-of-range is a typed 400).
Responses

  • 200: Run report

  • 400: Out-of-range month or unsupported jurisdiction

  • 401: Unauthorized

  • 403: Forbidden

  • 409: A generation run is already in progress

  • 422: Malformed month token

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Rates

List payment rate tables

GET /v1/financial/rates

Table 22. Parameters
Name In Required Description

page

query

No

Page

per_page

query

No

Per page

jurisdiction

query

No

Jurisdiction

payment_type

query

No

Payment type

search

query

No

Full-text search across jurisdiction, payment_type.

sort_by

query

No

Sort column: jurisdiction, payment_type, effective_date (default: created_at).

sort_dir

query

No

Sort direction: asc or desc (default: desc).
Responses

  • 200: Page of rate tables

  • 401: Unauthorized

  • 403: Forbidden

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Create a payment rate table entry

POST /v1/financial/rates

Table 23. Request Fields
Field Type Required Description

age_max

integer

Yes

Inclusive upper bound of the child-age band the rate applies to (#775: 0..=21).

age_min

integer

Yes

Inclusive lower bound of the child-age band the rate applies to (#775: 0..=21 — the extended-IV-E ceiling; band ordering is the handler’s cross-field check).

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1263) — REQUIRED. Same id + identical intent replays the original rate row; a different intent under the same id is a 409 idempotency-conflict.

daily_rate

string

Yes

Daily maintenance rate (rides the wire as a string via serde-str). #773/#775: strictly positive, at most 2 dp (sub-cent money refuses, never rounds), plausibly bounded.

effective_date

date

Yes

Date the rate becomes effective (window ordering vs end_date is the handler’s cross-field check, #775).

end_date

date (optional)

No

Optional date the rate stops applying (open-ended when absent).

jurisdiction

string

Yes

Jurisdiction the rate applies to (e.g. georgia).

payment_type

string

Yes

Payment type the rate covers (e.g. ive_maintenance).
Responses

  • 200: Rate created (or replayed — same client_request_id + intent)

  • 401: Unauthorized

  • 403: Forbidden

  • 409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)

  • 422: Validation failure (including a missing client_request_id)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get a rate table entry

GET /v1/financial/rates/{id}

Table 24. Parameters
Name In Required Description

id

path

Yes

Rate ID
Responses

  • 200: Rate table entry

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Update a rate table entry

PUT /v1/financial/rates/{id}

Table 25. Parameters
Name In Required Description

id

path

Yes

Rate ID

If-Match

header

Yes

REQUIRED row version from your last read (ADR-062 §G3), e.g. "3" or 3
Table 26. Request Fields
Field Type Required Description

age_max

integer (optional)

No

New age-band upper bound, or unchanged when absent (#775: 0..=21).

age_min

integer (optional)

No

New age-band lower bound, or unchanged when absent (#775: 0..=21).

daily_rate

string (optional)

No

New daily rate, or unchanged when absent (#773/#775: positive, ≤ 2 dp, bounded — same rules as create; inner because garde’s custom does not auto-descend into Option).

effective_date

date (optional)

No

New effective date, or unchanged when absent.

end_date

date (optional)

No

None keeps the current end date; Some(None) clears it; Some(Some(date)) sets it. The clear arm needs the #1077 deserializer — plain serde collapses an explicit JSON null into the outer None, making Some(None) wire-unreachable. skip_serializing_if is LOAD-BEARING with it: without the skip, a Rust-side keep-intent None serializes as an explicit null, which the fixed server now honestly reads as CLEAR.

jurisdiction

string (optional)

No

New jurisdiction, or unchanged when absent.

payment_type

string (optional)

No

New payment type, or unchanged when absent.
Responses

  • 200: Rate updated

  • 400: Missing or malformed If-Match

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found (including a tombstoned rate — previously still mutable)

  • 409: Version moved since your read (stale If-Match) — re-read and retry

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Delete a rate table entry

DELETE /v1/financial/rates/{id}

Table 27. Parameters
Name In Required Description

id

path

Yes

Rate ID
Responses

  • 204: Rate deleted

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Subsidy Agreements

List subsidy agreements

GET /v1/financial/subsidy-agreements

Pages agreement summaries (identity + current term). Enum filter tokens are validated up front (unknown → 400); a caller whose list scope resolves to denied receives an explicit 403, never an empty page.

Table 28. Parameters
Name In Required Description

page

query

No

Page

per_page

query

No

Per page

child_id

query

No

Filter by the subsidized child.

case_id

query

No

Filter by owning case.

program

query

No

Program token (snake_case; e.g. err, sg) — unknown tokens 400.

current_status

query

No

Projection-status token (e.g. active) — unknown tokens 400.
Responses

  • 200: Page of subsidy-agreement summaries

  • 400: Unrecognized program / status filter token

  • 401: Unauthorized

  • 403: Forbidden — including a denied list scope

  • 422: Query validation failed

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Native subsidy enrollment, program-tagged (#1069 ERR / #1070 guardianship)

POST /v1/financial/subsidy-agreements

Responses

  • 200: The created agreement’s full detail (also the exact-replay response)

  • 400: Wire validation / placement eligibility / date-rule / per-diem-conflict failure

  • 401: Missing or invalid token

  • 403: Authorization denied, or the ERR feature gate is OFF (the detail names the knob)

  • 409: Same client_request_id with a different payload, or an open episode already exists

  • 503: craig-placement unreachable — the anchoring placement cannot be verified

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Get a subsidy agreement by ID

GET /v1/financial/subsidy-agreements/{id}

Full agreement detail: identity + provenance, signatory parties, and the complete term-revision and status-interval ledgers (each ordered (effective_from, id)).

Table 29. Parameters
Name In Required Description

id

path

Yes

Subsidy agreement ID
Responses

  • 200: Subsidy agreement detail

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Witnessed guardianship activation (#1070, U4-gated)

POST /v1/financial/subsidy-agreements/{id}/activate

Table 30. Parameters
Name In Required Description

id

path

Yes

Agreement id
Table 31. Request Fields
Field Type Required Description

court_order_evidence_key

string

Yes

UNVERIFIED evidence reference: the permanent-guardianship court order (required non-blank, F7).

expected_head_interval_id

UUID

Yes

CAS: the open pending head interval the caller decided on.

legal_reference

string (optional)

No

Court order / docket reference — NULL→value records it; a value DIFFERENT from the recorded one is a typed conflict.

tanf_terminated_on

date (optional)

No

Operator ATTESTATION (unverified, past-dated): the date TANF for the child terminated, when the caregiver received it — shifts the money boundary later (F2). TANF still active ⇒ activate after it ends (runbook).
Responses

  • 200: The activated agreement’s detail (also the recognized-replay response)

  • 400: Witness failure: placement still active / wrong end reason / child mismatch / reunification goal / signing, residence-floor or date-window refusal

  • 401: Missing or invalid token

  • 403: Authorization denied, or the SG feature gate is OFF (the detail names the knob)

  • 404: Agreement not found

  • 409: Stale head (CAS — incl. a mismatched retry after success), a differing legal reference, or an open sibling agreement

  • 503: craig-placement unreachable — the transfer cannot be verified

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

POST /financial/subsidy-agreements/{id}/reviews — schedule the

type’s open slot (#1095). Replay with the open slot’s due → 200 with the existing row (no event); a different due → 409 naming it.

POST /v1/financial/subsidy-agreements/{id}/reviews

Table 32. Parameters
Name In Required Description

id

path

Yes

Agreement id
Table 33. Request Fields
Field Type Required Description

due_on

date

Yes

Statutory due date for the slot.

review_type

string

Yes

Review type token: renewal_12mo
Responses

  • 200: The open slot (created or replayed)

  • 400: Validation / window-authority failure

  • 401: Missing or invalid token

  • 403: Authorization denied

  • 404: Agreement not found

  • 409: An open slot exists with a different due

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

POST /financial/subsidy-agreements/{id}/reviews/{review_id}/completion

— complete a review with its linkage orchestrated in ONE transaction (#1095): a continued/amended RENEWAL re-signs (term append, kind Renewal) and links resulting_term_id; suspended/terminated outcomes perform the CAS transition and link resulting_interval_id. An identical replay returns the prior record (200); a differing one is a 409 — the fingerprint check runs BEFORE any append/transition, so a replay can never duplicate a revision.

POST /v1/financial/subsidy-agreements/{id}/reviews/{review_id}/completion

Table 34. Parameters
Name In Required Description

id

path

Yes

Agreement id

review_id

path

Yes

The open slot being completed
Table 35. Request Fields
Field Type Required Description

completed_on

date

Yes

Business date the review was completed (never in the future).

evidence_document_key

string (optional)

No

Object-store key of supporting verification evidence (untrusted reference; namespace-shape validated at the API).

outcome

string

Yes

Outcome token: continued

amended

suspended

terminated (an unknown token is a typed 400).

terms

ReviewTermsPayload (optional)

No

Terms

transition
Responses

  • 200: The completed review record

  • 400: Shape / authority / validation failure

  • 401: Missing or invalid token

  • 403: Authorization denied

  • 404: Agreement or review not found

  • 409: Differing replay, superseded slot, or stale CAS head

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

POST /financial/subsidy-agreements/{id}/reviews/{review_id}/reschedule

— audited supersession + same-cycle successor (#1095). Idempotent on (slot, new_due_on); the successor’s due obeys the natural window.

POST /v1/financial/subsidy-agreements/{id}/reviews/{review_id}/reschedule

Table 36. Parameters
Name In Required Description

id

path

Yes

Agreement id

review_id

path

Yes

The slot being superseded
Table 37. Request Fields
Field Type Required Description

new_due_on

date

Yes

The successor slot’s due date (same cycle — cycle is the identity; due dates are data).

reason

string

Yes

Why the due date moved — retained forever on the superseded row’s audit triple.
Responses

  • 200: The live successor slot

  • 400: Validation / window-authority failure

  • 401: Missing or invalid token

  • 403: Authorization denied

  • 404: Agreement or review not found

  • 409: Slot completed, or superseded with a different due

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

POST /financial/subsidy-agreements/{id}/terms — CAS terms

amendment (#1095). The request carries NO anchor fields: the store derives renewal_review_due/paper_review_due (ADR-054 anchor preservation) — the head’s values below are placeholders it overwrites.

POST /v1/financial/subsidy-agreements/{id}/terms

Table 38. Parameters
Name In Required Description

id

path

Yes

Agreement id
Table 39. Request Fields
Field Type Required Description

amount_basis

string

Yes

Rate-schedule citation backing the amount.

education_basis

string (optional)

No

Extension basis (school/GED enrollment description), when the flag is set.

education_expires_on

date (optional)

No

Date the education verification lapses, when the flag is set.

education_extension

boolean

Yes

Age-19 school/GED extension flag (22.8).

education_verified_by

string (optional)

No

Worker who verified the education basis, when the flag is set.

effective_from

date

Yes

Business-effective start of the appended revision (closes the current revision at the same date — half-open windows).

expected_head_term_id

UUID

Yes

The open term revision the caller last read — the optimistic-concurrency token the store compares-and-swaps on (stale → typed 409; retry-after-success → 409, see [TransitionSubsidyAgreementRequest]).

monthly_amount

string

Yes

New monthly subsidy amount (Decimal wire string, e.g. "450.00").
Responses

  • 200: The new term revision

  • 400: Validation / supervisor-session / office-authority failure, or unsupported jurisdiction (writes are Georgia-defined, ADR-054)

  • 401: Missing or invalid token

  • 403: Authorization denied

  • 404: Agreement not found

  • 409: Stale head term (CAS) — re-read and retry

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

POST /financial/subsidy-agreements/{id}/transitions — CAS status

transition (#1095). Rejects pending → active outright: activation requires eligibility evidence and ships with the #1069/#1070 flows.

POST /v1/financial/subsidy-agreements/{id}/transitions

Table 40. Parameters
Name In Required Description

id

path

Yes

Agreement id
Table 41. Request Fields
Field Type Required Description

business_date

date

Yes

Business-effective start of the new interval (strictly after the open head’s start, never in the future — ADR-052).

expected_head_interval_id

UUID

Yes

The open status interval the caller last read — the optimistic-concurrency token the store compares-and-swaps on.

note

string (optional)

No

Free-text protected note carried on the interval (never traced — #1064 doctrine).

reason_code

string (optional)

No

Controlled-vocabulary cause — required for reason statuses (suspended/terminated/withdrawn/declined), forbidden otherwise; membership is validated server-side.

to_status

string

Yes

Target status token (snake_case, e.g. suspended); parsed server-side against the 6-token vocabulary — an unknown token is a typed 400, not a silently-ignored write.
Responses

  • 200: The new head interval

  • 400: Validation / vocabulary / office-authority failure, or unsupported jurisdiction (writes are Georgia-defined, ADR-054)

  • 401: Missing or invalid token

  • 403: Authorization denied

  • 404: Agreement not found

  • 409: Stale head (CAS) — re-read and retry

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

POST /financial/subsidy-reviews/sweep/preview — pin the current

actionable sets into a previewed run and mint the single-use execute token (#1096). #1263: the run row commits atomically with its ADR-062 claim — a lost response can never strand an unclaimed previewed row. A verified replay returns the SAME run (original pinned sets + as-of) with a freshly ROTATED token (the row stores only a digest, so the lost original is unrecoverable by design); a run that has moved on answers a typed 409.

POST /v1/financial/subsidy-reviews/sweep/preview

Table 42. Request Fields
Field Type Required Description

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1263) — REQUIRED. Replaying it returns the SAME still-previewed run (original pinned sets and as-of) with a freshly ROTATED single-use execute token — the prior token is invalidated, never re-exposed (the row stores only a digest). A run that has moved on (executed / expired) answers a typed 409: preview again under a fresh id.
Responses

  • 200: The pinned candidate sets + the one-time execute token (a replay of a still-previewed run rotates the token; the original pinned sets and as-of return unchanged)

  • 400: Unsupported jurisdiction (the sweep is Georgia-defined, ADR-054)

  • 401: Missing or invalid token

  • 403: Authorization denied

  • 409: client_request_id claimed by a different operation (ADR-062), or the replayed run has moved on (executed / expired) — preview again under a fresh id

  • 422: Validation failure (including a missing client_request_id)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

GET /financial/subsidy-reviews/sweep/runs — recent run records,

newest first (#1096; the U5 operator surface).

GET /v1/financial/subsidy-reviews/sweep/runs

Table 43. Parameters
Name In Required Description

limit

query

No

Max rows (default 50, clamped 1..=200).
Responses

  • 200: Recent sweep runs

  • 401: Missing or invalid token

  • 403: Authorization denied

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

GET /financial/subsidy-reviews/sweep/runs/{run_id} — one run

record (#1096).

GET /v1/financial/subsidy-reviews/sweep/runs/{run_id}

Table 44. Parameters
Name In Required Description

run_id

path

Yes

Run id
Responses

  • 200: The run record

  • 401: Missing or invalid token

  • 403: Authorization denied

  • 404: Run not found

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

POST /financial/subsidy-reviews/sweep/{run_id}/execute — redeem a

preview: regional office + the one-time token + the CAS (#1096).

POST /v1/financial/subsidy-reviews/sweep/{run_id}/execute

Table 45. Parameters
Name In Required Description

run_id

path

Yes

The previewed run
Table 46. Request Fields
Field Type Required Description

acknowledged_handoff

integer

No

Leg-3 handoff candidates the caller rendered.

acknowledged_suspend

integer

No

Leg-1 candidates the caller rendered (must equal the pinned suspend set’s size).

acknowledged_terminate

integer

No

Leg-2 candidates the caller rendered.

execute_token

string

Yes

The preview’s single-use token (server-validated by digest).
Responses

  • 200: The finished run’s report (partial success carries nonzero errors)

  • 400: Bad token / office authority / jurisdiction failure

  • 401: Missing or invalid token

  • 403: Authorization denied

  • 404: Run not found

  • 409: Run not previewable (replayed/concurrent/expired), acknowledged counts stale (#1069 M3), or a sweep already running

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Subsidy Imports

Create a conversion batch (#1071 ADR-057; knob-gated, admin-only)

POST /v1/financial/subsidy-imports

Table 47. Request Fields
Field Type Required Description

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1263) — REQUIRED. Same id + identical intent replays the original batch (its detail view with CURRENT record counts); a different intent under the same id is a 409 idempotency-conflict. The xtask import tool pins it via --request-id so a create-crash retry within the 30-day claim window cannot double-create a batch (a retry AFTER the window is a documented fresh operation — resume long-dormant runs via --batch-id instead).

cutover_month

date

Yes

The inter-system money boundary (month-start; > snapshot_date — DDL-checked): SHINES pays every month strictly before it.

expected_count

integer

Yes

The manifest’s record count (1..=50000 — DDL-checked).

manifest_checksum

string

Yes

sha256 hex over the sorted (external_reference, canonical_hash) pairs — the finalize manifest gate.

snapshot_date

date

Yes

The named conversion baseline (G7): CRAIG’s review chain starts here; SHINES stays authoritative for earlier history.

source_system

string

Yes

Conversion source vocabulary token (shines — DDL-checked).
Responses

  • 200: The created batch (a replay returns its detail view with CURRENT record counts — same client_request_id + intent)

  • 400: Wire validation failure (vocabulary, month shape, checksum shape)

  • 401: Missing or invalid token

  • 403: Authorization denied, or the import gate is OFF (the detail names the knob)

  • 409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)

  • 422: Validation failure (including a missing client_request_id)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Batch detail + live per-status counts (readable knob-off for audit)

GET /v1/financial/subsidy-imports/{id}

Table 48. Parameters
Name In Required Description

id

path

Yes

Batch ID
Responses

  • 200: Batch detail

  • 401: Missing or invalid token

  • 403: Authorization denied

  • 404: Batch not found

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Abort a staging batch (frees every live claim; replay-honest)

POST /v1/financial/subsidy-imports/{id}/abort

Table 49. Parameters
Name In Required Description

id

path

Yes

Batch ID
Responses

  • 200: The aborted batch (also the already-aborted replay)

  • 401: Missing or invalid token

  • 403: Authorization denied, or the import gate is OFF

  • 404: Batch not found

  • 409: Abort is forbidden once finalize started (typed batch-state)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Finalize (or resume finalizing) — the single money-consent act (#1071 D12)

POST /v1/financial/subsidy-imports/{id}/finalize

Table 50. Parameters
Name In Required Description

id

path

Yes

Batch ID
Responses

  • 200: The pass report (also the deterministic replay once finalized)

  • 400: The session lacks state-office authority (the office refusal names it)

  • 401: Missing or invalid token

  • 403: Authorization denied, or the import gate is OFF

  • 404: Batch not found

  • 409: Manifest mismatch (the four numbers), batch state, or another finalize holds the lease

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

The records ledger — the reconciliation export (readable knob-off)

GET /v1/financial/subsidy-imports/{id}/records

Table 51. Parameters
Name In Required Description

id

path

Yes

Batch ID

page

query

No

Page

per_page

query

No

Per page
Responses

  • 200: One page of records (staging order) + total

  • 401: Missing or invalid token

  • 403: Authorization denied

  • 404: Batch not found

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Stage one source record (full validation now; replay-honest, #1071 D4)

POST /v1/financial/subsidy-imports/{id}/records

Table 52. Parameters
Name In Required Description

id

path

Yes

Batch ID
Table 53. Request Fields
Field Type Required Description

agreement_document_key

string (optional)

No

Object-store key of the scanned artifact, when available.

approving_county

string

Yes

Approving county.

case_id

UUID (optional)

No

Owning case, when known.

child_id

UUID

Yes

The subsidized child (S2S-verified at the service).

external_reference

string

Yes

The source system’s record identifier (the replay key — one LIVE claim across all batches). NUL / newline are refused: they are the manifest checksum’s pair-framing bytes ([manifest_checksum]), so a reference containing them could forge another pair’s framing.

form_number

string

Yes

Signed form identity (may be a legacy placeholder token).

form_version

string

Yes

Signed form version.

intervals

array of ImportIntervalRecord

Yes

Full historical interval chain (1..=200, contiguous, last open).

legal_county

string (optional)

No

Legal county, when distinct.

legal_reference

string (optional)

No

Court order / docket reference.

parties

array of ImportPartyRecord

Yes

Signatories (≥1 caregiver on non-terminal heads; ≤16).

predecessor_external_reference

string (optional)

No

Predecessor EXTERNAL reference (same source system) — resolved to the materialized predecessor’s agreement id at validation (same child, same family, terminal, closed before this chain).

program

enum (rcs, ercs, ersg, enrsg)

Yes

The four GA 22.8 closed cohorts — the ONLY programs a conversion import can carry (ADR-057 D2). Open-program conversion is a recorded non-goal (native re-enrollment).

signed_at

date

Yes

Signature date.

terms

array of ImportTermsRecord

Yes

Full term-revision chain (1..=200, ordered, last open).
Responses

  • 200: Replay outcome (already_staged / restaged / already_imported) with the ORIGINAL facts

  • 201: Fresh row staged (or rejected with typed blockers — a successful reconciliation outcome)

  • 400: Wire validation failure

  • 401: Missing or invalid token

  • 403: Authorization denied, or the import gate is OFF

  • 404: Batch not found

  • 409: Batch state / batch conflict / post-finalize content conflict (typed)

  • 503: craig-cases unreachable — record references cannot be verified (fail-closed)

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Edit this page · latest