Data Exchange & ICPC API Reference

On this page

Inter-agency data exchange and Interstate Compact on the Placement of Children (ICPC) workflow management.

Endpoints

Agreements

List data sharing agreements

GET /v1/exchange/agreements

Table 1. Parameters
Name In Required Description

page

query

No

Page

per_page

query

No

Per page

partner_id

query

No

Partner id

status

query

No

Status

search

query

No

Full-text search across agreement_title.

sort_by

query

No

Sort column: agreement_title, status, effective_date (default: created_at).

sort_dir

query

No

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

  • 200: Page of agreements

  • 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 data sharing agreement

POST /v1/exchange/agreements

Table 2. Request Fields
Field Type Required Description

agreement_title

string

Yes

Agreement title

client_request_id

UUID

Yes

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

data_elements

object

No

Data elements

effective_date

date

Yes

Effective date

expiration_date

date (optional)

No

Expiration date

legal_authority

string (optional)

No

Legal authority

object_key

string (optional)

No

Object key

partner_id

UUID

Yes

Partner id
Responses

  • 200: Agreement 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 data sharing agreement by ID

GET /v1/exchange/agreements/{id}

Table 3. Parameters
Name In Required Description

id

path

Yes

Agreement ID
Responses

  • 200: Agreement 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.

Update data sharing agreement

PUT /v1/exchange/agreements/{id}

Table 4. Parameters
Name In Required Description

id

path

Yes

Agreement ID
Table 5. Request Fields
Field Type Required Description

agreement_title

string (optional)

No

Agreement title

approved_by

string (optional)

No

Approved by

data_elements

object

No

Data elements

expiration_date

date (optional)

No

Expiration date

legal_authority

string (optional)

No

Legal authority

object_key

string (optional)

No

Object key

status

string (optional)

No

Status
Responses

  • 200: Agreement updated. The approval stamp is first-write-wins: a later write carrying approved_by cannot rewrite it. A replayed approve that repeats the status transition is a 400 (same-to-same is illegal); only a stamp-bearing write WITHOUT a status change converges to 200.

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

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

  • 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 draft data sharing agreement

DELETE /v1/exchange/agreements/{id}

Table 6. Parameters
Name In Required Description

id

path

Yes

Agreement ID
Responses

  • 204: Agreement deleted

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 409: Only draft agreements can be deleted, and only agreements no partner references (the refusal names the blocking partner)

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

ICPC

List ICPC requests

GET /v1/exchange/icpc

Table 7. Parameters
Name In Required Description

page

query

No

Page

per_page

query

No

Per page

direction

query

No

Direction

status

query

No

Status

overdue

query

No

Overdue

search

query

No

Full-text search across sending_state, receiving_state.

sort_by

query

No

Sort column: direction, status (default: created_at).

sort_dir

query

No

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

  • 200: Page of ICPC requests

  • 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 ICPC request

POST /v1/exchange/icpc

Table 8. Request Fields
Field Type Required Description

case_id

UUID

Yes

Case id

child_id

UUID

Yes

Child id

client_request_id

UUID

Yes

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

direction

string

Yes

Direction

receiving_state

string

Yes

Receiving state

request_type

string

Yes

Request type

sending_state

string

Yes

Sending state
Responses

  • 200: ICPC request 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 ICPC request detail

GET /v1/exchange/icpc/{id}

Table 9. Parameters
Name In Required Description

id

path

Yes

ICPC request ID
Responses

  • 200: ICPC request 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.

Update ICPC request status

PUT /v1/exchange/icpc/{id}

Table 10. Parameters
Name In Required Description

id

path

Yes

ICPC request ID
Table 11. Request Fields
Field Type Required Description

status

string

Yes

Status
Responses

  • 200: ICPC request updated

  • 400: Invalid transition

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

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

  • 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 ICPC attachments

GET /v1/exchange/icpc/{id}/attachments

Table 12. Parameters
Name In Required Description

id

path

Yes

ICPC request ID
Responses

  • 200: Attachments list

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

Upload ICPC attachment

POST /v1/exchange/icpc/{id}/attachments

Table 13. Parameters
Name In Required Description

id

path

Yes

ICPC request ID
Responses

  • 200: Attachment uploaded (a byte- and metadata-identical retry under the same client_request_id replays the SAME attachment)

  • 400: Validation error (including a missing client_request_id / file_sha256 text field or a digest that does not match the bytes)

  • 401: Unauthorized

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

  • 404: Not found

  • 409: Concurrent retries kept finalizing this upload; retry the request

  • 422: client_request_id reused with a different upload (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 ICPC attachment

GET /v1/exchange/icpc/{id}/attachments/{attachment_id}

Table 14. Parameters
Name In Required Description

id

path

Yes

ICPC request ID

attachment_id

path

Yes

Attachment ID
Responses

  • 200: Attachment 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.

Get home study for ICPC request

GET /v1/exchange/icpc/{id}/home-study

Table 15. Parameters
Name In Required Description

id

path

Yes

ICPC request ID
Responses

  • 200: Home study 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.

Submit home study assessment

POST /v1/exchange/icpc/{id}/home-study

Table 16. Parameters
Name In Required Description

id

path

Yes

ICPC request ID
Table 17. Request Fields
Field Type Required Description

background_checks

string

No

Background checks

client_request_id

UUID

Yes

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

coordinator_decision

string (optional)

No

Coordinator decision

education_access

string

No

Education access

home_safety

string

No

Home safety

medical_access

string

No

Medical access

override_justification

string (optional)

No

Override justification

references_check

string

No

References check

rules_recommendation

string (optional)

No

Rules recommendation

space_capacity

string

No

Space capacity

support_systems

string

No

Support systems
Responses

  • 200: Home study recorded (or replayed — same client_request_id + intent)

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 409: Home study already exists, 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.

Partners

List exchange partners

GET /v1/exchange/partners

Table 18. Parameters
Name In Required Description

page

query

No

Page

per_page

query

No

Per page

partner_type

query

No

Partner type

active

query

No

Active

search

query

No

Full-text search across partner_name.

sort_by

query

No

Sort column: partner_name, partner_type (default: created_at).

sort_dir

query

No

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

  • 200: Page of exchange partners

  • 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 exchange partner

POST /v1/exchange/partners

Table 19. Request Fields
Field Type Required Description

adapter_kind

string

No

Wire-protocol token driving adapter dispatch. One of the registry-backed snake_case tokens (open String carriage since Plan T3.1; registry-membership validated at the handler since T3.2 — discover via GET /v1/exchange/registry/adapter-kinds). Default shines preserves the seed/test behavior from the pre-Plan-L state where most fixtures targeted SHINES.

auth_config

object

No

Auth config

auth_type

string

No

Auth type

client_request_id

UUID

Yes

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

direction

string

Yes

Direction

endpoint_url

string (optional)

No

Endpoint url

exchange_format

string

No

Exchange format

partner_name

string

Yes

Partner name

partner_type

string

Yes

Partner type
Responses

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

  • 401: Unauthorized

  • 403: Forbidden (including a typed-only adapter kind, which may not be active until the B4/Phase-P lift — #1429)

  • 409: Duplicate partner name, 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 exchange partner by ID

GET /v1/exchange/partners/{id}

Table 20. Parameters
Name In Required Description

id

path

Yes

Partner ID
Responses

  • 200: Partner 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.

Update exchange partner

PUT /v1/exchange/partners/{id}

Table 21. Parameters
Name In Required Description

id

path

Yes

Partner ID

If-Match

header

Yes

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

adapter_kind

string (optional)

No

Adapter kind

auth_config

object

No

Auth config

auth_type

string (optional)

No

Auth type

data_sharing_agreement_id

UUID (optional)

No

Data sharing agreement id

direction

string (optional)

No

Direction

endpoint_url

string (optional)

No

Endpoint url

exchange_format

string (optional)

No

Exchange format

partner_name

string (optional)

No

Partner name

partner_type

string (optional)

No

Partner type
Responses

  • 200: Partner updated

  • 400: Missing or malformed If-Match, or a data_sharing_agreement_id that does not name an existing agreement (#1581)

  • 401: Unauthorized

  • 403: Forbidden (including a typed-only adapter kind left/made active by the effective post-merge state — #1429)

  • 404: Not found

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

Soft-delete exchange partner (sets active=false)

DELETE /v1/exchange/partners/{id}

Table 23. Parameters
Name In Required Description

id

path

Yes

Partner ID
Responses

  • 204: Partner deactivated

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found (including an already-deactivated partner — fleet delete convention)

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

Test partner connectivity

POST /v1/exchange/partners/{id}/test

Table 24. Parameters
Name In Required Description

id

path

Yes

Partner ID
Responses

  • 200: Connectivity test result

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

Registry

List registered adapter-kind tokens

GET /v1/exchange/registry/adapter-kinds

Responses

  • 200: Sorted adapter-kind tokens

  • 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 registered partner-type taxonomy tokens

GET /v1/exchange/registry/partner-types

Responses

  • 200: Sorted partner-type tokens

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

SSA Screening

Re-admit paused SSA screening jobs (human admin; #1469, fork 6)

POST /v1/exchange/ssa-screening-jobs/resume

Table 25. Request Fields
Field Type Required Description

reason

string (optional)

No

Re-admit only jobs paused with this categorical reason token (one of the H16 vocabulary).

run_id

UUID (optional)

No

Re-admit only the given run’s paused jobs.
Responses

  • 200: Matching paused jobs re-admitted (0 matches is a legal no-op)

  • 400: No filter given, or an unknown pause-reason token

  • 401: Unauthorized

  • 403: Service callers and non-admin humans are refused

  • 409: A live precondition still holds the pause condition — the detail names the token

  • 422: Validation failure (the reason token’s length bounds)

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

Service-to-service: stage an SSA screening run atomically (#1464, ADR-066 §D5)

POST /v1/exchange/ssa-screening-runs

Table 26. Request Fields
Field Type Required Description

as_of

date

Yes

The business date the cohort was bound (cases-side BusinessClock date; the UD11 freshness horizon counts from this).

case_id

UUID

Yes

The case whose household is being screened.

client_request_id

UUID

Yes

The client-held operation id, forwarded unchanged from the original caller (H4).

cohort_hash

string

Yes

The H1 cohort hash cases computed via the ONE shared [crate::screening_cohort::cohort_hash]; exchange recomputes and refuses on mismatch.

cohort_revision

integer

Yes

The case’s screening_cohort_revision READ IN THE SAME request that assembled the cohort (#1466 B5-U3, D14/D16): any producer mutation committing after that read carries a higher revision and invalidates this run — retroactively closing the torn-assembly window. REQUIRED with no serde default (deliberate: the mixed-version deploy window fails closed 4xx; pre-1.0, CHANGELOG’d).

members

array of StageScreeningMember

Yes

The cohort (1..=[SCREENING_MEMBERS_MAX] members; duplicate person ids are refused — the members table makes them unrepresentable, the handler refuses them typed).

requested_by

UUID

Yes

The requesting caseworker’s sub (stage-time actor attribution; becomes ssa_screening_runs.created_by).

requested_by_name

string

Yes

The requesting caseworker’s display name (attribution for the per-member exchange_transactions.initiated_by_name).
Responses

  • 202: Run staged (or an ADR-062 replay of the stored run — nothing re-staged)

  • 400: Malformed cohort (duplicate person ids, or cohort_hash does not match the members + as_of)

  • 401: Unauthorized

  • 403: Caller is not the craig-cases service identity, or the SSA screening knob is off (FEATURE_DISABLED)

  • 409: A screening run is already active for the case (SCREENING_RUN_ACTIVE), the submitted cohort revision is below the case watermark (SCREENING_COHORT_STALE — re-read the case and re-screen), or the partner’s DSA is missing/inactive/expired (DSA_NOT_ACTIVE)

  • 503: No active ssa_solq partner is configured, or more than one is (both categorical)

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

Rotation-runbook mass-invalidation of stale-digest runs (human admin; #1489, fork 4)

POST /v1/exchange/ssa-screening-runs/invalidate-stale-digests

Table 27. Request Fields
Field Type Required Description

current_version

integer

Yes

The digest-registry version the deployment rotated TO — runs whose members carry any OTHER version are the sweep set.

dry_run

boolean

No

True (the default) lists candidates without touching them.
Responses

  • 200: Candidates listed (dry run) or invalidated (execute)

  • 401: Unauthorized

  • 403: Service callers and non-admin humans are refused

  • 422: Validation failure

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

Service-to-service: the case’s latest screening run status (#1549, D4)

GET /v1/exchange/ssa-screening-runs/latest

Table 28. Parameters
Name In Required Description

case_id

query

Yes

The case id.
Responses

  • 200: The latest run’s status view

  • 401: Unauthorized

  • 403: Caller is not the craig-cases service identity

  • 404: The case has never staged a screening run

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

Service-to-service: operator cancel of one screening run (#1466, fork 1)

POST /v1/exchange/ssa-screening-runs/{run_id}/cancel

Table 29. Parameters
Name In Required Description

run_id

path

Yes

Screening run ID
Table 30. Request Fields
Field Type Required Description

case_id

UUID

Yes

The case the run must belong to (the relay’s binding check — a run id from another case answers 404, never a cross-case cancel).

requested_by

UUID

Yes

The acting worker (attribution; the durable actor-naming audit event ships with B6’s catalog — parsers before producers).

requested_by_name

string

Yes

Display attribution.
Responses

  • 200: Invalidated (or a deterministic already-invalidated replay)

  • 401: Unauthorized

  • 403: Caller is not the craig-cases service identity

  • 404: No such run for this case

  • 409: The run is completed and past the freshness horizon — quiesced for archive (the fork-2 no-op)

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

Set the UD10 legal hold on one screening run (human admin; #1566)

POST /v1/exchange/ssa-screening-runs/{run_id}/hold

Table 31. Parameters
Name In Required Description

run_id

path

Yes

Screening run ID
Table 32. Request Fields
Field Type Required Description

reason

string

Yes

Why this run’s records must not be pruned or archived (set) / why the hold is released (clear).
Responses

  • 200: Held (changed=false is the already-held replay)

  • 401: Unauthorized

  • 403: Service callers and non-admin humans are refused

  • 404: No such run

  • 422: Validation failure (reason length bounds)

  • 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 the UD10 legal hold on one screening run (human admin; #1566)

DELETE /v1/exchange/ssa-screening-runs/{run_id}/hold

Table 33. Parameters
Name In Required Description

run_id

path

Yes

Screening run ID
Table 34. Request Fields
Field Type Required Description

reason

string

Yes

Why this run’s records must not be pruned or archived (set) / why the hold is released (clear).
Responses

  • 200: Cleared (changed=false is the already-clear replay)

  • 401: Unauthorized

  • 403: Service callers and non-admin humans are refused

  • 404: No such run

  • 422: Validation failure (reason length bounds)

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

Transactions

Send outbound data exchange

POST /v1/exchange/send

Table 35. Request Fields
Field Type Required Description

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1260) — REQUIRED. Same id + identical intent replays the original 202 with the stored transaction (nothing restaged); a different intent under the same id is a 409 idempotency-conflict.

exchange_type

string

Yes

Exchange type

partner_id

UUID

Yes

Partner id

payload

object

No

Payload

record_count

integer (optional)

No

Record count
Responses

  • 202: Send accepted; will be dispatched asynchronously by the send-worker (a replay — same client_request_id + intent — returns 202 with the stored transaction, staging nothing)

  • 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, or a typed-only adapter kind refusing generic dispatch — #1428)

  • 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 exchange transactions

GET /v1/exchange/transactions

Table 36. Parameters
Name In Required Description

page

query

No

Page

per_page

query

No

Per page

partner_id

query

No

Partner id

status

query

No

Status

direction

query

No

Direction

search

query

No

Full-text search across exchange_type, partner_name.

sort_by

query

No

Sort column: direction, exchange_type (default: initiated_at).

sort_dir

query

No

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

  • 200: Page of transactions

  • 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 transaction detail

GET /v1/exchange/transactions/{id}

Table 37. Parameters
Name In Required Description

id

path

Yes

Transaction ID
Responses

  • 200: Transaction 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.

Retry a failed transaction

POST /v1/exchange/transactions/{id}/retry

Table 38. Parameters
Name In Required Description

id

path

Yes

Transaction ID
Responses

  • 200: Transaction retried

  • 400: Transaction not retryable

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not found

  • 422: Typed-only adapter kind refuses generic restage (#1428)

  • 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