Claim House API

v1 · 52 live endpoints · 67 coming soon · https://api.claimhouse.ai

Getting started

Overview

One API for dental eligibility today, with the same rules as the dashboard. Claims, attachments and payments are coming soon.

InfoLive today: Eligibility, Payers, Offices, API keys, Usage, Account and team. Everything marked Coming soon is not available yet: requests to it are refused.

Claim House runs real-time dental eligibility checks: send one check for one patient at one office, get the payer's answer in a readable form and as a PDF, and see what every check costs. Claims, attachments, claim status and remittances are coming soon, and their pages say so.

Everything your staff can do in the Claim House dashboard is available here. The dashboard calls the same /v1 routes with the same permissions, office scope, edits, holds and one-attempt rules, and writes to the same ledger.

AreaWhat you doAvailableStart with
EligibilityRun a real-time eligibility check, or hand over a whole list as a batch, read the answer and download it as a PDFLivePOST /v1/eligibility
PayersFind the payer id to send on a check, see what each payer supports and whether it is answeringLiveGET /v1/payers/search
OfficesList and add the offices you check for, and take an office liveLiveGET /v1/facilities
UsageSee every check, whether it was charged and whyLiveGET /v1/usage
Claims and claim draftsSubmit and track dental claimsComing soon
AttachmentsSend x-rays, charts and narratives through the electronic attachment networkComing soon
PaymentsRead remittances and what each claim was paidComing soon
Events and webhooksKeep your system in sync without pollingComing soon

Getting started

  • Sign up in the dashboard at https://dashboard.claimhouse.ai. Your organization's first test key is made there and shown once.
  • Test mode checks sample patients at test offices: nothing reaches a payer and nothing is charged. See Test mode.
  • Live checks open when your organization has a card on file and an office is live.

Base URL

https://api.claimhouse.ai/v1
  • Requests and responses are JSON over HTTPS.
  • Every response carries an X-Request-Id header. Log it and quote it when you contact Claim House.
  • Every response carries a Claim-House-Version header naming the API version. See Versions and changelog.
  • Claim House owns every clearinghouse and network credential. You never hold a vendor login.
InfoAll ids, keys and patient values in these docs are synthetic. Replace ch_test_key_EXAMPLE.secret_EXAMPLE with your own key.
Getting started

Start here: your first eligibility check

Set up your organization, try a free test check, then prepare an office for real payer answers. Use the dashboard, the API, or both.

Choose your path

You want toStart withYou will finish with
Run a check without writing codeDashboard walkthrough belowAn answer, its detailed breakdown and a PDF
Build an integrationFirst API check guideSaved requests, JSON answers and a PDF
Understand what the answer meansRead an eligibility answer guideClear distinctions between payer facts, request information and missing information

Dashboard: https://dashboard.claimhouse.ai. API: https://api.claimhouse.ai. Reference: https://docs.claimhouse.ai. Eligibility is the first released product. A feature marked Coming soon is not available for use.

1. Create or join your organization

  1. Open the dashboard and sign up, or sign in to your existing account. Complete email verification if requested.
  2. Create your organization, or select the organization you have been invited to join. An organization is your company; each office is a separate location within it.
  3. Wait for setup to finish. Signing in alone does not prove that registration, membership or office access is complete. If you see a pending, blocked or unavailable setup screen, follow its instructions before continuing.
  4. Check the organization name in the top bar. Team members must accept an invitation using its intended email address and receive access to the correct offices.
ImportantUse the setup state shown in your account. This guide does not promise immediate activation for every new organization. Do not register a second organization to work around a pending setup.

2. Try the dashboard in Test

  1. Select Test in the top bar and choose a test office. Test offices and live offices are separate.
  2. Open Eligibility, then New check. Use Load a sample when offered. Choose a sample payer and patient; sample people are synthetic.
  3. Review the office, payer, subscriber and dependent information. Submit one check.
  4. Open the saved result. Review the snapshot, expand the complete breakdown, and inspect the JSON views available for that check.
  5. Download its PDF and confirm the Test label. Return to eligibility history and find the same check under the same office.

Test mode uses sample answers and does not contact a real payer. A test success proves that you can use the flow; it does not verify real insurance coverage. Real patient information does not belong in test examples.

3. Give developers access

  1. From the test home, choose Show my test key when available, or use Settings, API keys. Create a Test key with read and submit permissions and the test office you intend to use.
  2. The secret is shown once. Save it privately on your server. A key id is not the secret. Do not put the secret into browser code, screenshots, documentation or a source repository.
  3. Follow First API check. Begin with GET /v1/me to confirm the organization, mode, permissions and reachable offices.
  4. Invite team members through your account settings. Review their role and office assignments. An organization invitation does not make every office accessible automatically.

4. Prepare a real office

  1. Register the actual office in Offices. Have its display name, legal billing name, billing NPI, tax ID, address and business contact information ready. Use your own stable office reference if you need to match it to another system.
  2. Review billing in Settings and add the payment method required for live use. Never send card details through an eligibility API request.
  3. Open Settings, Go live. Complete the displayed checklist for each office, including billing identity review and eligibility readiness. An office record alone does not prove readiness.
  4. When the office is ready, select Live. For integrations, use a separately issued Live key with the appropriate permissions and office grant. The dashboard switch does not change an API key's mode.

A practice-management connection is optional. You can use the dashboard or JSON API without one. Eligibility does not require claims or electronic-attachment setup unless your account explicitly identifies an eligibility prerequisite.

5. Make one live check

  1. Choose the actual patient's office and exact payer. Confirm the policy holder's member ID, first and last name, and date of birth. For a dependent, also supply the patient and relationship. Do not guess identifiers or pick another office's patient.
  2. In the dashboard, review the form and click once. Through the API, save the request body and a new idempotency key before making one POST /v1/eligibility.
  3. Save the returned eligibility_id and request_id. Check whether the payer answered before interpreting coverage status.
  4. Read the full breakdown and payer JSON, then download the PDF. Compare request identity with returned identity when they differ.
  5. Confirm the check in office history and usage. A usage record is not proof that a payment has settled.
ImportantIf a submission times out or its outcome is uncertain, stop submitting. Do not use a new key to try the same check again. Read the saved operation/history when you have an id, or contact support with the original request id, office id, idempotency key and time.

Before your team starts live work

  1. Confirm the right organization, live office, billing identity and key permissions.
  2. Complete the test API walkthrough and dashboard walkthrough independently.
  3. Test an answered check, an inactive test scenario, and a refusal test scenario. Treat these as different outcomes.
  4. Confirm that your integration saves the original request, response headers, status, request id, check id and idempotency key privately.
  5. Have an operator procedure for uncertain submissions, access problems and payer refusals. Review the answer limitations in Read an eligibility answer.
Getting started

First API check: copyable terminal walkthrough

Use a Test key first. Save each request and every response, then read the same check as its complete answer, its summary, the payer's answer as received and two PDFs.

InfoThis walkthrough uses API version 2026-11-01 (the answer is contract eligibility.v3) and pins it on every call, as an integration should, so a later change of the default never changes what you read. Every response shown below was executed in Test mode against the current API.

What you need

Use a Test key with read and submit permissions, a granted sandbox office, curl and jq. Load the key into CLAIMHOUSE_KEY using your normal private secret handling or the new-key instructions. These are ordinary HTTP calls; no helper functions or practice-system connection are required.

1. Save files in a private folder

umask 077
CH_RUN_DIR="$(mktemp -d "$HOME/claimhouse-test.XXXXXX")"
cd "$CH_RUN_DIR"
printf 'Save this folder path to resume later: %s\n' "$CH_RUN_DIR"

Use the same terminal and folder for the following steps. Files contain the full responses. Do not regenerate the request or its idempotency key to recover a lost response.

2. Confirm access and choose your sandbox office

curl --silent --show-error \
  --header "Authorization: Bearer $CLAIMHOUSE_KEY" \
  --header 'Claim-House-Version: 2026-11-01' \
  --output me.json --write-out 'HTTP %{http_code}\n' \
  "https://api.claimhouse.ai/v1/me"
curl --silent --show-error \
  --header "Authorization: Bearer $CLAIMHOUSE_KEY" \
  --header 'Claim-House-Version: 2026-11-01' \
  --output offices.json --write-out 'HTTP %{http_code}\n' \
  "https://api.claimhouse.ai/v1/facilities"

Inspect me.json and offices.json. Continue only if the responses succeeded, mode is test, and the office you choose is a sandbox office granted to this key. A Test toggle in the dashboard does not change an API key.

CH_OFFICE="YOUR_SANDBOX_OFFICE_ID"

3. Save a complete Test request

This is the flat request: the office, the insurance, the member ID and the patient. Replace the office placeholder above with your selected sandbox office. These synthetic values come from the Test sample catalog; they are not a recommendation for a live patient.

jq -n --arg office "$CH_OFFICE" '{
  office: $office,
  insurance: "94276",
  member_id: "CH-ACTIVE-FULL",
  patient: {first_name: "Test", last_name: "Patient", date_of_birth: "1980-01-01"},
  reference: "first-test-check"
}' > request.json
jq empty request.json

4. Save one intent key, then submit once

The flat request may go without a key: the server then derives one from the content and the UTC day, so the same check sent again that day replays for free. This walkthrough saves its own key so that a retry is provably the same intent. Generate it once for this intended check and keep it with request.json.

uuidgen > idempotency-key.txt
curl --silent --show-error --request POST \
  --header "Authorization: Bearer $CLAIMHOUSE_KEY" \
  --header 'Claim-House-Version: 2026-11-01' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $(cat idempotency-key.txt)" \
  --data-binary @request.json \
  --dump-header submit.headers --output submit.json \
  --write-out 'HTTP %{http_code}; elapsed %{time_total}s\n' \
  'https://api.claimhouse.ai/v1/eligibility'

submit.json is the answer itself: id, status, verified and every line the payer sent, plus billing, request (your reference and the key it ran under) and idempotent_replay. The start of an executed answer (excerpt):

{
  "id": "elg_rytbnz2t8d0ana377njh",
  "contract": "eligibility.v3",
  "view": "complete",
  "status": "active",
  "checked_at": "2026-09-07T15:00:00+00:00",
  "verified": true,
  "office": {
    "id": "fac_sandboxbatchsandbx",
    "name": "fac_sandboxbatchsandbx"
  },
  "payer": {
    "id": "94276",
    "name": "Delta Dental",
    "id_as_returned": "94276",
    "name_as_returned": "Delta Dental"
  },
  "counts": {
    "payer_rows": 16,
    "lines": 16,
    "procedures": 2,
    "notes": 0,
    "history": 0
  },
  "links": {
    "complete": "/v1/eligibility/elg_rytbnz2t8d0ana377njh/answer?contract=v3",
    "summary": "/v1/eligibility/elg_rytbnz2t8d0ana377njh/answer?contract=v3&view=summary",
    "lines": "/v1/eligibility/elg_rytbnz2t8d0ana377njh/answer?contract=v3&view=lines",
    "payer_answer": "/v1/eligibility/elg_rytbnz2t8d0ana377njh/answer?view=payer",
    "pdf": "/v1/eligibility/elg_rytbnz2t8d0ana377njh/pdf"
  }
}
CH_CHECK="$(jq -er '.id' submit.json)"
jq -r '.status, .verified' submit.json

HTTP success alone does not establish active or complete benefits. A transport error does not prove that no inquiry occurred: retain the original body and key and send the same body with the same key again, which replays the recorded check (idempotent_replay: true, no second payer call). Never create a new key automatically after a timeout. verified: false means the organized answer is withheld; links.payer_answer still reads the payer's answer as received.

A payer refusal answers 422 PAYER_REJECTED, with the recorded check id in errors[0].eligibility_id and the reason in errors[0].rejection. Do not treat a refusal as inactive coverage. Executed (excerpt):

{
  "error": "PAYER_REJECTED",
  "message": "The payer could not find this member.",
  "errors": [
    {
      "eligibility_id": "elg_kts7t14v5n3sxcm9b4dr",
      "error_class": "VENDOR_REJECTED",
      "rejection": {
        "kind": "FIX_AND_RESEND",
        "retry_later": false,
        "summary": "The payer could not find this member.",
        "reasons": [
          {
            "code": "MEMBER_NOT_FOUND",
            "about": "subscriber",
            "message": "The payer could not find this member.",
            "fix": "Check the member ID and the subscriber's name and date of birth exactly as they appear on the insurance card.",
            "field": null,
            "next_step": "FIX_REQUEST"
          }
        ]
      }
    }
  ]
}

5. Read the same check

curl --silent --show-error \
  --header "Authorization: Bearer $CLAIMHOUSE_KEY" \
  --header 'Claim-House-Version: 2026-11-01' \
  --output record.json --write-out 'HTTP %{http_code}\n' \
  "https://api.claimhouse.ai/v1/eligibility/$CH_CHECK"
curl --silent --show-error \
  --header "Authorization: Bearer $CLAIMHOUSE_KEY" \
  --header 'Claim-House-Version: 2026-11-01' \
  --output summary.json --write-out 'HTTP %{http_code}\n' \
  "https://api.claimhouse.ai/v1/eligibility/$CH_CHECK/answer?view=summary"
curl --silent --show-error \
  --header "Authorization: Bearer $CLAIMHOUSE_KEY" \
  --header 'Claim-House-Version: 2026-11-01' \
  --output complete.json --write-out 'HTTP %{http_code}\n' \
  "https://api.claimhouse.ai/v1/eligibility/$CH_CHECK/answer"
curl --silent --show-error \
  --header "Authorization: Bearer $CLAIMHOUSE_KEY" \
  --header 'Claim-House-Version: 2026-11-01' \
  --output payer.json --write-out 'HTTP %{http_code}\n' \
  "https://api.claimhouse.ai/v1/eligibility/$CH_CHECK/answer?view=payer"

record.json is the same answer with billing and what you sent. complete.json is every line, grouped: plan, totals, by_service, by_procedure, history, not_covered, notes. summary.json holds the lines your office's summary selects, never rewritten; counts says how many of how many. payer.json is the payer's answer as received. None of these reads sends another payer inquiry.

jq '.counts' summary.json
{
  "complete_lines": 16,
  "shown_lines": 16
}

6. Make and download the PDFs

A submit-capable key makes a PDF from the saved answer; a read-only key can only read one already made. There are two: the complete PDF (the default) prints every line, as long as the answer is; the streamlined PDF prints the summary's lines and says how many of how many. If making one is refused, keep the error and stop.

curl --silent --show-error --request POST \
  --header "Authorization: Bearer $CLAIMHOUSE_KEY" \
  --header 'Claim-House-Version: 2026-11-01' \
  --output pdf-complete.json --write-out 'HTTP %{http_code}\n' \
  "https://api.claimhouse.ai/v1/eligibility/$CH_CHECK/pdf"
curl --silent --show-error --request POST \
  --header "Authorization: Bearer $CLAIMHOUSE_KEY" \
  --header 'Claim-House-Version: 2026-11-01' \
  --output pdf-streamlined.json --write-out 'HTTP %{http_code}\n' \
  "https://api.claimhouse.ai/v1/eligibility/$CH_CHECK/pdf?kind=streamlined"
{
  "livemode": false,
  "request_id": "evt_q6j3d54ts933hfphxnka",
  "eligibility_id": "elg_rytbnz2t8d0ana377njh",
  "artifact_id": "art_qcs3qdvsbd2dz8p8cbyy",
  "filename": "elig_elg_rytbnz2t8d0ana377njh-complete.pdf",
  "bytes": 75451,
  "contract": "eligibility.v3",
  "kind": "complete"
}

Read each PDF with its short-lived link. The download deliberately sends no API credential to the download host. Keep the metadata private: the link is temporary access to the file.

curl --silent --show-error \
  --header "Authorization: Bearer $CLAIMHOUSE_KEY" \
  --header 'Claim-House-Version: 2026-11-01' \
  --output pdf-streamlined-read.json --write-out 'HTTP %{http_code}\n' \
  "https://api.claimhouse.ai/v1/eligibility/$CH_CHECK/pdf?kind=streamlined"
CH_DOWNLOAD_URL="$(jq -er '.download_url | select(startswith("https://"))' pdf-streamlined-read.json)"
curl --fail --silent --show-error --output answer-streamlined.pdf "$CH_DOWNLOAD_URL"
unset CH_DOWNLOAD_URL
{
  "livemode": false,
  "request_id": "evt_et1rdqvx815rbagz0p74",
  "eligibility_id": "elg_rytbnz2t8d0ana377njh",
  "artifact_id": "art_nx2yk9dwb93a94ycgn7z",
  "filename": "elig_elg_rytbnz2t8d0ana377njh-streamlined.pdf",
  "bytes": 77505,
  "contract": "eligibility.v3",
  "kind": "streamlined",
  "download_url": "https://files.claimhouse.ai/EXAMPLE-short-lived-link",
  "expires_in_seconds": 600
}

The same with no kind (or kind=complete) reads the complete PDF. If a link expires, read the PDF again for the same stored check; do not resubmit eligibility. Verify each download is a PDF and that the Test label and check identity are correct. (The link above is an example: the executed one was local.)

7. Find the same result in history

curl --silent --show-error \
  --header "Authorization: Bearer $CLAIMHOUSE_KEY" \
  --header 'Claim-House-Version: 2026-11-01' \
  --output history.json --write-out 'HTTP %{http_code}\n' \
  "https://api.claimhouse.ai/v1/facilities/$CH_OFFICE/eligibility?limit=20"

In the dashboard select Test and this office, then open the recorded check. Compare its Complete and Summary tabs and its two PDFs (Download PDF, then Complete or Streamlined) with your saved files. Opening the result is not a new inquiry; New check is a separate action.

From Test to Live

Use your own production-ready office, a Live key and actual verified insurance information. Confirm the key mode and office before sending. Keep the same request-saving and recovery discipline. Synthetic member IDs are only for Test.

Required information and field formats

FieldWhat to supplyRequired?
officeThe office: its fac_ id, its office code or its exact name. Optional when your key reaches exactly one office that takes checks in its mode; otherwise 422 OFFICE_REQUIRED with errors[0].candidates. A name or code that matches two offices is 422 OFFICE_AMBIGUOUS.No
insuranceThe payer: a Claim House payer id, the payer's own id, your practice system's payer id or the insurance name as the office records it. When Claim House is not sure, the check answers 409 PAYER_CHOICE_REQUIRED with candidates; it never guesses.Yes
member_idThe policy holder's member ID, as on the card.Yes
patientThe person being seen.Yes
relationshipThe patient's relationship to the policy holder: self (the default), spouse, child or other, in any letter case, or the codes 18, 01, 19 (any other two-digit code reads as other).No
subscriberThe policy holder, when the patient is a dependent (relationship spouse, child or other). Sending it without a dependent relationship is 422 INVALID_ELIGIBILITY_REQUEST with finding PATIENT_RELATIONSHIP_REQUIRED.No
group_numberThe policy holder's group number.No
visit_dateThe visit date, in any of the three formats. Defaults to today (UTC).No
proceduresUp to ten CDT codes to ask about, in any letter case.No
referenceYour own reference (up to 200 characters), returned in request.reference and kept with the check.No
max_age_secondsReuse a saved answer only when it is at most this old, 0 to 604800. 0 asks the payer again (and makes a derived key fresh). From 1 to 86399 the derived key also becomes a window of that many seconds, so a replay is never older than you asked.No
viewThe view the check answers with: complete (the default), summary, lines or payer.No

Dates are accepted as YYYY-MM-DD, MM/DD/YYYY or YYYYMMDD. The camelCase and snake_case request shapes are still accepted, unchanged; see Check eligibility.

Dependent request example

{
  "office": "YOUR_SANDBOX_OFFICE_ID",
  "insurance": "62308",
  "member_id": "CH-DEP-AGE-26",
  "patient": {
    "first_name": "Test",
    "last_name": "Child",
    "date_of_birth": "2014-01-01"
  },
  "relationship": "child",
  "subscriber": {
    "first_name": "Test",
    "last_name": "Subscriber",
    "date_of_birth": "1980-01-01"
  },
  "reference": "dependent-test-check"
}

This is a Test-only dependent example; it was executed with a sandbox office in place of YOUR_SANDBOX_OFFICE_ID (HTTP 200). Leave out relationship and subscriber when the patient is the policy holder. Do not infer patient identity or relationships from similar names.

The API map

CallPurposeSends a new payer inquiry?
GET /v1/meConfirm identity, permissions, mode and reachable officesNo
GET /v1/facilitiesList your officesNo
GET /v1/test/samplesChoose a labeled synthetic scenario in TestNo
GET /v1/payers/search?q=...Find the payer when the insurance name is not enoughNo
POST /v1/eligibilityCheck one patient; the response is the answerYes in Live; simulated in Test
GET /v1/eligibility/{id}Read the check again: the answer, billing and what you sentNo
GET /v1/eligibility/{id}/answer?view=summaryThe lines your office's summary selectsNo
GET /v1/eligibility/{id}/answerEvery line, grouped (view=complete)No
GET /v1/eligibility/{id}/answer?view=linesEvery line once, for spreadsheetsNo
GET /v1/eligibility/{id}/answer?view=payerThe payer's answer as receivedNo
POST /v1/eligibility/{id}/pdf?kind=complete|streamlinedMake (or reuse) a PDF of the saved answerNo
GET /v1/eligibility/{id}/pdf?kind=complete|streamlinedRead a PDF already made, with its linkNo
GET /v1/settings/eligibility-summaryRead which blocks and codes the summary selectsNo
GET /v1/facilities/{id}/eligibilityList one office's saved checksNo
GET /v1/eligibility?facility_id=...List checks across your officesNo

For full field definitions and named errors, open the corresponding API reference entry. Keep API keys on the server. Use your account's request logs and usage screens to reconcile checks; do not treat a usage flag as a settled card payment.

Test more than the happy path

Test member IDScenarioExpected distinction
CH-ACTIVE-FULLAnswered, active with sample benefitsstatus is active
CH-TERMINATEDAnswered, inactivestatus is not_answered; still an answered result
CH-NOT-FOUNDSample payer refusalHTTP 422 PAYER_REJECTED; read the rejection; do not turn a refusal into inactive

For each new intended Test scenario, save a separate request and idempotency key. These magic member IDs are for Test only. The sample catalog describes other scenarios, including dependent coverage and sparse answers.

Getting started

Read an eligibility answer

Understand the answer, its summary, the payer's answer and the two PDFs without turning missing data, qualifiers or request details into coverage promises.

InfoThis page describes the answer, contract eligibility.v3 (API version 2026-11-01, the default). Reading an eligibility answer, in the API guides, documents every block. The earlier readable answer (contract eligibility.v2) is still served with contract=v2 or Claim-House-Version: 2026-10-01.

Start with the outcome, then the coverage status

What you seeWhat it meansWhat to do
status activeThe payer's answer reports active coverageRead the lines: amounts, percents, limits, dates, exclusions and notes
status inactiveThe payer's answer reports inactive coverageReview the plan's coverage dates and the payer's notes
status unknownAn answer exists, but coverage was absent or unrecognizedRead every line and the payer's answer; do not translate it to inactive or uninsured
422 PAYER_REJECTED (the record reads not_answered with failure)The payer refused; no coverage answer was returnedRead the rejection; do not present it as a coverage decision
verified: falseThe organized answer did not match the payer's answer, so it is withheldRead the payer's answer as received (links.payer_answer); do not use partial lines
Pending or uncertainProcessing is not confirmed completeRead the operation or the history and reconcile; do not resend blindly

An active status does not say that every treatment is covered or paid. A refused query does not say the patient has no insurance. HTTP 200 alone is not a benefit determination.

The same check in six forms

RepresentationBest forWhat to retain
The answer (view=complete; the check response and the record)Every line the payer sent, groupedid, status, verified, counts and every line with its ref
Summary (view=summary)The lines an office usually needs, chosen by its saved settingscounts.shown_lines of counts.complete_lines; open the complete answer for the rest
Lines (view=lines)Spreadsheets and analytics: every line once with its groupgroup, text, ref
Payer (view=payer)The payer's answer as receivedThe fields as the payer named them
Complete PDF (kind=complete)Sharing every line on paperAll pages, the Test label and check id
Streamlined PDF (kind=streamlined)Sharing the summary's lines on paperThe "N of M lines" header; the complete PDF has every line

How a line reads

Each line is one row the payer sent. text is one plain sentence that holds every value on the line; the fields beside it (network, level, period, amount, percent, ...) are the payer's own, under plain names; ref names the payer's section and row, the same index as the payer's answer. An executed line:

{
  "kind": "deductible",
  "network": "in_network",
  "level": "individual",
  "period": "calendar",
  "service": "dental_care",
  "amount": "50.00",
  "text": "Dental care (general), in network, individual, calendar year: deductible $50.00",
  "ref": "deductible[0]"
}

Keep numbers with their qualifiers

  1. Read an amount or percent together with its network, coverage level, period, service and procedure code: they sit on the same line and in its sentence.
  2. A remaining amount is its own line (period: remaining), beside the plan amount; Claim House never subtracts one from the other or pairs them.
  3. "coinsurance 80%" is the payer's figure. The answer does not say whose share it is, and neither do we.
  4. An absent field is not zero and not proof that a rule does not apply. missing lists the sections an office usually expects that the payer did not send; not_read lists fields kept verbatim under a line's other.

Current limitations to account for

Procedure lines show CDT codes only, never procedure names. A row the payer listed under several codes appears under each code and is counted once.

A network value is the payer's wording about the plan. It does not prove that the specific provider participates in a payer network.

as_requested holds what you sent; patient and subscriber are what the payer returned. differences names fields the payer returned with another value. Review them, including the relationship, before using the answer. Do not automatically replace patient or subscriber records with the returned identity.

The requested visit date is request information. Do not treat it alone as proof of historical or future-date coverage. A clearly labeled test scenario does not prove that every live payer will return the same detail.

If something goes wrong

SituationNext action
401 or invalid keyCheck the privately stored secret and whether the key was revoked
403, mode mismatch or office access errorConfirm GET /v1/me, key permissions, office grant and Test/Live binding
Billing or readiness holdFollow the account's Billing and Go live checklist
422 invalid requestRead the named findings and check member ID, date format and dependent relationship; distinguish local validation from a payer refusal
Payer refusalRetain the full rejection. Correct only verified patient or insurance facts; do not guess or launch repeated inquiries
422 IDEMPOTENCY_KEY_REUSED or 409 in-flight checkKeep the original key and body and inspect the stored check; do not replace the key to bypass the hold
Timeout, connection failure or server errorThe submission may have reached the payer. Send the same body with the same key again (a replay) before any new submission
409 ANSWER_NOT_VERIFIED or verified falseRead the payer's answer as received; do not present partial lines as an eligibility answer
409 PDF_NOT_VERIFIEDRetain the error and check id; the answer itself is not affected
Expired PDF linkRead the PDF again (GET with the same kind) for the same saved check

What to send support

Contact support@claimhouse.ai with the request id, check id when available, office id, time and named error code. Keep the original idempotency key and request files for reconciliation. Do not email patient names, dates of birth, member IDs, API secrets, signed download URLs or full patient responses. Use your approved private support process if more detail is required.

Getting started

Quickstart

Run your first eligibility check in test mode with curl, exactly as the new-key dialog gives it. It is free and never reaches a payer.

You need a test key with read and submit, and a test office (mode sandbox). Your organization's first test key is made in the dashboard. When you create a key, choose the offices it reaches and Test or Live: nothing is preselected. Permissions default to read and submit.

Signed in? Settings, API docs in the dashboard shows this page with your own test office filled in.

1. Save the key

export CLAIMHOUSE_KEY='ch_test_key_EXAMPLE.secret_EXAMPLE'

This lasts for this terminal window. Store it in your secrets manager or an env file outside your code. Replace the example with your own key; the new-key dialog fills it in for you.

2. Who am I

curl -sS "https://api.claimhouse.ai/v1/me" -H "Authorization: Bearer $CLAIMHOUSE_KEY"

Check that mode is test and that reachable_facilities lists your test office (mode sandbox). Copy its facility_id. Keep URLs in double quotes: zsh treats an unquoted ? as a pattern.

3. First check

curl -sS -X POST "https://api.claimhouse.ai/v1/eligibility" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Content-Type: application/json" \
  -H 'Idempotency-Key: first-check-ab12cd' \
  -d '{
  "office": "fac_EXAMPLE0000000000001",
  "insurance": "94276",
  "member_id": "CH-ACTIVE-FULL",
  "patient": {
    "first_name": "Test",
    "last_name": "Patient",
    "date_of_birth": "19800101"
  }
}'

Replace fac_EXAMPLE0000000000001 with your test office's facility_id (or its office code, or leave office out when your key reaches one office). CH-ACTIVE-FULL is a test magic member ID: it answers active coverage with any names, date of birth and payer id. Test checks are answered by a payer simulator and never charged (billing.reason test_mode).

The answer is the payer's whole answer, organized: every payer row is one line with one plain sentence (text) and a ref. An executed test check answered with these fields among the rest:

{
  "id": "elg_9aqbap922506q92gx9ge",
  "contract": "eligibility.v3",
  "status": "active",
  "verified": true,
  "plan": {
    "group_number": "TESTGRP1",
    "insurance_type": "ppo",
    "name": "Delta Dental PPO",
    "coverage": {
      "start": "2026-01-01",
      "status": "active",
      "termination": "2026-12-31",
      "lines": [
        {
          "kind": "active_coverage",
          "network": "in_network",
          "insurance_type": "group_policy",
          "text": "In network, group policy: active coverage",
          "ref": "active_coverage[0]"
        }
      ]
    }
  },
  "totals": {
    "deductibles": [
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "individual",
        "period": "calendar",
        "service": "dental_care",
        "amount": "50.00",
        "text": "Dental care (general), in network, individual, calendar year: deductible $50.00",
        "ref": "deductible[0]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "individual",
        "period": "remaining",
        "service": "dental_care",
        "amount": "25.00",
        "text": "Dental care (general), in network, individual, remaining: deductible $25.00",
        "ref": "deductible[1]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "family",
        "period": "calendar",
        "service": "dental_care",
        "amount": "150.00",
        "text": "Dental care (general), in network, family, calendar year: deductible $150.00",
        "ref": "deductible[2]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "family",
        "period": "remaining",
        "service": "dental_care",
        "amount": "150.00",
        "text": "Dental care (general), in network, family, remaining: deductible $150.00",
        "ref": "deductible[3]"
      }
    ],
    "maximums": [
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "calendar",
        "service": "dental_care",
        "amount": "1500.00",
        "text": "Dental care (general), in network, individual, calendar year: maximum $1500.00",
        "ref": "maximums[0]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "remaining",
        "service": "dental_care",
        "amount": "1200.00",
        "text": "Dental care (general), in network, individual, remaining: maximum $1200.00",
        "ref": "maximums[1]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "lifetime",
        "service": "orthodontics",
        "amount": "1000.00",
        "text": "Orthodontics, in network, individual, lifetime: maximum $1000.00",
        "ref": "maximums[2]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "lifetime_remaining",
        "service": "orthodontics",
        "amount": "1000.00",
        "text": "Orthodontics, in network, individual, lifetime remaining: maximum $1000.00",
        "ref": "maximums[3]"
      }
    ]
  },
  "counts": {
    "payer_rows": 16,
    "lines": 16,
    "procedures": 2,
    "notes": 0,
    "history": 0
  },
  "links": {
    "complete": "/v1/eligibility/elg_9aqbap922506q92gx9ge/answer?contract=v3",
    "summary": "/v1/eligibility/elg_9aqbap922506q92gx9ge/answer?contract=v3&view=summary",
    "lines": "/v1/eligibility/elg_9aqbap922506q92gx9ge/answer?contract=v3&view=lines",
    "payer_answer": "/v1/eligibility/elg_9aqbap922506q92gx9ge/answer?view=payer",
    "pdf": "/v1/eligibility/elg_9aqbap922506q92gx9ge/pdf"
  },
  "billing": {
    "charged": false,
    "state": "NOT_BILLABLE",
    "reason": "test_mode",
    "label": "Test mode",
    "reason_label": "Test mode checks never reach a payer and are never charged"
  },
  "request": {
    "idempotency_key": "first-check-ab12cd",
    "idempotency_key_source": "header",
    "replayed": false,
    "reused": false,
    "corrections": [
      {
        "field": "patient.date_of_birth",
        "from": "YYYYMMDD",
        "to": "YYYY-MM-DD"
      }
    ],
    "payer_resolution": {
      "input": {
        "insurance": "94276"
      },
      "matched_payer_id": "94276",
      "matched_name": "Delta Dental",
      "method": "EXACT",
      "confidence": "HIGH"
    }
  }
}
InfoThe Idempotency-Key is optional on this request. Running the same command again the same day returns the same check (request.replayed: true and the Idempotent-Replayed: true header): no second check, no charge. Without a key, Claim House derives one from the check itself. Send "max_age_seconds": 0 to ask the payer again.

4. Read the answer and download the PDF

curl -sS "https://api.claimhouse.ai/v1/eligibility/elg_EXAMPLE0000000000001/answer?view=summary" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY"

# Make the PDF once, then ask for its short-lived download link.
curl -sS -X POST "https://api.claimhouse.ai/v1/eligibility/elg_EXAMPLE0000000000001/pdf" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY"
curl -sS "https://api.claimhouse.ai/v1/eligibility/elg_EXAMPLE0000000000001/pdf" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY"

# Paste the download_url from that answer. Never send your API key to the download link.
curl -sS --fail -o answer.pdf "PASTE_DOWNLOAD_URL_HERE"

Replace elg_EXAMPLE0000000000001 with the id from step 3. The check already returned the complete answer; view=summary is the short view an office usually needs, and it says how many lines of the complete answer it shows. The download link expires after expires_in_seconds; ask for a new one instead of checking again. Downloading in Python: if you see a certificate error on a Mac, install certifi and pass certifi.where() as the CA bundle. Never turn certificate checks off.

Built against the earlier check response? Send Claim-House-Version: 2026-10-01 on every request to keep it. Versions and changelog has the details.

Getting started

Reading an eligibility answer

Every block of the organized answer, what each line holds, and how to tell what the payer did not send.

An eligibility answer (contract eligibility.v3) is the payer's whole answer, organized. Every row the payer sent appears exactly once, as one line with one plain sentence that holds every value on it. Nothing is computed, merged or dropped: Claim House adds no total, no remaining amount, no network and no category the payer did not send. The check, the answer route, the dashboard and the complete PDF all show this one structure, so they cannot disagree.

Read it top to bottom

BlockWhat it holds
status, checked_at, verifiedThe coverage status (active, inactive, unknown), when the payer answered, and whether every truth check passed for this answer.
office, payerThe office, and the payer: name is Claim House's directory name, name_as_returned the payer's own. Neither replaces the other.
patient, subscriber, dependentsThe people exactly as the payer returned them.
as_requestedWhat you sent, with differences (fields the payer returned with another value) and not_returned (fields or a person the payer did not return). It never stands in for the payer's people.
planPlan fields as sent, coverage (status and each date under its own name: start, end, termination), the active coverage lines and plan notes.
totalsDeductibles, maximums and out of pocket that name no procedure code. A service type stays on the line as service.
by_serviceCoinsurance, copayment, limitation and other lines grouped by the payer's service type; not_stated when the payer named none.
by_procedureEvery line that names a CDT code, grouped by code, with that code's history.
historyEvery service date the payer sent, newest first.
not_covered, notesNot covered rows; payer notes and disclaimers that belong to no other line.
rejection, otherThe payer's refusal details, and anything else it sent at the top level, verbatim.
missing, not_readSections an office usually expects that the payer did not send; fields kept verbatim under other because they are not organized.
labels, counts, excluded, linksPlain words for the payer's tokens, the counts (payer_rows always equals lines), paths kept out on purpose, and where each view is read.

A line

Each line is one payer row: kind (its payer section), the row's fields under plain names, text, ref and, when needed, other. A field exists only when the payer sent its key; the names map one to one: coverage_level is level, plan_period is period, service_type is service, limitation is limit, quantity_qualifier is quantity_unit, age_limit is age, health_service_descriptions is frequency, payer_specific_description is note, and the rest keep their own names. From an executed test check:

{
  "kind": "deductible",
  "network": "in_network",
  "level": "individual",
  "period": "remaining",
  "service": "dental_care",
  "amount": "25.00",
  "text": "Dental care (general), in network, individual, remaining: deductible $25.00",
  "ref": "deductible[1]"
}
  • text is the line in one sentence and holds every value on the line. Show it as it is.
  • ref names the payer section and row (deductible[1]), the same index as view=payer, so every line can be traced to the payer's answer as received.
  • Money is a decimal string exactly as sent ("25.00"). percent is a number only when the payer sent a plain number; otherwise it is the string as sent.
  • A remaining amount is its own line with period: remaining (or lifetime_remaining), next to the plan amount in payer order. Claim House never computes one from the other and never pairs them.
  • Coinsurance reads "coinsurance N%", exactly as the payer states it. The payer's answer does not say whose share the percent is, so the line does not either.
  • Remaining rows, frequencies and notes are separate lines whenever the payer sent them as separate rows. Two rows are never merged, even when they look the same.

Procedure codes

Payers send codes as AD:D1110. A line with one qualifier and one CDT code is grouped under the bare code (code) and keeps code_as_sent; any other form is grouped under the value exactly as sent and never split. A row naming several codes is listed under each code with shared_with and counted once. Lines show the code only: no procedure names.

{
  "code": "D0120",
  "code_as_sent": "AD:D0120",
  "lines": [
    {
      "kind": "limitation",
      "network": "applies_all",
      "level": "individual",
      "limit": "2 visits in 1 calendar",
      "frequency": [
        {
          "quantity": "2",
          "quantity_qualifier": "visits",
          "time_period_qualifier": "calendar",
          "time_period_value": "1"
        }
      ],
      "service_dates": [
        {
          "latest_visit_or_consultation": "03/14/2026",
          "service_date": "03/14/2026",
          "type": "latest_visit_or_consultation",
          "value": "03/14/2026"
        }
      ],
      "text": "D0120, all networks, individual: limitation 2 visits in 1 calendar (frequency 2 visits per calendar year; last visit 03/14/2026)",
      "ref": "limitations[0]"
    }
  ]
}

What the payer did not send

  • missing lists sections an office usually expects that the payer did not send. An absent block means the payer sent nothing for it, never that coverage is absent.
  • not_read lists fields kept verbatim under a line's other because Claim House does not organize them. Nothing is dropped.
  • Fields that do not apply are absent, never null.

Verified, or withheld

verified: true means every truth check passed for this exact answer: payer rows in equal lines out, every value in its line unchanged, no number in a sentence that the payer did not send, group keys only from payer values. When a check fails, the organized answer is withheld: the check answers with verified: false, unverified_reason and links.payer_answer and no organized block, and the answer route answers 409 ANSWER_NOT_VERIFIED. The payer's answer as received (view=payer) still answers.

Views

ViewWhat it is
completeEverything above. The default for the check and the answer route.
summaryWhole lines selected from complete, never rewritten. It carries counts.complete_lines and counts.shown_lines (in the executed summary below, 24 of 26) and links.complete.
linesEvery line once, each with its group (for example by_procedure/D1110), for spreadsheets and analytics.
payerThe payer's answer as received, transport metadata removed.

Choose the summary's blocks and codes per call with fields= (for example fields=totals,D1110), or save them for your organization or one office with PUT /v1/settings/eligibility-summary. The default codes are D0120, D0140, D0150, D0210, D0220, D0272, D0274, D0330, D1110, D1120, D1206, D1208, D4341, D4342, D4910, D2740, D2750, D7140 and D7210.

{
  "view": "summary",
  "counts": {
    "complete_lines": 26,
    "shown_lines": 24
  },
  "summary": {
    "blocks": [
      "plan",
      "totals",
      "deductibles",
      "maximums",
      "out_of_pocket",
      "coinsurance",
      "procedures",
      "frequencies",
      "history",
      "not_covered",
      "missing_tooth",
      "waiting_periods"
    ],
    "procedures": [
      "D0120",
      "D0140",
      "D0150",
      "D0210",
      "D0220",
      "D0272",
      "D0274",
      "D0330",
      "D1110",
      "D1120",
      "D1206",
      "D1208",
      "D4341",
      "D4342",
      "D4910",
      "D2740",
      "D2750",
      "D7140",
      "D7210"
    ],
    "source": {
      "blocks": "default",
      "procedures": "default"
    }
  },
  "links": {
    "complete": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3",
    "summary": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3&view=summary",
    "lines": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3&view=lines",
    "payer_answer": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?view=payer",
    "pdf": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/pdf"
  }
}

On paper: two PDFs

POST /v1/eligibility/{eligibility_id}/pdf prints the same answer. kind=complete (the default) prints every line, as long as the answer is: procedure codes become a grid, one row per code and one column per network, and each line's sentence is printed once, in its cell or right under the row behind a letter. kind=streamlined prints the summary view's lines and says "Streamlined: N of M lines. The complete answer has every line." Each PDF is proven against the answer before it is stored.

curl -sS -X POST "https://api.claimhouse.ai/v1/eligibility/$CH_CHECK/pdf?kind=streamlined" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY"
{
  "livemode": false,
  "request_id": "evt_2gkn9cx9r15cs4ckz5td",
  "eligibility_id": "elg_m6ty5a8j8s4156mq1bs7",
  "artifact_id": "art_995q3cr3w14g739zampa",
  "filename": "elig_elg_m6ty5a8j8s4156mq1bs7-streamlined.pdf",
  "bytes": 89299,
  "contract": "eligibility.v3",
  "kind": "streamlined"
}
Getting started

Authentication and access

Authenticate with an API key, then permissions, office scope and mode decide what the call may do.

Send your key in the Authorization header on every request. The gateway then checks four things, in order: who is calling, what they may do, which offices they reach, and which environment they are in.

curl -s "https://api.claimhouse.ai/v1/me" \
  -H "Authorization: Bearer ch_test_key_EXAMPLE.secret_EXAMPLE"

API keys

  • Use the exact key shown once in your account. Its mode is reported by GET /v1/me. The secret is shown once when the key is created and can never be read back.
  • Your organization's first test key is made in the dashboard. A key with admin can mint equal or weaker keys with POST /v1/keys and revoke them with DELETE /v1/keys/{key_id}.
  • Unknown, malformed, wrong and revoked keys all return the same 401 UNAUTHORIZED. Five failures for one key from one address in 60 seconds block that key for 60 seconds.
  • The dashboard signs people in with a session token instead of a key. The session gets the same permission and office checks.

Permissions

PermissionUnlocks
readEvery read: claims, tracking, submissions, events, remittances, artifacts, offices, payers, eligibility results, drafts, keys, usage, GET /v1/me.
submitClaim submissions and drafts, eligibility checks and PDFs, attachment packets, drafts and sends.
webhooksCreate webhook endpoints, rotate secrets, list and replay deliveries.
adminMint and revoke keys, create and import offices, set claim naming, register an office for electronic attachments, confirm attachment provider profiles.

Permissions do not imply each other: an admin only key cannot read claims. Eligibility checks need submit because a live check reaches a payer. A missing permission returns 403 PERMISSION_DENIED.

Office scope

ScopeReaches
sellerEvery office in your organization.
groupEvery office in the granted groups, resolved on each request.
facilityExactly the granted offices.

Naming an office outside your scope returns 403 FACILITY_NOT_GRANTED. An id that belongs to another organization, or to an office you cannot reach, returns 404 NOT_FOUND so ids cannot be probed. Keys, usage, payers and webhook endpoints are organization-wide regardless of scope.

InfoAlways pass explicit scopeIds when you mint a group or facility key. A key minted without them reaches no office.
Getting started

Test mode

Test keys check sample patients at test offices. Nothing reaches a payer and nothing is charged.

Every key has a mode, test or production (live), shown on GET /v1/me. Read the mode from GET /v1/me; do not infer it from a key prefix. Every office has a binding, and the key's mode must match it:

Office binding_kindAccepts
sandboxTest keys
productionProduction keys
  • A key at the other kind of office returns 403 MODE_MISMATCH.
  • Test mode answers sample patients only, from a payer simulator. A request that names anyone else returns 422 NOT_A_TEST_PATIENT, before anything is recorded.
  • Name a sample with a magic member id in subscriber.memberId, such as CH-ACTIVE-FULL, with any names, date of birth and payer id, or with an exact sample patient from GET /v1/test/samples. Test outcomes lists every magic member id, one per outcome, and the X-Test-Scenario header.
  • CH-RATE-LIMIT answers 429 at once, so you can test your backoff.
  • Test checks are never charged: billing.reason is test_mode.
  • Offices you create with POST /v1/facilities are sandbox. An office goes live with POST /v1/facilities/{facility_id}/go-live once your organization has a card on file.

Limits

LimitValueOver the limit
Test checks500 a day per organization, reset at midnight UTC429 TEST_LIMIT_REACHED with Retry-After
New test offices50 a day per organization429 TEST_LIMIT_REACHED with Retry-After
Test requests10 a second per organization429 TEST_LIMIT_REACHED with Retry-After

Every test request counts toward the daily limit, including refused ones. Limits lists every limit in one place.

Getting started

Test outcomes

One magic member ID per outcome: answers, payer rejections, payer down, slow answers and more.

A test key answers a magic member ID with one fixed outcome, whatever names, date of birth and payer ID you send. Add a two digit suffix, for example CH-ACTIVE-FULL-02, to make distinct patients. Every outcome runs the real pipeline: refusals carry the live error codes, rejection reasons and next steps, and every test check is free (billing.reason test_mode). Answered outcomes have a readable answer and a PDF marked Test.

Magic member IDs work in single checks and in batches: each batch row is a single check, so one test file can exercise every outcome. The same table is returned by GET /v1/test/samples (scenarios).

Member IDOutcomeHTTP statusError or coverage statusNotes
CH-ACTIVE-FULLActive, full benefits200ACTIVE
CH-MAX-NEARLY-USEDMaximum nearly used200ACTIVE
CH-FREQUENCY-USEDFrequency used200ACTIVE
CH-WAITING-MAJORWaiting period on major200ACTIVE
CH-DEP-AGE-26Dependent child, covered to 26200ACTIVESend the child as the dependent.
CH-TERMINATEDCoverage ended200INACTIVEThe payer states coverage is not active; recorded as an answer.
CH-NOT-FOUNDMember not found (75)422PAYER_REJECTEDAlso CH-AAA-75.
CH-AAA-42Payer down (42)502VENDOR_ERRORDown on every try.
CH-MISSING-TOOTHMissing tooth clause200ACTIVE
CH-ORTHO-LIFETIMEOrthodontic lifetime maximum200ACTIVE
CH-SECONDARY-COBOther coverage (COB)200ACTIVE
CH-INACTIVEInactive coverage200INACTIVE
CH-AAA-72Invalid member ID (72)422PAYER_REJECTED
CH-AAA-73Invalid name (73)422PAYER_REJECTED
CH-AAA-71Birth date mismatch (71)422PAYER_REJECTED
CH-AAA-79Invalid participant (79)422PAYER_REJECTEDThe payer's rejection reason is PAYER_ID_INVALID, next step CHOOSE_PAYER.
CH-TIMEOUTPayer timed out502VENDOR_ERRORSent, and no answer came back: the outcome is uncertain.
CH-DHMODHMO copays200ACTIVE
CH-SPARSEPayer sends little200ACTIVE
CH-MALFORMEDUnreadable payer answer502VENDOR_ERROR
CH-ACTIVE-RICHActive, rich dental (frequencies and history)200ACTIVE
CH-TERMINATED-LAST-MONTHCoverage ended last month200INACTIVECoverage ended on the last day of last month.
CH-NOT-YET-EFFECTIVECoverage not yet effective200INACTIVECoverage starts on the first day of next month.
CH-DEP-OVER-AGEDependent over the age limit200INACTIVESend the child as the dependent. Coverage ended at the end of last month.
CH-SPOUSESpouse on the subscriber's plan200ACTIVESend the spouse as the dependent with relationship spouse.
CH-AAA-51Provider not on file (51)502VENDOR_ERRORThe payer's rejection reason is PROVIDER_NOT_ON_FILE, next step COMPLETE_SETUP.
CH-AAA-43Invalid provider ID (43)422PAYER_REJECTEDThe payer's rejection reason is PROVIDER_ID_INVALID, next step COMPLETE_SETUP.
CH-AAA-42-ONCEPayer down (42), first try only502PAYER_UNAVAILABLEDown on the first check of this patient; answered on a later new check (a new Idempotency-Key), so batch retries can be tested.
CH-SLOWSlow answer (20 seconds)200ACTIVEAnswered after about 20 seconds.
CH-VENDOR-ERRORNetwork error before the payer502VENDOR_ERRORThe network failed before reaching the payer. Free.
CH-NOT-EXTRACTEDAnswer with a section the summary does not extract200ACTIVEThe payer sent a waiting period section the summary does not read: it is listed in not_extracted, and the full answer shows it.
CH-MULTI-NETWORKIn network and out of network benefits200ACTIVEDeductibles, maximums and coinsurance for in network and out of network.
CH-PAYER-CHOICEPayer choice needed409PAYER_CHOICE_REQUIREDRefused with candidates unless the payer is one of the five sample payer IDs; send one of them to get an answer.
CH-RATE-LIMITRate limited (429)429TOO_MANY_REQUESTSNothing is counted or written.
  • Sample payer IDs: 94276 Delta Dental, 65978 MetLife Dental, 62308 Cigna Dental, 64246 Guardian, 52133 UnitedHealthcare Dental.
  • CH-AAA-42-ONCE is down on the first check of a patient and answered on a later new check (a new Idempotency-Key), so a batch's retry_payer_unavailable can be tried. Replaying the same key replays the recorded failure.
  • CH-PAYER-CHOICE: send an insurance name as the payer to get 409 PAYER_CHOICE_REQUIRED with candidates; send one of the sample payer IDs to get an answer. In a batch the row is NEEDS_PAYER.
  • CH-SLOW answers after about 20 seconds: set client timeouts above 30 seconds.

The X-Test-Scenario header

With a test key, X-Test-Scenario answers a sample patient (a catalog patient or a magic member ID) as another outcome. Send a scenario key (aaa_72), a magic token (AAA-72), a magic member ID (CH-AAA-72) or rate_limit. It never admits a real patient (422 NOT_A_TEST_PATIENT), always asks the simulator and never a saved answer, and an unknown value is 422 TEST_SCENARIO_UNKNOWN. A live key ignores it, and batch rows ignore it (use magic member IDs).

InfoX-Test-Scenario is not part of a check's identity: replaying the same Idempotency-Key replays the first result. Use a new key for each scenario.
Getting started

Sending once

Repeat a check safely with the same Idempotency-Key, and never resend one whose outcome is unknown.

You can safely repeat a request: the same Idempotency-Key with the same content returns the original answer, not a second check. And Claim House contacts a payer at most once per check: if the outcome is uncertain it says so and stops.

POST /v1/eligibility takes an Idempotency-Key. For the flat request it is optional: without one, Claim House derives one from the check's content and the UTC day (chk_ and 40 hex characters, no patient values in it), so the same check sent again the same day replays the first result, free, and a different check gets another key. max_age_seconds: 0, or a new key of your own, asks the payer again. The key a check ran under is always in request.idempotency_key. The camelCase and snake_case bodies still require the header.

What a repeat returns

You sendResult
Same key, same contentThe stored answer with idempotent_replay: true and the Idempotent-Replayed: true response header. No new check, no charge.
Same key, different content422 IDEMPOTENCY_KEY_REUSED
Same key while the first is still running, or an identical check already running409 ELIGIBILITY_OPERATION_PENDING. Nothing new was sent: wait a few seconds, then repeat the same request.

Keys belong to your organization, not to one API key. Use a random value such as a UUID and never derive it from patient or claim data. A check answered from a saved answer is recorded with your key too, so replaying that key returns the same answer.

Idempotent-Replayed: true is set on any response that replays a recorded result: POST /v1/eligibility with the same key (yours or the derived one) and body, and POST /v1/eligibility/batches with the same key and batch. The check also says request.replayed: true. A replayed refusal (for example a recorded PAYER_UNAVAILABLE) comes back as the original error, without the header.

When the outcome is unknown

  1. Your HTTP call timed out or returned a plain 500: send the same body with the same Idempotency-Key. You get the stored answer, 409 ELIGIBILITY_OPERATION_PENDING, or a normal first answer if the first request never arrived.
  2. A check returned 502 VENDOR_ERROR, 502 PAYER_UNAVAILABLE or 422 PAYER_REJECTED: Claim House will not retry it. Run a new check with a new key only when you decide to, after fixing what errors[0].rejection names. The error's next_step says which: FIX_REQUEST or NEW_CHECK_LATER.
ImportantRetry-After only permits retrying the local refusal that carried it (rate limit, quota, in-progress replay, auth block). It never authorizes resending a vendor action.
Getting started

Send what you have

Send the payer, office, dates and relationship the way your system holds them; every response says what Claim House changed.

The flat request is the simplest shape: office, insurance, member_id and patient, with relationship and subscriber for a dependent. You do not need to reshape your data for Claim House. Send the payer the way your practice system has it (a Claim House payer id, the payer's id, your practice system's payer id, the insurance name, or several of them in payer); name the office by its id, its office code or its exact name; write dates as YYYYMMDD, YYYY-MM-DD or MM/DD/YYYY; and give the relationship as a word or a code.

You haveSendNotes
The payer's id or nametradingPartnerServiceId (or payer_id), or the payer object: id, name, pms_carrier_id, group_number, employer_nameSend either, or both with the same id. tradingPartnerServiceId and payer.id naming different payers is 422 INVALID_ELIGIBILITY_REQUEST with finding PAYER_INPUT_CONFLICT. group_number and employer_name are recorded with the check and never sent to the payer.
The office's code or namefacilityId (or facility_id): the fac_ id, the office code or the exact office nameA code or name that matches more than one office you can use is 422 OFFICE_AMBIGUOUS with errors[0].candidates (facility_id, name, code); send the facility_id. One that matches none is 403 FACILITY_NOT_GRANTED.
Dates in your formatYYYYMMDD, YYYY-MM-DD or MM/DD/YYYY in either body shapeA date with slashes is always month first.
A relationship wordspouse, child or other in any case, or the code (01 spouse, 19 child; any other dependent code reads as other)On dependents[0].relationshipToSubscriberCode or patient.relationship.

What Claim House changed

Every successful check, including replays and saved answers, says what Claim House changed and how it matched the payer: request.corrections and request.payer_resolution under API version 2026-11-01 (request_corrections and payer_resolution at the top level under 2026-10-01, as in the executed example below). No corrections means the request was sent as written. For names, dates of birth and member ids it names the kind of change, never the value.

{
  "facilityId": "AAS",
  "payer": {
    "name": "Delta Dental",
    "id": "94276"
  },
  "subscriber": {
    "memberId": "CH-ACTIVE-FULL-02",
    "firstName": "Pat",
    "lastName": "Sample",
    "dateOfBirth": "01/15/1980"
  },
  "max_age_seconds": 0
}

A test check with that body (office code AAS is a test office) answered with these fields among the rest:

{
  "facility_id": "fac_sandboxsandboxsand",
  "payer_id": "94276",
  "reused": false,
  "payer_resolution": {
    "input": {
      "id": "94276",
      "name": "Delta Dental"
    },
    "matched_payer_id": "94276",
    "matched_name": "Delta Dental",
    "method": "EXACT",
    "confidence": "HIGH"
  },
  "request_corrections": [
    {
      "field": "subscriber.dateOfBirth",
      "from": "MM/DD/YYYY",
      "to": "YYYYMMDD"
    },
    {
      "field": "facilityId",
      "from": "AAS",
      "to": "fac_sandboxsandboxsand"
    }
  ]
}
payer_resolution.methodMeaning
EXACTA Claim House payer id or the payer's own id.
ALIASAnother id the payer is known by, or its exact name.
CONFIRMEDSomeone in your organization, or Claim House, confirmed this match.
LEARNEDAn earlier answer from that payer for this same input proved the match.

payer_resolution.confidence is HIGH, or MEDIUM for a match confirmed before the payer list last changed. Claim House never guesses a payer: when it is not sure, the check answers 409 PAYER_CHOICE_REQUIRED with the candidates, and a match is learned only after that payer answers for that input.

Control what you pay for: reuse

A check for the same patient, payer, office and visit date within an hour reuses the saved answer, and a reused answer is free (billing.reason cache_hit). max_age_seconds, in the body or the query, sets that window per request: up to 604800 (7 days) to reuse more, or 0 to always ask the payer. A reused answer says reused: true and cache.state: "hit", and keeps its own eligibility_id and retrieved_at, so you can see how old it is. Cache-Control: no-cache still forces a new check. Sending max_age_seconds in both places with different values is 422 INVALID_ELIGIBILITY_REQUEST with finding MAX_AGE_CONFLICT.

Getting started

Checking many patients

Hand over up to 10,000 patients in one request, preview it for free, follow progress, and read every answer back page by page or as one file.

Hand over a list and get every answer back. Send up to 10,000 patients to POST /v1/eligibility/batches as patients (each item exactly the single check's flat body), as JSON rows, or as csv text (up to 8 MB; the whole request up to 12 MB). Claim House validates them, runs each ready one as a normal check, and keeps every result on the batch. You do not write a loop, pace requests, retry refusals or invent an Idempotency-Key per patient.

  1. Preview first (free). Send "preview": true. Claim House checks every row, finds each office and payer, and flags duplicates. Nothing is sent and nothing is stored. Each row comes back READY, REFUSED (with problems), NEEDS_PAYER or DUPLICATE. In live mode the preview also says how many ready rows are past today's live check limit (counts.over_daily_limit, daily_limit); those rows will not be sent.
  2. Fix what it found. Rows with problems are listed with the field and plain words. Insurance names that match more than one payer are grouped in payer_choices: confirm each once with POST /v1/payer-mapping/mappings/{mapping_id}/confirm and preview again.
  3. Run it. Send the same body with "preview": false (the default) and an Idempotency-Key. You get 202 and a batch_id. Sending the same key and body again returns the same batch (Idempotent-Replayed: true); it never starts a second one.
  4. Follow progress. GET /v1/eligibility/batches/{batch_id} returns the state and counts, without rows. Poll it every few seconds while state is RUNNING.
  5. Read the results. Page through rows with GET /v1/eligibility/batches/{batch_id}/rows (500 at a time, up to 1,000), filtered by result (ACTIVE, INACTIVE, UNKNOWN, NOT_ANSWERED, REFUSED) or state, or download every row at once with GET /v1/eligibility/batches/{batch_id}/results (format=csv or jsonl). Each row has your reference and, when the check ran, its eligibility_id: open GET /v1/eligibility/{eligibility_id}/answer for the full answer, or make its PDF.
  6. Stop early if you need to. POST /v1/eligibility/batches/{batch_id}/cancel cancels every row not yet sent. Rows being checked at that moment finish.

The same check as one request: patients, with a top-level office and visit_date that apply to every item that leaves its own out. Results name each item by your reference and its index; under API version 2026-11-01 each answered row also links to its answer (links.answer, and answer_url in the results file).

curl -sS -X POST "https://api.claimhouse.ai/v1/eligibility/batches" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "preview": true,
  "office": "SBX",
  "visit_date": "2026-09-07",
  "patients": [
    {
      "reference": "appt-1",
      "insurance": "94276",
      "member_id": "CH-ACTIVE-FULL",
      "patient": {
        "first_name": "Avery",
        "last_name": "Molar",
        "date_of_birth": "1970-01-10"
      }
    },
    {
      "reference": "appt-2",
      "insurance": "94276",
      "member_id": "CH-TERMINATED",
      "patient": {
        "first_name": "Riley",
        "last_name": "Molar",
        "date_of_birth": "2015-06-02"
      },
      "relationship": "child",
      "subscriber": {
        "first_name": "Avery",
        "last_name": "Molar",
        "date_of_birth": "1970-01-10"
      },
      "visit_date": "2026-09-08"
    }
  ]
}'
curl -sS -X POST "https://api.claimhouse.ai/v1/eligibility/batches" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preview": true, "csv": "reference,office,payer,member_id,first_name,last_name,date_of_birth\nappt-1001,SBX,94276,CH-ACTIVE-FULL,Sample,Subscriber,1980-01-31\nappt-1002,SBX,94276,CH-TERMINATED,Sample,Subscriber,1975-06-15"}'
curl -sS -X POST "https://api.claimhouse.ai/v1/eligibility/batches" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Content-Type: application/json" \
  -H 'Idempotency-Key: batch-week-of-1005' \
  -d '{"reference": "week-of-1005", "retry_payer_unavailable": {"hours": 4}, "csv": "reference,office,payer,member_id,first_name,last_name,date_of_birth\nappt-1001,SBX,94276,CH-ACTIVE-FULL,Sample,Subscriber,1980-01-31\nappt-1002,SBX,94276,CH-TERMINATED,Sample,Subscriber,1975-06-15"}'
curl -sS "https://api.claimhouse.ai/v1/eligibility/batches/bat_EXAMPLE0000000000001" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY"
curl -sS "https://api.claimhouse.ai/v1/eligibility/batches/bat_EXAMPLE0000000000001/rows?result=NOT_ANSWERED&limit=500" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY"
curl -sS --fail -o results.csv "https://api.claimhouse.ai/v1/eligibility/batches/bat_EXAMPLE0000000000001/results?format=csv" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY"

Replace bat_EXAMPLE0000000000001 with your batch_id, and SBX with your test office's code or id.

Payer down? Ask again later, if you choose

By default each row is one check, and a payer that is not answering (502 PAYER_UNAVAILABLE) is final for that row, and free. To have Claim House ask the payer again later for you, add "retry_payer_unavailable": {"hours": 4} (1 to 24) when you create the batch. A row the payer did not answer is checked up to three more times, 1, 4 and 12 hours after its first check, for each of those that falls within the hours you chose. Each try is a new check with its own key, recorded on its own; payer-down checks are free. While a row waits for its next try it is PENDING with next_try_at, and its final result is the last try. Nothing else is tried again: a rejection, a timeout or an error is final.

Pull everything new

Every check a batch makes names its batch. GET /v1/eligibility?batch_id=... lists one batch's checks; GET /v1/eligibility?since=2026-10-05T00:00:00Z lists every check retrieved since your last pull, from batches and single checks alike, newest first, page by page with before.

CSV headers

Headers are matched without regard to case; spaces and dashes count as _. Other columns are ignored and listed in ignored_columns. RFC 4180 quoting, a byte order mark, and CRLF or LF line ends are all fine, up to 8 MB.

FieldAccepted headers
referencereference, ref, appointment_id, appt_id, tenant_reference, id
officefacility_id, office_id, office, facility, location: the office id, office code or display name
payerpayer, payer_id, insurance, insurance_name, carrier, carrier_name, elect_id
member IDmember_id, subscriber_id, memberid, insurance_id
first namefirst_name, subscriber_first_name, fname, subscriber_first
last namelast_name, subscriber_last_name, lname, subscriber_last
date of birthdate_of_birth, dob, birthdate, birth_date, subscriber_dob
group numbergroup_number, group, group_id
relationshiprelationship, patient_relationship, relation
patient first namepatient_first_name, patient_first
patient last namepatient_last_name, patient_last
patient date of birthpatient_date_of_birth, patient_dob, patient_birthdate
service dateservice_date, date_of_service, appointment_date, appt_date
proceduresprocedures: CDT codes separated by commas, semicolons or spaces
  • Dates: YYYY-MM-DD, YYYYMMDD or MM/DD/YYYY.
  • Relationship: self (the default when blank), spouse, child or other, any case, or the codes 18, 01, 19 and 34. Anything but self needs the patient's names and date of birth.
  • Office: its id, its office code or its display name. It must match exactly one office your credential can use.
  • The flat names work as headers too: insurance, member_id, patient_first_name, patient_last_name, patient_date_of_birth, subscriber_first_name, subscriber_last_name, subscriber_date_of_birth. A self row may give the person only in the patient_ columns.

Each patient is checked once

You sendResult
The same batch again with the same Idempotency-KeyThe same batch, idempotent_replay: true and the Idempotent-Replayed: true header. Nothing runs twice.
The same key with a different body422 IDEMPOTENCY_KEY_REUSED
Two identical rows in one batchThe later row is DUPLICATE and points at the first; one check runs.
The same row again the same day, in any batchIts stored answer, with idempotent_replay: true. No new payer request, no new charge.
A corrected row (another payer, a fixed member ID)A new check.

Busy moments are handled for you: a refusal made before any work (503 CAPACITY, 429 TOO_MANY_REQUESTS, 409 ELIGIBILITY_OPERATION_PENDING) is waited out and tried again, and never reaches a payer twice. Up to 8 rows of your organization run at once, payers interleaved, and single checks always keep room beside a running batch. Limits lists every batch limit.

Already export a day's schedule from your practice system? Sample adapters that turn it into a batch file are coming soon (SDKs and tools).

InfoEach row is a normal eligibility check with the same office access, limits and pricing as POST /v1/eligibility. In test mode every magic member ID works in a batch, so one file can exercise every outcome; CH-AAA-42-ONCE is down on the first check and answered on a later try, to try retry_payer_unavailable. Nothing reaches a payer and nothing is charged.

CSV results prefix formula-like text with an apostrophe so spreadsheet software treats it as text. JSON lines preserve the original values. References and messages may contain customer-supplied information; keep exports private. A partial export describes an unfinished batch. Read the final batch state and fetch a final export to reconcile every row.

Exports include X-Export-Started-At, X-Export-Complete and X-Export-Consistency headers. A download begun while running remains a live-pages observation even if the batch finishes during download. JSON lines include the same information and the capture end time in summary.export. Fetch a final export after completion for terminal results.

Getting started

Errors

Every refusal uses one JSON envelope with a stable machine code.

Every refusal uses one JSON envelope. Branch on error, then on next_step; never on message or user_message. Wording can change; codes do not.

{
  "error": "PAYER_REJECTED",
  "message": "The payer says the member ID is missing or not valid.",
  "errors": [
    {
      "eligibility_id": "elg_EXAMPLE0000000000001",
      "error_class": "VENDOR_REJECTED",
      "vendor_status": 400,
      "mode": "standard",
      "rejection": {
        "kind": "FIX_AND_RESEND",
        "retry_later": false,
        "summary": "The payer says the member ID is missing or not valid.",
        "reasons": [
          {
            "code": "MEMBER_ID_INVALID",
            "about": "subscriber",
            "message": "The payer says the member ID is missing or not valid.",
            "fix": "Enter the member ID exactly as it appears on the insurance card, including any letters and leading zeros.",
            "field": "subscriber.memberId",
            "next_step": "FIX_REQUEST"
          }
        ]
      },
      "billing": {
        "charged": false,
        "state": "NOT_BILLABLE",
        "reason": "test_mode",
        "label": "Test mode",
        "reason_label": "Test mode checks never reach a payer and are never charged",
        "unit_price_micros": null
      }
    }
  ],
  "request_id": "evt_EXAMPLE0000000000009",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-payer-rejected",
  "user_message": "The payer says the member ID is missing or not valid."
}
FieldTypeDescription
errorstringStable code.
messagestringA sentence for the developer.
errorsarrayStructured detail. Shape depends on the code. Never echoes a claim or patient value.
request_idstringSame value as the X-Request-Id header.
retryablebooleanTrue only for a 429, 503 CAPACITY and 409 ELIGIBILITY_OPERATION_PENDING. Then resend the same request with the same Idempotency-Key after retry_after_seconds.
retry_after_secondsinteger or nullSeconds to wait when Claim House knows it (the same as the Retry-After header); else null.
next_stepstringWhat to do next: RESEND_SAME_REQUEST, FIX_REQUEST, NEW_CHECK_LATER, CHOOSE_PAYER, CONTACT_SUPPORT, COMPLETE_SETUP or NONE. For a payer rejection, the first reason's next step.
doc_urlstringThis error's row in Error codes and retries: https://docs.claimhouse.ai/#error-<code in lowercase, underscores as dashes>.
user_messagestringA sentence safe to show a front desk, separate from the developer message. For a payer rejection, the rejection summary.

Error codes and retries lists every code with its status, whether to retry, with the same key or a new one, when, and what to fix, plus every payer rejection reason and request finding.

Payer rejections

When the payer turns a check down, errors[0].rejection explains it: kind, summary, and reasons[], each with a Claim House code, about, message, fix, field and its own next_step. If the payer turns a check down because the provider is not on file or was not enrolled on the service date, the next_step is COMPLETE_SETUP: confirm the provider's enrollment with that payer.

Validation errors

A 422 INVALID_REQUEST lists one item per problem with code, location (a dotted path such as body.subscriber.dateOfBirth), message, and value_redacted: true. Most request models refuse unknown fields, so send only documented fields.

Version header

A Claim-House-Version request header that names a version this API does not serve, is blank, or carries two different values is refused with 400 API_VERSION_UNKNOWN before authentication. Leave the header out to use the current version. See Versions and changelog.

Results that are not errors

  • A check the payer answered returns 200 even when coverage is inactive: read the coverage status in the answer.
InfoAn unmapped server fault returns a plain text 500 with no envelope. Treat it like a timeout: look the resource up, or repeat with the same Idempotency-Key.
Getting started

Error codes and retries

Every error code: whether to retry, with the same key or a new one, when, and what to fix.

Every error code the API returns, with what to do about it. Branch on error, then on next_step; never on message or user_message. Each code's row is the page doc_url points to. This page is generated from the same catalog the API reads, so it cannot drift from the API.

Next steps

next_stepWhat to doKey
RESEND_SAME_REQUESTSend the same request again, with the same Idempotency-Key, after retry_after_seconds.Same key
FIX_REQUESTChange the request as the error says, then send it with a new Idempotency-Key.New key
NEW_CHECK_LATERNothing in the request needs to change. Run a new check later with a new Idempotency-Key.New key
CHOOSE_PAYERPick one payer from the candidates in errors[0], then send the check with its payer ID.New key
CONTACT_SUPPORTThis needs Claim House. Contact support with the request_id.Do not retry yet
COMPLETE_SETUPFinish the account or office setup step the error names, then send the request again.Do not retry yet
NONENo action through the API. Read the message; the result may already be recorded.Do not retry yet
KeyMeaning
Same keyResend the same request with the same Idempotency-Key.
New keyAny new attempt is a new request with a new Idempotency-Key.
Do not retry yetDo not retry until the named step is done.

Eligibility

CodeStatusRetry?KeyWhenWhat to doFront desk sentence
ANSWER_NOT_VERIFIED409NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.The readable answer did not match the payer's response, so it is withheld. The original is retained.The readable answer could not be shown. The payer's original answer is kept.
BILLING_IDENTITY_MISMATCH403, 422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.Send the office's registered billing NPI, or leave provider out.The billing provider sent does not match the one registered for this office.
CAPACITY503YesSame keyRetry the same request with the same Idempotency-Key after retry_after_seconds.No payer slot was free within 2 seconds. Nothing was reserved, sent or charged.Many checks are running right now. Try again in a few seconds.
DAILY_LIMIT_REACHED429YesSame keyWait for the reset at midnight UTC (retry_after_seconds), then send the check again. Nothing was recorded, so the same Idempotency-Key is safe; a new one works too. Or ask to raise the limit.The organization's daily live check limit was reached. No payer inquiry was started and nothing was recorded. Contact Claim House to raise the limit.Your organization reached today's limit of live checks. It resets at midnight UTC.
ELIGIBILITY_CAPABILITY_NOT_READY409NoDo not retry yetSend the request again once the setup step is done.The office is not enabled for eligibility. errors[0].state names its setup state. Nothing was sent.This office is not set up for eligibility yet.
ELIGIBILITY_DENIED400NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The eligibility rail refused this request.Some details in this request need to be corrected before it can be sent.
ELIGIBILITY_EQUIVALENT_ACTIVE409NoDo not retry yetRead the named check with GET /v1/eligibility/{eligibility_id} instead of sending another.An equivalent check (same content, another key) is unresolved. errors[0].eligibility_id names it.The same check is still running. Wait a moment.
ELIGIBILITY_IN_FLIGHT409NoDo not retry yetWait, then repeat the same request with the same key to replay its result.A check with this Idempotency-Key is already reserved and running.This check is still running. Wait a moment.
ELIGIBILITY_OPERATION_PENDING409YesSame keyRetry the same request with the same Idempotency-Key after retry_after_seconds.An identical check is still running. Repeat the same request with the same Idempotency-Key in a few seconds to receive its result.This check is still running. Wait a moment.
ELIGIBILITY_RECONCILED_FAILURE409NoNew keyDo not resend this Idempotency-Key. Run a new check with a new key later.The check behind this key was reconciled to a final state with no ordinary result.This check ended without an answer. Run a new check.
ELIGIBILITY_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Live eligibility is not configured on this gateway. Test mode still works.Eligibility checks are not available right now.
ENHANCED_ELIGIBILITY_UNAVAILABLE503NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.mode=enhanced is not available. Leave out mode, or send mode=standard.Detailed benefits are not available on this account yet.
INVALID_ELIGIBILITY_REQUEST422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The check is missing something or has a value that cannot be sent. errors[0].findings names each problem.Some patient or insurance details need to be corrected before checking.
LIVE_LIMIT_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id to have the allowance set.Claim House could not confirm the organization's daily live check allowance: it could not be read, or it is set to 0 (no live checks admitted). This fails closed. No payer inquiry was started and nothing was recorded or charged. Test mode is not affected.Live checks are not available for your organization right now. Contact Claim House support.
NOT_A_TEST_PATIENT422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.Test keys check sample patients and CH- magic member IDs only (GET /v1/test/samples). Nothing was recorded.Test mode checks sample patients only. Pick a sample patient.
OFFICE_AMBIGUOUS422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The office name or code matches more than one office. Send one of errors[0].candidates as the office id.More than one office matches. Choose the office.
OFFICE_REQUIRED422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The flat request left office out, and the key does not reach exactly one office that takes checks in its mode. Send office as one of errors[0].candidates (its id, code or name). Nothing was sent.Choose the office for this check.
PAYER_CHOICE_REQUIRED409NoNew keySend the check again with the chosen payer ID and a new Idempotency-Key.The insurance sent matches more than one payer, or a suggestion needs confirming. Pick one of errors[0].candidates and send its payer_id.Choose which insurance company this is, then check again.
PAYER_NOT_SUPPORTED_FOR_ELIGIBILITY422NoNew keySend the check again with a supported payer ID and a new Idempotency-Key.No eligibility payer matches this payer ID or name. Search GET /v1/payers for a supported payer.Claim House cannot check eligibility with this insurance yet. Choose another payer or call the payer.
PAYER_REJECTED422NoNew keyFix the field named in the rejection, then run a new check with a new Idempotency-Key.The payer turned the check down for a reason the office can fix. Read errors[0].rejection: each reason has a fix, a field and its own next_step.The payer could not accept this check. Fix the details and check again.
PAYER_UNAVAILABLE502NoNew keyDo not resend this Idempotency-Key. Run a new check with a new key later.The payer did not answer (or is refusing calls for a short time). The check is recorded and free.The payer is not answering right now. Nothing needs to change; check again later.
PDF_NOT_MADE404NoNew keyMake the PDF, then read it.Make the PDF with POST /v1/eligibility/{eligibility_id}/pdf first. Reading never makes one.No PDF has been made for this answer yet.
PDF_NOT_VERIFIED409NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.The PDF did not pass its check against the payer's answer, so it is not served.The PDF could not be made for this answer. The answer itself is fine.
REQUEST_SHAPES_MIXED422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The body mixes the flat request (office, insurance, member_id, patient) with fields of the snake_case or camelCase shape. errors[0].flat_fields and errors[0].other_fields name them. Send one shape. Nothing was sent.Some details in this request need to be corrected before it can be sent.
TEST_MODE_ELIGIBILITY_DISABLED403NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Test mode eligibility is not connected on this gateway.Test checks are not available right now.
TEST_SCENARIO_UNKNOWN422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The X-Test-Scenario header names no test scenario. Use a scenario or magic member ID from GET /v1/test/samples.Some details in this request need to be corrected before it can be sent.
VENDOR_ERROR502NoNew keyDecide whether to run a new check with a new Idempotency-Key. Never resend the same key expecting a new attempt.One payer attempt was made and did not produce a usable answer. The check is recorded. If errors[0].rejection is present, its reasons say what to do.We could not get an answer from the payer this time. Check again later.

Batches

CodeStatusRetry?KeyWhenWhat to doFront desk sentence
BATCH_EMPTY422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The batch has no rows. Send rows or a CSV with at least one data row.Some details in this request need to be corrected before it can be sent.
BATCH_ROW_FAILED500NoNew keyDo not resend this Idempotency-Key. Run a new check with a new key later.A batch row could not be run after three tries and was closed. The other rows are not affected. No payer answer was recorded for it.This check could not be run. Check this patient again.
BATCH_TOO_LARGE422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The batch has more rows than one batch allows. Split it.Some details in this request need to be corrected before it can be sent.
CSV_INVALID422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The CSV could not be read. Check the header row, quoting and encoding (UTF-8).Some details in this request need to be corrected before it can be sent.
CSV_TOO_LARGE413NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The CSV is over the size limit for one batch. Split it.Some details in this request need to be corrected before it can be sent.
ELIGIBILITY_BATCHES_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Eligibility batches is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.

Payers

CodeStatusRetry?KeyWhenWhat to doFront desk sentence
PAYER_AMBIGUOUS409NoNew keySend the request again with the chosen payer ID.The payer name matches more than one payer. Pick one of the candidates and send its payer ID.Choose which insurance company this is.
PAYER_DIRECTORY_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.The payer directory is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
PAYER_ID_NOT_IN_CLAIMS_NETWORK422NoNew keySend it again with a listed payer ID.Confirm a payer ID listed for claims (GET /v1/payers).This payer ID is not one the claims network lists.
PAYER_NOT_ENROLLED409NoDo not retry yetSend the request again once the setup step is done.The office needs payer enrollment for this transaction before it can be sent.This office is not enrolled with this payer yet.

Any route

CodeStatusRetry?KeyWhenWhat to doFront desk sentence
API_VERSION_UNKNOWN400NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The Claim-House-Version header names a version this API does not serve. Send one of errors[0].supported_versions, or leave the header out to use the current version.Some details in this request need to be corrected before it can be sent.
ARTIFACT_URL_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Download links is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
IDEMPOTENCY_KEY_INVALID400NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The Idempotency-Key header is empty, too long or has characters that are not allowed.Some details in this request need to be corrected before it can be sent.
IDEMPOTENCY_KEY_REQUIRED400NoNew keyAdd the header and send the request.Add an Idempotency-Key header. Nothing was recorded.Some details in this request need to be corrected before it can be sent.
IDEMPOTENCY_KEY_REUSED422NoNew keySend the new content with a new Idempotency-Key, or resend the original content to replay it.This Idempotency-Key was already used with different content. Use a new key for new content.Some details in this request need to be corrected before it can be sent.
INVALID_CURSOR400, 422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The cursor is not one this list returned. Start from the first page.Some details in this request need to be corrected before it can be sent.
INVALID_REQUEST422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.Fix the fields named in errors[].location. Most bodies refuse unknown fields.Some details in this request need to be corrected before it can be sent.
NOT_FOUND404NoNew keyDo not retry with the same id. Check the id and the key.No resource with this id is visible to this key. Check the id and the key's office scope and mode.We could not find that item. It may have been removed, or you may not have access to it.
PAYLOAD_TOO_LARGE413NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The request body is over the route's size limit.This upload is too large. Send a smaller file.
REQUEST_REFUSED400, 405, 406, 415NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The HTTP method, path or content type is not one this route accepts.Some details in this request need to be corrected before it can be sent.
SERVICE_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.A part of the gateway this route needs is not wired in this deployment.Something on our side is not available right now. Try again later, or contact Claim House support.
VALIDATION422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.A field in the request is not valid. The message names it.Some details in this request need to be corrected before it can be sent.

Keys, sign-in and access

CodeStatusRetry?KeyWhenWhat to doFront desk sentence
ENTITLEMENT_REGISTRY_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.The product access registry is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
FACILITY_NOT_GRANTED403NoNew keyDo not retry with the same credentials. The key's office scope does not cover this office. Use an office from reachable_facility_ids on GET /v1/me.The key's office scope does not cover this office. Use an office from reachable_facility_ids on GET /v1/me.Your account does not have access to this office.
FEATURE_NOT_ENTITLED403NoDo not retry yetSend the request again once the setup step is done.The organization is not entitled to this product. Contact Claim House to turn it on.This feature is not turned on for your organization yet.
FORBIDDEN403NoNew keyDo not retry with the same credentials. The caller may not make this request.The caller may not make this request.Your account does not have access to do this. Ask an administrator in your organization.
LIVE_NOT_AVAILABLE403NoDo not retry yetSend the request again once the setup step is done.The organization or office has not completed the live rule for this product.Live work is not turned on for this organization yet.
LIVE_RULE_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.The live rule is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
MODE_HEADER_CONFLICT400NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The X-ClaimHouse-Mode header names a mode the credential cannot use, or conflicts with the key.Some details in this request need to be corrected before it can be sent.
MODE_MISMATCH403NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.Use a test key at test offices and a live key at live offices.This office is in a different mode (test or live) than your key.
PERMISSION_DENIED403NoNew keyDo not retry with the same credentials. Use a key or member role with the permission named in errors[0].permission.Use a key or member role with the permission named in errors[0].permission.Your account does not have access to do this. Ask an administrator in your organization.
SELLER_KEY_REQUIRED403NoNew keyDo not retry with the same credentials. This route needs an organization-wide key, not an office-scoped key.This route needs an organization-wide key, not an office-scoped key.Your account does not have access to do this. Ask an administrator in your organization.
SESSION_EXPIRED401NoNew keySign in again, then repeat the request.The dashboard session token has expired.Your session ended. Sign in again.
SESSION_REQUIRED403NoNew keyDo not retry with the same credentials. This route is for a signed-in dashboard member, not an API key.This route is for a signed-in dashboard member, not an API key.Your account does not have access to do this. Ask an administrator in your organization.
TEST_LIMITS_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Sandbox limits is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
TEST_LIMIT_REACHED429YesSame keyWait for the reset (retry_after_seconds), then send the request again. Nothing was recorded, so the same Idempotency-Key is safe; a new one works too.A daily sandbox limit (test checks or sandbox offices per day) was reached. Nothing was recorded. retry_after_seconds counts down to the reset at midnight UTC. Under API version 2026-10-01 the per second test limit also answers with this code, with errors[0].limit set to requests_per_second, a retry_after_seconds of about a second and the per second sentence as user_message; under 2026-11-01 it answers with TEST_RATE_LIMITED.Today's test limit is used up. It resets at midnight UTC.
TEST_MODE_ONLY403NoNew keyDo not retry with the same credentials. This route works in test mode only. Use a test key or switch the dashboard to Test.This route works in test mode only. Use a test key or switch the dashboard to Test.This is available in test mode only.
TEST_RATE_LIMITED429YesSame keyWait retry_after_seconds (about a second), then send the same request again. Nothing was recorded, so the same Idempotency-Key is safe.The sandbox limit on test requests per second for your organization was reached (API version 2026-11-01; under 2026-10-01 this answers TEST_LIMIT_REACHED with errors[0].limit set to requests_per_second). Nothing was recorded. errors[0].cap is the limit.Too many test requests at once. Try again in a second.
TOO_MANY_REQUESTS429YesSame keyRetry the same request with the same Idempotency-Key after retry_after_seconds.The key or organization is over its request rate. Back off for Retry-After seconds.Too many requests right now. Try again in a moment.
UNAUTHORIZED401NoNew keyDo not loop: five failures in 60 seconds block the key for 60 seconds. Fix the key, then retry.The key is unknown, its secret is wrong, or it was revoked. The body never says which.Claim House could not confirm who is signed in. Sign in again.

API keys

CodeStatusRetry?KeyWhenWhat to doFront desk sentence
KEYS_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Key management is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
KEY_ALREADY_REVOKED409NoDo not retry yetNo retry is needed.The key is already revoked.This key was already revoked.
KEY_ESCALATION403NoNew keyDo not retry with the same credentials. A key cannot be given more permissions, offices or modes than the member creating it has.A key cannot be given more permissions, offices or modes than the member creating it has.Your account does not have access to do this. Ask an administrator in your organization.

Organization, offices and team

CodeStatusRetry?KeyWhenWhat to doFront desk sentence
ACTIVATION_CONFLICT409NoNew keyRead the current state, then send the change again based on it.The organization status changed. Reload it.This changed since you opened it. Reload the page and try again.
ACTIVATION_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Activation is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
CLAIM_NAMING_IMMUTABLE409NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Claim naming is fixed once the office has sent claims.This office setting cannot be changed now.
CONFIRMATION_REQUIRED409NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.This action needs an explicit confirmation field in the request.Please confirm before continuing.
DELEGATION_EXCEEDED403NoNew keyDo not retry with the same credentials. A member cannot grant a role higher than their own.A member cannot grant a role higher than their own.Your account does not have access to do this. Ask an administrator in your organization.
FACILITY_EXISTS409NoNew keyUse the existing office.An office with this identity already exists in the organization.This office already exists.
FACILITY_NOT_FOUND404NoNew keyCheck the office id.No office with this id is visible to the caller.We could not find that item. It may have been removed, or you may not have access to it.
GO_LIVE_REFUSED409NoDo not retry yetSend the request again once the setup step is done.errors[0] lists what is missing before the office can go live.This office is not ready to go live yet.
GO_LIVE_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Taking offices live is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
IDENTITY_REGISTRY_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.The identity registry is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
IDENTITY_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Identity is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
INVALID_ORGANIZATION_CANDIDATES422NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.The organization candidates in the request are not valid.Some details in this request need to be corrected before it can be sent.
INVITATION_DELIVERY_UNCONFIGURED503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Invitation email delivery is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
INVITATION_IDENTITY_MISMATCH403NoNew keyDo not retry with the same credentials. The invitation belongs to another email address.The invitation belongs to another email address.This invitation was sent to a different email address.
MEMBERSHIP_CHANGE_REFUSED409NoNew keyRead the current state, then send the change again based on it.The membership change would leave the organization without an owner, or is not allowed.This changed since you opened it. Reload the page and try again.
MEMBERSHIP_CONFLICT409NoNew keyRead the current state, then send the change again based on it.The membership already exists or conflicts with an existing one.This person is already a member.
MEMBERSHIP_REQUIRED403NoNew keyDo not retry with the same credentials. An active organization membership is required.An active organization membership is required.Your account does not have access to do this. Ask an administrator in your organization.
NOTIFICATION_SETTINGS_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Notification settings is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
OFFICE_CODE_TAKEN409NoNew keyDo not resend it as is. Fix the request, then send it with a new Idempotency-Key.Office codes are unique within the organization.That office code is already in use. Choose another.
OFFICE_ON_CLEARINGHOUSE_SANDBOX409NoDo not retry yetSend the request again once the setup step is done.The office is on the sandbox binding; take it live before live work.This office is still a test office.
ORGANIZATION_REQUIRED403NoNew keyDo not retry with the same credentials. The signed-in user has no organization yet.The signed-in user has no organization yet.Your account does not have access to do this. Ask an administrator in your organization.
OWNER_VERIFICATION_REQUIRED403NoNew keyDo not retry with the same credentials. Only the verified invited owner can do this.Only the verified invited owner can do this.Your account does not have access to do this. Ask an administrator in your organization.
PROVISIONING_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Account provisioning is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
REGISTRY_WRITE_FAILED503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Saving to the registry is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
SELF_SERVE_CONFLICT409NoDo not retry yetNo retry is needed.An account for this organization already exists.This organization already has an account. Sign in instead.
SELF_SERVE_NOT_ALLOWED403NoNew keyDo not retry with the same credentials. Self-serve sign-up is not open for this account.Self-serve sign-up is not open for this account.Your account does not have access to do this. Ask an administrator in your organization.
SELF_SERVE_RATE_LIMITED429YesSame keyRetry the same request with the same Idempotency-Key after retry_after_seconds.Sign-up attempts from this source are rate limited.Too many sign-up attempts. Try again in a moment.
SELF_SERVE_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Self-serve sign-up is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
STALE_VERSION_OR_STATE409NoNew keyRead the current state, then send the change again based on it.The record changed since it was read. Reload and send the change again.This changed since you opened it. Reload the page and try again.
VERIFIED_EMAIL_REQUIRED403NoNew keyDo not retry with the same credentials. Verify the email address on the account first.Verify the email address on the account first.Verify your email address, then try again.

Billing

CodeStatusRetry?KeyWhenWhat to doFront desk sentence
BILLING_ACCOUNT_REQUIRED409NoDo not retry yetSend the request again once the setup step is done.The organization has no billing account yet.Your organization needs a billing account first.
BILLING_CUSTOMER_REQUIRED409NoDo not retry yetSend the request again once the setup step is done.No card is on file for the organization.Add a card first.
BILLING_INTERNAL409NoDo not retry yetNo retry is needed.Internal accounts need no card.This account is never charged and needs no card.
BILLING_PROCESSOR_MODE_MISMATCH409NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.The card setup was made in a different mode than this account uses.Something on our side is not available right now. Try again later, or contact Claim House support.
BILLING_REQUIRED402NoDo not retry yetSend the request again once the setup step is done.Live mode needs a payment method on file for the organization.Live checks need a card on file. Add one in Settings.
BILLING_UNAVAILABLE503NoDo not retry yetDo not retry in a loop. Contact Claim House support with the request_id.Billing is not available on this gateway right now. Nothing was changed.Something on our side is not available right now. Try again later, or contact Claim House support.
INVALID_EVENT400NoDo not retry yetNo retry is needed.The billing event is not one Claim House accepts.This request could not be read.
SIGNATURE_INVALID400NoDo not retry yetNo retry is needed.The billing event signature did not verify.This request could not be verified.

Payer rejection reasons

When the payer turns a check down, errors[0].rejection.reasons[] carries one of these codes, with its own fix and next_step. The top-level next_step is the first reason's. No value from your request is ever echoed.

CodeX12 AAA codesKindMessageFixnext_step
ACCESS_RESTRICTED41REJECTEDThe payer did not allow this check.Call the payer to check eligibility, or contact Claim House support.CONTACT_SUPPORT
AGE_OR_GENDER_MISMATCH69, 70FIX_AND_RESENDThe payer says this check does not fit the subscriber's age or gender.Check the subscriber's date of birth and the procedure codes, then check again.FIX_REQUEST
CHECK_NOT_FINISHEDNonePAYER_UNAVAILABLEThis check stopped before an answer was recorded.Check again with a new Idempotency-Key. Nothing needs to change in the request.NEW_CHECK_LATER
DATE_OF_BIRTH_AFTER_SERVICE60FIX_AND_RESENDThe subscriber's date of birth is after the service date.Check the date of birth and the service date.FIX_REQUEST
DATE_OF_BIRTH_INVALID58FIX_AND_RESENDThe payer says the subscriber's date of birth is missing or not valid.Enter the subscriber's date of birth and check again.FIX_REQUEST
DATE_OF_BIRTH_MISMATCH71FIX_AND_RESENDThe date of birth does not match the payer's records for the subscriber.Check the subscriber's date of birth against the insurance card or a photo ID.FIX_REQUEST
DATE_OF_DEATH_ON_FILE61REJECTEDThe payer's records show a date of death before the service date.Make sure this is the right member and service date. Call the payer if it is.NONE
GENDER_REQUIRED66, 74REJECTEDThe payer needs the subscriber's gender, and this check does not send it.Check eligibility with the payer directly for now, and tell Claim House support which payer asked.CONTACT_SUPPORT
MEMBER_ID_DUPLICATE68, 76FIX_AND_RESENDThe payer has more than one member with this ID.Check the subscriber's name and date of birth exactly as they appear on the insurance card so the payer can tell them apart. Adding the group number can help.FIX_REQUEST
MEMBER_ID_INVALID64, 72FIX_AND_RESENDThe payer says the member ID is missing or not valid.Enter the member ID exactly as it appears on the insurance card, including any letters and leading zeros.FIX_REQUEST
MEMBER_NOT_FOUND75FIX_AND_RESENDThe payer could not find this member.Check the member ID and the subscriber's name and date of birth exactly as they appear on the insurance card.FIX_REQUEST
NAME_INVALID65, 73FIX_AND_RESENDThe payer says the subscriber's name is missing or does not match.Enter the first and last name exactly as they appear on the insurance card, with no nicknames.FIX_REQUEST
NOT_IN_GROUP78FIX_AND_RESENDThe payer found the member, but not in the group or plan given.Check the group number on the insurance card, or leave it out and check again.FIX_REQUEST
OUTCOME_UNKNOWNNonePAYER_UNAVAILABLEThe payer did not answer in time, so the result of this check is unknown.Check again with a new Idempotency-Key. Nothing needs to change in the request.NEW_CHECK_LATER
OUT_OF_NETWORK35REJECTEDThe payer says this provider is out of network for this plan.Call the payer to confirm the member's out of network benefits.NONE
PATIENT_NOT_FOUND67FIX_AND_RESENDThe payer could not find this patient.Check the subscriber's name and date of birth and the member ID exactly as they appear on the insurance card.FIX_REQUEST
PATIENT_NOT_ON_PLAN77FIX_AND_RESENDThe payer found the subscriber but not this patient on the plan.Check the patient's name, date of birth and relationship to the subscriber. If the patient has their own member ID, check them as the subscriber.FIX_REQUEST
PAYER_ID_INVALID79FIX_AND_RESENDThe payer did not accept the insurance chosen for this check.Choose the insurance again from the list and check again.CHOOSE_PAYER
PAYER_NOT_ANSWERING42, 80PAYER_UNAVAILABLEThe payer is not answering right now.Try again in a few minutes; nothing needs to change.NEW_CHECK_LATER
PAYER_REJECTED_OTHERNoneREJECTEDThe payer turned down this check without a reason we recognize.Check the member ID, names and dates of birth exactly as they appear on the insurance card, then check again. If it happens again, contact Claim House support.FIX_REQUEST
PROCEDURE_CODE_INVALID54, 55FIX_AND_RESENDThe payer did not accept a procedure code on this check.Check the procedure codes, or leave them out, and check again.FIX_REQUEST
PROVIDER_DETAILS_INVALID45, 46, 47, 48, 97REJECTEDThe payer says some of the provider's details are missing or not valid.Contact Claim House support so the office's provider details can be checked.COMPLETE_SETUP
PROVIDER_ID_INVALID43FIX_AND_RESENDThe payer did not accept the provider's NPI or tax ID.Check the provider NPI and tax ID for this office. Contact Claim House support if they are right.COMPLETE_SETUP
PROVIDER_NAME_INVALID44FIX_AND_RESENDThe payer says the provider's name is missing or does not match its records.Check the provider or practice name for this office. Contact Claim House support if it is right.COMPLETE_SETUP
PROVIDER_NOT_ALLOWED49, 50, 53REJECTEDThe payer does not accept eligibility checks from this provider.Call the payer to check eligibility, or confirm the provider's enrollment with them.NONE
PROVIDER_NOT_ENROLLED_ON_DATE52REJECTEDThe payer says the provider was not enrolled with this plan on the service date.Check the service date. If it is right, confirm the provider's enrollment with the payer.COMPLETE_SETUP
PROVIDER_NOT_ON_FILE51REJECTEDThe payer does not have this provider on file.Confirm the provider's enrollment with this payer, or contact Claim House support.COMPLETE_SETUP
REQUEST_INCOMPLETE15, 33FIX_AND_RESENDThe payer says something on this check is missing or not valid.Check the member ID, names and dates of birth exactly as they appear on the insurance card, then check again.FIX_REQUEST
SERVICE_DATE_INVALID56, 57FIX_AND_RESENDThe payer says the service date is missing or not valid.Check the service date and check again.FIX_REQUEST
SERVICE_DATE_IN_FUTURE63FIX_AND_RESENDThe payer does not answer for a service date this far ahead.Use today's date, or a date closer to the appointment, and check again.FIX_REQUEST
SERVICE_DATE_OUT_OF_RANGE62FIX_AND_RESENDThe service date is outside the dates the payer will answer for.Use today's date, or a date within the last year, and check again.FIX_REQUEST

Request findings and batch row problems

A check refused before anything was sent (422 INVALID_ELIGIBILITY_REQUEST) names its findings in errors[0].findings. A batch row refused at preview or run carries problems[] with these codes.

CodeWhereFieldMessagenext_step
CODE_INVALIDBatch rows (problems[].code)NoneThis code is not valid.FIX_REQUEST
DAILY_LIMIT_REACHEDBatch rows (problems[].code)NoneToday's live check limit is reached, so this row was not sent. Send it again tomorrow.NEW_CHECK_LATER
DATE_INVALIDBatch rows (problems[].code)NoneUse YYYY-MM-DD, YYYYMMDD or MM/DD/YYYY.FIX_REQUEST
DATE_OF_BIRTH_IN_FUTUREPOST /v1/eligibility (errors[0].findings); Batch rows (problems[].code)date_of_birthThe date of birth is after the service date.FIX_REQUEST
FIELD_INVALIDBatch rows (problems[].code)NoneThis value is not text.FIX_REQUEST
FIELD_REQUIREDBatch rows (problems[].code)NoneThis field is required.FIX_REQUEST
FIELD_TOO_LONGBatch rows (problems[].code)NoneThis value is too long.FIX_REQUEST
MAX_AGE_CONFLICTPOST /v1/eligibility (errors[0].findings)Nonemax_age_seconds in the body and in the query disagree. Send one, or make them agree.FIX_REQUEST
MAX_AGE_INVALIDBatch rows (problems[].code)NoneUse a whole number of seconds from 0 to 604800 (7 days).FIX_REQUEST
MODE_INVALIDPOST /v1/eligibility (errors[0].findings)NoneUse mode standard, enhanced or auto.FIX_REQUEST
MODE_MISMATCHBatch rows (problems[].code)NoneThis office does not take checks in this mode.FIX_REQUEST
NOT_A_TEST_PATIENTBatch rows (problems[].code)NoneTest mode checks sample patients and magic member IDs only.FIX_REQUEST
OFFICE_AMBIGUOUSBatch rows (problems[].code)NoneMore than one office matches; use the office id or code.FIX_REQUEST
OFFICE_NOT_GRANTEDBatch rows (problems[].code)NoneThis office is not one you can check for.FIX_REQUEST
OFFICE_UNKNOWNBatch rows (problems[].code)NoneNo office you can use has this id, code or name.FIX_REQUEST
PATIENT_DATE_OF_BIRTH_REQUIREDPOST /v1/eligibility (errors[0].findings); Batch rows (problems[].code)patient.date_of_birthThe patient's date of birth is required.FIX_REQUEST
PATIENT_IS_SUBSCRIBERPOST /v1/eligibility (errors[0].findings); Batch rows (problems[].code)patientThe patient is the policy holder; use relationship self and leave the patient out.FIX_REQUEST
PATIENT_NAME_REQUIREDPOST /v1/eligibility (errors[0].findings); Batch rows (problems[].code)patient.first_nameThe patient's first and last name are required.FIX_REQUEST
PATIENT_NOT_ALLOWEDBatch rows (problems[].code)NoneLeave the patient out when the patient is the policy holder (relationship self).FIX_REQUEST
PATIENT_RELATIONSHIP_INVALIDPOST /v1/eligibility (errors[0].findings); Batch rows (problems[].code)relationshipUse spouse, child or other for a patient who is not the policy holder.FIX_REQUEST
PATIENT_RELATIONSHIP_REQUIREDPOST /v1/eligibility (errors[0].findings); Batch rows (problems[].code)relationshipSay how the patient relates to the policy holder.FIX_REQUEST
PATIENT_REQUIREDBatch rows (problems[].code)NoneA spouse, child or other check needs the patient's first name, last name and date of birth.FIX_REQUEST
PAYER_INPUT_CONFLICTPOST /v1/eligibility (errors[0].findings)NoneThe payer ID and payer.id name two different payers. Send one, or make them agree.FIX_REQUEST
PAYER_NOT_SUPPORTEDBatch rows (problems[].code)NoneNo supported eligibility payer matches this insurance.CHOOSE_PAYER
PAYER_REQUIREDPOST /v1/eligibility (errors[0].findings)NoneName the payer: send tradingPartnerServiceId, or the payer object.FIX_REQUEST
PAYER_TEXT_INVALIDBatch rows (problems[].code)NoneUse up to 80 letters, digits, spaces, dots, dashes or underscores.FIX_REQUEST
PROCEDURE_CODE_INVALIDPOST /v1/eligibility (errors[0].findings); Batch rows (problems[].code)proceduresUse CDT procedure codes such as D0120.FIX_REQUEST
RELATIONSHIP_INVALIDBatch rows (problems[].code)NoneUse self, spouse, child or other (or 18, 01, 19, 34).FIX_REQUEST
SUBSCRIBER_DATE_OF_BIRTH_REQUIREDPOST /v1/eligibility (errors[0].findings); Batch rows (problems[].code)date_of_birthThe policy holder's date of birth is required.FIX_REQUEST
SUBSCRIBER_MEMBER_ID_REQUIREDPOST /v1/eligibility (errors[0].findings); Batch rows (problems[].code)member_idThe member ID is required.FIX_REQUEST
SUBSCRIBER_NAME_REQUIREDPOST /v1/eligibility (errors[0].findings); Batch rows (problems[].code)first_nameThe policy holder's first and last name are required.FIX_REQUEST
TOO_MANY_PROCEDURE_CODESPOST /v1/eligibility (errors[0].findings); Batch rows (problems[].code)proceduresSend at most 10 procedure codes.FIX_REQUEST
Getting started

Pagination and rate limits

Follow the cursor each list route returns. Limits lists every rate, concurrency and daily limit.

List routes grew with the rails they serve, so paging style varies. Always pass back exactly the cursor the previous page returned and treat it as opaque.

RouteStylePage size (default / max)Order
GET /v1/eligibilitybefore from the previous page's next; since sets the oldest time100 / 500Newest first
GET /v1/eligibility/batcheslimit only20 / 50Newest first
GET /v1/eligibility/batches/{batch_id}/rowscursor from next_cursor (same filters)500 / 1,000Row order
GET /v1/payerspageToken, nextPageToken50 / 50Payer id
GET /v1/facilities/{facility_id}/eligibilitysince and limit, no cursor100 / 500Newest first

Rate limits

Every key has a read and a write rate and a cap on requests in flight, and each organization has daily allowances. Limits lists each one with its value, what it returns and how to raise it. A 429 or 503 CAPACITY is returned before any work, so the identical request is safe to resend after Retry-After.

  • Keys of the same organization have separate rate buckets but share the idempotency namespace.
  • Keep concurrency at or below 10 per key and add jitter. For long lists use a batch instead of a loop.
Getting started

Pricing and what's charged

Price per eligibility check, the monthly minimum, and which checks are charged or free.

Eligibility checks are priced per check by monthly volume across your whole organization. Every check says whether it is charged and why, and the Usage page lists every unit, so you never have to ask us what a charge was for.

Price per check

Checks in the monthPrice per check
1 to 250$0.30
251 to 3,500$0.15
3,501 to 10,000$0.10
10,001 and up$0.08

Each check is priced at the tier it falls in: the 251st check of a month costs $0.15 whatever the first 250 cost. Volume counts across every office in your organization and starts again each calendar month (UTC).

Monthly minimum

  • The monthly minimum is $1,000. Your charges count toward it; when a month's charges are lower, the difference is added as one line on the statement.
  • It starts the day your first office goes live, prorated by days for that first month. No live office, no minimum.
  • Your first 3 live months have a $500 minimum instead (for months from October 2026 on).

What's charged

A check is charged when it reaches the payer and the payer replies: the payer answered, or the payer rejected the member, the provider or the request. These are the reasons a charged check carries:

ReasonLabelWhat happened
answeredPayer answeredThe payer answered this check; checks the payer answers are charged.
payer_rejected_patientPayer could not find the memberThe payer could not find this member; checks that reach the payer are charged.
payer_rejected_providerPayer did not accept the providerThe payer did not accept the provider on this check; checks that reach the payer are charged.
payer_rejected_requestPayer rejected the request detailsThe payer could not check the dates, procedures or other details sent; checks that reach the payer are charged.

What's free

Free checks are counted, so your usage is complete, but never charged: the payer was down, the request never reached the payer, our errors, saved answers and test mode.

ReasonLabelWhat happened
payer_unavailablePayer was downThe payer could not answer at the time; not charged.
request_rejectedRequest refused before the payerThe request was refused before it reached the payer; not charged.
vendor_input_errorRequest refused before the payerThe request's details were refused before the payer saw them; not charged.
transport_failureConnection failedThe connection to the payer failed before an answer came back; not charged.
not_sentNever sentThe check was never sent to the payer; not charged.
malformed_answerOur errorThe payer's answer could not be read; not charged.
our_configurationOur errorA Claim House setup problem stopped this check; not charged.
cache_hitSaved answerA saved answer from a recent identical check was returned; not charged.
test_modeTest modeTest mode checks never reach a payer and are never charged.
operator_testClaim House testingClaim House ran this check to test the service; not charged.
not_classifiedPayer reply not classifiedThe payer's reply could not be classified when it was recorded; not charged.

Only eligibility checks that reach the payer and get a reply are priced. Always free:

  • Test mode, including test batches.
  • Batch previews: nothing is sent and nothing is stored.
  • PDFs, and every read of a stored check or answer.
  • Reused answers (reused: true, reason cache_hit) and same-key replays.
  • Checks the payer did not answer (payer_unavailable).
  • Checks refused before they reached the payer.

Under review

ReasonLabelWhat happened
under_reviewUnder reviewThe payer's reply is being reviewed; it is charged only if it proves to be a payer answer.

A reply we cannot classify yet is held, not charged, until Claim House reviews it. It is then charged only if it proves to be a payer answer. A month's statement is final only when nothing in it is under review.

Where you see it

  • Every eligibility response (POST /v1/eligibility, GET /v1/eligibility/{eligibility_id} and each row of the lists) carries billing: charged (true, false, or null while under review), state, reason, label and reason_label.
  • GET /v1/usage counts each product's units by reason and state (by_reason) and shows the month's tiers; GET /v1/usage/units lists every unit with its reason, office and who sent it.
  • The dashboard's Usage page shows the same counts, and each check shows its reason with "Rated at" and the price so far (an estimate until the month closes; the monthly minimum may apply) or "Not charged".
InfoStatements are built after each month closes. How and when your card is charged is added to this page when card charging opens.
Getting started

Limits

Rates, concurrency, daily allowances and batch sizes, what each returns, and how to raise it.

Every limit Claim House enforces on the routes that are live today, generated from the values the API enforces, so this page cannot drift from them.

LimitValueScopeApplies toOver the limitTo raise it
Write requests per key20 a secondPer keyRequests that start work: eligibility checks, PDFs, batches, claims, attachments.429 TOO_MANY_REQUESTS, Retry-After: 1 second; safe to resend as is.Spread the load over more keys, or contact Claim House support with your organization id and the volume you need.
Read requests per key100 a secondPer keyReads: lists, answers, results files, payer directory, account.429 TOO_MANY_REQUESTS, Retry-After: 1 second; safe to resend as is.Spread the load over more keys, or contact Claim House support with your organization id and the volume you need.
Requests in flight per key20 at oncePer keyEvery authenticated request still being answered for one key.429 TOO_MANY_REQUESTS, Retry-After: 1 second; safe to resend as is.Wait for answers before sending more, or use a batch for large lists.
Failed sign-ins per key5 failures in 60 secondsPer key and addressAfter 5 failed authentications in 60 seconds from one address, that key id is blocked from that address for 60 seconds.401 UNAUTHORIZED, Retry-After: 60 seconds.Not raisable. Fix the key secret.
Live eligibility checks per organization per day2,000 a dayPer organizationLive checks that reach the payer network. Saved answers (reused) and test mode do not count. A batch preview shows the remaining allowance, and rows past it are refused up front.429 DAILY_LIMIT_REACHED, Retry-After: seconds until midnight UTC; safe to resend as is.Claim House staff can raise it for your organization. Contact Claim House support with your organization id and the volume you need.
Eligibility checks running at once per organization20 at oncePer organizationChecks waiting on a payer at the same time. A check that cannot start within 2 seconds is refused before anything is sent or charged.503 CAPACITY, Retry-After: 2 seconds; safe to resend as is.Contact Claim House support with your organization id and the volume you need.
Test mode requests per organization10 a secondPer organizationRequests made with a test key or in test mode.429 TEST_RATE_LIMITED, Retry-After: 1 second; safe to resend as is.Claim House staff can raise it for your organization. Contact Claim House support with your organization id and the volume you need.
Test eligibility checks per organization per day500 a dayPer organizationTest mode only. Never reaches a payer and is never charged.429 TEST_LIMIT_REACHED, Retry-After: seconds until midnight UTC; safe to resend as is.Claim House staff can raise it for your organization. Contact Claim House support with your organization id and the volume you need.
Test offices created per organization per day50 a dayPer organizationTest mode only. Never reaches a payer and is never charged.429 TEST_LIMIT_REACHED, Retry-After: seconds until midnight UTC; safe to resend as is.Claim House staff can raise it for your organization. Contact Claim House support with your organization id and the volume you need.
Rows per batch10,000 rowsPer requestPOST /v1/eligibility/batches, as rows or CSV lines.422 BATCH_TOO_LARGE.Split the list into more batches.
Batch CSV size8 MBPer requestThe csv text in a batch request, at most 8 MB.413 CSV_TOO_LARGE.Split the file into more batches.
Batch request body size12 MBPer requestThe whole JSON body of POST /v1/eligibility/batches, at most 12 MB.413 PAYLOAD_TOO_LARGE.Split the list into more batches.
Batch rows per page1,000 rowsPer requestGET /v1/eligibility/batches/{batch_id}/rows takes limit 1 to 1000 (default 500).422 INVALID_REQUEST.Not raisable. Follow next_cursor, or download the results file.
Batches per list page50 batchesPer requestGET /v1/eligibility/batches takes limit 1 to 50 (default 20).422 INVALID_REQUEST.Not raisable. Follow the cursor.
Batch rows running at once per organization8 at oncePer organizationRows of your batches checked at the same time, payers interleaved. Batches always leave 8 of your organization's running checks free for single checks, so the front desk is never blocked by a batch.No error.Claim House staff can raise it for your organization. Contact Claim House support with your organization id and the volume you need.
Payer down: tries again within24 hoursPer requestWith the opt-in, a row whose payer did not answer is tried again at 1, 4, 12 hours after the first try (4 tries at most), within 1 to 24 hours you choose.No error.Not raisable.
  • A 429 carries a Retry-After header and retry_after_seconds in the body. Wait Retry-After seconds, then resend the same request with the same Idempotency-Key.
  • A 429 or 503 CAPACITY is returned before any work, so nothing was sent or charged.
  • Daily limits reset at midnight UTC.
  • If your organization's daily live allowance cannot be read, live checks are refused with 503 LIVE_LIMIT_UNAVAILABLE before anything is sent or charged. Test mode is not affected.
  • Contact Claim House support with your organization id and the volume you need.
Getting started

Versions and changelog

Every response names its API version; pin one with a header. Breaking changes only come under a new date.

Every response carries a Claim-House-Version header naming the API version it was served under, today 2026-11-01. Supported versions: 2026-10-01, 2026-11-01.

  • Every response carries the Claim-House-Version header naming the version it was served under.
  • Send the same header on a request to pin a version. A version this API does not serve is refused with 400 API_VERSION_UNKNOWN; leave the header out to use the current version.
  • Additive changes (new routes, new optional fields, new response fields, new error codes, new headers) arrive in place under the current version. Build clients that ignore fields they do not know.
  • Breaking changes (removing or renaming a field, changing a type, an HTTP status or an error code) only arrive under a new dated version, announced here first.
curl -sS "https://api.claimhouse.ai/v1/me" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Claim-House-Version: 2026-11-01"

What each version returns

VersionDefaultWhat it returns
2026-11-01YesEligibility checks, check reads and the answer route return the organized answer (contract eligibility.v3): every payer row as one line with one plain sentence, grouped by procedure code and by service, with nothing computed, merged or dropped. Batch rows link to it.
2026-10-01NoThe check returns the check summary, a check read returns the check record, and the answer route defaults to contract eligibility.v2. Send Claim-House-Version: 2026-10-01 on every request to keep these responses.

To keep an earlier version's responses, send its date on every request, for example Claim-House-Version: 2026-10-01. Every response names the version it was served under, so a client can check it.

Changelog

2026-11-01: The organized answer by default, the flat request and summary settings

API version 2026-11-01. Breaking.

  • Changed: POST /v1/eligibility returns the answer, contract eligibility.v3: every payer row exactly once as one line with one plain sentence, grouped into totals, by service and by procedure code, plus billing, request (your reference, the Idempotency-Key it ran under, replayed, reused, corrections, payer_resolution) and idempotent_replay. Fields that do not apply are absent, never null. Send Claim-House-Version: 2026-10-01 to keep the earlier check response.
  • Changed: An answer whose truth checks did not pass is never shown by the check: it answers 200 with verified false, unverified_reason and links.payer_answer, and no organized lines.
  • Changed: GET /v1/eligibility/{eligibility_id} returns the same answer with billing and what was sent (reference, Idempotency-Key, group number, procedure codes). A check the payer did not answer reads status not_answered with a failure block.
  • Changed: GET /v1/eligibility/{eligibility_id}/answer defaults to contract eligibility.v3, view complete (view=readable reads as complete). contract=v2 still serves the earlier readable answer, and view=full needs contract=v2.
  • Added: Answer views: complete, summary (whole lines selected from complete, never rewritten, with complete_lines and shown_lines), lines (one flat list for spreadsheets) and payer (as received). fields= narrows a summary by block and CDT code.
  • Added: GET and PUT /v1/settings/eligibility-summary read and save which blocks and procedure codes the summary shows, for the organization or one office.
  • Added: The flat request: office, insurance, member_id and patient, with relationship and subscriber for a dependent. Its Idempotency-Key is optional: without one, the same check sent again the same UTC day replays for free. The camelCase and snake_case shapes are still accepted, unchanged.
  • Added: Batches take patients, a list of flat requests, with a top-level office and visit_date that apply to every item that leaves its own out.
  • Added: Batch rows the payer answered carry links.answer and links.summary, and the results file ends with an answer_url column.
  • Changed: The PDF routes default to kind=complete: every line of the answer, as long as the answer is, in a compact layout (procedure codes as a grid, one row per code and one column per network), its own file (elig_{eligibility_id}-complete.pdf). include=pdf on the check makes this PDF too. Send Claim-House-Version: 2026-10-01, or contract=v2, for the earlier PDF.
  • Added: kind=streamlined on the PDF routes: the lines the summary view selects (saved summary settings, else the default), headed with how many it shows of how many, each line byte-equal to the complete answer's. Its own file (elig_{eligibility_id}-streamlined.pdf); a changed setting makes a new one. contract=v3 stays an alias for kind=complete.
  • Added: New error codes OFFICE_REQUIRED (a flat request without office from a key that reaches several offices) and REQUEST_SHAPES_MIXED (a body that mixes the flat request with another shape).
  • Changed: The per second test limit answers with its own code, TEST_RATE_LIMITED; TEST_LIMIT_REACHED now means a daily test limit only. Under 2026-10-01 it keeps TEST_LIMIT_REACHED.
  • Fixed: The per second test limit's user_message no longer says today's test limit is used up, under both versions.

2026-10-04: Batch at scale, actionable errors, test scenarios, payer directory and easier input

API version 2026-10-01.

  • Added: Batches take up to 10,000 rows: a CSV up to 8 MB or a JSON body up to 12 MB.
  • Changed: GET /v1/eligibility/batches/{batch_id} returns the summary and counts without rows; page the rows with GET /v1/eligibility/batches/{batch_id}/rows (state and result filters, up to 1,000 a page, next_cursor). Batches were not released before this change.
  • Added: A results file streams one line per row as CSV or JSON lines, with no patient values, at any time while the batch runs.
  • Added: Cancel a batch: waiting rows stop, running rows finish. Calling cancel again changes nothing.
  • Added: Checks made by a batch carry batch_id and reference, and GET /v1/eligibility filters by batch_id and since.
  • Added: The batch preview shows today's remaining live check allowance, and rows past it are refused up front with DAILY_LIMIT_REACHED.
  • Added: Opt in to try a row again when the payer did not answer: at 1, 4 and 12 hours, within the hours you choose.
  • Added: Every error body adds retryable, retry_after_seconds, next_step, doc_url and user_message beside the existing error, message, errors and request_id. A published retry matrix lists every code.
  • Added: A response that replays a recorded result for a repeated Idempotency-Key carries Idempotent-Replayed: true.
  • Added: Test mode covers every outcome: magic member IDs (CH-ACTIVE-FULL and others) and the X-Test-Scenario header choose the answer, each with a readable answer and a PDF marked Test. Batches in test mode take every magic member ID.
  • Added: Payer directory: search payers with what each supports per transaction, the search combinations each accepts, and enrollment_required.
  • Added: Payer health: answered rate and payer unavailable rate over the last hour and day, so you can tell a payer outage from a problem in your request.
  • Added: Send the payer as whatever you have (an optional payer object with id, name, practice system carrier id, group number or employer); every check returns payer_resolution saying how it was matched.
  • Added: Name the office by its id, its code or its exact name; more than one match answers 422 OFFICE_AMBIGUOUS with the candidates.
  • Added: Dates accept YYYYMMDD, YYYY-MM-DD and MM/DD/YYYY, and relationship accepts words as well as codes. Every change Claim House made to your input is listed in request_corrections.
  • Added: max_age_seconds controls reuse of a saved answer (0 always asks the payer); a reused answer says reused: true and stays free.
  • Added: GET /v1/me adds reachable_facilities with each office's id, name, code, city, state and mode, beside reachable_facility_ids. Facility rows add name.
  • Added: Every response carries Claim-House-Version, and a request may pin a version with the same header.
  • Changed: The public OpenAPI declares the shared error envelope (Error) on every operation, the Claim-House-Version, X-Test-Scenario and Idempotent-Replayed headers, typed responses for checks, GET /v1/me, offices and payers (PayerRecord, PayerPage), stable operation ids, examples and bearer security, so it generates clients cleanly. Operation ids changed from the framework-derived form.
  • Changed: A test-mode member ID, name or date of birth rejection names the request field in rejection.reasons[].field (for example subscriber.memberId), as a live payer rejection does.

2026-10-01: Baseline version

API version 2026-10-01.

  • Added: The first dated version. It covers the API as served on this date: eligibility checks with readable answers and PDFs, offices, keys, payers, and test mode with sample patients.
Getting started

SDKs and tools

The public OpenAPI description, plain text docs for AI agents, and what is coming: SDKs, request collections and sample adapters.

Everything here is built from the same public contract as this reference, so it never drifts from the API.

OpenAPI

The public OpenAPI 3.1 description of every live operation is at https://docs.claimhouse.ai/openapi.json. Each operation has a stable operationId, request and response examples, bearer authentication, and the shared error envelope (Error) as its answer to every refusal. Generate a client from it with any OpenAPI generator.

Docs for AI agents

  • https://docs.claimhouse.ai/llms.txt indexes every page.
  • https://docs.claimhouse.ai/llms-full.txt is every page in one file.
  • Every page has a Markdown twin at /docs/<page>.md, for example https://docs.claimhouse.ai/docs/guide-quickstart.md and https://docs.claimhouse.ai/docs/check-eligibility.md.

Coming soon

  • SDKs: TypeScript and Python clients generated from the public OpenAPI, with an Idempotency-Key made per call and reused on every retry, retries only where the error envelope says retryable, typed errors and batch helpers. They are not published yet; until then, call the API directly. The Quickstart and every endpoint's examples work as copied.
  • Command line: the claimhouse command checks a patient, runs a day's schedule and prints an answer from your terminal, built on the Python SDK. Not published yet; Command line describes it.
  • Request collections: every live request, ready to import into an API client, with one test check per magic member ID.
  • Sample adapters: short, read-only examples that turn a day's schedule from your practice system into a batch file for Checking many patients.
InfoNothing on this page needs an install today. When the SDKs and collections are published, this page will say where to get them.
Getting started

Command line

Check a patient, a day's schedule or an answer from your terminal with the claimhouse command. Not published yet.

ImportantThe claimhouse command line tool is not published yet. Until it is, it installs only from a local copy of the Python SDK source, and this page says how it works so you can plan for it. When it is published, this page will say where to get it.
pipx install "./sdks/python[keychain]"   # from a local copy of the SDK source, until publishing

Sign in

claimhouse login     # paste your API key; it is checked with GET /v1/me, then kept in your keychain
claimhouse whoami    # mode (test or live), organization, offices by name and code
claimhouse logout    # removes the stored key

The key is kept in your computer's keychain, never in a file and never printed. Without a keychain, set CLAIMHOUSE_KEY for your shell; when it is set it is used before the stored key. A test key prints a reminder that the command ran in test mode.

Check one patient

claimhouse check --office SBX --insurance 94276 --member CH-ACTIVE-FULL \
  --first Test --last Patient --dob 1980-01-01

Prints one screen: status, plan, coverage dates, deductibles and maximums, coinsurance by service, the commonly scheduled codes with their frequencies and history, not covered, what the payer did not send, and whether the answer is verified. Every line is the answer's own text, exactly as the API returns it. It ends with the number of lines in the complete answer and the command that shows them.

FlagMeaning
--officeOffice id, code or name; optional when your key reaches one office
--insurancePayer id, practice-system payer id or insurance name
--member, --first, --last, --dobThe member ID and the patient
--relationship child|spouse|otherThe patient is a dependent; add --sub-first, --sub-last, --sub-dob for the policy holder
--group, --visit-date, --procedures D1110,D0120, --referenceOptional
--max-age SECONDSReuse an answer at most this old; 0 asks the payer again
--view summary|completeWhat to print (default summary)
--jsonPrint the exact check response

The same check sent twice on the same day replays the first answer and is not charged again. Dates take any of the three accepted formats.

Read an answer

claimhouse answer elg_EXAMPLE0000000000001                 # the complete answer, paged
claimhouse answer elg_EXAMPLE0000000000001 --view summary  # also lines, or payer (as received)
claimhouse answer elg_EXAMPLE0000000000001 --json
claimhouse pdf elg_EXAMPLE0000000000001 -o answer.pdf      # makes the PDF first if needed

Check many patients

claimhouse batch preview schedule.csv --office SBX
claimhouse batch run schedule.csv --office SBX
claimhouse batch status bat_EXAMPLE0000000000001
claimhouse batch results bat_EXAMPLE0000000000001 -o results.csv
claimhouse batch cancel bat_EXAMPLE0000000000001

run previews the file (counts, problems by row, payer choices, the daily limit), asks before sending (--yes skips the question), runs, waits with progress, writes results.csv next to your file (or results-<batch id>.csv when that exists; -o picks the name) and prints the totals. --office fills the office on rows that name none. Stopping the wait does not stop the batch. The results file carries ids, codes and statuses, no patient details.

Exit codeMeaning
0Success
1Refused: the API's error code, message, user_message, next_step, doc_url and request id are printed. Also a declined confirmation, nothing ready to run, or a lost connection.
2Usage: a bad or missing flag, no API key, an address that is not https
VariableUse
CLAIMHOUSE_KEYThe API key (used before the stored key)
CLAIMHOUSE_API_BASEThe API address, default https://api.claimhouse.ai; plain http only on this computer
PAGERThe pager for answer and check --view complete
Getting started

Claim lifecycle (coming soon)

How a claim moves from queued to paid, and what each clearinghouse and payer response means.

Coming soon. This is not available yet. The full guide appears here when it is released.

Getting started

Webhooks (coming soon)

Receive signed claim events at your HTTPS endpoint instead of polling.

Coming soon. This is not available yet. The full guide appears here when it is released.

Getting started

Getting each claim to the right payer

How Claim House reads the payer you send, corrects it only when the evidence proves it, and tells you what it did.

InfoClaims and attachments are coming soon. This is how their payer IDs are handled when they open.

Every claim and every attachment carries its own payer. Claim House resolves it to the ID the payer is reached by, in this order, and stops at the first step that decides.

  1. A payer ID the claims network lists is sent as you gave it. If the carrier name clearly names a different payer, the claim waits and the message names the other payer.
  2. An ID the network does not list, or no ID, uses the payer your office confirmed for that carrier.
  3. Otherwise Claim House corrects it only on proof: an older or alternate ID that points to exactly one payer whose listed name is exactly the carrier name, or no ID and a carrier name the network lists for exactly one payer.
  4. Anything else waits with the payer Claim House found pre-filled, or a shortlist. Confirm it once for that carrier and every claim for it continues.

A correction is never silent: the response, the claim and its webhooks carry submittedPayerId, the correction and a PAYER_ID_CORRECTED or PAYER_ID_FILLED note with the ID to put in your system. A correction never changes the carrier you chose, and never writes to your practice system.

An office can choose to confirm every correction instead: PUT /v1/facilities/{facility_id}/payer-settings with autocorrect: confirm.

A claim and its attachment are matched separately. If they name different payers, both are sent as given and you get a note.

API reference

Eligibility

Check a patient's dental coverage with the eligibility vendor, store the answer, and render it as a PDF.

ImportantBeta. Checks and PDFs answer 503 ELIGIBILITY_UNAVAILABLE when eligibility is not configured on the gateway, and the deployed vendor configuration was not confirmed when these docs were written. Reading stored answers and office history works regardless.
  • A check makes at most one vendor call and Claim House never retries it. If the vendor rejects the access token, Claim House fetches a new token once and posts the same check once more; a second rejection is AUTH_FAILED.
  • A timeout, connection failure or unreadable answer is stored as a failure with its own eligibility_id and returned as 502 VENDOR_ERROR with an error_class. It is never served from cache.
  • An uncertain outcome is not a success. Before checking again, read GET /v1/eligibility/{eligibility_id} or the office history. Checking again with the same Idempotency-Key replays the stored failure; a live retry needs a new key, and that is your decision.
  • Every answer states absence explicitly: optional values are null, never zero. not_extracted names summary fields Claim House did not extract into a convenience value; the payer may still have sent that information, so read the full answer. The check-summary not_returned field is deprecated and empty on new summaries. The readable answer has a separate section-level not_returned list for expected sections that are absent or empty; it is not proof that related information is absent elsewhere.
ModeWhat happens
standard (default)The vendor's standard eligibility answer.
enhancedDetailed benefits. Coming soon. Today it is refused with 503 ENHANCED_ELIGIBILITY_UNAVAILABLE before any payer is called and before anything is billed.
autoRuns standard today (detailed benefits are coming soon). The mode used is always returned as mode.
  • A successful answer for the same office, payer, subscriber, dependent, service date and resolved mode is reused for your account's window (default 3600 seconds; 0 disables it). max_age_seconds sets the window per request, 0 to 604800. Names, member id and group number match case insensitively.
  • A reused answer returns the original eligibility_id and retrieved_at with reused: true, cache.state: "hit" and cache.age_seconds. It makes no payer call, adds no history row and is free. It is recorded with your Idempotency-Key, so replaying that key returns the same answer.
  • Procedure codes must match for an answer to be reused. Send Cache-Control: no-cache (the dashboard's "Skip the answer we already have from today") or max_age_seconds: 0 when you need a new answer.
You sendResult
New Idempotency-KeyA saved answer within the reuse window if one matches, else one payer call.
Same key, same contentThe recorded answer replayed with idempotent_replay: true and the Idempotent-Replayed: true header, or the recorded failure as its original error. No payer call.
Same key, different content422 IDEMPOTENCY_KEY_REUSED. Content is office, payer, subscriber and dependent identity, service date, procedure codes and resolved mode. Your tenantReference is not content.
Same key twice at once, or an identical check already running409 ELIGIBILITY_OPERATION_PENDING. Nothing new was sent: wait a few seconds and repeat the same request.
No key400 IDEMPOTENCY_KEY_REQUIRED.

Which response should I build on?

The readable answer, GET /v1/eligibility/{eligibility_id}/answer, is the complete, source-labeled contract: every payer row as sent, with its qualifiers. The summary fields on the check response (deductibles, maximums, coinsurance and the rest) are a convenience: they can omit qualifiers the full answer keeps, and not_extracted names what the summary did not extract. Build decisions on the readable answer; use the summary for quick display.

API reference

Check eligibility

POSThttps://api.claimhouse.ai/v1/eligibility

Check one patient's insurance at one office and get the payer's whole answer back, organized and proven: every payer row as one plain line.

Send the office, the insurance, the member ID and the patient. Claim House calls the payer at most once, never retries, and answers with the payer's whole answer organized (contract eligibility.v3): totals, coinsurance by service, every procedure code with its frequencies and history, not covered, notes. Every payer row is one line with one plain sentence; nothing is computed, merged or dropped. Reading an eligibility answer explains every block.

The Idempotency-Key is optional for this flat request: without one, Claim House derives one from the check's content and the UTC day, so the same check sent again the same day replays for free. max_age_seconds: 0, or a new key of your own, asks the payer again. The key the check ran under is in request.idempotency_key.

A matching answer saved within the reuse window (1 hour unless your organization has another) is returned without a payer call, free, with request.reused: true. Set the window per request with max_age_seconds, or send Cache-Control: no-cache to always ask the payer.

This is API version 2026-11-01, the default. To keep the earlier check response (the check summary), send Claim-House-Version: 2026-10-01. The camelCase and snake_case bodies are still accepted, unchanged, under both versions; they still need an Idempotency-Key.

Permission
submit
Idempotency
optional for the flat request (derived from the check's content and the UTC day when left out); required for the camelCase and snake_case bodies
Side effects
Contacts the eligibility vendor exactly once unless the answer is replayed or served from cache, stores one result row (success or vendor failure), and emits eligibility.checked. With include=pdf also stores a PDF artifact.
In the dashboard
Eligibility > New check

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret
Idempotency-KeystringOptional for the flat request: without it Claim House derives one (chk_ and 40 hex characters) from your organization, the key's mode, the office, the payer, the member ID, the people, the relationship, the visit date and the UTC day, and returns it in request.idempotency_key. Required for the camelCase and snake_case bodies (400 IDEMPOTENCY_KEY_REQUIRED). Keys are unique per organization for all time. A replay carries the Idempotent-Replayed: true header.
e.g. first-check-ab12cd
Cache-ControlstringAny value containing no-cache skips the cache and makes a live vendor call.
e.g. no-cache
Content-Type*stringMust be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.
e.g. application/json
X-Test-ScenariostringTest keys only. Answers a sample patient (catalog patient or magic member id) as this scenario: a scenario key (aaa_72), a magic token (AAA-72), a magic member id (CH-AAA-72) or rate_limit. Unknown values are 422 TEST_SCENARIO_UNKNOWN. Ignored with a live key. Not part of the check's identity: use a new Idempotency-Key per scenario.
e.g. CH-AAA-72
Claim-House-VersionstringPins the API version: 2026-11-01 (the default) answers with the v3 answer; 2026-10-01 answers with the earlier check summary. An unknown value is 400 API_VERSION_UNKNOWN. Every response carries the header.
e.g. 2026-11-01

Query parameters

NameTypeDescription
modestringLevel of detail. Default standard. enhanced (detailed benefits) is coming soon and is refused today with 503 ENHANCED_ELIGIBILITY_UNAVAILABLE; auto runs standard until then. Overrides a body mode.
one of: standard · enhanced · auto
e.g. auto
includestringComma list. pdf renders a PDF of the answer and adds artifact_id and pdf_filename to the response.
e.g. pdf
max_age_secondsintegerReuse a saved answer only when it is at most this old, 0 to 604800 (7 days). 0 always asks the payer. Leave it out for the default window. The same as the body field: send it once, or the same value in both.
e.g. 0

Request body

NameTypeDescription
officestringThe office: its fac_ id, its office code or its exact name. Optional when your key reaches exactly one office that takes checks in its mode; otherwise 422 OFFICE_REQUIRED with errors[0].candidates. A name or code that matches two offices is 422 OFFICE_AMBIGUOUS.
e.g. fac_EXAMPLE0000000000001
insurance*stringThe payer: a Claim House payer id, the payer's own id, your practice system's payer id or the insurance name as the office records it. When Claim House is not sure, the check answers 409 PAYER_CHOICE_REQUIRED with candidates; it never guesses.
e.g. 94276
member_id*stringThe policy holder's member ID, as on the card.
e.g. CH-ACTIVE-FULL
patient*objectThe person being seen.
first_name*stringFirst name.
e.g. Test
last_name*stringLast name.
e.g. Patient
date_of_birth*stringYYYY-MM-DD, YYYYMMDD or MM/DD/YYYY.
e.g. 19800101
relationshipstringThe patient's relationship to the policy holder: self (the default), spouse, child or other, in any letter case, or the codes 18, 01, 19 (any other two-digit code reads as other).
one of: self · spouse · child · other
subscriberobjectThe policy holder, when the patient is a dependent (relationship spouse, child or other). Sending it without a dependent relationship is 422 INVALID_ELIGIBILITY_REQUEST with finding PATIENT_RELATIONSHIP_REQUIRED.
first_name*stringFirst name.
last_name*stringLast name.
date_of_birth*stringYYYY-MM-DD, YYYYMMDD or MM/DD/YYYY.
group_numberstringThe policy holder's group number.
visit_datestringThe visit date, in any of the three formats. Defaults to today (UTC).
proceduresarrayUp to ten CDT codes to ask about, in any letter case.
e.g. ["D0120","D1110"]
referencestringYour own reference (up to 200 characters), returned in request.reference and kept with the check.
e.g. appt-1001
max_age_secondsintegerReuse a saved answer only when it is at most this old, 0 to 604800. 0 asks the payer again (and makes a derived key fresh). From 1 to 86399 the derived key also becomes a window of that many seconds, so a replay is never older than you asked.
e.g. 0
viewstringThe view the check answers with: complete (the default), summary, lines or payer.
one of: complete · summary · lines · payer

Request example

{
  "office": "SBX",
  "insurance": "94276",
  "member_id": "CH-ACTIVE-FULL",
  "patient": {
    "first_name": "Riley",
    "last_name": "Molar",
    "date_of_birth": "2015-06-02"
  },
  "relationship": "child",
  "subscriber": {
    "first_name": "Avery",
    "last_name": "Molar",
    "date_of_birth": "1970-01-10"
  },
  "procedures": [
    "D0120",
    "d1110"
  ],
  "visit_date": "20260907",
  "view": "summary"
}

Response fields

NameTypeDescription
id*stringThe check id, elg_.... A reused answer keeps the original check's id.
contract*stringAlways eligibility.v3.
one of: eligibility.v3
view*stringThe view served: complete (the default), summary, lines or payer.
one of: complete · summary · lines · payer
status*stringThe coverage status: active, inactive or unknown (not_answered only on a read of a check the payer did not answer).
one of: active · inactive · unknown · not_answered
checked_at*stringWhen the payer answered (ISO 8601).
verified*booleanTrue only when every truth check passed for this exact answer: every payer row is one line, every value is in its line unchanged, no number in a sentence that the payer did not send. False: the organized answer is withheld (no organized block is present) and links.payer_answer still answers.
unverified_reasonstringOnly with verified: false: why the organized answer is withheld.
office*objectThe office the check was made for: id and name.
payer*objectid and name are Claim House's directory entry. id_as_returned and name_as_returned are the payer's own words. Neither replaces the other.
patientobjectThe person being seen, exactly as the payer returned them (dates as YYYY-MM-DD when the payer sent a clean date). Fields the payer did not send are absent.
subscriberobjectThe policy holder as returned, when the payer returned one apart from the patient.
dependentsarrayOther people the payer listed.
as_requestedobjectWhat you sent (subscriber, patient, relationship, visit_date), with differences (fields the payer returned with another value) and not_returned (fields or a whole person you sent that the payer did not return). Never substituted for the payer's people.
planobjectPlan fields as the payer sent them (name, type, group_number, group_name, ...), coverage (status and each date under its own name: start, end, termination; plus the payer's active coverage rows as lines) and plan notes.
totalsobjectdeductibles, maximums and out_of_pocket: one line per payer row that names no procedure code, in payer order. A remaining amount is its own line with period: remaining.
by_servicearrayLines grouped by the payer's service type (service, label, lines) for rows that name no procedure code; service: not_stated when the payer named none.
by_procedurearrayEvery row that names a CDT code, grouped by code (code, code_as_sent, lines, history). Codes only, never procedure names. A row naming several codes is listed under each, with shared_with, and counted once.
historyarrayEvery service date the payer sent, newest first: code, type as sent, date, ref. A copy sits under each code.
not_coveredarrayThe payer's not covered rows, one line each.
notesarrayPayer notes and disclaimers that belong to no other line.
rejectionobjectThe payer's refusal details, when it sent them, with its rows as lines.
otherobjectAnything else the payer sent at the top level, verbatim.
missingarraySections an office usually expects that the payer did not send (deductible, maximums, coinsurance, limitations, not_covered, waiting_period).
not_readarrayFields kept verbatim under a line's other because Claim House does not organize them. Nothing is dropped.
labelsobjectPlain words for the payer tokens in this answer, by kind (network, level, period, service, ...).
counts*objectpayer_rows and lines (always equal), procedures, notes, history. A summary carries complete_lines and shown_lines instead.
excludedarrayPaths kept out on purpose (our own office identity echoed back, the network's computed summaries, social security numbers); their values are never shown.
links*objectcomplete, summary, lines, payer_answer and pdf: where each view of this answer is read.
billing*objectWhether this check is charged and why: charged, state, reason, label, reason_label, and unit_price_micros on a charged check. Fields that do not apply are absent (charged is absent while the unit is under review, state: PENDING).
request*objectWhat this call did.
referencestringYour reference for this request, when you sent one.
idempotency_key*stringThe key the check ran under: yours, or the derived chk_ key.
idempotency_key_source*stringheader (yours), derived, or fresh (derived and made unique because you asked the payer again).
one of: header · derived · fresh
replayed*booleanTrue when this replays the recorded result of the same request.
reused*booleanTrue when a saved answer was reused (free); id and checked_at are then the original check's.
viewstringThe view you asked for, when you sent one.
correctionsarrayEvery normalization applied to the request (field, from, to); absent when none. A person's value is never repeated: a date names its formats.
payer_resolutionobjectHow the payer was matched: input, matched_payer_id, matched_name, method (EXACT, ALIAS, CONFIRMED, LEARNED), confidence.
idempotent_replay*booleanThe same as request.replayed (the Idempotent-Replayed: true header says it too).
pdfobjectWith include=pdf only: status ready with artifact_id and filename, or unavailable with error. The check stands either way.

Responses

200OK: the complete answer (flat request, executed test check, synthetic patient and ids)
{
  "livemode": false,
  "request_id": "evt_9j3v95tbkd77k7cz2dk5",
  "id": "elg_9aqbap922506q92gx9ge",
  "contract": "eligibility.v3",
  "view": "complete",
  "status": "active",
  "checked_at": "2026-09-07T15:00:00+00:00",
  "verified": true,
  "office": {
    "id": "fac_sandboxbatchsandbx",
    "name": "fac_sandboxbatchsandbx"
  },
  "payer": {
    "id": "94276",
    "name": "Delta Dental",
    "id_as_returned": "94276",
    "name_as_returned": "Delta Dental"
  },
  "patient": {
    "date_of_birth": "1980-01-01",
    "first_name": "TEST",
    "last_name": "PATIENT",
    "member_id": "CH-ACTIVE-FULL",
    "relationship": "self"
  },
  "as_requested": {
    "subscriber": {
      "first_name": "Test",
      "last_name": "Patient",
      "date_of_birth": "1980-01-01",
      "member_id": "CH-ACTIVE-FULL"
    },
    "relationship": "self",
    "visit_date": "2026-09-07",
    "differences": [],
    "not_returned": [
      "subscriber"
    ]
  },
  "plan": {
    "group_number": "TESTGRP1",
    "insurance_type": "ppo",
    "name": "Delta Dental PPO",
    "coverage": {
      "start": "2026-01-01",
      "status": "active",
      "termination": "2026-12-31",
      "lines": [
        {
          "kind": "active_coverage",
          "network": "in_network",
          "insurance_type": "group_policy",
          "text": "In network, group policy: active coverage",
          "ref": "active_coverage[0]"
        }
      ]
    }
  },
  "totals": {
    "deductibles": [
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "individual",
        "period": "calendar",
        "service": "dental_care",
        "amount": "50.00",
        "text": "Dental care (general), in network, individual, calendar year: deductible $50.00",
        "ref": "deductible[0]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "individual",
        "period": "remaining",
        "service": "dental_care",
        "amount": "25.00",
        "text": "Dental care (general), in network, individual, remaining: deductible $25.00",
        "ref": "deductible[1]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "family",
        "period": "calendar",
        "service": "dental_care",
        "amount": "150.00",
        "text": "Dental care (general), in network, family, calendar year: deductible $150.00",
        "ref": "deductible[2]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "family",
        "period": "remaining",
        "service": "dental_care",
        "amount": "150.00",
        "text": "Dental care (general), in network, family, remaining: deductible $150.00",
        "ref": "deductible[3]"
      }
    ],
    "maximums": [
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "calendar",
        "service": "dental_care",
        "amount": "1500.00",
        "text": "Dental care (general), in network, individual, calendar year: maximum $1500.00",
        "ref": "maximums[0]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "remaining",
        "service": "dental_care",
        "amount": "1200.00",
        "text": "Dental care (general), in network, individual, remaining: maximum $1200.00",
        "ref": "maximums[1]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "lifetime",
        "service": "orthodontics",
        "amount": "1000.00",
        "text": "Orthodontics, in network, individual, lifetime: maximum $1000.00",
        "ref": "maximums[2]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "lifetime_remaining",
        "service": "orthodontics",
        "amount": "1000.00",
        "text": "Orthodontics, in network, individual, lifetime remaining: maximum $1000.00",
        "ref": "maximums[3]"
      }
    ]
  },
  "by_service": [
    {
      "service": "preventive",
      "label": "Preventive care",
      "lines": [
        {
          "kind": "coinsurance",
          "network": "in_network",
          "percent": 100,
          "text": "Preventive care, in network: coinsurance 100%",
          "ref": "coinsurance[0]"
        }
      ]
    },
    {
      "service": "restorative",
      "label": "Restorative (fillings)",
      "lines": [
        {
          "kind": "coinsurance",
          "network": "in_network",
          "percent": 80,
          "text": "Restorative (fillings), in network: coinsurance 80%",
          "ref": "coinsurance[1]"
        }
      ]
    },
    {
      "service": "dental_crowns",
      "label": "Crowns",
      "lines": [
        {
          "kind": "coinsurance",
          "network": "in_network",
          "percent": 50,
          "text": "Crowns, in network: coinsurance 50%",
          "ref": "coinsurance[2]"
        }
      ]
    }
  ],
  "by_procedure": [
    {
      "code": "D0274",
      "code_as_sent": "AD:D0274",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 visits in 12 month",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "month",
              "time_period_value": "12"
            }
          ],
          "text": "D0274, all networks, individual: limitation 1 visits in 12 month (frequency 1 visits per 12 months)",
          "ref": "limitations[2]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 units remaining",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "text": "D0274, all networks, individual: limitation 1 units remaining (frequency 1 units, time period remaining)",
          "ref": "limitations[3]"
        }
      ]
    },
    {
      "code": "D1110",
      "code_as_sent": "AD:D1110",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "2 visits in 1 calendar",
          "frequency": [
            {
              "quantity": "2",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "calendar",
              "time_period_value": "1"
            }
          ],
          "text": "D1110, all networks, individual: limitation 2 visits in 1 calendar (frequency 2 visits per calendar year)",
          "ref": "limitations[0]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 units remaining",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "text": "D1110, all networks, individual: limitation 1 units remaining (frequency 1 units, time period remaining)",
          "ref": "limitations[1]"
        }
      ]
    }
  ],
  "missing": [
    "not_covered",
    "waiting_period"
  ],
  "not_read": [],
  "labels": {
    "network": {
      "applies_all": "All networks",
      "in_network": "In network"
    },
    "level": {
      "family": "Family",
      "individual": "Individual"
    },
    "period": {
      "calendar": "Calendar year",
      "lifetime": "Lifetime",
      "lifetime_remaining": "Lifetime remaining",
      "remaining": "Remaining"
    },
    "service": {
      "dental_care": "Dental care (general)",
      "dental_crowns": "Crowns",
      "orthodontics": "Orthodontics",
      "preventive": "Preventive care",
      "restorative": "Restorative (fillings)"
    },
    "insurance_type": {
      "group_policy": "Group policy",
      "ppo": "PPO"
    }
  },
  "counts": {
    "payer_rows": 16,
    "lines": 16,
    "procedures": 2,
    "notes": 0,
    "history": 0
  },
  "links": {
    "complete": "/v1/eligibility/elg_9aqbap922506q92gx9ge/answer?contract=v3",
    "summary": "/v1/eligibility/elg_9aqbap922506q92gx9ge/answer?contract=v3&view=summary",
    "lines": "/v1/eligibility/elg_9aqbap922506q92gx9ge/answer?contract=v3&view=lines",
    "payer_answer": "/v1/eligibility/elg_9aqbap922506q92gx9ge/answer?view=payer",
    "pdf": "/v1/eligibility/elg_9aqbap922506q92gx9ge/pdf"
  },
  "billing": {
    "charged": false,
    "state": "NOT_BILLABLE",
    "reason": "test_mode",
    "label": "Test mode",
    "reason_label": "Test mode checks never reach a payer and are never charged"
  },
  "request": {
    "idempotency_key": "first-check-ab12cd",
    "idempotency_key_source": "header",
    "replayed": false,
    "reused": false,
    "corrections": [
      {
        "field": "patient.date_of_birth",
        "from": "YYYYMMDD",
        "to": "YYYY-MM-DD"
      }
    ],
    "payer_resolution": {
      "input": {
        "insurance": "94276"
      },
      "matched_payer_id": "94276",
      "matched_name": "Delta Dental",
      "method": "EXACT",
      "confidence": "HIGH"
    }
  },
  "idempotent_replay": false
}
200A dependent with procedure codes, view summary (excerpt)
{
  "id": "elg_t95xef05j13r99z1g248",
  "contract": "eligibility.v3",
  "view": "summary",
  "status": "active",
  "verified": true,
  "as_requested": {
    "subscriber": {
      "first_name": "Avery",
      "last_name": "Molar",
      "date_of_birth": "1970-01-10",
      "member_id": "CH-ACTIVE-FULL"
    },
    "patient": {
      "first_name": "Riley",
      "last_name": "Molar",
      "date_of_birth": "2015-06-02"
    },
    "relationship": "child",
    "visit_date": "2026-09-07",
    "differences": [],
    "not_returned": [
      "subscriber"
    ]
  },
  "counts": {
    "complete_lines": 16,
    "shown_lines": 16
  },
  "summary": {
    "blocks": [
      "plan",
      "totals",
      "deductibles",
      "maximums",
      "out_of_pocket",
      "coinsurance",
      "procedures",
      "frequencies",
      "history",
      "not_covered",
      "missing_tooth",
      "waiting_periods"
    ],
    "procedures": [
      "D0120",
      "D0140",
      "D0150",
      "D0210",
      "D0220",
      "D0272",
      "D0274",
      "D0330",
      "D1110",
      "D1120",
      "D1206",
      "D1208",
      "D4341",
      "D4342",
      "D4910",
      "D2740",
      "D2750",
      "D7140",
      "D7210"
    ],
    "source": {
      "blocks": "default",
      "procedures": "default"
    }
  },
  "request": {
    "idempotency_key": "chk_82ffd3fe3d2419dbe08ccc204a9d9cea748f791d",
    "idempotency_key_source": "derived",
    "replayed": false,
    "reused": false,
    "view": "summary",
    "corrections": [
      {
        "field": "visit_date",
        "from": "YYYYMMDD",
        "to": "YYYY-MM-DD"
      },
      {
        "field": "procedures[1]",
        "from": "d1110",
        "to": "D1110"
      },
      {
        "field": "office",
        "from": "SBX",
        "to": "fac_sandboxbatchsandbx"
      }
    ],
    "payer_resolution": {
      "input": {
        "insurance": "94276"
      },
      "matched_payer_id": "94276",
      "matched_name": "Delta Dental",
      "method": "EXACT",
      "confidence": "HIGH"
    }
  }
}
200No key sent: the derived key, sent again the same day (excerpt)
{
  "id": "elg_ztnbv2mkpn10d0qxy1yj",
  "request": {
    "reference": "appt-1001",
    "idempotency_key": "chk_0e28af6f90203cb515b58a55489203d22155c836",
    "idempotency_key_source": "derived",
    "replayed": true,
    "reused": false,
    "corrections": [
      {
        "field": "patient.date_of_birth",
        "from": "MM/DD/YYYY",
        "to": "YYYY-MM-DD"
      },
      {
        "field": "office",
        "from": "not sent",
        "to": "fac_sandboxbatchsandbx"
      }
    ],
    "payer_resolution": {
      "input": {
        "insurance": "94276"
      },
      "matched_payer_id": "94276",
      "matched_name": "Delta Dental",
      "method": "EXACT",
      "confidence": "HIGH"
    }
  },
  "idempotent_replay": true
}
200The organized answer withheld: verified false (forced truth defect, executed)
{
  "livemode": false,
  "request_id": "evt_bc5zc5eg0544h0wjyjwy",
  "id": "elg_m7zmjt02h17253dsz2wn",
  "contract": "eligibility.v3",
  "view": "complete",
  "status": "active",
  "checked_at": "2026-09-07T15:00:00+00:00",
  "verified": false,
  "unverified_reason": "The organized answer did not match the payer's answer, so it is withheld. The payer's answer as received is at links.payer_answer.",
  "office": {
    "id": "fac_sandboxbatchsandbx"
  },
  "payer": {
    "id": "94276"
  },
  "links": {
    "payer_answer": "/v1/eligibility/elg_m7zmjt02h17253dsz2wn/answer?view=payer"
  },
  "billing": {
    "charged": false,
    "state": "NOT_BILLABLE",
    "reason": "test_mode",
    "label": "Test mode",
    "reason_label": "Test mode checks never reach a payer and are never charged"
  },
  "request": {
    "reference": "appt-1004",
    "idempotency_key": "chk_1fb73568bdf4bb7a66ec2174ad8d253181108d37",
    "idempotency_key_source": "fresh",
    "replayed": false,
    "reused": false,
    "corrections": [
      {
        "field": "patient.date_of_birth",
        "from": "MM/DD/YYYY",
        "to": "YYYY-MM-DD"
      },
      {
        "field": "office",
        "from": "SBX",
        "to": "fac_sandboxbatchsandbx"
      }
    ],
    "payer_resolution": {
      "input": {
        "insurance": "94276"
      },
      "matched_payer_id": "94276",
      "matched_name": "Delta Dental",
      "method": "EXACT",
      "confidence": "HIGH"
    }
  },
  "idempotent_replay": false
}
200Pinned to 2026-10-01: the earlier check response (camelCase body, executed)
{
  "livemode": false,
  "request_id": "evt_yd9fd0vhs56r37v3wvtt",
  "idempotent_replay": false,
  "active_coverage": [
    {
      "amount": null,
      "as_sent": {
        "insurance_type": "group_policy",
        "network": "in_network"
      },
      "category": null,
      "coverage_level": null,
      "description": null,
      "end_date": null,
      "insurance_type": "group_policy",
      "network": "in_network",
      "percent": null,
      "plan_period": null,
      "procedure_code": null,
      "remaining": null,
      "section": "active_coverage",
      "service_type": null,
      "start_date": null,
      "used": null
    }
  ],
  "cache": {
    "state": "hit",
    "age_seconds": 0
  },
  "coinsurance": [
    {
      "amount": null,
      "as_sent": {
        "network": "in_network",
        "percent": "100",
        "service_type": "preventive"
      },
      "category": null,
      "coverage_level": null,
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": "100",
      "plan_period": null,
      "procedure_code": null,
      "remaining": null,
      "section": "coinsurance",
      "service_type": "preventive",
      "start_date": null,
      "used": null
    },
    {
      "amount": null,
      "as_sent": {
        "network": "in_network",
        "percent": "80",
        "service_type": "restorative"
      },
      "category": null,
      "coverage_level": null,
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": "80",
      "plan_period": null,
      "procedure_code": null,
      "remaining": null,
      "section": "coinsurance",
      "service_type": "restorative",
      "start_date": null,
      "used": null
    },
    {
      "amount": null,
      "as_sent": {
        "network": "in_network",
        "percent": "50",
        "service_type": "dental_crowns"
      },
      "category": null,
      "coverage_level": null,
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": "50",
      "plan_period": null,
      "procedure_code": null,
      "remaining": null,
      "section": "coinsurance",
      "service_type": "dental_crowns",
      "start_date": null,
      "used": null
    }
  ],
  "copayments": [],
  "coverage": {
    "effective_date": "2026-01-01",
    "status_reason": null,
    "termination_date": "2026-12-31"
  },
  "deductibles": [
    {
      "amount": "50.00",
      "as_sent": {
        "amount": "50.00",
        "coverage_level": "individual",
        "network": "in_network",
        "plan_period": "calendar",
        "service_type": "dental_care"
      },
      "category": null,
      "coverage_level": "individual",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "calendar",
      "procedure_code": null,
      "remaining": null,
      "section": "deductible",
      "service_type": "dental_care",
      "start_date": null,
      "used": null
    },
    {
      "amount": "25.00",
      "as_sent": {
        "amount": "25.00",
        "coverage_level": "individual",
        "network": "in_network",
        "plan_period": "remaining",
        "service_type": "dental_care"
      },
      "category": null,
      "coverage_level": "individual",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "remaining",
      "procedure_code": null,
      "remaining": null,
      "section": "deductible",
      "service_type": "dental_care",
      "start_date": null,
      "used": null
    },
    {
      "amount": "150.00",
      "as_sent": {
        "amount": "150.00",
        "coverage_level": "family",
        "network": "in_network",
        "plan_period": "calendar",
        "service_type": "dental_care"
      },
      "category": null,
      "coverage_level": "family",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "calendar",
      "procedure_code": null,
      "remaining": null,
      "section": "deductible",
      "service_type": "dental_care",
      "start_date": null,
      "used": null
    },
    {
      "amount": "150.00",
      "as_sent": {
        "amount": "150.00",
        "coverage_level": "family",
        "network": "in_network",
        "plan_period": "remaining",
        "service_type": "dental_care"
      },
      "category": null,
      "coverage_level": "family",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "remaining",
      "procedure_code": null,
      "remaining": null,
      "section": "deductible",
      "service_type": "dental_care",
      "start_date": null,
      "used": null
    }
  ],
  "disclaimers": [],
  "downgrade_rules": [],
  "eligibility_id": "elg_k3dkr9s0h95s90z0zc4g",
  "facility_id": "fac_sandboxbatchsandbx",
  "frequency_limitations": [
    {
      "as_sent": {
        "coverage_level": "individual",
        "health_service_descriptions": [
          {
            "quantity": "2",
            "quantity_qualifier": "visits",
            "time_period_qualifier": "calendar",
            "time_period_value": "1"
          }
        ],
        "limitation": "2 visits in 1 calendar",
        "network": "applies_all",
        "procedure_code": "AD:D1110"
      },
      "category": null,
      "description": null,
      "end_date": null,
      "network": "applies_all",
      "plan_period": null,
      "procedure_code": "D1110",
      "quantity": null,
      "quantity_remaining": null,
      "quantity_used": null,
      "service_type": null,
      "start_date": null
    },
    {
      "as_sent": {
        "coverage_level": "individual",
        "health_service_descriptions": [
          {
            "quantity": "1",
            "quantity_qualifier": "units",
            "time_period_qualifier": "remaining"
          }
        ],
        "limitation": "1 units remaining",
        "network": "applies_all",
        "procedure_code": "AD:D1110"
      },
      "category": null,
      "description": null,
      "end_date": null,
      "network": "applies_all",
      "plan_period": null,
      "procedure_code": "D1110",
      "quantity": null,
      "quantity_remaining": null,
      "quantity_used": null,
      "service_type": null,
      "start_date": null
    },
    {
      "as_sent": {
        "coverage_level": "individual",
        "health_service_descriptions": [
          {
            "quantity": "1",
            "quantity_qualifier": "visits",
            "time_period_qualifier": "month",
            "time_period_value": "12"
          }
        ],
        "limitation": "1 visits in 12 month",
        "network": "applies_all",
        "procedure_code": "AD:D0274"
      },
      "category": null,
      "description": null,
      "end_date": null,
      "network": "applies_all",
      "plan_period": null,
      "procedure_code": "D0274",
      "quantity": null,
      "quantity_remaining": null,
      "quantity_used": null,
      "service_type": null,
      "start_date": null
    },
    {
      "as_sent": {
        "coverage_level": "individual",
        "health_service_descriptions": [
          {
            "quantity": "1",
            "quantity_qualifier": "units",
            "time_period_qualifier": "remaining"
          }
        ],
        "limitation": "1 units remaining",
        "network": "applies_all",
        "procedure_code": "AD:D0274"
      },
      "category": null,
      "description": null,
      "end_date": null,
      "network": "applies_all",
      "plan_period": null,
      "procedure_code": "D0274",
      "quantity": null,
      "quantity_remaining": null,
      "quantity_used": null,
      "service_type": null,
      "start_date": null
    }
  ],
  "maximums": [
    {
      "amount": "1500.00",
      "as_sent": {
        "amount": "1500.00",
        "coverage_level": "individual",
        "network": "in_network",
        "plan_period": "calendar",
        "service_type": "dental_care"
      },
      "category": null,
      "coverage_level": "individual",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "calendar",
      "procedure_code": null,
      "remaining": null,
      "section": "maximums",
      "service_type": "dental_care",
      "start_date": null,
      "used": null
    },
    {
      "amount": "1200.00",
      "as_sent": {
        "amount": "1200.00",
        "coverage_level": "individual",
        "network": "in_network",
        "plan_period": "remaining",
        "service_type": "dental_care"
      },
      "category": null,
      "coverage_level": "individual",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "remaining",
      "procedure_code": null,
      "remaining": null,
      "section": "maximums",
      "service_type": "dental_care",
      "start_date": null,
      "used": null
    },
    {
      "amount": "1000.00",
      "as_sent": {
        "amount": "1000.00",
        "coverage_level": "individual",
        "network": "in_network",
        "plan_period": "lifetime",
        "service_type": "orthodontics"
      },
      "category": null,
      "coverage_level": "individual",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "lifetime",
      "procedure_code": null,
      "remaining": null,
      "section": "maximums",
      "service_type": "orthodontics",
      "start_date": null,
      "used": null
    },
    {
      "amount": "1000.00",
      "as_sent": {
        "amount": "1000.00",
        "coverage_level": "individual",
        "network": "in_network",
        "plan_period": "lifetime_remaining",
        "service_type": "orthodontics"
      },
      "category": null,
      "coverage_level": "individual",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "lifetime_remaining",
      "procedure_code": null,
      "remaining": null,
      "section": "maximums",
      "service_type": "orthodontics",
      "start_date": null,
      "used": null
    }
  ],
  "missing_tooth_clause": null,
  "mode": "standard",
  "network_status": null,
  "not_covered": [],
  "not_extracted": [
    "waiting_periods",
    "missing_tooth_clause",
    "downgrade_rules",
    "tooth_history"
  ],
  "not_returned": [],
  "out_of_pocket": [],
  "payer_id": "94276",
  "plan": {
    "group_number": "TESTGRP1",
    "name": "Delta Dental PPO",
    "type": null
  },
  "procedure_codes": [
    "D1120"
  ],
  "relationship": "child",
  "relationship_source": "request",
  "retrieved_at": "2026-09-07T15:00:00+00:00",
  "service_date": "2026-09-07",
  "service_date_source": "request",
  "source": {
    "transaction_id": "test-smp_magic_active_full",
    "vendor": "claimhouse"
  },
  "source_notes": [],
  "status": "ACTIVE",
  "tenant_reference": "visit-0001",
  "tooth_history": [],
  "vendor_latency_ms": 320,
  "waiting_periods": [],
  "warnings": [
    "NETWORK_SUMMARY_DEPRECATED",
    "SUMMARY_FIELDS_ARE_NOT_COMPLETE_PAYER_INFORMATION"
  ],
  "operation_id": "elg_hf3bf8350143f207zw1s",
  "request_reference": "visit-0001",
  "error_class": null,
  "procedure_benefits": [],
  "network_tiers": [],
  "coordination_of_benefits": null,
  "eligibility_flags": [],
  "payer_notes": [],
  "artifact_id": null,
  "pdf_filename": null,
  "billing": {
    "charged": false,
    "state": "NOT_BILLABLE",
    "reason": "test_mode",
    "label": "Test mode",
    "reason_label": "Test mode checks never reach a payer and are never charged",
    "unit_price_micros": null
  },
  "reused": true,
  "payer_resolution": {
    "input": {
      "payer_id": "94276"
    },
    "matched_payer_id": "94276",
    "matched_name": "Delta Dental",
    "method": "EXACT",
    "confidence": "HIGH"
  },
  "request_corrections": [
    {
      "field": "dependents[0].relationshipToSubscriberCode",
      "from": "19",
      "to": "child"
    },
    {
      "field": "facilityId",
      "from": "SBX",
      "to": "fac_sandboxbatchsandbx"
    }
  ]
}
422No office, and the key reaches two offices
{
  "livemode": false,
  "error": "OFFICE_REQUIRED",
  "message": "this key reaches more than one office; send office (its id, code or name)",
  "errors": [
    {
      "field": "office",
      "candidates": [
        {
          "facility_id": "fac_sandboxbatchsandbx",
          "name": "SBX",
          "code": "SBX"
        },
        {
          "facility_id": "fac_sandboxsecondoffic",
          "name": "SB2",
          "code": "SB2"
        }
      ]
    }
  ],
  "request_id": "evt_8wennzksn179331690h0",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-office-required",
  "user_message": "Choose the office for this check."
}
422A body that mixes the flat request with another shape
{
  "livemode": false,
  "error": "REQUEST_SHAPES_MIXED",
  "message": "this body mixes the flat request with another request shape; send one shape",
  "errors": [
    {
      "flat_fields": [
        "insurance",
        "member_id",
        "reference"
      ],
      "other_fields": [
        "patient.dateOfBirth",
        "patient.firstName",
        "patient.lastName"
      ]
    }
  ],
  "request_id": "evt_7tcgper79920s3hnxsag",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-request-shapes-mixed",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}
400camelCase body without an Idempotency-Key
{
  "livemode": false,
  "error": "IDEMPOTENCY_KEY_REQUIRED",
  "message": "the Idempotency-Key header is required",
  "errors": [],
  "request_id": "evt_mqqr3nz3ax67k5v0s88t",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-idempotency-key-required",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}
422Idempotency key reused with other content
{
  "livemode": false,
  "error": "IDEMPOTENCY_KEY_REUSED",
  "message": "Idempotency-Key belongs to different content or context",
  "errors": [],
  "request_id": "evt_21tm8abqbd0gv5yfwqde",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-idempotency-key-reused",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}
422A policy holder without a dependent relationship
{
  "livemode": false,
  "error": "INVALID_ELIGIBILITY_REQUEST",
  "message": "subscriber is for a patient who is not the policy holder: send relationship (spouse, child or other) with it, or leave subscriber out",
  "errors": [
    {
      "findings": [
        "PATIENT_RELATIONSHIP_REQUIRED"
      ],
      "fields": [
        "relationship",
        "subscriber"
      ]
    }
  ],
  "request_id": "evt_3qpg62h0tn53q577kyt1",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-invalid-eligibility-request",
  "user_message": "Some patient or insurance details need to be corrected before checking."
}
403Office code matches no office you can use
{
  "livemode": false,
  "error": "FACILITY_NOT_GRANTED",
  "message": "facility not granted",
  "errors": [
    {
      "facility_id": "ZZZ"
    }
  ],
  "request_id": "evt_pt5h9c3md514q0dg5gf4",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-facility-not-granted",
  "user_message": "Your account does not have access to this office."
}
422tradingPartnerServiceId and payer.id disagree (camelCase body)
{
  "livemode": false,
  "error": "INVALID_ELIGIBILITY_REQUEST",
  "message": "tradingPartnerServiceId and payer.id name different payers; send one, or the same id in both",
  "errors": [
    {
      "findings": [
        "PAYER_INPUT_CONFLICT"
      ],
      "fields": [
        "tradingPartnerServiceId",
        "payer.id"
      ]
    }
  ],
  "request_id": "evt_mbk65mj0sx4wf8bggveg",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-invalid-eligibility-request",
  "user_message": "Some patient or insurance details need to be corrected before checking."
}
502Vendor did not answer (test scenario CH-AAA-42)
{
  "livemode": false,
  "error": "VENDOR_ERROR",
  "message": "the eligibility vendor did not answer this check",
  "errors": [
    {
      "eligibility_id": "elg_8dz3g4gsy54rz54v89eg",
      "error_class": "VENDOR_UNAVAILABLE",
      "vendor_status": 502,
      "mode": "standard",
      "billing": {
        "charged": false,
        "state": "NOT_BILLABLE",
        "reason": "test_mode",
        "label": "Test mode",
        "reason_label": "Test mode checks never reach a payer and are never charged",
        "unit_price_micros": null
      }
    }
  ],
  "request_id": "evt_g2pxew89th18sbedn7rb",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "NEW_CHECK_LATER",
  "doc_url": "https://docs.claimhouse.ai/#error-vendor-error",
  "user_message": "We could not get an answer from the payer this time. Check again later."
}
422Payer rejected the check (test scenario CH-AAA-72)
{
  "livemode": false,
  "error": "PAYER_REJECTED",
  "message": "The payer says the member ID is missing or not valid.",
  "errors": [
    {
      "eligibility_id": "elg_tr74ypvrd16vh7n8qnet",
      "error_class": "VENDOR_REJECTED",
      "vendor_status": 400,
      "mode": "standard",
      "rejection": {
        "kind": "FIX_AND_RESEND",
        "retry_later": false,
        "summary": "The payer says the member ID is missing or not valid.",
        "reasons": [
          {
            "code": "MEMBER_ID_INVALID",
            "about": "subscriber",
            "message": "The payer says the member ID is missing or not valid.",
            "fix": "Enter the member ID exactly as it appears on the insurance card, including any letters and leading zeros.",
            "field": "subscriber.memberId",
            "next_step": "FIX_REQUEST"
          }
        ]
      },
      "billing": {
        "charged": false,
        "state": "NOT_BILLABLE",
        "reason": "test_mode",
        "label": "Test mode",
        "reason_label": "Test mode checks never reach a payer and are never charged",
        "unit_price_micros": null
      }
    }
  ],
  "request_id": "evt_5cjgcar7gx62kbb8grha",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-payer-rejected",
  "user_message": "The payer says the member ID is missing or not valid."
}
502Payer not answering (test scenario CH-AAA-42-ONCE)
{
  "livemode": false,
  "error": "PAYER_UNAVAILABLE",
  "message": "The payer is not answering right now. Try again in a few minutes; nothing needs to change.",
  "errors": [
    {
      "eligibility_id": "elg_3frxp0edtn7a5e713c5q",
      "error_class": "VENDOR_REJECTED",
      "vendor_status": 400,
      "mode": "standard",
      "rejection": {
        "kind": "PAYER_UNAVAILABLE",
        "retry_later": true,
        "summary": "The payer is not answering right now. Try again in a few minutes; nothing needs to change.",
        "reasons": [
          {
            "code": "PAYER_NOT_ANSWERING",
            "about": "payer",
            "message": "The payer is not answering right now.",
            "fix": "Try again in a few minutes; nothing needs to change.",
            "field": null,
            "next_step": "NEW_CHECK_LATER"
          }
        ]
      },
      "billing": {
        "charged": false,
        "state": "NOT_BILLABLE",
        "reason": "test_mode",
        "label": "Test mode",
        "reason_label": "Test mode checks never reach a payer and are never charged",
        "unit_price_micros": null
      }
    }
  ],
  "request_id": "evt_1qy5et9mv57wdeg8aeka",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "NEW_CHECK_LATER",
  "doc_url": "https://docs.claimhouse.ai/#error-payer-unavailable",
  "user_message": "The payer is not answering right now. Try again in a few minutes; nothing needs to change."
}

Errors

StatusCodeWhen
400API_VERSION_UNKNOWNClaim-House-Version names a version this API does not serve
400IDEMPOTENCY_KEY_REQUIREDA camelCase or snake_case body without the Idempotency-Key header (the flat request may leave it out)
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
402BILLING_REQUIREDLive mode: no card on file and not an internal account (errors[0].action_url is /settings/billing)
403BILLING_IDENTITY_MISMATCHprovider.npi differs from the office billing NPI
403FACILITY_NOT_GRANTEDNo office you can use matches the id, code or name, or it is not granted (never 404)
403MODE_MISMATCHA test key at a live office, or a live key at a test office
403ORG_SUSPENDEDLive mode: your organization or its account is suspended
403PERMISSION_DENIEDKey lacks the route's permission
409CAPABILITY_NOT_READYLive mode: the office is not enabled for eligibility yet; errors[0].state names its state
409ELIGIBILITY_OPERATION_PENDINGThe same check is still running; nothing new was sent
409OFFICE_NOT_LIVELive mode: the office is not live yet (take it live with POST /v1/facilities/{facility_id}/go-live)
409PAYER_CHOICE_REQUIREDThe insurance sent matches more than one payer; pick one of the candidates and send its id
422IDEMPOTENCY_KEY_REUSEDKey used before with different content
422INVALID_ELIGIBILITY_REQUESTRequest rule findings in errors[0].findings, for example a missing dependent relationship, PAYER_INPUT_CONFLICT or MAX_AGE_CONFLICT
422INVALID_REQUESTPath, query or body fails the schema, including no payer at all (missing at tradingPartnerServiceId or payer_id)
422NOT_A_TEST_PATIENTTest mode: the request names no sample patient
422OFFICE_AMBIGUOUSThe office code or name matches more than one office you can use; errors[0].candidates lists facility_id, name and code
422OFFICE_REQUIREDA flat request without office from a key that reaches more than one office (or none) that takes checks in its mode; errors[0].candidates lists them
422PAYER_NOT_SUPPORTED_FOR_ELIGIBILITYNo supported eligibility payer matches the payer you sent
422PAYER_REJECTEDThe payer turned the check down for a reason the office can fix (member not found, date of birth does not match, member ID missing). errors[0].rejection says what and where
422REQUEST_SHAPES_MIXEDA body that mixes flat fields with another shape's person fields; errors[0].flat_fields and other_fields name them
422TEST_SCENARIO_UNKNOWNTest mode: X-Test-Scenario names no test scenario
429DAILY_LIMIT_REACHEDLive: your organization reached today's live check limit (2,000 checks that reached a payer, per UTC day). Nothing was sent or charged; Retry-After counts down to midnight UTC. Contact Claim House to raise it
429TEST_LIMIT_REACHEDTest mode: today's limit is used up (Retry-After until midnight UTC)
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
502PAYER_UNAVAILABLEThe payer is not answering right now. Nothing needs to change; check again later with a new key
502VENDOR_ERRORVendor did not answer usefully, or its answer could not be read
503CAPACITYNo payer slot freed within 2 seconds; nothing was sent or charged (Retry-After)
503ELIGIBILITY_UNAVAILABLEEligibility is not configured on this gateway
503ENHANCED_ELIGIBILITY_UNAVAILABLEYou asked for enhanced; detailed benefits are not available on your account yet. No payer is called and nothing is billed. Leave out mode, or send mode=standard.
503LIVE_LIMIT_UNAVAILABLELive admission quota cannot be verified; no new inquiry is started.
InfoVENDOR_ERROR detail: errors[0] carries eligibility_id, error_class (AUTH_FAILED, TIMEOUT, CONNECTION_ERROR, VENDOR_UNAVAILABLE, VENDOR_REJECTED, MALFORMED_RESPONSE, SECRET_UNAVAILABLE), vendor_status and mode. Nothing of the vendor body is returned. The failure is stored and can be read with GET /v1/eligibility/{eligibility_id}.
InfoPayer rejections: when the payer turns a check down, errors[0].rejection explains it in Claim House words, and message is its summary. rejection.kind is FIX_AND_RESEND (answered as 422 PAYER_REJECTED), PAYER_UNAVAILABLE (502 PAYER_UNAVAILABLE, retry_later: true) or REJECTED (502 VENDOR_ERROR). Each item in rejection.reasons has a Claim House code (for example MEMBER_NOT_FOUND, DATE_OF_BIRTH_MISMATCH, MEMBER_ID_INVALID, MEMBER_ID_DUPLICATE, NAME_INVALID, SERVICE_DATE_INVALID, SERVICE_DATE_IN_FUTURE, PROVIDER_ID_INVALID, PROVIDER_NOT_ON_FILE, PAYER_NOT_ANSWERING, or PAYER_REJECTED_OTHER for a reason not yet mapped), about (subscriber, patient, provider or payer), a plain message and fix, and field: the request path to change, such as subscriber.memberId or dependents[0].dateOfBirth, or null. No value from your request is echoed. The check is stored with the same rejection.
InfoRequest rule findings (422 INVALID_ELIGIBILITY_REQUEST): SUBSCRIBER_MEMBER_ID_REQUIRED, SUBSCRIBER_NAME_REQUIRED, SUBSCRIBER_DATE_OF_BIRTH_REQUIRED, DATE_OF_BIRTH_IN_FUTURE, PATIENT_NAME_REQUIRED, PATIENT_DATE_OF_BIRTH_REQUIRED, PATIENT_RELATIONSHIP_REQUIRED, PATIENT_RELATIONSHIP_INVALID, PATIENT_IS_SUBSCRIBER, TOO_MANY_PROCEDURE_CODES, PROCEDURE_CODE_INVALID, PAYER_INPUT_CONFLICT, MAX_AGE_CONFLICT. PATIENT_IS_SUBSCRIBER means the dependent's name, date of birth, member id and group all equal the subscriber's. Error codes and retries lists each with its message.
ImportantTwo requests for the same check at once: the second answers 409 ELIGIBILITY_OPERATION_PENDING and nothing new is sent. Wait a few seconds, then repeat the same request.
InfoWith include=pdf, the PDF is made after the check is recorded. If the PDF fails, including 409 PDF_NOT_VERIFIED, the check stands: repeat with the same Idempotency-Key to replay it without a payer call and try the PDF again.
InfoA test key never reaches a payer: it checks sample patients (GET /v1/test/samples) at a sandbox office, answered by the test mode simulator and never charged (billing.reason test_mode).
InfoCharged or not: every answer carries billing. A reused answer is cache_hit, never charged. A recorded failure carries the same object in errors[0].billing: a payer rejection about the member, provider or request is charged, and a payer that did not answer is free. The Pricing and what's charged guide lists every reason.
InfoLive quota counts original admitted operations by UTC day. Stored reads, cached answers and same-key replays do not consume another admission. Limit exhaustion is DAILY_LIMIT_REACHED. Do not resend an uncertain submission.
InfoResponse headers: Idempotent-Replayed: true when the response replays a recorded result for this Idempotency-Key, and Claim-House-Version on every response.
InfoA line is one payer row: kind (its payer section), the row's fields under plain names (network, level, period, service, amount, percent, limit, quantity, quantity_unit, age, frequency, service_dates, note, disclaimers, references, ...), text (one sentence holding every value on the line), ref (the payer section and row, the same index as view=payer) and other (fields not organized, verbatim). A field is present only when the payer sent its key. Money is a decimal string exactly as sent; percent is a number only when the payer sent a plain number.
InfoFail closed: an answer whose truth checks did not pass is never shown. The check still answers 200 (it was made and recorded) with verified: false, unverified_reason, links.payer_answer and no organized block. GET /v1/eligibility/{eligibility_id}/answer then answers 409 ANSWER_NOT_VERIFIED; the payer's answer as received (view=payer) still answers.
InfoOlder body shapes, still accepted under both versions. The camelCase shape (a body with facilityId or tradingPartnerServiceId): tradingPartnerServiceId (string): The payer: a Claim House payer id, the payer's primary id, your practice system's payer id or the insurance name. Required unless you send payer. The registry is tried first, then your organization's payer matches; when Claim House is not sure, the check answers 409 PAYER_CHOICE_REQUIRED with candidates. 1 to 80 letters, digits, ., -, _ or spaces; payer (object): Whatever you know about the payer; may replace or accompany tradingPartnerServiceId. A typed id is looked up first; otherwise the name is matched. tradingPartnerServiceId and payer.id naming different payers is 422 INVALID_ELIGIBILITY_REQUEST (PAYER_INPUT_CONFLICT). Unknown fields are refused [id (string): A payer id: Claim House, the payer's own, or an alias. 1 to 80 letters, digits, ., -, _ or spaces; name (string): The insurance name as your system has it, at most 120 characters; pms_carrier_id (string): Your practice system's own carrier or payer id, used when id is not sent. Same characters as id; group_number (string): Group number, at most 50 characters. Recorded with the check; never used to pick a payer today and never sent to the payer; employer_name (string): Employer name, at most 120 characters. Recorded with the check; never used to pick a payer today and never sent to the payer]; facilityId (string): The office the check is for: its fac_ id, its office code or its exact office name, 1 to 120 characters. Must be granted to your key. A code or name that matches more than one office you can use is 422 OFFICE_AMBIGUOUS with candidates; provider (object): Accepted for compatibility. The office's registered billing NPI and tax id are always what the payer receives [npi (string): 10 digit NPI with a valid check digit. If it differs from the office's billing NPI the check is refused with 403 BILLING_IDENTITY_MISMATCH; organizationName (string): At most 60 characters. Ignored; firstName (string): At most 35 characters. Ignored; lastName (string): At most 60 characters. Ignored; taxId (string): 9 digits. Ignored]; subscriber (object): The policy holder [memberId (string): Member id, at most 80 characters. Required by rule for the subscriber: a missing or null value is 422 with finding SUBSCRIBER_MEMBER_ID_REQUIRED; firstName (string): First name, 1 to 35 characters; lastName (string): Last name, 1 to 60 characters; dateOfBirth (string): Date of birth as YYYYMMDD, YYYY-MM-DD or MM/DD/YYYY (a date with slashes is month first). Must be a real date not after the service date; groupNumber (string): Group number, at most 50 characters]; dependents (array): At most one item: the patient when the patient is not the subscriber [memberId (string): Member id, at most 80 characters. Optional for a dependent; firstName (string): First name, 1 to 35 characters; lastName (string): Last name, 1 to 60 characters; dateOfBirth (string): Date of birth as YYYYMMDD, YYYY-MM-DD or MM/DD/YYYY (a date with slashes is month first). Must be a real date not after the service date; groupNumber (string): Group number, at most 50 characters; relationshipToSubscriberCode (string): The patient's relationship to the subscriber: spouse, child or other in any case, or the code (01 spouse, 19 child; any other code is read as other). Missing is 422 INVALID_ELIGIBILITY_REQUEST with PATIENT_RELATIONSHIP_REQUIRED]; encounter (object): Service detail [dateOfService (string): Service date as YYYYMMDD, YYYY-MM-DD or MM/DD/YYYY. Defaults to today (UTC). Recorded with the check; not sent to the payer. It does not establish the date the payer evaluated; procedureCode (string): One CDT code, D plus 4 digits. Merged with procedureCodes; procedureCodes (array): Array of strings. CDT codes for benefit detail. The merged list may hold at most 10 codes; serviceTypeCodes (array): Array of strings, at most 10. Accepted and ignored on the dental rail]; tenantReference (string): Your reference, at most 200 characters. Stored and returned; max_age_seconds (integer): Reuse a saved answer only when it is at most this old, 0 to 604800 (7 days). 0 always asks the payer. The same as the query parameter; different values in both are 422 (MAX_AGE_CONFLICT).
InfoThe snake_case shape (a body with facility_id or payer_id) is also still accepted: facility_id, payer_id, payer, subscriber (first_name, last_name, date_of_birth, member_id), patient (the same plus relationship), service_date, procedure_codes, tenant_reference, max_age_seconds. A body with either shape's marker is read exactly as before.
InfoPinned to 2026-10-01 (Claim-House-Version: 2026-10-01), the response is the check summary, unchanged: request_id (string): Request id; idempotent_replay (boolean): True when the recorded answer for this Idempotency-Key was replayed without a vendor call; eligibility_id (string): The check id, elg_.... A reused answer returns the original check's id; facility_id (string): The office the check was made for; payer_id (string): The payer id you sent; mode (string): The resolved mode. auto resolves to one of these before the call; relationship (string): The relationship requested on the check. It is not confirmation of the relationship in the payer response; service_date (date): Requested visit date, stored as request metadata. This field does not prove a date-specific payer query; procedure_codes (array): Array of strings. CDT codes sent on the original check. On a reused answer these are the original check's codes; tenant_reference (string): Your reference. Null when you did not send one; status (string): Coverage status. UNKNOWN when not returned or not recognized; reused (boolean): true when Claim House answered from a saved answer instead of asking the payer. The answer keeps its own eligibility_id and retrieved_at, and a reused answer is free (billing.reason cache_hit); payer_resolution (object): How your payer input was matched [input (object): The payer fields you sent that identify a payer (payer_id, or id, name and pms_carrier_id from payer). Never group_number or employer_name; matched_payer_id (string): The payer id the check was sent to; matched_name (string): The payer's name. Null when not known; method (string): EXACT: a Claim House payer id or the payer's own id. ALIAS: another id the payer is known by, or its exact name. CONFIRMED: someone in your organization, or Claim House, confirmed this match. LEARNED: an earlier answer from that payer for this same input proved it; confidence (string): HIGH, or MEDIUM for a match confirmed before the payer list last changed. A match Claim House is unsure of is never used: the check answers 409 PAYER_CHOICE_REQUIRED]; request_corrections (array): Every change Claim House made to your request before sending it. Empty when the request was sent as written. For names, dates of birth and member ids it names the kind of change, never the value [field (string): The request path, for example subscriber.dateOfBirth or facilityId; from (string): What arrived: a format (MM/DD/YYYY), text with spaces around it, or for the office, payer, relationship and procedure codes the value you sent; to (string): What was sent: a format (YYYYMMDD), trimmed, or the value used]; coverage (object): Coverage dates [effective_date (date): Coverage start. Null when not returned; termination_date (date): Coverage end. Null when not returned]; plan (object): Plan detail. Enhanced mode adds number, issuing_state and benefit_period [name (string): Plan name. Null when not returned; type (string): Plan type. Null when not returned; group_number (string): Group number. Null when not returned; number (string): Enhanced mode only. Plan number. Null when not returned; issuing_state (string): Enhanced mode only. Issuing state. Null when not returned; benefit_period (string): Enhanced mode only. Benefit period. Null when not returned]; network_status (string): Deprecated. Null in the attribution-only summary. Benefit-row network indicators do not establish provider participation; deductibles (array): Deductible benefit lines. Every item field may be null [section (string): Benefit section, for example deductibles. Null when not returned; network (string): Network, for example in_network. Null when not returned; category (string): Service category. Null when not returned; service_type (string): Service type. Null when not returned; coverage_level (string): Coverage level, for example individual or family. Null when not returned; plan_period (string): Plan period, for example calendar_year. Null when not returned; procedure_code (string): CDT code the line applies to. Null when not returned; insurance_type (string): Insurance type. Null when not returned; amount (string): Money amount as a decimal string. Null when not returned; remaining (string): Remaining amount as a decimal string. Null when not returned; used (string): Used amount as a decimal string. Null when not returned; percent (string): Percent as a decimal string. Null when not returned; description (string): Payer description. Null when not returned; start_date (date): Start date. Null when not returned; end_date (date): End date. Null when not returned]; maximums (array): Annual or lifetime maximum lines, same item shape as deductibles; coinsurance (array): Coinsurance lines, same item shape as deductibles; copayments (array): Copayment lines, same item shape as deductibles; not_covered (array): Not covered lines, same item shape as deductibles; frequency_limitations (array): Frequency convenience fields plus each original public row in as_sent. Preserve its scope, notes, quantity qualifiers and limitation structure [network (string): Network. Null when not returned; category (string): Service category. Null when not returned; service_type (string): Service type. Null when not returned; procedure_code (string): CDT code. Null when not returned; plan_period (string): Plan period. Null when not returned; quantity (string): Allowed quantity. Null when not returned; quantity_remaining (string): Quantity remaining. Null when not returned; quantity_used (string): Quantity used. Null when not returned; description (string): Payer description. Null when not returned; start_date (date): Start date. Null when not returned; end_date (date): End date. Null when not returned]; waiting_periods (array): Waiting periods [network (string): Network. Null when not returned; category (string): Service category. Null when not returned; service_type (string): Service type. Null when not returned; procedure_code (string): CDT code. Null when not returned; description (string): Payer description. Null when not returned; start_date (date): Start date. Null when not returned; end_date (date): End date. Null when not returned]; missing_tooth_clause (object): Missing tooth clause. Null when not returned [text (string): Payer text; applies (boolean): False only when the payer's text negates the clause]; downgrade_rules (array): Downgrade rules [text (string): Payer text; category (string): Service category; service_type (string): Service type; procedure_code (string): CDT code]; tooth_history (array): Prior services by tooth [tooth (string): Tooth; procedure_code (string): CDT code; service_date (date): Date of service; description (string): Payer description]; procedure_benefits (array): Enhanced mode only. Per code benefit detail: procedure_code, description, network, category, covered, coinsurance_percent, copayment, deductible_applies, frequency, age and waiting period fields, usage_count, remaining_usage, last_service_date, next_eligible_date, disclaimers; network_tiers (array): Enhanced mode only. Items carry network, status, description; coordination_of_benefits (object): Enhanced mode only. Carries other_coverage and description; eligibility_flags (array): Enhanced mode only. Items carry name, value, description; payer_notes (array): Enhanced mode only. Array of strings; disclaimers (array): Array of strings. Payer disclaimers; not_returned (array): Deprecated. Always an empty list for new answers. Use not_extracted, and read the full answer for what the payer sent; warnings (array): Array of strings. Parse warnings such as UNREADABLE_DATE or UNRECOGNIZED_COVERAGE_STATUS. They name the field, never the value; source (object): Where the answer came from [vendor (string): Always claimhouse. Kept so parsers that read it keep working; transaction_id (string): Vendor transaction id. Null when none was read]; retrieved_at (datetime): When the vendor call was made; vendor_latency_ms (integer): Vendor latency in milliseconds; cache (object): Whether this answer was reused [state (string): fresh for a payer call, hit for a reused answer; age_seconds (integer): Age of the reused answer. 0 when fresh]; billing (object): Whether this check is charged and why, read from its usage unit. Null only for a check recorded before usage metering began. The reasons are listed in the Pricing and what's charged guide [charged (boolean): Legacy ledger billability flag. True means BILLABLE; it does not prove invoice collection or a settled card payment; state (string): The unit's billable state; reason (string): Why, as a stable code: for example answered, payer_rejected_patient, payer_unavailable, cache_hit (a saved answer served again), test_mode or under_review; label (string): A short plain label for the reason; reason_label (string): One plain sentence saying whether and why the check is charged; unit_price_micros (integer): The price this check is rated at in its month so far, in micros (1 USD = 1,000,000): the tier its place in the month falls in. An estimate until the monthly statement is final. Null when not charged]; artifact_id (string): Only with include=pdf. Pass it to GET /v1/artifacts/{artifact_id} for a download link; pdf_filename (string): Only with include=pdf. Always elig_<eligibility_id>.pdf, never a patient name; not_extracted (array): Summary fields Claim House did not extract into a convenience value. The payer may have sent that information: our summary did not extract it. Read the full answer (GET /v1/eligibility/{eligibility_id}/answer); source_notes (array): Literal payer notes retained by the summary. Review the complete answer for all source sections; relationship_source (string): request: relationship is what the caller requested; service_date_source (string): request: date is request information, not proof the payer queried that date; operation_id (string): This intent's operation ID. It differs from eligibility_id when an earlier answer is reused; request_reference (string | null): Reference recorded for this intent. tenant_reference belongs to the saved answer; legacy reused intents may have no saved reference.
API reference

Check many patients

POSThttps://api.claimhouse.ai/v1/eligibility/batches

Hand over up to 10,000 checks at once, as JSON rows or a CSV, preview them for free, then run them all.

Send preview: true first. It validates every row, resolves each office and payer and finds duplicates. It is free, never reaches a payer and stores nothing.

Send the same body with preview: false and an Idempotency-Key to run it. The answer is 202 with a batch_id. Every ready row then runs as a normal POST /v1/eligibility check, with the same rules, limits and pricing, under your credential. Follow it with GET /v1/eligibility/batches/{batch_id} and read the rows with .../rows or .../results.

Each row gets its own check key, made from your organization, the mode, the row's content and today's date (UTC). The same row sent again the same day, in any batch, replays its answer instead of asking the payer again. A corrected row (another payer, a fixed member ID) is a new check.

In live mode, ready rows past today's remaining live check limit are counted in the preview (counts.over_daily_limit, daily_limit) and, at run, stored REFUSED with DAILY_LIMIT_REACHED and never sent. Raising the limit is an operator action: contact Claim House support.

Permission
submit
Idempotency
required
Side effects
Preview: none, except that an insurance name may store a payer mapping, exactly as GET /v1/payers/resolve does. Run: stores the batch and its rows; each ready row then runs one eligibility check, which may contact a payer once and may be charged like any check. Rows that are refused, need a payer or repeat an earlier row are stored and never sent.
In the dashboard
Eligibility > Batch checks

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret
Idempotency-KeystringRequired when preview is false (at most 200 characters). The same key with the same body returns the same batch with idempotent_replay: true and the Idempotent-Replayed: true header; the same key with a different body (including a different retry_payer_unavailable) is 422 IDEMPOTENCY_KEY_REUSED. Not needed for a preview.
e.g. batch-EXAMPLE-0001
Content-Type*stringMust be application/json.
e.g. application/json

Request body

NameTypeDescription
patientsarray1 to 10,000 items, each exactly the flat check body (office, insurance, member_id, patient, relationship, subscriber, group_number, visit_date, procedures, reference, max_age_seconds, view). Send exactly one of patients, rows or csv.
officestringApplies to every item, row or CSV line that leaves its own out: the office id, code or name.
visit_datestringApplies to every item that leaves its own out, in any of the three date formats.
previewbooleantrue to validate and resolve only (free, nothing stored). Default false.
e.g. true
referencestringYour name for the batch, at most 200 characters.
e.g. week-of-0928
rowsarray1 to 10,000 rows. Send exactly one of rows or csv. Every value is text; a row with a problem is refused on its own and the rest run.
referencestringYour id for the row, at most 200 characters. Strongly recommended: it comes back on every result.
e.g. appt-1001
facility_id*stringThe office: its id, its office code, or its display name. It must match exactly one office your credential can use, else the row is refused with OFFICE_UNKNOWN, OFFICE_AMBIGUOUS or OFFICE_NOT_GRANTED.
e.g. fac_tycrfy0cs0qc7sq95eme
payer*stringA payer id, your practice system's own payer id, or the insurance name. At most 80 letters, digits, spaces, ., - or _.
e.g. 62308
member_id*stringThe policy holder's member ID, at most 80 characters.
e.g. SYN000123456
first_name*stringThe policy holder's first name, at most 35 characters.
e.g. Sample
last_name*stringThe policy holder's last name, at most 60 characters.
e.g. Subscriber
date_of_birth*stringThe policy holder's date of birth as YYYY-MM-DD, YYYYMMDD or MM/DD/YYYY.
e.g. 1980-01-31
group_numberstringGroup number, at most 50 characters.
relationshipstringThe patient's relationship to the policy holder: self (the default), spouse, child or other, any case. The codes 18, 01, 19 and 34 are also accepted.
e.g. self
patientobject{first_name, last_name, date_of_birth}. Required when relationship is not self; leave it out when it is.
service_datestringThe date of service. Today (UTC) when blank.
e.g. 2026-10-05
csvstringCSV text with a header row, at most 8 MB (the whole request body at most 12 MB). Headers are matched without regard to case, and spaces and dashes count as _; columns no field accepts are ignored and listed in ignored_columns. See the "Checking many patients" guide for every accepted header.
e.g. reference,office,payer,member_id,first_name,last_name,date_of_birth appt-1001,SBX,62308,CH-ACTIVE-FULL,Sample,Subscriber,1980-01-31
retry_payer_unavailableobjectOptional. Without it every row is one check, and a row the payer did not answer (502 PAYER_UNAVAILABLE) is final, and free. With it, such rows are checked again 1, 4 and 12 hours after their first check, for each of those that falls within hours. Each try is a new check with its own key, recorded on its own; payer-down checks are free. Only PAYER_UNAVAILABLE qualifies.
hours*integer1 to 24. 1 gives one more try, 4 two more, 12 or more three more.
e.g. 4

Request example

{
  "preview": true,
  "office": "SBX",
  "visit_date": "2026-09-07",
  "patients": [
    {
      "reference": "appt-1",
      "insurance": "94276",
      "member_id": "CH-ACTIVE-FULL",
      "patient": {
        "first_name": "Avery",
        "last_name": "Molar",
        "date_of_birth": "1970-01-10"
      }
    },
    {
      "reference": "appt-2",
      "insurance": "94276",
      "member_id": "CH-TERMINATED",
      "patient": {
        "first_name": "Riley",
        "last_name": "Molar",
        "date_of_birth": "2015-06-02"
      },
      "relationship": "child",
      "subscriber": {
        "first_name": "Avery",
        "last_name": "Molar",
        "date_of_birth": "1970-01-10"
      },
      "visit_date": "2026-09-08"
    }
  ]
}

Response fields

NameTypeDescription
request_id*stringRequest id. The same value as the X-Request-Id header.
previewbooleanPreview only: true.
counts*objectPreview: rows, ready, refused, needs_payer, duplicate, and over_daily_limit (ready rows past today's remaining live limit; 0 in test mode). Run: Rows by state and by result: rows, pending, running, done, refused, needs_payer, duplicate, cancelled, and of the done rows active, inactive, unknown (answered with that coverage status) and not_answered (the check ended without an answer).
daily_limitobjectPreview, live mode only: limit, used_today (live checks admitted today, UTC; reused answers do not count) and remaining. Null in test mode.
ignored_columnsarrayPreview only: the columns or keys no field accepts.
rowsarrayPreview only: one entry per row with index, reference, facility_id, state (READY, REFUSED, NEEDS_PAYER or DUPLICATE), and payer, problems, duplicate_of or over_daily_limit: true as they apply. A ready row past the limit stays READY in the preview and is refused at run.
payer_choicesarrayPreview only: one entry per unclear insurance name per office: input, facility_id, mapping_id, rows (their indexes), state, suggested_payer_id and candidates (payer_id, name). Confirm one with POST /v1/payer-mapping/mappings/{mapping_id}/confirm, then preview again.
batch_idstringRun only: the batch, bat_ plus 20 characters.
e.g. bat_qtncqy7e316j97d2ft0x
statestringRun only: RUNNING while any row waits or runs, else COMPLETE.
one of: RUNNING · COMPLETE
idempotent_replaybooleanRun only: true when this Idempotency-Key already made this batch.

Responses

202Same key, same body: the same batch (header Idempotent-Replayed: true)
{
  "livemode": false,
  "request_id": "evt_4vpwbe4eyx6rvfn1nczc",
  "batch_id": "bat_4eghyt58pn73b6ezzxy2",
  "state": "RUNNING",
  "idempotent_replay": true,
  "counts": {
    "rows": 4,
    "pending": 3,
    "running": 0,
    "done": 0,
    "refused": 1,
    "needs_payer": 0,
    "duplicate": 0,
    "cancelled": 0,
    "active": 0,
    "inactive": 0,
    "unknown": 0,
    "not_answered": 0
  }
}
422Same key, different body
{
  "livemode": false,
  "error": "IDEMPOTENCY_KEY_REUSED",
  "message": "this Idempotency-Key was used with a different batch",
  "errors": [],
  "request_id": "evt_ckrqt20trn2g76cbqrsx",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-idempotency-key-reused",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}
400Run without an Idempotency-Key
{
  "livemode": false,
  "error": "IDEMPOTENCY_KEY_REQUIRED",
  "message": "the Idempotency-Key header is required",
  "errors": [],
  "request_id": "evt_4aj9j7gak12hk13wdjzc",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-idempotency-key-required",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}
422More than 10,000 rows
{
  "livemode": false,
  "error": "BATCH_TOO_LARGE",
  "message": "a batch has at most 10,000 rows",
  "errors": [],
  "request_id": "evt_qh7tp5fm7x5zk0pjb5wp",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-batch-too-large",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}
200Preview of a patients body (executed, test mode)
{
  "livemode": false,
  "request_id": "evt_0kx5zfa70h7mv2dv40kz",
  "preview": true,
  "counts": {
    "rows": 2,
    "ready": 2,
    "refused": 0,
    "needs_payer": 0,
    "duplicate": 0,
    "over_daily_limit": 0
  },
  "daily_limit": null,
  "ignored_columns": [],
  "rows": [
    {
      "index": 0,
      "reference": "appt-1",
      "facility_id": "fac_sandboxbatchsandbx",
      "state": "READY",
      "payer": {
        "input": "94276",
        "payer_id": "94276",
        "payer_name": "Delta Dental",
        "state": "EXACT"
      }
    },
    {
      "index": 1,
      "reference": "appt-2",
      "facility_id": "fac_sandboxbatchsandbx",
      "state": "READY",
      "payer": {
        "input": "94276",
        "payer_id": "94276",
        "payer_name": "Delta Dental",
        "state": "EXACT"
      }
    }
  ],
  "payer_choices": []
}
202Created from a patients body (executed, test mode)
{
  "livemode": false,
  "request_id": "evt_y6s9ffz7en6g55rt411q",
  "batch_id": "bat_e93gnpn9rd2j7ajb4wnx",
  "state": "RUNNING",
  "idempotent_replay": false,
  "counts": {
    "rows": 2,
    "pending": 2,
    "running": 0,
    "done": 0,
    "refused": 0,
    "needs_payer": 0,
    "duplicate": 0,
    "cancelled": 0,
    "active": 0,
    "inactive": 0,
    "unknown": 0,
    "not_answered": 0
  }
}

Errors

StatusCodeWhen
400IDEMPOTENCY_KEY_REQUIREDpreview is false and the Idempotency-Key header is missing or blank
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403FEATURE_NOT_ENTITLEDYour organization is not enrolled for eligibility
403PERMISSION_DENIEDKey lacks submit
413CSV_TOO_LARGEThe CSV is over 8 MB
413PAYLOAD_TOO_LARGEThe request body is over 12 MB
422BATCH_TOO_LARGEMore than 10,000 rows
422BATCH_EMPTYNo rows (a CSV with only a header)
422CSV_INVALIDThe CSV could not be read (unbalanced quotes)
422INVALID_REQUESTNeither or both of rows and csv, a row that is not an object, retry_payer_unavailable.hours outside 1 to 24, or the body fails the schema
422IDEMPOTENCY_KEY_REUSEDThe key made a different batch
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
503ELIGIBILITY_BATCHES_UNAVAILABLEBatches are not configured on this gateway
InfoRow problem codes: FIELD_REQUIRED, FIELD_TOO_LONG, FIELD_INVALID, DATE_INVALID, DATE_OF_BIRTH_IN_FUTURE, RELATIONSHIP_INVALID, PATIENT_REQUIRED, PATIENT_NOT_ALLOWED, OFFICE_UNKNOWN, OFFICE_AMBIGUOUS, OFFICE_NOT_GRANTED, MODE_MISMATCH, PAYER_TEXT_INVALID, PAYER_NOT_SUPPORTED, NOT_A_TEST_PATIENT (test mode), DAILY_LIMIT_REACHED (live rows past today's limit, at run), PATIENT_DATE_OF_BIRTH_REQUIRED, and the request rule findings of POST /v1/eligibility such as SUBSCRIBER_MEMBER_ID_REQUIRED or PATIENT_IS_SUBSCRIBER. A problem's message never repeats a value you sent.
InfoTwo rows with the same office, payer, member, people and service date are one check: the later row is DUPLICATE with duplicate_of pointing at the first, and only the first runs.
InfoA run is checked row by row when each row's turn comes, exactly as a single check: office access, the mode, the live rule (card on file, a live office ready for eligibility), today's test limit (live rows past today's limit are refused up front), and the payer. A refusal there makes that row DONE with the same http_status and error the single check returns, and the rest of the batch keeps running.
ImportantA batch runs as the credential that created it. Revoke that API key and its remaining rows finish as 401 UNAUTHORIZED. A batch started from a dashboard session runs for 24 hours; rows still waiting after that finish as 401 SESSION_EXPIRED.
API reference

List batches

GEThttps://api.claimhouse.ai/v1/eligibility/batches

Your recent batches in this mode, newest first, with their counts and no rows.

An API key sees batches of its own mode. A credential limited to some offices sees only batches whose offices are all in its scope.

Permission
read
Idempotency
safe to repeat
Side effects
Writes an audit read row listing the returned batch ids. Never contacts a payer.
In the dashboard
Eligibility > Batch checks

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Query parameters

NameTypeDescription
limitintegerBatches to return, 1 to 50. Default 20.
e.g. 20

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id. The same value as the X-Request-Id header.
batches*arrayBatches, newest first.
batch_id*stringThe batch.
e.g. bat_qtncqy7e316j97d2ft0x
referencestringYour name for the batch.
state*stringRUNNING while any row is PENDING or RUNNING; then CANCELLED for a cancelled batch, else COMPLETE.
one of: RUNNING · COMPLETE · CANCELLED
created_at*datetimeWhen the batch was made.
completed_atdatetimeWhen the last row finished. Null while running.
cancelled_atdatetimeWhen the batch was cancelled. Null unless cancelled.
retry_payer_unavailableobjectThe payer-down opt-in the batch was made with, {"hours": n}, or null.
counts*objectRows by state and by result: rows, pending, running, done, refused, needs_payer, duplicate, cancelled, and of the done rows active, inactive, unknown (answered with that coverage status) and not_answered (the check ended without an answer).

Responses

200OK: executed local Test scenario, synthetic ids
{
  "livemode": false,
  "request_id": "evt_zygkctdwjd64xbzka831",
  "batches": [
    {
      "batch_id": "bat_4eghyt58pn73b6ezzxy2",
      "reference": "week-of-1005",
      "state": "CANCELLED",
      "created_at": "2026-09-07T15:00:00Z",
      "completed_at": "2026-09-07T15:00:00Z",
      "cancelled_at": "2026-09-07T15:00:00Z",
      "retry_payer_unavailable": {
        "hours": 4
      },
      "counts": {
        "rows": 4,
        "pending": 0,
        "running": 0,
        "done": 2,
        "refused": 1,
        "needs_payer": 0,
        "duplicate": 0,
        "cancelled": 1,
        "active": 1,
        "inactive": 1,
        "unknown": 0,
        "not_answered": 0
      }
    }
  ]
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403FEATURE_NOT_ENTITLEDYour organization is not enrolled for eligibility
403PERMISSION_DENIEDKey lacks read
422INVALID_REQUESTlimit outside 1 to 50
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
503ELIGIBILITY_BATCHES_UNAVAILABLEBatches are not configured on this gateway
API reference

Read a batch

GEThttps://api.claimhouse.ai/v1/eligibility/batches/{batch_id}

The batch's state and counts, without rows. Poll it while the batch runs.

RUNNING while any row is PENDING or RUNNING; then CANCELLED for a cancelled batch, else COMPLETE. Poll every few seconds while it runs; reading never starts or repeats a check.

Rows are not in this response: page through them with GET /v1/eligibility/batches/{batch_id}/rows, or download every row with GET /v1/eligibility/batches/{batch_id}/results.

Results carry ids, codes, statuses and your references only. No names, dates of birth or member IDs are returned here.

Permission
read
Idempotency
safe to repeat
Side effects
Writes an audit read row naming the batch. Never contacts a payer.
In the dashboard
Eligibility > Batch checks > a batch

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Path parameters

NameTypeDescription
batch_id*stringThe batch_id from POST /v1/eligibility/batches.
e.g. bat_qtncqy7e316j97d2ft0x

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id. The same value as the X-Request-Id header.
batch_id*stringThe batch.
e.g. bat_qtncqy7e316j97d2ft0x
referencestringYour name for the batch. Null when not sent.
e.g. week-of-0928
mode*stringThe mode the batch runs in.
one of: test · production
e.g. test
state*stringRUNNING while any row is PENDING or RUNNING; then CANCELLED for a cancelled batch, else COMPLETE.
one of: RUNNING · COMPLETE · CANCELLED
e.g. COMPLETE
created_at*datetimeWhen the batch was made.
completed_atdatetimeWhen the last row finished. Null while running.
cancelled_atdatetimeWhen the batch was cancelled. Null unless cancelled.
retry_payer_unavailableobjectThe payer-down opt-in the batch was made with, {"hours": n}, or null.
counts*objectRows by state and by result: rows, pending, running, done, refused, needs_payer, duplicate, cancelled, and of the done rows active, inactive, unknown (answered with that coverage status) and not_answered (the check ended without an answer).

Responses

200OK: executed local Test scenario, synthetic ids (one row waiting for its next try)
{
  "livemode": false,
  "request_id": "evt_a36q7vq5y57jd79z3241",
  "batch_id": "bat_4eghyt58pn73b6ezzxy2",
  "reference": "week-of-1005",
  "state": "RUNNING",
  "created_at": "2026-09-07T15:00:00Z",
  "completed_at": null,
  "cancelled_at": null,
  "retry_payer_unavailable": {
    "hours": 4
  },
  "counts": {
    "rows": 4,
    "pending": 1,
    "running": 0,
    "done": 2,
    "refused": 1,
    "needs_payer": 0,
    "duplicate": 0,
    "cancelled": 0,
    "active": 1,
    "inactive": 1,
    "unknown": 0,
    "not_answered": 0
  },
  "mode": "test"
}
200Cancelled
{
  "livemode": false,
  "request_id": "evt_433135snsh7gdcj0aj39",
  "batch_id": "bat_4ewhr3yg3d2m55mas86d",
  "reference": null,
  "state": "CANCELLED",
  "created_at": "2026-09-07T15:00:00Z",
  "completed_at": "2026-09-07T15:00:00Z",
  "cancelled_at": "2026-09-07T15:00:00Z",
  "retry_payer_unavailable": null,
  "counts": {
    "rows": 4,
    "pending": 0,
    "running": 0,
    "done": 0,
    "refused": 1,
    "needs_payer": 0,
    "duplicate": 0,
    "cancelled": 3,
    "active": 0,
    "inactive": 0,
    "unknown": 0,
    "not_answered": 0
  },
  "mode": "test"
}
404Not found
{
  "livemode": false,
  "error": "NOT_FOUND",
  "message": "no such eligibility batch",
  "errors": [],
  "request_id": "evt_bnmwfmgnhh03z6p3afkt",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-not-found",
  "user_message": "We could not find that item. It may have been removed, or you may not have access to it."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403FEATURE_NOT_ENTITLEDYour organization is not enrolled for eligibility
403PERMISSION_DENIEDKey lacks read
404NOT_FOUNDNo such batch in your organization and key mode, or the batch names an office your credential cannot use
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
503ELIGIBILITY_BATCHES_UNAVAILABLEBatches are not configured on this gateway
InfoA row the payer did not answer (for example PAYER_UNAVAILABLE or VENDOR_ERROR) counts as not_answered. With retry_payer_unavailable, a PAYER_UNAVAILABLE row waits as PENDING for its next try. Otherwise check those patients again later: the same row sent again the same day replays its stored result, so send it the next day, or run a single check with a new Idempotency-Key.
InfoRefusals made before any work (503 CAPACITY, 429 TOO_MANY_REQUESTS, 409 ELIGIBILITY_OPERATION_PENDING) are waited out and retried for you, up to 20 times, and never reach a payer twice. 429 DAILY_LIMIT_REACHED and 429 TEST_LIMIT_REACHED finish the row; send those rows again the next day.
API reference

List a batch's rows

GEThttps://api.claimhouse.ai/v1/eligibility/batches/{batch_id}/rows

Every row's result, page by page: the check's status, error and id, with your reference.

Rows come in row order, at most limit per page. Pass next_cursor back as cursor, with the same filters, until it is null.

result filters by outcome: ACTIVE or INACTIVE (the payer answered with that status), UNKNOWN (answered, no clear status), NOT_ANSWERED (the check ended without an answer: a rejection, payer down, an error or a refusal at run time) and REFUSED (not sent: a row problem or a payer to choose). Waiting, running, duplicate and cancelled rows have no result word; filter them by state.

A DONE row carries http_status, error and message exactly as POST /v1/eligibility returned them for that check, and its eligibility_id when one was recorded. No names, dates of birth or member IDs are returned here.

Permission
read
Idempotency
safe to repeat
Side effects
Writes an audit read row naming the batch. Never contacts a payer.
In the dashboard
Eligibility > Batch checks > a batch

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Path parameters

NameTypeDescription
batch_id*stringThe batch_id from POST /v1/eligibility/batches.
e.g. bat_EXAMPLE0000000000001

Query parameters

NameTypeDescription
statestringOnly rows in this state.
one of: PENDING · RUNNING · DONE · REFUSED · NEEDS_PAYER · DUPLICATE · CANCELLED
resultstringOnly rows with this result.
one of: ACTIVE · INACTIVE · UNKNOWN · NOT_ANSWERED · REFUSED
limitintegerRows per page, 1 to 1,000. Default 500.
e.g. 500
cursorstringThe next_cursor from the previous page, with the same filters. Opaque.

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id. The same value as the X-Request-Id header.
batch_id*stringThe batch.
rows*arrayThis page's rows, in row order.
index*integerThe row's position, starting at 0 (a CSV header row is not counted).
referencestringYour reference for the row, as sent. Null when not sent.
facility_idstringThe office the row resolved to. Null when it did not resolve.
state*stringWhere the row is. A row waiting for its next payer-down try is PENDING.
one of: PENDING · RUNNING · DONE · REFUSED · NEEDS_PAYER · DUPLICATE · CANCELLED
http_statusintegerThe status POST /v1/eligibility returned for this row's last check.
eligibility_idstringThe check, when one was recorded (answers and recorded payer failures). Open it with GET /v1/eligibility/{eligibility_id}.
statusstringCoverage status of an answered check. Null otherwise.
one of: ACTIVE · INACTIVE · UNKNOWN
errorstringFor a check that was refused or failed: the error code POST /v1/eligibility returned, for example PAYER_REJECTED or PAYER_UNAVAILABLE. Null for an answer.
messagestringThe plain message that came with error.
idempotent_replaybooleantrue when the row replayed an answer the same check already had (the same row sent earlier the same day).
billingobjectWhether this check is charged and why, the same object POST /v1/eligibility returns.
rejectionobjectFor a payer rejection: kind, and the first reason's code and field. Codes only.
problemsarrayFor a REFUSED row: {field, code, message} for each problem found before any check ran.
payerobjectHow the row's payer resolved: input, payer_id, payer_name, state (EXACT, MAPPED, NEEDS_CHOICE or SUGGESTED), and mapping_id when a payer mapping is involved.
duplicate_ofintegerFor a DUPLICATE row: the index of the earlier row that is the same check.
attempts*integerChecks this row has made: 0 before its first, 1 after it, up to 4 with retry_payer_unavailable.
next_try_atdatetimeWhen a payer-down row is checked again. Null otherwise.
next_cursorstringPass as cursor for the next page. Null at the end.
linksobjectAPI version 2026-11-01, on a row the payer answered: answer and summary, where its organized answer is read. Absent on other rows and under 2026-10-01.

Responses

200First page of two (limit=2): executed local Test scenario, synthetic ids
{
  "livemode": false,
  "request_id": "evt_wgpejzf64n23xb12q04c",
  "batch_id": "bat_4eghyt58pn73b6ezzxy2",
  "rows": [
    {
      "index": 0,
      "reference": "appt-1001",
      "facility_id": "fac_sandboxbatchsandbx",
      "state": "DONE",
      "http_status": 200,
      "eligibility_id": "elg_de0skc6wkd6kv70zeyxv",
      "status": "ACTIVE",
      "error": null,
      "message": null,
      "idempotent_replay": false,
      "billing": {
        "charged": false,
        "label": "Test mode",
        "reason": "test_mode",
        "reason_label": "Test mode checks never reach a payer and are never charged",
        "state": "NOT_BILLABLE",
        "unit_price_micros": null
      },
      "rejection": null,
      "problems": null,
      "payer": {
        "input": "94276",
        "payer_id": "94276",
        "payer_name": "Delta Dental",
        "state": "EXACT"
      },
      "duplicate_of": null,
      "attempts": 1,
      "next_try_at": null
    },
    {
      "index": 1,
      "reference": "appt-1002",
      "facility_id": "fac_sandboxbatchsandbx",
      "state": "DONE",
      "http_status": 200,
      "eligibility_id": "elg_pr6kqzt8696yz41d720w",
      "status": "INACTIVE",
      "error": null,
      "message": null,
      "idempotent_replay": false,
      "billing": {
        "charged": false,
        "label": "Test mode",
        "reason": "test_mode",
        "reason_label": "Test mode checks never reach a payer and are never charged",
        "state": "NOT_BILLABLE",
        "unit_price_micros": null
      },
      "rejection": null,
      "problems": null,
      "payer": {
        "input": "94276",
        "payer_id": "94276",
        "payer_name": "Delta Dental",
        "state": "EXACT"
      },
      "duplicate_of": null,
      "attempts": 1,
      "next_try_at": null
    }
  ],
  "next_cursor": "eyJhIjoxLCJjIjoiZjBlNmM0YjUzOTQ0ODkzZiJ9"
}
422A cursor that was changed, belongs to another batch, or is sent with other filters
{
  "livemode": false,
  "error": "INVALID_CURSOR",
  "message": "cursor is not a cursor from this list",
  "errors": [],
  "request_id": "evt_2azzqtbdnn73b87nb0qf",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-invalid-cursor",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}
200API version 2026-11-01: rows link to their answer (executed, test mode)
{
  "livemode": false,
  "request_id": "evt_fem3pby60d7yh0tmbpty",
  "batch_id": "bat_e93gnpn9rd2j7ajb4wnx",
  "rows": [
    {
      "index": 0,
      "reference": "appt-1",
      "facility_id": "fac_sandboxbatchsandbx",
      "state": "DONE",
      "http_status": 200,
      "eligibility_id": "elg_npfp8hvb6d3tv8j8t65s",
      "status": "ACTIVE",
      "error": null,
      "message": null,
      "idempotent_replay": false,
      "billing": {
        "charged": false,
        "label": "Test mode",
        "reason": "test_mode",
        "reason_label": "Test mode checks never reach a payer and are never charged",
        "state": "NOT_BILLABLE",
        "unit_price_micros": null
      },
      "rejection": null,
      "problems": null,
      "payer": {
        "input": "94276",
        "payer_id": "94276",
        "payer_name": "Delta Dental",
        "state": "EXACT"
      },
      "duplicate_of": null,
      "attempts": 1,
      "next_try_at": null,
      "links": {
        "answer": "/v1/eligibility/elg_npfp8hvb6d3tv8j8t65s/answer?contract=v3",
        "summary": "/v1/eligibility/elg_npfp8hvb6d3tv8j8t65s/answer?contract=v3&view=summary"
      }
    },
    {
      "index": 1,
      "reference": "appt-2",
      "facility_id": "fac_sandboxbatchsandbx",
      "state": "DONE",
      "http_status": 200,
      "eligibility_id": "elg_292senh9ns0m13nyf1h9",
      "status": "INACTIVE",
      "error": null,
      "message": null,
      "idempotent_replay": false,
      "billing": {
        "charged": false,
        "label": "Test mode",
        "reason": "test_mode",
        "reason_label": "Test mode checks never reach a payer and are never charged",
        "state": "NOT_BILLABLE",
        "unit_price_micros": null
      },
      "rejection": null,
      "problems": null,
      "payer": {
        "input": "94276",
        "payer_id": "94276",
        "payer_name": "Delta Dental",
        "state": "EXACT"
      },
      "duplicate_of": null,
      "attempts": 1,
      "next_try_at": null,
      "links": {
        "answer": "/v1/eligibility/elg_292senh9ns0m13nyf1h9/answer?contract=v3",
        "summary": "/v1/eligibility/elg_292senh9ns0m13nyf1h9/answer?contract=v3&view=summary"
      }
    }
  ],
  "next_cursor": null
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403FEATURE_NOT_ENTITLEDYour organization is not enrolled for eligibility
403PERMISSION_DENIEDKey lacks read
404NOT_FOUNDNo such batch in your organization and key mode, or the batch names an office your credential cannot use
422INVALID_CURSORThe cursor was changed, belongs to another batch, or is sent with other filters
422INVALID_REQUESTstate or result is not an allowed value, or limit is outside 1 to 1,000
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
503ELIGIBILITY_BATCHES_UNAVAILABLEBatches are not configured on this gateway
InfoWith retry_payer_unavailable, a row waiting for its next try is PENDING, carries its last try's outcome (http_status 502, error PAYER_UNAVAILABLE) and next_try_at. Its final result is the last try.
API reference

Download a batch's results

GEThttps://api.claimhouse.ai/v1/eligibility/batches/{batch_id}/results

Every row in one file, CSV or JSON lines, with no patient values. Ready at any time.

Streams one line per row, every row, in row order: index, reference, office_code, facility_id, state, result, eligibility_id, http_status, error, message, rejection_code, rejection_field, charged, billing_reason.

format=csv (the default) is text/csv with a header line and CRLF line ends; an empty cell is null, and charged is true or false. format=jsonl is application/x-ndjson, one object per row, and its last line is {"summary": {...}}: the batch summary plus rows_in_file, which always equals counts.rows.

Ready at any time: while the batch runs, rows not yet checked show their current state. The file is read from the database a page at a time and sent as Content-Disposition: attachment; filename="bat_...-results.csv" (or .jsonl).

Permission
read
Idempotency
safe to repeat
Side effects
Writes an audit read row naming the batch. Never contacts a payer.
In the dashboard
Eligibility > Batch checks > a batch > Download results (CSV)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Path parameters

NameTypeDescription
batch_id*stringThe batch_id from POST /v1/eligibility/batches.
e.g. bat_EXAMPLE0000000000001

Query parameters

NameTypeDescription
formatstringFile format. Default csv.
one of: csv · jsonl

Request example

null

Response fields

NameTypeDescription
index*integerThe row's position, starting at 0.
referencestringYour reference for the row.
office_codestringThe office's code.
facility_idstringThe office the row resolved to.
state*stringThe row's state.
one of: PENDING · RUNNING · DONE · REFUSED · NEEDS_PAYER · DUPLICATE · CANCELLED
resultstringThe row's result word; empty for waiting, running, duplicate and cancelled rows.
one of: ACTIVE · INACTIVE · UNKNOWN · NOT_ANSWERED · REFUSED
eligibility_idstringThe check, when one was recorded.
http_statusintegerThe status of the row's last check.
errorstringThe error code of the row's last check, when it failed.
messagestringThe plain message that came with error.
rejection_codestringFor a payer rejection or payer down: the first reason's code.
rejection_fieldstringFor a payer rejection: the request field the reason names.
chargedbooleanWhether the check is charged.
billing_reasonstringWhy, as the stable billing.reason code.

Responses

200format=csv: executed local Test scenario, synthetic ids (row 3 waits for its next payer-down try)
"index,reference,office_code,facility_id,state,result,eligibility_id,http_status,error,message,rejection_code,rejection_field,charged,billing_reason\r\n0,appt-1001,SBX,fac_sandboxbatchsandbx,DONE,ACTIVE,elg_de0skc6wkd6kv70zeyxv,200,,,,,false,test_mode\r\n1,appt-1002,SBX,fac_sandboxbatchsandbx,DONE,INACTIVE,elg_pr6kqzt8696yz41d720w,200,,,,,false,test_mode\r\n2,appt-1003,SBX,fac_sandboxbatchsandbx,REFUSED,REFUSED,,,,,,,,\r\n3,appt-1004,SBX,fac_sandboxbatchsandbx,PENDING,,elg_t1daeb0bhh3q5czrxvx2,502,PAYER_UNAVAILABLE,The payer is not answering right now. Try again in a few minutes; nothing needs to change.,PAYER_NOT_ANSWERING,,false,test_mode\r\n"
200format=jsonl: the same batch
"{\"index\":0,\"reference\":\"appt-1001\",\"office_code\":\"SBX\",\"facility_id\":\"fac_sandboxbatchsandbx\",\"state\":\"DONE\",\"result\":\"ACTIVE\",\"eligibility_id\":\"elg_de0skc6wkd6kv70zeyxv\",\"http_status\":200,\"error\":null,\"message\":null,\"rejection_code\":null,\"rejection_field\":null,\"charged\":false,\"billing_reason\":\"test_mode\"}\n{\"index\":1,\"reference\":\"appt-1002\",\"office_code\":\"SBX\",\"facility_id\":\"fac_sandboxbatchsandbx\",\"state\":\"DONE\",\"result\":\"INACTIVE\",\"eligibility_id\":\"elg_pr6kqzt8696yz41d720w\",\"http_status\":200,\"error\":null,\"message\":null,\"rejection_code\":null,\"rejection_field\":null,\"charged\":false,\"billing_reason\":\"test_mode\"}\n{\"index\":2,\"reference\":\"appt-1003\",\"office_code\":\"SBX\",\"facility_id\":\"fac_sandboxbatchsandbx\",\"state\":\"REFUSED\",\"result\":\"REFUSED\",\"eligibility_id\":null,\"http_status\":null,\"error\":null,\"message\":null,\"rejection_code\":null,\"rejection_field\":null,\"charged\":null,\"billing_reason\":null}\n{\"index\":3,\"reference\":\"appt-1004\",\"office_code\":\"SBX\",\"facility_id\":\"fac_sandboxbatchsandbx\",\"state\":\"PENDING\",\"result\":null,\"eligibility_id\":\"elg_t1daeb0bhh3q5czrxvx2\",\"http_status\":502,\"error\":\"PAYER_UNAVAILABLE\",\"message\":\"The payer is not answering right now. Try again in a few minutes; nothing needs to change.\",\"rejection_code\":\"PAYER_NOT_ANSWERING\",\"rejection_field\":null,\"charged\":false,\"billing_reason\":\"test_mode\"}\n{\"summary\":{\"batch_id\":\"bat_4eghyt58pn73b6ezzxy2\",\"reference\":\"week-of-1005\",\"state\":\"RUNNING\",\"created_at\":\"2026-09-07T15:00:00Z\",\"completed_at\":null,\"cancelled_at\":null,\"retry_payer_unavailable\":{\"hours\":4},\"counts\":{\"rows\":4,\"pending\":1,\"running\":0,\"done\":2,\"refused\":1,\"needs_payer\":0,\"duplicate\":0,\"cancelled\":0,\"active\":1,\"inactive\":1,\"unknown\":0,\"not_answered\":0},\"mode\":\"test\",\"rows_in_file\":4}}\n"
200API version 2026-11-01, format=csv: the answer_url column (executed, test mode)
"index,reference,office_code,facility_id,state,result,eligibility_id,http_status,error,message,rejection_code,rejection_field,charged,billing_reason,answer_url\r\n0,appt-1,SBX,fac_sandboxbatchsandbx,DONE,ACTIVE,elg_npfp8hvb6d3tv8j8t65s,200,,,,,false,test_mode,/v1/eligibility/elg_npfp8hvb6d3tv8j8t65s/answer?contract=v3\r\n1,appt-2,SBX,fac_sandboxbatchsandbx,DONE,INACTIVE,elg_292senh9ns0m13nyf1h9,200,,,,,false,test_mode,/v1/eligibility/elg_292senh9ns0m13nyf1h9/answer?contract=v3\r\n"

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403FEATURE_NOT_ENTITLEDYour organization is not enrolled for eligibility
403PERMISSION_DENIEDKey lacks read
404NOT_FOUNDNo such batch in your organization and key mode, or the batch names an office your credential cannot use
422INVALID_REQUESTformat is not csv or jsonl
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
503ELIGIBILITY_BATCHES_UNAVAILABLEBatches are not configured on this gateway
InfoResponse fields above are the file's columns, not a JSON body.
InfoAPI version 2026-11-01 adds one last column, answer_url: where an answered row's organized answer is read (empty for a row with no answer). Pinned to 2026-10-01 the file has the columns above only.
API reference

Cancel a batch

POSThttps://api.claimhouse.ai/v1/eligibility/batches/{batch_id}/cancel

Stop a batch: every row not yet sent is cancelled; rows being checked finish.

Every PENDING row, including a payer-down row waiting for its next try, becomes CANCELLED and is never sent. Rows already RUNNING finish normally: a payer call in progress is never interrupted.

Returns the batch summary plus cancelled_rows, how many rows this call cancelled. The batch reads CANCELLED once no row is running (until then RUNNING).

Calling it again, or on a finished batch, changes nothing: cancelled_rows: 0 and the same summary. A batch that finished before you cancelled stays COMPLETE.

Permission
submit
Idempotency
safe to repeat (Idempotency-Key accepted, not needed)
Side effects
Marks the batch's waiting rows CANCELLED. Never contacts a payer.
In the dashboard
Eligibility > Batch checks > a batch > Cancel remaining

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret
Idempotency-KeystringAccepted and optional: cancel is idempotent by itself.

Path parameters

NameTypeDescription
batch_id*stringThe batch_id from POST /v1/eligibility/batches.
e.g. bat_EXAMPLE0000000000001

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id. The same value as the X-Request-Id header.
batch_id*stringThe batch.
referencestringYour name for the batch.
state*stringRUNNING while any row is PENDING or RUNNING; then CANCELLED for a cancelled batch, else COMPLETE.
one of: RUNNING · COMPLETE · CANCELLED
created_at*datetimeWhen the batch was made.
completed_atdatetimeWhen the last row finished. Null while running.
cancelled_atdatetimeWhen the batch was cancelled. Null unless cancelled.
retry_payer_unavailableobjectThe payer-down opt-in the batch was made with, {"hours": n}, or null.
counts*objectRows by state and by result: rows, pending, running, done, refused, needs_payer, duplicate, cancelled, and of the done rows active, inactive, unknown (answered with that coverage status) and not_answered (the check ended without an answer).
mode*stringThe mode the batch runs in.
one of: test · production
cancelled_rows*integerHow many rows this call cancelled.

Responses

200Cancel before any row ran: executed local Test scenario, synthetic ids
{
  "livemode": false,
  "request_id": "evt_erh276p0ks2xh5f8w57n",
  "batch_id": "bat_4ewhr3yg3d2m55mas86d",
  "reference": null,
  "state": "CANCELLED",
  "created_at": "2026-09-07T15:00:00Z",
  "completed_at": "2026-09-07T15:00:00Z",
  "cancelled_at": "2026-09-07T15:00:00Z",
  "retry_payer_unavailable": null,
  "counts": {
    "rows": 4,
    "pending": 0,
    "running": 0,
    "done": 0,
    "refused": 1,
    "needs_payer": 0,
    "duplicate": 0,
    "cancelled": 3,
    "active": 0,
    "inactive": 0,
    "unknown": 0,
    "not_answered": 0
  },
  "mode": "test",
  "cancelled_rows": 3
}
200Calling cancel again
{
  "livemode": false,
  "request_id": "evt_2e87z2x6td7kf75cd2mm",
  "batch_id": "bat_4eghyt58pn73b6ezzxy2",
  "reference": "week-of-1005",
  "state": "CANCELLED",
  "created_at": "2026-09-07T15:00:00Z",
  "completed_at": "2026-09-07T15:00:00Z",
  "cancelled_at": "2026-09-07T15:00:00Z",
  "retry_payer_unavailable": {
    "hours": 4
  },
  "counts": {
    "rows": 4,
    "pending": 0,
    "running": 0,
    "done": 2,
    "refused": 1,
    "needs_payer": 0,
    "duplicate": 0,
    "cancelled": 1,
    "active": 1,
    "inactive": 1,
    "unknown": 0,
    "not_answered": 0
  },
  "mode": "test",
  "cancelled_rows": 0
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403FEATURE_NOT_ENTITLEDYour organization is not enrolled for eligibility
403PERMISSION_DENIEDKey lacks submit
404NOT_FOUNDNo such batch in your organization and key mode, or the batch names an office your credential cannot use
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
503ELIGIBILITY_BATCHES_UNAVAILABLEBatches are not configured on this gateway
API reference

Get an eligibility answer

GEThttps://api.claimhouse.ai/v1/eligibility/{eligibility_id}

Read one check: its organized answer, what it cost and what was sent.

Returns the check's answer (contract eligibility.v3, view complete), the same as the check returned, plus billing and request: your reference, the Idempotency-Key it ran under, and the group number and procedure codes you sent.

A check the payer did not answer has status: not_answered and a failure block (error_class, and the payer's rejection when it refused), with no answer blocks. An answer whose truth checks did not pass reads verified: false with no organized block.

This is API version 2026-11-01, the default. Claim-House-Version: 2026-10-01 returns the earlier check record.

Permission
read
Idempotency
none
Side effects
Writes an audit read row. Never contacts the eligibility vendor.
In the dashboard
Eligibility > New check (answer card), Eligibility > Previous checks

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Path parameters

NameTypeDescription
eligibility_id*stringThe check id, elg_..., 1 to 64 characters.
e.g. elg_hp130jp45188vw4wk5tz

Request example

null

Response fields

NameTypeDescription
id*stringThe check id, elg_.... A reused answer keeps the original check's id.
contract*stringAlways eligibility.v3.
one of: eligibility.v3
view*stringThe view served: complete (the default), summary, lines or payer.
one of: complete · summary · lines · payer
status*stringThe coverage status: active, inactive or unknown (not_answered only on a read of a check the payer did not answer).
one of: active · inactive · unknown · not_answered
checked_at*stringWhen the payer answered (ISO 8601).
verified*booleanTrue only when every truth check passed for this exact answer: every payer row is one line, every value is in its line unchanged, no number in a sentence that the payer did not send. False: the organized answer is withheld (no organized block is present) and links.payer_answer still answers.
unverified_reasonstringOnly with verified: false: why the organized answer is withheld.
office*objectThe office the check was made for: id and name.
payer*objectid and name are Claim House's directory entry. id_as_returned and name_as_returned are the payer's own words. Neither replaces the other.
patientobjectThe person being seen, exactly as the payer returned them (dates as YYYY-MM-DD when the payer sent a clean date). Fields the payer did not send are absent.
subscriberobjectThe policy holder as returned, when the payer returned one apart from the patient.
dependentsarrayOther people the payer listed.
as_requestedobjectWhat you sent (subscriber, patient, relationship, visit_date), with differences (fields the payer returned with another value) and not_returned (fields or a whole person you sent that the payer did not return). Never substituted for the payer's people.
planobjectPlan fields as the payer sent them (name, type, group_number, group_name, ...), coverage (status and each date under its own name: start, end, termination; plus the payer's active coverage rows as lines) and plan notes.
totalsobjectdeductibles, maximums and out_of_pocket: one line per payer row that names no procedure code, in payer order. A remaining amount is its own line with period: remaining.
by_servicearrayLines grouped by the payer's service type (service, label, lines) for rows that name no procedure code; service: not_stated when the payer named none.
by_procedurearrayEvery row that names a CDT code, grouped by code (code, code_as_sent, lines, history). Codes only, never procedure names. A row naming several codes is listed under each, with shared_with, and counted once.
historyarrayEvery service date the payer sent, newest first: code, type as sent, date, ref. A copy sits under each code.
not_coveredarrayThe payer's not covered rows, one line each.
notesarrayPayer notes and disclaimers that belong to no other line.
rejectionobjectThe payer's refusal details, when it sent them, with its rows as lines.
otherobjectAnything else the payer sent at the top level, verbatim.
missingarraySections an office usually expects that the payer did not send (deductible, maximums, coinsurance, limitations, not_covered, waiting_period).
not_readarrayFields kept verbatim under a line's other because Claim House does not organize them. Nothing is dropped.
labelsobjectPlain words for the payer tokens in this answer, by kind (network, level, period, service, ...).
counts*objectpayer_rows and lines (always equal), procedures, notes, history. A summary carries complete_lines and shown_lines instead.
excludedarrayPaths kept out on purpose (our own office identity echoed back, the network's computed summaries, social security numbers); their values are never shown.
links*objectcomplete, summary, lines, payer_answer and pdf: where each view of this answer is read.
failureobjectOnly on a check the payer did not answer: error_class and rejection.
billing*objectWhether the check is charged and why.
requestobjectWhat was sent: reference, idempotency_key, group_number, procedures (each only when present).

Responses

200OK: an answered check (executed test check, synthetic patient and ids)
{
  "livemode": false,
  "request_id": "evt_jbarbayqk15kqdkn80w7",
  "id": "elg_9aqbap922506q92gx9ge",
  "contract": "eligibility.v3",
  "view": "complete",
  "status": "active",
  "checked_at": "2026-09-07T15:00:00+00:00",
  "verified": true,
  "office": {
    "id": "fac_sandboxbatchsandbx",
    "name": "fac_sandboxbatchsandbx"
  },
  "payer": {
    "id": "94276",
    "name": "Delta Dental",
    "id_as_returned": "94276",
    "name_as_returned": "Delta Dental"
  },
  "patient": {
    "date_of_birth": "1980-01-01",
    "first_name": "TEST",
    "last_name": "PATIENT",
    "member_id": "CH-ACTIVE-FULL",
    "relationship": "self"
  },
  "as_requested": {
    "subscriber": {
      "first_name": "Test",
      "last_name": "Patient",
      "date_of_birth": "1980-01-01",
      "member_id": "CH-ACTIVE-FULL"
    },
    "relationship": "self",
    "visit_date": "2026-09-07",
    "differences": [],
    "not_returned": [
      "subscriber"
    ]
  },
  "plan": {
    "group_number": "TESTGRP1",
    "insurance_type": "ppo",
    "name": "Delta Dental PPO",
    "coverage": {
      "start": "2026-01-01",
      "status": "active",
      "termination": "2026-12-31",
      "lines": [
        {
          "kind": "active_coverage",
          "network": "in_network",
          "insurance_type": "group_policy",
          "text": "In network, group policy: active coverage",
          "ref": "active_coverage[0]"
        }
      ]
    }
  },
  "totals": {
    "deductibles": [
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "individual",
        "period": "calendar",
        "service": "dental_care",
        "amount": "50.00",
        "text": "Dental care (general), in network, individual, calendar year: deductible $50.00",
        "ref": "deductible[0]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "individual",
        "period": "remaining",
        "service": "dental_care",
        "amount": "25.00",
        "text": "Dental care (general), in network, individual, remaining: deductible $25.00",
        "ref": "deductible[1]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "family",
        "period": "calendar",
        "service": "dental_care",
        "amount": "150.00",
        "text": "Dental care (general), in network, family, calendar year: deductible $150.00",
        "ref": "deductible[2]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "family",
        "period": "remaining",
        "service": "dental_care",
        "amount": "150.00",
        "text": "Dental care (general), in network, family, remaining: deductible $150.00",
        "ref": "deductible[3]"
      }
    ],
    "maximums": [
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "calendar",
        "service": "dental_care",
        "amount": "1500.00",
        "text": "Dental care (general), in network, individual, calendar year: maximum $1500.00",
        "ref": "maximums[0]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "remaining",
        "service": "dental_care",
        "amount": "1200.00",
        "text": "Dental care (general), in network, individual, remaining: maximum $1200.00",
        "ref": "maximums[1]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "lifetime",
        "service": "orthodontics",
        "amount": "1000.00",
        "text": "Orthodontics, in network, individual, lifetime: maximum $1000.00",
        "ref": "maximums[2]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "lifetime_remaining",
        "service": "orthodontics",
        "amount": "1000.00",
        "text": "Orthodontics, in network, individual, lifetime remaining: maximum $1000.00",
        "ref": "maximums[3]"
      }
    ]
  },
  "by_service": [
    {
      "service": "preventive",
      "label": "Preventive care",
      "lines": [
        {
          "kind": "coinsurance",
          "network": "in_network",
          "percent": 100,
          "text": "Preventive care, in network: coinsurance 100%",
          "ref": "coinsurance[0]"
        }
      ]
    },
    {
      "service": "restorative",
      "label": "Restorative (fillings)",
      "lines": [
        {
          "kind": "coinsurance",
          "network": "in_network",
          "percent": 80,
          "text": "Restorative (fillings), in network: coinsurance 80%",
          "ref": "coinsurance[1]"
        }
      ]
    },
    {
      "service": "dental_crowns",
      "label": "Crowns",
      "lines": [
        {
          "kind": "coinsurance",
          "network": "in_network",
          "percent": 50,
          "text": "Crowns, in network: coinsurance 50%",
          "ref": "coinsurance[2]"
        }
      ]
    }
  ],
  "by_procedure": [
    {
      "code": "D0274",
      "code_as_sent": "AD:D0274",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 visits in 12 month",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "month",
              "time_period_value": "12"
            }
          ],
          "text": "D0274, all networks, individual: limitation 1 visits in 12 month (frequency 1 visits per 12 months)",
          "ref": "limitations[2]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 units remaining",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "text": "D0274, all networks, individual: limitation 1 units remaining (frequency 1 units, time period remaining)",
          "ref": "limitations[3]"
        }
      ]
    },
    {
      "code": "D1110",
      "code_as_sent": "AD:D1110",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "2 visits in 1 calendar",
          "frequency": [
            {
              "quantity": "2",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "calendar",
              "time_period_value": "1"
            }
          ],
          "text": "D1110, all networks, individual: limitation 2 visits in 1 calendar (frequency 2 visits per calendar year)",
          "ref": "limitations[0]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 units remaining",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "text": "D1110, all networks, individual: limitation 1 units remaining (frequency 1 units, time period remaining)",
          "ref": "limitations[1]"
        }
      ]
    }
  ],
  "missing": [
    "not_covered",
    "waiting_period"
  ],
  "not_read": [],
  "labels": {
    "network": {
      "applies_all": "All networks",
      "in_network": "In network"
    },
    "level": {
      "family": "Family",
      "individual": "Individual"
    },
    "period": {
      "calendar": "Calendar year",
      "lifetime": "Lifetime",
      "lifetime_remaining": "Lifetime remaining",
      "remaining": "Remaining"
    },
    "service": {
      "dental_care": "Dental care (general)",
      "dental_crowns": "Crowns",
      "orthodontics": "Orthodontics",
      "preventive": "Preventive care",
      "restorative": "Restorative (fillings)"
    },
    "insurance_type": {
      "group_policy": "Group policy",
      "ppo": "PPO"
    }
  },
  "counts": {
    "payer_rows": 16,
    "lines": 16,
    "procedures": 2,
    "notes": 0,
    "history": 0
  },
  "links": {
    "complete": "/v1/eligibility/elg_9aqbap922506q92gx9ge/answer?contract=v3",
    "summary": "/v1/eligibility/elg_9aqbap922506q92gx9ge/answer?contract=v3&view=summary",
    "lines": "/v1/eligibility/elg_9aqbap922506q92gx9ge/answer?contract=v3&view=lines",
    "payer_answer": "/v1/eligibility/elg_9aqbap922506q92gx9ge/answer?view=payer",
    "pdf": "/v1/eligibility/elg_9aqbap922506q92gx9ge/pdf"
  },
  "billing": {
    "charged": false,
    "state": "NOT_BILLABLE",
    "reason": "test_mode",
    "label": "Test mode",
    "reason_label": "Test mode checks never reach a payer and are never charged"
  },
  "request": {
    "idempotency_key": "first-check-ab12cd"
  }
}
200A check the payer did not answer (test scenario CH-AAA-42)
{
  "livemode": false,
  "request_id": "evt_0htmp36hvh683c5f5hvv",
  "id": "elg_8dz3g4gsy54rz54v89eg",
  "contract": "eligibility.v3",
  "status": "not_answered",
  "checked_at": "2026-09-07T15:00:00+00:00",
  "office": {
    "id": "fac_sandboxbatchsandbx"
  },
  "payer": {
    "id": "94276"
  },
  "failure": {
    "error_class": "VENDOR_UNAVAILABLE"
  },
  "billing": {
    "charged": false,
    "state": "NOT_BILLABLE",
    "reason": "test_mode",
    "label": "Test mode",
    "reason_label": "Test mode checks never reach a payer and are never charged"
  },
  "request": {
    "reference": "appt-1001",
    "idempotency_key": "chk_d4c0de981ea93e7f89c870faa5f55c21be4dd363"
  }
}
200Pinned to 2026-10-01: the earlier check record (executed)
{
  "livemode": false,
  "request_id": "evt_hy0k6hg2zd77vbzj8b5v",
  "active_coverage": [
    {
      "amount": null,
      "as_sent": {
        "insurance_type": "group_policy",
        "network": "in_network"
      },
      "category": null,
      "coverage_level": null,
      "description": null,
      "end_date": null,
      "insurance_type": "group_policy",
      "network": "in_network",
      "percent": null,
      "plan_period": null,
      "procedure_code": null,
      "remaining": null,
      "section": "active_coverage",
      "service_type": null,
      "start_date": null,
      "used": null
    }
  ],
  "cache": {
    "age_seconds": 0,
    "state": "fresh"
  },
  "coinsurance": [
    {
      "amount": null,
      "as_sent": {
        "network": "in_network",
        "percent": "100",
        "service_type": "preventive"
      },
      "category": null,
      "coverage_level": null,
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": "100",
      "plan_period": null,
      "procedure_code": null,
      "remaining": null,
      "section": "coinsurance",
      "service_type": "preventive",
      "start_date": null,
      "used": null
    },
    {
      "amount": null,
      "as_sent": {
        "network": "in_network",
        "percent": "80",
        "service_type": "restorative"
      },
      "category": null,
      "coverage_level": null,
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": "80",
      "plan_period": null,
      "procedure_code": null,
      "remaining": null,
      "section": "coinsurance",
      "service_type": "restorative",
      "start_date": null,
      "used": null
    },
    {
      "amount": null,
      "as_sent": {
        "network": "in_network",
        "percent": "50",
        "service_type": "dental_crowns"
      },
      "category": null,
      "coverage_level": null,
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": "50",
      "plan_period": null,
      "procedure_code": null,
      "remaining": null,
      "section": "coinsurance",
      "service_type": "dental_crowns",
      "start_date": null,
      "used": null
    }
  ],
  "copayments": [],
  "coverage": {
    "effective_date": "2026-01-01",
    "status_reason": null,
    "termination_date": "2026-12-31"
  },
  "deductibles": [
    {
      "amount": "50.00",
      "as_sent": {
        "amount": "50.00",
        "coverage_level": "individual",
        "network": "in_network",
        "plan_period": "calendar",
        "service_type": "dental_care"
      },
      "category": null,
      "coverage_level": "individual",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "calendar",
      "procedure_code": null,
      "remaining": null,
      "section": "deductible",
      "service_type": "dental_care",
      "start_date": null,
      "used": null
    },
    {
      "amount": "25.00",
      "as_sent": {
        "amount": "25.00",
        "coverage_level": "individual",
        "network": "in_network",
        "plan_period": "remaining",
        "service_type": "dental_care"
      },
      "category": null,
      "coverage_level": "individual",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "remaining",
      "procedure_code": null,
      "remaining": null,
      "section": "deductible",
      "service_type": "dental_care",
      "start_date": null,
      "used": null
    },
    {
      "amount": "150.00",
      "as_sent": {
        "amount": "150.00",
        "coverage_level": "family",
        "network": "in_network",
        "plan_period": "calendar",
        "service_type": "dental_care"
      },
      "category": null,
      "coverage_level": "family",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "calendar",
      "procedure_code": null,
      "remaining": null,
      "section": "deductible",
      "service_type": "dental_care",
      "start_date": null,
      "used": null
    },
    {
      "amount": "150.00",
      "as_sent": {
        "amount": "150.00",
        "coverage_level": "family",
        "network": "in_network",
        "plan_period": "remaining",
        "service_type": "dental_care"
      },
      "category": null,
      "coverage_level": "family",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "remaining",
      "procedure_code": null,
      "remaining": null,
      "section": "deductible",
      "service_type": "dental_care",
      "start_date": null,
      "used": null
    }
  ],
  "disclaimers": [],
  "downgrade_rules": [],
  "eligibility_id": "elg_k3dkr9s0h95s90z0zc4g",
  "facility_id": "fac_sandboxbatchsandbx",
  "frequency_limitations": [
    {
      "as_sent": {
        "coverage_level": "individual",
        "health_service_descriptions": [
          {
            "quantity": "2",
            "quantity_qualifier": "visits",
            "time_period_qualifier": "calendar",
            "time_period_value": "1"
          }
        ],
        "limitation": "2 visits in 1 calendar",
        "network": "applies_all",
        "procedure_code": "AD:D1110"
      },
      "category": null,
      "description": null,
      "end_date": null,
      "network": "applies_all",
      "plan_period": null,
      "procedure_code": "D1110",
      "quantity": null,
      "quantity_remaining": null,
      "quantity_used": null,
      "service_type": null,
      "start_date": null
    },
    {
      "as_sent": {
        "coverage_level": "individual",
        "health_service_descriptions": [
          {
            "quantity": "1",
            "quantity_qualifier": "units",
            "time_period_qualifier": "remaining"
          }
        ],
        "limitation": "1 units remaining",
        "network": "applies_all",
        "procedure_code": "AD:D1110"
      },
      "category": null,
      "description": null,
      "end_date": null,
      "network": "applies_all",
      "plan_period": null,
      "procedure_code": "D1110",
      "quantity": null,
      "quantity_remaining": null,
      "quantity_used": null,
      "service_type": null,
      "start_date": null
    },
    {
      "as_sent": {
        "coverage_level": "individual",
        "health_service_descriptions": [
          {
            "quantity": "1",
            "quantity_qualifier": "visits",
            "time_period_qualifier": "month",
            "time_period_value": "12"
          }
        ],
        "limitation": "1 visits in 12 month",
        "network": "applies_all",
        "procedure_code": "AD:D0274"
      },
      "category": null,
      "description": null,
      "end_date": null,
      "network": "applies_all",
      "plan_period": null,
      "procedure_code": "D0274",
      "quantity": null,
      "quantity_remaining": null,
      "quantity_used": null,
      "service_type": null,
      "start_date": null
    },
    {
      "as_sent": {
        "coverage_level": "individual",
        "health_service_descriptions": [
          {
            "quantity": "1",
            "quantity_qualifier": "units",
            "time_period_qualifier": "remaining"
          }
        ],
        "limitation": "1 units remaining",
        "network": "applies_all",
        "procedure_code": "AD:D0274"
      },
      "category": null,
      "description": null,
      "end_date": null,
      "network": "applies_all",
      "plan_period": null,
      "procedure_code": "D0274",
      "quantity": null,
      "quantity_remaining": null,
      "quantity_used": null,
      "service_type": null,
      "start_date": null
    }
  ],
  "maximums": [
    {
      "amount": "1500.00",
      "as_sent": {
        "amount": "1500.00",
        "coverage_level": "individual",
        "network": "in_network",
        "plan_period": "calendar",
        "service_type": "dental_care"
      },
      "category": null,
      "coverage_level": "individual",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "calendar",
      "procedure_code": null,
      "remaining": null,
      "section": "maximums",
      "service_type": "dental_care",
      "start_date": null,
      "used": null
    },
    {
      "amount": "1200.00",
      "as_sent": {
        "amount": "1200.00",
        "coverage_level": "individual",
        "network": "in_network",
        "plan_period": "remaining",
        "service_type": "dental_care"
      },
      "category": null,
      "coverage_level": "individual",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "remaining",
      "procedure_code": null,
      "remaining": null,
      "section": "maximums",
      "service_type": "dental_care",
      "start_date": null,
      "used": null
    },
    {
      "amount": "1000.00",
      "as_sent": {
        "amount": "1000.00",
        "coverage_level": "individual",
        "network": "in_network",
        "plan_period": "lifetime",
        "service_type": "orthodontics"
      },
      "category": null,
      "coverage_level": "individual",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "lifetime",
      "procedure_code": null,
      "remaining": null,
      "section": "maximums",
      "service_type": "orthodontics",
      "start_date": null,
      "used": null
    },
    {
      "amount": "1000.00",
      "as_sent": {
        "amount": "1000.00",
        "coverage_level": "individual",
        "network": "in_network",
        "plan_period": "lifetime_remaining",
        "service_type": "orthodontics"
      },
      "category": null,
      "coverage_level": "individual",
      "description": null,
      "end_date": null,
      "insurance_type": null,
      "network": "in_network",
      "percent": null,
      "plan_period": "lifetime_remaining",
      "procedure_code": null,
      "remaining": null,
      "section": "maximums",
      "service_type": "orthodontics",
      "start_date": null,
      "used": null
    }
  ],
  "missing_tooth_clause": null,
  "mode": "standard",
  "network_status": null,
  "not_covered": [],
  "not_extracted": [
    "waiting_periods",
    "missing_tooth_clause",
    "downgrade_rules",
    "tooth_history"
  ],
  "not_returned": [],
  "out_of_pocket": [],
  "payer_id": "94276",
  "plan": {
    "group_number": "TESTGRP1",
    "name": "Delta Dental PPO",
    "type": null
  },
  "procedure_codes": [
    "D1120"
  ],
  "relationship": "child",
  "relationship_source": "request",
  "retrieved_at": "2026-09-07T15:00:00+00:00",
  "service_date": "2026-09-07",
  "service_date_source": "request",
  "source": {
    "transaction_id": "test-smp_magic_active_full",
    "vendor": "claimhouse"
  },
  "source_notes": [],
  "status": "ACTIVE",
  "tenant_reference": "visit-0001",
  "tooth_history": [],
  "vendor_latency_ms": 320,
  "waiting_periods": [],
  "warnings": [
    "NETWORK_SUMMARY_DEPRECATED",
    "SUMMARY_FIELDS_ARE_NOT_COMPLETE_PAYER_INFORMATION"
  ],
  "outcome": "OK",
  "error_class": null,
  "procedure_benefits": [],
  "network_tiers": [],
  "coordination_of_benefits": null,
  "eligibility_flags": [],
  "payer_notes": [],
  "idempotency_key": "elig-camel-0001",
  "group_number": null,
  "billing": {
    "charged": false,
    "state": "NOT_BILLABLE",
    "reason": "test_mode",
    "label": "Test mode",
    "reason_label": "Test mode checks never reach a payer and are never charged",
    "unit_price_micros": null
  }
}
404Not found
{
  "error": "NOT_FOUND",
  "message": "no such eligibility result",
  "errors": [],
  "request_id": "evt_wmkpgd7r9t71sskpmz6q",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-not-found",
  "user_message": "We could not find that item. It may have been removed, or you may not have access to it."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks the route's permission
404NOT_FOUNDNo such check, or outside the key's office grants
422INVALID_REQUESTPath, query or body fails the schema
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
InfoA failure record carries only eligibility_id, facility_id, payer_id, relationship, service_date, status, outcome, error_class, source, retrieved_at, vendor_latency_ms and tenant_reference. There is no idempotent_replay field on this route.
ImportantThe summary is a convenience projection. Read the complete readable/payer/full answer before treating qualifiers or source information as absent. Requested identity and visit date are not payer confirmation.
InfoPinned to 2026-10-01, the response is the check record, unchanged: request_id (string): Request id; outcome (string): OK for an answer, VENDOR_ERROR for a recorded vendor failure; error_class (string): Only on a failure record. The vendor error class, for example TIMEOUT; rejection (object): Only on a failure record. The payer's rejection in Claim House words: kind (FIX_AND_RESEND, PAYER_UNAVAILABLE or REJECTED), retry_later, a plain summary, and reasons (each with code, about, message, fix and field). Null when the payer gave no reason, for example after a timeout; eligibility_id (string): The check id, elg_.... A cache hit returns the original check's id; facility_id (string): The office the check was made for; payer_id (string): The payer id you sent; mode (string): The resolved mode. auto resolves to one of these before the call; relationship (string): The relationship requested on the check. It is not confirmation of the relationship in the payer response; service_date (date): Requested visit date, stored as request metadata. This field does not prove a date-specific payer query; procedure_codes (array): Array of strings. The procedure codes sent on the request, in the order sent (empty when none); idempotency_key (string): The Idempotency-Key this check was sent with. Sending the same body with this key again replays the check (idempotent_replay: true, header Idempotent-Replayed: true, no payer call). Your own organization's value; not on list rows; group_number (string): The subscriber group number sent on the request. Null when none was sent, or for a check recorded before requests were saved. Not the payer's plan.group_number; tenant_reference (string): Your reference. Null when you did not send one; status (string): Coverage status. UNKNOWN when not returned or not recognized; coverage (object): Coverage dates [effective_date (date): Coverage start. Null when not returned; termination_date (date): Coverage end. Null when not returned]; plan (object): Plan detail. Enhanced mode adds number, issuing_state and benefit_period [name (string): Plan name. Null when not returned; type (string): Plan type. Null when not returned; group_number (string): Group number. Null when not returned; number (string): Enhanced mode only. Plan number. Null when not returned; issuing_state (string): Enhanced mode only. Issuing state. Null when not returned; benefit_period (string): Enhanced mode only. Benefit period. Null when not returned]; network_status (string): Deprecated. Null in the attribution-only summary. Benefit-row network indicators do not establish provider participation; deductibles (array): Deductible benefit lines. Every item field may be null [section (string): Benefit section, for example deductibles. Null when not returned; network (string): Network, for example in_network. Null when not returned; category (string): Service category. Null when not returned; service_type (string): Service type. Null when not returned; coverage_level (string): Coverage level, for example individual or family. Null when not returned; plan_period (string): Plan period, for example calendar_year. Null when not returned; procedure_code (string): CDT code the line applies to. Null when not returned; insurance_type (string): Insurance type. Null when not returned; amount (string): Money amount as a decimal string. Null when not returned; remaining (string): Remaining amount as a decimal string. Null when not returned; used (string): Used amount as a decimal string. Null when not returned; percent (string): Percent as a decimal string. Null when not returned; description (string): Payer description. Null when not returned; start_date (date): Start date. Null when not returned; end_date (date): End date. Null when not returned]; maximums (array): Annual or lifetime maximum lines, same item shape as deductibles; coinsurance (array): Coinsurance lines, same item shape as deductibles; copayments (array): Copayment lines, same item shape as deductibles; not_covered (array): Not covered lines, same item shape as deductibles; frequency_limitations (array): Frequency convenience fields plus each original public row in as_sent. Preserve its scope, notes, quantity qualifiers and limitation structure [network (string): Network. Null when not returned; category (string): Service category. Null when not returned; service_type (string): Service type. Null when not returned; procedure_code (string): CDT code. Null when not returned; plan_period (string): Plan period. Null when not returned; quantity (string): Allowed quantity. Null when not returned; quantity_remaining (string): Quantity remaining. Null when not returned; quantity_used (string): Quantity used. Null when not returned; description (string): Payer description. Null when not returned; start_date (date): Start date. Null when not returned; end_date (date): End date. Null when not returned]; waiting_periods (array): Waiting periods [network (string): Network. Null when not returned; category (string): Service category. Null when not returned; service_type (string): Service type. Null when not returned; procedure_code (string): CDT code. Null when not returned; description (string): Payer description. Null when not returned; start_date (date): Start date. Null when not returned; end_date (date): End date. Null when not returned]; missing_tooth_clause (object): Missing tooth clause. Null when not returned [text (string): Payer text; applies (boolean): False only when the payer's text negates the clause]; downgrade_rules (array): Downgrade rules [text (string): Payer text; category (string): Service category; service_type (string): Service type; procedure_code (string): CDT code]; tooth_history (array): Prior services by tooth [tooth (string): Tooth; procedure_code (string): CDT code; service_date (date): Date of service; description (string): Payer description]; procedure_benefits (array): Enhanced mode only. Per code benefit detail: procedure_code, description, network, category, covered, coinsurance_percent, copayment, deductible_applies, frequency, age and waiting period fields, usage_count, remaining_usage, last_service_date, next_eligible_date, disclaimers; network_tiers (array): Enhanced mode only. Items carry network, status, description; coordination_of_benefits (object): Enhanced mode only. Carries other_coverage and description; eligibility_flags (array): Enhanced mode only. Items carry name, value, description; payer_notes (array): Enhanced mode only. Array of strings; disclaimers (array): Array of strings. Payer disclaimers; not_returned (array): Deprecated. Always an empty list for new answers. Use not_extracted; warnings (array): Array of strings. Parse warnings such as UNREADABLE_DATE or UNRECOGNIZED_COVERAGE_STATUS. They name the field, never the value; source (object): Where the answer came from [vendor (string): Always claimhouse. Kept so parsers that read it keep working; transaction_id (string): Vendor transaction id. Null when none was read]; retrieved_at (datetime): When the vendor call was made; vendor_latency_ms (integer): Vendor latency in milliseconds; cache (object): Whether this answer came from the cache [state (string): fresh for a live call, hit when served from cache; age_seconds (integer): Age of the cached answer. 0 when fresh]; billing (object): Whether this check is charged and why, read from its usage unit. Null only for a check recorded before usage metering began. The reasons are listed in the Pricing and what's charged guide [charged (boolean): Legacy ledger billability flag. True means BILLABLE; it does not prove invoice collection or a settled card payment; state (string): The unit's billable state; reason (string): Why, as a stable code: for example answered, payer_rejected_patient, payer_unavailable, cache_hit (a saved answer served again), test_mode or under_review; label (string): A short plain label for the reason; reason_label (string): One plain sentence saying whether and why the check is charged; unit_price_micros (integer): The price this check is rated at in its month so far, in micros (1 USD = 1,000,000): the tier its place in the month falls in. An estimate until the monthly statement is final. Null when not charged]; not_extracted (array): Summary fields Claim House did not extract into a convenience value. The payer may have sent that information: read the full answer (GET /v1/eligibility/{eligibility_id}/answer); source_notes (array): Literal payer notes retained by the summary. Review the complete answer for all source sections; relationship_source (string): request: relationship is what the caller requested; service_date_source (string): request: date is request information, not proof the payer queried that date.
API reference

Read the payer's answer

GEThttps://api.claimhouse.ai/v1/eligibility/{eligibility_id}/answer

The payer's whole answer to one check, organized: every row as one plain line, in the view you pick.

Returns contract eligibility.v3 by default (API version 2026-11-01). Every payer row appears exactly once as one line with one plain sentence holding every value; nothing is computed, merged or dropped. Reading an eligibility answer explains every block.

view picks the view: complete (the default; readable reads as complete), summary (whole lines selected from complete, never rewritten, with counts.complete_lines and counts.shown_lines), lines (one flat list, each line with its group, for spreadsheets) or payer (the payer's answer as received, transport metadata removed). fields= narrows a summary by block and CDT code, for example fields=totals,D1110; without it the office's saved setting applies, then the organization's, then the defaults (PUT /v1/settings/eligibility-summary).

contract=v2 still serves the earlier readable answer (contract eligibility.v2: view readable, payer or full), and it is the default under Claim-House-Version: 2026-10-01.

Fail closed: an answer whose truth checks did not pass is 409 ANSWER_NOT_VERIFIED with errors[0].verified: false and errors[0].payer_answer; view=payer still answers.

Each response carries an ETag. Send it back in If-None-Match and an unchanged answer is 304 Not Modified with no body. A 304 is still authorized and recorded as a read of the answer. Responses are never stored by a browser (Cache-Control: no-store).

Permission
read
Idempotency
none
Side effects
None. Read only. Every read, a 304 included, is recorded in the read audit.
In the dashboard
Eligibility > check > Benefits and Payer JSON

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret
If-None-MatchstringAn ETag from an earlier response for the same view. When it still matches, the answer is 304 Not Modified with no body.
e.g. "3f9a0c1d7e2b4a6c8d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e"

Path parameters

NameTypeDescription
eligibility_id*stringThe eligibility id returned by POST /v1/eligibility.
e.g. elg_EXAMPLE0000000000000001

Query parameters

NameTypeDescription
viewstringContract v3: complete (default), summary, lines or payer; readable reads as complete. Contract v2: readable (default), payer or full.
one of: complete · summary · lines · payer · readable · full
e.g. summary
contractstringv3 (the default under 2026-11-01) or v2 (the earlier readable answer; the default under 2026-10-01). eligibility.v3 and eligibility.v2 are accepted too. view=full needs contract=v2.
one of: v3 · v2 · eligibility.v3 · eligibility.v2
e.g. v3
fieldsstringWith view=summary only: a comma list of summary blocks and CDT codes, for example totals,D1110 (naming a code adds the procedures block). Blocks: plan, totals, deductibles, maximums, out_of_pocket, coinsurance, procedures, frequencies, history, not_covered, missing_tooth, waiting_periods. An unknown token is 422 INVALID_ELIGIBILITY_REQUEST with field: fields.
e.g. totals,D1110

Request example

null

Response fields

NameTypeDescription
id*stringThe check id, elg_.... A reused answer keeps the original check's id.
contract*stringAlways eligibility.v3.
one of: eligibility.v3
view*stringThe view served: complete (the default), summary, lines or payer.
one of: complete · summary · lines · payer
status*stringThe coverage status: active, inactive or unknown (not_answered only on a read of a check the payer did not answer).
one of: active · inactive · unknown · not_answered
checked_at*stringWhen the payer answered (ISO 8601).
verified*booleanTrue only when every truth check passed for this exact answer: every payer row is one line, every value is in its line unchanged, no number in a sentence that the payer did not send. False: the organized answer is withheld (no organized block is present) and links.payer_answer still answers.
unverified_reasonstringOnly with verified: false: why the organized answer is withheld.
office*objectThe office the check was made for: id and name.
payer*objectid and name are Claim House's directory entry. id_as_returned and name_as_returned are the payer's own words. Neither replaces the other.
patientobjectThe person being seen, exactly as the payer returned them (dates as YYYY-MM-DD when the payer sent a clean date). Fields the payer did not send are absent.
subscriberobjectThe policy holder as returned, when the payer returned one apart from the patient.
dependentsarrayOther people the payer listed.
as_requestedobjectWhat you sent (subscriber, patient, relationship, visit_date), with differences (fields the payer returned with another value) and not_returned (fields or a whole person you sent that the payer did not return). Never substituted for the payer's people.
planobjectPlan fields as the payer sent them (name, type, group_number, group_name, ...), coverage (status and each date under its own name: start, end, termination; plus the payer's active coverage rows as lines) and plan notes.
totalsobjectdeductibles, maximums and out_of_pocket: one line per payer row that names no procedure code, in payer order. A remaining amount is its own line with period: remaining.
by_servicearrayLines grouped by the payer's service type (service, label, lines) for rows that name no procedure code; service: not_stated when the payer named none.
by_procedurearrayEvery row that names a CDT code, grouped by code (code, code_as_sent, lines, history). Codes only, never procedure names. A row naming several codes is listed under each, with shared_with, and counted once.
historyarrayEvery service date the payer sent, newest first: code, type as sent, date, ref. A copy sits under each code.
not_coveredarrayThe payer's not covered rows, one line each.
notesarrayPayer notes and disclaimers that belong to no other line.
rejectionobjectThe payer's refusal details, when it sent them, with its rows as lines.
otherobjectAnything else the payer sent at the top level, verbatim.
missingarraySections an office usually expects that the payer did not send (deductible, maximums, coinsurance, limitations, not_covered, waiting_period).
not_readarrayFields kept verbatim under a line's other because Claim House does not organize them. Nothing is dropped.
labelsobjectPlain words for the payer tokens in this answer, by kind (network, level, period, service, ...).
counts*objectpayer_rows and lines (always equal), procedures, notes, history. A summary carries complete_lines and shown_lines instead.
excludedarrayPaths kept out on purpose (our own office identity echoed back, the network's computed summaries, social security numbers); their values are never shown.
links*objectcomplete, summary, lines, payer_answer and pdf: where each view of this answer is read.
summaryobjectSummary view: the blocks and procedures shown and the source of each choice (request, office, organization or default).
linesarrayLines view: every line once, each with its group (for example by_procedure/D1110) and its group key.
payer_answerobjectPayer view: the payer's answer as received.

Responses

200OK: the complete answer (executed test check, synthetic patient and ids)
{
  "livemode": false,
  "request_id": "evt_aszh2ntab12qze3beasn",
  "id": "elg_ztnbv2mkpn10d0qxy1yj",
  "contract": "eligibility.v3",
  "view": "complete",
  "status": "active",
  "checked_at": "2026-09-07T15:00:00+00:00",
  "verified": true,
  "office": {
    "id": "fac_sandboxbatchsandbx",
    "name": "fac_sandboxbatchsandbx"
  },
  "payer": {
    "id": "94276",
    "name": "Delta Dental",
    "id_as_returned": "94276",
    "name_as_returned": "Delta Dental"
  },
  "patient": {
    "date_of_birth": "1970-01-10",
    "first_name": "AVERY",
    "last_name": "MOLAR",
    "member_id": "CH-ACTIVE-RICH",
    "relationship": "self"
  },
  "as_requested": {
    "subscriber": {
      "first_name": "Avery",
      "last_name": "Molar",
      "date_of_birth": "1970-01-10",
      "member_id": "CH-ACTIVE-RICH"
    },
    "relationship": "self",
    "visit_date": "2026-09-07",
    "differences": [],
    "not_returned": [
      "subscriber"
    ]
  },
  "plan": {
    "group_number": "TESTGRP1",
    "insurance_type": "ppo",
    "name": "Delta Dental PPO",
    "coverage": {
      "start": "2026-01-01",
      "status": "active",
      "termination": "2026-12-31",
      "lines": [
        {
          "kind": "active_coverage",
          "network": "in_network",
          "insurance_type": "group_policy",
          "text": "In network, group policy: active coverage",
          "ref": "active_coverage[0]"
        }
      ]
    }
  },
  "totals": {
    "deductibles": [
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "individual",
        "period": "calendar",
        "service": "dental_care",
        "amount": "50.00",
        "text": "Dental care (general), in network, individual, calendar year: deductible $50.00",
        "ref": "deductible[0]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "individual",
        "period": "remaining",
        "service": "dental_care",
        "amount": "25.00",
        "text": "Dental care (general), in network, individual, remaining: deductible $25.00",
        "ref": "deductible[1]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "family",
        "period": "calendar",
        "service": "dental_care",
        "amount": "150.00",
        "text": "Dental care (general), in network, family, calendar year: deductible $150.00",
        "ref": "deductible[2]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "family",
        "period": "remaining",
        "service": "dental_care",
        "amount": "150.00",
        "text": "Dental care (general), in network, family, remaining: deductible $150.00",
        "ref": "deductible[3]"
      }
    ],
    "maximums": [
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "calendar",
        "service": "dental_care",
        "amount": "1500.00",
        "text": "Dental care (general), in network, individual, calendar year: maximum $1500.00",
        "ref": "maximums[0]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "remaining",
        "service": "dental_care",
        "amount": "1200.00",
        "text": "Dental care (general), in network, individual, remaining: maximum $1200.00",
        "ref": "maximums[1]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "lifetime",
        "service": "orthodontics",
        "amount": "1500.00",
        "text": "Orthodontics, in network, individual, lifetime: maximum $1500.00",
        "ref": "maximums[2]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "lifetime_remaining",
        "service": "orthodontics",
        "amount": "1500.00",
        "text": "Orthodontics, in network, individual, lifetime remaining: maximum $1500.00",
        "ref": "maximums[3]"
      }
    ]
  },
  "by_service": [
    {
      "service": "preventive",
      "label": "Preventive care",
      "lines": [
        {
          "kind": "coinsurance",
          "network": "in_network",
          "percent": 100,
          "text": "Preventive care, in network: coinsurance 100%",
          "ref": "coinsurance[0]"
        }
      ]
    },
    {
      "service": "restorative",
      "label": "Restorative (fillings)",
      "lines": [
        {
          "kind": "coinsurance",
          "network": "in_network",
          "percent": 80,
          "text": "Restorative (fillings), in network: coinsurance 80%",
          "ref": "coinsurance[1]"
        }
      ]
    },
    {
      "service": "dental_crowns",
      "label": "Crowns",
      "lines": [
        {
          "kind": "coinsurance",
          "network": "in_network",
          "percent": 50,
          "text": "Crowns, in network: coinsurance 50%",
          "ref": "coinsurance[2]"
        }
      ]
    }
  ],
  "by_procedure": [
    {
      "code": "D0120",
      "code_as_sent": "AD:D0120",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "2 visits in 1 calendar",
          "frequency": [
            {
              "quantity": "2",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "calendar",
              "time_period_value": "1"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D0120, all networks, individual: limitation 2 visits in 1 calendar (frequency 2 visits per calendar year; last visit 03/14/2026)",
          "ref": "limitations[0]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 units remaining",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D0120, all networks, individual: limitation 1 units remaining (frequency 1 units, time period remaining; last visit 03/14/2026)",
          "ref": "limitations[1]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2026-03-14",
          "ref": "limitations[0].service_dates[0]"
        },
        {
          "type": "latest_visit_or_consultation",
          "date": "2026-03-14",
          "ref": "limitations[1].service_dates[0]"
        }
      ]
    },
    {
      "code": "D0150",
      "code_as_sent": "AD:D0150",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 visits in 36 month",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "month",
              "time_period_value": "36"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "05/20/2024",
              "service_date": "05/20/2024",
              "type": "latest_visit_or_consultation",
              "value": "05/20/2024"
            }
          ],
          "text": "D0150, all networks, individual: limitation 1 visits in 36 month (frequency 1 visits per 36 months; last visit 05/20/2024)",
          "ref": "limitations[2]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2024-05-20",
          "ref": "limitations[2].service_dates[0]"
        }
      ]
    },
    {
      "code": "D0274",
      "code_as_sent": "AD:D0274",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 visits in 12 month",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "month",
              "time_period_value": "12"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D0274, all networks, individual: limitation 1 visits in 12 month (frequency 1 visits per 12 months; last visit 03/14/2026)",
          "ref": "limitations[3]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "0 units remaining",
          "frequency": [
            {
              "quantity": "0",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D0274, all networks, individual: limitation 0 units remaining (frequency 0 units, time period remaining; last visit 03/14/2026)",
          "ref": "limitations[4]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2026-03-14",
          "ref": "limitations[3].service_dates[0]"
        },
        {
          "type": "latest_visit_or_consultation",
          "date": "2026-03-14",
          "ref": "limitations[4].service_dates[0]"
        }
      ]
    },
    {
      "code": "D0330",
      "code_as_sent": "AD:D0330",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 visits in 60 month",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "month",
              "time_period_value": "60"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "06/02/2022",
              "service_date": "06/02/2022",
              "type": "latest_visit_or_consultation",
              "value": "06/02/2022"
            }
          ],
          "text": "D0330, all networks, individual: limitation 1 visits in 60 month (frequency 1 visits per 60 months; last visit 06/02/2022)",
          "ref": "limitations[5]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2022-06-02",
          "ref": "limitations[5].service_dates[0]"
        }
      ]
    },
    {
      "code": "D1110",
      "code_as_sent": "AD:D1110",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "2 visits in 1 calendar",
          "frequency": [
            {
              "quantity": "2",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "calendar",
              "time_period_value": "1"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D1110, all networks, individual: limitation 2 visits in 1 calendar (frequency 2 visits per calendar year; last visit 03/14/2026)",
          "ref": "limitations[6]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 units remaining",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D1110, all networks, individual: limitation 1 units remaining (frequency 1 units, time period remaining; last visit 03/14/2026)",
          "ref": "limitations[7]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2026-03-14",
          "ref": "limitations[6].service_dates[0]"
        },
        {
          "type": "latest_visit_or_consultation",
          "date": "2026-03-14",
          "ref": "limitations[7].service_dates[0]"
        }
      ]
    },
    {
      "code": "D1206",
      "code_as_sent": "AD:D1206",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "2 visits in 1 calendar",
          "frequency": [
            {
              "quantity": "2",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "calendar",
              "time_period_value": "1"
            }
          ],
          "text": "D1206, all networks, individual: limitation 2 visits in 1 calendar (frequency 2 visits per calendar year)",
          "ref": "limitations[8]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "quantity": "19",
          "quantity_unit": "age_high_value",
          "age": {
            "age_high_value": "19"
          },
          "text": "D1206, all networks, individual: limitation (quantity 19 maximum age; through age 19)",
          "ref": "limitations[9]"
        }
      ]
    },
    {
      "code": "D2391",
      "code_as_sent": "AD:D2391",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 visits in 24 month",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "month",
              "time_period_value": "24"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "01/17/2025",
              "service_date": "01/17/2025",
              "type": "latest_visit_or_consultation",
              "value": "01/17/2025"
            }
          ],
          "note": "Per surface. Last service on tooth 30",
          "text": "D2391, all networks, individual: limitation 1 visits in 24 month (frequency 1 visits per 24 months; last visit 01/17/2025; payer note: Per surface. Last service on tooth 30)",
          "ref": "limitations[13]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2025-01-17",
          "ref": "limitations[13].service_dates[0]"
        }
      ]
    },
    {
      "code": "D2740",
      "code_as_sent": "AD:D2740",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 visits in 60 month",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "month",
              "time_period_value": "60"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "04/11/2021",
              "service_date": "04/11/2021",
              "type": "latest_visit_or_consultation",
              "value": "04/11/2021"
            }
          ],
          "note": "Per tooth. Last service on tooth 3",
          "text": "D2740, all networks, individual: limitation 1 visits in 60 month (frequency 1 visits per 60 months; last visit 04/11/2021; payer note: Per tooth. Last service on tooth 3)",
          "ref": "limitations[11]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2021-04-11",
          "ref": "limitations[11].service_dates[0]"
        }
      ]
    },
    {
      "code": "D3330",
      "code_as_sent": "AD:D3330",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 visits in lifetime",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "lifetime"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "08/09/2023",
              "service_date": "08/09/2023",
              "type": "latest_visit_or_consultation",
              "value": "08/09/2023"
            }
          ],
          "note": "Per tooth. Last service on tooth 19",
          "text": "D3330, all networks, individual: limitation 1 visits in lifetime (frequency 1 visits per lifetime; last visit 08/09/2023; payer note: Per tooth. Last service on tooth 19)",
          "ref": "limitations[12]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2023-08-09",
          "ref": "limitations[12].service_dates[0]"
        }
      ]
    },
    {
      "code": "D4910",
      "code_as_sent": "AD:D4910",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "4 visits in 1 calendar",
          "frequency": [
            {
              "quantity": "4",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "calendar",
              "time_period_value": "1"
            }
          ],
          "text": "D4910, all networks, individual: limitation 4 visits in 1 calendar (frequency 4 visits per calendar year)",
          "ref": "limitations[10]"
        }
      ]
    }
  ],
  "history": [
    {
      "code": "D0120",
      "type": "latest_visit_or_consultation",
      "date": "2026-03-14",
      "ref": "limitations[0].service_dates[0]"
    },
    {
      "code": "D0120",
      "type": "latest_visit_or_consultation",
      "date": "2026-03-14",
      "ref": "limitations[1].service_dates[0]"
    },
    {
      "code": "D0274",
      "type": "latest_visit_or_consultation",
      "date": "2026-03-14",
      "ref": "limitations[3].service_dates[0]"
    },
    {
      "code": "D0274",
      "type": "latest_visit_or_consultation",
      "date": "2026-03-14",
      "ref": "limitations[4].service_dates[0]"
    },
    {
      "code": "D1110",
      "type": "latest_visit_or_consultation",
      "date": "2026-03-14",
      "ref": "limitations[6].service_dates[0]"
    },
    {
      "code": "D1110",
      "type": "latest_visit_or_consultation",
      "date": "2026-03-14",
      "ref": "limitations[7].service_dates[0]"
    },
    {
      "code": "D2391",
      "type": "latest_visit_or_consultation",
      "date": "2025-01-17",
      "ref": "limitations[13].service_dates[0]"
    },
    {
      "code": "D0150",
      "type": "latest_visit_or_consultation",
      "date": "2024-05-20",
      "ref": "limitations[2].service_dates[0]"
    },
    {
      "code": "D3330",
      "type": "latest_visit_or_consultation",
      "date": "2023-08-09",
      "ref": "limitations[12].service_dates[0]"
    },
    {
      "code": "D0330",
      "type": "latest_visit_or_consultation",
      "date": "2022-06-02",
      "ref": "limitations[5].service_dates[0]"
    },
    {
      "code": "D2740",
      "type": "latest_visit_or_consultation",
      "date": "2021-04-11",
      "ref": "limitations[11].service_dates[0]"
    }
  ],
  "missing": [
    "not_covered",
    "waiting_period"
  ],
  "not_read": [],
  "labels": {
    "network": {
      "applies_all": "All networks",
      "in_network": "In network"
    },
    "level": {
      "family": "Family",
      "individual": "Individual"
    },
    "period": {
      "calendar": "Calendar year",
      "lifetime": "Lifetime",
      "lifetime_remaining": "Lifetime remaining",
      "remaining": "Remaining"
    },
    "service": {
      "dental_care": "Dental care (general)",
      "dental_crowns": "Crowns",
      "orthodontics": "Orthodontics",
      "preventive": "Preventive care",
      "restorative": "Restorative (fillings)"
    },
    "quantity_unit": {
      "age_high_value": "maximum age"
    },
    "insurance_type": {
      "group_policy": "Group policy",
      "ppo": "PPO"
    }
  },
  "counts": {
    "payer_rows": 26,
    "lines": 26,
    "procedures": 10,
    "notes": 0,
    "history": 11
  },
  "links": {
    "complete": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3",
    "summary": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3&view=summary",
    "lines": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3&view=lines",
    "payer_answer": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?view=payer",
    "pdf": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/pdf"
  }
}
200view=summary with the default blocks and codes
{
  "livemode": false,
  "request_id": "evt_0d0m0q422d48x640j3eq",
  "id": "elg_ztnbv2mkpn10d0qxy1yj",
  "contract": "eligibility.v3",
  "view": "summary",
  "status": "active",
  "checked_at": "2026-09-07T15:00:00+00:00",
  "verified": true,
  "office": {
    "id": "fac_sandboxbatchsandbx",
    "name": "fac_sandboxbatchsandbx"
  },
  "payer": {
    "id": "94276",
    "name": "Delta Dental",
    "id_as_returned": "94276",
    "name_as_returned": "Delta Dental"
  },
  "patient": {
    "date_of_birth": "1970-01-10",
    "first_name": "AVERY",
    "last_name": "MOLAR",
    "member_id": "CH-ACTIVE-RICH",
    "relationship": "self"
  },
  "as_requested": {
    "subscriber": {
      "first_name": "Avery",
      "last_name": "Molar",
      "date_of_birth": "1970-01-10",
      "member_id": "CH-ACTIVE-RICH"
    },
    "relationship": "self",
    "visit_date": "2026-09-07",
    "differences": [],
    "not_returned": [
      "subscriber"
    ]
  },
  "plan": {
    "group_number": "TESTGRP1",
    "insurance_type": "ppo",
    "name": "Delta Dental PPO",
    "coverage": {
      "start": "2026-01-01",
      "status": "active",
      "termination": "2026-12-31",
      "lines": [
        {
          "kind": "active_coverage",
          "network": "in_network",
          "insurance_type": "group_policy",
          "text": "In network, group policy: active coverage",
          "ref": "active_coverage[0]"
        }
      ]
    }
  },
  "totals": {
    "deductibles": [
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "individual",
        "period": "calendar",
        "service": "dental_care",
        "amount": "50.00",
        "text": "Dental care (general), in network, individual, calendar year: deductible $50.00",
        "ref": "deductible[0]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "individual",
        "period": "remaining",
        "service": "dental_care",
        "amount": "25.00",
        "text": "Dental care (general), in network, individual, remaining: deductible $25.00",
        "ref": "deductible[1]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "family",
        "period": "calendar",
        "service": "dental_care",
        "amount": "150.00",
        "text": "Dental care (general), in network, family, calendar year: deductible $150.00",
        "ref": "deductible[2]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "family",
        "period": "remaining",
        "service": "dental_care",
        "amount": "150.00",
        "text": "Dental care (general), in network, family, remaining: deductible $150.00",
        "ref": "deductible[3]"
      }
    ],
    "maximums": [
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "calendar",
        "service": "dental_care",
        "amount": "1500.00",
        "text": "Dental care (general), in network, individual, calendar year: maximum $1500.00",
        "ref": "maximums[0]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "remaining",
        "service": "dental_care",
        "amount": "1200.00",
        "text": "Dental care (general), in network, individual, remaining: maximum $1200.00",
        "ref": "maximums[1]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "lifetime",
        "service": "orthodontics",
        "amount": "1500.00",
        "text": "Orthodontics, in network, individual, lifetime: maximum $1500.00",
        "ref": "maximums[2]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "lifetime_remaining",
        "service": "orthodontics",
        "amount": "1500.00",
        "text": "Orthodontics, in network, individual, lifetime remaining: maximum $1500.00",
        "ref": "maximums[3]"
      }
    ]
  },
  "by_service": [
    {
      "service": "preventive",
      "label": "Preventive care",
      "lines": [
        {
          "kind": "coinsurance",
          "network": "in_network",
          "percent": 100,
          "text": "Preventive care, in network: coinsurance 100%",
          "ref": "coinsurance[0]"
        }
      ]
    },
    {
      "service": "restorative",
      "label": "Restorative (fillings)",
      "lines": [
        {
          "kind": "coinsurance",
          "network": "in_network",
          "percent": 80,
          "text": "Restorative (fillings), in network: coinsurance 80%",
          "ref": "coinsurance[1]"
        }
      ]
    },
    {
      "service": "dental_crowns",
      "label": "Crowns",
      "lines": [
        {
          "kind": "coinsurance",
          "network": "in_network",
          "percent": 50,
          "text": "Crowns, in network: coinsurance 50%",
          "ref": "coinsurance[2]"
        }
      ]
    }
  ],
  "by_procedure": [
    {
      "code": "D0120",
      "code_as_sent": "AD:D0120",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "2 visits in 1 calendar",
          "frequency": [
            {
              "quantity": "2",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "calendar",
              "time_period_value": "1"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D0120, all networks, individual: limitation 2 visits in 1 calendar (frequency 2 visits per calendar year; last visit 03/14/2026)",
          "ref": "limitations[0]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 units remaining",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D0120, all networks, individual: limitation 1 units remaining (frequency 1 units, time period remaining; last visit 03/14/2026)",
          "ref": "limitations[1]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2026-03-14",
          "ref": "limitations[0].service_dates[0]"
        },
        {
          "type": "latest_visit_or_consultation",
          "date": "2026-03-14",
          "ref": "limitations[1].service_dates[0]"
        }
      ]
    },
    {
      "code": "D0150",
      "code_as_sent": "AD:D0150",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 visits in 36 month",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "month",
              "time_period_value": "36"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "05/20/2024",
              "service_date": "05/20/2024",
              "type": "latest_visit_or_consultation",
              "value": "05/20/2024"
            }
          ],
          "text": "D0150, all networks, individual: limitation 1 visits in 36 month (frequency 1 visits per 36 months; last visit 05/20/2024)",
          "ref": "limitations[2]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2024-05-20",
          "ref": "limitations[2].service_dates[0]"
        }
      ]
    },
    {
      "code": "D0274",
      "code_as_sent": "AD:D0274",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 visits in 12 month",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "month",
              "time_period_value": "12"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D0274, all networks, individual: limitation 1 visits in 12 month (frequency 1 visits per 12 months; last visit 03/14/2026)",
          "ref": "limitations[3]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "0 units remaining",
          "frequency": [
            {
              "quantity": "0",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D0274, all networks, individual: limitation 0 units remaining (frequency 0 units, time period remaining; last visit 03/14/2026)",
          "ref": "limitations[4]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2026-03-14",
          "ref": "limitations[3].service_dates[0]"
        },
        {
          "type": "latest_visit_or_consultation",
          "date": "2026-03-14",
          "ref": "limitations[4].service_dates[0]"
        }
      ]
    },
    {
      "code": "D0330",
      "code_as_sent": "AD:D0330",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 visits in 60 month",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "month",
              "time_period_value": "60"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "06/02/2022",
              "service_date": "06/02/2022",
              "type": "latest_visit_or_consultation",
              "value": "06/02/2022"
            }
          ],
          "text": "D0330, all networks, individual: limitation 1 visits in 60 month (frequency 1 visits per 60 months; last visit 06/02/2022)",
          "ref": "limitations[5]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2022-06-02",
          "ref": "limitations[5].service_dates[0]"
        }
      ]
    },
    {
      "code": "D1110",
      "code_as_sent": "AD:D1110",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "2 visits in 1 calendar",
          "frequency": [
            {
              "quantity": "2",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "calendar",
              "time_period_value": "1"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D1110, all networks, individual: limitation 2 visits in 1 calendar (frequency 2 visits per calendar year; last visit 03/14/2026)",
          "ref": "limitations[6]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 units remaining",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D1110, all networks, individual: limitation 1 units remaining (frequency 1 units, time period remaining; last visit 03/14/2026)",
          "ref": "limitations[7]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2026-03-14",
          "ref": "limitations[6].service_dates[0]"
        },
        {
          "type": "latest_visit_or_consultation",
          "date": "2026-03-14",
          "ref": "limitations[7].service_dates[0]"
        }
      ]
    },
    {
      "code": "D1206",
      "code_as_sent": "AD:D1206",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "2 visits in 1 calendar",
          "frequency": [
            {
              "quantity": "2",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "calendar",
              "time_period_value": "1"
            }
          ],
          "text": "D1206, all networks, individual: limitation 2 visits in 1 calendar (frequency 2 visits per calendar year)",
          "ref": "limitations[8]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "quantity": "19",
          "quantity_unit": "age_high_value",
          "age": {
            "age_high_value": "19"
          },
          "text": "D1206, all networks, individual: limitation (quantity 19 maximum age; through age 19)",
          "ref": "limitations[9]"
        }
      ]
    },
    {
      "code": "D2740",
      "code_as_sent": "AD:D2740",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 visits in 60 month",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "month",
              "time_period_value": "60"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "04/11/2021",
              "service_date": "04/11/2021",
              "type": "latest_visit_or_consultation",
              "value": "04/11/2021"
            }
          ],
          "note": "Per tooth. Last service on tooth 3",
          "text": "D2740, all networks, individual: limitation 1 visits in 60 month (frequency 1 visits per 60 months; last visit 04/11/2021; payer note: Per tooth. Last service on tooth 3)",
          "ref": "limitations[11]"
        }
      ],
      "history": [
        {
          "type": "latest_visit_or_consultation",
          "date": "2021-04-11",
          "ref": "limitations[11].service_dates[0]"
        }
      ]
    },
    {
      "code": "D4910",
      "code_as_sent": "AD:D4910",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "4 visits in 1 calendar",
          "frequency": [
            {
              "quantity": "4",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "calendar",
              "time_period_value": "1"
            }
          ],
          "text": "D4910, all networks, individual: limitation 4 visits in 1 calendar (frequency 4 visits per calendar year)",
          "ref": "limitations[10]"
        }
      ]
    }
  ],
  "history": [
    {
      "code": "D0120",
      "type": "latest_visit_or_consultation",
      "date": "2026-03-14",
      "ref": "limitations[0].service_dates[0]"
    },
    {
      "code": "D0120",
      "type": "latest_visit_or_consultation",
      "date": "2026-03-14",
      "ref": "limitations[1].service_dates[0]"
    },
    {
      "code": "D0274",
      "type": "latest_visit_or_consultation",
      "date": "2026-03-14",
      "ref": "limitations[3].service_dates[0]"
    },
    {
      "code": "D0274",
      "type": "latest_visit_or_consultation",
      "date": "2026-03-14",
      "ref": "limitations[4].service_dates[0]"
    },
    {
      "code": "D1110",
      "type": "latest_visit_or_consultation",
      "date": "2026-03-14",
      "ref": "limitations[6].service_dates[0]"
    },
    {
      "code": "D1110",
      "type": "latest_visit_or_consultation",
      "date": "2026-03-14",
      "ref": "limitations[7].service_dates[0]"
    },
    {
      "code": "D0150",
      "type": "latest_visit_or_consultation",
      "date": "2024-05-20",
      "ref": "limitations[2].service_dates[0]"
    },
    {
      "code": "D0330",
      "type": "latest_visit_or_consultation",
      "date": "2022-06-02",
      "ref": "limitations[5].service_dates[0]"
    },
    {
      "code": "D2740",
      "type": "latest_visit_or_consultation",
      "date": "2021-04-11",
      "ref": "limitations[11].service_dates[0]"
    }
  ],
  "missing": [
    "not_covered",
    "waiting_period"
  ],
  "not_read": [],
  "labels": {
    "network": {
      "applies_all": "All networks",
      "in_network": "In network"
    },
    "level": {
      "family": "Family",
      "individual": "Individual"
    },
    "period": {
      "calendar": "Calendar year",
      "lifetime": "Lifetime",
      "lifetime_remaining": "Lifetime remaining",
      "remaining": "Remaining"
    },
    "service": {
      "dental_care": "Dental care (general)",
      "dental_crowns": "Crowns",
      "orthodontics": "Orthodontics",
      "preventive": "Preventive care",
      "restorative": "Restorative (fillings)"
    },
    "quantity_unit": {
      "age_high_value": "maximum age"
    },
    "insurance_type": {
      "group_policy": "Group policy",
      "ppo": "PPO"
    }
  },
  "counts": {
    "complete_lines": 26,
    "shown_lines": 24
  },
  "summary": {
    "blocks": [
      "plan",
      "totals",
      "deductibles",
      "maximums",
      "out_of_pocket",
      "coinsurance",
      "procedures",
      "frequencies",
      "history",
      "not_covered",
      "missing_tooth",
      "waiting_periods"
    ],
    "procedures": [
      "D0120",
      "D0140",
      "D0150",
      "D0210",
      "D0220",
      "D0272",
      "D0274",
      "D0330",
      "D1110",
      "D1120",
      "D1206",
      "D1208",
      "D4341",
      "D4342",
      "D4910",
      "D2740",
      "D2750",
      "D7140",
      "D7210"
    ],
    "source": {
      "blocks": "default",
      "procedures": "default"
    }
  },
  "links": {
    "complete": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3",
    "summary": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3&view=summary",
    "lines": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3&view=lines",
    "payer_answer": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?view=payer",
    "pdf": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/pdf"
  }
}
200view=summary, fields totals and D1110
{
  "livemode": false,
  "request_id": "evt_phrq6w0hes6q5ej9fvcv",
  "id": "elg_ztnbv2mkpn10d0qxy1yj",
  "contract": "eligibility.v3",
  "view": "summary",
  "status": "active",
  "checked_at": "2026-09-07T15:00:00+00:00",
  "verified": true,
  "office": {
    "id": "fac_sandboxbatchsandbx",
    "name": "fac_sandboxbatchsandbx"
  },
  "payer": {
    "id": "94276",
    "name": "Delta Dental",
    "id_as_returned": "94276",
    "name_as_returned": "Delta Dental"
  },
  "patient": {
    "date_of_birth": "1970-01-10",
    "first_name": "AVERY",
    "last_name": "MOLAR",
    "member_id": "CH-ACTIVE-RICH",
    "relationship": "self"
  },
  "as_requested": {
    "subscriber": {
      "first_name": "Avery",
      "last_name": "Molar",
      "date_of_birth": "1970-01-10",
      "member_id": "CH-ACTIVE-RICH"
    },
    "relationship": "self",
    "visit_date": "2026-09-07",
    "differences": [],
    "not_returned": [
      "subscriber"
    ]
  },
  "totals": {
    "deductibles": [
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "individual",
        "period": "calendar",
        "service": "dental_care",
        "amount": "50.00",
        "text": "Dental care (general), in network, individual, calendar year: deductible $50.00",
        "ref": "deductible[0]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "individual",
        "period": "remaining",
        "service": "dental_care",
        "amount": "25.00",
        "text": "Dental care (general), in network, individual, remaining: deductible $25.00",
        "ref": "deductible[1]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "family",
        "period": "calendar",
        "service": "dental_care",
        "amount": "150.00",
        "text": "Dental care (general), in network, family, calendar year: deductible $150.00",
        "ref": "deductible[2]"
      },
      {
        "kind": "deductible",
        "network": "in_network",
        "level": "family",
        "period": "remaining",
        "service": "dental_care",
        "amount": "150.00",
        "text": "Dental care (general), in network, family, remaining: deductible $150.00",
        "ref": "deductible[3]"
      }
    ],
    "maximums": [
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "calendar",
        "service": "dental_care",
        "amount": "1500.00",
        "text": "Dental care (general), in network, individual, calendar year: maximum $1500.00",
        "ref": "maximums[0]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "remaining",
        "service": "dental_care",
        "amount": "1200.00",
        "text": "Dental care (general), in network, individual, remaining: maximum $1200.00",
        "ref": "maximums[1]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "lifetime",
        "service": "orthodontics",
        "amount": "1500.00",
        "text": "Orthodontics, in network, individual, lifetime: maximum $1500.00",
        "ref": "maximums[2]"
      },
      {
        "kind": "maximum",
        "network": "in_network",
        "level": "individual",
        "period": "lifetime_remaining",
        "service": "orthodontics",
        "amount": "1500.00",
        "text": "Orthodontics, in network, individual, lifetime remaining: maximum $1500.00",
        "ref": "maximums[3]"
      }
    ]
  },
  "by_procedure": [
    {
      "code": "D1110",
      "code_as_sent": "AD:D1110",
      "lines": [
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "2 visits in 1 calendar",
          "frequency": [
            {
              "quantity": "2",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "calendar",
              "time_period_value": "1"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D1110, all networks, individual: limitation 2 visits in 1 calendar (frequency 2 visits per calendar year; last visit 03/14/2026)",
          "ref": "limitations[6]"
        },
        {
          "kind": "limitation",
          "network": "applies_all",
          "level": "individual",
          "limit": "1 units remaining",
          "frequency": [
            {
              "quantity": "1",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "service_dates": [
            {
              "latest_visit_or_consultation": "03/14/2026",
              "service_date": "03/14/2026",
              "type": "latest_visit_or_consultation",
              "value": "03/14/2026"
            }
          ],
          "text": "D1110, all networks, individual: limitation 1 units remaining (frequency 1 units, time period remaining; last visit 03/14/2026)",
          "ref": "limitations[7]"
        }
      ]
    }
  ],
  "missing": [
    "not_covered",
    "waiting_period"
  ],
  "not_read": [],
  "labels": {
    "network": {
      "applies_all": "All networks",
      "in_network": "In network"
    },
    "level": {
      "family": "Family",
      "individual": "Individual"
    },
    "period": {
      "calendar": "Calendar year",
      "lifetime": "Lifetime",
      "lifetime_remaining": "Lifetime remaining",
      "remaining": "Remaining"
    },
    "service": {
      "dental_care": "Dental care (general)",
      "dental_crowns": "Crowns",
      "orthodontics": "Orthodontics",
      "preventive": "Preventive care",
      "restorative": "Restorative (fillings)"
    },
    "quantity_unit": {
      "age_high_value": "maximum age"
    },
    "insurance_type": {
      "group_policy": "Group policy",
      "ppo": "PPO"
    }
  },
  "counts": {
    "complete_lines": 26,
    "shown_lines": 10
  },
  "summary": {
    "blocks": [
      "totals",
      "procedures"
    ],
    "procedures": [
      "D1110"
    ],
    "source": {
      "blocks": "request",
      "procedures": "request"
    }
  },
  "links": {
    "complete": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3",
    "summary": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3&view=summary",
    "lines": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3&view=lines",
    "payer_answer": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?view=payer",
    "pdf": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/pdf"
  }
}
200view=lines (excerpt: the first five lines)
{
  "livemode": false,
  "request_id": "evt_tbs7v8wmax6mdf7y0c0m",
  "id": "elg_ztnbv2mkpn10d0qxy1yj",
  "contract": "eligibility.v3",
  "view": "lines",
  "status": "active",
  "checked_at": "2026-09-07T15:00:00+00:00",
  "verified": true,
  "office": {
    "id": "fac_sandboxbatchsandbx",
    "name": "fac_sandboxbatchsandbx"
  },
  "payer": {
    "id": "94276",
    "name": "Delta Dental",
    "id_as_returned": "94276",
    "name_as_returned": "Delta Dental"
  },
  "missing": [
    "not_covered",
    "waiting_period"
  ],
  "not_read": [],
  "labels": {
    "network": {
      "applies_all": "All networks",
      "in_network": "In network"
    },
    "level": {
      "family": "Family",
      "individual": "Individual"
    },
    "period": {
      "calendar": "Calendar year",
      "lifetime": "Lifetime",
      "lifetime_remaining": "Lifetime remaining",
      "remaining": "Remaining"
    },
    "service": {
      "dental_care": "Dental care (general)",
      "dental_crowns": "Crowns",
      "orthodontics": "Orthodontics",
      "preventive": "Preventive care",
      "restorative": "Restorative (fillings)"
    },
    "quantity_unit": {
      "age_high_value": "maximum age"
    },
    "insurance_type": {
      "group_policy": "Group policy",
      "ppo": "PPO"
    }
  },
  "counts": {
    "payer_rows": 26,
    "lines": 26,
    "procedures": 10,
    "notes": 0,
    "history": 11
  },
  "links": {
    "complete": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3",
    "summary": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3&view=summary",
    "lines": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?contract=v3&view=lines",
    "payer_answer": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/answer?view=payer",
    "pdf": "/v1/eligibility/elg_ztnbv2mkpn10d0qxy1yj/pdf"
  },
  "lines": [
    {
      "group": "plan.coverage",
      "kind": "active_coverage",
      "network": "in_network",
      "insurance_type": "group_policy",
      "text": "In network, group policy: active coverage",
      "ref": "active_coverage[0]"
    },
    {
      "group": "totals.deductibles",
      "kind": "deductible",
      "network": "in_network",
      "level": "individual",
      "period": "calendar",
      "service": "dental_care",
      "amount": "50.00",
      "text": "Dental care (general), in network, individual, calendar year: deductible $50.00",
      "ref": "deductible[0]"
    },
    {
      "group": "totals.deductibles",
      "kind": "deductible",
      "network": "in_network",
      "level": "individual",
      "period": "remaining",
      "service": "dental_care",
      "amount": "25.00",
      "text": "Dental care (general), in network, individual, remaining: deductible $25.00",
      "ref": "deductible[1]"
    },
    {
      "group": "totals.deductibles",
      "kind": "deductible",
      "network": "in_network",
      "level": "family",
      "period": "calendar",
      "service": "dental_care",
      "amount": "150.00",
      "text": "Dental care (general), in network, family, calendar year: deductible $150.00",
      "ref": "deductible[2]"
    },
    {
      "group": "totals.deductibles",
      "kind": "deductible",
      "network": "in_network",
      "level": "family",
      "period": "remaining",
      "service": "dental_care",
      "amount": "150.00",
      "text": "Dental care (general), in network, family, remaining: deductible $150.00",
      "ref": "deductible[3]"
    }
  ]
}
200contract=v2: the earlier readable answer (executed)
{
  "livemode": false,
  "request_id": "evt_b6v72egepn1wfezfex4d",
  "facility_id": "fac_sandboxbatchsandbx",
  "payer_id": "94276",
  "retrieved_at": "2026-09-07T15:00:00+00:00",
  "service_date": "2026-09-07",
  "service_date_source": "request",
  "requested": {
    "subscriber": {
      "date_of_birth": "1980-01-01",
      "first_name": "Test",
      "group_number": null,
      "last_name": "Patient",
      "member_id": "CH-ACTIVE-FULL",
      "relationship": null
    },
    "patient": {
      "date_of_birth": "1980-01-01",
      "first_name": "Test",
      "group_number": null,
      "last_name": "Patient",
      "member_id": "CH-ACTIVE-FULL",
      "relationship": "self"
    }
  },
  "eligibility_id": "elg_9aqbap922506q92gx9ge",
  "office": "fac_sandboxbatchsandbx",
  "contract": "eligibility.v2",
  "excluded": [],
  "format_rules": {
    "F1": "quantity q, period p, value n -> 'q per p' (n = 1) or 'q per n p' ('calendar' -> 'calendar year')",
    "F2": "unit_qualifier u, unit n with row quantity q -> 'q per n u'",
    "F3": "age_limit high a / low a -> 'through age a' / 'from age a'",
    "F4": "service_dates entry of type t with value d -> '<t in words> d'",
    "F5": "amount '2898.00' -> '$2898.00' (an amount sent as '$2898.00' stays as sent)",
    "F6": "percent '80' -> '80%'",
    "F7": "procedure code 'AD:D0150' -> 'D0150'",
    "F8": "booleans -> 'yes' / 'no'"
  },
  "member": {
    "as_sent": {
      "coverage": {
        "effective_date": "01/01/2026",
        "status": "active",
        "termination_date": "12/31/2026"
      },
      "dob": "01/01/1980",
      "first_name": "TEST",
      "last_name": "PATIENT",
      "member_id": "CH-ACTIVE-FULL",
      "relationship": "self"
    },
    "coverage": {
      "effective_date": "01/01/2026",
      "status": "active",
      "termination_date": "12/31/2026"
    }
  },
  "not_returned": [
    "not_covered"
  ],
  "outcome": {
    "answered": true
  },
  "payer": {
    "id": "94276",
    "name": "Delta Dental"
  },
  "plan": {
    "as_sent": {
      "group_number": "TESTGRP1",
      "insurance_type": "ppo",
      "name": "Delta Dental PPO"
    },
    "labels": {
      "insurance_type": "PPO"
    }
  },
  "section_titles": {
    "active_coverage": "Active coverage",
    "coinsurance": "Coinsurance",
    "deductible": "Deductible",
    "limitations": "Limitations and frequencies",
    "maximums": "Maximums"
  },
  "sections": {
    "active_coverage": [
      {
        "as_sent": {
          "insurance_type": "group_policy",
          "network": "in_network"
        },
        "codes": [],
        "labels": {
          "insurance_type": "Group policy",
          "network": "In network"
        },
        "reads_as": "Service not named by the payer · listed by the payer as active · In network, Group policy",
        "row": 0,
        "unknown_fields": []
      }
    ],
    "coinsurance": [
      {
        "as_sent": {
          "network": "in_network",
          "percent": "100",
          "service_type": "preventive"
        },
        "codes": [],
        "labels": {
          "network": "In network",
          "service_type": "Preventive care"
        },
        "reads_as": "Preventive care · coinsurance 100% · In network",
        "row": 0,
        "unknown_fields": []
      },
      {
        "as_sent": {
          "network": "in_network",
          "percent": "80",
          "service_type": "restorative"
        },
        "codes": [],
        "labels": {
          "network": "In network",
          "service_type": "Restorative (fillings)"
        },
        "reads_as": "Restorative (fillings) · coinsurance 80% · In network",
        "row": 1,
        "unknown_fields": []
      },
      {
        "as_sent": {
          "network": "in_network",
          "percent": "50",
          "service_type": "dental_crowns"
        },
        "codes": [],
        "labels": {
          "network": "In network",
          "service_type": "Crowns"
        },
        "reads_as": "Crowns · coinsurance 50% · In network",
        "row": 2,
        "unknown_fields": []
      }
    ],
    "deductible": [
      {
        "as_sent": {
          "amount": "50.00",
          "coverage_level": "individual",
          "network": "in_network",
          "plan_period": "calendar",
          "service_type": "dental_care"
        },
        "codes": [],
        "labels": {
          "coverage_level": "Individual",
          "network": "In network",
          "plan_period": "Calendar year",
          "service_type": "Dental care (general)"
        },
        "reads_as": "Dental care (general) · deductible $50.00 · Individual, In network, Calendar year",
        "row": 0,
        "unknown_fields": []
      },
      {
        "as_sent": {
          "amount": "25.00",
          "coverage_level": "individual",
          "network": "in_network",
          "plan_period": "remaining",
          "service_type": "dental_care"
        },
        "codes": [],
        "labels": {
          "coverage_level": "Individual",
          "network": "In network",
          "plan_period": "Remaining",
          "service_type": "Dental care (general)"
        },
        "reads_as": "Dental care (general) · deductible remaining $25.00 · Individual, In network",
        "row": 1,
        "unknown_fields": []
      },
      {
        "as_sent": {
          "amount": "150.00",
          "coverage_level": "family",
          "network": "in_network",
          "plan_period": "calendar",
          "service_type": "dental_care"
        },
        "codes": [],
        "labels": {
          "coverage_level": "Family",
          "network": "In network",
          "plan_period": "Calendar year",
          "service_type": "Dental care (general)"
        },
        "reads_as": "Dental care (general) · deductible $150.00 · Family, In network, Calendar year",
        "row": 2,
        "unknown_fields": []
      },
      {
        "as_sent": {
          "amount": "150.00",
          "coverage_level": "family",
          "network": "in_network",
          "plan_period": "remaining",
          "service_type": "dental_care"
        },
        "codes": [],
        "labels": {
          "coverage_level": "Family",
          "network": "In network",
          "plan_period": "Remaining",
          "service_type": "Dental care (general)"
        },
        "reads_as": "Dental care (general) · deductible remaining $150.00 · Family, In network",
        "row": 3,
        "unknown_fields": []
      }
    ],
    "limitations": [
      {
        "as_sent": {
          "coverage_level": "individual",
          "health_service_descriptions": [
            {
              "quantity": "2",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "calendar",
              "time_period_value": "1"
            }
          ],
          "limitation": "2 visits in 1 calendar",
          "network": "applies_all",
          "procedure_code": "AD:D1110"
        },
        "codes": [
          "D1110"
        ],
        "labels": {
          "coverage_level": "Individual",
          "network": "All networks"
        },
        "reads_as": "D1110 · 2 visits in 1 calendar · Individual, All networks",
        "row": 0,
        "unknown_fields": []
      },
      {
        "as_sent": {
          "coverage_level": "individual",
          "health_service_descriptions": [
            {
              "quantity": "1",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "limitation": "1 units remaining",
          "network": "applies_all",
          "procedure_code": "AD:D1110"
        },
        "codes": [
          "D1110"
        ],
        "labels": {
          "coverage_level": "Individual",
          "network": "All networks"
        },
        "reads_as": "D1110 · 1 units remaining · Individual, All networks",
        "row": 1,
        "unknown_fields": []
      },
      {
        "as_sent": {
          "coverage_level": "individual",
          "health_service_descriptions": [
            {
              "quantity": "1",
              "quantity_qualifier": "visits",
              "time_period_qualifier": "month",
              "time_period_value": "12"
            }
          ],
          "limitation": "1 visits in 12 month",
          "network": "applies_all",
          "procedure_code": "AD:D0274"
        },
        "codes": [
          "D0274"
        ],
        "labels": {
          "coverage_level": "Individual",
          "network": "All networks"
        },
        "reads_as": "D0274 · 1 visits in 12 month · Individual, All networks",
        "row": 2,
        "unknown_fields": []
      },
      {
        "as_sent": {
          "coverage_level": "individual",
          "health_service_descriptions": [
            {
              "quantity": "1",
              "quantity_qualifier": "units",
              "time_period_qualifier": "remaining"
            }
          ],
          "limitation": "1 units remaining",
          "network": "applies_all",
          "procedure_code": "AD:D0274"
        },
        "codes": [
          "D0274"
        ],
        "labels": {
          "coverage_level": "Individual",
          "network": "All networks"
        },
        "reads_as": "D0274 · 1 units remaining · Individual, All networks",
        "row": 3,
        "unknown_fields": []
      }
    ],
    "maximums": [
      {
        "as_sent": {
          "amount": "1500.00",
          "coverage_level": "individual",
          "network": "in_network",
          "plan_period": "calendar",
          "service_type": "dental_care"
        },
        "codes": [],
        "labels": {
          "coverage_level": "Individual",
          "network": "In network",
          "plan_period": "Calendar year",
          "service_type": "Dental care (general)"
        },
        "reads_as": "Dental care (general) · maximum $1500.00 · Individual, In network, Calendar year",
        "row": 0,
        "unknown_fields": []
      },
      {
        "as_sent": {
          "amount": "1200.00",
          "coverage_level": "individual",
          "network": "in_network",
          "plan_period": "remaining",
          "service_type": "dental_care"
        },
        "codes": [],
        "labels": {
          "coverage_level": "Individual",
          "network": "In network",
          "plan_period": "Remaining",
          "service_type": "Dental care (general)"
        },
        "reads_as": "Dental care (general) · maximum remaining $1200.00 · Individual, In network",
        "row": 1,
        "unknown_fields": []
      },
      {
        "as_sent": {
          "amount": "1000.00",
          "coverage_level": "individual",
          "network": "in_network",
          "plan_period": "lifetime",
          "service_type": "orthodontics"
        },
        "codes": [],
        "labels": {
          "coverage_level": "Individual",
          "network": "In network",
          "plan_period": "Lifetime",
          "service_type": "Orthodontics"
        },
        "reads_as": "Orthodontics · maximum $1000.00 · Individual, In network, Lifetime",
        "row": 2,
        "unknown_fields": []
      },
      {
        "as_sent": {
          "amount": "1000.00",
          "coverage_level": "individual",
          "network": "in_network",
          "plan_period": "lifetime_remaining",
          "service_type": "orthodontics"
        },
        "codes": [],
        "labels": {
          "coverage_level": "Individual",
          "network": "In network",
          "plan_period": "Lifetime remaining",
          "service_type": "Orthodontics"
        },
        "reads_as": "Orthodontics · maximum $1000.00 · Individual, In network, Lifetime remaining",
        "row": 3,
        "unknown_fields": []
      }
    ]
  },
  "subscriber": null,
  "truth": {
    "checked": 33,
    "defects": 0,
    "ok": true
  },
  "unknown_fields": []
}
409The organized answer withheld (forced truth defect, executed)
{
  "livemode": false,
  "error": "ANSWER_NOT_VERIFIED",
  "message": "The organized answer did not match the payer's answer, so it is withheld. The payer's answer as received is at payer_answer.",
  "errors": [
    {
      "eligibility_id": "elg_m7zmjt02h17253dsz2wn",
      "verified": false,
      "payer_answer": "/v1/eligibility/elg_m7zmjt02h17253dsz2wn/answer?view=payer"
    }
  ],
  "request_id": "evt_317j1hq6xn193fwd3xfm",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "CONTACT_SUPPORT",
  "doc_url": "https://docs.claimhouse.ai/#error-answer-not-verified",
  "user_message": "The readable answer could not be shown. The payer's original answer is kept."
}
422view=full needs contract=v2
{
  "livemode": false,
  "error": "INVALID_REQUEST",
  "message": "view=full is a v2 view; under contract v3 use complete, summary, lines or payer, or send contract=v2",
  "errors": [],
  "request_id": "evt_28wtztn3t13w13bvwrx5",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-invalid-request",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}
422An unknown fields token
{
  "livemode": false,
  "error": "INVALID_ELIGIBILITY_REQUEST",
  "message": "fields names 'nonsense', which is neither a summary block (plan, totals, deductibles, maximums, out_of_pocket, coinsurance, procedures, frequencies, history, not_covered, missing_tooth, waiting_periods) nor a CDT code such as D1110",
  "errors": [
    {
      "field": "fields"
    }
  ],
  "request_id": "evt_p3nhdfy4tn3khdgg584g",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-invalid-eligibility-request",
  "user_message": "Some patient or insurance details need to be corrected before checking."
}
304Not modified
null
404Not found
{
  "error": "NOT_FOUND",
  "message": "no such eligibility result",
  "errors": [],
  "request_id": "evt_ang0n1gexynjw0dmfh8v",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-not-found",
  "user_message": "We could not find that item. It may have been removed, or you may not have access to it."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDmissing, invalid or revoked credential
403FACILITY_NOT_GRANTEDcredential is not granted the check's office
403PERMISSION_DENIEDcredential lacks eligibility access
404NOT_FOUNDno such eligibility result in your organization, grants and key mode
409ANSWER_NOT_VERIFIEDthe organized answer did not pass its truth checks; errors[0].payer_answer names the payer's answer as received, which still answers
422INVALID_ELIGIBILITY_REQUESTthe check did not succeed, so there is no payer answer to read
422INVALID_ELIGIBILITY_REQUESTa fields token is not a summary block or a CDT code (errors[0].field is fields)
422INVALID_REQUESTview or contract is not one listed, or view=full without contract=v2, or fields without view=summary
429TOO_MANY_REQUESTSrate or concurrency limit reached
503ELIGIBILITY_UNAVAILABLEthe eligibility rail is not configured on this gateway
InfoA line is one payer row: kind (its payer section), the row's fields under plain names (network, level, period, service, amount, percent, limit, quantity, quantity_unit, age, frequency, service_dates, note, disclaimers, references, ...), text (one sentence holding every value on the line), ref (the payer section and row, the same index as view=payer) and other (fields not organized, verbatim). A field is present only when the payer sent its key. Money is a decimal string exactly as sent; percent is a number only when the payer sent a plain number.
InfoThe ETag of each view names that view (and, for a summary, its selection). Revalidate each view with its own tag.
InfoContract v2 (contract=v2, or the default under 2026-10-01), unchanged: request_id (string): Unique id for this request. Also returned in the X-Request-Id header; contract (string): eligibility.v2. Not present with view=payer; eligibility_id (string): The eligibility id; facility_id (string): The office the check ran under. Not present with view=payer; office (string): The office's current display name. Not present with view=payer; outcome (object): answered true when the payer sent benefits; otherwise the payer's own reason as sent. Not present with view=payer; sections (object): Payer rows by section (deductible, maximums, coinsurance, limitations and more), each with as_sent, labels, codes and reads_as; not_returned (array): Expected section keys that are absent or empty in this readable view. Related information may exist in other fields or notes; this does not mean services are not covered; truth (object): The truth checks: checked count, defects count and ok. Not present with view=payer; payer_answer (object): The payer's answer as received, less excluded keys. Only with view=payer or view=full. The network's transaction id is named claimhouseTransactionId, and network processing fields (such as response_level) name Claim House; payer values are never changed.
API reference

Read the summary settings

GEThttps://api.claimhouse.ai/v1/settings/eligibility-summary

Which blocks and procedure codes the summary view of an answer shows, for the organization or one office.

Returns the organization's saved setting, the office's (with facility_id), what a summary would use now (effective, with the source of each choice) and the defaults.

Precedence for a summary: the call's fields=, then the office's setting, then the organization's, then the defaults. Blocks and codes are decided separately. The same settings apply in test and live mode: they choose what is shown, never what is checked.

Permission
read
Idempotency
none
Side effects
None. Read only.
In the dashboard
Eligibility

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Query parameters

NameTypeDescription
facility_idstringAn office your key reaches. Without it, the organization's setting.
e.g. fac_EXAMPLE0000000000001

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id.
organization*objectThe organization's saved setting (blocks, procedures, version, updated_at, updated_by), or null when none is saved.
facility_idstringWith facility_id: the office.
officeobjectWith facility_id: the office's saved setting, or null.
effective*objectWhat a summary for this office (or the organization) shows now: blocks, procedures and the source of each (office, organization or default).
defaults*objectThe default blocks and procedures.
blocks_available*arrayEvery block a summary can show.

Responses

200OK: the organization (executed, test mode)
{
  "livemode": false,
  "request_id": "evt_0ab99jh25h2b70hvryej",
  "organization": null,
  "effective": {
    "blocks": [
      "plan",
      "totals",
      "deductibles",
      "maximums",
      "out_of_pocket",
      "coinsurance",
      "procedures",
      "frequencies",
      "history",
      "not_covered",
      "missing_tooth",
      "waiting_periods"
    ],
    "procedures": [
      "D0120",
      "D0140",
      "D0150",
      "D0210",
      "D0220",
      "D0272",
      "D0274",
      "D0330",
      "D1110",
      "D1120",
      "D1206",
      "D1208",
      "D4341",
      "D4342",
      "D4910",
      "D2740",
      "D2750",
      "D7140",
      "D7210"
    ],
    "source": {
      "blocks": "default",
      "procedures": "default"
    }
  },
  "defaults": {
    "blocks": [
      "plan",
      "totals",
      "deductibles",
      "maximums",
      "out_of_pocket",
      "coinsurance",
      "procedures",
      "frequencies",
      "history",
      "not_covered",
      "missing_tooth",
      "waiting_periods"
    ],
    "procedures": [
      "D0120",
      "D0140",
      "D0150",
      "D0210",
      "D0220",
      "D0272",
      "D0274",
      "D0330",
      "D1110",
      "D1120",
      "D1206",
      "D1208",
      "D4341",
      "D4342",
      "D4910",
      "D2740",
      "D2750",
      "D7140",
      "D7210"
    ]
  },
  "blocks_available": [
    "plan",
    "totals",
    "deductibles",
    "maximums",
    "out_of_pocket",
    "coinsurance",
    "procedures",
    "frequencies",
    "history",
    "not_covered",
    "missing_tooth",
    "waiting_periods"
  ]
}
200OK: one office after its setting was saved
{
  "livemode": false,
  "request_id": "evt_g9267jm9z10bf4ppmx45",
  "organization": null,
  "facility_id": "fac_sandboxbatchsandbx",
  "office": {
    "scope": "office",
    "facility_id": "fac_sandboxbatchsandbx",
    "blocks": [
      "plan",
      "totals",
      "procedures",
      "history"
    ],
    "procedures": [
      "D0120",
      "D1110",
      "D2740"
    ],
    "version": 1,
    "updated_at": "2026-10-05T17:38:37.425394+00:00"
  },
  "effective": {
    "blocks": [
      "plan",
      "totals",
      "procedures",
      "history"
    ],
    "procedures": [
      "D0120",
      "D1110",
      "D2740"
    ],
    "source": {
      "blocks": "office",
      "procedures": "office"
    }
  },
  "defaults": {
    "blocks": [
      "plan",
      "totals",
      "deductibles",
      "maximums",
      "out_of_pocket",
      "coinsurance",
      "procedures",
      "frequencies",
      "history",
      "not_covered",
      "missing_tooth",
      "waiting_periods"
    ],
    "procedures": [
      "D0120",
      "D0140",
      "D0150",
      "D0210",
      "D0220",
      "D0272",
      "D0274",
      "D0330",
      "D1110",
      "D1120",
      "D1206",
      "D1208",
      "D4341",
      "D4342",
      "D4910",
      "D2740",
      "D2750",
      "D7140",
      "D7210"
    ]
  },
  "blocks_available": [
    "plan",
    "totals",
    "deductibles",
    "maximums",
    "out_of_pocket",
    "coinsurance",
    "procedures",
    "frequencies",
    "history",
    "not_covered",
    "missing_tooth",
    "waiting_periods"
  ]
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403FACILITY_NOT_GRANTEDfacility_id is not an office your key reaches
403PERMISSION_DENIEDKey lacks read
API reference

Save the summary settings

PUThttps://api.claimhouse.ai/v1/settings/eligibility-summary

Choose the blocks and procedure codes the summary view shows, for the organization or one office.

Without facility_id it saves the organization's setting and needs an organization-wide key or session; with facility_id it saves that office's. Each save adds one to version. To go back to the defaults, save the defaults (there is no delete).

The summary always selects whole lines from the complete answer and says how many it shows (counts.shown_lines of counts.complete_lines), so it is never mistaken for the whole answer.

Permission
admin (keys); a dashboard session holding offices.manage
Idempotency
safe to repeat
Side effects
Stores the setting. No payer call, no charge.
In the dashboard
Eligibility

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Query parameters

NameTypeDescription
facility_idstringAn office your key reaches. Without it, the organization's setting.
e.g. fac_EXAMPLE0000000000001

Request body

NameTypeDescription
blocks*arrayBlocks to show: plan, totals, deductibles, maximums, out_of_pocket, coinsurance, procedures, frequencies, history, not_covered, missing_tooth, waiting_periods.
e.g. ["plan","totals","procedures","history"]
procedures*arrayCDT codes (D and four digits) the summary shows, up to 200.
e.g. ["D0120","D1110","D2740"]

Request example

{
  "blocks": [
    "plan",
    "totals",
    "procedures",
    "history"
  ],
  "procedures": [
    "D0120",
    "D1110",
    "D2740"
  ]
}

Response fields

NameTypeDescription
request_id*stringRequest id.
organization*objectThe organization's saved setting (blocks, procedures, version, updated_at, updated_by), or null when none is saved.
facility_idstringWith facility_id: the office.
officeobjectWith facility_id: the office's saved setting, or null.
effective*objectWhat a summary for this office (or the organization) shows now: blocks, procedures and the source of each (office, organization or default).
defaults*objectThe default blocks and procedures.
blocks_available*arrayEvery block a summary can show.
saved*objectThe setting just saved.

Responses

200OK: one office setting saved (executed, test mode)
{
  "livemode": false,
  "request_id": "evt_s7x4h51ye91j74m6tdd3",
  "organization": null,
  "facility_id": "fac_sandboxbatchsandbx",
  "office": {
    "scope": "office",
    "facility_id": "fac_sandboxbatchsandbx",
    "blocks": [
      "plan",
      "totals",
      "procedures",
      "history"
    ],
    "procedures": [
      "D0120",
      "D1110",
      "D2740"
    ],
    "version": 1,
    "updated_at": "2026-10-05T17:38:37.425394+00:00"
  },
  "effective": {
    "blocks": [
      "plan",
      "totals",
      "procedures",
      "history"
    ],
    "procedures": [
      "D0120",
      "D1110",
      "D2740"
    ],
    "source": {
      "blocks": "office",
      "procedures": "office"
    }
  },
  "defaults": {
    "blocks": [
      "plan",
      "totals",
      "deductibles",
      "maximums",
      "out_of_pocket",
      "coinsurance",
      "procedures",
      "frequencies",
      "history",
      "not_covered",
      "missing_tooth",
      "waiting_periods"
    ],
    "procedures": [
      "D0120",
      "D0140",
      "D0150",
      "D0210",
      "D0220",
      "D0272",
      "D0274",
      "D0330",
      "D1110",
      "D1120",
      "D1206",
      "D1208",
      "D4341",
      "D4342",
      "D4910",
      "D2740",
      "D2750",
      "D7140",
      "D7210"
    ]
  },
  "blocks_available": [
    "plan",
    "totals",
    "deductibles",
    "maximums",
    "out_of_pocket",
    "coinsurance",
    "procedures",
    "frequencies",
    "history",
    "not_covered",
    "missing_tooth",
    "waiting_periods"
  ],
  "saved": {
    "scope": "office",
    "facility_id": "fac_sandboxbatchsandbx",
    "blocks": [
      "plan",
      "totals",
      "procedures",
      "history"
    ],
    "procedures": [
      "D0120",
      "D1110",
      "D2740"
    ],
    "version": 1,
    "updated_at": "2026-10-05T17:38:37.425394+00:00"
  }
}
403A key without admin
{
  "livemode": false,
  "error": "PERMISSION_DENIED",
  "message": "permission denied",
  "errors": [
    {
      "permission": "admin"
    }
  ],
  "request_id": "evt_9rfm4n0wd15851282cnf",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-permission-denied",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks admin, or an office-scoped key saving the organization's setting
403FACILITY_NOT_GRANTEDfacility_id is not an office your key reaches
422INVALID_ELIGIBILITY_REQUESTA block is not in blocks_available or a code is not D and four digits (errors[0].field)
422INVALID_REQUESTAn unknown field in the body
API reference

Get the PDF of a check

GEThttps://api.claimhouse.ai/v1/eligibility/{eligibility_id}/pdf

Return the PDF of the asked kind already made for a check's current answer, with a short-lived download link. Read access is enough (Viewers and read-only keys). It never makes a PDF: until one of that kind has been made with POST /v1/eligibility/{eligibility_id}/pdf it answers 404 PDF_NOT_MADE.

No payer call, no charge, nothing stored. The PDF returned always matches the check's current answer and, for kind=streamlined, the summary settings in force now; a PDF made from an older answer is never returned.

The download_url is valid for expires_in_seconds. Download it without your API key: it is a signed link to the file. You can also fetch a link later with GET /v1/artifacts/{artifact_id}.

Permission
read
Idempotency
safe to repeat
Side effects
None. No payer call, no charge, nothing stored.
In the dashboard
Eligibility > a check > Download PDF (for Viewers, when a PDF exists)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Path parameters

NameTypeDescription
eligibility_id*stringThe check id, elg_..., 1 to 64 characters. The check must have succeeded.
e.g. elg_hp130jp45188vw4wk5tz

Query parameters

NameTypeDescription
kindstringcomplete (the default under API version 2026-11-01): every line of the answer, as long as the answer is, never cut, in a compact layout (procedure codes as a grid, one row per code and one column per network, every line's sentence printed once). streamlined: the lines the summary view selects (the office's saved summary settings, else the organization's, else the default), headed "Streamlined: N of M lines. The complete answer has every line." Each kind is its own file and never replaces the other.
one of: complete · streamlined
e.g. streamlined
contractstringv3 is the same as kind=complete (kept for callers that used it). v2 is the 2026-10-01 PDF (elig_{eligibility_id}.pdf), the default when you pin Claim-House-Version: 2026-10-01. Sent with a kind that disagrees, 422 INVALID_REQUEST.
one of: v2 · v3
e.g. v3

Response fields

NameTypeDescription
request_id*stringSame as the X-Request-Id header.
eligibility_id*stringThe check.
artifact_id*stringThe stored PDF (art_...).
filename*stringelig_<eligibility_id>-complete.pdf or elig_<eligibility_id>-streamlined.pdf; elig_<eligibility_id>.pdf for the 2026-10-01 PDF. No patient name.
bytes*integerPDF size in bytes.
contractstringeligibility.v3 on the complete and streamlined PDFs; absent on the 2026-10-01 PDF.
one of: eligibility.v3
kindstringcomplete or streamlined; absent on the 2026-10-01 PDF.
one of: complete · streamlined
download_url*stringShort-lived link to download the PDF.
expires_in_seconds*integerHow long download_url stays valid.

Responses

200The complete PDF already made, the default (executed; the local download link is replaced by an example)
{
  "livemode": false,
  "request_id": "evt_mxrzjwfm6h5mn430pty0",
  "eligibility_id": "elg_m6ty5a8j8s4156mq1bs7",
  "artifact_id": "art_pxwvrtatv14dq6kw8mmp",
  "filename": "elig_elg_m6ty5a8j8s4156mq1bs7-complete.pdf",
  "bytes": 90033,
  "contract": "eligibility.v3",
  "kind": "complete",
  "download_url": "https://files.claimhouse.ai/EXAMPLE-short-lived-link",
  "expires_in_seconds": 600
}
200kind=streamlined, read with a read-only key (executed; the local download link is replaced by an example)
{
  "livemode": false,
  "request_id": "evt_sk6e7gv3cd2pde7tvzx8",
  "eligibility_id": "elg_m6ty5a8j8s4156mq1bs7",
  "artifact_id": "art_995q3cr3w14g739zampa",
  "filename": "elig_elg_m6ty5a8j8s4156mq1bs7-streamlined.pdf",
  "bytes": 89299,
  "contract": "eligibility.v3",
  "kind": "streamlined",
  "download_url": "https://files.claimhouse.ai/EXAMPLE-short-lived-link",
  "expires_in_seconds": 600
}
404Before it was made (executed)
{
  "livemode": false,
  "error": "PDF_NOT_MADE",
  "message": "No PDF has been made for this check yet. Make one with POST /v1/eligibility/elg_m6ty5a8j8s4156mq1bs7/pdf.",
  "errors": [
    {
      "eligibility_id": "elg_m6ty5a8j8s4156mq1bs7"
    }
  ],
  "request_id": "evt_3q9qt4wmms55hfm5n8vx",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-pdf-not-made",
  "user_message": "No PDF has been made for this answer yet."
}
404kind=streamlined before it was made (executed)
{
  "livemode": false,
  "error": "PDF_NOT_MADE",
  "message": "No PDF has been made for this check yet. Make one with POST /v1/eligibility/elg_m6ty5a8j8s4156mq1bs7/pdf?kind=streamlined.",
  "errors": [
    {
      "eligibility_id": "elg_m6ty5a8j8s4156mq1bs7"
    }
  ],
  "request_id": "evt_3hwkswsdtn3b75r079mz",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-pdf-not-made",
  "user_message": "No PDF has been made for this answer yet."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks read
403FACILITY_NOT_GRANTEDThe check belongs to an office your key or session cannot reach
404NOT_FOUNDNo such check for your organization and mode
404PDF_NOT_MADENo PDF has been made for this check's current answer yet
422INVALID_REQUESTPath or query fails the schema: for example kind is not complete or streamlined, or kind and contract disagree
422INVALID_ELIGIBILITY_REQUESTThe check did not succeed, so it has no PDF
InfoTwo PDFs, one answer (API version 2026-11-01). The complete PDF prints every line of the answer in the API's order: who, the plan, deductibles and maximums, by service, by procedure, history, not covered and notes. Its length follows the answer and nothing is cut: the largest real answer we measured (2,672 lines) prints on 55 pages. Procedure codes are a grid, one row per code and one column per network; a cell holds the line's sentence, or its kind and values with a letter whose sentence is printed right under the row.
InfoThe streamlined PDF prints the lines the summary view selects, each exactly as the complete answer has it, and says how many it shows of how many. Change what it selects with PUT /v1/settings/eligibility-summary; a changed setting makes a new streamlined PDF on the next request.
InfoEvery PDF is proven against the answer before it is stored (every line's sentence present exactly once, every value traced, nothing added, the streamlined one a byte-equal subset of the complete answer), else 409 PDF_NOT_VERIFIED and nothing is stored. Lines show procedure codes only, never procedure names.
API reference

Create an eligibility PDF

POSThttps://api.claimhouse.ai/v1/eligibility/{eligibility_id}/pdf

Make the PDF of a successful check and store it as a downloadable file. kind=complete (the default) prints every line of the answer; kind=streamlined prints the lines the summary view selects. Before it is stored, every line and value in the PDF is checked against the answer; if that check fails you get 409 PDF_NOT_VERIFIED (rare) and the answer stays available. Asking again for the same kind returns the same stored PDF. Needs the submit permission.

Draws from the answer stored for that check, so there is no new payer call. The response's artifact_id fetches a short-lived download link with GET /v1/artifacts/{artifact_id}, or read the PDF and its link together with GET /v1/eligibility/{eligibility_id}/pdf (same kind).

Asking again for the same answer and kind returns the PDF already stored (same artifact_id); a new PDF is made only when the answer, the PDF format or (for streamlined) the summary settings changed. A failed check cannot produce a PDF.

Permission
submit
Idempotency
none
Side effects
Stores a new PDF artifact and emits eligibility.pdf_generated. No vendor call and no practice management system write.
In the dashboard
Eligibility > New check (Download PDF), Eligibility > Previous checks (PDF)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Path parameters

NameTypeDescription
eligibility_id*stringThe check id, elg_..., 1 to 64 characters. The check must have succeeded.
e.g. elg_hp130jp45188vw4wk5tz

Query parameters

NameTypeDescription
kindstringcomplete (the default under API version 2026-11-01): every line of the answer, as long as the answer is, never cut, in a compact layout (procedure codes as a grid, one row per code and one column per network, every line's sentence printed once). streamlined: the lines the summary view selects (the office's saved summary settings, else the organization's, else the default), headed "Streamlined: N of M lines. The complete answer has every line." Each kind is its own file and never replaces the other.
one of: complete · streamlined
e.g. streamlined
contractstringv3 is the same as kind=complete (kept for callers that used it). v2 is the 2026-10-01 PDF (elig_{eligibility_id}.pdf), the default when you pin Claim-House-Version: 2026-10-01. Sent with a kind that disagrees, 422 INVALID_REQUEST.
one of: v2 · v3
e.g. v3

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id.
eligibility_id*stringThe check.
artifact_id*stringThe stored PDF, art_.... Pass to GET /v1/artifacts/{artifact_id} for a download link.
filename*stringelig_<eligibility_id>-complete.pdf or elig_<eligibility_id>-streamlined.pdf; elig_<eligibility_id>.pdf for the 2026-10-01 PDF. No patient name.
bytes*integerPDF size in bytes.
contractstringeligibility.v3 on the complete and streamlined PDFs; absent on the 2026-10-01 PDF.
one of: eligibility.v3
kindstringcomplete or streamlined; absent on the 2026-10-01 PDF.
one of: complete · streamlined

Responses

200The complete PDF made, the default (executed, test mode)
{
  "livemode": false,
  "request_id": "evt_5hd70es8253wbbg47xye",
  "eligibility_id": "elg_m6ty5a8j8s4156mq1bs7",
  "artifact_id": "art_pxwvrtatv14dq6kw8mmp",
  "filename": "elig_elg_m6ty5a8j8s4156mq1bs7-complete.pdf",
  "bytes": 90033,
  "contract": "eligibility.v3",
  "kind": "complete"
}
200kind=streamlined: the streamlined PDF made, its own file (executed, test mode)
{
  "livemode": false,
  "request_id": "evt_2gkn9cx9r15cs4ckz5td",
  "eligibility_id": "elg_m6ty5a8j8s4156mq1bs7",
  "artifact_id": "art_995q3cr3w14g739zampa",
  "filename": "elig_elg_m6ty5a8j8s4156mq1bs7-streamlined.pdf",
  "bytes": 89299,
  "contract": "eligibility.v3",
  "kind": "streamlined"
}
200Pinned to Claim-House-Version: 2026-10-01: the 2026-10-01 PDF, unchanged (executed, test mode)
{
  "livemode": false,
  "request_id": "evt_rvcyagszp52bh453azw6",
  "eligibility_id": "elg_m6ty5a8j8s4156mq1bs7",
  "artifact_id": "art_1s3a6da4c52k11793nb8",
  "filename": "elig_elg_m6ty5a8j8s4156mq1bs7.pdf",
  "bytes": 87759
}
422kind and contract disagree (executed)
{
  "livemode": false,
  "error": "INVALID_REQUEST",
  "message": "kind and contract disagree: contract=v3 is kind=complete and contract=v2 is the 2026-10-01 PDF, which has no kind; send kind alone",
  "errors": [],
  "request_id": "evt_8b236y63qn57f1sqr3g1",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-invalid-request",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}
403A read-only key cannot make a PDF (executed)
{
  "livemode": false,
  "error": "PERMISSION_DENIED",
  "message": "permission denied",
  "errors": [
    {
      "permission": "submit"
    }
  ],
  "request_id": "evt_2fgtakjr0d5m95gswyqm",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-permission-denied",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}
422Check was a vendor failure
{
  "error": "INVALID_ELIGIBILITY_REQUEST",
  "message": "PDF requires a successful eligibility result",
  "errors": [
    {
      "eligibility_id": "elg_wddgq19nhagdyseyyhte"
    }
  ],
  "request_id": "evt_bkfrar1bddj3efgmw6s0",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-invalid-eligibility-request",
  "user_message": "Some patient or insurance details need to be corrected before checking."
}
404Not found
{
  "error": "NOT_FOUND",
  "message": "no such eligibility result",
  "errors": [
    {
      "eligibility_id": "elg_5zgacj2z460gmw1ebbq7"
    }
  ],
  "request_id": "evt_y496y9sv80mh6vq5a73g",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-not-found",
  "user_message": "We could not find that item. It may have been removed, or you may not have access to it."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks the route's permission
403FACILITY_NOT_GRANTEDThe check's office is not granted to your key
404NOT_FOUNDNo such check for your account
422INVALID_REQUESTPath or query fails the schema: for example kind is not complete or streamlined, or kind and contract disagree
422INVALID_ELIGIBILITY_REQUESTThe check was a vendor failure or has no archived answer
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
503ELIGIBILITY_UNAVAILABLEEligibility is not configured on this gateway
ImportantBeta: like the check, this route answers 503 ELIGIBILITY_UNAVAILABLE when eligibility is not configured on the gateway, and the deployed configuration was not confirmed when these docs were written.
InfoA failure in the archive read or the renderer returns a 500 with no error code. Calling again is safe: it renders a new artifact and never contacts the vendor.
InfoOpenAPI does not declare the 403, 404 or 503 answers.
InfoTwo PDFs, one answer (API version 2026-11-01). The complete PDF prints every line of the answer in the API's order: who, the plan, deductibles and maximums, by service, by procedure, history, not covered and notes. Its length follows the answer and nothing is cut: the largest real answer we measured (2,672 lines) prints on 55 pages. Procedure codes are a grid, one row per code and one column per network; a cell holds the line's sentence, or its kind and values with a letter whose sentence is printed right under the row.
InfoThe streamlined PDF prints the lines the summary view selects, each exactly as the complete answer has it, and says how many it shows of how many. Change what it selects with PUT /v1/settings/eligibility-summary; a changed setting makes a new streamlined PDF on the next request.
InfoEvery PDF is proven against the answer before it is stored (every line's sentence present exactly once, every value traced, nothing added, the streamlined one a byte-equal subset of the complete answer), else 409 PDF_NOT_VERIFIED and nothing is stored. Lines show procedure codes only, never procedure names.
API reference

List an office's eligibility checks

GEThttps://api.claimhouse.ai/v1/facilities/{facility_id}/eligibility

List recorded checks for one office, newest first, with ids, codes and outcomes only.

Use it for history, reconciliation, and to find out what happened after an uncertain check before you send it again. Rows include vendor failures.

There is no cursor and no upper time bound: only since and limit. Cache hits are not stored rows and do not appear.

Permission
read
Idempotency
none
Side effects
Writes an audit read row listing the returned ids. Never contacts the eligibility vendor.
In the dashboard
Eligibility > Previous checks, Eligibility > New check (history below the form)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Path parameters

NameTypeDescription
facility_id*stringThe office, 1 to 64 characters. Must be granted to your key.
e.g. fac_q5s09nzww25ysd5a2f3g

Query parameters

NameTypeDescription
sincedatetimeOnly checks retrieved at or after this ISO 8601 time.
e.g. 2026-09-01T00:00:00Z
limitintegerRows to return, 1 to 500. Default 100.
e.g. 2

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id.
facility_id*stringThe office.
results*arrayChecks, newest first.
eligibility_id*stringThe check id, elg_....
facility_id*stringThe office.
payer_id*stringThe payer id sent.
relationship*stringWho was checked.
one of: self · spouse · child · other
service_date*dateService date.
status*stringCoverage status.
one of: ACTIVE · INACTIVE · UNKNOWN
outcome*stringOK or VENDOR_ERROR.
one of: OK · VENDOR_ERROR
error_classstringVendor error class on failures. Null on success.
rejection_summarystringOnly on a failure the payer explained: one plain sentence saying why, from the stored rejection. Null otherwise.
vendor*stringAlways claimhouse. Kept so parsers that read it keep working.
vendor_transaction_idstringVendor transaction id. Null when none was read.
vendor_latency_ms*integerVendor latency in milliseconds.
tenant_referencestringYour reference. Null when not sent.
retrieved_at*datetimeWhen the vendor call was made.
billing*objectWhether this check is charged and why, read from its usage unit. Null only for a check recorded before usage metering began. The reasons are listed in the Pricing and what's charged guide.
chargedbooleantrue when charged, false when free, null while the check is under review.
e.g. true
state*stringThe unit's billable state.
one of: BILLABLE · PENDING · NOT_BILLABLE
reason*stringWhy, as a stable code: for example answered, payer_rejected_patient, payer_unavailable, cache_hit (a saved answer served again), test_mode or under_review.
e.g. answered
label*stringA short plain label for the reason.
e.g. Payer answered
reason_label*stringOne plain sentence saying whether and why the check is charged.
e.g. The payer answered this check; checks the payer answers are charged
unit_price_microsintegerAlways null in lists; read the check by id for its price.
e.g. null

Responses

200OK: executed local Test scenario, synthetic patient and ids
{
  "livemode": false,
  "request_id": "evt_ppc4dn32mh0yv310gtx6",
  "facility_id": "fac_sandboxsandboxsand",
  "results": [
    {
      "eligibility_id": "elg_cz2zee1eeh3tb79rxc58",
      "facility_id": "fac_sandboxsandboxsand",
      "payer_id": "94276",
      "relationship": "self",
      "service_date": "2026-09-07",
      "status": "ACTIVE",
      "outcome": "OK",
      "error_class": null,
      "vendor": "claimhouse",
      "vendor_transaction_id": "test-smp_magic_active_full",
      "vendor_latency_ms": 320,
      "tenant_reference": "first-test-check",
      "retrieved_at": "2026-09-07T15:00:00+00:00",
      "rejection_summary": null,
      "billing": {
        "charged": false,
        "state": "NOT_BILLABLE",
        "reason": "test_mode",
        "label": "Test mode",
        "reason_label": "Test mode checks never reach a payer and are never charged",
        "unit_price_micros": null
      }
    }
  ]
}
403Office not granted
{
  "error": "FACILITY_NOT_GRANTED",
  "message": "this key's grants do not cover that facility",
  "errors": [
    {
      "facility_id": "fac_w9qxypnbcw7b308jbbhh"
    }
  ],
  "request_id": "evt_raxyv96xhdgz5s57d4bd",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-facility-not-granted",
  "user_message": "Your account does not have access to this office."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks the route's permission
403FACILITY_NOT_GRANTEDOffice not covered by the key's grants
404NOT_FOUNDNo such office for your account
422INVALID_REQUESTPath, query or body fails the schema
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
Infomode is not on list rows. Read a single check for it.
ImportantWithout a cursor you cannot page past the newest 500 checks retrieved after a given since. Narrow since to walk older history.
API reference

Poll an eligibility operation

GEThttps://api.claimhouse.ai/v1/eligibility/{eligibility_id}/operation

Poll the state of one eligibility request, including archive and PDF status.

Eligibility answers asynchronously. This route reports the operation state, whether the raw request and response are durably archived, and the latest PDF artifact: without re-issuing the clinical question.

Reads are safe to repeat: polling never causes a second payer call.

Permission
read
Idempotency
none
Side effects
None. Read only.
In the dashboard
Eligibility > request detail

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Path parameters

NameTypeDescription
eligibility_id*stringThe eligibility id returned by POST /v1/eligibility.
e.g. elg_EXAMPLE0000000000000001

Request example

null

Response fields

NameTypeDescription
request_id*stringUnique id for this request. Also returned in the X-Request-Id header.
e.g. evt_EXAMPLE0000000000000031
eligibility_id*stringThe eligibility id.
e.g. elg_EXAMPLE0000000000000001
facility_id*stringThe office the check ran under.
e.g. fac_EXAMPLE0000000000000001
environment*stringThe key mode the operation ran in, test or live.
one of: test · live
e.g. test
state*stringOperation state.
e.g. ANSWERED
response_mode*stringHow the answer was delivered.
e.g. realtime
result_idstringThe retained result id once answered. Null while in flight.
e.g. res_EXAMPLE0000000000000001
request_archived*booleanThe exact outbound request is durably archived.
e.g. true
response_archived*booleanThe raw payer response is durably archived.
e.g. true
pdfobjectLatest PDF artifact metadata when one has been generated.
e.g. {"artifact_id":"art_EXAMPLE0000000000000001","status":"ready"}

Responses

200OK: executed local Test scenario, synthetic patient and ids
{
  "livemode": false,
  "request_id": "evt_00z0kmw3d10pf70mxq0f",
  "eligibility_id": "elg_cz2zee1eeh3tb79rxc58",
  "facility_id": "fac_sandboxsandboxsand",
  "environment": "test",
  "state": "COMPLETE",
  "response_mode": "standard",
  "result_id": "elg_cz2zee1eeh3tb79rxc58",
  "request_archived": true,
  "response_archived": true,
  "pdf": null
}
404Not found
{
  "error": "NOT_FOUND",
  "message": "no such eligibility operation",
  "errors": [],
  "request_id": "evt_ang0n1gexynjw0dmfh8v",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-not-found",
  "user_message": "We could not find that item. It may have been removed, or you may not have access to it."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDmissing, invalid or revoked credential
403PERMISSION_DENIEDcredential lacks read or the operation's office
404NOT_FOUNDno such eligibility operation in your seller, grants and key mode
503ELIGIBILITY_UNAVAILABLEthe eligibility rail is not configured on this gateway
429TOO_MANY_REQUESTSrate or concurrency limit reached
InfoPoll this route instead of re-submitting. Re-submitting the same patient question spends another payer request; polling never does.
API reference

List eligibility checks

GEThttps://api.claimhouse.ai/v1/eligibility

List recorded checks across your offices, newest first, with the people named on each request and whether each check is charged.

Use it for a check history screen or to find a patient's recent checks. Rows include failures. Cache hits are not stored rows and do not appear.

Each row names the subscriber and, for a dependent, the patient: this is patient data from your own offices. It does not carry benefits. Read GET /v1/eligibility/{eligibility_id} for the full answer.

q splits on spaces and uses the first 6 words. Every word must appear, case insensitively, in the subscriber or patient names, member id, payer id, the payer's name or your reference. Page with before, set to the next of the previous page.

Permission
read
Idempotency
none
Side effects
Writes an audit read row listing the returned check ids. Never contacts a payer.
In the dashboard
Eligibility > Previous checks

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Query parameters

NameTypeDescription
facility_idstringOnly this office. Repeat the parameter for several offices. Each must be granted to your key. Without it, every office your key can see.
e.g. fac_tycrfy0cs0qc7sq95eme
statusstringACTIVE, INACTIVE or UNKNOWN match answered checks with that coverage status. ERROR matches checks the payer did not answer (outcome VENDOR_ERROR).
one of: ACTIVE · INACTIVE · UNKNOWN · ERROR
e.g. ACTIVE
qstringSearch words, up to 120 characters.
e.g. testpatient
beforestringThe next value from the previous page, up to 120 characters.
e.g. 2026-09-07T15:00:10+00:00|elg_skvgqer72n4zf02jz5rb
limitintegerRows to return, 1 to 500. Default 100.
e.g. 2
batch_idstringOnly the checks one batch made (bat_...).
e.g. bat_EXAMPLE0000000000001
sincestringAn ISO 8601 time, for example 2026-10-05T00:00:00Z (no zone means UTC): only checks retrieved at or after it. Combine with before to pull everything since your last pull, page by page.
e.g. 2026-10-05T00:00:00Z

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id. The same value as the X-Request-Id header.
results*arrayChecks, newest first.
eligibility_id*stringThe check id, elg_....
e.g. elg_skvgqer72n4zf02jz5rb
facility_id*stringThe office.
e.g. fac_tycrfy0cs0qc7sq95eme
payer_id*stringThe payer id sent.
e.g. TESTPAYER1
relationship*stringWho was checked.
one of: self · spouse · child · other
e.g. self
service_date*dateService date.
e.g. 2026-09-07
status*stringCoverage status.
one of: ACTIVE · INACTIVE · UNKNOWN
e.g. ACTIVE
outcome*stringOK for an answer, VENDOR_ERROR for a recorded failure.
one of: OK · VENDOR_ERROR
e.g. OK
error_classstringError class on failures. Null on success.
vendor_latency_ms*integerTime the payer call took, in milliseconds.
e.g. 1840
tenant_referencestringYour reference. Null when not sent.
retrieved_at*datetimeWhen the payer call was made.
e.g. 2026-09-07T15:00:10+00:00
rejection_summarystringOnly on a failure the payer explained: one plain sentence saying why. Null otherwise.
billingobjectWhether this check is charged and why. Null only for a check recorded before usage metering began.
chargedbooleantrue when charged, false when free, null while the check is under review.
e.g. true
state*stringThe billable state.
one of: BILLABLE · PENDING · NOT_BILLABLE
e.g. BILLABLE
reason*stringWhy, as a stable code: for example answered, payer_rejected_patient, payer_unavailable, cache_hit, test_mode or under_review. The full list is in the Pricing and what's charged guide.
e.g. answered
label*stringA short plain label for the reason.
e.g. Payer answered
reason_label*stringOne plain sentence saying whether and why the check is charged.
e.g. The payer answered this check; checks the payer answers are charged
unit_price_microsintegerAlways null in lists. Read the single check for its price.
source*objectWhere the answer came from.
network*stringAlways claimhouse.
e.g. claimhouse
referencestringThe network's transaction id. Null when none was read.
mode*stringThe mode the check ran in.
one of: test · production
e.g. production
subscriber*objectThe subscriber named on the request.
first_namestringFirst name as sent.
e.g. Jane
last_namestringLast name as sent.
e.g. Testpatient
date_of_birthdateDate of birth as sent.
e.g. 1980-01-15
member_idstringMember id as sent. Null when not sent.
e.g. SYN000123456
patientobjectThe dependent named on the request. Null when relationship is self.
first_namestringFirst name as sent.
e.g. Sam
last_namestringLast name as sent.
e.g. Testpatient
date_of_birthdateDate of birth as sent.
e.g. 2015-01-01
batch_idstringThe batch that made this check. Null for a single check. When a later batch replays a check an earlier batch made, the check keeps the first batch.
referencestringYour own id for the row: the same value as tenant_reference.
nextstringPass as before to read the next page. Set only when this page is full, so the next page can be empty. Null when the page is not full.

Responses

200OK
{
  "request_id": "evt_v2d5abcabd28samwxfsk",
  "results": [
    {
      "eligibility_id": "elg_skvgqer72n4zf02jz5rb",
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "payer_id": "TESTPAYER1",
      "relationship": "child",
      "service_date": "2026-09-07",
      "status": "ACTIVE",
      "outcome": "OK",
      "error_class": null,
      "vendor_latency_ms": 1840,
      "tenant_reference": "visit-0002",
      "retrieved_at": "2026-09-07T15:00:10+00:00",
      "rejection_summary": null,
      "billing": {
        "charged": true,
        "state": "BILLABLE",
        "reason": "answered",
        "label": "Payer answered",
        "reason_label": "The payer answered this check; checks the payer answers are charged",
        "unit_price_micros": null
      },
      "source": {
        "network": "claimhouse",
        "reference": "txn-EXAMPLE-0002"
      },
      "mode": "production",
      "subscriber": {
        "first_name": "Jane",
        "last_name": "Testpatient",
        "date_of_birth": "1980-01-15",
        "member_id": "SYN000123456"
      },
      "patient": {
        "first_name": "Sam",
        "last_name": "Testpatient",
        "date_of_birth": "2015-01-01"
      }
    },
    {
      "eligibility_id": "elg_6zm731h2sd161402r84g",
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "payer_id": "TESTPAYER1",
      "relationship": "self",
      "service_date": "2026-09-07",
      "status": "ACTIVE",
      "outcome": "OK",
      "error_class": null,
      "vendor_latency_ms": 1320,
      "tenant_reference": "visit-0001",
      "retrieved_at": "2026-09-07T15:00:00+00:00",
      "rejection_summary": null,
      "billing": {
        "charged": true,
        "state": "BILLABLE",
        "reason": "answered",
        "label": "Payer answered",
        "reason_label": "The payer answered this check; checks the payer answers are charged",
        "unit_price_micros": null
      },
      "source": {
        "network": "claimhouse",
        "reference": "txn-EXAMPLE-0001"
      },
      "mode": "production",
      "subscriber": {
        "first_name": "Jane",
        "last_name": "Testpatient",
        "date_of_birth": "1980-01-15",
        "member_id": "SYN000123456"
      },
      "patient": null
    }
  ],
  "next": null
}
200One batch checks (batch_id filter), executed local Test scenario, synthetic patients and ids
{
  "livemode": false,
  "request_id": "evt_wtj0gxbg6s4jdf8hmcnh",
  "results": [
    {
      "eligibility_id": "elg_t1daeb0bhh3q5czrxvx2",
      "facility_id": "fac_sandboxbatchsandbx",
      "payer_id": "94276",
      "relationship": "self",
      "service_date": "2026-09-07",
      "status": "UNKNOWN",
      "outcome": "VENDOR_ERROR",
      "error_class": "VENDOR_REJECTED",
      "vendor_latency_ms": 230,
      "tenant_reference": "appt-1004",
      "retrieved_at": "2026-09-07T15:00:00+00:00",
      "rejection_summary": "The payer is not answering right now. Try again in a few minutes; nothing needs to change.",
      "billing": {
        "charged": false,
        "state": "NOT_BILLABLE",
        "reason": "test_mode",
        "label": "Test mode",
        "reason_label": "Test mode checks never reach a payer and are never charged",
        "unit_price_micros": null
      },
      "source": {
        "network": "claimhouse",
        "reference": "test-smp_magic_aaa_42_once"
      },
      "mode": "test",
      "subscriber": {
        "first_name": "Sample",
        "last_name": "Subscriber",
        "date_of_birth": "1985-07-07",
        "member_id": "CH-AAA-42-ONCE"
      },
      "patient": null,
      "batch_id": "bat_4eghyt58pn73b6ezzxy2",
      "reference": "appt-1004"
    },
    {
      "eligibility_id": "elg_pr6kqzt8696yz41d720w",
      "facility_id": "fac_sandboxbatchsandbx",
      "payer_id": "94276",
      "relationship": "self",
      "service_date": "2026-09-07",
      "status": "INACTIVE",
      "outcome": "OK",
      "error_class": null,
      "vendor_latency_ms": 180,
      "tenant_reference": "appt-1002",
      "retrieved_at": "2026-09-07T15:00:00+00:00",
      "rejection_summary": null,
      "billing": {
        "charged": false,
        "state": "NOT_BILLABLE",
        "reason": "test_mode",
        "label": "Test mode",
        "reason_label": "Test mode checks never reach a payer and are never charged",
        "unit_price_micros": null
      },
      "source": {
        "network": "claimhouse",
        "reference": null
      },
      "mode": "test",
      "subscriber": {
        "first_name": "Sample",
        "last_name": "Subscriber",
        "date_of_birth": "1975-06-15",
        "member_id": "CH-TERMINATED"
      },
      "patient": null,
      "batch_id": "bat_4eghyt58pn73b6ezzxy2",
      "reference": "appt-1002"
    },
    {
      "eligibility_id": "elg_de0skc6wkd6kv70zeyxv",
      "facility_id": "fac_sandboxbatchsandbx",
      "payer_id": "94276",
      "relationship": "self",
      "service_date": "2026-09-07",
      "status": "ACTIVE",
      "outcome": "OK",
      "error_class": null,
      "vendor_latency_ms": 320,
      "tenant_reference": "appt-1001",
      "retrieved_at": "2026-09-07T15:00:00+00:00",
      "rejection_summary": null,
      "billing": {
        "charged": false,
        "state": "NOT_BILLABLE",
        "reason": "test_mode",
        "label": "Test mode",
        "reason_label": "Test mode checks never reach a payer and are never charged",
        "unit_price_micros": null
      },
      "source": {
        "network": "claimhouse",
        "reference": "test-smp_magic_active_full"
      },
      "mode": "test",
      "subscriber": {
        "first_name": "Sample",
        "last_name": "Subscriber",
        "date_of_birth": "1980-01-31",
        "member_id": "CH-ACTIVE-FULL"
      },
      "patient": null,
      "batch_id": "bat_4eghyt58pn73b6ezzxy2",
      "reference": "appt-1001"
    }
  ],
  "next": null
}
403Office not granted
{
  "error": "FACILITY_NOT_GRANTED",
  "message": "this key's grants do not cover that facility",
  "errors": [
    {
      "facility_id": "fac_w9qxypnbcw7b308jbbhh"
    }
  ],
  "request_id": "evt_zejc8pc58d7xfd2fntvw",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-facility-not-granted",
  "user_message": "Your account does not have access to this office."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks read
403FEATURE_NOT_ENTITLEDYour account is not enrolled for eligibility
403FACILITY_NOT_GRANTEDA facility_id is not covered by the key's grants, or the key has no office grants
422INVALID_CURSORbefore does not start with a valid timestamp
422INVALID_REQUESTstatus is not an allowed value, limit is out of range, since is not an ISO 8601 time, or a parameter is too long
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
InfoAn API key sees only checks made in its own mode: a test key lists test checks, a production key lists live checks. A dashboard session sees each office in that office's mode.
InfoWith a seller wide key, a facility_id that is not one of your offices is not refused. It simply returns no rows.
InfoA test mode check always carries billing.reason test_mode and is never charged.
API reference

List test sample patients

GEThttps://api.claimhouse.ai/v1/test/samples

List the synthetic sample patients and magic member ids that test mode answers, each labeled with the outcome it produces.

Use it in test mode to pick a patient for a test eligibility check. Every person here is synthetic.

payers lists sample patients by payer. Each patient names its eligibility scenario, the outcome a check produces, and claim_outcome, what the test payer does with a test claim for that patient (test claims are not yet published).

scenarios lists the magic member ids. Send one as the subscriber member id on a test check, with any name and date of birth, to get that scenario's answer, or name one in the X-Test-Scenario header to answer a sample patient as that scenario.

Test mode only. A live key or a live dashboard session is refused with 403 TEST_MODE_ONLY.

Permission
read
Idempotency
none
Side effects
Records one audit entry. No vendor call.
In the dashboard
Eligibility > New check (Load a sample, test mode)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Request example

null

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000401
livemode*booleanAlways false: this route answers in test mode only.
e.g. false
payers*arrayThe sample patients by payer. Today 5 payers with 20 patients each.
payer_id*stringPayer id to send on a test check.
e.g. 94276
name*stringPayer display name.
e.g. Delta Dental
patients*arrayOne entry per sample patient.
sample_id*stringThe sample id, smp_<payer id>_<name>. Stable.
e.g. smp_94276_full
scenario*stringThe eligibility scenario key.
e.g. active_full
scenario_number*stringThe scenario's number in the test scenario list.
e.g. E1
magic_member_id*stringThe magic member id for the same scenario.
e.g. CH-ACTIVE-FULL
label*stringA short plain label for the scenario.
e.g. Active, full benefits
outcome*stringWhat a test check for this patient does, in plain words, for example succeeds, payer rejects or retry, free.
e.g. succeeds
outcome_tone*stringThe outcome as a stable tone.
one of: success · inactive · rejected · retry
claim_outcome*stringWhat the test payer does with a test claim for this patient.
one of: paid_full · contractual · frequency_denial · xray_requested · rejected
claim_outcome_label*stringA short plain label for claim_outcome.
e.g. Paid in full
relationship*stringself when the patient is the subscriber, else child.
one of: self · child
subscriber*objectThe synthetic subscriber.
first_name*stringSynthetic first name.
e.g. Avery
last_name*stringSynthetic last name.
e.g. Molar
member_id*stringSynthetic member id. Send it as the subscriber member id on a test check.
e.g. TEST9427601
date_of_birth*dateSynthetic date of birth.
e.g. 1970-01-10
dependentobjectThe synthetic dependent patient. Null when the patient is the subscriber.
first_name*stringSynthetic first name.
e.g. Mia
last_name*stringSynthetic last name.
e.g. Bridge
date_of_birth*dateSynthetic date of birth.
e.g. 2014-03-05
scenarios*arrayEvery magic member id, one per scenario, plus CH-RATE-LIMIT. Today 34 entries. Test outcomes renders the same table.
member_id*stringThe magic member id. Matched without regard to case.
e.g. CH-ACTIVE-FULL
scenario*stringThe scenario key.
e.g. active_full
scenario_number*stringThe scenario's number. Empty for CH-RATE-LIMIT.
e.g. E1
label*stringA short plain label.
e.g. Active, full benefits
outcome*stringWhat a test check with this member id does, in plain words.
e.g. succeeds
http_status*integerThe HTTP status a check with this member id returns.
errorstringThe error code it returns. Null for an answer.
resultstringThe coverage status of an answer. Null for an error.
one of: ACTIVE · INACTIVE
catalog*booleanTrue when the scenario also has sample patients in payers.
aliases*arrayArray of strings. Other magic member ids for the same scenario, for example CH-AAA-75.
note*stringA plain note. Empty when there is none.

Responses

200OK (shortened to one payer, two patients and three scenarios)
{
  "livemode": false,
  "request_id": "evt_q0wd9p8rgs4efe7evt1c",
  "payers": [
    {
      "payer_id": "94276",
      "name": "Delta Dental",
      "patients": [
        {
          "sample_id": "smp_94276_full",
          "scenario": "active_full",
          "scenario_number": "E1",
          "magic_member_id": "CH-ACTIVE-FULL",
          "label": "Active, full benefits",
          "outcome": "succeeds",
          "outcome_tone": "success",
          "claim_outcome": "paid_full",
          "claim_outcome_label": "Paid in full",
          "relationship": "self",
          "subscriber": {
            "first_name": "Avery",
            "last_name": "Molar",
            "member_id": "TEST9427601",
            "date_of_birth": "1970-01-10"
          },
          "dependent": null
        },
        {
          "sample_id": "smp_94276_dependent",
          "scenario": "dependent_age_26",
          "scenario_number": "E7",
          "magic_member_id": "CH-DEP-AGE-26",
          "label": "Dependent child, covered to 26",
          "outcome": "succeeds",
          "outcome_tone": "success",
          "claim_outcome": "paid_full",
          "claim_outcome_label": "Paid in full",
          "relationship": "child",
          "subscriber": {
            "first_name": "Casey",
            "last_name": "Bridge",
            "member_id": "TEST9427605",
            "date_of_birth": "1974-05-10"
          },
          "dependent": {
            "first_name": "Mia",
            "last_name": "Bridge",
            "date_of_birth": "2014-03-05"
          }
        }
      ]
    }
  ],
  "scenarios": [
    {
      "member_id": "CH-ACTIVE-FULL",
      "scenario": "active_full",
      "scenario_number": "E1",
      "label": "Active, full benefits",
      "outcome": "succeeds",
      "http_status": 200,
      "error": null,
      "result": "ACTIVE",
      "catalog": true,
      "aliases": [],
      "note": ""
    },
    {
      "member_id": "CH-AAA-71",
      "scenario": "aaa_71",
      "scenario_number": "E14",
      "label": "Birth date mismatch (71)",
      "outcome": "payer rejects",
      "http_status": 422,
      "error": "PAYER_REJECTED",
      "result": null,
      "catalog": true,
      "aliases": [],
      "note": ""
    },
    {
      "member_id": "CH-RATE-LIMIT",
      "scenario": "rate_limit",
      "scenario_number": "",
      "label": "Rate limited (429)",
      "outcome": "429 at once; retry after the Retry-After seconds",
      "http_status": 429,
      "error": "TOO_MANY_REQUESTS",
      "result": null,
      "catalog": false,
      "aliases": [],
      "note": "Nothing is counted or written."
    }
  ]
}
403Live mode
{
  "livemode": true,
  "error": "TEST_MODE_ONLY",
  "message": "sample patients are available in test mode only",
  "errors": [],
  "request_id": "evt_ahqzytm9694fk55e1r3j",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-test-mode-only",
  "user_message": "This is available in test mode only."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks read
403FEATURE_NOT_ENTITLEDYour account is not enrolled for eligibility
403TEST_MODE_ONLYThe key or dashboard session is in live mode
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
429TEST_LIMIT_REACHEDOver the test mode limit of requests a second for your organization (10 unless Claim House raised it)
InfoThe catalog is fixed and the same for every organization. Sample ids and magic member ids are stable, so you can hard code them in integration tests.
InfoA test check for anyone who is not a sample patient and has no magic member id is refused with 422 NOT_A_TEST_PATIENT. Test mode never sends a real patient to a payer.
InfoCH-RATE-LIMIT has no sample patient. A test check with it answers 429 at once; retry after the Retry-After seconds.
InfoOffice grants are not applied: every key with read gets the whole catalog, and 403 FACILITY_NOT_GRANTED is never returned.
API reference

Payers

Look up which payers Claim House knows, which transactions each supports, and which attachment doors each accepts.

The payer registry is global: every account sees the same records, and payer routes have no office scope.

RouteAccepts
GET /v1/payers/{payer_id}/healthPrimary id, internal id or alias
GET /v1/payers/{payer_id}/doorsPrimary id only
POST /v1/eligibilityA Claim House payer id, the primary id, your practice system's payer id or the insurance name; when unsure it answers 409 PAYER_CHOICE_REQUIRED with candidates
Attachment packet send and draftsPrimary id only
POST /v1/dental-claims/submissionThe claims payer ID only, as sent (never translated through an alias), or payerMapping
InfoPass primaryPayerId everywhere unless a route says otherwise. Store payerId as your database key: it never changes.
  • transactionSupport describes the payer as the network lists it. Prefer transaction_support: it says what works through Claim House today, per transaction, as SUPPORTED, ENROLLMENT_REQUIRED, NOT_SUPPORTED or COMING_SOON (the payer takes it and the Claim House product for it is not released yet).
  • transaction_support.eligibility is SUPPORTED exactly when Claim House can route a check to the payer by its id. A payer that is NOT_SUPPORTED can still match by insurance name, and the check may answer 409 PAYER_CHOICE_REQUIRED.
  • unsolicitedClaimAttachment: SUPPORTED does not guarantee a network_A send works: it also needs network_A in the door order and a network registration that no payer route exposes.

Enrollment

Eligibility needs no payer enrollment. Claims and remittances may: each payer record says so per transaction in enrollment_required. If a payer turns a check down because the provider is not on file or was not enrolled on the service date, the reason's next_step is COMPLETE_SETUP: confirm the provider's enrollment with that payer.

A claim is billed to the claims payer ID it names. A listed payer ID is sent as given. An ID the claims network does not list, or no ID, is corrected only when the evidence proves the payer, and the claim says what was corrected; otherwise the claim waits with the right payer named. Confirm a carrier once with POST /v1/payer-mapping/claims/confirm.

Payer statistics and health

stats on each payer and GET /v1/payers/{payer_id}/health are Claim House's own numbers, across every customer, and never one organization's. They are rounded and hidden below 20 checks. Answered means the payer gave a definitive answer, including "member not found". Use health before you retry or open a ticket: a high payer_unavailable_rate in the last hour means the payer is down for everyone, so wait and check again later (next_step: NEW_CHECK_LATER); a normal rate means the problem is more likely in the request.

accepted_searches says which identifier combinations a payer accepts and how we know (PAYER_GUIDE, OBSERVED or UNKNOWN). Today every check still requires the member ID: these say what the payer accepts, not what the API accepts yet.

ImportantPer payer documentation requirements by CDT code have no public route yet. Missing documentation is only reported at attachment validate and send time as 422 DOCUMENTATION_RULE_UNMET.
InfoA claim is billed to the claims payer ID it names, and Claim House never changes it. An ID from another clearinghouse, or a payer name that fits another payer, holds the claim with suggestions; confirm the carrier once per office with POST /v1/payer-mapping/claims/confirm.
API reference

Search payers

GEThttps://api.claimhouse.ai/v1/payers/search

Find payers by name, id, alias, transaction or state, with what each supports and how it is answering.

Use it for a payer picker. Send at least one of q, transaction and state. q matches display name, every name variant, primary payer id and alias, case insensitively; % and _ are literal characters.

Order: an exact match on id, alias or name; then a name prefix; then a word in the name; then the rest. Within each, payers busier on Claim House first, then by name. At most 50 payers, with no paging.

Permission
read
Idempotency
none
Side effects
Writes an audit read row. No vendor call.
In the dashboard
Eligibility > New check (payer search)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Query parameters

NameTypeDescription
qstringSearch text, 2 to 120 characters.
e.g. cigna
transactionstringKeep payers that take this transaction through Claim House now (SUPPORTED or ENROLLMENT_REQUIRED). claims returns nothing until claims are released.
one of: eligibility · claims · claim_status · remittance · attachments
statestringTwo letters, any case. Keeps payers tied to that state and payers not tied to a region.
e.g. FL

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id.
payers*arrayMatching payer records. Empty when nothing matches (never 404).
payerId*stringImmutable internal id. Use it as your database key.
displayName*stringName to show.
primaryPayerId*stringThe id to show and to send on claims, eligibility and attachments.
aliases*arrayArray of strings. Other ids that resolve to this payer.
names*arrayArray of strings. Known names. Falls back to [displayName].
transactionSupport*objectSupport level per transaction.
eligibilityCheck*stringEligibility checks.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED
claimStatus*stringClaim status.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED
dentalClaimSubmission*stringDental claim submission.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED
claimPayment*string835 remittances. Never SUPPORTED unless set explicitly, since an 835 needs ERA enrollment.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED
unsolicitedClaimAttachment*stringAttachments sent after the claim.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED
coverageTypes*arrayArray of strings. Falls back to ["dental"].
attachmentDoors*arrayArray of strings. The payer's attachment door order, for example ["network_A", "paper"]. Empty when the payer has no routing.
eraEnrollmentCodestringERA enrollment code. Null when none.
paperEobShutoffbooleanWhether paper EOBs stop after ERA enrollment. Null when unknown.
transaction_support*objectWhat works through Claim House today, per transaction. Prefer it to transactionSupport.
eligibility*stringSUPPORTED exactly when Claim House can route a check to the payer by its id.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON
claims*stringDental claims. COMING_SOON while claims are not released.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON
claim_status*stringClaim status.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON
remittance*stringRemittances (835). COMING_SOON while payments are not released.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON
attachments*stringAttachments.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON
enrollment_required*objectPer transaction (eligibility, claims, claim_status, remittance, attachments), true when the provider must enroll with the payer first. Eligibility needs no enrollment. Shown for unreleased products too.
states*arrayArray of strings. Two-letter codes a regional payer is tied to. Empty means not tied to one region in our data.
accepted_searches*arrayWhich identifier combinations the payer accepts. Today every check still requires the member ID: these say what the payer accepts, not what the API accepts yet.
search*stringThe combination.
one of: MEMBER_ID_NAME_DOB · MEMBER_ID_DOB · NAME_DOB_ONLY · SSN_AS_MEMBER_ID · SSN_WITH_NAME_OR_DOB
source*stringPAYER_GUIDE (the payer's published guide), OBSERVED (Claim House customers got at least 20 answers with this search in 30 days) or UNKNOWN (no evidence yet; the standard member ID search is listed).
one of: PAYER_GUIDE · OBSERVED · UNKNOWN
citation_urlstringThe payer's published guide, when public. Null otherwise.
notestringA plain note on the source.
stats*objectThe last 30 days of Claim House production eligibility checks to the payer, every customer together. Every number is null below 20 checks.
eligibility_answered_rate_30dnumber0 to 1, two decimals. Answered includes "member not found".
eligibility_median_latency_ms_30dintegerMedian time to an answer, rounded to 100 ms.
checks_30dintegerChecks counted, rounded down to tens.
minimum_sample*integer20: below it, every number is null.

Responses

200Search q=cigna, transaction=eligibility, state=FL: executed local run, synthetic usage
{
  "request_id": "evt_cz8r87frpd2bba03a233",
  "payers": [
    {
      "payerId": "pay_cigna",
      "displayName": "Cigna Dental",
      "primaryPayerId": "62308",
      "aliases": [],
      "names": [
        "Cigna Dental"
      ],
      "transactionSupport": {
        "eligibilityCheck": "SUPPORTED",
        "claimStatus": "NOT_SUPPORTED",
        "dentalClaimSubmission": "SUPPORTED",
        "claimPayment": "ENROLLMENT_REQUIRED",
        "unsolicitedClaimAttachment": "NOT_SUPPORTED"
      },
      "coverageTypes": [
        "dental"
      ],
      "attachmentDoors": [],
      "eraEnrollmentCode": "S",
      "paperEobShutoff": null,
      "transaction_support": {
        "eligibility": "SUPPORTED",
        "claims": "COMING_SOON",
        "claim_status": "NOT_SUPPORTED",
        "remittance": "COMING_SOON",
        "attachments": "NOT_SUPPORTED"
      },
      "enrollment_required": {
        "eligibility": false,
        "claims": false,
        "claim_status": false,
        "remittance": true,
        "attachments": false
      },
      "states": [],
      "accepted_searches": [
        {
          "search": "MEMBER_ID_NAME_DOB",
          "source": "PAYER_GUIDE",
          "citation_url": "https://www.cigna.com/static/www-cigna-com/docs/5010-270-271-companion-guide.pdf",
          "note": "First step of the payer's search order."
        },
        {
          "search": "NAME_DOB_ONLY",
          "source": "PAYER_GUIDE",
          "citation_url": "https://www.cigna.com/static/www-cigna-com/docs/5010-270-271-companion-guide.pdf",
          "note": "First name, last name and date of birth is the third step of the payer's search order."
        },
        {
          "search": "MEMBER_ID_DOB",
          "source": "PAYER_GUIDE",
          "citation_url": "https://www.cigna.com/static/www-cigna-com/docs/5010-270-271-companion-guide.pdf",
          "note": "Member ID with date of birth is the last step of the payer's search order."
        }
      ],
      "stats": {
        "eligibility_answered_rate_30d": 0.94,
        "eligibility_median_latency_ms_30d": 1200,
        "checks_30d": 30,
        "minimum_sample": 20
      }
    }
  ]
}
422No filter sent
{
  "livemode": true,
  "error": "VALIDATION",
  "message": "send q, transaction or state",
  "errors": [],
  "request_id": "evt_jjkvebq5ph71qexe1ztj",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-validation",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}
422Query too short
{
  "error": "INVALID_REQUEST",
  "message": "the request body is not valid",
  "errors": [
    {
      "code": "string_too_short",
      "location": "query.q",
      "message": "String should have at least 2 characters",
      "value_redacted": true
    }
  ],
  "request_id": "evt_tsp30zyjmerzr3c6sxvj",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-invalid-request",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks read
422VALIDATIONNone of q, transaction and state was sent, or state is not a US state or territory code
422INVALID_REQUESTq shorter than 2 or longer than 120, or an unknown transaction
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
InfoPayer transaction support describes the payer, not which Claim House products are released. Claims, attachments and remittances remain Coming soon.
API reference

Get a payer's health

GEThttps://api.claimhouse.ai/v1/payers/{payer_id}/health

Answered rate and payer unavailable rate over the last hour and day, so you can tell a payer outage from a problem in your request.

Use it before you retry or open a ticket. A high payer_unavailable_rate in the last hour means the payer is down for everyone: wait and check again later (next_step: NEW_CHECK_LATER). A normal rate means the problem is more likely in the request.

The numbers are Claim House's own production eligibility checks, across every customer and never one organization's: rounded, and null below 20 checks in a window. Counts are cached up to 60 seconds.

Permission
read
Idempotency
safe to repeat
Side effects
Writes an audit read row naming the payer. No vendor call.
In the dashboard
None yet

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Path parameters

NameTypeDescription
payer_id*stringThe payer's primary id, internal id or alias (exact). An alias two payers share is 409 PAYER_AMBIGUOUS.
e.g. 62308

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id.
payer_id*stringThe payer's primary id.
display_name*stringThe payer's name.
transaction*stringAlways eligibility today.
one of: eligibility
eligibility*stringThe payer's transaction_support.eligibility.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON
measured*booleanFalse when Claim House cannot read its own outcomes right now, or the payer has no eligibility route; every number is then null. Never read a missing number as zero.
minimum_sample*integer20: a window with fewer checks shows no numbers.
windows*objectlast_hour and last_day, each with the fields below.
checksintegerChecks counted, rounded down to tens.
answered_ratenumber0 to 1. Answered means the payer gave a definitive answer, including "member not found".
payer_unavailable_ratenumber0 to 1: the payer said it cannot respond now (X12 AAA 42 or 80), answered payer down, timed out or dropped the connection.
median_latency_msintegerMedian time of answered checks, rounded to 100 ms.
sufficient_sample*booleanTrue when the window has at least minimum_sample checks.

Responses

200OK: executed local run, synthetic usage
{
  "request_id": "evt_s24w6n4khh2h51t01eag",
  "payer_id": "62308",
  "display_name": "Cigna Dental",
  "transaction": "eligibility",
  "eligibility": "SUPPORTED",
  "measured": true,
  "minimum_sample": 20,
  "windows": {
    "last_hour": {
      "checks": 30,
      "answered_rate": 0.94,
      "payer_unavailable_rate": 0.06,
      "median_latency_ms": 1200,
      "sufficient_sample": true
    },
    "last_day": {
      "checks": 30,
      "answered_rate": 0.94,
      "payer_unavailable_rate": 0.06,
      "median_latency_ms": 1200,
      "sufficient_sample": true
    }
  }
}
200Fewer than 20 checks: no numbers
{
  "livemode": true,
  "request_id": "evt_7wmsetwsch44n14jne3g",
  "payer_id": "FULLPAYER",
  "display_name": "Full Dental Plan",
  "transaction": "eligibility",
  "eligibility": "SUPPORTED",
  "measured": true,
  "minimum_sample": 20,
  "windows": {
    "last_hour": {
      "checks": null,
      "answered_rate": null,
      "payer_unavailable_rate": null,
      "median_latency_ms": null,
      "sufficient_sample": false
    },
    "last_day": {
      "checks": null,
      "answered_rate": null,
      "payer_unavailable_rate": null,
      "median_latency_ms": null,
      "sufficient_sample": false
    }
  }
}
404No such payer
{
  "livemode": true,
  "error": "NOT_FOUND",
  "message": "no such payer",
  "errors": [],
  "request_id": "evt_hn4n6gkmsx7kx3mc7bdy",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-not-found",
  "user_message": "We could not find that item. It may have been removed, or you may not have access to it."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks read
404NOT_FOUNDNo payer has this id or alias
409PAYER_AMBIGUOUSThe alias belongs to more than one payer; send the primary id
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
InfoReference data: the same in test and live mode, for every key with read, and always on.
API reference

List payers

GEThttps://api.claimhouse.ai/v1/payers

Page through the whole payer registry, or download it as one CSV file.

Use it to sync the registry into your system. JSON pages are ordered by internal id; pass nextPageToken back as pageToken until it is null.

format=csv returns one text/csv file named payers.csv instead, with one row per payer.

Permission
read
Idempotency
none
Side effects
Writes an audit read row. No vendor call.
In the dashboard
Payers directory, Attachments > New attachment (payer select)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Query parameters

NameTypeDescription
formatstringResponse format. Default json.
one of: json · csv
e.g. json
pageTokenstringThe nextPageToken from the previous page, at most 200 characters. Ignored for CSV.
pageSizeintegerPayers per page, 10 to 50. Default 50. Ignored for CSV.
e.g. 10

Request example

null

Response fields

NameTypeDescription
payers*arrayPayer records for this page.
payerId*stringImmutable internal id. Use it as your database key.
displayName*stringName to show.
primaryPayerId*stringThe id to show and to send on claims, eligibility and attachments.
aliases*arrayArray of strings. Other ids that resolve to this payer.
names*arrayArray of strings. Known names. Falls back to [displayName].
transactionSupport*objectSupport level per transaction.
eligibilityCheck*stringEligibility checks.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED
claimStatus*stringClaim status.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED
dentalClaimSubmission*stringDental claim submission.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED
claimPayment*string835 remittances. Never SUPPORTED unless set explicitly, since an 835 needs ERA enrollment.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED
unsolicitedClaimAttachment*stringAttachments sent after the claim.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED
coverageTypes*arrayArray of strings. Falls back to ["dental"].
attachmentDoors*arrayArray of strings. The payer's attachment door order, for example ["network_A", "paper"]. Empty when the payer has no routing.
eraEnrollmentCodestringERA enrollment code. Null when none.
paperEobShutoffbooleanWhether paper EOBs stop after ERA enrollment. Null when unknown.
transaction_support*objectWhat works through Claim House today, per transaction. Prefer it to transactionSupport.
eligibility*stringSUPPORTED exactly when Claim House can route a check to the payer by its id.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON
claims*stringDental claims. COMING_SOON while claims are not released.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON
claim_status*stringClaim status.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON
remittance*stringRemittances (835). COMING_SOON while payments are not released.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON
attachments*stringAttachments.
one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON
enrollment_required*objectPer transaction (eligibility, claims, claim_status, remittance, attachments), true when the provider must enroll with the payer first. Eligibility needs no enrollment. Shown for unreleased products too.
states*arrayArray of strings. Two-letter codes a regional payer is tied to. Empty means not tied to one region in our data.
accepted_searches*arrayWhich identifier combinations the payer accepts. Today every check still requires the member ID: these say what the payer accepts, not what the API accepts yet.
search*stringThe combination.
one of: MEMBER_ID_NAME_DOB · MEMBER_ID_DOB · NAME_DOB_ONLY · SSN_AS_MEMBER_ID · SSN_WITH_NAME_OR_DOB
source*stringPAYER_GUIDE (the payer's published guide), OBSERVED (Claim House customers got at least 20 answers with this search in 30 days) or UNKNOWN (no evidence yet; the standard member ID search is listed).
one of: PAYER_GUIDE · OBSERVED · UNKNOWN
citation_urlstringThe payer's published guide, when public. Null otherwise.
notestringA plain note on the source.
stats*objectThe last 30 days of Claim House production eligibility checks to the payer, every customer together. Every number is null below 20 checks.
eligibility_answered_rate_30dnumber0 to 1, two decimals. Answered includes "member not found".
eligibility_median_latency_ms_30dintegerMedian time to an answer, rounded to 100 ms.
checks_30dintegerChecks counted, rounded down to tens.
minimum_sample*integer20: below it, every number is null.
nextPageTokenstringToken for the next page. Null on the last page.

Responses

200OK
{
  "payers": [
    {
      "payerId": "pay_second",
      "displayName": "Second Test Plan",
      "primaryPayerId": "TESTPAYER2",
      "aliases": [],
      "names": [
        "Second Test Plan"
      ],
      "transactionSupport": {
        "eligibilityCheck": "NOT_SUPPORTED",
        "claimStatus": "SUPPORTED",
        "dentalClaimSubmission": "SUPPORTED",
        "claimPayment": "NOT_SUPPORTED",
        "unsolicitedClaimAttachment": "NOT_SUPPORTED"
      },
      "coverageTypes": [
        "dental"
      ],
      "attachmentDoors": [],
      "eraEnrollmentCode": null,
      "paperEobShutoff": null,
      "transaction_support": {
        "eligibility": "NOT_SUPPORTED",
        "claims": "COMING_SOON",
        "claim_status": "COMING_SOON",
        "remittance": "NOT_SUPPORTED",
        "attachments": "NOT_SUPPORTED"
      },
      "enrollment_required": {
        "eligibility": false,
        "claims": false,
        "claim_status": false,
        "remittance": false,
        "attachments": false
      },
      "states": [],
      "accepted_searches": [
        {
          "search": "MEMBER_ID_NAME_DOB",
          "source": "UNKNOWN",
          "citation_url": null,
          "note": null
        }
      ],
      "stats": {
        "eligibility_answered_rate_30d": null,
        "eligibility_median_latency_ms_30d": null,
        "checks_30d": null,
        "minimum_sample": 20
      }
    },
    {
      "payerId": "pay_test",
      "displayName": "Test Dental Plan",
      "primaryPayerId": "TESTPAYER1",
      "aliases": [
        "TDP"
      ],
      "names": [
        "Test Dental Plan",
        "TDP of Testland"
      ],
      "transactionSupport": {
        "eligibilityCheck": "SUPPORTED",
        "claimStatus": "NOT_SUPPORTED",
        "dentalClaimSubmission": "ENROLLMENT_REQUIRED",
        "claimPayment": "ENROLLMENT_REQUIRED",
        "unsolicitedClaimAttachment": "SUPPORTED"
      },
      "coverageTypes": [
        "dental"
      ],
      "attachmentDoors": [
        "network_A",
        "portal"
      ],
      "eraEnrollmentCode": "S",
      "paperEobShutoff": true,
      "transaction_support": {
        "eligibility": "NOT_SUPPORTED",
        "claims": "COMING_SOON",
        "claim_status": "NOT_SUPPORTED",
        "remittance": "COMING_SOON",
        "attachments": "COMING_SOON"
      },
      "enrollment_required": {
        "eligibility": false,
        "claims": true,
        "claim_status": false,
        "remittance": true,
        "attachments": false
      },
      "states": [],
      "accepted_searches": [
        {
          "search": "MEMBER_ID_NAME_DOB",
          "source": "UNKNOWN",
          "citation_url": null,
          "note": null
        }
      ],
      "stats": {
        "eligibility_answered_rate_30d": null,
        "eligibility_median_latency_ms_30d": null,
        "checks_30d": null,
        "minimum_sample": 20
      }
    }
  ],
  "nextPageToken": null
}
422Page size out of range
{
  "error": "INVALID_REQUEST",
  "message": "the request body is not valid",
  "errors": [
    {
      "code": "less_than_equal",
      "location": "query.pageSize",
      "message": "Input should be less than or equal to 50",
      "value_redacted": true
    }
  ],
  "request_id": "evt_be4nnzktd50qt0hta11z",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-invalid-request",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks read
422INVALID_REQUESTpageSize outside 10 to 50, unknown format, or pageToken too long
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
InfoThis route's JSON body has no request_id field. The X-Request-Id header is still set.
InfoCSV columns: payerId, displayName, primaryPayerId, aliases, names, eligibilityCheck, claimStatus, dentalClaimSubmission, claimPayment, unsolicitedClaimAttachment, coverageTypes, attachmentDoors, eraEnrollmentCode, paperEobShutoff. List values are joined with |; paperEobShutoff is true, false or empty.
ImportantThe CSV export stops at 10,000 payers and is silently truncated above that.
API reference

Get a payerComing soon

GEThttps://api.claimhouse.ai/v1/payers/{payer_id}

Read one payer record by exact primary id, internal id or alias.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get a payer's attachment doorsComing soon

GEThttps://api.claimhouse.ai/v1/payers/{payer_id}/doors

Read the doors a payer accepts attachments through, in the payer's order, with file limits per door.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get a payer's attachment profileComing soon

GEThttps://api.claimhouse.ai/v1/payers/{payer_id}/attachment-profile

Payer level attachment facts, without procedure codes.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

List a payer's attachment plansComing soon

GEThttps://api.claimhouse.ai/v1/payers/{payer_id}/attachment-plans

Plan names for the plan picker, when requirements differ by plan.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

List insurance mappings

GEThttps://api.claimhouse.ai/v1/payer-mapping/mappings

List how the insurance names and payer ids your offices typed map to catalog payers, and which ones still need a person to pick.

Every time an office types insurance text or a payer id, Claim House stores one mapping to a payer it can check eligibility with. Use this list for an insurance mapping screen: show NEEDS_CHOICE rows with their candidates, and confirm each once with POST /v1/payer-mapping/mappings/{mapping_id}/confirm.

Rows are ordered most recently updated first, with no paging. Organization wide and Claim House wide mappings are included with every office's list.

Permission
read
Idempotency
none
Side effects
Writes an audit read row. Never contacts a payer or the network.
In the dashboard
Settings > Insurance mapping

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Query parameters

NameTypeDescription
facility_idstringOnly mappings for this office, plus organization wide and Claim House wide mappings. Up to 64 characters. It must be an office in your account. Without it, every office.
e.g. fac_tycrfy0cs0qc7sq95eme
statestringOnly mappings in this state, up to 20 characters. Any other value returns no rows.
one of: EXACT · SUGGESTED · NEEDS_CHOICE · UNMAPPABLE · CONFIRMED · STALE
e.g. NEEDS_CHOICE

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id. The same value as the X-Request-Id header.
mappings*arrayMappings, most recently updated first. Empty when there are none.
mapping_id*stringThe mapping id: map_ plus 16 lowercase hex characters.
e.g. map_4b19b5ec72e122ec
scope*stringWho the mapping applies to. A new mapping is office. Confirming one also stores an organization copy for every office in your account. platform mappings are set by Claim House.
one of: office · organization · platform
e.g. office
state*stringEXACT: the input matched a catalog payer exactly. SUGGESTED: a likely payer that needs one confirmation. NEEDS_CHOICE: several or no payers fit, so a person must pick. UNMAPPABLE: not a payer Claim House can check eligibility with. CONFIRMED: a person or a payer answer confirmed it. STALE: the payer left the catalog; Claim House reviews it.
one of: EXACT · SUGGESTED · NEEDS_CHOICE · UNMAPPABLE · CONFIRMED · STALE
e.g. EXACT
reasonstringWhy the mapping is not exact, as a code, for example not_found, ambiguous, several_payers_match, checks_disagree, model_unavailable, cannot_tell or unsupported. Null when there is nothing to explain, and always null after a confirmation.
network_payer_idstringThe catalog payer id the mapping points to. Null while a choice is needed.
payer_namestringThe network's name for network_payer_id. Null when there is no payer or it is no longer in the catalog.
usable_for_eligibility*booleanTrue when a check can use this mapping: the state is EXACT, SUGGESTED, CONFIRMED or STALE and a payer is set.
needs_confirmation*booleanTrue only in state SUGGESTED: show the payer and ask the user to confirm it once.
resolved_bystringHow Claim House found the payer: payer_id, alternate_id, correction, exact_name or model. Null when no payer was found. Kept after a confirmation.
confirmed_bystringuser (this API or the dashboard), operator (Claim House) or payer_answer (a check through this mapping found the member). Null until confirmed.
confirmed_atdatetimeWhen it was confirmed. Null until confirmed.
candidates*arrayPayers offered for a choice, best first. Empty when there is nothing to choose. Kept after a confirmation.
payer_id*stringA catalog payer id you can confirm.
name*stringThe network's name for that payer id.
states*arrayArray of strings. Up to 12 two letter state codes the payer is filed under. Often empty.
why*stringWhy it was suggested, in plain words, for example similar words or matches the name.
probabilitynumberPresent only when the matching model scored this candidate. Rounded to 3 decimals.

Responses

200OK
{
  "request_id": "evt_1fzaj6804s7c90j3a0g3",
  "mappings": [
    {
      "mapping_id": "map_ee5e7c07e4accbcb",
      "scope": "organization",
      "state": "CONFIRMED",
      "reason": null,
      "network_payer_id": "DELTO",
      "payer_name": "Delta Dental of Ohio",
      "usable_for_eligibility": true,
      "needs_confirmation": false,
      "resolved_by": null,
      "confirmed_by": "user",
      "confirmed_at": "2026-09-28T16:40:41.894269+00:00",
      "candidates": [
        {
          "payer_id": "94276",
          "name": "Delta Dental - DDIC",
          "states": [],
          "why": "similar words"
        },
        {
          "payer_id": "DELTA",
          "name": "Delta Dental of Michigan",
          "states": [],
          "why": "similar words"
        },
        {
          "payer_id": "DELTO",
          "name": "Delta Dental of Ohio",
          "states": [],
          "why": "similar words"
        }
      ]
    },
    {
      "mapping_id": "map_4b19b5ec72e122ec",
      "scope": "office",
      "state": "CONFIRMED",
      "reason": null,
      "network_payer_id": "DELTO",
      "payer_name": "Delta Dental of Ohio",
      "usable_for_eligibility": true,
      "needs_confirmation": false,
      "resolved_by": null,
      "confirmed_by": "user",
      "confirmed_at": "2026-09-28T16:40:41.894269+00:00",
      "candidates": [
        {
          "payer_id": "94276",
          "name": "Delta Dental - DDIC",
          "states": [],
          "why": "similar words"
        },
        {
          "payer_id": "DELTA",
          "name": "Delta Dental of Michigan",
          "states": [],
          "why": "similar words"
        },
        {
          "payer_id": "DELTO",
          "name": "Delta Dental of Ohio",
          "states": [],
          "why": "similar words"
        }
      ]
    },
    {
      "mapping_id": "map_a8ada2b1781d4323",
      "scope": "office",
      "state": "EXACT",
      "reason": null,
      "network_payer_id": "94276",
      "payer_name": "Delta Dental - DDIC",
      "usable_for_eligibility": true,
      "needs_confirmation": false,
      "resolved_by": "alternate_id",
      "confirmed_by": null,
      "confirmed_at": null,
      "candidates": []
    }
  ]
}
404Unknown office
{
  "error": "NOT_FOUND",
  "message": "{'code': 'FACILITY_NOT_FOUND'}",
  "errors": [],
  "request_id": "evt_kvn7y3rzad1rna71wrjx",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-not-found",
  "user_message": "We could not find that item. It may have been removed, or you may not have access to it."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks read
404NOT_FOUNDfacility_id is not an office in your account. The message reads {'code': 'FACILITY_NOT_FOUND'}
422INVALID_REQUESTA parameter is too long
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
503REQUEST_REFUSEDPayer matching is not configured on this gateway. The message reads {'code': 'PAYER_MATCHING_UNAVAILABLE'}
ImportantRefusals raised by this route use the generic envelope codes NOT_FOUND (404) and REQUEST_REFUSED (other statuses). The specific reason, for example FACILITY_NOT_FOUND, appears only inside message, written as {'code': 'FACILITY_NOT_FOUND'}. Match on the status and error, and treat message as text.
ImportantOffice grants are not applied: facility_id only has to be an office in your account, and 403 FACILITY_NOT_GRANTED is never returned.
InfoA mapping does not name the office or repeat the text that was typed. Keep your own record of the input if you need it.
API reference

Confirm an insurance mapping

POSThttps://api.claimhouse.ai/v1/payer-mapping/mappings/{mapping_id}/confirm

Pick or confirm the catalog payer for one mapping. It becomes CONFIRMED and is remembered for every office in your account.

Use it when a mapping is NEEDS_CHOICE (pick one of candidates, or any catalog payer) or SUGGESTED (confirm the suggested payer). The payer must be in the eligibility catalog.

The mapping becomes CONFIRMED with confirmed_by user, reason null and the time. Claim House also stores an organization wide copy, so the same insurance typed at any of your offices maps the same way.

If your organization already has a confirmed mapping for the same insurance with a different payer, that one is kept, and Claim House opens a review instead of switching it.

Permission
submit
Idempotency
none
Side effects
Updates the mapping, may store an organization wide copy or open a Claim House review, and writes an audit row. Never contacts a payer or the network.
In the dashboard
Settings > Insurance mapping, Eligibility > New check (insurance choice)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret
Content-Type*stringMust be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.
e.g. application/json

Path parameters

NameTypeDescription
mapping_id*stringThe mapping id.
e.g. map_4b19b5ec72e122ec

Request body

NameTypeDescription
network_payer_id*stringThe catalog payer id to map to, 1 to 40 characters. Spaces around it are trimmed and it is uppercased before the check.
e.g. DELTO

Request example

{
  "network_payer_id": "DELTO"
}

Response fields

NameTypeDescription
request_id*stringRequest id. The same value as the X-Request-Id header.
mapping*objectThe mapping after the confirmation.
mapping_id*stringThe mapping id: map_ plus 16 lowercase hex characters.
e.g. map_4b19b5ec72e122ec
scope*stringWho the mapping applies to. A new mapping is office. Confirming one also stores an organization copy for every office in your account. platform mappings are set by Claim House.
one of: office · organization · platform
e.g. office
state*stringEXACT: the input matched a catalog payer exactly. SUGGESTED: a likely payer that needs one confirmation. NEEDS_CHOICE: several or no payers fit, so a person must pick. UNMAPPABLE: not a payer Claim House can check eligibility with. CONFIRMED: a person or a payer answer confirmed it. STALE: the payer left the catalog; Claim House reviews it.
one of: EXACT · SUGGESTED · NEEDS_CHOICE · UNMAPPABLE · CONFIRMED · STALE
e.g. EXACT
reasonstringWhy the mapping is not exact, as a code, for example not_found, ambiguous, several_payers_match, checks_disagree, model_unavailable, cannot_tell or unsupported. Null when there is nothing to explain, and always null after a confirmation.
network_payer_idstringThe catalog payer id the mapping points to. Null while a choice is needed.
payer_namestringThe network's name for network_payer_id. Null when there is no payer or it is no longer in the catalog.
usable_for_eligibility*booleanTrue when a check can use this mapping: the state is EXACT, SUGGESTED, CONFIRMED or STALE and a payer is set.
needs_confirmation*booleanTrue only in state SUGGESTED: show the payer and ask the user to confirm it once.
resolved_bystringHow Claim House found the payer: payer_id, alternate_id, correction, exact_name or model. Null when no payer was found. Kept after a confirmation.
confirmed_bystringuser (this API or the dashboard), operator (Claim House) or payer_answer (a check through this mapping found the member). Null until confirmed.
confirmed_atdatetimeWhen it was confirmed. Null until confirmed.
candidates*arrayPayers offered for a choice, best first. Empty when there is nothing to choose. Kept after a confirmation.
payer_id*stringA catalog payer id you can confirm.
name*stringThe network's name for that payer id.
states*arrayArray of strings. Up to 12 two letter state codes the payer is filed under. Often empty.
why*stringWhy it was suggested, in plain words, for example similar words or matches the name.
probabilitynumberPresent only when the matching model scored this candidate. Rounded to 3 decimals.

Responses

200OK
{
  "request_id": "evt_xxsf101bmd1qxbmysjgh",
  "mapping": {
    "mapping_id": "map_4b19b5ec72e122ec",
    "scope": "office",
    "state": "CONFIRMED",
    "reason": null,
    "network_payer_id": "DELTO",
    "payer_name": "Delta Dental of Ohio",
    "usable_for_eligibility": true,
    "needs_confirmation": false,
    "resolved_by": null,
    "confirmed_by": "user",
    "confirmed_at": "2026-09-28T16:40:41.894269+00:00",
    "candidates": [
      {
        "payer_id": "94276",
        "name": "Delta Dental - DDIC",
        "states": [],
        "why": "similar words"
      },
      {
        "payer_id": "DELTA",
        "name": "Delta Dental of Michigan",
        "states": [],
        "why": "similar words"
      },
      {
        "payer_id": "DELTO",
        "name": "Delta Dental of Ohio",
        "states": [],
        "why": "similar words"
      }
    ]
  }
}
422Payer not in the eligibility catalog
{
  "error": "REQUEST_REFUSED",
  "message": "{'code': 'PAYER_NOT_SUPPORTED_FOR_ELIGIBILITY'}",
  "errors": [],
  "request_id": "evt_j36w0q9d590rqfczhcqj",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-request-refused",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks submit
404NOT_FOUNDNo such mapping in your account, including Claim House wide mappings. The message reads {'code': 'MAPPING_NOT_FOUND'}
422REQUEST_REFUSEDnetwork_payer_id is not a payer Claim House can check eligibility with. The message reads {'code': 'PAYER_NOT_SUPPORTED_FOR_ELIGIBILITY'}
422INVALID_REQUESTBody fails the schema, for example network_payer_id missing, empty or over 40 characters
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
503REQUEST_REFUSEDPayer matching is not configured on this gateway. The message reads {'code': 'PAYER_MATCHING_UNAVAILABLE'}
ImportantRefusals raised by this route use the generic envelope codes NOT_FOUND (404) and REQUEST_REFUSED (other statuses). The specific reason, for example FACILITY_NOT_FOUND, appears only inside message, written as {'code': 'FACILITY_NOT_FOUND'}. Match on the status and error, and treat message as text.
ImportantThe route does not check the mapping's current state. Confirming an already CONFIRMED mapping with a different payer changes it. Show the current payer before you send.
InfoOffice grants are not applied: any mapping of your account can be confirmed by any key with submit.
API reference

List claims payer mappingsComing soon

GEThttps://api.claimhouse.ai/v1/payer-mapping/claims

Every carrier question for your offices, the payer Claim House found for each, and the claims payer mappings in force.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Confirm a carrier's claims payerComing soon

POSThttps://api.claimhouse.ai/v1/payer-mapping/claims/confirm

Confirm once which claims payer a carrier is billed to, for one office or every office. Its next claims use it.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get the payer picker

GEThttps://api.claimhouse.ai/v1/payers/picker

Get the browsable list of payers an office can check eligibility with: the office's own payers, popular payers, then A to Z with payer families grouped.

Use it to build an insurance picker. all is sorted by label, A to Z, case insensitive. A payer family, such as Delta Dental, is one entry with its rows in items; rows filed under the office's state come first.

your_office lists payers this office already uses through EXACT or CONFIRMED mappings, including organization wide ones, one row per payer id.

The catalog is the same for every account. Only office_state and your_office depend on the office.

Permission
read
Idempotency
none
Side effects
Writes an audit read row naming the office. Never contacts a payer or the network.
In the dashboard
Eligibility > New check (payer picker)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Query parameters

NameTypeDescription
facility_id*stringThe office, 1 to 64 characters. It must be an office in your account.
e.g. fac_tycrfy0cs0qc7sq95eme

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id. The same value as the X-Request-Id header.
office_statestringThe office's address state. Null when the office has none.
e.g. GA
your_office*arrayPayers this office already uses. Empty when none.
label*stringThe network's name for the payer.
e.g. Delta Dental of Ohio
payer_id*stringThe catalog payer id.
e.g. DELTO
popular*arrayPayers Claim House lists as popular. Empty when none are set.
label*stringThe network's name for the payer.
e.g. Cigna
payer_id*stringThe catalog payer id.
e.g. 62308
all*arrayEvery catalog row, A to Z. Each entry is a family (kind family) or a single payer row (kind payer, with the row fields listed under items).
kind*stringThe entry type.
one of: family · payer
e.g. family
familystringFamilies only. The family code, for example delta_dental.
e.g. delta_dental
label*stringThe family name, or the row label for a single payer.
e.g. Delta Dental
hintstringFamilies only. A plain hint for choosing inside the family. Null for most families.
countintegerFamilies only. Number of rows in items.
e.g. 3
itemsarrayFamilies only. The family's rows, office state first, then by label.
label*stringThe name to show, as printed on member cards where Claim House has it.
e.g. Delta Dental of Georgia
payer_id*stringThe catalog payer id this row maps to. Several rows can share one id.
e.g. 94276
network_name*stringThe network's own name for that id.
e.g. Delta Dental - DDIC
states*arrayArray of strings. Two letter state codes the row is filed under. Often empty.
e.g. ["GA"]
source*stringnetwork when the label is the network's own name, claimhouse when it comes from the Claim House payer directory.
one of: network · claimhouse
e.g. claimhouse
viastringPresent only when label differs from network_name: the network name the row goes through.
e.g. Delta Dental - DDIC
payer_count*integerDistinct catalog payers.
e.g. 5
row_count*integerRows across the whole list. One payer can have several rows.
e.g. 6

Responses

200OK
{
  "request_id": "evt_c53wfdsgv124ncfd8szx",
  "office_state": "GA",
  "your_office": [
    {
      "label": "Delta Dental of Ohio",
      "payer_id": "DELTO"
    }
  ],
  "popular": [
    {
      "label": "Cigna",
      "payer_id": "62308"
    }
  ],
  "all": [
    {
      "kind": "family",
      "family": "delta_dental",
      "label": "Delta Dental",
      "hint": "Delta Dental is separate companies by state. Pick the state on the member's card.",
      "count": 3,
      "items": [
        {
          "label": "Delta Dental of Georgia",
          "payer_id": "94276",
          "network_name": "Delta Dental - DDIC",
          "states": [
            "GA"
          ],
          "source": "claimhouse",
          "via": "Delta Dental - DDIC"
        },
        {
          "label": "Delta Dental of Michigan",
          "payer_id": "DELTA",
          "network_name": "Delta Dental of Michigan",
          "states": [
            "MI"
          ],
          "source": "network"
        },
        {
          "label": "Delta Dental of Ohio",
          "payer_id": "DELTO",
          "network_name": "Delta Dental of Ohio",
          "states": [
            "OH"
          ],
          "source": "network"
        }
      ]
    },
    {
      "kind": "payer",
      "label": "GEHA",
      "payer_id": "39026",
      "network_name": "GEHA",
      "states": [],
      "source": "network"
    }
  ],
  "payer_count": 5,
  "row_count": 6
}
404Unknown office
{
  "error": "NOT_FOUND",
  "message": "{'code': 'FACILITY_NOT_FOUND'}",
  "errors": [],
  "request_id": "evt_kvn7y3rzad1rna71wrjx",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-not-found",
  "user_message": "We could not find that item. It may have been removed, or you may not have access to it."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks read
404NOT_FOUNDfacility_id is not an office in your account. The message reads {'code': 'FACILITY_NOT_FOUND'}
422INVALID_REQUESTfacility_id missing, empty or over 64 characters
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
503REQUEST_REFUSEDPayer matching is not configured on this gateway. The message reads {'code': 'PAYER_MATCHING_UNAVAILABLE'}
ImportantRefusals raised by this route use the generic envelope codes NOT_FOUND (404) and REQUEST_REFUSED (other statuses). The specific reason, for example FACILITY_NOT_FOUND, appears only inside message, written as {'code': 'FACILITY_NOT_FOUND'}. Match on the status and error, and treat message as text.
ImportantOffice grants are not applied: facility_id only has to be an office in your account, and 403 FACILITY_NOT_GRANTED is never returned.
InfoThe list has no paging and no search. Filter it in your interface, or use GET /v1/payers/resolve to match typed text.
API reference

Match insurance to a payer

GEThttps://api.claimhouse.ai/v1/payers/resolve

Turn the insurance name or payer id an office typed into a stored mapping to a payer Claim House can check eligibility with.

Send insurance, payer_id, or both. If a mapping for the same input already exists for this office, your organization or Claim House, it is returned unchanged. Otherwise Claim House resolves it once and stores a new office mapping.

Read usable_for_eligibility first. EXACT needs nothing. SUGGESTED needs one confirmation (needs_confirmation). NEEDS_CHOICE needs a person to pick from candidates. Confirm with POST /v1/payer-mapping/mappings/{mapping_id}/confirm.

Matching uses exact id and name rules first, then Claim House's payer matching model for what the rules cannot settle. Its answers are cached, so the same input is resolved once.

Permission
submit
Idempotency
none
Side effects
On a new input, stores one office mapping and, when a choice is needed, opens a Claim House review. Writes an audit row naming the office and the mapping. Never contacts a payer or the network.
In the dashboard
Eligibility > New check (insurance matching)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Query parameters

NameTypeDescription
facility_id*stringThe office, 1 to 64 characters. It must be an office in your account.
e.g. fac_tycrfy0cs0qc7sq95eme
insurancestringThe insurance name as typed, up to 200 characters. Required when payer_id is not sent.
e.g. Delta Dental of Georgia
payer_idstringA payer id as typed, up to 40 characters. Required when insurance is not sent.
e.g. 94276

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id. The same value as the X-Request-Id header.
mapping*objectThe stored mapping for this input.
mapping_id*stringThe mapping id: map_ plus 16 lowercase hex characters.
e.g. map_4b19b5ec72e122ec
scope*stringWho the mapping applies to. A new mapping is office. Confirming one also stores an organization copy for every office in your account. platform mappings are set by Claim House.
one of: office · organization · platform
e.g. office
state*stringEXACT: the input matched a catalog payer exactly. SUGGESTED: a likely payer that needs one confirmation. NEEDS_CHOICE: several or no payers fit, so a person must pick. UNMAPPABLE: not a payer Claim House can check eligibility with. CONFIRMED: a person or a payer answer confirmed it. STALE: the payer left the catalog; Claim House reviews it.
one of: EXACT · SUGGESTED · NEEDS_CHOICE · UNMAPPABLE · CONFIRMED · STALE
e.g. EXACT
reasonstringWhy the mapping is not exact, as a code, for example not_found, ambiguous, several_payers_match, checks_disagree, model_unavailable, cannot_tell or unsupported. Null when there is nothing to explain, and always null after a confirmation.
network_payer_idstringThe catalog payer id the mapping points to. Null while a choice is needed.
payer_namestringThe network's name for network_payer_id. Null when there is no payer or it is no longer in the catalog.
usable_for_eligibility*booleanTrue when a check can use this mapping: the state is EXACT, SUGGESTED, CONFIRMED or STALE and a payer is set.
needs_confirmation*booleanTrue only in state SUGGESTED: show the payer and ask the user to confirm it once.
resolved_bystringHow Claim House found the payer: payer_id, alternate_id, correction, exact_name or model. Null when no payer was found. Kept after a confirmation.
confirmed_bystringuser (this API or the dashboard), operator (Claim House) or payer_answer (a check through this mapping found the member). Null until confirmed.
confirmed_atdatetimeWhen it was confirmed. Null until confirmed.
candidates*arrayPayers offered for a choice, best first. Empty when there is nothing to choose. Kept after a confirmation.
payer_id*stringA catalog payer id you can confirm.
name*stringThe network's name for that payer id.
states*arrayArray of strings. Up to 12 two letter state codes the payer is filed under. Often empty.
why*stringWhy it was suggested, in plain words, for example similar words or matches the name.
probabilitynumberPresent only when the matching model scored this candidate. Rounded to 3 decimals.

Responses

200Exact match
{
  "request_id": "evt_gaf9ev7dbh24keyj7pwa",
  "mapping": {
    "mapping_id": "map_a8ada2b1781d4323",
    "scope": "office",
    "state": "EXACT",
    "reason": null,
    "network_payer_id": "94276",
    "payer_name": "Delta Dental - DDIC",
    "usable_for_eligibility": true,
    "needs_confirmation": false,
    "resolved_by": "alternate_id",
    "confirmed_by": null,
    "confirmed_at": null,
    "candidates": []
  }
}
200Choice needed
{
  "request_id": "evt_2j8p4hg6xd2pbfz4pah8",
  "mapping": {
    "mapping_id": "map_4b19b5ec72e122ec",
    "scope": "office",
    "state": "NEEDS_CHOICE",
    "reason": "not_found",
    "network_payer_id": null,
    "payer_name": null,
    "usable_for_eligibility": false,
    "needs_confirmation": false,
    "resolved_by": null,
    "confirmed_by": null,
    "confirmed_at": null,
    "candidates": [
      {
        "payer_id": "94276",
        "name": "Delta Dental - DDIC",
        "states": [],
        "why": "similar words"
      },
      {
        "payer_id": "DELTA",
        "name": "Delta Dental of Michigan",
        "states": [],
        "why": "similar words"
      },
      {
        "payer_id": "DELTO",
        "name": "Delta Dental of Ohio",
        "states": [],
        "why": "similar words"
      }
    ]
  }
}
422No input
{
  "error": "REQUEST_REFUSED",
  "message": "{'code': 'INSURANCE_REQUIRED'}",
  "errors": [],
  "request_id": "evt_9n9z5kt55d5tv85d5wy8",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-request-refused",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks submit
404NOT_FOUNDfacility_id is not an office in your account. The message reads {'code': 'FACILITY_NOT_FOUND'}
422REQUEST_REFUSEDNeither insurance nor payer_id was sent. The message reads {'code': 'INSURANCE_REQUIRED'}
422INVALID_REQUESTfacility_id missing or empty, or a parameter too long
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
503REQUEST_REFUSEDPayer matching is not configured on this gateway. The message reads {'code': 'PAYER_MATCHING_UNAVAILABLE'}
ImportantThis is a GET that needs the submit permission, because a new input stores a mapping. A read only key receives 403 PERMISSION_DENIED.
ImportantRefusals raised by this route use the generic envelope codes NOT_FOUND (404) and REQUEST_REFUSED (other statuses). The specific reason, for example FACILITY_NOT_FOUND, appears only inside message, written as {'code': 'FACILITY_NOT_FOUND'}. Match on the status and error, and treat message as text.
ImportantOffice grants are not applied: facility_id only has to be an office in your account, and 403 FACILITY_NOT_GRANTED is never returned.
InfoA stored mapping is never switched silently. The same input at the same office always returns the same stored mapping. Once confirmed, the same input at your other offices returns the organization wide copy.
API reference

Read payer auto-correctComing soon

GEThttps://api.claimhouse.ai/v1/facilities/{facility_id}/payer-settings

The office's switch for automatic payer corrections.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Set payer auto-correctComing soon

PUThttps://api.claimhouse.ai/v1/facilities/{facility_id}/payer-settings

Choose whether the reviewed automatic payer corrections apply to this office.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Import an office's carriersComing soon

POSThttps://api.claimhouse.ai/v1/payer-mapping/claims/import

Share an office's carrier list once, before the first claim. Claim House finds each carrier's claims payer and tells you which ones need an answer.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get a carrier importComing soon

GEThttps://api.claimhouse.ai/v1/payer-mapping/claims/imports/{import_id}

An import's counts, including payers our matching check is still looking for.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Revoke a claims payer confirmationComing soon

POSThttps://api.claimhouse.ai/v1/payer-mapping/claims/{mapping_id}/revoke

Withdraw a carrier's confirmed claims payer. Its next claims ask again; claims already sent are not touched.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Offices

Register the billing offices your claims belong to, name their claims, and check payer enrollment and attachment network registration.

An office (called a facility in the API, ids start with fac_) is one billing entity at one location: one billing NPI plus one TIN, as the payer sees it. A ten-location dental group is one seller with ten offices. Every claim, attachment packet and eligibility check names its office, and the gateway proves a claim's billing NPI and TIN against that office before it transports anything. Read one office with GET /v1/facilities/{facility_id}; every office row carries name (display name, else legal name, else office code).

FieldSet byRules
facility_idGatewayfac_ plus 20 lowercase base32 characters. Opaque.
billing_npiYou, on createTen digits with a valid NPI check digit. Unique together with the TIN inside your seller. Cannot be changed.
tin / tin_typeYou, on createNine digits, no dashes. The TIN is never returned by any route; responses carry only tin_type (EI default, or SY). Cannot be changed.
control_prefixGateway (or you, to import one)Three or four uppercase letters or digits stamped into X12 control numbers. Unique across the whole gateway. Cannot be changed.
binding_kindGatewaysandbox or production. API-created offices are sandbox and accept only test keys. Moving to production is a Claim House action with no route.
claim_office_code / claim_timezoneYou, onceForm human claim references such as NORTH-20260914-0001. Permanent once saved.
nea_facility_idClaim House, when the office is registered for electronic attachmentsThe office's id on the electronic attachment network. Null until the office is registered for electronic attachments.
statusGatewayACTIVE, SUSPENDED or RETIRED. Created offices are ACTIVE.
  • Claim references are assigned when the gateway records confirmed transport of the file that carried the claim, not at submission.
  • The format is <claim_office_code>-<YYYYMMDD>-<sequence>: the transport date in claim_timezone, and a per-office per-day sequence starting at 1, zero-padded to four digits.
  • Claims transported before naming was set never get a reference. The reference is separate from X12 control numbers, which use control_prefix.
Enrollment stateMeaningClaims to this payer
NOT_REQUIREDThe payer needs no enrollment for this transaction.Accepted
REQUESTEDClaim House has requested enrollment.Refused
PENDINGThe payer or clearinghouse is processing it.Refused
LIVEEnrolled.Accepted
REJECTEDThe payer refused the enrollment.Refused
InfoThe per-office transport armed switch is set by a Claim House operator before production transport and is not returned by any route. Enrollment rows are set by the Claim House enrollment desk; no route requests one.
API reference

List offices

GEThttps://api.claimhouse.ai/v1/facilities

List every office your credential reaches.

Use it to map your own office records to facility_ids and to read each office's control prefix, binding, claim naming and electronic attachment registration.

There is no pagination: at most 500 offices are returned, ordered by facility_id. A seller scope sees every office, a group scope sees offices in its groups, and an office scope sees its granted offices.

Permission
read
Idempotency
none
Side effects
Records one audit entry listing the returned office ids. No vendor call.
In the dashboard
Settings > Organization > Offices

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Request example

null

Response fields

NameTypeDescription
request_id*stringThe request id, also sent in the X-Request-Id header.
e.g. evt_EXAMPLE0000000000101
facilities*arrayOne entry per reachable office.
facility_id*stringThe office id.
e.g. fac_EXAMPLE0000000000001
name*stringThe office's name, computed on the server: the display name, else the legal name, else the office code.
group_idstringThe group the office belongs to. Null when the office is in no group.
billing_npi*stringThe office's billing NPI.
e.g. 1234567893
tin_type*stringThe TIN type. The TIN itself is never returned.
one of: EI · SY
taxonomy*stringBilling taxonomy code. Empty string when not set.
e.g. 1223G0001X
control_prefix*stringThe three or four character code stamped into this office's X12 control numbers.
e.g. AAB
claim_office_codestringOffice code used in claim references. Null until set.
claim_timezonestringIANA timezone that decides the claim reference date. Null until set.
nea_facility_idstringThe office's id on the electronic attachment network. Null until the office is registered for electronic attachments.
binding_kind*stringWhether the office accepts test or production keys.
one of: sandbox · production
status*stringThe office's lifecycle status.
one of: ACTIVE · SUSPENDED · RETIRED
address_line1stringReturned by the current gateway build; not yet described in this reference. Can be null.
address_line2stringReturned by the current gateway build; not yet described in this reference. Can be null.
citystringReturned by the current gateway build; not yet described in this reference. Can be null.
contact_emailstringReturned by the current gateway build; not yet described in this reference. Can be null.
contact_namestringReturned by the current gateway build; not yet described in this reference. Can be null.
contact_phonestringReturned by the current gateway build; not yet described in this reference. Can be null.
countrystringReturned by the current gateway build; not yet described in this reference. Can be null.
display_namestringReturned by the current gateway build; not yet described in this reference. Can be null.
identity_review_statusstringReturned by the current gateway build; not yet described in this reference. Can be null.
legal_namestringReturned by the current gateway build; not yet described in this reference. Can be null.
partner_office_refstringReturned by the current gateway build; not yet described in this reference. Can be null.
postal_codestringReturned by the current gateway build; not yet described in this reference. Can be null.
profile_sourcestringReturned by the current gateway build; not yet described in this reference. Can be null.
profile_versionstringReturned by the current gateway build; not yet described in this reference. Can be null.
statestringReturned by the current gateway build; not yet described in this reference. Can be null.
eligibility_statestringThe office's eligibility capability. An office is live for eligibility when binding_kind is production and this is READY.
one of: UNCONFIGURED · PENDING_VERIFICATION · READY · BLOCKED · SUSPENDED

Responses

200OK
{
  "request_id": "evt_j912jjpyq90stk2r84g5",
  "facilities": [
    {
      "facility_id": "fac_q5s09nzww25ysd5a2f3g",
      "name": "HAL",
      "group_id": null,
      "billing_npi": "9999999995",
      "tin_type": "EI",
      "taxonomy": "1223G0001X",
      "control_prefix": "HAL",
      "claim_office_code": null,
      "claim_timezone": null,
      "nea_facility_id": null,
      "binding_kind": "production",
      "status": "ACTIVE",
      "display_name": null,
      "legal_name": null,
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "state": null,
      "postal_code": null,
      "country": null,
      "contact_name": null,
      "contact_email": null,
      "contact_phone": null,
      "partner_office_ref": null,
      "profile_source": null,
      "profile_version": null,
      "identity_review_status": null
    },
    {
      "facility_id": "fac_w9qxypnbcw7b308jbbhh",
      "name": "HA2",
      "group_id": null,
      "billing_npi": "9999999995",
      "tin_type": "EI",
      "taxonomy": "1223G0001X",
      "control_prefix": "HA2",
      "claim_office_code": null,
      "claim_timezone": null,
      "nea_facility_id": null,
      "binding_kind": "production",
      "status": "ACTIVE",
      "display_name": null,
      "legal_name": null,
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "state": null,
      "postal_code": null,
      "country": null,
      "contact_name": null,
      "contact_email": null,
      "contact_phone": null,
      "partner_office_ref": null,
      "profile_source": null,
      "profile_version": null,
      "identity_review_status": null
    },
    {
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "name": "SBX",
      "group_id": null,
      "billing_npi": "9999999995",
      "tin_type": "EI",
      "taxonomy": "1223G0001X",
      "control_prefix": "SBX",
      "claim_office_code": null,
      "claim_timezone": null,
      "nea_facility_id": null,
      "binding_kind": "sandbox",
      "status": "ACTIVE",
      "display_name": null,
      "legal_name": null,
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "state": null,
      "postal_code": null,
      "country": null,
      "contact_name": null,
      "contact_email": null,
      "contact_phone": null,
      "partner_office_ref": null,
      "profile_source": null,
      "profile_version": null,
      "identity_review_status": null
    },
    {
      "facility_id": "fac_qnwrs4rq9tjtqwv37phe",
      "name": "SB2",
      "group_id": null,
      "billing_npi": "9999999995",
      "tin_type": "EI",
      "taxonomy": "1223G0001X",
      "control_prefix": "SB2",
      "claim_office_code": null,
      "claim_timezone": null,
      "nea_facility_id": null,
      "binding_kind": "sandbox",
      "status": "ACTIVE",
      "display_name": null,
      "legal_name": null,
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "state": null,
      "postal_code": null,
      "country": null,
      "contact_name": null,
      "contact_email": null,
      "contact_phone": null,
      "partner_office_ref": null,
      "profile_source": null,
      "profile_version": null,
      "identity_review_status": null
    }
  ]
}
403No office granted
{
  "error": "FACILITY_NOT_GRANTED",
  "message": "No office access is granted.",
  "errors": [],
  "request_id": "evt_bkfrar1bddj3efgmw6s0",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-facility-not-granted",
  "user_message": "Your account does not have access to this office."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, unknown or revoked key, or wrong secret
403PERMISSION_DENIEDThe credential lacks read
403FACILITY_NOT_GRANTEDA group or office scope resolves to no office
429TOO_MANY_REQUESTSMore than 20 requests in flight or the read bucket is empty
InfoNot returned: the TIN, your officeId, the transport armed switch and the created time.
InfoThe current gateway build also returns office profile fields (for example display_name, city, state, partner_office_ref, identity_review_status) that this reference does not yet document. Treat them as unstable.
API reference

Get an officeComing soon

GEThttps://api.claimhouse.ai/v1/facilities/{facility_id}

Read one office your credential reaches, in the same shape as a row of GET /v1/facilities.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Create an office

POSThttps://api.claimhouse.ai/v1/facilities

Register one billing office under your seller in sandbox binding.

Call it during onboarding for each billing location before submitting claims for it. The gateway checks the NPI check digit, allocates a control prefix unless you import one, and creates the office as sandbox and ACTIVE.

The body is strict: unknown fields are refused with 422 and string values are trimmed.

Permission
admin
Idempotency
none
Side effects
Creates the office, reserves its control prefix gateway-wide and seeds its control number counters in one transaction. No vendor call.
In the dashboard
Settings > Organization > Offices > Add offices

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret
Content-Type*stringMust be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.
e.g. application/json

Request body

NameTypeDescription
billingNpi*stringThe office's billing NPI. Ten digits with a valid NPI check digit.
e.g. 1234567893
tin*stringThe billing TIN, nine digits with no dashes. Stored for billing identity checks and never returned.
e.g. 000000000
tinTypestringThe TIN type. Defaults to EI.
one of: EI · SY
taxonomystringBilling taxonomy code, up to 10 characters. Defaults to empty string. The API does not check the pattern.
e.g. 1223G0001X
groupIdstringA group of your seller to place the office in. Up to 64 characters. There is no route to create or list groups.
neaFacilityIdstringAn attachment network office id you already hold, up to 64 characters. When it is set, registering this office for electronic attachments answers 409.
officeIdstringYour own office reference, up to 64 characters. Stored but never returned.
e.g. your-office-17
controlPrefixstringImport a control prefix that already stamps claims elsewhere: 3 or 4 uppercase letters or digits, not already registered. Omit to let the gateway allocate the next free code.
claimOfficeCodestringClaim office code, matching ^[A-Z][A-Z0-9]{1,7}$. Send together with claimTimezone.
e.g. NORTH
claimTimezonestringA valid IANA timezone, up to 64 characters. Send together with claimOfficeCode.
e.g. America/New_York

Request example

{
  "billingNpi": "9999900241",
  "tin": "990000024",
  "tinType": "EI",
  "taxonomy": "1223G0001X",
  "officeId": "your-office-17",
  "claimOfficeCode": "NORTH",
  "claimTimezone": "America/New_York"
}

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000102
facility_id*stringThe new office id.
e.g. fac_EXAMPLE0000000000001
seller_id*stringYour seller id.
e.g. sel_EXAMPLE0000000000001
group_idstringThe group id. Null when none was sent.
billing_npi*stringThe billing NPI.
e.g. 1234567893
tin_type*stringThe TIN type.
one of: EI · SY
control_prefix*stringThe allocated or imported control prefix.
e.g. AAB
claim_office_codestringThe claim office code. Null when not sent.
claim_timezonestringThe claim timezone. Null when not sent.
binding_kind*stringAlways sandbox for offices created through the API.
one of: sandbox
status*stringAlways ACTIVE on create.
one of: ACTIVE
address_line1*stringReturned by the current gateway build; not yet described in this reference.
address_line2*stringReturned by the current gateway build; not yet described in this reference.
capabilities*arrayReturned by the current gateway build; not yet described in this reference.
capability*stringReturned by the current gateway build; not yet described in this reference.
state*stringReturned by the current gateway build; not yet described in this reference.
city*stringReturned by the current gateway build; not yet described in this reference.
contact_email*stringReturned by the current gateway build; not yet described in this reference.
contact_name*stringReturned by the current gateway build; not yet described in this reference.
contact_phone*stringReturned by the current gateway build; not yet described in this reference.
country*stringReturned by the current gateway build; not yet described in this reference.
display_name*stringReturned by the current gateway build; not yet described in this reference.
legal_namestringReturned by the current gateway build; not yet described in this reference. Can be null.
partner_office_refstringReturned by the current gateway build; not yet described in this reference. Can be null.
postal_code*stringReturned by the current gateway build; not yet described in this reference.
profile_source*stringReturned by the current gateway build; not yet described in this reference.
profile_version*integerReturned by the current gateway build; not yet described in this reference.
state*stringReturned by the current gateway build; not yet described in this reference.

Responses

201Created
{
  "request_id": "evt_nxh76fn21ap0j5ans7at",
  "facility_id": "fac_2b5g4kw42z7zqt0y8046",
  "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
  "group_id": null,
  "billing_npi": "9999900241",
  "tin_type": "EI",
  "control_prefix": "NEW",
  "claim_office_code": "NORTH",
  "claim_timezone": "America/New_York",
  "binding_kind": "sandbox",
  "status": "ACTIVE",
  "display_name": "",
  "legal_name": null,
  "address_line1": "",
  "address_line2": "",
  "city": "",
  "state": "",
  "postal_code": "",
  "country": "US",
  "contact_name": "",
  "contact_email": "",
  "contact_phone": "",
  "partner_office_ref": null,
  "profile_source": "customer_supplied",
  "profile_version": 1,
  "capabilities": [
    {
      "capability": "claims",
      "state": "UNCONFIGURED"
    },
    {
      "capability": "attachments",
      "state": "UNCONFIGURED"
    },
    {
      "capability": "eligibility",
      "state": "UNCONFIGURED"
    },
    {
      "capability": "remittances",
      "state": "UNCONFIGURED"
    }
  ]
}
409Office exists
{
  "error": "FACILITY_EXISTS",
  "message": "A facility identity or claim office code is already reserved",
  "errors": [],
  "request_id": "evt_944a31r81kthrt83daef",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-facility-exists",
  "user_message": "This office already exists."
}
422NPI check digit
{
  "error": "VALIDATION",
  "message": "billingNpi fails the 80840 Luhn check digit",
  "errors": [
    {
      "billingNpi": "check digit invalid"
    }
  ],
  "request_id": "evt_d6sx71qdq9t9ctx4t3j3",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-validation",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, unknown or revoked key, or wrong secret
403PERMISSION_DENIEDThe credential lacks admin
409FACILITY_EXISTSSame NPI and TIN, or the claim office code, already used in your seller
422VALIDATIONNPI check digit fails, or groupId is not a group of your seller
422INVALID_REQUESTMissing field, wrong pattern, unknown field, office code without timezone, unknown timezone
429TOO_MANY_REQUESTSMore than 20 requests in flight or the read bucket is empty
ImportantNot idempotent. If a create response is lost, call List offices to find the office before retrying; a repeat returns 409 FACILITY_EXISTS.
InfoThe route is seller wide: an office or group scoped admin key can create offices it cannot reach afterwards.
ImportantA controlPrefix that is malformed (for example AB) or already registered currently returns an unhandled 500 with a plain text body. Nothing is created.
Infotaxonomy and neaFacilityId are accepted but not echoed; read them back with List offices.
InfoThe current gateway build also accepts optional office profile fields (displayName, legalName, addressLine1, addressLine2, city, state, postalCode, country, contactName, contactEmail, contactPhone, partnerOfficeRef) and echoes profile fields plus a capabilities list. This reference does not yet document them.
API reference

Import offices in bulk

POSThttps://api.claimhouse.ai/v1/facilities/import

Create up to 500 offices in one call with a verdict for each row.

Each row is created in its own transaction, in order, so one bad row does not stop the rest. The response is 200 OK even when rows are created.

The whole body is schema checked first: a row with a schema problem (an 11-digit NPI, an unknown field, an office code without a timezone) fails the entire request with 422 and creates nothing. Only NPI check digit, duplicate and group checks are judged per row.

Permission
admin
Idempotency
none
Side effects
Creates each accepted office exactly like Create an office. Rows created before a later failure stay created. No vendor call.
In the dashboard
Settings > Organization > Offices > Add offices

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret
Content-Type*stringMust be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.
e.g. application/json

Request body

NameTypeDescription
facilities*arrayOffice rows, 1 to 500, processed in order. Each row takes the same fields and constraints as the Create an office body.
billingNpi*stringThe office's billing NPI. Ten digits with a valid NPI check digit.
e.g. 1234567893
tin*stringThe billing TIN, nine digits with no dashes. Stored for billing identity checks and never returned.
e.g. 000000000
tinTypestringThe TIN type. Defaults to EI.
one of: EI · SY
taxonomystringBilling taxonomy code, up to 10 characters. Defaults to empty string. The API does not check the pattern.
e.g. 1223G0001X
groupIdstringA group of your seller to place the office in. Up to 64 characters. There is no route to create or list groups.
neaFacilityIdstringAn attachment network office id you already hold, up to 64 characters. When it is set, registering this office for electronic attachments answers 409.
officeIdstringYour own office reference, up to 64 characters. Stored but never returned.
e.g. your-office-17
controlPrefixstringImport a control prefix that already stamps claims elsewhere: 3 or 4 uppercase letters or digits, not already registered. Omit to let the gateway allocate the next free code.
claimOfficeCodestringClaim office code, matching ^[A-Z][A-Z0-9]{1,7}$. Send together with claimTimezone.
e.g. NORTH
claimTimezonestringA valid IANA timezone, up to 64 characters. Send together with claimOfficeCode.
e.g. America/New_York

Request example

{
  "facilities": [
    {
      "billingNpi": "9999900258",
      "tin": "990000025"
    },
    {
      "billingNpi": "1234567890",
      "tin": "990000778"
    },
    {
      "billingNpi": "9999900258",
      "tin": "990000025"
    },
    {
      "billingNpi": "9999900266",
      "tin": "990000026"
    }
  ]
}

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000103
received*integerNumber of rows in the request.
e.g. 3
created*integerNumber of rows with status created.
e.g. 1
results*arrayOne entry per row, in request order.
index*integerZero-based row index.
e.g. 0
status*stringThe verdict for this row.
one of: created · duplicate · invalid
facility_idstringThe new office id. Present only when created.
control_prefixstringThe allocated or imported control prefix. Present only when created.
errorstringWhy the row was refused. Present only when invalid: billingNpi fails the 80840 Luhn check digit, groupId names a group this seller does not have, or rejected for any other failure.

Responses

200OK
{
  "request_id": "evt_ynxr9rqjmte6a8cr2ch4",
  "received": 4,
  "created": 2,
  "results": [
    {
      "index": 0,
      "status": "created",
      "facility_id": "fac_rk50recfer1p4h8rrb4w",
      "control_prefix": "NEW"
    },
    {
      "index": 1,
      "status": "invalid",
      "error": "billingNpi fails the 80840 Luhn check digit"
    },
    {
      "index": 2,
      "status": "duplicate"
    },
    {
      "index": 3,
      "status": "created",
      "facility_id": "fac_2b3hhwz195xxnc9myfch",
      "control_prefix": "NEW"
    }
  ]
}
422Schema failure
{
  "error": "INVALID_REQUEST",
  "message": "the request body is not valid",
  "errors": [
    {
      "code": "string_pattern_mismatch",
      "location": "body.facilities.1.billingNpi",
      "message": "String should match pattern",
      "value_redacted": true
    }
  ],
  "request_id": "evt_bkfrar1bddj3efgmw6s0",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-invalid-request",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, unknown or revoked key, or wrong secret
403PERMISSION_DENIEDThe credential lacks admin
422INVALID_REQUESTEmpty or over 500 rows, or any row fails the schema
429TOO_MANY_REQUESTSMore than 20 requests in flight or the read bucket is empty
ImportantNot idempotent. Sending the same rows again reports the already created ones as duplicate.
InfoThe dashboard accepts a CSV with columns billing_npi, tin, tin_type, taxonomy, control_prefix, group_id, partner_office_ref, claim_office_code, claim_timezone and converts it to this JSON body. The API itself takes JSON only.
InfoA bad or already registered controlPrefix is reported per row as invalid with error rejected.
API reference

Get office capabilities

GEThttps://api.claimhouse.ai/v1/facilities/{facility_id}/capabilities

Read the readiness state of each Claim House service for one office.

Returns one row per service (claims, attachments, eligibility, remittances) with its readiness state for the office, ordered by capability name. Offices created through the API get all four rows at UNCONFIGURED.

Today this route answers only signed-in dashboard sessions whose membership holds offices.read and covers the office. API keys always receive 404.

Permission
Dashboard session with read and offices.read (API keys receive 404)
Idempotency
none
Side effects
Read only. No audit entry and no vendor call.
In the dashboard
API only

Headers

NameTypeDescription
Authorization*stringA signed-in dashboard session token as Bearer <session token>. API keys are refused (404).
e.g. Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyX0VYQU1QTEUifQ.EXAMPLEsignature

Path parameters

NameTypeDescription
facility_id*stringThe office id (fac_...). Must be covered by the session's office access.
e.g. fac_tycrfy0cs0qc7sq95eme

Request example

null

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000104
capabilities*arrayOne row per capability for this office. Empty when the office has no capability rows.
seller_id*stringYour seller id.
e.g. sel_EXAMPLE0000000000001
facility_id*stringThe office id.
e.g. fac_EXAMPLE0000000000001
capability*stringThe service the row describes.
one of: attachments · claims · eligibility · remittances
state*stringThe office's readiness for this service. New offices start at UNCONFIGURED.
one of: UNCONFIGURED · PENDING_VERIFICATION · READY · BLOCKED · SUSPENDED
reason_codestringWhy the capability is in its state. Null when not set.
evidence_referencestringReference to the evidence reviewed for this state. Null when not set.
reviewed_bystringWho last reviewed the capability. Null when never reviewed.
reviewed_atdatetimeWhen the capability was last reviewed. Null when never reviewed.
version*integerRow version, starting at 1.
e.g. 1

Responses

200OK
{
  "request_id": "evt_4205ze8wkh0wgkrrzb72",
  "capabilities": [
    {
      "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "capability": "attachments",
      "state": "UNCONFIGURED",
      "reason_code": null,
      "evidence_reference": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "version": 1
    },
    {
      "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "capability": "claims",
      "state": "UNCONFIGURED",
      "reason_code": null,
      "evidence_reference": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "version": 1
    },
    {
      "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "capability": "eligibility",
      "state": "UNCONFIGURED",
      "reason_code": null,
      "evidence_reference": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "version": 1
    },
    {
      "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "capability": "remittances",
      "state": "UNCONFIGURED",
      "reason_code": null,
      "evidence_reference": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "version": 1
    }
  ]
}
404Not found
{
  "error": "NOT_FOUND",
  "message": "no such office",
  "errors": [],
  "request_id": "evt_hvmk24krwqtwq9dbndsy",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-not-found",
  "user_message": "We could not find that item. It may have been removed, or you may not have access to it."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, unknown or revoked key, or wrong secret
403PERMISSION_DENIEDThe credential lacks read
404NOT_FOUNDAny API key, a session without offices.read, or an office outside the session's access
429TOO_MANY_REQUESTSMore than 20 requests in flight or the read bucket is empty
ImportantBeta. API key callers always get 404 NOT_FOUND, even for their own offices.
InfoNo partner route changes a capability state, so rows stay UNCONFIGURED until Claim House verifies the service for the office.
InfoThe route does not check that the office exists: a session with access to all offices gets 200 with an empty capabilities array for an unknown id. Offices created before capability tracking also return an empty array.
API reference

Set claim namingComing soon

PUThttps://api.claimhouse.ai/v1/facilities/{facility_id}/claim-naming

Set the permanent office code and timezone used to build human claim references.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

List office enrollmentsComing soon

GEThttps://api.claimhouse.ai/v1/facilities/{facility_id}/enrollments

List the office's enrollment state with each payer for each transaction type.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Register an office for electronic attachmentsComing soon

POSThttps://api.claimhouse.ai/v1/facilities/{facility_id}/nea-registration

Register the office for electronic attachments, so its claim attachments can be sent through the electronic attachment network.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Read an office's plan choiceComing soon

GEThttps://api.claimhouse.ai/v1/facilities/{facility_id}/payer-plans/{payer_id}

The plan this office chose for this payer, if any.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Remember an office's plan choiceComing soon

PUThttps://api.claimhouse.ai/v1/facilities/{facility_id}/payer-plans/{payer_id}

Save the plan for this office so the question is asked once.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Forget an office's plan choiceComing soon

DELETEhttps://api.claimhouse.ai/v1/facilities/{facility_id}/payer-plans/{payer_id}

Remove the saved plan for this office and payer.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get office go-live

GEThttps://api.claimhouse.ai/v1/facilities/{facility_id}/go-live

Where an office's go-live stands: test only, in review, live, or declined.

An office is live for eligibility when it is bound to production, its identity is verified, and its eligibility is ready. Test mode works at a sandbox office either way.

Permission
read, or a dashboard session holding offices.read
Idempotency
none
Side effects
None. No vendor call.
In the dashboard
Offices > an office > Go live

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Path parameters

NameTypeDescription
facility_id*stringThe office id: fac_ plus 20 lowercase letters and digits. It must be granted to your key.
e.g. fac_tycrfy0cs0qc7sq95eme

Request example

null

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000511
facility_id*stringThe office.
e.g. fac_tycrfy0cs0qc7sq95eme
state*stringsandbox: not live, no review. in_review: Claim House is checking the office. live: live for eligibility. refused: the last review was declined; see customer_message.
one of: sandbox · in_review · live · refused
reasons*arrayArray of strings: why the registry check did not pass.
one of: NOT_FOUND · INACTIVE · NOT_DENTAL · NAME_MISMATCH · STATE_MISMATCH · REGISTRY_UNAVAILABLE · NPI_REGISTERED_TO_ANOTHER_ORGANIZATION
submitted_atdatetimeWhen the review opened, or null.
decided_atdatetimeWhen the office went live or the review was decided, or null.
customer_messagestringClaim House's note when a review was declined, or null.

Responses

200Test only
{
  "livemode": true,
  "request_id": "evt_27epgwyqb17z10q384c1",
  "facility_id": "fac_tycrfy0cs0qc7sq95eme",
  "state": "sandbox",
  "reasons": [],
  "submitted_at": null,
  "decided_at": null,
  "customer_message": null
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed or unknown credential
403PERMISSION_DENIEDThe credential lacks read
404FACILITY_NOT_FOUNDNo such office for your key (another organization's office is also not found)
API reference

Take an office live

POSThttps://api.claimhouse.ai/v1/facilities/{facility_id}/go-live

Check the office against the national provider registry and make it live for eligibility when it matches.

Needs a card on file, or an internal account, and the eligibility product: otherwise 402 BILLING_REQUIRED or 403 FEATURE_NOT_ENTITLED, and nothing is checked.

Claim House looks up the office's billing NPI in the national provider registry (CMS NPPES). It passes when the NPI is found and active, has a dental taxonomy, a registry name matches the office's legal or display name, and the office's state is a practice state. A pass makes the office live at once (200).

Anything else, including a registry that cannot be reached, puts the office in review (202) with the reasons. Claim House reviews it, usually within one business day. Calling again while the review is open returns it; nothing is charged for a review.

When another Claim House account already holds the NPI live or in review, the office goes to review with the reason NPI_REGISTERED_TO_ANOTHER_ORGANIZATION, never live. The answer names no other account.

The registry proves identity, not licensure: an NPI does not establish a license. Once verified, the office's NPI, tax id, names and address change only through Claim House.

Permission
a dashboard session of an owner or admin holding offices.manage; API keys are refused
Idempotency
repeat-safe
Side effects
One public registry lookup (cached for 24 hours). On a pass: binds the office to production, marks its identity verified, sets eligibility ready, and records the decision. Otherwise opens one review. The monthly minimum starts with your first live office.
In the dashboard
Offices > an office > Go live

Headers

NameTypeDescription
Authorization*stringA signed-in dashboard session token (Bearer <session token>) of an owner or admin. API keys are refused with 403 SESSION_REQUIRED: a person decides to take an office live.
e.g. Bearer eyJhbGciOiJSUzI1NiJ9.EXAMPLE.EXAMPLE

Path parameters

NameTypeDescription
facility_id*stringThe office id: fac_ plus 20 lowercase letters and digits. It must be granted to your key.
e.g. fac_tycrfy0cs0qc7sq95eme

Request example

null

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000511
facility_id*stringThe office.
e.g. fac_tycrfy0cs0qc7sq95eme
state*stringsandbox: not live, no review. in_review: Claim House is checking the office. live: live for eligibility. refused: the last review was declined; see customer_message.
one of: sandbox · in_review · live · refused
reasons*arrayArray of strings: why the registry check did not pass.
one of: NOT_FOUND · INACTIVE · NOT_DENTAL · NAME_MISMATCH · STATE_MISMATCH · REGISTRY_UNAVAILABLE · NPI_REGISTERED_TO_ANOTHER_ORGANIZATION
submitted_atdatetimeWhen the review opened, or null.
decided_atdatetimeWhen the office went live or the review was decided, or null.
customer_messagestringClaim House's note when a review was declined, or null.

Responses

200Live
{
  "livemode": true,
  "request_id": "evt_bcyw9vfp513pzeywspyn",
  "facility_id": "fac_tycrfy0cs0qc7sq95eme",
  "state": "live",
  "reasons": [],
  "submitted_at": null,
  "decided_at": "2026-10-05T12:00:00+00:00",
  "customer_message": null
}
202In review
{
  "livemode": true,
  "request_id": "evt_zpxydpm9hd7w98xca3bs",
  "facility_id": "fac_tycrfy0cs0qc7sq95eme",
  "state": "in_review",
  "reasons": [
    "NAME_MISMATCH"
  ],
  "submitted_at": "2026-10-05T12:00:00+00:00",
  "decided_at": null,
  "customer_message": null
}
402No card
{
  "livemode": true,
  "error": "BILLING_REQUIRED",
  "message": "Add a card on file to send live requests. Test mode keeps working.",
  "errors": [
    {
      "action_url": "/settings/billing"
    }
  ],
  "request_id": "evt_2w70ggmw457cz13h8ag3",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "COMPLETE_SETUP",
  "doc_url": "https://docs.claimhouse.ai/#error-billing-required",
  "user_message": "Live checks need a card on file. Add one in Settings."
}
409Office incomplete
{
  "livemode": true,
  "error": "GO_LIVE_REFUSED",
  "message": "this office cannot go live yet",
  "errors": [
    {
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "reason": "IDENTITY_INCOMPLETE"
    }
  ],
  "request_id": "evt_5fxkx8pz4h2vh2f73k2s",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "COMPLETE_SETUP",
  "doc_url": "https://docs.claimhouse.ai/#error-go-live-refused",
  "user_message": "This office is not ready to go live yet."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed or unknown credential
402BILLING_REQUIREDNo card on file and not an internal account
403FEATURE_NOT_ENTITLEDYour organization is not enrolled for eligibility
403ORG_SUSPENDEDYour account is suspended
403PERMISSION_DENIEDThe session is not an owner or admin holding offices.manage
403SESSION_REQUIREDCalled with an API key
404FACILITY_NOT_FOUNDNo such office for your key
409GO_LIVE_REFUSEDerrors[0].reason: FACILITY_INACTIVE, FACILITY_ARMED, IDENTITY_INCOMPLETE (NPI, tax id, address or name missing) or CAPABILITY_BLOCKED
InfoPayers are not part of go-live: payer mapping is shared reference data Claim House keeps up to date.
API reference

API keys

Mint, audit and revoke the keys your servers use to authenticate, each with one mode, one scope and a set of permissions.

A key is <key_id>.<secret>, sent as Authorization: Bearer <key>. The key_id (key_ plus 20 lowercase characters) is safe to log. The secret is returned only once, by Create an API key, and is stored as a salted digest that cannot be shown again. Examples use the placeholder ch_test_key_EXAMPLE.secret_EXAMPLE.

SettingValuesMeaning
Modetest, productionA test key submits only to sandbox offices, a production key only to production offices. Reads are not mode filtered.
Scope sellerOmit scopeIdsEvery office of the seller, including offices created later.
Scope groupGroup ids of your sellerEvery office currently in those groups, re-evaluated on each request.
Scope facilityOffice ids of your sellerExactly those offices.
Permissionssubmit, read, webhooks, adminAny non-empty subset. GET /v1/me needs read, so a submit-only key cannot call it.
Minting callerMay create
Any callerOnly permissions it holds
test mode callerOnly test keys
seller scopeAny scope
group scopegroup keys for its own groups, or facility keys for offices in its groups. Not seller keys.
facility scopeOnly facility keys for its own offices
InfoMinting rules apply to creation only. Listing and revoking are seller wide: any read credential lists every key, and any admin credential can revoke any key, including itself. There is no rotate route: create a new key with the same settings, deploy it, confirm traffic on it with last_used_at, then revoke the old key. Both keys work in between.
API reference

List API keys

GEThttps://api.claimhouse.ai/v1/keys

Returns metadata for every key your seller owns, active and revoked, newest first.

Use it to audit access and to find keys that have not been used recently. Secrets and digests are never returned.

Seller wide: any credential with read sees every key of the seller, whatever its own scope. There is no pagination.

Permission
read
Idempotency
none
Side effects
Records an audit entry listing the key ids returned. No vendor call.
In the dashboard
Settings > Developer > API keys

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Request example

null

Response fields

NameTypeDescription
request_id*stringUnique id for this request. Also returned in the X-Request-Id header.
e.g. evt_EXAMPLE0000000000000031
keys*arrayArray of key objects, every key of the seller, newest first.
key_id*stringKey id. Safe to log.
e.g. key_EXAMPLE0000000000000002
namestringLabel given at creation. Null when empty.
e.g. north office submitter
mode*stringKey mode.
one of: test · production
e.g. test
scope_kind*stringScope kind.
one of: seller · group · facility
e.g. facility
scope_ids*arrayArray of strings. Granted ids; [<seller id>] for seller keys.
e.g. ["fac_EXAMPLE0000000000000001"]
permissions*arrayArray of strings. Sorted permissions.
e.g. ["read","submit"]
created_bystringKey id of the creator, clerk:<id> for a dashboard user, or null when no creator was recorded (for example a key issued by Claim House).
e.g. key_EXAMPLE0000000000000001
created_at*datetimeISO 8601 creation time.
e.g. 2026-09-14T15:00:00+00:00
last_used_atdatetimeISO 8601 time of the last successful authentication. Null if never used.
e.g. null
revoked_atdatetimeISO 8601 revocation time. Null while active.
e.g. null
revoked_bystringKey id or clerk: id that revoked the key. Null while active.
e.g. null

Responses

200OK
{
  "request_id": "evt_6xsegfmnynpvgzbhgy1h",
  "keys": [
    {
      "key_id": "key_6h9tywc98yqhsy5h7t0n",
      "name": null,
      "mode": "production",
      "scope_kind": "seller",
      "scope_ids": [
        "sel_s4zf3w33k6x8j1e1z6sh"
      ],
      "permissions": [
        "read",
        "submit",
        "webhooks"
      ],
      "created_by": "bootstrap",
      "created_at": "2026-09-05T14:30:00+00:00",
      "last_used_at": null,
      "revoked_at": null,
      "revoked_by": null
    },
    {
      "key_id": "key_7jr01wnnggdpvnsy7a66",
      "name": null,
      "mode": "production",
      "scope_kind": "facility",
      "scope_ids": [
        "fac_q5s09nzww25ysd5a2f3g"
      ],
      "permissions": [
        "read",
        "submit",
        "webhooks"
      ],
      "created_by": "bootstrap",
      "created_at": "2026-09-05T14:30:00+00:00",
      "last_used_at": null,
      "revoked_at": null,
      "revoked_by": null
    },
    {
      "key_id": "key_26z6a4mswbz9c34jjd9n",
      "name": "docs verification",
      "mode": "test",
      "scope_kind": "seller",
      "scope_ids": [
        "sel_s4zf3w33k6x8j1e1z6sh"
      ],
      "permissions": [
        "admin",
        "read",
        "submit",
        "webhooks"
      ],
      "created_by": "bootstrap",
      "created_at": "2026-09-05T14:30:00+00:00",
      "last_used_at": null,
      "revoked_at": null,
      "revoked_by": null
    },
    {
      "key_id": "key_rajhp4p69d3266hejjtc",
      "name": null,
      "mode": "production",
      "scope_kind": "seller",
      "scope_ids": [
        "sel_s4zf3w33k6x8j1e1z6sh"
      ],
      "permissions": [
        "admin",
        "read",
        "submit",
        "webhooks"
      ],
      "created_by": "bootstrap",
      "created_at": "2026-09-05T14:30:00+00:00",
      "last_used_at": null,
      "revoked_at": null,
      "revoked_by": null
    },
    {
      "key_id": "key_7v1bynctfrjr08xahty0",
      "name": "docs verification",
      "mode": "test",
      "scope_kind": "facility",
      "scope_ids": [
        "fac_tycrfy0cs0qc7sq95eme"
      ],
      "permissions": [
        "admin",
        "read",
        "submit",
        "webhooks"
      ],
      "created_by": "bootstrap",
      "created_at": "2026-09-05T14:30:00+00:00",
      "last_used_at": null,
      "revoked_at": null,
      "revoked_by": null
    },
    {
      "key_id": "key_98p1kx2vsy54ehpr2jnq",
      "name": "docs verification",
      "mode": "production",
      "scope_kind": "seller",
      "scope_ids": [
        "sel_s4zf3w33k6x8j1e1z6sh"
      ],
      "permissions": [
        "admin",
        "read",
        "submit",
        "webhooks"
      ],
      "created_by": "bootstrap",
      "created_at": "2026-09-05T14:30:00+00:00",
      "last_used_at": null,
      "revoked_at": null,
      "revoked_by": null
    },
    {
      "key_id": "key_yhzvgbk8v6w4xa9ywy57",
      "name": "docs verification",
      "mode": "test",
      "scope_kind": "seller",
      "scope_ids": [
        "sel_s4zf3w33k6x8j1e1z6sh"
      ],
      "permissions": [
        "read"
      ],
      "created_by": "bootstrap",
      "created_at": "2026-09-05T14:30:00+00:00",
      "last_used_at": null,
      "revoked_at": null,
      "revoked_by": null
    }
  ]
}
403Permission denied
{
  "error": "PERMISSION_DENIED",
  "message": "permission denied",
  "errors": [
    {
      "permission": "read"
    }
  ],
  "request_id": "evt_7rfv80tdkpyymp1xkewh",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-permission-denied",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDmissing, invalid or revoked credential
403PERMISSION_DENIEDcredential lacks read
429TOO_MANY_REQUESTSrate or concurrency limit reached
InfoThe office detail page in the dashboard also uses this list, filtered to active keys that reach that office.
API reference

Create an API key

POSThttps://api.claimhouse.ai/v1/keys

Mints one key inside the caller's own permissions, mode and scope, and returns its secret once.

Use it to issue a separate key per integration, office or environment. The minting rules apply: a key can never create a key stronger than itself.

The full key string is returned only in this response. created_at is not returned; read it from List API keys.

Permission
admin
Idempotency
none
Side effects
Creates the key and its grants and records a key created event. No vendor call.
In the dashboard
Settings > Developer > API keys

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret
Content-Type*stringMust be application/json.
e.g. application/json

Request body

NameTypeDescription
namestringLabel shown in key lists. Up to 120 characters. Defaults to an empty string.
e.g. north office submitter
modestringKey mode. Defaults to test.
one of: test · production
e.g. test
scopeKindstringScope kind. Defaults to seller.
one of: seller · group · facility
e.g. facility
scopeIdsarrayArray of strings. Group ids for group keys, office ids for facility keys; omit for seller keys. Up to 64 items; duplicates are collapsed.
e.g. ["fac_EXAMPLE0000000000000001"]
permissions*arrayArray of strings. At least one of submit, read, webhooks, admin, each held by the caller.
one of: submit · read · webhooks · admin
e.g. ["submit","read"]

Request example

{
  "name": "north office submitter",
  "mode": "test",
  "scopeKind": "facility",
  "scopeIds": [
    "fac_tycrfy0cs0qc7sq95eme"
  ],
  "permissions": [
    "submit",
    "read"
  ]
}

Response fields

NameTypeDescription
request_id*stringUnique id for this request. Also returned in the X-Request-Id header.
e.g. evt_EXAMPLE0000000000000031
key_id*stringThe new key id.
e.g. key_EXAMPLE0000000000000002
namestringLabel. Null when empty.
e.g. north office submitter
mode*stringKey mode.
one of: test · production
e.g. test
scope_kind*stringScope kind.
one of: seller · group · facility
e.g. facility
scope_ids*arrayArray of strings. Stored grant ids; [<seller id>] when none were sent.
e.g. ["fac_EXAMPLE0000000000000001"]
permissions*arrayArray of strings. Sorted permissions.
e.g. ["read","submit"]
secret*stringThe full key string <key_id>.<secret> to send as Authorization: Bearer. Shown only in this response.
e.g. key_EXAMPLE0000000000000002.secret_EXAMPLE
secret_shown_once*booleanAlways true.
e.g. true

Responses

201Created
{
  "request_id": "evt_e3j4hjahy20pegkgy56s",
  "key_id": "key_qh935chyky1z37jap1yj",
  "name": "north office submitter",
  "mode": "test",
  "scope_kind": "facility",
  "scope_ids": [
    "fac_tycrfy0cs0qc7sq95eme"
  ],
  "permissions": [
    "read",
    "submit"
  ],
  "secret": "key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret",
  "secret_shown_once": true
}
403Key escalation
{
  "error": "KEY_ESCALATION",
  "message": "a key cannot grant permissions it does not hold",
  "errors": [
    {
      "permissions": [
        "webhooks"
      ]
    }
  ],
  "request_id": "evt_xrysvceszptzvc7p2t95",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-key-escalation",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}
422Unknown scope ids
{
  "error": "VALIDATION",
  "message": "scopeIds name facilities this seller does not have",
  "errors": [
    {
      "scope_ids": [
        "fac_byjtcdyn6ftbhpxhczwr"
      ]
    }
  ],
  "request_id": "evt_5cx6w1pc0er88x0p46xn",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-validation",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDmissing, invalid or revoked credential
403PERMISSION_DENIEDcredential lacks admin
403FACILITY_NOT_GRANTEDthe caller's own group or office scope resolves to no office
403KEY_ESCALATIONrequested permissions, mode or scope beyond the caller's own
422VALIDATIONscopeIds name offices or groups your seller does not have
422INVALID_REQUESTmissing permissions, unknown permission or mode, more than 64 scopeIds, or an unknown field
429TOO_MANY_REQUESTSrate or concurrency limit reached
ImportantNot idempotent. A retried request creates a second key. If a response is lost, list keys and revoke any key you did not receive a secret for.
ImportantSend non-empty scopeIds for group and facility keys and omit them for seller keys. A group or facility key sent without scopeIds is created but reaches no office, and a seller key sent with foreign scopeIds is refused with 403 FACILITY_NOT_GRANTED on every scoped route.
InfoUnknown scope ids return code VALIDATION, not INVALID_REQUEST. The body is strict: unknown fields are refused and strings are trimmed.
API reference

Revoke an API key

DELETEhttps://api.claimhouse.ai/v1/keys/{key_id}

Revokes one of your seller's keys immediately and permanently.

The next request made with the key gets 401. Use it when a key leaks, an integration is retired, or after rotating to a new key.

Seller wide: any admin credential can revoke any key of the seller, including seller-scoped keys and itself. There is no un-revoke.

Permission
admin
Idempotency
none
Side effects
Sets revoked_at and revoked_by and records a key revoked event; requests already in flight finish, and the key cannot authenticate again. No vendor call.
In the dashboard
Settings > Developer > API keys

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Path parameters

NameTypeDescription
key_id*stringThe key_... id, not the full key string. 1 to 64 characters.
e.g. key_1n71fpwn02kz0k3m5bbw

Request example

null

Response fields

NameTypeDescription
request_id*stringUnique id for this request. Also returned in the X-Request-Id header.
e.g. evt_EXAMPLE0000000000000031
key_id*stringThe revoked key id.
e.g. key_EXAMPLE0000000000000002
revoked*booleanAlways true.
e.g. true

Responses

200OK
{
  "request_id": "evt_vc1amfhv11434kj9c446",
  "key_id": "key_1n71fpwn02kz0k3m5bbw",
  "revoked": true
}
409Already revoked
{
  "error": "KEY_ALREADY_REVOKED",
  "message": "that key is already revoked",
  "errors": [],
  "request_id": "evt_xv44qd2x2rp0sw9m8bs7",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "NONE",
  "doc_url": "https://docs.claimhouse.ai/#error-key-already-revoked",
  "user_message": "This key was already revoked."
}
404Key not found
{
  "error": "NOT_FOUND",
  "message": "no such key",
  "errors": [],
  "request_id": "evt_3ew2wdypbanvkpamjd1n",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-not-found",
  "user_message": "We could not find that item. It may have been removed, or you may not have access to it."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDmissing, invalid or revoked credential, including a caller that revoked its own key earlier
403PERMISSION_DENIEDcredential lacks admin
404NOT_FOUNDno such key in your seller
409KEY_ALREADY_REVOKEDthe key is already revoked
422INVALID_REQUESTkey_id longer than 64 characters
429TOO_MANY_REQUESTSrate or concurrency limit reached
InfoEffectively idempotent in outcome: a second call on the same key returns 409 KEY_ALREADY_REVOKED and changes nothing.
ImportantRevoking the key you are calling with succeeds, and every later request with that key returns 401.
API reference

Create the starter test key

POSThttps://api.claimhouse.ai/v1/keys/starter

Make your organization's first test key, once, and return its secret once. Dashboard sessions only.

The dashboard calls it on the first visit to the home screen in test mode, so a new organization can try the sandbox at once. It is not for your servers: an API key is refused.

The key is made only when your organization has never had a test key. Every later call, and any call after you made a test key another way, answers created: false with no secret.

The key is a seller scoped test key named Test key (created at signup). Its permissions are whichever of read, submit and webhooks your session holds, or read alone when it holds none of them.

Permission
admin, from a dashboard session holding the keys.manage action (API keys are refused)
Idempotency
repeat-safe
Side effects
When it creates the key: stores the key and its seller grant, records a key created event and an audit entry. Otherwise nothing is written. No vendor call.
In the dashboard
Overview (test mode home, shown once)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Request example

null

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000403
livemode*booleanAlways false: this route answers in test mode only.
e.g. false
created*booleanTrue when this call made the key. False when your organization already has, or once had, a test key; then no other field follows.
e.g. true
key_idstringOnly when created is true. The new key id.
e.g. key_EXAMPLE0000000000000003
namestringOnly when created is true. Always Test key (created at signup).
e.g. Test key (created at signup)
modestringOnly when created is true. Always test.
e.g. test
scope_kindstringOnly when created is true. Always seller.
e.g. seller
scope_idsarrayOnly when created is true. Array of strings: your seller id.
e.g. ["sel_EXAMPLE0000000000001"]
permissionsarrayOnly when created is true. Array of strings, sorted.
e.g. ["read","submit","webhooks"]
secretstringOnly when created is true. The full key string to send as Authorization: Bearer. Shown only in this response.
e.g. ch_test_key_EXAMPLE0000000000000003.EXAMPLEsecret
secret_shown_oncebooleanOnly when created is true. Always true.
e.g. true

Responses

200Created
{
  "livemode": false,
  "request_id": "evt_81wbvwes6943xaszse1d",
  "created": true,
  "key_id": "key_7qm2x9d4hs3ve6kt8wbn",
  "name": "Test key (created at signup)",
  "mode": "test",
  "scope_kind": "seller",
  "scope_ids": [
    "sel_s4zf3w33k6x8j1e1z6sh"
  ],
  "permissions": [
    "read",
    "submit",
    "webhooks"
  ],
  "secret": "ch_test_key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret",
  "secret_shown_once": true
}
200Already made
{
  "livemode": false,
  "request_id": "evt_c0t1zjcdmh63f9789gx6",
  "created": false
}
403Live mode
{
  "livemode": true,
  "error": "TEST_MODE_ONLY",
  "message": "the starter key is a test key; switch to Test",
  "errors": [],
  "request_id": "evt_cp0sdqrqg960z3dz59aa",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-test-mode-only",
  "user_message": "This is available in test mode only."
}
403API key
{
  "livemode": false,
  "error": "SESSION_REQUIRED",
  "message": "the starter test key is made from the dashboard",
  "errors": [],
  "request_id": "evt_k557p9p4j141bax9pbg0",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-session-required",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, invalid or revoked credential
403PERMISSION_DENIEDThe credential lacks admin, or the signed-in member lacks the keys.manage action
403SESSION_REQUIREDThe credential is an API key, not a dashboard session
403TEST_MODE_ONLYThe dashboard session is in live mode
429TOO_MANY_REQUESTSRate or concurrency limit reached
429TEST_LIMIT_REACHEDOver the test mode limit of requests a second for your organization
503KEYS_UNAVAILABLEKey creation is not connected on this gateway
ImportantThe secret is shown once. If the response is lost, the key still exists and this route will not show it again: revoke it with DELETE /v1/keys/{key_id} and make a new one with POST /v1/keys.
InfoTwo first visits at the same moment make one key: the organization is locked while the key is made, so only one call answers created: true.
InfoTo make more test keys, or keys with other scopes, use POST /v1/keys.
API reference

Usage

Read meter counts for your seller account over a date range.

Usage is a read of the ledger, not a bill. It counts submissions received, eligibility checks run, attachment packets created and offices on the account, with submissions broken down by office. Periods are whole UTC days.

MeterCountsDoes not count
claims_submittedSubmission records received, including held and rejected ones, in both test and production modes. A file with 12 claims counts as 1.Idempotent replays
eligibility_checksStored eligibility results, successful or vendor error.Answers served from cache
attachment_packetsAttachment packets created.
facilities_activeOffices on the account, regardless of status or period.
InfoThere are no meters for claims transported, remittances, attachments sent or amounts, and no pricing or statement data. The totals are always seller-wide, even for office or group scoped keys.
API reference

Get usage

GEThttps://api.claimhouse.ai/v1/usage

Read usage meters for your seller account between two dates.

Returns seller-wide meters for the period with submissions broken down by office. Use it for a usage widget or to reconcile against a statement.

Days are UTC days: the period runs from from at 00:00 UTC up to, not including, the day after to. There is no maximum range and no facility_id or month parameter.

billing is the month to date from the usage ledger: charges per product, how each product's units split by reason (by_reason), how charged units fall into the price tiers, the monthly minimum and your statements with their lines. To list the units themselves, use GET /v1/usage/units.

Permission
read
Idempotency
none
Side effects
Records one audit entry naming your seller. No vendor call.
In the dashboard
API only

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Query parameters

NameTypeDescription
fromdateFirst day of the period, inclusive (YYYY-MM-DD). Defaults to the first day of the month that contains to.
e.g. 2026-09-01
todateLast day of the period, inclusive (YYYY-MM-DD). Defaults to today in UTC.
e.g. 2026-09-30

Request example

null

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000301
seller_id*stringYour seller id.
e.g. sel_EXAMPLE0000000000001
period*objectThe resolved period.
from*dateThe resolved first day.
e.g. 2026-09-01
to*dateThe resolved last day.
e.g. 2026-09-30
meters*objectCounts for the period. Every meter is 0 when there is nothing to count.
claims_submitted*integerSubmission records received, including held and rejected ones, in test and production modes. A file with many claims counts as 1. Idempotent replays are not counted.
e.g. 42
eligibility_checks*integerStored eligibility results created, successful or vendor error. Cache answers are not counted.
e.g. 130
attachment_packets*integerAttachment packets created.
e.g. 9
facilities_active*integerOffices on your account regardless of status or period, counted up to 5,000.
e.g. 3
by_facility*arrayOne entry per office with at least one submission in the period. Offices with none are omitted; order is not guaranteed.
facility_id*stringThe office id.
e.g. fac_EXAMPLE0000000000001
claims_submitted*integerSubmissions for that office. The entries sum to meters.claims_submitted.
e.g. 30
billingobjectThe month to date from the usage ledger, for the calendar month (UTC) that contains to. Money is in integer micros (1 USD = 1,000,000). Absent when the ledger is not connected.
currency*stringAlways USD.
e.g. USD
billing_mode*stringHow you are billed.
one of: CARD · INVOICE · INTERNAL
products*arrayOne entry per product.
product*stringThe product.
e.g. eligibility_check
units*integerCharged units this month.
e.g. 260
pending_units*integerUnits under review, not charged unless they prove to be payer answers.
e.g. 1
free_units*integerUnits counted but never charged.
e.g. 31
amount_micros*integerThis product's charges so far.
e.g. 76500000
by_reason*arrayEvery unit of the month by reason and state, charged first, largest first. The counts add up to units + pending_units + free_units.
reason*stringA reason code from the pricing guide.
e.g. answered
state*stringBillable state.
one of: BILLABLE · PENDING · NOT_BILLABLE
units*integerUnits with this reason and state.
e.g. 180
label*stringA short plain label.
e.g. Payer answered
tiers*arrayHow the charged units fall into the price tiers so far, for example units 251 to 3,500 at $0.15.
tierintegerThe tier number. Null on a minimum line.
e.g. 2
from_unitsintegerThe tier's first unit of the month. Null on a minimum line.
e.g. 251
to_unitsintegerThe tier's last unit. Null for the open top tier and on a minimum line.
e.g. 3500
units*integerUnits priced in this tier.
e.g. 10
unit_price_micros*integerPrice per unit, in micros.
e.g. 150000
amount_micros*integerUnits times price, in micros.
e.g. 1500000
minimum*objectThe monthly minimum: amount_micros, covered_micros, true_up_micros, starts_on and full_monthly_micros.
estimate*objectsubtotal_micros (usage) and total_micros (with the minimum).
offices*arrayPer office: facility_id, group_id, units, free_units and amount_micros.
groups*arrayPer client group: group_id, offices and amount_micros.
statements*arrayYour last 12 statements, newest first.
statement_id*stringThe statement id.
e.g. stm_EXAMPLE00000000001
period*dateThe month, as its first day.
e.g. 2026-09-01
status*stringDRAFT until the month closes.
one of: DRAFT · FINAL
total_micros*integerThe statement total.
e.g. 1000000000
billing_mode*stringHow it was billed.
e.g. CARD
lines*arrayOne line per product tier (PRODUCT_TIER) and the minimum top-up (MINIMUM), each with its tier bounds.
kind*stringLine kind.
one of: PRODUCT_TIER · MINIMUM
productstringThe product. Null on the minimum line.
e.g. eligibility_check
tierintegerThe tier number. Null on a minimum line.
e.g. 2
from_unitsintegerThe tier's first unit of the month. Null on a minimum line.
e.g. 251
to_unitsintegerThe tier's last unit. Null for the open top tier and on a minimum line.
e.g. 3500
units*integerUnits priced in this tier.
e.g. 10
unit_price_micros*integerPrice per unit, in micros.
e.g. 150000
amount_micros*integerUnits times price, in micros.
e.g. 1500000

Responses

200OK
{
  "request_id": "evt_nkpjxkvjpdx58yvk4jgr",
  "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
  "period": {
    "from": "2026-09-01",
    "to": "2026-09-30"
  },
  "meters": {
    "claims_submitted": 13,
    "eligibility_checks": 0,
    "attachment_packets": 0,
    "facilities_active": 9
  },
  "by_facility": [
    {
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "claims_submitted": 13
    }
  ],
  "billing": {
    "currency": "USD",
    "billing_mode": "CARD",
    "price_book": {
      "price_book_id": "pbk_baseline_v1",
      "name": "Baseline",
      "version": 1,
      "tier_method": "GRADUATED"
    },
    "products": [
      {
        "product": "eligibility_check",
        "units": 260,
        "pending_units": 1,
        "free_units": 31,
        "current_tier": 2,
        "next_tier_at": 3501,
        "next_unit_price_micros": 100000,
        "amount_micros": 76500000,
        "by_reason": [
          {
            "reason": "answered",
            "state": "BILLABLE",
            "units": 212,
            "label": "Payer answered"
          },
          {
            "reason": "payer_rejected_patient",
            "state": "BILLABLE",
            "units": 48,
            "label": "Payer could not find the member"
          },
          {
            "reason": "under_review",
            "state": "PENDING",
            "units": 1,
            "label": "Under review"
          },
          {
            "reason": "cache_hit",
            "state": "NOT_BILLABLE",
            "units": 20,
            "label": "Saved answer"
          },
          {
            "reason": "payer_unavailable",
            "state": "NOT_BILLABLE",
            "units": 11,
            "label": "Payer was down"
          }
        ],
        "tiers": [
          {
            "from_units": 1,
            "to_units": 250,
            "tier": 1,
            "units": 250,
            "unit_price_micros": 300000,
            "amount_micros": 75000000
          },
          {
            "from_units": 251,
            "to_units": 3500,
            "tier": 2,
            "units": 10,
            "unit_price_micros": 150000,
            "amount_micros": 1500000
          }
        ]
      }
    ],
    "minimum": {
      "amount_micros": 500000000,
      "covered_micros": 76500000,
      "true_up_micros": 423500000,
      "starts_on": "2026-09-01",
      "full_monthly_micros": 500000000
    },
    "estimate": {
      "subtotal_micros": 76500000,
      "total_micros": 500000000
    },
    "offices": [
      {
        "facility_id": "fac_tycrfy0cs0qc7sq95eme",
        "group_id": null,
        "units": {
          "eligibility_check": 260
        },
        "free_units": {
          "eligibility_check": 31
        },
        "amount_micros": 76500000
      }
    ],
    "groups": [
      {
        "group_id": null,
        "offices": 1,
        "amount_micros": 76500000
      }
    ],
    "statements": [
      {
        "statement_id": "stm_k3v9x2m7q4w8r1t6y5za",
        "period": "2026-08-01",
        "status": "FINAL",
        "total_micros": 1000000000,
        "billing_mode": "CARD",
        "lines": [
          {
            "kind": "PRODUCT_TIER",
            "product": "eligibility_check",
            "tier": 1,
            "from_units": 1,
            "to_units": 250,
            "units": 120,
            "unit_price_micros": 300000,
            "amount_micros": 36000000
          },
          {
            "kind": "MINIMUM",
            "product": null,
            "tier": null,
            "from_units": null,
            "to_units": null,
            "units": 1,
            "unit_price_micros": 964000000,
            "amount_micros": 964000000
          }
        ]
      }
    ]
  }
}
422Range reversed
{
  "error": "VALIDATION",
  "message": "to must not precede from",
  "errors": [],
  "request_id": "evt_gqn68xwksccy64p7wzct",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-validation",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, unknown or revoked key, or wrong secret
403PERMISSION_DENIEDThe credential lacks read
422VALIDATIONto is earlier than from
422INVALID_REQUESTfrom or to is not a valid date
429TOO_MANY_REQUESTSMore than 20 requests in flight or the read bucket is empty
ImportantBeta. Against a real database this route can currently return an unhandled 500; retrying does not help, so report it.
InfoA reversed range returns code VALIDATION, not INVALID_REQUEST.
InfoOffice grants are not applied: office and group scoped keys receive the same seller-wide totals and every office's breakdown, and 403 FACILITY_NOT_GRANTED is never returned.
API reference

List usage units

GEThttps://api.claimhouse.ai/v1/usage/units

Every unit billed in a month, newest first, with whether it is charged and why.

One row per unit in the billing month: a check you sent (charged or free), a saved answer served again, or a check under review. Each row names its reason, office, channel and who sent it.

Ids and codes only, never patient details. source_id is the eligibility id; open it with GET /v1/eligibility/{eligibility_id} under that route's own permissions.

A unit recorded after its month's statement was final is billed in the next open month, so filter by billing month (period), not by when it happened.

Permission
read
Idempotency
none
Side effects
Records one audit entry naming your seller. No vendor call.
In the dashboard
Settings > Usage > Download units (CSV)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Query parameters

NameTypeDescription
periodstringThe billing month, YYYY-MM. Defaults to the current month in UTC.
e.g. 2026-09
productstringOnly this product.
one of: eligibility_check · claim_status_check · claim_submission · adjudicated_claim · attachment
statestringOnly units in this state.
one of: BILLABLE · PENDING · NOT_BILLABLE
reasonstringOnly units with this reason code (see the pricing guide). under_review implies PENDING. test_mode is every unit that is not live, a saved answer served in test mode included.
e.g. payer_unavailable
facilityIdstringOnly this office. It must be granted to your key.
e.g. fac_tycrfy0cs0qc7sq95eme
cursorstringThe next_cursor of the previous page: ASCII digits only.
e.g. 18231
limitintegerPage size, 1 to 500. Default 100.
e.g. 100

Request example

null

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000301
period*stringThe billing month, YYYY-MM.
e.g. 2026-09
data*arrayUnits, newest first.
usage_id*integerThe unit id.
e.g. 18232
occurred_at*datetimeWhen it happened.
facility_id*stringThe office.
product*stringThe product.
e.g. eligibility_check
state*stringBillable state.
one of: BILLABLE · PENDING · NOT_BILLABLE
reason*stringA reason code.
e.g. answered
label*stringA short plain label.
e.g. Payer answered
billing_period*dateThe first day of the month the unit is billed in.
e.g. 2026-09-01
source_id*stringThe eligibility id. For a saved answer, the check whose answer was served.
channelstringWhere it came from.
one of: api · dashboard · agent · batch · system
actor*objectWho sent it.
kindstringapi_key, member (the dashboard), operator (Claim House) or system.
idstringThe key id or the dashboard member's id. Null for Claim House.
namestringThe key's name, or Claim House. Null for a dashboard member: people's names are not stored with usage.
next_cursorstringPass as cursor for the next page. Null on the last page.

Responses

200OK
{
  "request_id": "evt_nkpjxkvjpdx58yvk4jgr",
  "period": "2026-09",
  "data": [
    {
      "usage_id": 18232,
      "occurred_at": "2026-09-20T15:04:11+00:00",
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "product": "eligibility_check",
      "state": "BILLABLE",
      "reason": "answered",
      "label": "Payer answered",
      "billing_period": "2026-09-01",
      "source_id": "elg_wddgq19nhagdyseyyhte",
      "channel": "api",
      "actor": {
        "kind": "api_key",
        "id": "key_7qm2x9d4hs3ve6kt8wbn",
        "name": "Front desk"
      }
    },
    {
      "usage_id": 18231,
      "occurred_at": "2026-09-20T14:58:02+00:00",
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "product": "eligibility_check",
      "state": "NOT_BILLABLE",
      "reason": "payer_unavailable",
      "label": "Payer was down",
      "billing_period": "2026-09-01",
      "source_id": "elg_r7c2m9x4k0v8t1q6p3b5",
      "channel": "dashboard",
      "actor": {
        "kind": "member",
        "id": "clerk:3f9a1c0d2b7e4a6f8c1d0e2a",
        "name": null
      }
    }
  ],
  "next_cursor": null
}
422Unknown reason
{
  "error": "VALIDATION",
  "message": "reason is not a known reason code",
  "errors": [
    {
      "reason": "made_up",
      "allowed": [
        "answered",
        "cache_hit",
        "malformed_answer",
        "not_classified",
        "not_sent",
        "operator_test",
        "our_configuration",
        "payer_rejected_patient",
        "payer_rejected_provider",
        "payer_rejected_request",
        "payer_unavailable",
        "request_rejected",
        "test_mode",
        "transport_failure",
        "under_review",
        "vendor_input_error"
      ]
    }
  ],
  "request_id": "evt_gqn68xwksccy64p7wzct",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-validation",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, unknown or revoked key, or wrong secret
403PERMISSION_DENIEDThe credential lacks read
403FACILITY_NOT_GRANTEDfacilityId is not granted to your key
422VALIDATIONreason is not a known reason code
422INVALID_CURSORcursor is not a cursor from this list
422INVALID_REQUESTperiod, product, state or limit is not valid
429TOO_MANY_REQUESTSMore than 20 requests in flight or the read bucket is empty
InfoOffice and group scoped keys see only their offices' units. A reason of under_review with a state other than PENDING matches nothing.
InfoA unit that is not live always shows reason test_mode, the same as the billing object on a test mode check, whatever it was recorded as.
API reference

Get billing

GEThttps://api.claimhouse.ai/v1/billing

Your organization's billing state and the card on file, and whether live requests are open.

Test mode is always free. Live requests reach payers and are billed, so they need a card on file, or an internal account.

The card is shown as brand, last four digits and expiry only. The card number is typed on the card processor's hosted page and never reaches Claim House.

After card setup, the page you return to reads this route until card appears. The return itself saves nothing: the card is saved only when the card processor confirms it to Claim House.

Permission
read, or a dashboard session holding billing.read
Idempotency
none
Side effects
None. No vendor call.
In the dashboard
Settings > Billing

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Request example

null

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000501
state*stringThe billing state. ACTIVE once a card is saved.
one of: CARD_REQUIRED · ACTIVE · PAST_DUE · SUSPENDED
mode*stringHow the organization is billed. INTERNAL accounts are never charged and need no card.
one of: INTERNAL · CARD · INVOICE
processor_modestringtest or live once a card processor customer exists for your organization, else null.
cardobjectThe card on file, or null. Brand, last four digits and expiry only: card numbers never reach Claim House.
brand*stringThe card brand.
one of: visa · mastercard · amex · discover · diners · jcb · unionpay · unknown
last4*stringThe last four digits.
e.g. 4242
exp_month*integerExpiry month, 1 to 12.
e.g. 4
exp_year*integerExpiry year.
e.g. 2028
state_reasonstringWhy the state last changed.
one of: card_saved · card_removed · card_expired · customer_deleted · operator
state_changed_atdatetimeWhen the state last changed, or null.
live_billing_ok*booleanWhether billing lets your organization send live requests: an active card, or an internal account.
e.g. true
can_manage*booleanWhether this signed-in person may add or replace the card (the billing.manage action). Always false for an API key and for internal accounts.
e.g. true
card_setup_available*booleanWhether card setup can be opened right now. False for internal accounts and while card processing is not configured.
e.g. true

Responses

200Card on file
{
  "livemode": false,
  "request_id": "evt_2fqv1c3h5k8m9n0p7r6s",
  "state": "ACTIVE",
  "mode": "CARD",
  "processor_mode": "test",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 4,
    "exp_year": 2028
  },
  "state_reason": "card_saved",
  "state_changed_at": "2026-10-05T12:00:00+00:00",
  "live_billing_ok": true,
  "can_manage": true,
  "card_setup_available": true
}
200No card yet
{
  "livemode": true,
  "request_id": "evt_k1v1fmgttd1e5bda8fj3",
  "state": "CARD_REQUIRED",
  "mode": "CARD",
  "processor_mode": null,
  "card": null,
  "state_reason": null,
  "state_changed_at": null,
  "live_billing_ok": false,
  "can_manage": false,
  "card_setup_available": true
}
200Internal account
{
  "livemode": false,
  "request_id": "evt_0nvmbqztwh3fd6bqt9q1",
  "state": "CARD_REQUIRED",
  "mode": "INTERNAL",
  "processor_mode": null,
  "card": null,
  "state_reason": null,
  "state_changed_at": null,
  "live_billing_ok": true,
  "can_manage": false,
  "card_setup_available": false
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed or unknown credential
403PERMISSION_DENIEDThe credential lacks read, or the session lacks billing.read
503BILLING_UNAVAILABLEBilling is not connected on this gateway
InfoA live request from an organization whose billing does not allow it is refused with 402 BILLING_REQUIRED before anything reaches a payer; its errors[0].action_url is /settings/billing. Reads, test mode and PDFs of earlier checks keep working.
API reference

Open card setup

POSThttps://api.claimhouse.ai/v1/billing/card-session

Start the hosted page where a signed-in owner or admin saves a card. Dashboard sessions only.

Returns the URL of the card processor's hosted card page. Send the person there; they come back to /settings/billing?card=returned (or ?card=cancelled).

The hosted page shows the card authorization: by saving the card you authorize Claim House (Zions Health, Inc.) to charge it monthly for live usage under the Claim House terms, until you remove it, and for usage when it reaches $500 in a month (then $2,000 after your first three paid months), and at month end, plus the monthly minimum.

The first call creates your organization's customer at the card processor, once. Nothing is saved until the card processor confirms the card to Claim House; read GET /v1/billing for the result.

Permission
a dashboard session holding billing.manage (owners and admins); API keys are refused
Idempotency
repeat-safe per nonce
Side effects
Creates the card processor customer on the first call and records its id. Card data never reaches Claim House.
In the dashboard
Settings > Billing > Add card

Headers

NameTypeDescription
Authorization*stringA signed-in dashboard session token (Bearer <session token>). API keys are refused with 403 SESSION_REQUIRED: saving a card is a person agreeing to the card authorization.
e.g. Bearer eyJhbGciOiJSUzI1NiJ9.EXAMPLE.EXAMPLE

Request body

NameTypeDescription
nonce*stringA new UUID for each click, made by your page. The same nonce returns the same hosted page.
e.g. 3f2b6c1e-8d4a-4b5e-9c1a-2e7f6d5c4b3a

Request example

{
  "nonce": "3f2b6c1e-8d4a-4b5e-9c1a-2e7f6d5c4b3a"
}

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000502
url*stringThe hosted page to send the person to (https only). Open it in the same browser tab.
e.g. https://pay.example.com/card/cs_test_EXAMPLE

Responses

200Hosted page
{
  "livemode": false,
  "request_id": "evt_8sgg4m61en3dsc4ewj0d",
  "url": "https://pay.example.com/card/cs_test_EXAMPLE"
}
403API key
{
  "livemode": true,
  "error": "SESSION_REQUIRED",
  "message": "card setup needs a signed-in person, not an API key",
  "errors": [],
  "request_id": "evt_a58xv4s36n2nbb5gzssg",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-session-required",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}
409Internal account
{
  "livemode": false,
  "error": "BILLING_INTERNAL",
  "message": "internal accounts are never charged and need no card",
  "errors": [],
  "request_id": "evt_qbfss8kjn16wb76bdz6p",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "NONE",
  "doc_url": "https://docs.claimhouse.ai/#error-billing-internal",
  "user_message": "This account is never charged and needs no card."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed or unknown credential
403SESSION_REQUIREDCalled with an API key
403PERMISSION_DENIEDThe session lacks billing.manage
409BILLING_INTERNALYour account is internal: never charged, no card needed
409BILLING_ACCOUNT_REQUIREDYour organization has no billing account yet
409BILLING_PROCESSOR_MODE_MISMATCHYour card was saved in the other card processor mode; contact support
422VALIDATIONnonce is not a UUID
503BILLING_UNAVAILABLECard setup is not available right now
API reference

Open the card portal

POSThttps://api.claimhouse.ai/v1/billing/portal-session

Start the hosted page where a signed-in owner or admin replaces or removes the card. Dashboard sessions only.

Returns the URL of the card processor's hosted portal, limited to updating the payment method. The person comes back to /settings/billing?portal=returned.

A replaced card shows in GET /v1/billing once the card processor confirms it. A removed card sets state to CARD_REQUIRED: new live requests get 402 BILLING_REQUIRED, live offices stay live, and reads keep working.

Permission
a dashboard session holding billing.manage (owners and admins); API keys are refused
Idempotency
none
Side effects
None at Claim House until the card processor reports a change. No card data reaches Claim House.
In the dashboard
Settings > Billing > Replace card

Headers

NameTypeDescription
Authorization*stringA signed-in dashboard session token (Bearer <session token>). API keys are refused with 403 SESSION_REQUIRED: saving a card is a person agreeing to the card authorization.
e.g. Bearer eyJhbGciOiJSUzI1NiJ9.EXAMPLE.EXAMPLE

Request example

null

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000502
url*stringThe hosted page to send the person to (https only). Open it in the same browser tab.
e.g. https://pay.example.com/card/cs_test_EXAMPLE

Responses

200Hosted portal
{
  "livemode": false,
  "request_id": "evt_t9nsqb25r11sf2j4q3j7",
  "url": "https://pay.example.com/manage/EXAMPLE"
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed or unknown credential
403SESSION_REQUIREDCalled with an API key
403PERMISSION_DENIEDThe session lacks billing.manage
409BILLING_CUSTOMER_REQUIREDNo card has been added yet; use card setup first
409BILLING_INTERNALYour account is internal
503BILLING_UNAVAILABLECard setup is not available right now
API reference

Account and team

Confirm who a credential is, onboard a new organization, and manage the people who can use it.

Route familyCredentialNeeds an organization membership
GET /v1/meAPI key or dashboard session with readSessions: yes, active
/v1/onboarding/*Signed-in dashboard session onlyNo. Works before any organization exists
/v1/members, /v1/invitations, /v1/access-requestsDashboard session only, admin plus a member actionYes, active. API keys are refused with 403
  1. Sign in to the dashboard, then call GET /v1/onboarding/state.
  2. New company: create an application, then submit it. Joining an existing company: request access with its partner reference.
  3. Claim House reviews the application. When the organization is READY, the state route returns allowed_actions: ["enter_partner"].
  4. Organization administrators prepare invitations for teammates and adjust each member's actions and office access.
RecordStates
ApplicationDRAFT > PENDING_REVIEW > NEEDS_INFORMATION | APPROVED > PROVISIONING > READY, or DECLINED / BLOCKED
Access requestPENDING > APPROVED_FOR_INVITATION | DECLINED
InvitationPREPARED > DELIVERY_PENDING > SENT > ACCEPTED > RECONCILED; also REVOKED, EXPIRED, DELIVERY_FAILED, OUTCOME_UNCERTAIN

A member's rights are a set of actions (for example claims.read, claims.submit, members.manage) plus an office scope: ALL (every current and future office), SUBSET (listed offices) or NONE (no office data). The role is a label. An administrator can only grant actions and offices they hold themselves; anything wider is refused with 403 DELEGATION_EXCEEDED.

ImportantEvery change route uses optimistic concurrency: send the version (or a member's authorization_version) you last read as expected_version. A mismatch returns 409 STALE_VERSION_OR_STATE; reload and try again. Everything here except GET /v1/me is beta: it needs dashboard sign-in configured, and invitation email delivery is not connected yet.
API reference

Get the current identity

GEThttps://api.claimhouse.ai/v1/me

Return who the presented credential is: seller, principal, mode, scope and reachable offices.

Call it once at startup to confirm a key is wired to the seller and mode you expect, and to read the offices it reaches with their names (reachable_facilities).

The body has two shapes. An API key gets seller, key id, scope and reachable office ids. A signed-in dashboard session gets the person, organization, role, member actions and office scope instead.

Permission
read
Idempotency
none
Side effects
Writes one audit row naming the credential and route. No vendor call.
In the dashboard
Header and shell (seller name and environment dot); Settings > Organization > Team and Offices (role gate)

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id, same as the X-Request-Id header.
seller_idstringAPI key only. Your seller id, sel_....
seller_namestringAPI key only. The seller's legal name.
seller_statusstringAPI key only. Seller status, for example ACTIVE.
principal*objectWho is calling.
kind*stringA machine key or dashboard-session principal; wire enum values appear below.
one of: api_key · clerk
key_idstringAPI key only. The key_... id.
subjectstringSession only. A stable pseudonymous id clerk:<24 hex> derived from the signed-in user.
mode*stringtest or production. For a key, the key's mode. For a session, the gateway's configured session mode.
one of: test · production
scopeobjectAPI key only. The key's grants.
kind*stringScope kind.
one of: seller · group · facility
ids*arrayArray of strings. The raw grant ids. For a seller scope, [seller_id].
permissions*arrayArray of strings. Sorted key permissions.
one of: admin · read · submit · webhooks
reachable_facility_idsarrayAPI key only. Array of strings. Office ids the key reaches. For seller scope, every office of the seller (first 500).
reachable_facilitiesarrayThe same offices as reachable_facility_ids (or office_scope.facility_ids for a session), in the same order, with names. Both shapes.
facility_id*stringThe office id.
name*stringThe display name, else the legal name, else the office code.
code*stringThe office code.
citystringCity as the office was entered. Null when not set.
statestringState as the office was entered. Null when not set.
mode*stringsandbox (test) or production.
one of: sandbox · production
userobjectSession only. The signed-in person.
display_name*stringName from the session token. Empty string when the token carries none.
email*stringEmail from the session token. Empty string when the token carries none.
organizationobjectSession only. The organization the session is signed into.
clerk_org_id*stringThe sign-in organization id.
seller_id*stringThe Claim House seller the organization is bound to.
name*stringSeller display name, or legal name when no display name is set.
onboarding_state*stringSeller onboarding status. Always READY for a session that can call this route.
one of: APPLICATION · PROVISIONING · READY · BLOCKED
rolestringSession only. The membership role label.
one of: owner · admin · submitter · viewer
permissionsarraySession only. Array of strings. Sorted member actions, for example claims.read.
one of: claims.read · claims.submit · attachments.read · attachments.manage · eligibility.read · eligibility.check · remittances.read · members.read · members.manage · offices.read · offices.manage · keys.read · keys.manage · webhooks.read · webhooks.manage · usage.read · billing.read
office_scopeobjectSession only. The member's office access.
kind*stringALL, SUBSET or NONE.
one of: ALL · SUBSET · NONE
facility_ids*arrayArray of strings. For ALL, every office of the seller. For SUBSET, the granted offices. For NONE, empty.
authorization_versionintegerSession only. The membership's authorization version.
capabilitiesobjectSession only. Reserved. Always an empty object today.

Responses

200OK (API key)
{
  "request_id": "evt_f8cwc9ew49wa6bjpqdyd",
  "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
  "seller_name": "Sample Dental Group LLC",
  "seller_status": "ACTIVE",
  "principal": {
    "kind": "api_key",
    "key_id": "key_26z6a4mswbz9c34jjd9n"
  },
  "mode": "test",
  "scope": {
    "kind": "seller",
    "ids": [
      "sel_s4zf3w33k6x8j1e1z6sh"
    ],
    "permissions": [
      "admin",
      "read",
      "submit",
      "webhooks"
    ]
  },
  "reachable_facility_ids": [
    "fac_q5s09nzww25ysd5a2f3g",
    "fac_w9qxypnbcw7b308jbbhh",
    "fac_tycrfy0cs0qc7sq95eme",
    "fac_qnwrs4rq9tjtqwv37phe",
    "fac_2b5g4kw42z7zqt0y8046",
    "fac_rk50recfer1p4h8rrb4w",
    "fac_2b3hhwz195xxnc9myfch",
    "fac_bkzth74mqx09wergap5c",
    "fac_j0h554r1qy2nzrkvspb4"
  ],
  "reachable_facilities": [
    {
      "facility_id": "fac_q5s09nzww25ysd5a2f3g",
      "name": "HAL",
      "code": "HAL",
      "city": null,
      "state": null,
      "mode": "production"
    },
    {
      "facility_id": "fac_w9qxypnbcw7b308jbbhh",
      "name": "HA2",
      "code": "HA2",
      "city": null,
      "state": null,
      "mode": "production"
    },
    {
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "name": "SBX",
      "code": "SBX",
      "city": null,
      "state": null,
      "mode": "sandbox"
    },
    {
      "facility_id": "fac_qnwrs4rq9tjtqwv37phe",
      "name": "SB2",
      "code": "SB2",
      "city": null,
      "state": null,
      "mode": "sandbox"
    },
    {
      "facility_id": "fac_2b5g4kw42z7zqt0y8046",
      "name": "MED",
      "code": "MED",
      "city": null,
      "state": null,
      "mode": "production"
    },
    {
      "facility_id": "fac_rk50recfer1p4h8rrb4w",
      "name": "TOD",
      "code": "TOD",
      "city": null,
      "state": null,
      "mode": "production"
    },
    {
      "facility_id": "fac_2b3hhwz195xxnc9myfch",
      "name": "TO2",
      "code": "TO2",
      "city": null,
      "state": null,
      "mode": "production"
    },
    {
      "facility_id": "fac_bkzth74mqx09wergap5c",
      "name": "ME2",
      "code": "ME2",
      "city": null,
      "state": null,
      "mode": "production"
    },
    {
      "facility_id": "fac_j0h554r1qy2nzrkvspb4",
      "name": "HA3",
      "code": "HA3",
      "city": null,
      "state": null,
      "mode": "production"
    }
  ],
  "user": null,
  "organization": null,
  "role": null,
  "permissions": [
    "admin",
    "read",
    "submit",
    "webhooks"
  ],
  "office_scope": null,
  "authorization_version": null,
  "capabilities": {},
  "entitlements": [
    {
      "product": "eligibility",
      "state": "ACTIVE",
      "effective_from": "2026-09-05T14:30:00+00:00",
      "effective_to": null
    }
  ]
}
200OK (dashboard session)
{
  "request_id": "evt_qrspxxcadxgt581h8wkc",
  "principal": {
    "kind": "clerk",
    "subject": "clerk:0123456789abcdef01234567"
  },
  "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
  "seller_name": "Sample Dental Group",
  "seller_status": "READY",
  "scope": null,
  "user": {
    "display_name": "Sample Member",
    "email": "sample.member@example.com"
  },
  "organization": {
    "clerk_org_id": "org_EXAMPLE0000000000001",
    "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
    "name": "Sample Dental Group",
    "onboarding_state": "READY"
  },
  "mode": "production",
  "role": "submitter",
  "permissions": [
    "claims.read",
    "claims.submit",
    "offices.read"
  ],
  "office_scope": {
    "kind": "SUBSET",
    "facility_ids": [
      "fac_tycrfy0cs0qc7sq95eme"
    ]
  },
  "reachable_facility_ids": [
    "fac_tycrfy0cs0qc7sq95eme"
  ],
  "reachable_facilities": [
    {
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "name": "SBX",
      "code": "SBX",
      "city": null,
      "state": null,
      "mode": "sandbox"
    }
  ],
  "authorization_version": 3,
  "capabilities": {},
  "entitlements": [
    {
      "product": "eligibility",
      "state": "ACTIVE",
      "effective_from": "2026-09-05T14:30:00+00:00",
      "effective_to": null
    }
  ]
}
403Permission denied
{
  "error": "PERMISSION_DENIED",
  "message": "permission denied",
  "errors": [
    {
      "permission": "read"
    }
  ],
  "request_id": "evt_bkfrar1bddj3efgmw6s0",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-permission-denied",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, revoked or unverifiable credential
401UNAUTHORIZEDSession with no active membership in a bound organization
403PERMISSION_DENIEDCredential lacks read, or the session's membership, seller or onboarding is not active
403FACILITY_NOT_GRANTEDAPI key whose group or office grants resolve to no office
404NOT_FOUNDAPI key whose seller record does not exist
429TOO_MANY_REQUESTSRate or concurrency limit reached
InfoFields marked API key only or Session only are omitted, not null, for the other principal.
InfoA dashboard session gets read when it holds any *.read action. A session whose membership is not active, or whose organization is not fully onboarded, holds no actions and is refused with 403.
ImportantThe account reference page describes an earlier session shape (with seller_name, scope.office_scope and principal.role). The shapes above follow the current gateway; API key responses no longer carry scope.office_scope.
API reference

Get onboarding state

GEThttps://api.claimhouse.ai/v1/onboarding/state

Return where the signed-in person stands: ready, pending, blocked or no organization yet.

The first call after sign-in. It works for a person who has no organization or membership yet, and lists their own applications, access requests and any pending invitation addressed to their email.

Use allowed_actions to decide which screen to show next.

Permission
Signed-in dashboard session (no key permission, no membership needed)
Idempotency
none
Side effects
None. Reads only.
In the dashboard
Onboarding (after sign-in)

Headers

NameTypeDescription
Authorization*stringA signed-in dashboard session token (a JWT from the sign-in service) as Bearer <token>. API keys are refused on this route.
e.g. Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyX0VYQU1QTEUifQ.EXAMPLEsignature

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id, same as the X-Request-Id header.
state*stringREADY when the session's organization is onboarded; BLOCKED or SUSPENDED from the organization; PENDING when the person has an application, access request or invitation; else NO_ORGANIZATION.
one of: READY · BLOCKED · SUSPENDED · PENDING · NO_ORGANIZATION
applications*arrayThe person's own applications, newest first. Each item has the same fields as Get an onboarding application.
application_id*stringApplication id, app_....
status*stringApplication status.
one of: DRAFT · PENDING_REVIEW · NEEDS_INFORMATION · DECLINED · APPROVED · PROVISIONING · READY · BLOCKED
version*integerCurrent version.
display_name*stringDisplay name.
review_reasonstringReview guidance, or null.
invitationobjectThe most recent unexpired invitation addressed to the session's email in state SENT, ACCEPTED or OUTCOME_UNCERTAIN. Null when there is none or the session token carries no email.
invitation_id*stringInvitation id, inv_....
organization_name*stringThe inviting organization's name.
intended_email*stringThe email the invitation was addressed to.
state*stringInvitation state.
one of: PREPARED · DELIVERY_PENDING · SENT · ACCEPTED · RECONCILED · EXPIRED · REVOKED · DELIVERY_FAILED · OUTCOME_UNCERTAIN
version*integerInvitation version.
access_requests*arrayThe person's own access requests, newest first.
request_id*stringAccess request id, arq_.... Not the trace id.
organization_reference*stringThe organization reference the request named.
relationship_reason*stringWhy the person asked for access.
status*stringReview status.
one of: PENDING · APPROVED_FOR_INVITATION · DECLINED
version*integerCurrent version.
created_at*datetimeWhen it was created.
reviewed_atdatetimeWhen it was reviewed, or null.
allowed_actions*arrayArray of strings. ["enter_partner"] when state is READY, else ["create_application", "request_access"].

Responses

200OK
{
  "request_id": "evt_nj662q095m3fjmnsbj9r",
  "state": "READY",
  "applications": [],
  "invitation": null,
  "access_requests": [],
  "allowed_actions": [
    "enter_partner"
  ]
}
401Not a signed-in session
{
  "error": "UNAUTHORIZED",
  "message": "unauthorized",
  "errors": [],
  "request_id": "evt_devdp7p3r4z468arq3en",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-unauthorized",
  "user_message": "Claim House could not confirm who is signed in. Sign in again."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDNo session token, an API key was presented, or session sign-in is not configured
InfoIdentity-only routes do not use the per-key rate limits and do not require an organization.
InfoSUSPENDED is declared but not produced by the current organization statuses. An organization still in APPLICATION or PROVISIONING reports PENDING or NO_ORGANIZATION.
ImportantBeta: needs dashboard sign-in configured on the gateway. Without it every call returns 401. When the onboarding registry is not wired the lists come back empty rather than erroring.
API reference

Create an onboarding applicationComing soon

POSThttps://api.claimhouse.ai/v1/onboarding/applications

Save a company application as a DRAFT owned by the signed-in person.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get an onboarding applicationComing soon

GEThttps://api.claimhouse.ai/v1/onboarding/applications/{application_id}

Return one application owned by the signed-in person.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Update an onboarding applicationComing soon

PATCHhttps://api.claimhouse.ai/v1/onboarding/applications/{application_id}

Replace the details of a DRAFT or NEEDS_INFORMATION application.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Submit an onboarding applicationComing soon

POSThttps://api.claimhouse.ai/v1/onboarding/applications/{application_id}/submit

Move a DRAFT or NEEDS_INFORMATION application to PENDING_REVIEW.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Accept an organization invitation

POSThttps://api.claimhouse.ai/v1/onboarding/invitations/{invitation_id}/accept

Create one local membership from a sent invitation after the signed-in session's issuer, organization and verified email all match exactly.

The request body contains only expected_version. Identity and email come from the verified dashboard session and cannot be supplied by the caller.

Actions and explicit office grants are copied from the invitation in the same transaction. A replay or stale version is refused and never creates a second membership.

Permission
Signed-in dashboard session for the invited organization and verified email
Idempotency
one SENT to RECONCILED transition guarded by expected_version
Side effects
Creates one local membership and grants, then reconciles the invitation. It sends no email and contacts no external service.
In the dashboard
Onboarding > Accept invitation
API reference

Request access to an organizationComing soon

POSThttps://api.claimhouse.ai/v1/onboarding/access-requests

Ask an existing Claim House organization to let the signed-in person join.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

List access requests

GEThttps://api.claimhouse.ai/v1/access-requests

List every access request made to your organization, newest first.

For organization administrators reviewing who asked to join. Seller wide, not narrowed by office scope. Not paginated.

Permission
admin, from a dashboard session holding the members.manage action (API keys are refused)
Idempotency
none
Side effects
None. Reads only.
In the dashboard
Settings > Organization > Team > Invite and review

Headers

NameTypeDescription
Authorization*stringA signed-in dashboard session token (a JWT from the sign-in service) as Bearer <token>. API keys are refused on this route.
e.g. Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyX0VYQU1QTEUifQ.EXAMPLEsignature

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id, same as the X-Request-Id header.
access_requests*arrayAccess requests, newest first.
seller_id*stringYour seller id.
request_id*stringThe access request id, arq_....
requester_issuer*stringSign-in issuer of the requester.
requester_user_id*stringSign-in user id of the requester.
organization_reference*stringThe reference the requester typed.
relationship_reason*stringThe requester's stated reason.
status*stringReview status.
one of: PENDING · APPROVED_FOR_INVITATION · DECLINED
reviewer_idstringReviewer, or null.
review_reasonstringReview reason, or null.
version*integerCurrent version.
idempotency_key*stringThe key the requester sent.
created_at*datetimeWhen it was created.
reviewed_atdatetimeWhen it was reviewed, or null.

Responses

200OK
{
  "request_id": "evt_smqb8kmqf7gk589mq1ys",
  "access_requests": [
    {
      "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
      "request_id": "arq_EXAMPLE0000000000001",
      "requester_issuer": "https://issuer.EXAMPLE",
      "requester_user_id": "user_EXAMPLE0000000000001",
      "organization_reference": "SAMPLE-DENTAL-GROUP",
      "relationship_reason": "I manage billing for two Sample Dental Group offices.",
      "status": "PENDING",
      "reviewer_id": null,
      "review_reason": null,
      "version": 1,
      "idempotency_key": "3f0c2a4e-EXAMPLE-idempotency-key",
      "created_at": "2026-09-14T15:04:05+00:00",
      "reviewed_at": null
    }
  ]
}
403API key or missing member action
{
  "error": "PERMISSION_DENIED",
  "message": "members.manage is required",
  "errors": [],
  "request_id": "evt_vaqnezmamm7k8ty2e30h",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-permission-denied",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, revoked or unverifiable credential
403PERMISSION_DENIEDLacks admin, is an API key, or the session lacks members.manage
429TOO_MANY_REQUESTSRate or concurrency limit reached
InfoEach item's request_id is the access request id, while the top-level request_id is the trace id.
ImportantBeta: needs a dashboard session with an active membership. No route exists yet to approve or decline a request.
API reference

List members

GEThttps://api.claimhouse.ai/v1/members

List every person with a membership in your organization, with role, actions and office access.

Seller wide and not paginated. Read authorization_version from here before calling Update a member.

Permission
read, from a dashboard session holding the members.read action (API keys are refused)
Idempotency
none
Side effects
None. Reads only.
In the dashboard
Settings > Organization > Team

Headers

NameTypeDescription
Authorization*stringA signed-in dashboard session token (a JWT from the sign-in service) as Bearer <token>. API keys are refused on this route.
e.g. Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyX0VYQU1QTEUifQ.EXAMPLEsignature

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id, same as the X-Request-Id header.
members*arrayMembers ordered by membership id.
membership_id*stringThe membership id, mem_....
name*stringCurrently the member's sign-in user id, not a person name.
email*stringAlways an empty string today.
role*stringRole label.
one of: owner · admin · submitter · viewer
status*stringMembership status.
one of: PENDING · ACTIVE · SUSPENDED · REVOKED
actions*arrayArray of strings. Active member actions, sorted.
one of: claims.read · claims.submit · attachments.read · attachments.manage · eligibility.read · eligibility.check · remittances.read · members.read · members.manage · offices.read · offices.manage · keys.read · keys.manage · webhooks.read · webhooks.manage · usage.read · billing.read
scope_kind*stringOffice access kind.
one of: ALL · SUBSET · NONE
scope_ids*arrayArray of strings. Granted office ids. Empty for ALL and NONE.
scope_label*stringHuman label: All offices, <n> offices or No office access.
authorization_version*integerSend it back as expected_version when updating the member.
last_sign_in_atdatetimeLast time the membership was reconciled with sign-in, or null. Not a true last sign-in time.

Responses

200OK
{
  "request_id": "evt_smqb8kmqf7gk589mq1ys",
  "members": [
    {
      "membership_id": "mem_1w2pqxr89mss07rbry6s",
      "name": "user_EXAMPLE0000000000001",
      "email": "",
      "role": "submitter",
      "status": "ACTIVE",
      "actions": [
        "claims.read",
        "claims.submit",
        "offices.read"
      ],
      "scope_kind": "SUBSET",
      "scope_ids": [
        "fac_tycrfy0cs0qc7sq95eme"
      ],
      "scope_label": "1 offices",
      "authorization_version": 3,
      "last_sign_in_at": null
    }
  ]
}
403Missing member action
{
  "error": "PERMISSION_DENIED",
  "message": "members.read is required",
  "errors": [],
  "request_id": "evt_c0g0xxwhg11bv0p0yc26",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-permission-denied",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, revoked or unverifiable credential
403PERMISSION_DENIEDLacks read, is an API key, or the session lacks members.read
429TOO_MANY_REQUESTSRate or concurrency limit reached
ImportantBeta: needs a dashboard session with an active membership. name and email are placeholders until profile data is joined.
API reference

Update a member

PATCHhttps://api.claimhouse.ai/v1/members/{membership_id}

Replace a member's role, actions and office access.

A full replacement: the actions and office grants you send become the member's complete set, and any others are revoked.

You can only hand out what you hold. Every action must be one you have, ALL needs your own scope to be ALL, and SUBSET offices must be inside your own offices.

Permission
admin, from a dashboard session holding the members.manage action (API keys are refused)
Idempotency
none
Side effects
Rewrites the member's actions and office grants, increments authorization_version, and records an audit event with your reason. Takes effect on the member's next request.
In the dashboard
Settings > Organization > Team > Manage access

Headers

NameTypeDescription
Authorization*stringA signed-in dashboard session token (a JWT from the sign-in service) as Bearer <token>. API keys are refused on this route.
e.g. Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyX0VYQU1QTEUifQ.EXAMPLEsignature
Content-Type*stringMust be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.
e.g. application/json

Path parameters

NameTypeDescription
membership_id*stringThe membership id, mem_....
e.g. mem_1w2pqxr89mss07rbry6s

Request body

NameTypeDescription
expected_version*integerThe member's authorization_version from List members. Minimum 1.
e.g. 3
role*stringThe role label to record.
one of: owner · admin · submitter · viewer
e.g. viewer
actionsarrayArray of strings. The member's complete action set. Up to 100. Each must be one you hold. Defaults to empty, which removes every action.
one of: claims.read · claims.submit · attachments.read · attachments.manage · eligibility.read · eligibility.check · remittances.read · members.read · members.manage · offices.read · offices.manage · keys.read · keys.manage · webhooks.read · webhooks.manage · usage.read · billing.read
e.g. ["claims.read","offices.read"]
scope_kind*stringALL for every current and future office, SUBSET for the listed offices, NONE for no office data.
one of: ALL · SUBSET · NONE
e.g. SUBSET
office_idsarrayArray of strings. Required and non-empty for SUBSET; must be empty otherwise. Up to 500 office ids of your seller.
e.g. ["fac_EXAMPLE0000000000001"]
reason*stringWhy the access changed. 3 to 1000 characters. Stored with the audit event.
e.g. Moved to front desk role.

Request example

{
  "expected_version": 3,
  "role": "viewer",
  "actions": [
    "claims.read",
    "offices.read"
  ],
  "scope_kind": "SUBSET",
  "office_ids": [
    "fac_tycrfy0cs0qc7sq95eme"
  ],
  "reason": "Moved to front desk role."
}

Response fields

NameTypeDescription
seller_id*stringYour seller id.
membership_id*stringThe membership id, mem_....
clerk_issuer*stringThe sign-in issuer of the member.
clerk_user_id*stringThe member's sign-in user id.
clerk_org_id*stringThe sign-in organization the membership belongs to.
role_template*stringThe member's role label after the change.
one of: owner · admin · submitter · viewer
status*stringMembership status.
one of: PENDING · ACTIVE · SUSPENDED · REVOKED
authorization_version*integerIncrements on every access change. Send it back as expected_version.
all_current_and_future_offices*booleanTrue when the new scope is ALL.
invitation_idstringThe invitation the membership came from, or null.
source*stringHow the membership was created, for example invitation.
activated_atdatetimeWhen it became active, or null.
suspended_atdatetimeWhen it was suspended, or null.
revoked_atdatetimeWhen it was revoked, or null.
last_reconciled_clerk_eventstringLast sign-in provider event applied, or null.
last_reconciled_atdatetimeWhen it was last reconciled, or null.

Responses

200OK
{
  "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
  "membership_id": "mem_1w2pqxr89mss07rbry6s",
  "clerk_issuer": "https://issuer.EXAMPLE",
  "clerk_user_id": "user_EXAMPLE0000000000001",
  "clerk_org_id": "org_EXAMPLE0000000000001",
  "role_template": "viewer",
  "status": "ACTIVE",
  "authorization_version": 4,
  "all_current_and_future_offices": false,
  "invitation_id": "inv_c78sg2v0veqke88d7h7s",
  "source": "invitation",
  "activated_at": "2026-09-14T15:04:05+00:00",
  "suspended_at": null,
  "revoked_at": null,
  "last_reconciled_clerk_event": null,
  "last_reconciled_at": null
}
403Delegation exceeded
{
  "error": "DELEGATION_EXCEEDED",
  "message": "membership proposal exceeds caller offices",
  "errors": [],
  "request_id": "evt_bkfrar1bddj3efgmw6s0",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-delegation-exceeded",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}
409Change refused
{
  "error": "MEMBERSHIP_CHANGE_REFUSED",
  "message": "the final active owner cannot be demoted",
  "errors": [],
  "request_id": "evt_bkfrar1bddj3efgmw6s0",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-membership-change-refused",
  "user_message": "This changed since you opened it. Reload the page and try again."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, revoked or unverifiable credential
403PERMISSION_DENIEDLacks admin, is an API key, or the session lacks members.manage
403DELEGATION_EXCEEDEDActions or offices exceed yours, or office_ids do not fit scope_kind
409STALE_VERSION_OR_STATEexpected_version is stale or the membership id is unknown
409MEMBERSHIP_CHANGE_REFUSEDDemoting the last active owner, or an office id that is not yours
422INVALID_REQUESTBody, path or header does not fit the schema
429TOO_MANY_REQUESTSRate or concurrency limit reached
InfoThe response is the membership record and carries no request_id, actions or office list. Call List members to see the new access.
Inforole is a label. What the member can do comes from actions and office scope.
ImportantBeta: needs a dashboard session with an active membership. An unknown membership id returns 409, not 404.
API reference

List invitations

GEThttps://api.claimhouse.ai/v1/invitations

List every invitation your organization has prepared, newest first.

Seller wide and not paginated. Read version from here before sending or revoking.

Permission
admin, from a dashboard session holding the members.manage action (API keys are refused)
Idempotency
none
Side effects
None. Reads only.
In the dashboard
Settings > Organization > Team > Invite and review

Headers

NameTypeDescription
Authorization*stringA signed-in dashboard session token (a JWT from the sign-in service) as Bearer <token>. API keys are refused on this route.
e.g. Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyX0VYQU1QTEUifQ.EXAMPLEsignature

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id, same as the X-Request-Id header.
invitations*arrayInvitations, newest first.
invitation_id*stringThe invitation id, inv_....
organization_name*stringYour organization's display name, or legal name.
intended_email*stringThe invitee email.
email*stringSame value as intended_email.
role*stringProposed role label.
one of: owner · admin · submitter · viewer
office_scope*objectProposed office access.
kind*stringScope kind.
one of: ALL · SUBSET · NONE
facility_idsarrayArray of strings. Present only when kind is SUBSET.
state*stringInvitation state.
one of: PREPARED · DELIVERY_PENDING · SENT · ACCEPTED · RECONCILED · EXPIRED · REVOKED · DELIVERY_FAILED · OUTCOME_UNCERTAIN
version*integerCurrent version.
created_at*datetimeWhen it was prepared.

Responses

200OK
{
  "request_id": "evt_smqb8kmqf7gk589mq1ys",
  "invitations": [
    {
      "invitation_id": "inv_c78sg2v0veqke88d7h7s",
      "organization_name": "Sample Dental Group",
      "intended_email": "sample.teammate@example.com",
      "email": "sample.teammate@example.com",
      "role": "submitter",
      "office_scope": {
        "kind": "SUBSET",
        "facility_ids": [
          "fac_tycrfy0cs0qc7sq95eme"
        ]
      },
      "state": "PREPARED",
      "version": 1,
      "created_at": "2026-09-14T15:04:05+00:00"
    }
  ]
}
403API key or missing member action
{
  "error": "PERMISSION_DENIED",
  "message": "members.manage is required",
  "errors": [],
  "request_id": "evt_52t06r6aw1f55ava9sp3",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-permission-denied",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, revoked or unverifiable credential
403PERMISSION_DENIEDLacks admin, is an API key, or the session lacks members.manage
429TOO_MANY_REQUESTSRate or concurrency limit reached
InfoThis list uses a shaped view. Create, send and revoke return the raw invitation record instead (intended_email_display, role_template, proposed_scope_kind).
ImportantBeta: needs a dashboard session with an active membership.
API reference

Prepare an invitation

POSThttps://api.claimhouse.ai/v1/invitations

Record a PREPARED invitation for a teammate without sending anything.

Stores who to invite, with the role, actions and office access they will get. Nothing is emailed; delivery is a separate, confirmed step (Send an invitation).

You can only offer what you hold: every action must be yours, ALL needs your own scope to be ALL, and offices must be inside your own.

Permission
admin, from a dashboard session holding the members.manage action (API keys are refused)
Idempotency
none
Side effects
Stores one PREPARED invitation with its actions and office grants. Sends no email and contacts no sign-in provider.
In the dashboard
Settings > Organization > Team > Invite and review (Prepare invitation)

Headers

NameTypeDescription
Authorization*stringA signed-in dashboard session token (a JWT from the sign-in service) as Bearer <token>. API keys are refused on this route.
e.g. Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyX0VYQU1QTEUifQ.EXAMPLEsignature
Content-Type*stringMust be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.
e.g. application/json

Request body

NameTypeDescription
email*stringThe invitee email. 3 to 254 characters, must contain @. Stored lowercased.
e.g. sample.teammate@example.com
role*stringThe role label to propose.
one of: owner · admin · submitter · viewer
e.g. submitter
scope_kind*stringProposed office access.
one of: ALL · SUBSET · NONE
e.g. SUBSET
office_idsarrayArray of strings. Required and non-empty for SUBSET; must be empty otherwise. Up to 500, each inside your own office access.
e.g. ["fac_EXAMPLE0000000000001"]
actionsarrayArray of strings. The actions the invitee will hold. Up to 100, each one you hold.
one of: claims.read · claims.submit · attachments.read · attachments.manage · eligibility.read · eligibility.check · remittances.read · members.read · members.manage · offices.read · offices.manage · keys.read · keys.manage · webhooks.read · webhooks.manage · usage.read · billing.read
e.g. ["claims.read","claims.submit","offices.read"]
expires_at*datetimeWhen the invitation expires. The dashboard uses seven days from now.
e.g. 2026-09-21T15:04:05+00:00

Request example

{
  "email": "sample.teammate@example.com",
  "role": "submitter",
  "scope_kind": "SUBSET",
  "office_ids": [
    "fac_tycrfy0cs0qc7sq95eme"
  ],
  "actions": [
    "claims.read",
    "claims.submit",
    "offices.read"
  ],
  "expires_at": "2026-09-21T15:04:05+00:00"
}

Response fields

NameTypeDescription
seller_id*stringYour seller id, sel_....
invitation_id*stringThe invitation id, inv_....
intended_email_digest*stringSHA-256 hex digest of the lowercased invitee email.
intended_email_display*stringThe invitee email, lowercased.
role_template*stringThe role label proposed for the invitee.
one of: owner · admin · submitter · viewer
proposed_scope_kind*stringThe office scope proposed for the invitee.
one of: ALL · SUBSET · NONE
expires_at*datetimeWhen the invitation stops being valid.
clerk_invitation_idstringThe sign-in provider's invitation id once delivered, else null.
delivery_operation_idstringId of the single delivery attempt once one starts, else null.
state*stringInvitation state.
one of: PREPARED · DELIVERY_PENDING · SENT · ACCEPTED · RECONCILED · EXPIRED · REVOKED · DELIVERY_FAILED · OUTCOME_UNCERTAIN
version*integerIncrements on every change. Send it back as expected_version.
created_by*stringThe user id of the administrator who prepared it.
created_at*datetimeWhen it was prepared.
revoked_atdatetimeWhen it was revoked, else null.
accepted_atdatetimeWhen acceptance was observed, else null.
reconciled_atdatetimeWhen membership was reconciled, else null.

Responses

201Created
{
  "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
  "invitation_id": "inv_c78sg2v0veqke88d7h7s",
  "intended_email_digest": "0000000000000000000000000000000000000000000000000000000000000000",
  "intended_email_display": "sample.teammate@example.com",
  "role_template": "submitter",
  "proposed_scope_kind": "SUBSET",
  "expires_at": "2026-09-21T15:04:05+00:00",
  "clerk_invitation_id": null,
  "delivery_operation_id": null,
  "state": "PREPARED",
  "version": 1,
  "created_by": "user_EXAMPLE0000000000001",
  "created_at": "2026-09-14T15:04:05+00:00",
  "revoked_at": null,
  "accepted_at": null,
  "reconciled_at": null
}
403Delegation exceeded
{
  "error": "DELEGATION_EXCEEDED",
  "message": "membership proposal exceeds caller actions",
  "errors": [],
  "request_id": "evt_bkfrar1bddj3efgmw6s0",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-delegation-exceeded",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}
403API key
{
  "error": "PERMISSION_DENIED",
  "message": "human member administration is required",
  "errors": [],
  "request_id": "evt_a83nh7hhkqk6kgqkghrh",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-permission-denied",
  "user_message": "Your account does not have access to do this. Ask an administrator in your organization."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, revoked or unverifiable credential
403PERMISSION_DENIEDLacks admin, or is an API key
403DELEGATION_EXCEEDEDSession lacks members.manage, actions or offices exceed yours, or office_ids do not fit scope_kind
404NOT_FOUNDAn office id outside your own office access
422INVALID_REQUESTBody, path or header does not fit the schema
429TOO_MANY_REQUESTSRate or concurrency limit reached
503REGISTRY_WRITE_FAILEDThe invitation was not stored
InfoNot idempotent: each call prepares a new invitation, even for the same email.
ImportantBeta: a known server fault currently makes this route return a plain-text 500 after the permission checks pass, before anything is stored.
API reference

Send an invitation

POSThttps://api.claimhouse.ai/v1/invitations/{invitation_id}/send

Deliver a PREPARED invitation through the sign-in provider, once.

Requires explicit confirmation. Moves the invitation to DELIVERY_PENDING, makes exactly one delivery attempt, then records SENT.

If the attempt fails or its outcome is unclear, the invitation becomes OUTCOME_UNCERTAIN and the route answers 502. Do not resend.

Permission
admin, from a dashboard session holding the members.manage action (API keys are refused)
Idempotency
none
Side effects
When delivery is configured, makes one invitation delivery attempt and records the outcome. On this gateway delivery is not configured, so nothing is sent and the state does not change.
In the dashboard
API only

Headers

NameTypeDescription
Authorization*stringA signed-in dashboard session token (a JWT from the sign-in service) as Bearer <token>. API keys are refused on this route.
e.g. Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyX0VYQU1QTEUifQ.EXAMPLEsignature
Content-Type*stringMust be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.
e.g. application/json

Path parameters

NameTypeDescription
invitation_id*stringThe invitation id, inv_....
e.g. inv_c78sg2v0veqke88d7h7s

Request body

NameTypeDescription
expected_version*integerThe invitation version you last read. Minimum 1.
e.g. 1
confirmed*booleanMust be true. Confirms you intend a real delivery.
e.g. true

Request example

{
  "expected_version": 1,
  "confirmed": true
}

Response fields

NameTypeDescription
seller_id*stringYour seller id, sel_....
invitation_id*stringThe invitation id, inv_....
intended_email_digest*stringSHA-256 hex digest of the lowercased invitee email.
intended_email_display*stringThe invitee email, lowercased.
role_template*stringThe role label proposed for the invitee.
one of: owner · admin · submitter · viewer
proposed_scope_kind*stringThe office scope proposed for the invitee.
one of: ALL · SUBSET · NONE
expires_at*datetimeWhen the invitation stops being valid.
clerk_invitation_idstringThe sign-in provider's invitation id once delivered, else null.
delivery_operation_idstringId of the single delivery attempt once one starts, else null.
state*stringInvitation state.
one of: PREPARED · DELIVERY_PENDING · SENT · ACCEPTED · RECONCILED · EXPIRED · REVOKED · DELIVERY_FAILED · OUTCOME_UNCERTAIN
version*integerIncrements on every change. Send it back as expected_version.
created_by*stringThe user id of the administrator who prepared it.
created_at*datetimeWhen it was prepared.
revoked_atdatetimeWhen it was revoked, else null.
accepted_atdatetimeWhen acceptance was observed, else null.
reconciled_atdatetimeWhen membership was reconciled, else null.

Responses

503Delivery not configured
{
  "error": "INVITATION_DELIVERY_UNCONFIGURED",
  "message": "invitation delivery is not configured",
  "errors": [],
  "request_id": "evt_3ss6bwba7cb1y4etkcwf",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "CONTACT_SUPPORT",
  "doc_url": "https://docs.claimhouse.ai/#error-invitation-delivery-unconfigured",
  "user_message": "Something on our side is not available right now. Try again later, or contact Claim House support."
}
200Sent (when delivery is configured)
{
  "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
  "invitation_id": "inv_c78sg2v0veqke88d7h7s",
  "intended_email_digest": "0000000000000000000000000000000000000000000000000000000000000000",
  "intended_email_display": "sample.teammate@example.com",
  "role_template": "submitter",
  "proposed_scope_kind": "SUBSET",
  "expires_at": "2026-09-21T15:04:05+00:00",
  "clerk_invitation_id": "inv_s6kv7qsg8edf9b9me10y_EXAMPLE",
  "delivery_operation_id": "op_fh92fzqy215mtxw02a6d",
  "state": "SENT",
  "version": 3,
  "created_by": "user_EXAMPLE0000000000001",
  "created_at": "2026-09-14T15:04:05+00:00",
  "revoked_at": null,
  "accepted_at": null,
  "reconciled_at": null
}
502Outcome uncertain
{
  "code": "DELIVERY_OUTCOME_UNCERTAIN",
  "message": "delivery may have succeeded; reconcile instead of resending",
  "invitation": {
    "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
    "invitation_id": "inv_c78sg2v0veqke88d7h7s",
    "intended_email_digest": "0000000000000000000000000000000000000000000000000000000000000000",
    "intended_email_display": "sample.teammate@example.com",
    "role_template": "submitter",
    "proposed_scope_kind": "SUBSET",
    "expires_at": "2026-09-21T15:04:05+00:00",
    "clerk_invitation_id": null,
    "delivery_operation_id": null,
    "state": "OUTCOME_UNCERTAIN",
    "version": 3,
    "created_by": "user_EXAMPLE0000000000001",
    "created_at": "2026-09-14T15:04:05+00:00",
    "revoked_at": null,
    "accepted_at": null,
    "reconciled_at": null
  }
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, revoked or unverifiable credential
403PERMISSION_DENIEDLacks admin, is an API key, or the session lacks members.manage
409CONFIRMATION_REQUIREDconfirmed is not true
409STALE_VERSION_OR_STATEVersion mismatch, not PREPARED, or unknown id
502DELIVERY_OUTCOME_UNCERTAINDelivery failed or could not be recorded; do not resend
503INVITATION_DELIVERY_UNCONFIGUREDNo delivery provider is configured (the current default)
422INVALID_REQUESTBody, path or header does not fit the schema
429TOO_MANY_REQUESTSRate or concurrency limit reached
ImportantBeta: invitation delivery is not configured on the gateway today, so every confirmed call returns 503 INVITATION_DELIVERY_UNCONFIGURED and no email is sent.
ImportantThe 502 body is not the standard envelope: it has code, message and invitation, with no error or request_id. No route can clear OUTCOME_UNCERTAIN yet; contact Claim House support.
API reference

Revoke an invitation

POSThttps://api.claimhouse.ai/v1/invitations/{invitation_id}/revoke

Mark a PREPARED or SENT invitation as REVOKED so it cannot be used.

Records the revocation in Claim House. A revoked invitation cannot be sent or reused; prepare a new one instead.

Permission
admin, from a dashboard session holding the members.manage action (API keys are refused)
Idempotency
none
Side effects
Sets the invitation state to REVOKED and stamps revoked_at. Does not contact the sign-in provider.
In the dashboard
API only

Headers

NameTypeDescription
Authorization*stringA signed-in dashboard session token (a JWT from the sign-in service) as Bearer <token>. API keys are refused on this route.
e.g. Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyX0VYQU1QTEUifQ.EXAMPLEsignature
Content-Type*stringMust be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.
e.g. application/json

Path parameters

NameTypeDescription
invitation_id*stringThe invitation id, inv_....
e.g. inv_c78sg2v0veqke88d7h7s

Request body

NameTypeDescription
expected_version*integerThe invitation version you last read. Minimum 1.
e.g. 1
reason*stringWhy it is revoked. 1 to 1000 characters.
e.g. Invited the wrong address.

Request example

{
  "expected_version": 1,
  "reason": "Invited the wrong address."
}

Response fields

NameTypeDescription
seller_id*stringYour seller id, sel_....
invitation_id*stringThe invitation id, inv_....
intended_email_digest*stringSHA-256 hex digest of the lowercased invitee email.
intended_email_display*stringThe invitee email, lowercased.
role_template*stringThe role label proposed for the invitee.
one of: owner · admin · submitter · viewer
proposed_scope_kind*stringThe office scope proposed for the invitee.
one of: ALL · SUBSET · NONE
expires_at*datetimeWhen the invitation stops being valid.
clerk_invitation_idstringThe sign-in provider's invitation id once delivered, else null.
delivery_operation_idstringId of the single delivery attempt once one starts, else null.
state*stringInvitation state.
one of: PREPARED · DELIVERY_PENDING · SENT · ACCEPTED · RECONCILED · EXPIRED · REVOKED · DELIVERY_FAILED · OUTCOME_UNCERTAIN
version*integerIncrements on every change. Send it back as expected_version.
created_by*stringThe user id of the administrator who prepared it.
created_at*datetimeWhen it was prepared.
revoked_atdatetimeWhen it was revoked, else null.
accepted_atdatetimeWhen acceptance was observed, else null.
reconciled_atdatetimeWhen membership was reconciled, else null.

Responses

200OK
{
  "seller_id": "sel_s4zf3w33k6x8j1e1z6sh",
  "invitation_id": "inv_c78sg2v0veqke88d7h7s",
  "intended_email_digest": "0000000000000000000000000000000000000000000000000000000000000000",
  "intended_email_display": "sample.teammate@example.com",
  "role_template": "submitter",
  "proposed_scope_kind": "SUBSET",
  "expires_at": "2026-09-21T15:04:05+00:00",
  "clerk_invitation_id": null,
  "delivery_operation_id": null,
  "state": "REVOKED",
  "version": 2,
  "created_by": "user_EXAMPLE0000000000001",
  "created_at": "2026-09-14T15:04:05+00:00",
  "revoked_at": "2026-09-14T15:10:00+00:00",
  "accepted_at": null,
  "reconciled_at": null
}
409Stale version or state
{
  "error": "STALE_VERSION_OR_STATE",
  "message": "invitation changed; reload before retrying",
  "errors": [],
  "request_id": "evt_bkfrar1bddj3efgmw6s0",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-stale-version-or-state",
  "user_message": "This changed since you opened it. Reload the page and try again."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, revoked or unverifiable credential
403PERMISSION_DENIEDLacks admin, is an API key, or the session lacks members.manage
409STALE_VERSION_OR_STATEVersion mismatch, not PREPARED or SENT, or unknown id
422INVALID_REQUESTBody, path or header does not fit the schema
429TOO_MANY_REQUESTSRate or concurrency limit reached
Inforeason is required but is not stored today.
ImportantBeta: needs a dashboard session with an active membership. Revoking a SENT invitation does not withdraw the email already delivered by the sign-in provider.
API reference

Read notification preferencesComing soon

GEThttps://api.claimhouse.ai/v1/notification-preferences

Read the signed-in member's email notification preferences.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Save notification preferencesComing soon

PUThttps://api.claimhouse.ai/v1/notification-preferences

Replace the signed-in member's notification preferences, guarded by a version check.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Request a product entitlementComing soon

POSThttps://api.claimhouse.ai/v1/entitlement-requests

Ask Claim House to enable a product for your organization.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Look up candidate organizations

GEThttps://api.claimhouse.ai/v1/onboarding/organizations

Resolve which of the candidate organizations the signed-in identity belongs to.

During sign-up the dashboard may hold candidate organization ids (for example from an invitation link). This route returns only the candidates where the verified identity actually holds a membership: naming another identity's organization reveals nothing.

Answers private, no-store. Use it to pre-fill organization choice during onboarding; it is not a directory and cannot be probed for other organizations.

Permission
Signed-in dashboard session (no key permission, no membership needed)
Idempotency
none
Side effects
None. Read only.
In the dashboard
Sign-up > choose organization

Headers

NameTypeDescription
Authorization*stringA signed-in session token as Bearer <token>. This is an onboarding route: it answers before membership exists, so API keys are not used.
e.g. Bearer <session token>

Query parameters

NameTypeDescription
organization_ids*stringComma-separated candidate organization ids: 1 to 100 values, each at most 200 characters with no surrounding whitespace.
e.g. org_EXAMPLE00000000001,org_EXAMPLE00000000002

Request example

null

Response fields

NameTypeDescription
request_id*stringUnique id for this request. Also returned in the X-Request-Id header.
e.g. evt_EXAMPLE0000000000000031
organizations*arrayThe candidates this identity belongs to, in candidate order.
organization_id*stringThe organization id.
e.g. org_EXAMPLE0000000000000001
name*stringOrganization display name.
e.g. Northgate Dental Partners
state*stringMembership readiness for this identity.
one of: READY · SUSPENDED · PENDING · BLOCKED
e.g. READY
authorization_version*integerThe organization's authorization version at read time.
e.g. 3
can_enter*booleanTrue when the identity may enter this organization now (active membership, active organization, onboarding ready).
e.g. true

Responses

200OK
{
  "request_id": "evt_ang0n1gexynjw0dmfh8v",
  "organizations": [
    {
      "organization_id": "org_35ka7045j25e5w5h2a32",
      "name": "Northgate Dental Partners",
      "state": "READY",
      "authorization_version": 3,
      "can_enter": true
    }
  ]
}

Errors

StatusCodeWhen
401UNAUTHORIZEDmissing, invalid or expired session token
422INVALID_ORGANIZATION_CANDIDATESzero or more than 100 ids, an empty value, or an id over 200 characters
503IDENTITY_REGISTRY_UNAVAILABLEorganization access cannot be verified
429TOO_MANY_REQUESTSrate or concurrency limit reached
InfoOnly memberships of the signed-in identity are returned. The route answers a locator question during sign-up; it is not an organization search.
API reference

Events and files

Pull the append-only event feed and download the raw X12 and PDF bytes behind each event.

Every change Claim House records about your claims, eligibility checks and linked attachment sends is an event. Events are append-only and never updated or deleted. Webhooks push the same rows this feed returns. Claim events produced by the state machine carry kind, from_state, applied (true when the event moved the claim), state (after) and verdict_state (what the event implies on its own) in summary.

TypeMeaningClaim state effectartifact_idKey summary fields
claim.receivedSubmission stored but held at intake for review.Created in HOLD.nonesubmission_id, state, finding_codes
claim.queuedPassed intake, waiting for a transport window.Created in QUEUED.nonesubmission_id, state, finding_codes
submission.rejected_pre_transportIntake edits rejected the submission, one event per claim. Nothing sent.Created in REJECTED_PRE_TRANSPORT (terminal).nonesubmission_id, state, finding_codes
claim.transportedThe outbound 837D file was uploaded once and verified by read-back.Moves to TRANSPORTED.The 837D file as sentfile_id, file_stem, window_id, session_id
claim.transport_ambiguousThe single upload attempt failed or could not be verified. Never resent automatically.Moves to TRANSPORT_AMBIGUOUS.The 837D file attemptedfile_id, reason (put_failed:<ErrorClass> or readback_mismatch)
claim.operator_resolvedAn operator settled an ambiguous file with the clearinghouse.TRANSPORTED (delivered), QUEUED (not delivered) or CLOSED (dead).noneresolution, resolved_by, file_id, note
claim.ack_997A 997 acknowledgment arrived.Accepted to ACK_997_ACCEPTED, including a set accepted with errors (E), which must not be resent; rejected to NEEDS_CORRECTION.The 997 filegroup_code, transaction_code, ack_kind, accepted_with_errors, errors, error_count
claim.ack_999A 999 acknowledgment arrived.Same as claim.ack_997.The 999 fileSame as claim.ack_997, ack_kind 999
claim.status_277A 277 or 277CA claim status arrived.By STC01-1 category: received, accepted, rejected (to NEEDS_CORRECTION), pending or final. Unknown category has category_unmapped: true and no change.The 277 filecategory_code, status_code, entity_code, effective_date, payer_claim_number
claim.stalled_997No 997 within the window after transport (default 4 hours). Raised once.STALLED_997, only from TRANSPORTED.noneexpected_event_kind, due_at, sla_seconds
claim.stalled_277No 277 within the window after transport (default 2 days). Raised once.STALLED_277, only from TRANSPORTED.noneexpected_event_kind, due_at, sla_seconds
claim.paidAn 835 line paid the claim fully or partly.Moves to PAID (not from REJECTED_PRE_TRANSPORT).The 835 fileclaim_status_code, remittance_id, payment_id, charged_amount, paid_amount, patient_responsibility, trace_number, payment_date
claim.deniedAn 835 line with CLP02 4 denied the claim.Moves to DENIED.The 835 fileSame as claim.paid
claim.reversedAn 835 line with CLP02 22 reversed a payment.Moves to REVERSED.The 835 fileSame as claim.paid
remittance.receivedAn 835 file included at least one of your claims. One per seller per file.None (applied: false).The 835 fileremittance_id, claim_count, paid_amount, claim_ids, trace_number, payment_method, payer_id
eligibility.checkedAn eligibility check finished.No claim (claim_id is null).noneeligibility_id, payer_id, status, outcome, cache, mode
eligibility.pdf_generatedA PDF of an eligibility answer was generated.No claim.The PDFeligibility_id, artifact_id, filename, bytes
attachment.sentAn attachment packet was delivered and named a resolvable claim.None (applied: false).nonepacket_id, payer_id, door, outcome (OK), reference, send_id
attachment.failedAn attachment send failed or was ambiguous and named a resolvable claim.None.noneSame as attachment.sent, outcome FAILED or AMBIGUOUS
attachment.packet_createdA packet was created.Written only to the packet's own timeline, so it does not appear in this feed today.nonepacket_id, attachment_count, deduplicated_count, kinds
  1. Load your stored cursor (start at 0). The cursor is a plain integer and never expires.
  2. Call GET /v1/events?since_cursor=<cursor>&limit=500. Events come back oldest first in ascending sequence.
  3. Process each event, skipping any event_id you already processed. sequence is shared by every seller, so gaps are normal.
  4. Store next_cursor only after processing succeeds. On an empty page it echoes your since_cursor.
  5. If has_more is true, repeat immediately; otherwise wait 30 to 60 seconds. Resume from a cursor a few hundred sequence numbers behind your last one to catch late-committing events, and de-duplicate by event_id.
  • Out-of-order evidence is normal: a 277 can arrive before its 997. Use applied and state, not the event type, to know the current claim state.
  • occurred_at is not monotonic with sequence. Never order or resume by time.
  • One inbound 997, 999, 277 or 835 file is copied once per seller and office, so several claims can point at the same artifact_id. Parse it by your patient control number.
  • Summaries never contain patient names, dates of birth or member ids. They can contain control numbers and amounts.
RecordIdWhere you find the idWhat you get
Artifactart_...artifact_id on events, remittance records and the eligibility PDF responseA short-lived download URL for one stored document (837D, 997, 999, 277, 835 or eligibility PDF).
Filefile_...transport.file_id on a submission, or summary.file_id on transport eventsThe transport record of one outbound 837D file (control numbers, hash, state) plus a download URL when one exists.
API reference

List eventsComing soon

GEThttps://api.claimhouse.ai/v1/events

Page through your events after a cursor, oldest first.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get an artifact

GEThttps://api.claimhouse.ai/v1/artifacts/{artifact_id}

Get a short-lived download URL for one stored document.

Returns a freshly signed URL to one stored 837D, 997, 999, 277, 835 or eligibility PDF, plus the claim and event it belongs to. Call it at the moment a user clicks download, not when you render a page.

Inbound 997, 999, 277 and 835 artifacts are the whole file as received, not a slice for one claim. When one artifact covers several claims, claim_id is the claim of the first referencing event only.

Permission
read
Idempotency
none
Side effects
Signs a new URL locally and records one audit entry. No vendor or clearinghouse call.
In the dashboard
Claims > Claim detail

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Path parameters

NameTypeDescription
artifact_id*stringThe artifact id (art_...), 1 to 64 characters. Must be referenced by an event in your seller and grants.
e.g. art_5ajgzw1wwge9x43v86b2

Request example

null

Response fields

NameTypeDescription
request_id*stringThe request id.
e.g. evt_EXAMPLE0000000000202
artifact_id*stringThe id you asked for.
e.g. art_EXAMPLE0000000000277
download_filenamestringSuggested file name such as NORTH-20260912-0007_277_s01_r01.edi. Null unless the first event is an 837D, 997, 999 or 277 for exactly one claim that has a claim_reference.
claim_idstringClaim of the first event that references this artifact. Null for an eligibility PDF.
facility_id*stringOffice of that first event.
e.g. fac_EXAMPLE0000000000001
event_kind*stringType of that first event.
e.g. claim.status_277
url*stringThe download URL. Anyone holding it can download the file until it expires, so never log or store it.
expires_in_seconds*integerLifetime of url in seconds.
e.g. 600

Responses

200OK
{
  "request_id": "evt_1jnvj4ackt0ndkm9awpm",
  "artifact_id": "art_5ajgzw1wwge9x43v86b2",
  "download_filename": null,
  "claim_id": "clm_sey00k954s2ctghndb3h",
  "facility_id": "fac_tycrfy0cs0qc7sq95eme",
  "event_kind": "claim.transported",
  "url": "https://archive.example/sellers/sel_s4zf3w33k6x8j1e1z6sh/fac_tycrfy0cs0qc7sq95eme/artifacts/art_5ajgzw1wwge9x43v86b2?ttl=600",
  "expires_in_seconds": 600
}
404Not found
{
  "error": "NOT_FOUND",
  "message": "no such artifact",
  "errors": [],
  "request_id": "evt_21qntm5psys23mxtpbqd",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-not-found",
  "user_message": "We could not find that item. It may have been removed, or you may not have access to it."
}
503URL unavailable
{
  "error": "ARTIFACT_URL_UNAVAILABLE",
  "message": "this archive store cannot produce a retrieval URL",
  "errors": [],
  "request_id": "evt_bkfrar1bddj3efgmw6s0",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "CONTACT_SUPPORT",
  "doc_url": "https://docs.claimhouse.ai/#error-artifact-url-unavailable",
  "user_message": "Something on our side is not available right now. Try again later, or contact Claim House support."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing, malformed, unknown or revoked key, or wrong secret
403PERMISSION_DENIEDThe credential lacks read
403FACILITY_NOT_GRANTEDThe key has no office grant at all
404NOT_FOUNDNo event in your seller and grants references this id
422INVALID_REQUESTartifact_id longer than 64 characters
429TOO_MANY_REQUESTSMore than 20 requests in flight or the read bucket is empty
503ARTIFACT_URL_UNAVAILABLEThe archive store cannot produce a URL
InfoFilenames use <claim_reference>_<KIND>_s01.edi for the 837D and <claim_reference>_<KIND>_s01_rNN.edi for responses, where NN counts that kind of response for the claim. 835 artifacts and eligibility PDFs never get a filename.
ImportantEach call signs a new URL that expires after expires_in_seconds (600 today). Do not cache it, log it or put it in page HTML.
InfoA local development gateway returns a file:// path on the gateway machine instead of a signed URL.
API reference

Get an outbound fileComing soon

GEThttps://api.claimhouse.ai/v1/files/{file_id}

Get the transport record of one outbound 837D file and a download link when one exists.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

List API requests

GEThttps://api.claimhouse.ai/v1/api-requests

List every authenticated call to the Claim House API for your account, newest first: route, status, time taken, office, ids touched and error code.

Use it to see what your integration and your team did, and to find the request behind an error. Calls from API keys and from the dashboard are both listed.

Rows hold ids and codes only. No request or response bodies and no patient details are kept. Open a listed id, for example a check, to see it.

Filters combine. Page with before, set to the next_cursor of the previous page.

Permission
read
Idempotency
none
Side effects
None. Reading the log writes no audit row and is not itself logged. Never contacts a payer or the clearinghouse.
In the dashboard
Activity > API requests

Headers

NameTypeDescription
Authorization*stringYour API key as Bearer key_<20 characters>.<secret> (the key id is key_ plus 20 lowercase base32 characters). A signed-in dashboard session token is also accepted.
e.g. Bearer key_7qm2x9d4hs3ve6kt8wbn.EXAMPLEsecretEXAMPLEsecret

Query parameters

NameTypeDescription
facility_idstringOnly calls that named this office. Repeat the parameter for several offices. Each must be granted to your key.
e.g. fac_tycrfy0cs0qc7sq95eme
outcomestringok (status below 400), error (400 and above), client_error (400 to 499) or server_error (500 and above).
one of: ok · error · client_error · server_error
e.g. error
sourcestringOnly API key calls or only dashboard calls.
one of: api_key · dashboard
e.g. api_key
productstringOnly this product area, up to 40 characters. See product below for the values. Any other value returns no rows.
e.g. eligibility
key_idstringOnly calls made by this API key, up to 64 characters.
e.g. key_7qm2x9d4hs3ve6kt8wbn
resource_idstringOnly calls whose resource_ids contain this id, up to 64 characters. Use it to see every call that touched one check or claim.
e.g. elg_skvgqer72n4zf02jz5rb
changes_onlybooleantrue leaves out GET calls, so only calls that could change something remain. Default false.
e.g. true
beforestringThe next_cursor from the previous page, up to 120 characters.
e.g. 2026-09-28T16:39:48.842388+00:00|evt_f911mnkad52wv96ggzty
limitintegerRows to return, 1 to 500. Default 100.
e.g. 2

Request example

null

Response fields

NameTypeDescription
request_id*stringRequest id. The same value as the X-Request-Id header.
data*arrayCalls, newest first.
request_id*stringThe logged call's request id: the X-Request-Id it answered with, and the request_id in its error body.
e.g. evt_zejc8pc58d7xfd2fntvw
received_at*datetimeWhen the call arrived.
e.g. 2026-09-28T16:39:48.843382+00:00
method*stringHTTP method.
one of: GET · POST · PUT · PATCH · DELETE
e.g. POST
route*stringThe route template, not the literal URL, so ids never appear here. For example /v1/eligibility/{eligibility_id}.
e.g. /v1/eligibility
status*integerHTTP status the call answered with.
e.g. 200
latency_ms*integerTime taken in milliseconds.
e.g. 412
source*stringapi_key for a call made with an API key, dashboard for a call made from a signed-in dashboard session.
one of: api_key · dashboard
e.g. api_key
key_idstringThe API key that made the call. Null for dashboard calls.
e.g. key_7qm2x9d4hs3ve6kt8wbn
actor_idstringThe dashboard user who made the call. Null for API key calls.
modestringThe mode the call ran in. A dashboard call that targets an office runs in that office's mode.
one of: test · production
e.g. production
facility_idstringThe office the call named, from the path, the query or the refusal. Null when the call named no office.
e.g. fac_tycrfy0cs0qc7sq95eme
product*stringThe product area, from the route: eligibility, payers, claims, attachments, remittances, webhooks, artifacts, events, or account for everything else.
e.g. eligibility
resource_ids*arrayArray of strings. Ids the call touched: every ..._id path parameter, plus ids some routes add, such as the check a POST /v1/eligibility created or a failed check named in a refusal. Empty when none.
e.g. ["elg_skvgqer72n4zf02jz5rb"]
error_codestringThe error code the call answered with, for example FACILITY_NOT_GRANTED. Null on success.
next_cursorstringPass as before to read the next page. Set only when this page is full, so the next page can be empty. Null when the page is not full.

Responses

200OK
{
  "request_id": "evt_c171bg4fc97bz4xawf4n",
  "data": [
    {
      "request_id": "evt_zejc8pc58d7xfd2fntvw",
      "received_at": "2026-09-28T16:39:48.843382+00:00",
      "method": "GET",
      "route": "/v1/eligibility",
      "status": 403,
      "latency_ms": 3,
      "source": "api_key",
      "key_id": "key_c8m2x9d4hs3ve6kt8wbn",
      "actor_id": null,
      "mode": "production",
      "facility_id": "fac_w9qxypnbcw7b308jbbhh",
      "product": "eligibility",
      "resource_ids": [],
      "error_code": "FACILITY_NOT_GRANTED"
    },
    {
      "request_id": "evt_m1vn1w69c52c7e5wjhf2",
      "received_at": "2026-09-28T16:39:47.836017+00:00",
      "method": "POST",
      "route": "/v1/eligibility",
      "status": 200,
      "latency_ms": 1840,
      "source": "api_key",
      "key_id": "key_7qm2x9d4hs3ve6kt8wbn",
      "actor_id": null,
      "mode": "production",
      "facility_id": "fac_tycrfy0cs0qc7sq95eme",
      "product": "eligibility",
      "resource_ids": [
        "elg_skvgqer72n4zf02jz5rb"
      ],
      "error_code": null
    }
  ],
  "next_cursor": "2026-09-28T16:39:47.836017+00:00|evt_m1vn1w69c52c7e5wjhf2"
}
422Bad cursor
{
  "error": "INVALID_CURSOR",
  "message": "before is not a cursor from this list",
  "errors": [],
  "request_id": "evt_2mk0nadaqn1qh1ryc644",
  "retryable": false,
  "retry_after_seconds": null,
  "next_step": "FIX_REQUEST",
  "doc_url": "https://docs.claimhouse.ai/#error-invalid-cursor",
  "user_message": "Some details in this request need to be corrected before it can be sent."
}

Errors

StatusCodeWhen
401UNAUTHORIZEDKey missing, malformed, unknown or revoked
403PERMISSION_DENIEDKey lacks read
403FACILITY_NOT_GRANTEDA facility_id is not covered by the key's grants, or the key has no office grants
422INVALID_CURSORbefore does not start with a valid timestamp
422INVALID_REQUESToutcome or source is not an allowed value, limit is out of range, or a parameter is too long
429TOO_MANY_REQUESTSMore than 20 in flight or rate bucket empty
InfoOnly calls that passed authentication are logged. A call refused with 401 does not appear.
InfoA key limited to some offices sees only calls that named one of its offices. Calls that named no office, such as GET /v1/me, are not shown to it.
ImportantLogging is best effort: a call is never slowed or failed by the log, so a row can occasionally be missing. Do not use this list as a billing or audit record.
InfoWith a seller wide key, a facility_id that is not one of your offices is not refused. It simply returns no rows.
API reference

ClaimsComing soon

Submit dental claims as 837D or JSON, then track each claim from queued to paid.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Submit an 837D fileComing soon

POSThttps://api.claimhouse.ai/v1/submissions

Send one finished 837D file for one office and receive an intake receipt.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Submit a dental claim as JSONComing soon

POSThttps://api.claimhouse.ai/v1/dental-claims/submission

Send one dental claim as JSON and let Claim House build the 837D.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Submit raw X12 with a compat responseComing soon

POSThttps://api.claimhouse.ai/v1/dental-claims/raw-x12-submission

Send one finished 837D and receive the ClaimSubmissionResponse envelope.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Check an 837D without sending itComing soon

POSThttps://api.claimhouse.ai/v1/dental-claims/x12-validation

Run the supported batch X224A2 byte and structure checks without creating a claim.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Inspect an 837D element by elementComing soon

POSThttps://api.claimhouse.ai/v1/dental-claims/x12-inspection

Check an 837D against the X12 005010X224A2 guide and Claim House rules, with the line, column and a fix for every finding. Nothing is sent.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get a submissionComing soon

GEThttps://api.claimhouse.ai/v1/submissions/{submission_id}

Read one submission's state, dispatch window, transport file record and claim states.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

List claimsComing soon

GEThttps://api.claimhouse.ai/v1/claims

Return one page of your claims, most recently updated first, with optional filters.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get a claimComing soon

GEThttps://api.claimhouse.ai/v1/claims/{claim_id}

Return one claim with its full event ladder and, once an 835 arrives, its payment summary.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Track a claimComing soon

GEThttps://api.claimhouse.ai/v1/claims/{claim_id}/tracking

Return where one claim is as one plain sentence, with the ladder, what happens next and by when, and its artifacts.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Claim draftsComing soon

Hold a claim as a draft, build it to see exactly what intake would decide and the rendered 837D, then send it once.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Create a claim draftComing soon

POSThttps://api.claimhouse.ai/v1/claims/drafts

Store one claim input as a draft without submitting it.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get a claim draftComing soon

GEThttps://api.claimhouse.ai/v1/claims/drafts/{draft_id}

Return one draft with its findings, verdict, and attachment link.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Update a claim draftComing soon

PATCHhttps://api.claimhouse.ai/v1/claims/drafts/{draft_id}

Change an ADA draft's fields, lines, or payer, or any draft's claim id or packet link.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Build a claim draftComing soon

POSThttps://api.claimhouse.ai/v1/claims/drafts/{draft_id}/build

Run the intake checks on a draft and return its findings, verdict, and rendered 837D.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Submit a claim draftComing soon

POSThttps://api.claimhouse.ai/v1/claims/drafts/{draft_id}/submit

Send a built, ready draft through intake once and return the submission receipt.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

List claim draftsComing soon

GEThttps://api.claimhouse.ai/v1/claims/drafts

Page your drafts for the key's mode, newest first.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Delete a claim draftComing soon

DELETEhttps://api.claimhouse.ai/v1/claims/drafts/{draft_id}

Permanently delete a draft that was not consumed by a queued submission.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Read draft historyComing soon

GEThttps://api.claimhouse.ai/v1/claims/drafts/{draft_id}/history

Read the captured version history of one claim draft.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get a claim importComing soon

GEThttps://api.claimhouse.ai/v1/claims/imports/{import_id}

Read one claim import: its state and, for each item, the draft it became or the finding that stopped it.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Import claims as draftsComing soon

POSThttps://api.claimhouse.ai/v1/claims/imports

Upload up to 32 JSON claims in one small file and get one claim draft per valid claim, ready for review. Nothing is submitted.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

AttachmentsComing soon

Upload claim documents, send them once to the payer's attachment door, and get back the attachment number your claim must carry.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

List attachment providersComing soon

GEThttps://api.claimhouse.ai/v1/facilities/{facility_id}/attachment-providers

Returns the office's provider roster for the attachment workspace.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Save an attachment providerComing soon

POSThttps://api.claimhouse.ai/v1/facilities/{facility_id}/attachment-providers

Adds, confirms, changes or retires a provider profile by writing a new version.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Create an attachment draftComing soon

POSThttps://api.claimhouse.ai/v1/attachment-drafts

Starts a workspace draft for one office at version 1 in state DRAFT.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Retrieve an attachment draftComing soon

GEThttps://api.claimhouse.ai/v1/attachment-drafts/{draft_id}

Returns one draft with its context, provider selections, linked packet and review snapshot.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Update an attachment draftComing soon

PATCHhttps://api.claimhouse.ai/v1/attachment-drafts/{draft_id}

Changes a draft's context, provider selections or linked packet.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Create an attachment packetComing soon

POSThttps://api.claimhouse.ai/v1/attachments

Stores one or more files for one office and opens a packet you can send once.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Retrieve an attachment packetComing soon

GEThttps://api.claimhouse.ai/v1/attachments/packets/{packet_id}

Returns a packet's state, door, attachment number, files and send record.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Validate an attachment draftComing soon

POSThttps://api.claimhouse.ai/v1/attachment-drafts/{draft_id}/validate

Checks that a draft is complete and sendable, then freezes a review snapshot and marks it READY.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Send an attachment draftComing soon

POSThttps://api.claimhouse.ai/v1/attachment-drafts/{draft_id}/send

Sends the draft's linked packet to the payer once, using the reviewed snapshot.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Send an attachment packetComing soon

POSThttps://api.claimhouse.ai/v1/attachments/packets/{packet_id}/send

Sends one OPEN packet to the payer through one door, once.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

List attachment draftsComing soon

GEThttps://api.claimhouse.ai/v1/attachment-drafts

Lists attachment drafts for one office without their protected context.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get attachment requirementsComing soon

GEThttps://api.claimhouse.ai/v1/attachment-requirements

What a payer asks you to attach for a set of procedure codes.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get attachment requirements in bulkComing soon

POSThttps://api.claimhouse.ai/v1/attachment-requirements/batch

Requirements for many payer and code groups in one call.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

PaymentsComing soon

Read the 835 remittances payers send for your claims, with each matched payment and its adjustments.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

List remittancesComing soon

GEThttps://api.claimhouse.ai/v1/remittances

Page through the 835 files that contain at least one of your payment lines, newest received first.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Get a remittanceComing soon

GEThttps://api.claimhouse.ai/v1/remittances/{remittance_id}

Read one 835 header and every payment line in it that belongs to you, with claim and line adjustments.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

WebhooksComing soon

Register an HTTPS endpoint to receive signed claim, acknowledgment, payment and eligibility events, then inspect, replay and re-sign deliveries.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Create a webhook endpointComing soon

POSThttps://api.claimhouse.ai/v1/webhook-endpoints

Registers one HTTPS endpoint for a list of event types and returns its signing secret once.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

List webhook endpointsComing soon

GEThttps://api.claimhouse.ai/v1/webhook-endpoints

Lists the webhook endpoints registered for your seller.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

List webhook deliveriesComing soon

GEThttps://api.claimhouse.ai/v1/webhook-endpoints/{endpoint_id}/deliveries

Returns the delivery attempts recorded for one endpoint, newest first.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Replay a webhook deliveryComing soon

POSThttps://api.claimhouse.ai/v1/webhook-endpoints/{endpoint_id}/deliveries/{delivery_id}/replay

Makes the event behind a delivery due again so the worker attempts it on its next pass.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.

API reference

Rotate a webhook signing secretComing soon

POSThttps://api.claimhouse.ai/v1/webhook-endpoints/{endpoint_id}/rotate-secret

Issues a new signing secret and keeps the previous one signing for 24 hours.

Coming soon. This is not available yet: requests to it are refused. The full reference appears here when it is released.