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).
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.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.
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 agtinidentifier) are documented in the types as needing a valid GTIN, with400 invalid_gtinwhen they do not, and an item update that sends back the sameupcis accepted.
state value and treats an unknown one as impossible. Update with npm install @clinikehr/[email protected] or pip install clinikehr==0.4.0.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’supc, 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’supcon create and update. Nothing is saved when a request is refused. Thebarcodefilter onGET /v1/inventory/itemsis 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
barcodeis refused on its own ("state": "error", reason startinginvalid_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
upcan 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 differentupcmust be valid. (The check reads the item with your key, so it needsinventory.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 thaninvalid_gtin.) Creating an item always checks theupc. - 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 uses5000000000005). 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.
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_controlledon inventory items, read-only. See Inventory.line_idon Pharmacy-edition pickup lines, the value you send inline_idsto collect part of a pickup. See Prescription pickups.signature_datais 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).
npm install @clinikehr/[email protected] or pip install clinikehr==0.3.0.See which inventory items a clinic has marked as controlled
Inventory items now carry a read-onlyis_controlled flag, so your integration can tell a controlled medicine from an ordinary one without keeping its own list.is_controlledon every item in the item list and the single item. It istruewhen 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
falseeverywhere.
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 theline_idvalues you want to hand over inline_idson the collection request; the lines you leave out stay on a new awaiting pickup. For a prescription lineline_idequals itsprescription_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_dataon 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, readinghas_signature: false. When the clinic requires a signature, a request without one is refused with400 signature_required(see Errors). A signature you send is always checked.
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 withpickups: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, withoutreach:write. - Both need the same patient-data access as the other patient records. A submission’s
resource_typecan now beprescription_pickup_collectionoroutreach_checkin, and a submission says whether a signature came with it (has_signature). - New webhook events:
prescription_pickup.collectedandoutreach_event.attendee_checked_in.
A narrow permission for stock reports, and stricter stock reports
inventory.external_stock:writelets 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 withinventory.stock:writestill 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.
Pharmacy listings show the online store
A pharmacy listing now carriesstore_url: the address of the pharmacy’s online store, when it runs one.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; theasynciovariants are not usable yet. In an async program, run a call in a worker thread. - Install only
clinikehrfrom PyPI, and nothing of that name from anyone else.
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.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.The TypeScript client updates records too
Version 0.1.3 sends anIdempotency-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.Six fixes found by running the whole API end to end
- The change feed works.
GET /v1/clinics/{clinic_id}/eventsanswered404 not_foundfor 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
PATCHon 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 withslot_taken). See Appointments. - Creating or updating a note returns the whole note. The answer used to show
content: nullandcitations: 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
urlthat does not start withhttp://orhttps://is refused withinvalid_request, naming/citations/N/url. - CRM contact values are checked. A
record_type,lifecycle_stage,priorityorsourceoutside the documented values is refused withinvalid_requestand a field-levelerrorslist, instead of being stored (test keys) or answered with a server error (live keys). See CRM. - Rate-limit headers tell the truth.
RateLimit-Resetwas always60; it now gives the seconds until your allowance is full again. A429now carriesRateLimit-Limit,RateLimit-Remaining: 0andRateLimit-Resetas well asRetry-After, as Rate limits always said. That page now explains how the limit refills.
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.2or 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.
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.
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, andGET …/prescriptions/{prescription_id}answers404for them. - Prescriptions written in ClinikEHR are unchanged, including ones that were sent electronically.
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 byinsurance_no),…/insurance/plans,…/insurance/claimsand…/insurance/pre-authorizations, with their lines, diagnoses and document details. - Vet a claim:
POST …/insurance/claims/{claim_id}/adjudicationapproves, 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}/decisionapproves it with apa_codeor 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.requestedandinsurance.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 codeshmo_not_linkedandinsurance_region_unsupported. - Fixed: the change feed (
GET …/events) could not return a page; it now does.
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_idorvenue_typeon 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_notificationson an appointment covers every email the patient receives about it, not only reminders. With itfalsethe 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.
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}/restorebrings it back for sale and dispensing. Archiving an item now also accepts an optionalreason, and the response is the item underdata, 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 withitem_has_history, and the answer is to archive it. - Write off a lot:
POST …/inventory/lots/{lot_id}/write-offrecords the lot’s remaining stock as wasted and archives the lot. It needs areasonand anIdempotency-Key, so a retry cannot write a lot off twice. - Filter the catalogue by status:
GET …/inventory/items?status=active|archived|all. The default isall, so existing calls return what they always did. Each item now carriesarchived_at, empty while the item is active. - Two new error codes,
item_has_history(409) andreason_required(400). See Errors.
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_atand other fields came backnullin 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-Keyis 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.
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.
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 Acceptedwith aLocation, but the submission may showreview_status: "confirmed",result_record_idand a newaccepted_automatically: true(falseotherwise). 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, ornullwhile not yet accepted), andreviewed_atandreviewed_by_staff_id, which staynulluntil a clinician marks an automatically accepted item reviewed. - Not presented as checked. An item accepted automatically reads
verification_status: "unconfirmed"(andunconfirmedin FHIR, with anaccepted_byextension) 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 handledallergy_exists, that branch will no longer run. See Allergies.
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 oneid. See Encounters.- Read a patient’s visits:
GET /v1/clinics/{clinic_id}/encountersandGET /v1/clinics/{clinic_id}/encounters/{encounter_id}, permissionencounters:read. Each carriesstatus(draftorcompleted),class,period,reasonand the clinician, and never any clinical text or billing. Notes the clinic marked sensitive are not listed. Also available as FHIREncounter. - Open a draft visit with
POST, permissionencounters:write. The answer is201 CreatedandIdempotency-Keyis 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 with409 note_not_editable. See Errors. - Permissions:
encounters:readandencounters:writecan 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.
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}/referralsandGET /v1/clinics/{clinic_id}/referrals/{referral_id}, permissionreferrals:read. Each carries the clinic’s workflowstatus(received,accepted,scheduled,completed,declined,cancelled,entered_in_error). Also available as FHIRServiceRequest. - Send a referral with
POST, permissionreferrals:write. The answer is202 Acceptedwith aLocationheader, andIdempotency-Keyis required. Follow it withGET /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 with400 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:readandreferrals:writecan now be given to a key, and the Referrals kind can be requested in an organization’s application. See Permissions.
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}/providersandGET /v1/clinics/{clinic_id}/providers/{provider_id}, permissionproviders: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 FHIRPractitioner. - Read a patient’s outside care providers:
GET /v1/clinics/{clinic_id}/care-providersandGET /v1/clinics/{clinic_id}/care-providers/{care_provider_id}, permissioncare_providers:read. Every contact is listed withsourceand a neweditableflag. - Add one with
POST, permissioncare_providers:write. The answer is201 CreatedandIdempotency-Keyis required. It is saved straight away and appears at the clinic marked From your system. - Change or remove only what your app added.
PATCHand the newDELETE(204 No Content) work on contacts your app added. On a contact the clinic or another app added they are refused with409 care_provider_clinic_managed. See Errors. - Permissions:
providers:read,care_providers:readandcare_providers:writecan 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_providersas read-only; use the new routes to add one.
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-statementsandGET /v1/clinics/{clinic_id}/medication-statements/{medication_statement_id}, permissionmedications:read. Also available as FHIRMedicationStatement. - Send a reported medicine, or ask for a change, with
POSTandPATCH, permissionmedications:write. The answer is202 Acceptedwith aLocationheader, and nothing reaches the chart until a clinician accepts it. Follow it withGET /v1/clinics/{clinic_id}/submissions/{submission_id}. - Read a patient’s prescriptions:
GET /v1/clinics/{clinic_id}/prescriptionsandGET /v1/clinics/{clinic_id}/prescriptions/{prescription_id}, permissionmedications:read. They are read-only and carry only the drug, dose, frequency, status and dates; prescriptions sent electronically are included withsource: "eprescribe". Also available as FHIRMedicationRequest. 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
localcode. - 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-cmoricd-10code that is not a real ICD-10 code is refused withinvalid_request. Before, only the shape of the code was checked. - Permissions:
medications:readandmedications:writecan 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.
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}/allergiesandGET /v1/clinics/{clinic_id}/allergies/{allergy_id}, permissionallergies:read. Also available as FHIRAllergyIntolerance. - Send a new allergy, or ask for a change, with
POSTandPATCH, permissionallergies:write. The answer is202 Acceptedwith aLocationheader, and nothing reaches the chart until a clinician accepts it. Follow it withGET /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 noid, 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:readandallergies:writecan 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_medicationsorchronic_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
Conditionfix: the extra ClinikEHR fields on a FHIRCondition(review_status,source,origin_assistant_name,submission_id,decision_reason) are now valid FHIR extensions, each carrying avalueString. Before, they carried a barevalue, 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 withunknown_field.
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}/payersandGET /v1/clinics/{clinic_id}/payers/{payer_id}, permissionpayers:read. Only the payers the clinic has enabled under Settings → Insurance are listed. - Coverage: read with
GET /v1/clinics/{clinic_id}/coveragesand…/coverages/{coverage_id}(coverage:read). Add withPOST(201,Idempotency-Keyrequired) and change withPATCH(coverage:write). - Confirm before active: a coverage you add is
unconfirmedand 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 tounconfirmed. - FHIR: read a coverage as
Coverageand a payer asOrganizationwithAccept: application/fhir+json. - Permissions:
payers:read,coverage:readandcoverage:writecan 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_enabledandactivation_requires_staff.
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}/conditionsandGET /v1/clinics/{clinic_id}/conditions/{condition_id}, with permissionconditions:read. Also available as FHIRCondition. - Send a new condition, or ask for a change, with
POSTandPATCH, permissionconditions:write. The answer is202 Acceptedwith aLocationheader. Nothing reaches the chart until a clinician accepts it. Marking a conditionentered_in_erroris a retraction, reviewed the same way. - Follow it with
GET /v1/clinics/{clinic_id}/submissions/{submission_id}, or list your own withreview_status. - Permissions:
conditions:readandconditions:writecan 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_conflictandsubmission_not_pending, both409.
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(neverPUT), 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.
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.
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.
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.
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) orlisting.availability:read(for a search) — new scopes, granted the same way as any other connection scope. - A search result’s availability can come back
unknownwhen 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/profileand.../listing/items.
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.
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/connectionslists 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.
Build against a sandbox before you ever touch a real clinic
Signing up for a developer portal workspace now gets you anehr_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.
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), andinventory.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+jsonbody with a stablecodeyou can branch on — see Errors. - See Inventory and Getting a key.