Placement Periods API creates cross-agency placements in one request
Placement Periods API creates cross-agency placements in one request
POST /api/v1/placement_periods can now record that a child lives in a home
licensed by a partner agency in a single request. Send the partner agency's
home as agency_placement_id along with the final placement_type:
{
"placement_period": {
"child_id": 93893,
"placement_type": "placed_with_family",
"start_date": "2026-11-01",
"agency_placement_id": 136560,
"partner_agency_placed_slug": "some-partner-agency"
},
"meta": {
"suppress_email_notifications": true
}
}- With
partner_agency_placed_slug: the home must belong to that partner
agency. Otherwise the request returns422with an error on
agency-placement-id. - Without
partner_agency_placed_slug: a home at another agency makes the
placement cross-agency with that agency, as long as the child's agency may
refer children there for placement. The response's
partner-agency-placed-slugshows the partner Binti set. If the child's agency
can't refer children to the home's agency, the request returns422with an
error onagency-placement-id. Callers that previously sent another agency's
home without a slug got an ordinary placement; they now get a cross-agency
placement or a422. - Placements with a home at the child's own agency, and placements with only a
partner agency and no home, work as before.
Same side effects as creating a placement in Binti
Non-respite creates now run the same follow-up steps as creating the placement
in Binti:
- A
placement_ended_reasonthat means the child exited care (for example
adoption_finalizedoremancipation) marks the child as no longer in agency
care. - Ending a cross-agency placement with an
end_dateof today or earlier removes
the partner agency's workers from the child and ends the partner agency's
schedules for the child.
Emails
Creating a cross-agency placement through the API now emails the partner
agency's default assignee for cross-agency placements, as creating one in
Binti does. This includes placements with only a partner agency and no home.
The new meta.suppress_email_notifications field (boolean, defaults to false)
stops every email the request would send: the partner agency's default
assignee, the family about newly granted child profile access, and workers on
placement searches the placement closes. Everything else, such as closing
searches, still happens.
Request validation
POST request bodies are now validated against the documented schema. Requests that
include fields outside the schema, or values of the wrong type, return 422
with an error pointing at the field, for example
/placement-period/not-a-field. Previously Binti ignored undocumented fields.
provider_typeis now documented, so respite placements can send it.placement_typemay be omitted for respite placements. Every other placement
still requires it.- An invalid
respite_reason_requestedstill returns422, but the error now
points at/placement-period/respite-reason-requestedinstead of
/data/attributes/respite-reason-requested.
Response fields
Placement period responses from every Placement Periods endpoint include new
fields so callers can confirm which agencies and home the placement ended up
with:
partner-agency-placed-name: the partner agency's name.agency-placement-agency-slugandagency-placement-agency-name: the agency
the home belongs to. On a cross-agency placement with a home, these match the
partner agency.agency-slugandagency-name: the child's custodial agency.placement-name: the home's display name.
