Building a Health-Insurance Startup for Emerging Markets: What Your Hospital Integration Must Do (2027 Developer Guide)

You are an insurtech founder building health insurance for an emerging market, and you need a hospital integration. The hospital holds the members, approval requests, claims and payments your code needs. This guide maps what the integration must cover to the ClinikEHR API (api.clinikehr.com) and its documentation. ClinikAPI (clinikapi.com) is a different product, built around the FHIR health data standard, with its own site, keys and licence. ClinikEHR is not connected to any national claims exchange.

Quick Answer

A hospital integration for an insurer must cover eight things, and the ClinikEHR API documents each one on a published docs page.

• Look up members against the record the hospital holds, then run a pre-authorization round trip: one request and one decision.
• Vet each claim line by line and send payment advices, which are messages the hospital reconciles. No money moves through the API.
• Take five signed event types, keep each insurer's data apart, and make every write safe to retry.
• Collect two approvals: a ClinikEHR reviewer approves your organization, and each hospital's owner approves the connection.
• Accept the data-protection addendum, and test insurance with a live key against a linked hospital, because the insurance routes have no sandbox data.

What Is a Hospital Integration for an Insurer, in Plain Words

A hospital integration is a link that lets an insurer's software read what a hospital has recorded and answer it. An insurer, often called an HMO (health maintenance organization), pays all or part of a member's hospital bill. An enrollee is a member the insurer covers.

The hospital sends two kinds of request. A pre-authorization request asks the insurer to agree in advance to pay for something. A claim is the hospital's bill for care already given, with one line for each service or medicine. Adjudication, also called vetting, is the insurer's decision on each line. A pre-authorization (PA) code is the code the insurer gives when it approves a request. A payment advice is a note from the insurer saying what it paid.

The insurance routes of the ClinikEHR API return plain JSON. They do not return FHIR resources. FHIR is an international standard for how health records are shaped when two systems exchange them.

Before You Build: What This Integration Is and Is Not

It is not a national exchange

ClinikEHR is not connected to any national claims exchange or national insurance scheme, in any country. A connection to the ClinikEHR API is a private link that a hospital's owner can approve for one organization at a time.

The insurance routes serve a hospital whose owner has set Insurance to Outside the US, under Settings, General. That is a setting, not a place or a currency. A new hospital workspace starts on the United States setting, and a hospital on it is refused with insurance_region_unsupported, wherever it is. So this guide claims nothing about where ClinikEHR hospitals are.

The routes and their documentation are published at docs.clinikehr.com, and this guide follows them as read on 14 October 2026. It says nothing about which insurers use the routes.

Three roles: who you are to a hospital

The hospital decides what each connected organization is.

A startup that is not itself an insurer is a developer. A developer reads nothing of an insurer's data and is refused with hmo_not_linked if it tries.

Illustrative: a startup builds a claims-preparation tool, so it is a developer and submits claims for the patients a hospital linked to it. A startup that is itself an insurer is linked to the hospital's record of that insurer, and reads and acts on that insurer's rows only.

Two Enterprise plans, and what they are not

Two Enterprise plans must be in place before an organization's key can reach patient-level insurance data. They are a pair:

1. Your developer workspace is on the Enterprise contract plan. ClinikEHR sets it on request, through Contact us to go live. There is no self-serve checkout.
2. The hospital is on the Enterprise plan, with Allow API access switched on. That switch is off by default.

Enterprise here means the subscription plan, not the Enterprise Clinic type chosen at setup. The API add-on, which opens a hospital's own keys, plays no part for an organization's key. Do not confuse the pair with the hospital's own HMO billing inside ClinikEHR. That is available on any plan once its owner sets Insurance to Outside the US.

No test data for insurance

A test key reaches the rest of the API in a sandbox of invented data. For insurance, the documentation is plain:

A test key reaches only its own sandbox clinic, which holds no insurance data. Lists answer an empty page and reads answer 404. Writes also answer 404.

ClinikEHR API documentation, Insurance for HMOs and insurers

So insurance is tried with a live key against a hospital that has linked your organization. A test key still lets you call GET /v1/me and GET /v1/connections to see the shape of an answer.

The Eight Things Your Hospital Integration Must Cover

Each part below says what the integration must do, what the ClinikEHR API documents and the limit to plan around. Every insurance route starts with https://api.clinikehr.com/v1/clinics/YOUR_CLINIC_ID. The HMO claims tutorial holds the full claims walk-through.

1. Look Up Members Against the Record the Hospital Holds

Your product must know whether a patient is a member you cover. The route is GET /v1/clinics/YOUR_CLINIC_ID/insurance/enrollees?insurance_no=. Send the number the patient presented. It matches the member's number and their alternate number.

The route reads the enrollee record the hospital holds, as the hospital keyed it in. It does not ask the insurer, so it is not a live eligibility check. A number the hospital does not hold under your insurer comes back as 200 with an empty data list. No route creates or changes an enrollee. Here is the documentation's sample. It needs a live key and a linked hospital, and its member and key are examples.

curl "https://api.clinikehr.com/v1/clinics/YOUR_CLINIC_ID/insurance/enrollees?insurance_no=ABC-001234" \
  -H "Authorization: Bearer ehr_live_EXAMPLEKEYID0000000000_EXAMPLESECRET…"

{
  "data": [
    {
      "id": "0a1b2c3d-4444-4e5f-8a6b-23456789abcd",
      "insurance_company_id": "9d2e7a10-2222-4b3c-8d4e-123456789abc",
      "insurance_no": "ABC-001234",
      "firstname": "Ada",
      "lastname": "Okafor",
      "status": "AA",
      "valid_until": "2027-06-30",
      "plan": { "id": "7e1f0c2a-5555-4a6b-9c7d-3456789abcde", "name": "Gold", "code": "GLD" }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

• What you need: the insurance.enrollees:read scope (a scope is a named permission on your key) and an organization linked to the insurer.
• How you know it worked: the answer lists the member with a status code, such as AA for active. If the hospital holds no such number, the list is empty.
• The mistake people make: treating the answer as proof of cover today.

2. Run a Pre-Authorization Round Trip

A pre-authorization request is the hospital's ask, before treatment, for your agreement to pay. You see only requests the hospital has sent, never drafts. Read them with GET .../insurance/pre-authorizations. Decide one with POST .../insurance/pre-authorizations/PA_ID/decision and an Idempotency-Key, a header that makes a retry do the work once.

The decision is approved with a pa_code, or denied with a reason. The approved_amount defaults to the hospital's estimate and can never exceed it. A second decision on the same request is refused with 409 and invalid_status_transition. The pa_code then goes onto the claim. An approval is not a promise to pay, because the claim must still match it. Here is the documented decision, which needs a live key and a linked hospital:

curl -X POST "https://api.clinikehr.com/v1/clinics/YOUR_CLINIC_ID/insurance/pre-authorizations/PA_ID/decision" \
  -H "Authorization: Bearer ehr_live_EXAMPLEKEYID0000000000_EXAMPLESECRET…" \
  -H "Idempotency-Key: 0c6a4a56-6d0b-4a7d-8b53-6f2f0c9d1e22" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "approved", "pa_code": "AUTH-20261009-001", "approved_amount": 400 }'

• What you need: the insurance.pa:read and insurance.pa:decide scopes, and an organization linked to the insurer. The pre-authorization tutorial has the detail.
• How you know it worked: a read of the request shows status approved and your code, and the hospital sees the code on its own request.
• The mistake people make: posting a second decision to correct the first. A request is decided once.

3. Vet Claims Line by Line

A list row has no lines, so read one claim to get its lines, diagnoses and document names. Documents come as name, type and size only. Claims still being prepared are never shown to you.

A line carries the billed price and, where the hospital recorded one, a tariff code. That is the code for the item on the price list the hospital agreed with the insurer. The API compares nothing with a tariff. Your decision sets the approved figures, and they can never exceed what was billed. You send decision for the whole claim, approved or rejected. You may also send a status for single lines: approved, adjusted or declined. A declined line needs a reason, unless the body has a reason of its own. An adjusted line sets a lower qty_approved or unit_price_approved.

Vetting moves no money. Once the hospital has recorded a payment or a write-off (an amount it gives up collecting), the claim can no longer be vetted. The hospital picks one way of delivering claims to each insurer. For claims to reach your organization through the API, it must pick the ClinikEHR API channel. Here is the documented vetting request, which needs a live key and a linked hospital:

curl -X POST "https://api.clinikehr.com/v1/clinics/YOUR_CLINIC_ID/insurance/claims/CLAIM_ID/adjudication" \
  -H "Authorization: Bearer ehr_live_EXAMPLEKEYID0000000000_EXAMPLESECRET…" \
  -H "Idempotency-Key: 6b9f6c1e-1d7e-4f55-9a52-0c4c3b1c8a11" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approved",
    "items": [
      { "item_id": "LINE_ID_1", "status": "adjusted", "qty_approved": 1, "comment": "One unit covered" },
      { "item_id": "LINE_ID_2", "status": "declined", "reason": "Not covered by the plan" }
    ]
  }'

• What you need: the insurance.claims:read and insurance.claims:adjudicate scopes. Only an organization linked to the insurer may vet.
• How you know it worked: the answer is the claim with its lines. Every line approved as billed gives approved, every line declined gives denied, and anything else gives partially_approved.
• The mistake people make: expecting the API to compare a line with the hospital's agreed prices. It does not, and no route reads a tariff.

4. Take Payment Advices

A payment advice tells the hospital: we paid this much, by this method, against these claims. It is a message. It does not change a claim, the hospital's payments or its books. Staff record the money themselves, and only then does a claim move to partially_paid or paid.

Post one with POST .../insurance/payment-advices and an Idempotency-Key. The method is bank_transfer, eft, cheque or other. Each allocation names one of your claims that is waiting for payment, for no more than it still owes. The allocations cannot add up to more than the amount.

• What you need: the insurance.remittances:write scope. Listing advices needs it too.
• How you know it worked: the answer is the advice with status advised. The hospital sees it on its HMO receivables as Awaiting you. The claim reads paid only after staff record the money, and the advice then turns recorded or declined.
• The mistake people make: allocating more to a claim than it still owes.

5. Receive Events

An event tells you something changed, so your code does not have to keep asking. Five types exist: insurance.claim.submitted, insurance.claim.adjudicated, insurance.claim.paid, insurance.pa.requested and insurance.pa.decided. A webhook is an https address you register, which ClinikEHR calls with each event. An event carries ids, a number, a status and amounts, never a patient name or identifier, so your handler reads the record to see the new state. Two details trip people up. insurance.claim.paid follows the hospital's recording of a payment or write-off, not your advice. And insurance.pa.decided carries no pa_code, so read the request for it.

Every delivery is signed with HMAC-SHA256 (a signature made with a shared secret) over its id, its timestamp and the raw body, and the secret is shown once. If your endpoint was down, a change feed, GET /v1/clinics/YOUR_CLINIC_ID/events, pages with after_seq and a limit of 1 to 200. Events are kept for 30 days, and exist only once someone is listening. Insurance events reach only your own insurer's records, and a developer with no insurer link gets none. See events and signatures.

• What you need: insurance.claims:read for the three claim events and insurance.pa:read for the two authorization events. An Admin of your workspace also adds an https webhook address in the developer portal.
• How you know it worked: your handler checks the signature against the raw body, skips an id it has handled, then reads the record.
• The mistake people make: checking the signature against a re-serialized body. Use the raw body.

6. Keep Each Insurer's Data Apart

An insurer sees only its own rows. A record that belongs to a different insurer answers 404, exactly as a record that does not exist does. An unsent record and a restricted patient's record get the same 404, so the answer never tells you which.

The addendum says you use what you receive only to administer that insurer's cover.

• What you need: your organization linked to the hospital's record of your insurer, under Settings, API access, Insurer links. Only an owner or manager can link.
• How you know it worked: reading a claim of your insurer returns it, and any other id answers 404.
• The mistake people make: reading 404 as a fault in your code.

7. Get Both Approvals, Then the Link

Two approvals are needed. They are not substitutes, and a third act, the link, follows them.

First, a ClinikEHR reviewer approves your organization. You get your workspace verified: a DNS TXT record for your domain, a business profile, then Submit for review. You accept the API Terms of Use. Then an Admin or Owner applies for patient data access for the kind Insurer claims, authorizations and enrollees. The application states your purpose, the data you need, a legal basis and your safeguards. A reviewer decides, and the documentation states no timeline.

Second, each hospital's owner decides what to share. The owner generates a one-time connection code, valid from 24 hours up to 14 days, and hands it to you. You enter it in the developer portal. The owner reviews your request, may grant less than you asked for or nothing, records a legal basis and approves with a fresh second-factor sign-in. Third, the owner or a manager links your organization to the hospital's record of your insurer. Until then you count as a developer. The connections page documents each act.

Approval is not a clinic's permission: a clinic still decides whether to grant you any permission, and on what basis.

Data Protection Addendum for Organizations, section 1A

There is no directory of hospitals. A hospital can be reached only through a code its owner hands over, so plan one onboarding per hospital.

• What you need: DNS access, an Admin or Owner in your workspace, and a hospital owner who will generate the code.
• How you know it worked: GET /v1/connections lists the hospital with the scopes it granted.
• The mistake people make: assuming the reviewer's approval gives you access to a hospital.

8. Accept the Data-Protection Addendum

The Owner of your workspace accepts the Data Protection Addendum for Organizations, version 2026-10-09. It is an agreement between Bettar Platforms, Inc. and your organization, and it applies when you receive patient information through the API. Its main terms are these:

• You receive patient information as an independent controller: you decide how to protect and use it within the purpose the hospital agreed, and you answer for doing so lawfully. ClinikEHR is not your processor.
• You keep it secure: encrypted when stored and when sent, open only to people who need it, with a record of who accessed it.
• You keep it only as long as that purpose and the law require, and pass it on only to someone bound by terms at least as protective.
• You tell ClinikEHR and the hospital of unauthorized access within 72 hours.
• ClinikEHR records every disclosure. The hospital can see the record, and the patient can see which organizations received their information, never the information itself. The records are kept for seven years.

If your product moves patient information across a border, clause 8 matters:

Each party is responsible for making sure that any transfer of patient information it makes across a border is lawful where the information comes from and where it goes.

Data Protection Addendum for Organizations, section 8, Bettar Platforms, Inc.

You also agree not to transfer patient information to a country where you cannot protect it as the addendum requires. This guide describes no country's law and is not legal advice, so read the addendum with your own lawyer.

• What you need: the Owner of your workspace, on the Agreements page.
• How you know it worked: calls are no longer refused with agreement_required.
• The mistake people make: treating acceptance as legal clearance for your market.

Build It Safely: Retries, Currency, Paging and Keys

• Make every write safe to retry. Every POST needs an Idempotency-Key header. A repeat with the same key returns the first answer, marked idempotent_replay: true, and the same key with a different body is 409 idempotency_key_conflict. Make the key once per action, never per retry. See retries and idempotency.
• Keep each hospital's currency. Amounts are in the hospital's own currency, and a claim carries currency. A currency on a payment advice must be the hospital's. Store the currency beside every amount.
• Carry the codes. A claim carries diagnosis codes in icd_code, such as J06.9 in the documentation, and a line can carry a tariff_code.
• Page lists and expect limits. Pass the next_cursor you were given as starting_after, and never build one. The per-minute limit is per key, and past it you get 429 rate_limited with a Retry-After header. Errors carry a stable code, so branch on code, not on detail. See pagination, rate limits and errors.
• Protect the key. Every request uses one key, sent in the Authorization header, that starts ehr_live_ or ehr_test_. Keep it on your own server. Never put it in a URL, and never call the API from a browser or a phone app. See authentication.
• Use the libraries. Two client libraries are published, and both run on your own server. The TypeScript client needs Node.js 18 or later; use 0.1.3 or later, which is current. The Python client needs Python 3.11 or later, and 0.1.1 is current.

npm install @clinikehr/api
pip install clinikehr

import { createClient } from "@clinikehr/api";

const client = createClient({ apiKey: process.env.CLINIKEHR_API_KEY! });

The documentation shows the insurance routes only in curl, so this guide shows no library call for them. Check one against the TypeScript guide or the Python guide first.

One Claim From Request to Payment (Illustrative)

Illustrative: the figures below are invented to show the order of events. They are not data. No currency is named, because amounts are in the hospital's own currency.

A Starter List of Questions for Each Hospital

Illustrative: a list a startup could carry to its first hospital call.

• Is Insurance set to Outside the US?
• Is the hospital on the Enterprise plan, and is API access on?
• Which owner will generate the connection code?
• Which legal basis will the hospital record?
• Which of its insurer records will you be linked to?
• Which delivery channel is set for that insurer?

The checklist for connecting an HMO goes further.

Mistakes That Cost Insurtech Founders Time

• Asking for the wrong workspace plan. A verified workspace on the Essential plan gets live keys but never reaches patient data.
• Putting a launch date or a hospital count in a pitch. The reviewer's decision has no stated timeline, and each hospital's owner decides whether to connect.
• Letting a live key expire unnoticed. A live key has an end date you choose when you create it, at most 12 months away. After that date it is refused with 401 and invalid_key, like a revoked key.
• Building no plan for a connection that ends. The hospital can end the link or revoke the connection at any time. A revoke cannot be undone, so you need a brand-new code from the owner. A revoked connection drops out of GET /v1/connections and no longer answers.
• Keeping patient information after a connection ends. The addendum says to return or destroy what you hold for that hospital's patients, unless the law requires you to keep some.

Frequently Asked Questions

What must a hospital integration for an insurer cover?

It must cover eight things. Look up members against the record the hospital holds. Run a pre-authorization round trip. Vet claims line by line. Take payment advices and events. Keep each insurer's data apart. Get the approvals of a reviewer and of each hospital, and accept a data-protection addendum. The ClinikEHR API documents each one at docs.clinikehr.com.

Is ClinikEHR connected to a national claims exchange?

No. ClinikEHR is not connected to any national claims exchange or national insurance scheme, in any country. A connection to the ClinikEHR API is a private link that a hospital's owner can approve for one organization at a time.

How is the ClinikEHR API different from ClinikAPI?

The ClinikEHR API (api.clinikehr.com) is the API of the ClinikEHR app, and it works through a connected hospital's account. ClinikAPI (clinikapi.com) is a separate product built around the FHIR standard, with its own site, keys and licence. The insurance routes of the ClinikEHR API return plain JSON, not FHIR.

Can a startup read a hospital's claims and members?

Only if the startup is itself the insurer and a hospital's owner or manager links its organization to the hospital's record of that insurer. A startup that is not an insurer is a developer. It can submit claims and authorization requests for patients the hospital linked to it, but it cannot read an insurer's data and is refused with hmo_not_linked.

Is there a sandbox for the insurance routes?

No insurance data exists in the sandbox. A test key reaches only its own sandbox clinic, where lists answer an empty page and reads and writes answer 404. Try the insurance routes with a live key against a hospital that has linked your organization.

Does the member lookup check live eligibility with the insurer?

No. The enrollee lookup reads the enrollee record the hospital holds, as the hospital keyed it in. It does not ask the insurer, and the hospital must already hold the member. A number the hospital does not hold comes back as an empty list.

What does a hospital need before an insurer can connect?

Its owner sets Insurance to Outside the US. The hospital is on the Enterprise plan with API access switched on. Its owner approves the connection with the insurance permissions and a recorded legal basis. The owner or a manager then links the organization to the hospital's record of the insurer. Your own workspace needs the Enterprise contract plan and a reviewer's approval.

Does the data-protection addendum make my product lawful in my country?

No. The addendum says each party is responsible for making sure that any cross-border transfer of patient information is lawful where the information comes from and where it goes. It does not make anything lawful in any country. This guide is not legal advice, so ask a lawyer who knows your market.

Conclusion

A hospital integration for an insurer comes down to eight things. The ClinikEHR API documents each one, and each has a page at docs.clinikehr.com.

Start by reading the insurance documentation and opening a workspace in the developer portal. A ClinikEHR reviewer approves insurer access, and each hospital chooses whether to link you. If you want to talk before you apply, contact us.

Related Articles

• How to Build an HMO Claims Integration in Nigeria With the ClinikEHR API (Step-by-Step, 2027)
• Pre-Authorization API for Nigerian HMOs: Approve or Deny PA Requests With a PA Code (2027)
• Connecting Your HMO to the ClinikEHR API in Nigeria: Access, Approval and Data Protection Explained (2027)
• NDPA Compliance for HMOs and Health-Tech Startups Receiving Patient Data in Nigeria (2027 Guide)
• What You Can Build With the ClinikEHR API in Nigeria: Ideas by Access Level (2027)
• ClinikEHR API documentation
• Insurance for HMOs and insurers (API documentation)
• Data Protection Addendum for Organizations (API documentation)
• ClinikEHR pricing

Facts are as of the dates shown. Check the linked sources for updates. This is general information, not legal or professional advice.