Improved

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 returns 422 with 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-slug shows the partner Binti set. If the child's agency
    can't refer children to the home's agency, the request returns 422 with an
    error on agency-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 a 422.
  • 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_reason that means the child exited care (for example
    adoption_finalized or emancipation) marks the child as no longer in agency
    care.
  • Ending a cross-agency placement with an end_date of 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_type is now documented, so respite placements can send it.
  • placement_type may be omitted for respite placements. Every other placement
    still requires it.
  • An invalid respite_reason_requested still returns 422, but the error now
    points at /placement-period/respite-reason-requested instead 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-slug and agency-placement-agency-name: the agency
    the home belongs to. On a cross-agency placement with a home, these match the
    partner agency.
  • agency-slug and agency-name: the child's custodial agency.
  • placement-name: the home's display name.