> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinikehr.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ClinikEHR API
> Connect your software to ClinikEHR clinics: read and send records with simple HTTPS requests and JSON.
export const Availability = ({keyKind = [], plan, scopes, note}) => {
const kinds = keyKind.length ? keyKind : ['clinic', 'organization'];
return
Works with
{kinds.map((k, i) =>
{KEY_KIND_LABELS[k] || k}
)}
{plan ? Needs : null}
{plan ? {plan} : null}
{scopes ? Scope : null}
{scopes ? {scopes} : null}
{note ? {note} : null}
;
};
The ClinikEHR API lets software you build talk to ClinikEHR, the records system clinics, pharmacies and laboratories use. Your program sends an ordinary web request, and gets back plain JSON: a clinic's stock, a patient's allergies, an appointment, and more. You can also send information back for the clinic to review.
**This API is under active development.** The sections below say, resource by resource, what you can call **today**. A page that describes something not yet available says so at the top, in its own banner — nothing on this site describes a defect as if it were a feature.
## How it works
A key is a long secret string, like a password for your program. A clinic creates one for you, or you create your own in the [developer portal](https://developer.clinikehr.com). See [Getting a key](#getting-a-key).
Put the key in the `Authorization` header. That is the only sign-in this API has.
Call an endpoint, such as `GET /v1/clinics/{clinic_id}/inventory/items`, and read the JSON that comes back.
Here is a complete request. It asks the API which clinic or workspace your key belongs to:
```bash theme={"system"}
curl https://api.clinikehr.com/v1/me \
-H "Authorization: Bearer ehr_test_EXAMPLEKEYID0000000000_EXAMPLESECRET…"
```
**New here? Start in the sandbox.** [Sign up for a developer portal account](https://developer.clinikehr.com) and you get a **test** key straight away. It reaches only a sandbox of invented data, so you can try the examples on this site without touching a real clinic. Then follow the [Quickstart](/quickstart).
## Two ways to use this API
| | A clinic's own key | An organization's key |
| - | - | - |
| Created | By the clinic itself, in **Settings → API access** | By you, in the [developer portal](https://developer.clinikehr.com) |
| Reaches | Only that one clinic, always | Every clinic that has approved a connection to your organization, by [connection code](/connections) |
| Test mode | None — every key is `ehr_live_` | Yes — a `ehr_test_` key reaches your workspace's own **sandbox**, seeded with fictional data, before you ever touch a real clinic |
| Needs | Nothing beyond the clinic creating it | A verified workspace, and — for a **live** key — a paid workspace plan (see [Plans and pricing](/plans-and-pricing)) |
Both kinds send the same `Authorization: Bearer` header, hit the same base URL, and get the same responses for the same resource — see [Authentication](/authentication).
## What you can build
Read a clinic's catalogue, stock and availability, and record stock changes.
Patients, visits, notes, allergies, conditions and medicines, with the clinic's permission.
Send referrals for a clinic to review, and read the ones it received.
The payers a clinic works with, and a patient's coverage.
Ask a clinic for access with a one-time code, and find listed pharmacies.
Read clinical records in the FHIR R4 standard.
Every endpoint, with its request and response, is in the **API reference** tab.
## Patient information
Anything about a patient (records, appointments, notes, allergies, medicines, referrals, insurance and drug requests) needs more than a key, because it is protected health information. The clinic must agree, and the key must be allowed to carry patient-data permissions. [Getting access to patient data](/patient-data-access) lists exactly what is needed. A **test** key can try all of it in the sandbox today.
## What's available now
* **Inventory**, for a clinic your key reaches: locations, catalogue items, availability bands, and exact stock — see [Inventory](/inventory) and [Stock bands](/stock-bands). Creating an item, receiving or adjusting stock, and recording a transfer are also live, with the same key — see [Retries and duplicates](/retries-and-idempotency) for the idempotency design every write uses.
* **Insurance**: the payers a clinic has enabled, and a patient's coverage, which you can read and add (a coverage you add stays inactive until staff confirm it). It needs the same patient-data access as the records below. See [Insurance](/insurance).
* **Allergies**: a patient's allergies and intolerances, which you can read and send for a clinician to review. They need the same patient-data access as the records below. See [Allergies](/allergies).
* **Referrals**: the referrals a clinic has received for a patient, which you can read and send for the clinic to review. The clinic alone accepts, declines or books them. They need the same patient-data access as the records below. See [Referrals](/referrals).
* **Medications**: the medicines a patient reports, which you can read and send for a clinician to review, and the prescriptions written for them, which are read-only. They need the same patient-data access as the records below. See [Medications](/medications).
* **Automatic acceptance**: a clinic can choose to accept new allergies, conditions, reported medicines or referrals from your key or connection without review. The answer then already shows `review_status: "confirmed"` and `accepted_automatically: true`. See [Automatic acceptance](/automatic-acceptance).
* **Providers**: the clinic's clinical staff directory (name, role, specialty, NPI and licence), which is read-only and holds no contact details. See [Providers](/providers).
* **Outside care providers**: the doctors, referrers and specialists a patient names, which you can read and add, and change or remove when your app added them. They need the same patient-data access as the records below. See [Outside care providers](/care-providers).
* **Encounters**: a patient's visits as the clinic documents them, which you can read, and open as a draft visit for a clinician to complete. No clinical text is returned, and nothing is ordered, billed or signed. They need the same patient-data access as the records below. See [Encounters](/encounters).
* **Network search** — finding a listed pharmacy, and checking its availability band, without a direct connection to it yet — see [Connections](/connections#network-search).
* **Connections** — an organization requesting access to a clinic by one-time code, and the clinic narrowing or revoking what it granted — see [Connections](/connections).
* **Workspaces** — signing up for a developer portal account, verifying it, and using your sandbox with a test key before anything is live.
* Looking up which clinic or workspace a key belongs to, and confirming the key itself is valid (`GET /v1/me`).
* **Your sandbox** — invented inventory, pharmacies, patients, notes, appointments and medicine codes, reachable with a test key, with a request you can paste for each on the **Sandbox** page of the [developer portal](https://developer.clinikehr.com).
## What isn't available yet
If your integration needs any of this, it isn't ready to build against — check back, or ask us.
* **A self-serve checkout for a workspace's paid plan.** Moving off Sandbox is a request to us today — see [Plans and pricing](/plans-and-pricing).
* **OAuth, or any authentication method other than a bearer key.**
## Words you'll see
| Word | What it means |
| - | - |
| **Key** | The secret your program sends with every request. `ehr_live_` keys reach real clinics; `ehr_test_` keys reach only your sandbox. |
| **Sandbox** | A practice clinic full of invented data, for trying things safely. |
| **Workspace** | Your organization's account in the [developer portal](https://developer.clinikehr.com). |
| **Connection** | A clinic's permission for your organization to reach some of its records. The clinic can narrow or remove it at any time. |
| **Permission** (scope) | What a key may do, such as `inventory.items:read`. A request needs the permission its endpoint names. |
| **Clinic ID** | The id in the URL that says which clinic a request is about. With a clinic's own key, `GET /v1/me` returns it; an organization finds it on its [connections](/connections). |
## Base URL
```
https://api.clinikehr.com/v1
```
Every endpoint lives under this base URL. See [Versioning](/versioning) for how the path changes over time.
## Where to start
Make your first request in a few minutes.
How a key is formatted, sent, and kept safe.
What a key can be given access to, and how that's enforced.
Every endpoint, with its request, response and permission.
Client libraries and a ready-made request collection.
## Getting a key
* **Building for one clinic you already work with?** Ask them to create a key inside their own ClinikEHR workspace, under **Settings → API access**, and share it with you over a channel you both trust. See the product's own guide: [API access](https://help.clinikehr.com/platform/settings/api-access).
* **Building something that reaches more than one clinic?** [Sign up for a developer portal account](https://developer.clinikehr.com) — you get a test key and a sandbox immediately. A live key needs your workspace verified, on a paid plan, and to have accepted the [API Terms of Use](/terms-of-use), and it only ever reaches a clinic that has approved a [connection](/connections) to you.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.