Connecting Your HMO to the ClinikEHR API in Nigeria: Access, Approval and Data Protection Explained (2027)

You lead technology or operations at an HMO, a health maintenance organisation that pays part of its members' hospital bills. You want your systems to read the claims a hospital sends you, and you need to know who must say yes. This guide shows how to connect your HMO to the ClinikEHR API (api.clinikehr.com), which works through a hospital that has connected to you. ClinikAPI (clinikapi.com) is a separate product built around the FHIR health data standard, with its own site, keys and licence.

Quick Answer

To connect your HMO to the ClinikEHR API, ClinikEHR must approve your organization first, and then each hospital chooses whether to connect you.

• Set up your side: a verified developer workspace on the Enterprise contract plan, which ClinikEHR sets on request.
• Get approved: a ClinikEHR reviewer decides your application for insurer data, and your Owner accepts the data-protection addendum.
• Ready the hospital: its owner sets Insurance to Outside the US, and it is on the Enterprise plan with API access on.
• Connect: the owner gives you a one-time code and approves what you may see, then the owner or a manager links you to its record of your HMO.
• Check: create a live key, confirm the connection, and run the nine checks below on any EMR.

What Is an HMO Connection to the ClinikEHR API, in Plain Words

An HMO connection is a hospital's decision to let your organization read part of its insurance data through the ClinikEHR API. An API is a set of routes your software calls to read or send data. An enrollee is a member you cover, as the hospital has recorded them. A claim is the hospital's bill to you for a member's care. A pre-authorization request asks you to agree in advance to pay for something, and the authorization code you give, called the PA code, goes on the claim afterwards.

Access works through scopes, which are named permissions such as reading claims. The hospital's owner ticks the scopes to grant and records a legal basis, the ground on which the hospital shares the information. Your key is the secret your software sends with every request. A webhook is a message posted to a web address you register. The routes and their documentation are published at docs.clinikehr.com.

There Is No Programme to Join

There is no programme to join, and no directory of hospitals to pick from. A hospital can be reached only through a one-time connection code that its owner hands over. Your organization needs its own workspace and an approval first, and then each hospital chooses to connect and link you.

Two steps need ClinikEHR itself, so you cannot finish them alone. ClinikEHR sets your workspace's plan on request, because there is no self-serve checkout. A ClinikEHR reviewer, who is a person, decides your application for insurer data. The documentation states no timeline for either, so this guide gives none.

Two Enterprise Requirements, Kept Apart From HMO Billing

Two plans must be right before your key can read a hospital's insurance data. They are a pair.

1. Your own developer workspace is on the Enterprise contract plan. ClinikEHR sets it on request.
2. The hospital is on the Enterprise plan, with API access switched on.

Both are gates for the API, and both are separate from HMO billing inside the app, which is available on any plan once the hospital's owner sets Insurance to Outside the US. Enterprise here also means the subscription plan, not the Enterprise Clinic type chosen when a workspace is created. The API add-on opens a hospital's own keys and plays no part in yours.

The Whole Path, in Order, With Who Does Each Step

Here is the whole path for your HMO to reach one hospital's insurance data, with who does each step.

Steps 1 to 3: Open and Verify Your Workspace

What to do. Sign up in the developer portal. Then verify the workspace: add a DNS TXT record (a text entry in your domain's settings) for your domain at the host _clinikehr-verify, with your subdomain after it if you entered one. When the domain reads Domain verified, complete the business profile and select Submit for review. Last, accept the API Terms of Use. A live key cannot be created before that.

What you need. Access to your domain's DNS settings, and a person with the Admin or Owner role.

How you know it worked. The domain reads Domain verified.

The mistake people make. Leaving verification until the contract is agreed. You can apply for patient data only once the workspace is verified.

Step 4: Put the Workspace on the Enterprise Contract Plan

What to do. In the portal, select Contact us to go live. It opens your mail client with a message addressed to ClinikEHR, and nothing is sent from the page. ClinikEHR sets your plan once it approves your organization. Enterprise is a contract plan and the documentation prints no price, so contact ClinikEHR with questions.

A paid plan alone is not enough. The Essential plan gives a verified workspace live keys, but only for data that is not about patients, such as inventory. Insurer data is patient data.

What you need. A verified workspace.

How you know it worked. Check your dashboard's Plan & usage page, or wait for ClinikEHR's confirmation that the plan is set. A live key is then no longer refused with workspace_plan_required, although that alone only shows you are off the Sandbox plan.

The mistake people make. Waiting for a checkout page. There is none.

Steps 5 and 6: Get Approved and Accept the Addendum

What to do. Apply for patient data access in the portal, under Settings, Verification, in the Patient data access card. Ask for the kind Insurer claims, authorizations and enrollees, which holds eight scopes. The application covers your purpose, the data and patient numbers you need, your legal basis, your jurisdiction and regulator, two contacts and your safeguards.

A ClinikEHR reviewer decides. The status reads Pending, Under review, Approved, Rejected or Revoked, and a rejection or revocation carries the reviewer's reason. Then your workspace Owner accepts the data-protection addendum, version 2026-10-09, covered in its own section below.

What you need. A verified workspace, and an Admin or Owner to apply.

How you know it worked. The Patient data access card reads Approved, and your Owner has accepted the addendum.

The mistake people make. Reading approval as a licence to read any hospital. It is not a hospital's permission, and a request outside your approval is refused with approval_required.

Steps 7 and 8: Get the Hospital Ready

What to do. These steps belong to the hospital, so your job is to ask.

Step 7. The hospital's owner picks Outside the US under Settings, General, Insurance. Only the owner can change it, and new workspaces start on United States. It is a setting, not geography, and a hospital on the United States setting is refused with insurance_region_unsupported. The Help Center explains the General settings.

Step 8. The hospital is on the Enterprise plan, and its Allow API access switch is on. The switch is off by default, and with it off no key on the workspace can answer. The hospital's plans are on the pricing page.

What you need. A hospital owner who agrees. Ask the owner to confirm both.

How you know it worked. The owner confirms both settings. Your connection list shows the hospital only after the owner approves in step 11, and a hospital that switches API access off drops out of it.

The mistake people make. Assuming a hospital that already bills HMOs in ClinikEHR is ready. It may have the Insurance setting right but a plan below Enterprise, or API access off.

Steps 9 to 12: Connect, Approve and Link

What to do. The hospital's owner generates a one-time connection code and hands it to you directly. The owner chooses how long it is valid, from 24 hours up to 14 days. In your portal, choose Connections, then Connect to a clinic, enter the code and choose what to ask for.

The owner then reviews your request, ticks only the scopes to grant, records a legal basis and approves with a fresh second-factor sign-in. The Help Center puts it plainly:

Only the clinic owner can generate a code, or approve, change, decline, or revoke a connection.

ClinikEHR Help Center, API access

Last, the owner or a manager links your organization to the hospital's record of your HMO, under Settings, API access, Insurer links. That section appears only when Insurance is Outside the US. Linking grants nothing by itself, so you still need the scopes the owner approved.

What you need. Steps 5 to 8 done, and an owner to generate the code and approve.

How you know it worked. The hospital appears in your connection list once the owner approves. After the owner links you, an insurance read is no longer refused with hmo_not_linked.

The mistake people make. Treating the code as the finish line. The owner may grant less than you asked or nothing, and a code is valid for a limited time. Skipping the link leaves you refused with hmo_not_linked on every insurance read.

Step 13: Create a Live Key and Check What It Reaches

What to do. In the portal, create a live key and choose its end date. Every request carries that one key in its Authorization header, and there is no other sign-in. Keep it on your own server, never in a web address, and never call the API from a browser or a phone app. Then call GET https://api.clinikehr.com/v1/connections. It lists each hospital that approved a connection to your workspace, with its name, the scopes it granted and when the connection expires.

What you need. A verified workspace on the Enterprise contract plan, the accepted terms, an approval for the insurer kind, the accepted addendum and a connection.

How you know it worked. The hospital is in the list, and the scopes it granted include the insurance scopes you asked for.

The mistake people make. Reading a refusal as a bug. A live key is refused with not_verified until the workspace is verified, and with workspace_plan_required while it is on the Sandbox plan.

Step 14: Choose How Claims Reach You

What to do. The hospital's owner or a manager picks one submission channel for each HMO. For claims to reach your organization through the API, they pick ClinikEHR API, which needs API access on and your organization linked to your HMO. Other channels include a signed webhook, an email with a secure link that expires after 7 days, and your HMO's own portal, where nothing is sent from ClinikEHR. Where a channel is set up, ClinikEHR delivers the claim through it. The Help Center explains how claims reach HMOs.

For signed events, an Admin adds a webhook address on the portal's Webhooks page. That address is for the API's events and is separate from the hospital's signed webhook channel for claims. The claims tutorial covers events and signatures.

What you need. The hospital's choice of channel, a linked organization and API access on.

How you know it worked. Once the hospital has submitted a claim to you, it appears in your claim list.

The mistake people make. Expecting claims before the hospital has submitted any. Claims still being prepared are never shown to an insurer.

What Your HMO Can See, and What It Cannot

Once you are connected and linked, you act for your own insurer only. Anything that belongs to another insurer answers 404, the same as a record that does not exist, so the answer never tells you which it was.

To vet a claim is to decide it line by line, which the documentation also calls adjudication. A payment advice is a message that tells the hospital what you paid. Until the hospital links you to your insurer record, you count as a developer, as does any technology vendor that builds for you. A developer can submit claims and requests for linked patients but cannot read an insurer's data.

What the Connection Does Not Give

The connection does not offer:

• Live eligibility. The enrollee lookup reads the record the hospital holds, not an insurer's system, and a number the hospital does not hold comes back as an empty list.
• A comparison of claim lines with the hospital's tariffs, which are the price lists agreed with each HMO. No route reads a tariff, and the API does not score claims for fraud.
• FHIR. The HMO routes return plain JSON.
• Reporting to, or any connection with, the NHIA or another regulator.

How a Hospital Ends Your Access

A hospital keeps control for as long as you are connected. It has three ways to end or narrow your access.

• End the link. The owner or a manager selects End link under Insurer links. You no longer see that insurer's information straight away. Nothing already recorded changes, and the hospital can link you again.
• Narrow the connection. The owner changes what is granted. To receive something new, you must ask again.
• Revoke the connection. The owner ends your access, and it cannot be undone. To get access again you need a brand-new code.

Ending the link or revoking the connection takes effect on your next request, so there is nothing to retry. A hospital that switches its own API access off, or a connection that has expired, simply disappears from your connection list. ClinikEHR can also withdraw your approval, and access then ends on the next request. The addendum requires you to return or destroy what you hold for that hospital's patients, unless the law requires you to keep some.

The Data-Protection Addendum, in Plain Words

The addendum is the contract for the patient information you receive. It is between your organization and Bettar Platforms, Inc., and your workspace Owner accepts it. ClinikEHR is a product of Bettar Platforms, Inc. You can read it at docs.clinikehr.com, and your own lawyer should too. This guide is general information, not legal advice.

In short, it says this:

• Roles and purpose. The hospital decides what its patients' information is used for. You receive it as an independent controller, for the purpose the hospital agreed to and no other, and ClinikEHR is not your processor for it. Once linked, you may receive only your insurer's enrollees, plans, claims and authorization requests at that hospital, and only to administer that insurer's cover.
• Basis. You confirm that the basis the hospital recorded is true for every person whose information you request.
• Care. Keep the information secure, encrypted when stored and when sent, with access limited to people who need it and a record of who accessed it. Keep it only as long as the purpose and the law require, and pass it on only to someone bound by terms at least as protective.
• Incidents. Tell ClinikEHR ([email protected], marked Security incident) and the hospital about unauthorised access to what you received without undue delay, and in any case within 72 hours.
• Nigeria. An organization established in Nigeria, or handling the information of people in Nigeria, is covered by this clause:

You are a data controller for what you receive and you will comply with the Nigeria Data Protection Act...

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

The clause adds that where the Act requires you to register with the Nigeria Data Protection Commission, you will do so. It states that Bettar Platforms, Inc. is registered with the Commission. Where the Act and the addendum both apply, you follow whichever protects the person more.

The addendum has NDPA terms, meaning terms that refer to the Nigeria Data Protection Act (NDPA). It is a contract, not a certification. It sets duties for each side and does not confirm that you or ClinikEHR already meet the Act. This guide does not explain the Act itself.

What gets recorded. ClinikEHR records every disclosure to you: which patient, which kind of record, when, and under which connection and basis. The hospital can see the record and export it. The patient can see, in the hospital's patient portal, which organizations received their information, when and what kind, never the information itself. The addendum says ClinikEHR keeps these records for seven years.

9 Things to Check Before Integrating With an EMR as a Nigerian HMO

Use these nine checks on any EMR, including this one. For ClinikEHR the honest answer to each is below, and where an answer is only partial, it says so.

1. An API rather than file exports

Answered. The ClinikEHR API has 14 documented routes for HMOs, a published OpenAPI description (a machine-readable list of the routes), curl samples and two client libraries. Install the TypeScript one with npm install @clinikehr/api (use 0.1.3 or later, on Node.js 18 or later) and the Python one with pip install clinikehr (Python 3.11 or later).

2. A sandbox, with insurance tested against a linked clinic

Partly. A test key reaches a sandbox for the rest of the API, but not for insurance:

A test key reaches only its own sandbox clinic, which holds no insurance data.

ClinikEHR API documentation, Insurance for HMOs and insurers

Lists answer an empty page, and reads and writes answer 404. You try the insurance routes with a live key against a hospital that has linked your organization, so agree your first hospital before you plan a build. No insurance test data exists, so this guide invents no sample responses.

3. Per-insurer data isolation

Answered. See the table of what your HMO can see, above: an insurer sees only its own rows, and anything else answers 404.

4. Line-by-line vetting

Answered. To vet a claim you send a decision, approved or rejected, and you can set each line to approved, adjusted or declined with a reason. You can never approve more than was billed. Vetting moves no money, and it ends once the hospital has recorded a payment or a write-off, an amount it gives up collecting.

5. Authorization (PA) codes

Answered, with limits. When you approve a request you send a PA code, and the code goes on the claim. A request is decided once, and a second decision is refused with invalid_status_transition. The approved amount cannot exceed the hospital's estimate. The documentation describes no validity period for a code and no check for a code used twice, so keep your own record of the codes you issue. An approval is not a promise of payment, since the claim must still match it. The pre-authorization guide covers the routes.

6. Payment advices

Answered, as a message. A payment advice tells the hospital what you paid, by which method and against which claims. It changes no claim and no books, and no money moves through the API. Hospital staff record the money, and only then does a claim read partly paid or paid.

7. Event notifications

Answered, with limits. Five event types exist: a claim submitted, vetted or paid, and a request made or decided. Each delivery is signed, and the signing secret is shown once. Events carry ids, numbers, statuses and amounts, never a patient's name. The paid event fires when hospital staff record a payment or write-off, not when you post an advice. A change feed lets you catch up after an outage, and events are kept for 30 days.

8. A record of what was shared

Answered. ClinikEHR records every disclosure, and the hospital and the patient can see it, as the addendum section above describes. The documentation does not promise your HMO a copy of that record.

9. Data-protection terms that include the NDPA

Answered as contract terms. The addendum has NDPA terms in its Nigeria clause, along with the 72-hour incident notice and the independent controller role, all described above. It is a contract, not a certification.

How You Know the Connection Works

• Your connection list shows the hospital, with the insurance scopes it granted.
• A refused request carries a stable code you can act on, such as hmo_not_linked or approval_required.

Mistakes That Delay an HMO Connection

• Missing a connection's end date. Each connection can carry an expiry, shown as expires_at in your connection list. A connection that has expired drops out of the list and has to be approved again.
• Planning around one hospital's yes. A key reaches only the hospitals that approved a connection to your workspace. A second hospital needs its own code, approval and link.
• Letting the live key run out. A live key's end date is at most 12 months away. An expired key is refused with 401 invalid_key, the same as a bad one.
• Treating an event as the record. An event says which claim changed, not the claim itself. Read the claim for its current state.
• Accepting the addendum as a formality. Your responsibility to a hospital and to patients for what you do with the information is not limited by its terms. Have your lawyer read it before your Owner accepts it.

Frequently Asked Questions

How do I connect my HMO to the ClinikEHR API?

Open a developer workspace, verify it, accept the API terms and ask ClinikEHR to set the Enterprise contract plan. Apply for insurer data access, which a ClinikEHR reviewer decides, and have your Owner accept the data-protection addendum. Then a hospital's owner gives you a one-time code, approves what you may see and links you to its record of your HMO. After that you create a live key and check the connection.

Is there a programme to join, and can we go live on our own?

No programme exists and there is no directory of hospitals. ClinikEHR sets your plan on request and a reviewer decides your application, so you cannot go live alone. Each hospital's owner then chooses whether to connect you. The documentation states no timeline for the plan or the review, and this guide promises none.

What does a hospital need before an HMO can read its claims?

Its owner must set Insurance to Outside the US, and the hospital must be on the Enterprise plan with API access switched on. The owner approves your connection with the insurance scopes and a recorded legal basis, and the owner or a manager links your organization to its record of your HMO. Billing HMOs inside the app is separate and is available on any plan once Insurance is Outside the US.

What can an HMO see, and what can it not see?

You see only your own insurer's enrollees, plans, claims and pre-authorization requests, and only claims and requests the hospital has sent. Another insurer's records answer 404. You cannot see a claim still being prepared, the files attached to a claim or the hospital's notes, and you cannot create or change an enrollee. No route moves money.

How can a hospital end an HMO's access?

The owner or a manager can end the link to your insurer record, and the owner can narrow the connection or revoke it. Ending the link or revoking the connection takes effect on your next request. A revoked connection cannot be undone, and you need a new code. The addendum then requires you to return or destroy what you hold for that hospital's patients, unless the law requires you to keep some.

Does the data-protection addendum certify that we meet the Nigeria Data Protection Act (NDPA)?

No. The addendum has NDPA terms in its Nigeria clause, plus a 72-hour incident notice and an independent controller role. It is a contract, not a certification, and it does not confirm that you or ClinikEHR already meet the Act. Read the Act itself and ask your own lawyer. This is general information, not legal advice.

Can we test the insurance routes with a test key?

No. A test key reaches only its own sandbox clinic, which holds no insurance data, so lists answer an empty page and reads and writes answer 404. The rest of the API has a sandbox. For insurance you use a live key against a hospital that has linked your organization.

How much does the Enterprise workspace plan cost for an HMO?

The documentation lists it as a contract plan and prints no price. ClinikEHR sets the plan on request once your organization is approved, so contact ClinikEHR to discuss it. The hospital's own plans are on the pricing page.

Conclusion

Connecting an HMO to a hospital through the ClinikEHR API is a path of decisions by different people. ClinikEHR sets your plan and a reviewer decides your application. Your Owner accepts the addendum. Each hospital's owner chooses whether to connect, what to grant and whether to link you. No step is a programme you join.

Start in the developer portal, and ask a hospital's owner for a code once your workspace is ready. For questions about plans or access, contact ClinikEHR. The Insurance for HMOs and insurers page covers each insurance route, and the API documentation page introduces the API.

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)
• Getting Paid by HMOs in Nigeria: The Complete 2027 Guide for Hospital Owners and Billers
• NDPA Compliance for HMOs and Health-Tech Startups Receiving Patient Data in Nigeria (2027 Guide)
• ClinikEHR API documentation
• Insurance for HMOs and insurers, in the 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.