Skip to main content
What a developer can build against changes here, newest first. Every entry is something you can call today — see api-docs/README.md for what earns an entry and what doesn’t. Tags: API (a resource, scope, or endpoint) · Sandbox (test keys and synthetic data) · Portal (the developer dashboard at developer.clinikehr.com) · Webhooks (endpoints, deliveries and the change feed) · Billing (workspace plans and usage).
Portal
Developer portal

A new dark mode in the developer portal

The developer portal’s dark mode now uses a soft charcoal page, warm off-white text and a slightly darker menu and top bar, the same as ClinikEHR. Cards are outlined rather than filled, and hint and label text meets the accessibility contrast standard. Light mode is unchanged.
Portal
Developer portal

Create a developer account without a clinic

Signing up at developer.clinikehr.com now asks only for your name, email and a password, and for you to agree to the Terms of Service and Privacy Policy. Before, the form asked for a clinic’s details as well, and you could end up on a page that did not exist.
  • Check your email after you submit, confirm the address, then sign in.
  • The first thing you see is Create your first workspace. Nothing is created for a clinic behind your back.
  • See Create your account.
API
TypeScript and Python clients 0.4.0

The clients know about the barcode check

Version 0.4.0 of both clients brings their types in line with the October 30 change:
  • Partner code uploads can return a row with "state": "error" (the row was refused, for example an invalid barcode, and nothing was saved for it). The Python client in 0.3.0 did not know this value and could not read a response that contained it, so upgrade before you upload partner codes from Python. See Uploading partner codes.
  • Barcodes (upc, and a gtin identifier) are documented in the types as needing a valid GTIN, with 400 invalid_gtin when they do not, and an item update that sends back the same upc is accepted.
Code written for 0.3.0 keeps working, except code that checks every state value and treats an unknown one as impossible. Update with npm install @clinikehr/[email protected] or pip install clinikehr==0.4.0.
API
Behaviour change

Requests with an invalid GTIN are now rejected

This is a behaviour change, announced here with the release as described in Versioning. A barcode that is not a real GTIN used to be accepted and then quietly matched nothing. Now the API refuses it straight away when you send it as an identifier or an item’s upc, with 400 invalid_gtin, and tells you which field and which value. A valid GTIN is digits only, 8, 12, 13 or 14 long, with a correct GS1 check digit.
  • Where it applies: an identifier with system: "gtin" in availability checks, network search and feedback, stock reports and drug requests, and an item’s upc on create and update. Nothing is saved when a request is refused. The barcode filter on GET /v1/inventory/items is not checked: it still simply matches nothing, so you can use it to find an item whose stored barcode is not a valid GTIN.
  • Partner code uploads: a row with an invalid barcode is refused on its own ("state": "error", reason starting invalid_gtin); the other rows are still processed.
  • Already-saved values are not changed. They are still returned exactly as stored. Send a corrected value to replace one.
  • Updating an item only checks a changed barcode. If you send back the upc an item already holds, it is accepted even when it is not a valid GTIN, so reading an item and writing it back keeps working. A different upc must be valid. (The check reads the item with your key, so it needs inventory.items:read, and that read counts toward your rate limit. If the read itself is refused, for example because you are rate limited, you get that answer rather than invalid_gtin.) Creating an item always checks the upc.
  • Docs examples fixed. The example barcode in our Inventory, Stock bands, Connections, Uploading partner codes and Quickstart examples did not pass the check-digit rule. Every example now uses 6001234567899 (the stock report example uses 5000000000005). If you copied the old one into a test, swap it.
  • Sandbox: newly seeded sandbox items carry valid GTIN-13 barcodes. A sandbox that was seeded earlier keeps its old values until you reset it.
See Errors for the new code.
API
TypeScript and Python clients 0.3.0

The clients know about controlled items and pickup lines

Version 0.3.0 of both clients adds the fields from the October 20 releases to their types, so your editor knows about them and checks them:
  • is_controlled on inventory items, read-only. See Inventory.
  • line_id on Pharmacy-edition pickup lines, the value you send in line_ids to collect part of a pickup. See Prescription pickups.
  • signature_data is optional on a pickup collection, matching the clinic’s Require a signature at pickup setting. A clinic that requires one still refuses a collection without it (400 signature_required).
Code written for 0.2.0 keeps working. Update with npm install @clinikehr/[email protected] or pip install clinikehr==0.3.0.
API
Inventory

See which inventory items a clinic has marked as controlled

Inventory items now carry a read-only is_controlled flag, so your integration can tell a controlled medicine from an ordinary one without keeping its own list.
  • is_controlled on every item in the item list and the single item. It is true when the clinic marked the item as a controlled medicine.
  • Read-only. You cannot set it through the API; it is changed in the ClinikEHR app by staff the clinic has allowed to do so. A clinic that has marked nothing reports false everywhere.
API
Prescription pickups

Collect part of a till pickup, and know which line is which

A Pharmacy-edition till pickup could only be collected whole, because its lines carried no value you could send back to pick one. Now they do.
  • Every pickup line has a line_id. Send the line_id values you want to hand over in line_ids on the collection request; the lines you leave out stay on a new awaiting pickup. For a prescription line line_id equals its prescription_id, so requests you already send keep working. For a till line it is the line’s own id, and it is not a prescription id.
  • A list that names the wrong line is refused straight away with 400 invalid_request: an empty list, an id that is not a line of this pickup, or one that is not a UUID. Before, such a request was accepted and then sat in review without ever being completable.
  • The signature follows the clinic’s setting. signature_data on the collection request is now optional when the clinic has switched off Require a signature at pickup: leave it out and the pickup is recorded unsigned, reading has_signature: false. When the clinic requires a signature, a request without one is refused with 400 signature_required (see Errors). A signature you send is always checked.
APIWebhooks
Prescription pickups · Outreach events

Read prescription pickups and outreach events, and submit them for review

Two record types a pharmacy or an outreach team works with every day are now in the API.
  • Prescription pickups: who collected a dispensed prescription, whether counselling was offered, the clinic’s own questions and answers, and whether a signature is on file (never the image itself). Read them with pickups:read; submit a collection for a clinician to review with pickups:write.
  • Outreach events: a clinic’s screening-day events, their stations, and who is checked in. Read them with outreach:read; check an existing patient in, for a clinician to review, with outreach:write.
  • Both need the same patient-data access as the other patient records. A submission’s resource_type can now be prescription_pickup_collection or outreach_checkin, and a submission says whether a signature came with it (has_signature).
  • New webhook events: prescription_pickup.collected and outreach_event.attendee_checked_in.
API
Stock reports

A narrow permission for stock reports, and stricter stock reports

  • inventory.external_stock:write lets a key send a pharmacy’s stock report from another system, and read back the status of the reports it sent, and nothing else. It is available on every paid pharmacy plan, including the Listing plan. A key with inventory.stock:write still works.
  • A stock report to a pharmacy that is not set up to receive one is now refused with 409 external_stock_mode_required. It used to be accepted and quietly ignored.
  • A report with an unreadable row is refused as a whole, with nothing written: a row with no identifier, a negative quantity, or neither a quantity nor a band. Fix the rows the error lists and send the report again. See Errors.
API
Pharmacy listings

Pharmacy listings show the online store

A pharmacy listing now carries store_url: the address of the pharmacy’s online store, when it runs one.
API
Python client 0.1.0

The Python client is on PyPI

pip install clinikehr gives you a typed client for every route in this reference: your key sent for you, a reused Idempotency-Key on retries, sensible retry delays, paged lists walked for you, typed errors and webhook signature checks. It needs Python 3.11 or later.
  • Published from its public source at github.com/clinikehr/sdk-python by GitHub Actions, with a signed attestation for each file on PyPI.
  • Use the synchronous calls in 0.1.0; the asyncio variants are not usable yet. In an async program, run a call in a worker thread.
  • Install only clinikehr from PyPI, and nothing of that name from anyone else.
Start with the Python client guide, or see SDKs and Postman.
PortalBilling
Subscriptions

Billing & subscriptions in the developer portal

The developer portal has a Billing & subscriptions page in its navigation, with the workspace plan’s status, price and next charge and Cancel or Resume (workspace owners and admins). Cancelling keeps live keys working until the end of the period you paid for. The same plan also appears in a clinic owner’s Billing → Other subscriptions when that person is the workspace’s owner or admin.
Portal
Keys

Live keys end on a date you choose

A new live key needs an end date, at most 12 months away, in the developer portal and in a clinic’s API access settings. Create the replacement before the date, switch your system over, then revoke the old key. We email the workspace’s owners and admins 30 days and 7 days before a live key stops working. Test keys can still have no end date, and keys you already have keep working until you revoke them. See Authentication.
API
TypeScript client 0.1.3

The TypeScript client updates records too

Version 0.1.3 sends an Idempotency-Key on every PATCH, the way it already did on every POST. Earlier versions sent none, so a PATCH route that requires one, such as updating an appointment, was refused whatever you passed. A DELETE now carries your idempotencyKey when you give one. Update with npm install @clinikehr/[email protected]. See Writing safely.
APISandboxWebhooks
Fixes

Six fixes found by running the whole API end to end

  • The change feed works. GET /v1/clinics/{clinic_id}/events answered 404 not_found for every key. It now returns the feed, filtered to the event types your key’s scopes cover.
  • Appointments can be updated with a test key. Every PATCH on a sandbox appointment was refused as a reschedule, even a change to the notes or the status. Status, notes, urgency and venue changes now work, and so does a new time (sandbox times are in UTC; an overlap with the same clinician is refused with slot_taken). See Appointments.
  • Creating or updating a note returns the whole note. The answer used to show content: null and citations: null; it now carries the content and citations, the same as reading the note. See Notes.
  • A citation link must be a web address. A citation url that does not start with http:// or https:// is refused with invalid_request, naming /citations/N/url.
  • CRM contact values are checked. A record_type, lifecycle_stage, priority or source outside the documented values is refused with invalid_request and a field-level errors list, instead of being stored (test keys) or answered with a server error (live keys). See CRM.
  • Rate-limit headers tell the truth. RateLimit-Reset was always 60; it now gives the seconds until your allowance is full again. A 429 now carries RateLimit-Limit, RateLimit-Remaining: 0 and RateLimit-Reset as well as Retry-After, as Rate limits always said. That page now explains how the limit refills.
API
TypeScript client 0.1.2

The TypeScript client is on npm

npm install @clinikehr/api gives you a typed client for every route in this reference: your key kept on the server, a reused Idempotency-Key on retries, sensible retry delays, paged lists walked for you, typed errors and webhook signature checks.
  • Install 0.1.2 or later. Versions 0.1.0 and 0.1.1 are deprecated: they sent every request to the wrong address and could not complete a call.
  • Built from its public source at github.com/clinikehr/sdk-typescript, with a signed provenance statement.
  • The Python client follows.
Start with the TypeScript client guide.
API
Data protection addendum 2026-10-09

A new version of the data protection addendum

Version 2026-10-09 of the data protection addendum for organizations adds two sections. You do not need to accept it again: acceptances of 2026-10-03 stay valid, and an organization accepting now accepts 2026-10-09.
  • 3A — if a clinic links you to an insurer (clinics on the insurance setup for outside the US): you receive only that insurer’s enrollees, plans, claims and authorization requests at that clinic, only to administer its cover; your decisions and payment advices move no money; the clinic can end the link at any time.
  • 3B — information we do not provide: medication information a clinic holds only through its electronic prescribing connection is never provided to an organization, and a clinic cannot waive this.
API
v1

Prescriptions held only in the clinic’s e-prescribing service go to the clinic’s own keys

The e-prescribing network’s rules do not allow its information to be passed on to outside organizations, even with the clinic’s permission. So a prescription that exists only in a clinic’s e-prescribing service, and was not written in ClinikEHR, is now returned only to keys the clinic created for its own systems.
  • An organization’s key no longer receives these prescriptions from GET …/prescriptions, and GET …/prescriptions/{prescription_id} answers 404 for them.
  • Prescriptions written in ClinikEHR are unchanged, including ones that were sent electronically.
See Medications.
APIWebhooks
v1

Insurance for HMOs and insurers

An HMO or insurer can now work with the clinics it serves through the API, and developers can build billing tools for those clinics. It is for clinics that use the non-US insurance setup.
  • Clinics decide who is an insurer. A clinic owner or manager links a connected organization to one of the clinic’s insurer records under Settings → API access → Insurer links. An insurer sees only its own enrollees, plans, claims and authorization requests; anything else answers 404.
  • Verify and read: GET …/insurance/enrollees (verify by insurance_no), …/insurance/plans, …/insurance/claims and …/insurance/pre-authorizations, with their lines, diagnoses and document details.
  • Vet a claim: POST …/insurance/claims/{claim_id}/adjudication approves, adjusts or declines each line with a reason. It can never approve more than was billed, never moves money, and stops once the clinic has recorded a payment.
  • Decide an authorization request: POST …/insurance/pre-authorizations/{pa_id}/decision approves it with a pa_code or denies it with a reason.
  • Tell the clinic what you paid: POST …/insurance/payment-advices. It is an advice for clinic staff to reconcile and changes nothing in the clinic’s books.
  • Submit a claim (POST …/insurance/claims) or an authorization request (POST …/insurance/pre-authorizations) as a developer, for a patient the clinic has linked to you.
  • Events: insurance.claim.submitted, insurance.claim.adjudicated, insurance.claim.paid, insurance.pa.requested and insurance.pa.decided, delivered to an insurer only for its own records.
  • New permissions and errors: nine insurance.* permissions, a new patient-data kind (Insurer claims, authorizations and enrollees), and the codes hmo_not_linked and insurance_region_unsupported.
  • Fixed: the change feed (GET …/events) could not return a page; it now does.
Start with Insurance for HMOs and insurers.
API
v1

Changing an appointment now tells the people it concerns

Changing a booked appointment through the API used to email the patient only when the time moved, and only the first time. Now the right people hear about each change.
  • Patient and participants: changing start_at, clinician_id or venue_type on a live appointment that is still booked and in the future emails them. A new time is a reschedule notice; a new clinician or venue is an “Appointment updated” notice. Each later change sends its own notice, and the patient’s reminder moves to the new time.
  • Clinicians: the new clinician is told a visit was added, the previous one that it was removed, and the current one that it moved, in the app and by email, following the clinic’s and each clinician’s notification settings.
  • email_notifications on an appointment covers every email the patient receives about it, not only reminders. With it false the patient is not emailed about a change, but the clinicians still are.
  • Test-key appointments still never send email. Requests and responses are unchanged. See Appointments.
API
v1

Archive, restore, delete and write off inventory

Your integration can now retire inventory as well as read it, with the same key.
  • Restore an archived item: POST …/inventory/items/{item_id}/restore brings it back for sale and dispensing. Archiving an item now also accepts an optional reason, and the response is the item under data, as the other writes are. See Inventory.
  • Delete an item that was never used: DELETE …/inventory/items/{item_id} removes it for good, but only if it has never held stock or been part of an order, count, recipe or dispense. Anything with history is refused with item_has_history, and the answer is to archive it.
  • Write off a lot: POST …/inventory/lots/{lot_id}/write-off records the lot’s remaining stock as wasted and archives the lot. It needs a reason and an Idempotency-Key, so a retry cannot write a lot off twice.
  • Filter the catalogue by status: GET …/inventory/items?status=active|archived|all. The default is all, so existing calls return what they always did. Each item now carries archived_at, empty while the item is active.
  • Two new error codes, item_has_history (409) and reason_required (400). See Errors.
API
v1

CRM search returns the full contact, and note templates return their fields

  • CRM contact search now answers with the full contact, exactly as reading it by id does. Before, do_not_contact, unsubscribed_at, consent_at and other fields came back null in a search result. Check them before contacting anyone. See CRM.
  • Getting a note template (GET …/note-templates/{template_key}) now returns the template’s fields. It used to answer an empty list for every template. See Notes.
  • Idempotency-Key is now shown on every request that reads it, in the API reference, the SDKs and the Postman collection, marked required or optional. Nothing changed in what the API accepts. See Retries and idempotency.
APIPortal
v1

The API Terms of Use are in force, and approved organizations can now receive patient information

The legal terms for using the API are now published, and the path to patient information is open for organizations that have been approved for it.
  • API Terms of Use and Acceptable Use Policy, version 2026-10-03. An owner or administrator accepts them once for the workspace. Creating a new live key needs the acceptance now. Live keys a workspace already has keep working for 30 days, then pause until the terms are accepted. Test keys are never affected. See Terms of Use.
  • Data Protection Addendum for Organizations, version 2026-10-03. An organization accepts it before it receives any patient information. See Data Protection Addendum.
  • Patient information, for approved organizations only. Apply on Settings → Verification. Once your organization is approved and has accepted the addendum, Connect to a clinic lets you request the patient-data kinds you were approved for, and the clinic decides what to grant. Nothing changes for an organization that has not applied. See Connections.
API
v1

Items you send can now be accepted automatically when a clinic chooses

A clinic’s owner or manager can choose, for one key or one connected organization and for each kind separately, to accept your new allergies, conditions, reported medicines and referrals without review. It is off until the clinic turns it on, and you cannot request or detect it. Every field below is new and optional to read. See Automatic acceptance.
  • The answer to a send can already be decided. It is still 202 Accepted with a Location, but the submission may show review_status: "confirmed", result_record_id and a new accepted_automatically: true (false otherwise). Read the body, not the status code.
  • The record says how it got there. Allergies, conditions, reported medicines and referrals carry accepted_by (automatic, clinic, or null while not yet accepted), and reviewed_at and reviewed_by_staff_id, which stay null until a clinician marks an automatically accepted item reviewed.
  • Not presented as checked. An item accepted automatically reads verification_status: "unconfirmed" (and unconfirmed in FHIR, with an accepted_by extension) until a clinician reviews it. Updates, retractions and “no known allergies” are never accepted automatically, and an item accepted automatically can no longer be changed or withdrawn (409 submission_not_pending).
  • It pauses on unusual volume, after which your items wait for review again, and a rolled key or a new connection starts with it off.
  • Removed: 409 allergy_exists. Sending an allergy the patient already has is no longer refused. It is accepted into review (202) and a clinician can decline it, and a duplicate is never added to the chart or accepted automatically. If your code handled allergy_exists, that branch will no longer run. See Allergies.
API
v1

Encounters: read a patient’s visits, and open a draft visit for a clinician to complete

Show a patient’s visits in your own app, and open a visit from a scheduling or intake system. A visit is the clinic’s visit note, so an encounter and its note share one id. See Encounters.
  • Read a patient’s visits: GET /v1/clinics/{clinic_id}/encounters and GET /v1/clinics/{clinic_id}/encounters/{encounter_id}, permission encounters:read. Each carries status (draft or completed), class, period, reason and the clinician, and never any clinical text or billing. Notes the clinic marked sensitive are not listed. Also available as FHIR Encounter.
  • Open a draft visit with POST, permission encounters:write. The answer is 201 Created and Idempotency-Key is required. The visit appears in the clinic’s consultation list, marked From your app and not yet reviewed, for a clinician to complete. Nothing is ordered, prescribed, billed, signed or finalised, and there is no field for note text.
  • Change the type, start, end or reason of a draft your app opened with PATCH, until a person touches it. Once a clinician edits the draft, including its visit details, or signs it, the change is refused with 409 note_not_editable. See Errors.
  • Permissions: encounters:read and encounters:write can now be given to a key, and the Visits kind can be requested in an organization’s application. See Permissions.
  • Clinicians can now edit a visit’s details on any note, and a visit with no type shows as unknown in FHIR rather than as a guessed type.
  • A note’s text still comes from the Notes routes: notes created through the API cannot carry treatment, service or diagnosis blocks.
API
v1

Referrals: read the referrals a clinic has received, and send one for review

Connect a referring practice’s system to the clinic it refers to. A referral you send is reviewed by the clinic before it joins its referral list, and the clinic alone decides to accept, decline or book it. See Referrals.
  • Read a patient’s referrals: GET /v1/clinics/{clinic_id}/referrals and GET /v1/clinics/{clinic_id}/referrals/{referral_id}, permission referrals:read. Each carries the clinic’s workflow status (received, accepted, scheduled, completed, declined, cancelled, entered_in_error). Also available as FHIR ServiceRequest.
  • Send a referral with POST, permission referrals:write. The answer is 202 Accepted with a Location header, and Idempotency-Key is required. Follow it with GET /v1/clinics/{clinic_id}/submissions/{submission_id}.
  • Change or take back a referral you sent with PATCH, only while the clinic has not acted on it. After the clinic accepts, declines or books it, a change is refused with 400 invalid_request. No request can accept, decline, book, complete or cancel a referral.
  • ICD-10 reason codes are checked against a verified list, and one that is not a real ICD-10 code is refused.
  • A reason stays private. The reason the clinic gives for declining or cancelling is shown only to the key or organization that sent the referral.
  • Permissions: referrals:read and referrals:write can now be given to a key, and the Referrals kind can be requested in an organization’s application. See Permissions.
API
v1

Providers and outside care providers: read the clinic’s clinicians, and keep a patient’s outside contacts

Show who a patient will see, and keep the doctors, referrers and specialists a patient names up to date. See Providers and Outside care providers.
  • Read the clinic’s clinicians: GET /v1/clinics/{clinic_id}/providers and GET /v1/clinics/{clinic_id}/providers/{provider_id}, permission providers:read. Each carries name, role, specialties, NPI and licences. It is read-only, holds no contact details and no verified flag, and is not a patient-data permission. Also available as FHIR Practitioner.
  • Read a patient’s outside care providers: GET /v1/clinics/{clinic_id}/care-providers and GET /v1/clinics/{clinic_id}/care-providers/{care_provider_id}, permission care_providers:read. Every contact is listed with source and a new editable flag.
  • Add one with POST, permission care_providers:write. The answer is 201 Created and Idempotency-Key is required. It is saved straight away and appears at the clinic marked From your system.
  • Change or remove only what your app added. PATCH and the new DELETE (204 No Content) work on contacts your app added. On a contact the clinic or another app added they are refused with 409 care_provider_clinic_managed. See Errors.
  • Permissions: providers:read, care_providers:read and care_providers:write can now be given to a key, and the Outside care team kind can be requested in an organization’s application. See Permissions.
  • The Patients routes keep showing care_providers as read-only; use the new routes to add one.
API
v1

Medications: read reported medicines and prescriptions, and send a reported medicine for review

Connect an intake or records system to the medicines a patient reports taking, and read the prescriptions written for them. A reported medicine you send is reviewed by a clinician before it reaches the chart. See Medications.
  • Read a patient’s reported medicines: GET /v1/clinics/{clinic_id}/medication-statements and GET /v1/clinics/{clinic_id}/medication-statements/{medication_statement_id}, permission medications:read. Also available as FHIR MedicationStatement.
  • Send a reported medicine, or ask for a change, with POST and PATCH, permission medications:write. The answer is 202 Accepted with a Location header, and nothing reaches the chart until a clinician accepts it. Follow it with GET /v1/clinics/{clinic_id}/submissions/{submission_id}.
  • Read a patient’s prescriptions: GET /v1/clinics/{clinic_id}/prescriptions and GET /v1/clinics/{clinic_id}/prescriptions/{prescription_id}, permission medications:read. They are read-only and carry only the drug, dose, frequency, status and dates; prescriptions sent electronically are included with source: "eprescribe". Also available as FHIR MedicationRequest. No request can create or change a prescription.
  • RxNorm codes on a reported medicine are accepted only when they are on our verified list. A code we do not recognise is refused; send the medicine as text, or with a local code.
  • Pharmacy checks use it. A confirmed reported medicine with a recognised code is included in the clinic’s drug interaction checks while it is active. One without a recognised code is shown to the pharmacist as not checked, and is never matched by its name.
  • ICD-10 codes are now validated. A condition sent with an icd-10-cm or icd-10 code that is not a real ICD-10 code is refused with invalid_request. Before, only the shape of the code was checked.
  • Permissions: medications:read and medications:write can now be given to a key, and the Medications kind can be requested in an organization’s application. See Permissions.
  • The Patients routes keep refusing current_medications; send reported medicines here instead.
API
v1

Allergies: read a patient’s allergies and send one for review

Connect an intake or records system to a patient’s allergies and intolerances. An allergy you send is reviewed by a clinician before it reaches the chart. See Allergies.
  • Read a patient’s allergies: GET /v1/clinics/{clinic_id}/allergies and GET /v1/clinics/{clinic_id}/allergies/{allergy_id}, permission allergies:read. Also available as FHIR AllergyIntolerance.
  • Send a new allergy, or ask for a change, with POST and PATCH, permission allergies:write. The answer is 202 Accepted with a Location header, and nothing reaches the chart until a clinician accepts it. Follow it with GET /v1/clinics/{clinic_id}/submissions/{submission_id}, which now works for the kind of item you sent.
  • Names on the clinic’s plain allergy list are returned too, as read-only items with entry: "legacy_text" and no id, so a patient is never shown as having no allergies when the chart says otherwise. An empty list does not mean “no known allergies”.
  • RxNorm codes are accepted only when they are on our verified list. A substance such as “none” or “NKDA” is refused.
  • Permissions: allergies:read and allergies:write can now be given to a key, and the Allergies kind can be requested in an organization’s application. See Permissions.
  • “No known allergies” can be sent as a statement. It is reviewed like an allergy, and a clinician cannot confirm it while the patient has an active allergy on the chart.
  • Breaking change, Patients routes: creating, updating or importing a patient no longer accepts allergies, current_medications or chronic_conditions. A request that includes any of them is refused. These fields used to write the patient’s record directly, with no review. Send allergies with Allergies and conditions with Conditions instead; both are reviewed by a clinician before they reach the chart. Current medications cannot be set through the API.
  • New error code allergy_exists (409): the patient already has an active, confirmed allergy to that substance.
  • FHIR Condition fix: the extra ClinikEHR fields on a FHIR Condition (review_status, source, origin_assistant_name, submission_id, decision_reason) are now valid FHIR extensions, each carrying a valueString. Before, they carried a bare value, which FHIR validators reject.
  • Blank notes created through the API no longer accept order or billing content (diagnosisData, treatment_plans, follow_up_plans, services, diagnoses) or underscore-prefixed fields; such a request is refused with unknown_field.
API
v1

Insurance: list a clinic’s payers, read and add a patient’s coverage

For clinics on the US insurance setup. Clinics outside the US use Insurance for HMOs and insurers.Connect an intake or eligibility system to a patient’s insurance. A coverage you add stays inactive until the clinic’s staff confirm it. See Insurance.
  • Payers: GET /v1/clinics/{clinic_id}/payers and GET /v1/clinics/{clinic_id}/payers/{payer_id}, permission payers:read. Only the payers the clinic has enabled under Settings → Insurance are listed.
  • Coverage: read with GET /v1/clinics/{clinic_id}/coverages and …/coverages/{coverage_id} (coverage:read). Add with POST (201, Idempotency-Key required) and change with PATCH (coverage:write).
  • Confirm before active: a coverage you add is unconfirmed and inactive. Staff confirm it at the clinic, and only then can it be used for eligibility checks and claims. Changing a confirmed coverage’s payer, member ID or subscriber returns it to unconfirmed.
  • FHIR: read a coverage as Coverage and a payer as Organization with Accept: application/fhir+json.
  • Permissions: payers:read, coverage:read and coverage:write can now be given to a key, and the Insurance coverage kind can be requested in an organization’s application. See Permissions.
  • Three new error codes, all 409: coverage_exists, payer_not_enabled and activation_requires_staff.
API
v1

Conditions: read a patient’s problem list and send a diagnosis for review

The first clinical resource that goes through clinician review. See Conditions.
  • Read a patient’s problem list: GET /v1/clinics/{clinic_id}/conditions and GET /v1/clinics/{clinic_id}/conditions/{condition_id}, with permission conditions:read. Also available as FHIR Condition.
  • Send a new condition, or ask for a change, with POST and PATCH, permission conditions:write. The answer is 202 Accepted with a Location header. Nothing reaches the chart until a clinician accepts it. Marking a condition entered_in_error is a retraction, reviewed the same way.
  • Follow it with GET /v1/clinics/{clinic_id}/submissions/{submission_id}, or list your own with review_status.
  • Permissions: conditions:read and conditions:write can now be given to a key, and the Conditions kind can be requested in an organization’s application. See Permissions.
  • Two new error codes: client_reference_conflict and submission_not_pending, both 409.
API
v1

The FHIR guide now matches the API, and there is a page for SDKs and Postman

The FHIR guide had drifted from what the API does. It is corrected, and two new pages are added.
  • FHIR R4 no longer says FHIR is not deployed. It now says updates are PATCH (never PUT), that a write is answered in our plain JSON shape, and lists the search parameters each resource accepts.
  • SDKs and Postman says what exists, that the TypeScript and Python libraries are not published yet, and how to use the Postman collection against https://api.clinikehr.com/v1.
  • Reviewing outside submissions explains pending, confirmed and rejected, and 202 Accepted. No endpoint uses it yet.
  • The overview no longer says CRM has no route. CRM contacts and activities are patient-data permissions like the others.
Portal
v1

Workspace settings have their own sidebar, and your account has its own page

The Settings entry in the dashboard no longer opens a drop-down. Workspace settings now sit in a sidebar of their own (a menu at the top of the page on a phone or tablet), and each page is shown only to the roles that can use it.
  • Profile and Settings in the header now opens your own account page — your name, password, two-factor authentication and passkeys, and email preferences. It previously led to a page that did not exist.
  • See Workspace settings and your account.
  • The API keys list now fits a phone and pages once you have more than ten keys. Each key shows its first two permissions with a +N for the rest, and selecting a key opens a panel with its full permissions, dates, allowed addresses and status. See Authentication.
  • Creating a key and adding a webhook endpoint each have a Select all box above their lists, and a key’s ID says plainly that it is not the key.
  • Documentation and API Reference buttons now sit in the header, just before the Test / Live switch, and open this site in a new tab (on a phone they are in the menu).
  • The Overview request card now counts requests made today, and shows how many succeeded, were refused (4xx) or failed (5xx), with a per-day chart. Before, requests made today were left out, so a new workspace could read “No requests in this environment yet.”
  • The Test / Live switch is now clear on every page. A strip under the header always says which mode you are in (red on Live), the choice is remembered when you reload or follow a link without it, and API keys, Request logs, Webhooks and Overview each say which mode they show. Webhooks now list only the endpoints for the mode you are in. Members, Plan, Settings and the other workspace pages are the same in both modes.
  • Agreements now shows the full API Terms of Use, with the Acceptable Use Policy, and, for an organization applying for patient data, the Data Protection Addendum for Organizations. An Admin or Owner accepts the terms for the workspace. A live key cannot be created until they are accepted; a workspace that already had live keys has 30 days from publication before they pause. See Workspace settings and your account.
SandboxPortalWebhooks
v1

Try every resource in your sandbox, with a request to paste for each

The Sandbox page in your workspace now says exactly what is in your sandbox and gives you a ready-to-paste request for each resource. A test key can now hold the patient-data permissions, because it reaches only your workspace’s sandbox — invented patients, notes and appointments, never a real clinic.
  • Patients, notes and appointments: six invented patients (named “SANDBOX”), four invented notes, and invented services and clinicians with weekly hours. Create, read, change and cancel patients and notes; book and cancel appointments (to move one, cancel it and book again). Nothing is sent to anyone.
  • Network search: searching by name or barcode now returns results from the sample pharmacies, and feedback on a result is accepted.
  • Your own medicine codes: four sample codes, one in each state; list, read, upload and delete them.
  • Reset sandbox puts all of it back to the starting data.
  • Webhooks is the new name of the Notifications page; the old address redirects.
  • Referred pharmacies now shows an explanation instead of an error when you have not referred anyone yet.
PortalWebhooks
v1

Manage webhook endpoints and your own medicine codes from the dashboard

The Webhooks (previously called Notifications — the old address redirects) and Partner codes pages in your workspace now do what they describe. Both need the Admin role or higher in the workspace.
  • Webhooks: add an endpoint, send a test event, read the delivery log, replay a delivery that failed, rotate the signing secret, and delete an endpoint. The signing secret is shown once, when you create or rotate it — copy it then. See Verifying a webhook’s signature.
  • Partner codes: upload a CSV of your own medicine codes, see which matched automatically, which are waiting for a pharmacist’s confirmation and which did not match, and delete a code you no longer want. See Uploading your own medicine codes.
  • The Connect to a clinic sheet now says plainly that patient information can’t be requested yet: an organization can’t receive patient data today, on any plan.
APIPortal
v1

Find and check a pharmacy across the network, before you have a direct connection

Two new routes let your organization discover a pharmacy and check what it has, without connecting to it first: GET /v1/listings/pharmacies lists pharmacies that have listed themselves to your organization, and POST /v1/listings/search searches by barcode, NAFDAC number, or name across all of them at once.
  • Requires listing.profile:read (for the list) or listing.availability:read (for a search) — new scopes, granted the same way as any other connection scope.
  • A search result’s availability can come back unknown when a pharmacy’s own point-of-sale hasn’t synced recently — see Stock bands for what that means and why it’s never shown as out of stock.
  • Once you hold a connection to a specific pharmacy, its full listing is also readable directly: GET /v1/clinics/{clinic_id}/listing/profile and .../listing/items.
BillingPortal
v1

See your workspace’s plan and this month’s usage before you go live

Every developer portal workspace now has a plan — Sandbox to start, Essential or Enterprise once you’re ready for a live key — with a dashboard page showing exactly where you stand.
  • Plan & usage, inside your workspace, shows this month’s requests and connected clinics against what’s included, and this month’s computed overage charge so far, in USD and NGN.
  • Going over Essential’s included requests or connected clinics is billed automatically — a live key is never interrupted mid-month for it. See Usage and billing.
  • A live key on a workspace still on the Sandbox plan is refused with code: "workspace_plan_required" until the workspace is on a paid plan — see Plans and pricing and Errors.
APIPortal
v1

Approve, narrow, or revoke exactly what another organization can reach

A clinic can now approve a connection from an outside organization item by item, instead of an all-or-nothing grant — and see, at any time, exactly what it has shared.
  • GET /v1/connections lists every clinic (or, for a test key, your sandbox) a key currently reaches, with the scopes actually granted for each one.
  • A clinic narrows or revokes what’s granted at any time — a revoked connection stops answering on your very next call, nothing to catch or retry around.
  • See Connections.
SandboxPortal
v1

Build against a sandbox before you ever touch a real clinic

Signing up for a developer portal workspace now gets you an ehr_test_ key immediately — no verification needed — that reaches a fixed, fictional clinic seeded with synthetic inventory. The same router, the same validation, the same error codes as a live key; only the data behind it is fake.
  • A test key can never reach a real clinic, and a live key can never reach the sandbox — each direction is refused, not just discouraged.
  • Moving to a live key needs your workspace verified (a domain check plus a completed profile) and on a paid plan — see Authentication.
  • See the two ways to use this API for how a clinic’s own key and an organization’s key differ.
API
v1

Read a clinic’s own inventory straight from your own systems

A clinic can create a key, under its own Settings → API access, that reads straight out of its ClinikEHR workspace — no separate account, no separate documentation to reconcile.
  • Three read scopes: inventory.availability:read (a band, not a number), inventory.items:read (catalogue detail), and inventory.stock:read (exact quantities, the most sensitive of the three).
  • Every list is cursor-paginated and accepts updated_since, so a periodic sync only pulls what changed — see Pagination.
  • Every failure is a consistent application/problem+json body with a stable code you can branch on — see Errors.
  • See Inventory and Getting a key.