Skip to main content

Locations

Locations are the places an agency works with: hospitals, jails, courthouses, clinics. Keeping them as records rather than free text means an application refers to a facility consistently, and a change of address does not have to be retyped on every form.

Create​

curl -s -X POST "$BASE/locations" \
  -H "x-api-key: $API_KEY" \
  -H "X-On-Behalf-Of: admin.reyes@example.gov" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mercy General Hospital",
    "type": "HOSPITAL",
    "address": "1201 Red River Street",
    "city": "Austin",
    "state": "TX",
    "zip_code": "78701",
    "county": "Travis",
    "phone": "+1-512-555-0142",
    "contact_person": "Records Office",
    "notes": "Emergency department intake, third floor."
  }'

name, address, city, state, and zip_code are required. type is a label your agency chooses, such as HOSPITAL, JAIL, or COURT; the API does not constrain it, so pick a vocabulary and keep to it.

List​

curl -s "$BASE/locations?type=HOSPITAL" -H "x-api-key: $API_KEY"

The list view carries the fields a picker needs. Fetch a single location for the complete record:

curl -s "$BASE/locations/$LOCATION_ID" -H "x-api-key: $API_KEY"

Retired locations are hidden by default. Pass active_only=false to include them, which is what you want when rendering an old application that still refers to one.

Update and delete​

PUT /v1/locations/{locationId} updates a location, and DELETE /v1/locations/{locationId} removes it.

Applications that already reference a location keep the values they captured in form_data. Editing a location does not rewrite the applications that named it, and deleting one does not blank them. That is intentional: an application records where something happened at the time it happened.

Prefer setting is_active: false over deleting. A retired facility stays readable, and nothing in the archive turns into a dangling reference.

Using locations on an application​

Locations are referenced from form_data by whatever field your template declares, commonly a SELECT populated from this list or a text field filled from the chosen record. Store the location's name (and id, if your template has a field for it) so the application stays readable on its own, without a second lookup years later.