From file drops to write-back: maturing the Placements REST API

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. For programs on Salesforce as SIS or hybrid CRM/SIS, that path is documented in Integrate HealthTasks with Salesforce via our REST API.

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 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 actually see and send

Partners work only with the sites on their key. Document files never travel through the API. Here is the shape of the exchange, focused on the fields that matter day to day.

Who is scheduled

Student, course, dates, site, and unit. Enough for the hospital's scheduling system. Not the rest of the program.

{
  "student": { "first_name": "Jordan", "last_name": "Lee" },
  "classroom": { "name": "NUR 412 — Acute Care Practicum" },
  "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
    }
  ]
}

Who is cleared

Requirement name, status, and expiration. Status fields only. No document downloads.

{
  "student": { "first_name": "Jordan", "last_name": "Lee" },
  "is_compliant": false,
  "items": [
    { "name": "TB screening", "status": "approved", "expiration_date": "2027-01-15" },
    { "name": "HIPAA attestation", "status": "approved" },
    { "name": "Annual flu vaccine", "status": "pending" }
  ]
}

Units the hospital can write back

Partners create, update, or archive units on their own sites. Name and capacity are the core fields. If capacity drops below students already assigned, HealthTasks flags the unit as over capacity and the school resolves the roster in product.

{
  "name": "5 East — Progressive Care",
  "max_students": 6,
  "description": "Step-down / progressive care. Day shift preferred."
}

{
  "name": "4 West — Medical Surgical",
  "max_students": 4,
  "assigned_count": 6,
  "over_capacity": true
}

Deidentified evaluation signal for QI

Site-level averages, optional benchmarks, and question rollups. Small samples stay suppressed. No evaluator names, comments, or raw rows.

{
  "site_evaluations": {
    "count": 42,
    "average_score_percent": 91.4,
    "suppressed": false
  },
  "benchmark": {
    "count": 1280,
    "average_score_percent": 88.7
  },
  "by_question": [
    {
      "question_text": "Orientation prepared me for this clinical site",
      "average_score_percent": 93.1
    },
    {
      "question_text": "Staff supported my learning on the unit",
      "average_score_percent": 90.2
    }
  ]
}

Get started

Generate keys in HealthTasks under Settings → REST API. For authentication, endpoints, and the full resource catalog, see the documentation.

• REST API overview
• API 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.