The Hero Health Public API uses API key authentication on all requests. Every API key is tied to a specific Hero practice group and partner. Scopes control which endpoints your key can access.
Before you can access Hero's APIs, you need to become a verified partner:
- Fill out our partner onboarding form at our Get Started page
- Review and sign our Partner Agreement (includes SLA and rate limits)
- Receive access credentials for both staging and production environments
Once approved, you'll receive:
- A staging API key for development and testing
- A practice group ID for each practice you're integrating with
- Access to our Slack environment for developer support
Never expose API keys in client-side code or commit them to source control. Store keys securely using environment variables or a secrets manager. Use separate keys for staging and production.
All requests require two headers:
| Header | Description |
|---|---|
x-api-key | Your Hero Health API key |
x-practice-group-id | The ID of the practice you are acting on behalf of |
curl -X GET "https://api.herohealth.net/v1/practice-groups" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-practice-group-id: YOUR_PRACTICE_GROUP_ID"| Environment | Base URL | Use for |
|---|---|---|
| Staging | https://api.staging.htech.app | Development, testing, and integration verification |
| Production | https://api.herohealth.net | Live applications serving real practices |
Use test data only in staging — it does not contain real patient information.
Cross-organisational calls allow you to make API requests on behalf of a different practice group, provided both practices belong to the same Hero-configured network.
Hero supports cross-organisational API calls. If the x-practice-group-id header you pass does not match the practice group ID configured on your API key, Hero will verify that the target practice exists within a Hero-configured network alongside your key's practice. If such a network exists, the call returns data from the specified practice group.
The primary use case is cross-organisational bookings — for example, a practice within a PCN inviting patients to book at a hub site.
| Status | Error | Cause |
|---|---|---|
401 | invalid_credentials | API key is missing, invalid, or expired |
403 | insufficient_permissions | Key does not have the required scope for this endpoint |
403 | forbidden | Cross-org access denied — practices are not in the same network |
429 | rate_limit_exceeded | Too many requests — implement retry with exponential backoff |
The API enforces a limit of 300 requests per minute per API key. Contact Hero support if your integration requires a higher limit.
- Store API keys in environment variables or a secrets manager — never in source code
- Use separate keys for staging and production
- Request only the minimum scopes your integration needs
- All API calls must use HTTPS
- Contact Hero support to rotate a compromised key immediately
- Basic concepts — understand Hero's data model
- Your first API call — make a working API request end-to-end