REST API

Institution administrators can connect HealthTasks to other systems with the REST API—for example a student information system, CRM, hospital partner portal, or custom integration.

Overview

The REST API is a server-to-server interface for your institution’s data. You create API keys in Settings → REST API, then call the production base URL from your own backend or integration platform.

Full reference docs (endpoints, schemas, and examples) live at:

https://healthtasks.apidocumentation.com

Before you start

You must be an institution administrator.
Keys should stay in a secrets manager or secure server environment—never in public repos, browser apps, or hosted “try it” tools.
Prefer one key per integration so you can revoke access without affecting other systems.

Set up a key

Open Settings and select the REST API tab.
Open the public docs link if you need endpoint details, and copy your institution’s API base URL.
Create an API key. Give it a clear label (for example “Hospital partner – North Campus”).
Optionally limit the key to specific clinical sites (site-scoped). Leave sites empty for institution-wide access.
Copy the secret when it is shown. It is displayed only once.

Authenticate requests with either:

Authorization: Bearer ht_…
or x-healthtasks-api-key: ht_…

What you can access

Institution-wide keys can read curated resources such as:

People and sites (students, preceptors, classrooms, locations)
Clinical schedules and assignments
Clinical logs
Evaluations and skills checkoffs
Clinical-site partner resources (placements, compliance status summaries, site evaluation insights)

Keys include read access by default. Write access is limited to creating, updating, and archiving location units under existing clinical locations (for example capacity updates from a partner scheduling system).

Site-scoped keys only see the clinical sites you selected, and only the partner-oriented resources for those sites (locations, placements, compliance status, site evaluation insights, and unit writes).

Common uses

School integrations
Sync rosters, placements, or clinical activity into your SIS, data warehouse, or reporting tools.

Clinical site partners
Share a site-scoped key so a hospital can pull who is coming, check clearance summaries, and push unit capacity—without institution-wide access.

Operational automation
Run scheduled jobs on your servers that call HealthTasks and update downstream systems.

Managing keys

Edit a key’s label or site scope without rotating the secret.
Revoke a key immediately when an integration ends or a secret may have leaked. Create a new key to reconnect.
Monitor last used timestamps on the REST API tab to spot unused or unexpected keys.

Security tips

Store secrets server-side only; do not paste keys into browser-based API explorers or third-party docs pages.
Use site-scoped keys whenever you share access with an external clinical partner.
Rotate (revoke + recreate) keys on a regular schedule or after staff changes.
Treat student and clinical data according to your institution’s agreements and policies—you remain responsible for how shared keys are used.

Troubleshooting

Cannot see the REST API tab
Confirm you are signed in as an institution administrator.

401 / unauthorized
Check that the secret is complete and that the key has not been revoked. Send the key in one of the supported headers.

403 / forbidden
The key may be site-scoped and you requested a resource or location outside that scope. Use an institution-wide key or expand the site list.

Rate limited (429)
Slow down requests and honor Retry-After. Heavy sync jobs should use incremental filters when available (see the public API docs).

Need endpoint details
Use the hosted reference at https://healthtasks.apidocumentation.com rather than this help article.

Settings: REST API keys, notifications, MFA, and LMS connections
Placements: Clinical sites and units (Locations tab) that partners may update via the API
Billing: Subscription and seat management (separate from API access)

Support

For integration questions or account access issues: [email protected]