From file drops to write-back: maturing the Placements REST API
Site-scoped API keys now let clinical partners pull live placements and compliance, write location units for scheduling control, and view deidentified evaluation aggregates for Magnet and QI, still limited to their sites.
When we introduced the HealthTasks REST API, we focused on connecting clinical education data to the systems your institution already runs. SIS, LMS, data warehouses, accreditation reporting.
Placements have a different interoperability problem. Coordinators email rosters. Hospitals re-key schedules. Compliance status lives in folders that do not match what the school sees. Too often the "source of truth" is last night's SFTP drop.
Site-scoped API keys were built to close that gap for clinical partners. We have now extended that surface from read-only feeds into a read and write placements offering: partners can manage units on their locations and pull deidentified evaluation aggregates for Magnet and QI work, still limited to the sites they are privileged to access.
Why placements need their own access model
Your IT team needs the full picture: rosters, schedules, logs, evaluations, skills checkoffs, placements, and compliance across the program. That is what institution-wide API keys are for.
Clinical partners need something different. A hospital should see who is coming, on which unit, and for which dates. They should confirm a student is cleared for clinical work. They should keep their own unit structure current when floors open, close, or rename. They should not see your entire student body, every classroom, or unrelated sites across your network.
Site-scoped keys are built for that boundary. Under Settings → REST API, administrators create a key and select the clinical sites a partner should see. The partner receives only data for those sites, not your entire institution.
What changes for coordinators and partners
Instead of waiting on overnight file transfers, hospitals can pull placement and compliance feeds into their own scheduling systems, credentialing workflows, or internal dashboards. When a unit needs to change, partners can create, update, or archive location units through the same scoped key, so school and hospital calendars stay aligned without another spreadsheet round-trip.
For Magnet and quality improvement programs, partners can also view deidentified evaluation aggregates for their scoped locations. That gives clinical education leaders signal for status and QI work without exposing identifiable student evaluation detail through the partner API.
Schools keep HealthTasks as the system of record. Partners work from the same schedule and readiness data the program sees, and can write unit changes back where they have access. As you add clinical sites, you issue scoped keys per partner. The network scales without adding coordinator overhead.
That is hospital-school interoperability built for how placements actually run: shared data, appropriate boundaries, and no re-keying overnight.
What partners can do with a scoped key
Site-scoped keys (location_ids) may read locations, site_placements, compliance_statuses, and location_evaluation_insights, and may manage units under allowed locations. Document files are never included through the API. Write access requires the rest:write scope (included on new keys by default). When a key covers multiple sites, partners can narrow results with location_id.
Example: site placement feed
Hospital partners see who is scheduled, on which unit, and for which dates, without access to the rest of your program.
{
"data": [
{
"id": "classroom-uuid:student-uuid",
"student": {
"first_name": "Jordan",
"last_name": "Lee"
},
"classroom": {
"name": "NUR 412 — Acute Care Practicum"
},
"track": {
"name": "Med-Surg Rotation A"
},
"segments": [
{
"start_date": "2026-01-06",
"end_date": "2026-03-14",
"location": { "name": "Mercy General Hospital" },
"location_unit": { "name": "4 West — Medical Surgical" },
"weekly_hours": 36
}
]
}
]
}
Example: compliance status
Sites can verify student readiness from status fields only. Document content and download links are not exposed through the API.
{
"data": [
{
"user_id": "a91f0e44-…",
"is_compliant": false,
"student": {
"first_name": "Jordan",
"last_name": "Lee"
},
"items": [
{
"name": "TB screening",
"status": "approved",
"expiration_date": "2027-01-15"
},
{
"name": "HIPAA attestation",
"status": "approved"
},
{
"name": "Annual flu vaccine",
"status": "pending"
}
]
}
]
}
Example: create a location unit
POST /locations/{location_id}/units with rest:write. Required fields are name and max_students.
{
"name": "5 East — Progressive Care",
"max_students": 6,
"description": "Step-down / progressive care. Day shift preferred.",
"sort_order": 3
}
{
"data": {
"id": "c2e8f1a0-…",
"location_id": "b7d4a912-…",
"name": "5 East — Progressive Care",
"description": "Step-down / progressive care. Day shift preferred.",
"max_students": 6,
"sort_order": 3,
"archived": false,
"assigned_count": 0,
"over_capacity": false,
"created_at": "2026-07-12T14:02:11Z",
"updated_at": "2026-07-12T14:02:11Z"
}
}
Example: update a location unit
PATCH /location_units/{id}. Capacity changes are soft: lowering max_students below current assignments succeeds and sets over_capacity: true. The school resolves roster conflicts in HealthTasks.
{
"name": "4 West — Medical Surgical",
"max_students": 4,
"description": "Med-surg. Reduced capacity for summer renovations."
}
{
"data": {
"id": "a91f0e44-…",
"location_id": "b7d4a912-…",
"name": "4 West — Medical Surgical",
"description": "Med-surg. Reduced capacity for summer renovations.",
"max_students": 4,
"sort_order": 1,
"archived": false,
"assigned_count": 6,
"over_capacity": true,
"updated_at": "2026-07-12T15:40:02Z"
}
}
Example: archive a location unit
POST /location_units/{id}/archive marks the unit archived so partners can retire floors without deleting history the school still needs.
{
"data": {
"id": "c2e8f1a0-…",
"location_id": "b7d4a912-…",
"name": "5 East — Progressive Care",
"max_students": 6,
"archived": true,
"assigned_count": 0,
"over_capacity": false,
"updated_at": "2026-07-12T16:05:44Z"
}
}
Example: location evaluation insights
GET /location_evaluation_insights returns aggregate scores for site-targeted evaluations only. Scores are suppressed when count is under 5. Responses include no evaluator identity, comments, or raw evaluation rows.
{
"data": [
{
"location_id": "b7d4a912-…",
"master_location_id": "mloc-88c1-…",
"site_evaluations": {
"count": 42,
"average_score_percent": 91.4,
"last_submission_at": "2026-07-08T19:22:10Z",
"suppressed": false
},
"benchmark": {
"count": 1280,
"average_score_percent": 88.7,
"suppressed": false
},
"by_template": [
{
"evaluation_template_id": "tmpl-clinic-site-…",
"name": "Clinical Site Experience",
"count": 42,
"average_score_percent": 91.4,
"suppressed": false
}
],
"by_question": [
{
"question_text": "Orientation prepared me for this clinical site",
"count": 42,
"average_score_percent": 93.1,
"suppressed": false
},
{
"question_text": "Staff supported my learning on the unit",
"count": 42,
"average_score_percent": 90.2,
"suppressed": false
},
{
"question_text": "I would recommend this site to other students",
"count": 3,
"average_score_percent": null,
"suppressed": true
}
]
}
],
"next_cursor": null,
"high_watermark": "2026-07-08T19:22:10Z"
}
Get started
Generate keys in HealthTasks under Settings → REST API. For authentication, endpoints, and the full resource catalog, see the documentation.
Sharing a site-scoped key with a clinical partner is at your institution's discretion. You are responsible for key custody and for agreements that govern student information.
