Placement API Reference

On this page

Placement and foster care management: foster homes, placements, kinship evaluations, sibling tracking, and matching.

Endpoints

Education

List education records by child

GET /v1/placement/education

Table 1. Parameters
Name	In	Required	Description
child_id	query	No	Optional child filter. When omitted, lists across all children (supervisor/admin triage). platform-stab-2 §D7 follow-up: pre-§D7 the BFF /placement/education page silently swallowed the 400 from the previously-required field.
page	query	No	Page
per_page	query	No	Per page

Responses

200: Page of education 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.

Create education record

POST /v1/placement/education

Table 2. Request Fields
Field	Type	Required	Description
child_id	UUID	Yes	Child id
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1259) — REQUIRED. Same id + identical intent replays the original education record; a different intent under the same id is a 409 idempotency-conflict.
enrollment_date	date	Yes	Enrollment date
grade_level	string (optional)	No	Grade level
iep_flag	boolean (optional)	No	Iep flag
notes	string (optional)	No	Notes
placement_id	UUID (optional)	No	Placement id
school_district	string (optional)	No	School district
school_name	string	Yes	School name
school_type	string	Yes	School type
section_504	boolean (optional)	No	Section 504

Responses

200: Education record created (or replayed — same client_request_id + intent)
400: Bad request
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 education record by ID

GET /v1/placement/education/{id}

Table 3. Parameters
Name	In	Required	Description
id	path	Yes	Education record ID

Responses

200: Education record
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 education record

PUT /v1/placement/education/{id}

Table 4. Parameters
Name	In	Required	Description
id	path	Yes	Education record ID

Table 5. Request Fields
Field	Type	Required	Description
grade_level	string (optional)	No	Grade level
iep_flag	boolean (optional)	No	Iep flag
notes	string (optional)	No	Notes
school_district	string (optional)	No	School district
school_name	string (optional)	No	School name
school_type	string (optional)	No	School type
section_504	boolean (optional)	No	Section 504
withdrawal_date	date (optional)	No	Withdrawal date
withdrawal_reason	string (optional)	No	Withdrawal reason

Responses

200: Education record updated
400: Bad request
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 education record (soft-delete)

DELETE /v1/placement/education/{id}

Table 6. Parameters
Name	In	Required	Description
id	path	Yes	Education record ID

Responses

200: Education record 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.

Foster Homes

Search foster homes

GET /v1/placement/homes

Table 7. Parameters
Name	In	Required	Description
page	query	No	Page
per_page	query	No	Per page
admin_unit	query	No	Admin unit
license_status	query	No	License status
license_type	query	No	License type
has_capacity	query	No	Has capacity
search	query	No	Full-text search across name, address, admin_unit.
sort_by	query	No	Sort column: name, admin_unit, license_status.
sort_dir	query	No	Sort direction: asc or desc (default: desc).

Responses

200: Page of foster homes
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 foster home record

POST /v1/placement/homes

Table 8. Request Fields
Field	Type	Required	Description
accepts_ages_max	integer (optional)	No	Accepts ages max
accepts_ages_min	integer (optional)	No	Accepts ages min
accepts_sibling_groups	boolean	No	Accepts sibling groups
address	string	Yes	Address
admin_unit	string	Yes	Admin unit
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1259) — REQUIRED. Same id + identical intent replays the original foster home; a different intent under the same id is a 409 idempotency-conflict.
icwa_compliant	boolean	No	Icwa compliant
license_expires	date (optional)	No	License expires
license_number	string (optional)	No	License number
license_type	string	Yes	License type
licensed_at	date (optional)	No	Licensed at
max_capacity	integer	Yes	Max capacity
name	string	Yes	Name
phone	string (optional)	No	Phone
primary_contact	string (optional)	No	Primary contact

Responses

200: Foster home 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 foster home detail with training records

GET /v1/placement/homes/{id}

Table 9. Parameters
Name	In	Required	Description
id	path	Yes	Foster home ID

Responses

200: Foster home 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 foster home

PUT /v1/placement/homes/{id}

Table 10. Parameters
Name	In	Required	Description
id	path	Yes	Foster home ID
If-Match	header	Yes	REQUIRED row version from your last read (ADR-062 §G2), e.g. `"3"` or `3`

Table 11. Request Fields
Field	Type	Required	Description
accepts_ages_max	integer (optional)	No	Accepts ages max
accepts_ages_min	integer (optional)	No	Accepts ages min
accepts_sibling_groups	boolean (optional)	No	Accepts sibling groups
address	string (optional)	No	Address
admin_unit	string (optional)	No	Admin unit
icwa_compliant	boolean (optional)	No	Icwa compliant
license_expires	date (optional)	No	License expires
license_number	string (optional)	No	License number
license_status	string (optional)	No	License status
license_type	string (optional)	No	License type
licensed_at	date (optional)	No	Licensed at
max_capacity	integer (optional)	No	Max capacity
name	string (optional)	No	Name
phone	string (optional)	No	Phone
primary_contact	string (optional)	No	Primary contact

Responses

200: Foster home updated
400: Invalid license type or license-status transition, or a missing/malformed If-Match
401: Unauthorized
403: Forbidden
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.

List training records for a foster home

GET /v1/placement/homes/{id}/training

Table 12. Parameters
Name	In	Required	Description
id	path	Yes	Foster home ID

Responses

200: Training records
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 training completion

POST /v1/placement/homes/{id}/training

Table 13. Parameters
Name	In	Required	Description
id	path	Yes	Foster home ID

Table 14. Request Fields
Field	Type	Required	Description
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1259) — REQUIRED. Same id + identical intent (including the foster home path id) replays the original training record; a different intent under the same id is a 409 idempotency-conflict.
completed_at	date	Yes	Completed at
expires_at	date (optional)	No	Expires at
hours	number	Yes	Hours
training_type	string	Yes	Training type
verified_by	string (optional)	No	Verified by

Responses

200: Training recorded (or replayed — same client_request_id + intent)
401: Unauthorized
403: Forbidden
404: 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.

Get a training record

GET /v1/placement/training/{id}

Table 15. Parameters
Name	In	Required	Description
id	path	Yes	Training record ID

Responses

200: Training record
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 training record

PUT /v1/placement/training/{id}

Table 16. Parameters
Name	In	Required	Description
id	path	Yes	Training record ID

Table 17. Request Fields
Field	Type	Required	Description
completed_at	date (optional)	No	Completed at
expires_at	date (optional)	No	Expires at
hours	number (optional)	No	Hours
training_type	string (optional)	No	Training type
verified_by	string (optional)	No	Verified by

Responses

200: Training updated
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 training record

DELETE /v1/placement/training/{id}

Table 18. Parameters
Name	In	Required	Description
id	path	Yes	Training record ID

Responses

204: Training 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.

Health

List health records by child

GET /v1/placement/health

Table 19. Parameters
Name	In	Required	Description
child_id	query	No	Optional child filter. When omitted, lists across all children (supervisor/admin triage). platform-stab-2 §D7 follow-up.
page	query	No	Page
per_page	query	No	Per page

Responses

200: Page of health 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.

Create health record

POST /v1/placement/health

Table 20. Request Fields
Field	Type	Required	Description
child_id	UUID	Yes	Child id
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1259) — REQUIRED. Same id + identical intent replays the original health record; a different intent under the same id is a 409 idempotency-conflict.
diagnosis	string (optional)	No	Diagnosis
immunization_date	date (optional)	No	Immunization date
immunization_name	string (optional)	No	Immunization name
medications	string (optional)	No	Medications
next_due_date	date (optional)	No	Next due date
notes	string (optional)	No	Notes
provider_name	string (optional)	No	Provider name
provider_type	string (optional)	No	Provider type
record_type	string	Yes	Record type
treatment_plan	string (optional)	No	Treatment plan
visit_date	date	Yes	Visit date

Responses

200: Health record created (or replayed — same client_request_id + intent)
400: Bad request
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.

List overdue health records

GET /v1/placement/health/overdue

Table 21. Parameters
Name	In	Required	Description
page	query	No	Page
per_page	query	No	Per page

Responses

200: Page of overdue health 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.

Get health record by ID

GET /v1/placement/health/{id}

Table 22. Parameters
Name	In	Required	Description
id	path	Yes	Health record ID

Responses

200: Health record
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 health record

PUT /v1/placement/health/{id}

Table 23. Parameters
Name	In	Required	Description
id	path	Yes	Health record ID

Table 24. Request Fields
Field	Type	Required	Description
diagnosis	string (optional)	No	Diagnosis
immunization_date	date (optional)	No	Immunization date
immunization_name	string (optional)	No	Immunization name
medications	string (optional)	No	Medications
next_due_date	date (optional)	No	Next due date
notes	string (optional)	No	Notes
provider_name	string (optional)	No	Provider name
provider_type	string (optional)	No	Provider type
record_type	string (optional)	No	Record type
treatment_plan	string (optional)	No	Treatment plan
visit_date	date (optional)	No	Visit date

Responses

200: Health record updated
400: Bad request
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 health record (soft-delete)

DELETE /v1/placement/health/{id}

Table 25. Parameters
Name	In	Required	Description
id	path	Yes	Health record ID

Responses

200: Health record 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.

Home Documents

List documents for a foster home

GET /v1/placement/homes/{home_id}/documents

Table 26. Parameters
Name	In	Required	Description
home_id	path	Yes	Foster home ID

Responses

200: Documents 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 a document to a foster home

POST /v1/placement/homes/{home_id}/documents

Table 27. Parameters
Name	In	Required	Description
home_id	path	Yes	Foster home ID

Responses

200: Document uploaded (a byte- and metadata-identical retry under the same client_request_id replays the SAME document)
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.

Delete a foster home document

DELETE /v1/placement/homes/{home_id}/documents/{doc_id}

Table 28. Parameters
Name	In	Required	Description
home_id	path	Yes	Foster home ID
doc_id	path	Yes	Document ID

Responses

204: Document 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.

Download a foster home document

GET /v1/placement/homes/{home_id}/documents/{doc_id}/download

Table 29. Parameters
Name	In	Required	Description
home_id	path	Yes	Foster home ID
doc_id	path	Yes	Document ID

Responses

200: Document 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.

Kinship

List kinship options for a case

GET /v1/placement/kinship

Table 30. Parameters
Name	In	Required	Description
case_id	query	Yes	Case id

Responses

200: Kinship options
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.

Record kinship option evaluation

POST /v1/placement/kinship

Table 31. Request Fields
Field	Type	Required	Description
approved	boolean (optional)	No	Approved
case_id	UUID	Yes	Case id
child_id	UUID	Yes	Child id
client_request_id	UUID	Yes	Client-minted idempotency id (ADR-062 §B, #1259) — REQUIRED. Same id + identical intent replays the original kinship option; a different intent under the same id is a 409 idempotency-conflict.
evaluated	boolean	No	Evaluated
evaluated_at	datetime (optional)	No	Evaluated at
rejection_reason	string (optional)	No	Rejection reason
relationship	string	Yes	Relationship
relative_name	string	Yes	Relative name

Responses

200: Kinship option recorded (or replayed — same client_request_id + intent)
401: Unauthorized
403: Forbidden
409: client_request_id claimed by a different operation, replayed entity gone (ADR-062), or case assignment changed since authorization (#1213) — re-read and retry
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 kinship option

GET /v1/placement/kinship/{id}

Table 32. Parameters
Name	In	Required	Description
id	path	Yes	Kinship option ID

Responses

200: Kinship option
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 kinship option

PUT /v1/placement/kinship/{id}

Table 33. Parameters
Name	In	Required	Description
id	path	Yes	Kinship option ID

Table 34. Request Fields
Field	Type	Required	Description
approved	boolean (optional)	No	Approved
evaluated	boolean (optional)	No	Evaluated
evaluated_at	datetime (optional)	No	Evaluated at
rejection_reason	string (optional)	No	Rejection reason

Responses

200: Kinship option updated
401: Unauthorized
403: Forbidden
404: Not found
409: Assignment changed since authorization (#1187, ADR-060) — 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 kinship option

DELETE /v1/placement/kinship/{id}

Table 35. Parameters
Name	In	Required	Description
id	path	Yes	Kinship option ID

Responses

204: Kinship option deleted
401: Unauthorized
403: Forbidden
404: Not found
409: Assignment changed since authorization (#1187, ADR-060) — 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.

Matching

Matching search for available foster homes

GET /v1/placement/matching

Table 36. Parameters
Name	In	Required	Description
child_age	query	No	Child age
icwa_required	query	No	Icwa required
sibling_group_size	query	No	Sibling group size
page	query	No	Page
per_page	query	No	Per page

Responses

200: Matching foster homes
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.

Placements

List placements

GET /v1/placement/placements

Table 37. Parameters
Name	In	Required	Description
page	query	No	Page
per_page	query	No	Per page
case_id	query	No	Case id
child_id	query	No	Child id
foster_home_id	query	No	Foster home id
status	query	No	Status
search	query	No	Full-text search across placement_type, status.
sort_by	query	No	Sort column: placement_type, status, started_at.
sort_dir	query	No	Sort direction: asc or desc (default: desc).

Responses

200: Page of placements
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 placement

POST /v1/placement/placements

Table 38. 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, #1259) — REQUIRED. Same id + identical intent replays the original placement (the capacity guard and activation event never re-run); a different intent under the same id is a 409 idempotency-conflict.
foster_home_id	UUID (optional)	No	Foster home id
permanency_goal	string (optional)	No	Permanency goal
placement_type	string	Yes	Placement type
removal_date	date (optional)	No	Removal date
removal_reason	string (optional)	No	Removal reason
started_at	datetime	Yes	Started at
status	string	No	Status

Responses

200: Placement created (or replayed — same client_request_id + intent)
400: Validation failure — placements are born planned or active, never ended (#1112)
401: Unauthorized
403: Forbidden
409: client_request_id claimed by a different operation, replayed entity gone (ADR-062), or case assignment changed since authorization (#1213) — re-read and retry
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 placement detail

GET /v1/placement/placements/{id}

Table 39. Parameters
Name	In	Required	Description
id	path	Yes	Placement ID

Responses

200: Placement 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 placement

PUT /v1/placement/placements/{id}

Table 40. Parameters
Name	In	Required	Description
id	path	Yes	Placement ID

Table 41. Request Fields
Field	Type	Required	Description
ctw_finding	boolean (optional)	No	Ctw finding
ctw_finding_date	date (optional)	No	Ctw finding date
end_reason	string (optional)	No	Terminal fact (#1112): accepted only when this request also sets `status: "ended"`; optional there (reason requiredness is jurisdiction policy). Immutable once the placement is ended.
ended_at	datetime (optional)	No	Terminal fact (#1112): accepted only when this request also sets `status: "ended"`, and REQUIRED on that transition. Immutable once the placement is ended.
permanency_goal	string (optional)	No	Permanency goal
reasonable_efforts	boolean (optional)	No	Reasonable efforts
reasonable_efforts_date	date (optional)	No	Reasonable efforts date
status	string (optional)	No	Status

Responses

200: Placement updated
400: Invalid transition or terminal-fact write decoupled from the ending transition (#1112)
401: Unauthorized
403: Forbidden
404: Not found
409: Assignment changed since authorization (#1187, ADR-060) — 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.

Placement history timeline for a child

GET /v1/placement/placements/{id}/history

Table 42. Parameters
Name	In	Required	Description
id	path	Yes	Child ID

Responses

200: Placement history
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.

Subsidy-eligibility projection of a placement (#1069 S2S)

GET /v1/placement/placements/{id}/subsidy-eligibility

#1084: the assignment triple (assigned_worker_sub, supervisor_sub, assignment_revision) is served from the #1213 case_assignments projection as ONE coherent read — mixing the placement row’s worker with the projection’s supervisor could pair a stale value with a newer revision, and a consumer stamping that pair would permanently block its own event-driven backfill guard. Absent projection row = NULL pair at revision 0 (fail-closed; the consumer’s next case.assignment_changed fills it).

Table 43. Parameters
Name	In	Required	Description
id	path	Yes	Placement ID

Responses

200: Eligibility projection
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.

Edit this page · latest