Reporting & Data Quality API Reference

On this page

Data quality monitoring, plus submission management for AFCARS (the Adoption and Foster Care Analysis and Reporting System) and NCANDS (the National Child Abuse and Neglect Data System).

Endpoints

AFCARS

List AFCARS submissions

GET /v1/reporting/afcars

Table 1. Parameters
Name In Required Description

page

query

No

Page

per_page

query

No

Per page

status

query

No

Status

search

query

No

Search

sort_by

query

No

Sort by

sort_dir

query

No

Sort dir
Responses

  • 200: Page of AFCARS submissions

  • 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 AFCARS submission

POST /v1/reporting/afcars/generate

Creates an AFCARS submission for the given reporting period. Real data extraction (collect from cases/placement/financial, map, materialize, validate) is not yet implemented (#949); the submission is created as an incomplete draft stub that cannot advance the federal workflow or be transmitted.

Table 2. Request Fields
Field Type Required Description

client_request_id

UUID

Yes

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

reporting_period

string

Yes

Reporting-period label (e.g. 2025-Q1). Free-text today — reporting does not yet constrain the format (see the service evil_corpus skips); length-capped at CODE_MAX.
Responses

  • 200: AFCARS submission generated (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 AFCARS submission by ID

GET /v1/reporting/afcars/{id}

Table 3. Parameters
Name In Required Description

id

path

Yes

Submission ID
Responses

  • 200: AFCARS submission 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 AFCARS submission

PUT /v1/reporting/afcars/{id}/approve

Table 4. Parameters
Name In Required Description

id

path

Yes

Submission ID
Responses

  • 200: Submission approved

  • 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.

Generate AFCARS flat file export

POST /v1/reporting/afcars/{id}/export

Generates a tab-delimited flat file from the submission data and stores it in object storage. Deterministic per (submission, generated_on): a replay under the same client_request_id returns the byte-identical artifact (ADR-062 §U).

Table 5. Parameters
Name In Required Description

id

path

Yes

Submission ID
Table 6. Request Fields
Field Type Required Description

client_request_id

UUID (optional)

No

Client-held idempotency id: replays under it are answered from the pinned attempt (byte-identical artifact).
Responses

  • 200: Export generated (a same-client_request_id retry replays the SAME artifact byte-identically)

  • 400: Invalid state

  • 401: Unauthorized

  • 403: Forbidden (including a foreign actor replaying another’s client_request_id)

  • 404: Not found

  • 409: export-source-changed: the submission’s data changed since this client_request_id first exported it (prior artifact retained; mint a fresh id) — or concurrent retries kept finalizing

  • 422: client_request_id reused against a different submission or kind (ADR-062 §U)

  • 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.

Download AFCARS export flat file

GET /v1/reporting/afcars/{id}/export/download

Table 7. Parameters
Name In Required Description

id

path

Yes

Submission ID
Responses

  • 200: Export file

  • 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.

Review AFCARS submission

PUT /v1/reporting/afcars/{id}/review

Marks the submission as reviewed (validated → reviewed).

Table 8. Parameters
Name In Required Description

id

path

Yes

Submission ID
Responses

  • 200: Submission reviewed

  • 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.

Transmit AFCARS submission to ACF

POST /v1/reporting/afcars/{id}/transmit

Marks the submission as transmitted. Actual ACF transmission is a stub in MVP.

Table 9. Parameters
Name In Required Description

id

path

Yes

Submission ID
Responses

  • 200: Submission transmitted

  • 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.

Data Quality

Data quality dashboard

GET /v1/reporting/quality/dashboard

Returns data quality metrics, unresolved issue counts by severity, and latest readiness scores.

Responses

  • 200: Dashboard data

  • 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.

List data quality issues

GET /v1/reporting/quality/issues

Table 10. Parameters
Name In Required Description

page

query

No

Page

per_page

query

No

Per page

source_service

query

No

Source service

issue_type

query

No

Issue type

severity

query

No

Severity

resolved

query

No

Resolved

search

query

No

Search

sort_by

query

No

Sort by

sort_dir

query

No

Sort dir
Responses

  • 200: Page of data quality issues

  • 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.

Resolve a data quality issue

PUT /v1/reporting/quality/issues/{id}/resolve

Table 11. Parameters
Name In Required Description

id

path

Yes

Issue ID
Responses

  • 200: Issue resolved

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 409: Unreachable defensive arm: a live-but-unresolved row after a zero-row miss (no un-resolve route exists)

  • 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.

NCANDS

List NCANDS submissions

GET /v1/reporting/ncands

Table 12. Parameters
Name In Required Description

page

query

No

Page

per_page

query

No

Per page

status

query

No

Status

search

query

No

Search

sort_by

query

No

Sort by

sort_dir

query

No

Sort dir
Responses

  • 200: Page of NCANDS submissions

  • 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 NCANDS submission

POST /v1/reporting/ncands/generate

Generates an NCANDS submission for the given federal fiscal year.

Table 13. Request Fields
Field Type Required Description

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1264) — REQUIRED. Same id + identical intent replays the ORIGINAL submission (its materialized rows and counts as of the first execution — the cases export is never re-fetched); a different intent under the same id is a 409 idempotency-conflict.

reporting_year

integer

Yes

Calendar reporting year (e.g. 2025).
Responses

  • 200: NCANDS submission generated (a replay returns the ORIGINAL submission — same client_request_id + intent; the cases export is never re-fetched)

  • 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: NCANDS source service (craig-cases) unavailable

  • 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 NCANDS submission

PUT /v1/reporting/ncands/{id}/approve

Table 14. Parameters
Name In Required Description

id

path

Yes

Submission ID
Responses

  • 200: Submission approved

  • 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.

Generate NCANDS Child File export

POST /v1/reporting/ncands/{id}/export

Builds the tab-delimited NCANDS Child File from the submission’s materialized rows and stores it in object storage. Deterministic: the body is timestamp-free, so a replay under the same client_request_id returns the byte-identical artifact (ADR-062 §U).

Table 15. Parameters
Name In Required Description

id

path

Yes

Submission ID
Table 16. Request Fields
Field Type Required Description

client_request_id

UUID (optional)

No

Client-held idempotency id: replays under it are answered from the pinned attempt (byte-identical artifact).
Responses

  • 200: Export generated (a same-client_request_id retry replays the SAME artifact byte-identically)

  • 401: Unauthorized

  • 403: Forbidden (including a foreign actor replaying another’s client_request_id)

  • 404: Not found

  • 409: export-source-changed: the submission’s materialized rows changed since this client_request_id first exported them (prior artifact retained; mint a fresh id) — or concurrent retries kept finalizing

  • 422: client_request_id reused against a different submission or kind (ADR-062 §U)

  • 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.

Download NCANDS Child File export

GET /v1/reporting/ncands/{id}/export/download

Table 17. Parameters
Name In Required Description

id

path

Yes

Submission ID
Responses

  • 200: Export file

  • 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.

Review NCANDS submission

PUT /v1/reporting/ncands/{id}/review

Marks the submission as reviewed (validated → reviewed).

Table 18. Parameters
Name In Required Description

id

path

Yes

Submission ID
Responses

  • 200: Submission reviewed

  • 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.

Transmit NCANDS submission to ACF

POST /v1/reporting/ncands/{id}/transmit

Marks the submission as transmitted. Actual ACF transmission is a stub in MVP.

Table 19. Parameters
Name In Required Description

id

path

Yes

Submission ID
Responses

  • 200: Submission transmitted

  • 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.

Edit this page · latest