Skip to main content
Two resources work together. A payer is an insurance company the clinic has enabled. A coverage is one policy a patient holds with a payer: the member ID, the group, the subscriber and the dates. Payers carry no patient information, so payers:read is not a patient-data permission. Coverage is: the add-on, the agreement and, for an organization, the approval for the Insurance coverage kind all apply. See Permissions. A patient the clinic has restricted, or a coverage that does not exist, returns 404 with code: "not_found". The two are never told apart. See Errors.

​
Payers

The list holds only the payers the clinic has enabled under Settings → Insurance. A payer the clinic has not enabled is not listed, and reading it returns 404. To attach a coverage to a payer you need its id from this list.

​
What a coverage looks like

The subscriber’s address, the clinic’s private notes and the running deductible and out-of-pocket totals are never returned.

​
List coverages

​
Add a coverage

The answer is 201 Created with the coverage. Idempotency-Key is required on POST and optional on PATCH. See Retries and duplicates. You may send payer_id, member_id, group_number, group_name, plan_name, payment_responsibility, relationship_to_subscriber, the subscriber’s name, date of birth, gender and member ID, coverage_type, effective_date, termination_date, copay_amount, coinsurance_percent, deductible_amount, out_of_pocket_max, pre_authorization_required, network_status, is_primary and origin_assistant_name. A field this list does not name is refused with invalid_request, and the error names the field. Eligibility results, running deductible and out-of-pocket totals, and the clinic’s notes belong to the clinic and cannot be sent.

​
A coverage you add is not active until staff confirm it

This is the rule to build around. A coverage created through the API is saved as unconfirmed and inactive (coverage_active: false), and you cannot change that:
  • Sending coverage_active: true is refused with 409 activation_requires_staff.
  • At the clinic, the coverage shows Added by your system’s name, not active until confirmed, with a Confirm button.
  • A member of staff checks the payer, member ID and subscriber against the patient’s card and selects Confirm. Only then is the coverage active and usable for eligibility checks and claims.
  • Reading the coverage afterwards shows verification_status: "confirmed" and coverage_active: true. Poll it, or use the change feed, to find out.
Ending a coverage is yours to do: send coverage_active: false or a termination_date. If you change a confirmed coverage’s payer, member ID, group number, relationship or the subscriber’s name, date of birth or member ID, it returns to unconfirmed and inactive, and staff must confirm it again. Other edits keep its status.

​
The payer must be enabled

payer_id must be a payer from the payer list. If it is not enabled under Settings → Insurance, the request is refused with 409 payer_not_enabled. Ask the clinic to enable the payer, then send it again.

​
One coverage per patient and payer

A patient can have one coverage per payer. Adding a second one for the same payer returns 409 coverage_exists, and when you may see that patient the error carries the existing coverage’s id so you can PATCH it instead.

​
Change a coverage

Send only the fields that change. The answer is 200 with the coverage. The same rules apply as when adding one. A PATCH does not accept null, so a value you have sent cannot be cleared again through the API; ask the clinic to clear it.

​
FHIR

Send Accept: application/fhir+json to read a coverage, or a list of them as a Bundle, as a FHIR R4 Coverage. An unconfirmed coverage has status: "draft"; a confirmed active one is active; an ended or inactive one is cancelled (confirmed, but not active). The beneficiary is the patient, the payor is an Organization for the payer, and relationship uses the standard HL7 subscriber-relationship coding. A payer is read as a FHIR Organization the same way. A payer’s Organization has type of payer. FHIR input is not accepted: an application/fhir+json body on POST or PATCH is refused with an OperationOutcome (400, not supported), so send additions and changes in the plain JSON shape above. See FHIR R4.

​
A worked example

  1. Your intake system reads a patient’s insurance card. It lists the clinic’s payers and finds “Aetna”.
  2. It sends POST …/coverages with the payer’s id, the member ID and an Idempotency-Key. The answer is 201, with coverage_active: false and verification_status: "unconfirmed".
  3. The connection drops before the answer arrives. It sends the same request with the same key and gets the same coverage back, not a second one.
  4. At the clinic the patient’s Insurance Coverage shows Added by Acme Intake, not active until confirmed. A staff member compares it with the card and selects Confirm.
  5. Your system reads the coverage again. It is confirmed and active, and the clinic can run an eligibility check on it.
  6. Later the patient changes plans. Your system sends a PATCH with the new member ID. The coverage returns to unconfirmed until staff confirm it again.
A test key reaches only your workspace’s sandbox, with a made-up payer list and invented patients, so you can try every request above without touching a real chart.