Claim House API
Overview
One API for dental eligibility today, with the same rules as the dashboard. Claims, attachments and payments are coming soon.
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.
| Area | What you do | Available | Start with |
|---|---|---|---|
| Eligibility | Run a real-time eligibility check, or hand over a whole list as a batch, read the answer and download it as a PDF | Live | POST /v1/eligibility |
| Payers | Find the payer id to send on a check, see what each payer supports and whether it is answering | Live | GET /v1/payers/search |
| Offices | List and add the offices you check for, and take an office live | Live | GET /v1/facilities |
| Usage | See every check, whether it was charged and why | Live | GET /v1/usage |
| Claims and claim drafts | Submit and track dental claims | Coming soon | |
| Attachments | Send x-rays, charts and narratives through the electronic attachment network | Coming soon | |
| Payments | Read remittances and what each claim was paid | Coming soon | |
| Events and webhooks | Keep your system in sync without polling | Coming 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-Idheader. Log it and quote it when you contact Claim House. - Every response carries a
Claim-House-Versionheader naming the API version. See Versions and changelog. - Claim House owns every clearinghouse and network credential. You never hold a vendor login.
ch_test_key_EXAMPLE.secret_EXAMPLE with your own key.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 to | Start with | You will finish with |
|---|---|---|
| Run a check without writing code | Dashboard walkthrough below | An answer, its detailed breakdown and a PDF |
| Build an integration | First API check guide | Saved requests, JSON answers and a PDF |
| Understand what the answer means | Read an eligibility answer guide | Clear 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
- Open the dashboard and sign up, or sign in to your existing account. Complete email verification if requested.
- 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.
- 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.
- 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.
2. Try the dashboard in Test
- Select Test in the top bar and choose a test office. Test offices and live offices are separate.
- Open Eligibility, then New check. Use Load a sample when offered. Choose a sample payer and patient; sample people are synthetic.
- Review the office, payer, subscriber and dependent information. Submit one check.
- Open the saved result. Review the snapshot, expand the complete breakdown, and inspect the JSON views available for that check.
- 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
- 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.
- 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.
- Follow First API check. Begin with GET /v1/me to confirm the organization, mode, permissions and reachable offices.
- 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
- 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.
- Review billing in Settings and add the payment method required for live use. Never send card details through an eligibility API request.
- 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.
- 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
- 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.
- 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.
- Save the returned eligibility_id and request_id. Check whether the payer answered before interpreting coverage status.
- Read the full breakdown and payer JSON, then download the PDF. Compare request identity with returned identity when they differ.
- Confirm the check in office history and usage. A usage record is not proof that a payment has settled.
Before your team starts live work
- Confirm the right organization, live office, billing identity and key permissions.
- Complete the test API walkthrough and dashboard walkthrough independently.
- Test an answered check, an inactive test scenario, and a refusal test scenario. Treat these as different outcomes.
- Confirm that your integration saves the original request, response headers, status, request id, check id and idempotency key privately.
- Have an operator procedure for uncertain submissions, access problems and payer refusals. Review the answer limitations in Read an eligibility answer.
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.
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.json4. 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
| Field | What to supply | Required? |
|---|---|---|
| office | The 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 |
| insurance | The 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_id | The policy holder's member ID, as on the card. | Yes |
| patient | The person being seen. | Yes |
| relationship | The 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 |
| subscriber | The 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_number | The policy holder's group number. | No |
| visit_date | The visit date, in any of the three formats. Defaults to today (UTC). | No |
| procedures | Up to ten CDT codes to ask about, in any letter case. | No |
| reference | Your own reference (up to 200 characters), returned in request.reference and kept with the check. | No |
| max_age_seconds | Reuse 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 |
| view | The 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
| Call | Purpose | Sends a new payer inquiry? |
|---|---|---|
| GET /v1/me | Confirm identity, permissions, mode and reachable offices | No |
| GET /v1/facilities | List your offices | No |
| GET /v1/test/samples | Choose a labeled synthetic scenario in Test | No |
| GET /v1/payers/search?q=... | Find the payer when the insurance name is not enough | No |
| POST /v1/eligibility | Check one patient; the response is the answer | Yes in Live; simulated in Test |
| GET /v1/eligibility/{id} | Read the check again: the answer, billing and what you sent | No |
| GET /v1/eligibility/{id}/answer?view=summary | The lines your office's summary selects | No |
| GET /v1/eligibility/{id}/answer | Every line, grouped (view=complete) | No |
| GET /v1/eligibility/{id}/answer?view=lines | Every line once, for spreadsheets | No |
| GET /v1/eligibility/{id}/answer?view=payer | The payer's answer as received | No |
| POST /v1/eligibility/{id}/pdf?kind=complete|streamlined | Make (or reuse) a PDF of the saved answer | No |
| GET /v1/eligibility/{id}/pdf?kind=complete|streamlined | Read a PDF already made, with its link | No |
| GET /v1/settings/eligibility-summary | Read which blocks and codes the summary selects | No |
| GET /v1/facilities/{id}/eligibility | List one office's saved checks | No |
| GET /v1/eligibility?facility_id=... | List checks across your offices | No |
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 ID | Scenario | Expected distinction |
|---|---|---|
| CH-ACTIVE-FULL | Answered, active with sample benefits | status is active |
| CH-TERMINATED | Answered, inactive | status is not_answered; still an answered result |
| CH-NOT-FOUND | Sample payer refusal | HTTP 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.
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.
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 see | What it means | What to do |
|---|---|---|
status active | The payer's answer reports active coverage | Read the lines: amounts, percents, limits, dates, exclusions and notes |
status inactive | The payer's answer reports inactive coverage | Review the plan's coverage dates and the payer's notes |
status unknown | An answer exists, but coverage was absent or unrecognized | Read 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 returned | Read the rejection; do not present it as a coverage decision |
verified: false | The organized answer did not match the payer's answer, so it is withheld | Read the payer's answer as received (links.payer_answer); do not use partial lines |
| Pending or uncertain | Processing is not confirmed complete | Read 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
| Representation | Best for | What to retain |
|---|---|---|
| The answer (view=complete; the check response and the record) | Every line the payer sent, grouped | id, status, verified, counts and every line with its ref |
| Summary (view=summary) | The lines an office usually needs, chosen by its saved settings | counts.shown_lines of counts.complete_lines; open the complete answer for the rest |
| Lines (view=lines) | Spreadsheets and analytics: every line once with its group | group, text, ref |
| Payer (view=payer) | The payer's answer as received | The fields as the payer named them |
| Complete PDF (kind=complete) | Sharing every line on paper | All pages, the Test label and check id |
| Streamlined PDF (kind=streamlined) | Sharing the summary's lines on paper | The "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
- 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.
- A remaining amount is its own line (
period: remaining), beside the plan amount; Claim House never subtracts one from the other or pairs them. - "coinsurance 80%" is the payer's figure. The answer does not say whose share it is, and neither do we.
- An absent field is not zero and not proof that a rule does not apply.
missinglists the sections an office usually expects that the payer did not send;not_readlists fields kept verbatim under a line'sother.
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
| Situation | Next action |
|---|---|
| 401 or invalid key | Check the privately stored secret and whether the key was revoked |
| 403, mode mismatch or office access error | Confirm GET /v1/me, key permissions, office grant and Test/Live binding |
| Billing or readiness hold | Follow the account's Billing and Go live checklist |
| 422 invalid request | Read the named findings and check member ID, date format and dependent relationship; distinguish local validation from a payer refusal |
| Payer refusal | Retain 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 check | Keep the original key and body and inspect the stored check; do not replace the key to bypass the hold |
| Timeout, connection failure or server error | The 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 false | Read the payer's answer as received; do not present partial lines as an eligibility answer |
| 409 PDF_NOT_VERIFIED | Retain the error and check id; the answer itself is not affected |
| Expired PDF link | Read 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.
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"
}
}
}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.
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
| Block | What it holds |
|---|---|
status, checked_at, verified | The coverage status (active, inactive, unknown), when the payer answered, and whether every truth check passed for this answer. |
office, payer | The office, and the payer: name is Claim House's directory name, name_as_returned the payer's own. Neither replaces the other. |
patient, subscriber, dependents | The people exactly as the payer returned them. |
as_requested | What 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. |
plan | Plan fields as sent, coverage (status and each date under its own name: start, end, termination), the active coverage lines and plan notes. |
totals | Deductibles, maximums and out of pocket that name no procedure code. A service type stays on the line as service. |
by_service | Coinsurance, copayment, limitation and other lines grouped by the payer's service type; not_stated when the payer named none. |
by_procedure | Every line that names a CDT code, grouped by code, with that code's history. |
history | Every service date the payer sent, newest first. |
not_covered, notes | Not covered rows; payer notes and disclaimers that belong to no other line. |
rejection, other | The payer's refusal details, and anything else it sent at the top level, verbatim. |
missing, not_read | Sections an office usually expects that the payer did not send; fields kept verbatim under other because they are not organized. |
labels, counts, excluded, links | Plain 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]"
}textis the line in one sentence and holds every value on the line. Show it as it is.refnames the payer section and row (deductible[1]), the same index asview=payer, so every line can be traced to the payer's answer as received.- Money is a decimal string exactly as sent (
"25.00").percentis 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(orlifetime_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
missinglists 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_readlists fields kept verbatim under a line'sotherbecause 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
| View | What it is |
|---|---|
complete | Everything above. The default for the check and the answer route. |
summary | Whole 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. |
lines | Every line once, each with its group (for example by_procedure/D1110), for spreadsheets and analytics. |
payer | The 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"
}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
admincan mint equal or weaker keys withPOST /v1/keysand revoke them withDELETE /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
| Permission | Unlocks |
|---|---|
read | Every read: claims, tracking, submissions, events, remittances, artifacts, offices, payers, eligibility results, drafts, keys, usage, GET /v1/me. |
submit | Claim submissions and drafts, eligibility checks and PDFs, attachment packets, drafts and sends. |
webhooks | Create webhook endpoints, rotate secrets, list and replay deliveries. |
admin | Mint 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
| Scope | Reaches |
|---|---|
seller | Every office in your organization. |
group | Every office in the granted groups, resolved on each request. |
facility | Exactly 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.
scopeIds when you mint a group or facility key. A key minted without them reaches no office.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_kind | Accepts |
|---|---|
sandbox | Test keys |
production | Production 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 asCH-ACTIVE-FULL, with any names, date of birth and payer id, or with an exact sample patient fromGET /v1/test/samples. Test outcomes lists every magic member id, one per outcome, and theX-Test-Scenarioheader. CH-RATE-LIMITanswers429at once, so you can test your backoff.- Test checks are never charged:
billing.reasonistest_mode. - Offices you create with
POST /v1/facilitiesaresandbox. An office goes live withPOST /v1/facilities/{facility_id}/go-liveonce your organization has a card on file.
Limits
| Limit | Value | Over the limit |
|---|---|---|
| Test checks | 500 a day per organization, reset at midnight UTC | 429 TEST_LIMIT_REACHED with Retry-After |
| New test offices | 50 a day per organization | 429 TEST_LIMIT_REACHED with Retry-After |
| Test requests | 10 a second per organization | 429 TEST_LIMIT_REACHED with Retry-After |
Every test request counts toward the daily limit, including refused ones. Limits lists every limit in one place.
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 ID | Outcome | HTTP status | Error or coverage status | Notes |
|---|---|---|---|---|
CH-ACTIVE-FULL | Active, full benefits | 200 | ACTIVE | |
CH-MAX-NEARLY-USED | Maximum nearly used | 200 | ACTIVE | |
CH-FREQUENCY-USED | Frequency used | 200 | ACTIVE | |
CH-WAITING-MAJOR | Waiting period on major | 200 | ACTIVE | |
CH-DEP-AGE-26 | Dependent child, covered to 26 | 200 | ACTIVE | Send the child as the dependent. |
CH-TERMINATED | Coverage ended | 200 | INACTIVE | The payer states coverage is not active; recorded as an answer. |
CH-NOT-FOUND | Member not found (75) | 422 | PAYER_REJECTED | Also CH-AAA-75. |
CH-AAA-42 | Payer down (42) | 502 | VENDOR_ERROR | Down on every try. |
CH-MISSING-TOOTH | Missing tooth clause | 200 | ACTIVE | |
CH-ORTHO-LIFETIME | Orthodontic lifetime maximum | 200 | ACTIVE | |
CH-SECONDARY-COB | Other coverage (COB) | 200 | ACTIVE | |
CH-INACTIVE | Inactive coverage | 200 | INACTIVE | |
CH-AAA-72 | Invalid member ID (72) | 422 | PAYER_REJECTED | |
CH-AAA-73 | Invalid name (73) | 422 | PAYER_REJECTED | |
CH-AAA-71 | Birth date mismatch (71) | 422 | PAYER_REJECTED | |
CH-AAA-79 | Invalid participant (79) | 422 | PAYER_REJECTED | The payer's rejection reason is PAYER_ID_INVALID, next step CHOOSE_PAYER. |
CH-TIMEOUT | Payer timed out | 502 | VENDOR_ERROR | Sent, and no answer came back: the outcome is uncertain. |
CH-DHMO | DHMO copays | 200 | ACTIVE | |
CH-SPARSE | Payer sends little | 200 | ACTIVE | |
CH-MALFORMED | Unreadable payer answer | 502 | VENDOR_ERROR | |
CH-ACTIVE-RICH | Active, rich dental (frequencies and history) | 200 | ACTIVE | |
CH-TERMINATED-LAST-MONTH | Coverage ended last month | 200 | INACTIVE | Coverage ended on the last day of last month. |
CH-NOT-YET-EFFECTIVE | Coverage not yet effective | 200 | INACTIVE | Coverage starts on the first day of next month. |
CH-DEP-OVER-AGE | Dependent over the age limit | 200 | INACTIVE | Send the child as the dependent. Coverage ended at the end of last month. |
CH-SPOUSE | Spouse on the subscriber's plan | 200 | ACTIVE | Send the spouse as the dependent with relationship spouse. |
CH-AAA-51 | Provider not on file (51) | 502 | VENDOR_ERROR | The payer's rejection reason is PROVIDER_NOT_ON_FILE, next step COMPLETE_SETUP. |
CH-AAA-43 | Invalid provider ID (43) | 422 | PAYER_REJECTED | The payer's rejection reason is PROVIDER_ID_INVALID, next step COMPLETE_SETUP. |
CH-AAA-42-ONCE | Payer down (42), first try only | 502 | PAYER_UNAVAILABLE | Down on the first check of this patient; answered on a later new check (a new Idempotency-Key), so batch retries can be tested. |
CH-SLOW | Slow answer (20 seconds) | 200 | ACTIVE | Answered after about 20 seconds. |
CH-VENDOR-ERROR | Network error before the payer | 502 | VENDOR_ERROR | The network failed before reaching the payer. Free. |
CH-NOT-EXTRACTED | Answer with a section the summary does not extract | 200 | ACTIVE | The 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-NETWORK | In network and out of network benefits | 200 | ACTIVE | Deductibles, maximums and coinsurance for in network and out of network. |
CH-PAYER-CHOICE | Payer choice needed | 409 | PAYER_CHOICE_REQUIRED | Refused with candidates unless the payer is one of the five sample payer IDs; send one of them to get an answer. |
CH-RATE-LIMIT | Rate limited (429) | 429 | TOO_MANY_REQUESTS | Nothing is counted or written. |
- Sample payer IDs:
94276Delta Dental,65978MetLife Dental,62308Cigna Dental,64246Guardian,52133UnitedHealthcare Dental. CH-AAA-42-ONCEis down on the first check of a patient and answered on a later new check (a newIdempotency-Key), so a batch'sretry_payer_unavailablecan be tried. Replaying the same key replays the recorded failure.CH-PAYER-CHOICE: send an insurance name as the payer to get409 PAYER_CHOICE_REQUIREDwith candidates; send one of the sample payer IDs to get an answer. In a batch the row isNEEDS_PAYER.CH-SLOWanswers 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).
X-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.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 send | Result |
|---|---|
| Same key, same content | The stored answer with idempotent_replay: true and the Idempotent-Replayed: true response header. No new check, no charge. |
| Same key, different content | 422 IDEMPOTENCY_KEY_REUSED |
| Same key while the first is still running, or an identical check already running | 409 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
- Your HTTP call timed out or returned a plain
500: send the same body with the sameIdempotency-Key. You get the stored answer,409 ELIGIBILITY_OPERATION_PENDING, or a normal first answer if the first request never arrived. - A check returned
502 VENDOR_ERROR,502 PAYER_UNAVAILABLEor422 PAYER_REJECTED: Claim House will not retry it. Run a new check with a new key only when you decide to, after fixing whaterrors[0].rejectionnames. The error'snext_stepsays which:FIX_REQUESTorNEW_CHECK_LATER.
Retry-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.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 have | Send | Notes |
|---|---|---|
| The payer's id or name | tradingPartnerServiceId (or payer_id), or the payer object: id, name, pms_carrier_id, group_number, employer_name | Send 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 name | facilityId (or facility_id): the fac_ id, the office code or the exact office name | A 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 format | YYYYMMDD, YYYY-MM-DD or MM/DD/YYYY in either body shape | A date with slashes is always month first. |
| A relationship word | spouse, 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.method | Meaning |
|---|---|
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 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.
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.
- 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 backREADY,REFUSED(withproblems),NEEDS_PAYERorDUPLICATE. 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. - 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 withPOST /v1/payer-mapping/mappings/{mapping_id}/confirmand preview again. - Run it. Send the same body with
"preview": false(the default) and anIdempotency-Key. You get202and abatch_id. Sending the same key and body again returns the same batch (Idempotent-Replayed: true); it never starts a second one. - Follow progress.
GET /v1/eligibility/batches/{batch_id}returns the state and counts, without rows. Poll it every few seconds whilestateisRUNNING. - Read the results. Page through rows with
GET /v1/eligibility/batches/{batch_id}/rows(500 at a time, up to 1,000), filtered byresult(ACTIVE,INACTIVE,UNKNOWN,NOT_ANSWERED,REFUSED) orstate, or download every row at once withGET /v1/eligibility/batches/{batch_id}/results(format=csvorjsonl). Each row has yourreferenceand, when the check ran, itseligibility_id: openGET /v1/eligibility/{eligibility_id}/answerfor the full answer, or make its PDF. - Stop early if you need to.
POST /v1/eligibility/batches/{batch_id}/cancelcancels 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.
| Field | Accepted headers |
|---|---|
| reference | reference, ref, appointment_id, appt_id, tenant_reference, id |
| office | facility_id, office_id, office, facility, location: the office id, office code or display name |
| payer | payer, payer_id, insurance, insurance_name, carrier, carrier_name, elect_id |
| member ID | member_id, subscriber_id, memberid, insurance_id |
| first name | first_name, subscriber_first_name, fname, subscriber_first |
| last name | last_name, subscriber_last_name, lname, subscriber_last |
| date of birth | date_of_birth, dob, birthdate, birth_date, subscriber_dob |
| group number | group_number, group, group_id |
| relationship | relationship, patient_relationship, relation |
| patient first name | patient_first_name, patient_first |
| patient last name | patient_last_name, patient_last |
| patient date of birth | patient_date_of_birth, patient_dob, patient_birthdate |
| service date | service_date, date_of_service, appointment_date, appt_date |
| procedures | procedures: CDT codes separated by commas, semicolons or spaces |
- Dates:
YYYY-MM-DD,YYYYMMDDorMM/DD/YYYY. - Relationship:
self(the default when blank),spouse,childorother, any case, or the codes18,01,19and34. Anything butselfneeds 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 thepatient_columns.
Each patient is checked once
| You send | Result |
|---|---|
The same batch again with the same Idempotency-Key | The same batch, idempotent_replay: true and the Idempotent-Replayed: true header. Nothing runs twice. |
| The same key with a different body | 422 IDEMPOTENCY_KEY_REUSED |
| Two identical rows in one batch | The later row is DUPLICATE and points at the first; one check runs. |
| The same row again the same day, in any batch | Its 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).
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.
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."
}| Field | Type | Description |
|---|---|---|
error | string | Stable code. |
message | string | A sentence for the developer. |
errors | array | Structured detail. Shape depends on the code. Never echoes a claim or patient value. |
request_id | string | Same value as the X-Request-Id header. |
retryable | boolean | True 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_seconds | integer or null | Seconds to wait when Claim House knows it (the same as the Retry-After header); else null. |
next_step | string | What 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_url | string | This error's row in Error codes and retries: https://docs.claimhouse.ai/#error-<code in lowercase, underscores as dashes>. |
user_message | string | A 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
200even when coverage is inactive: read the coverage status in the answer.
500 with no envelope. Treat it like a timeout: look the resource up, or repeat with the same Idempotency-Key.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_step | What to do | Key |
|---|---|---|
RESEND_SAME_REQUEST | Send the same request again, with the same Idempotency-Key, after retry_after_seconds. | Same key |
FIX_REQUEST | Change the request as the error says, then send it with a new Idempotency-Key. | New key |
NEW_CHECK_LATER | Nothing in the request needs to change. Run a new check later with a new Idempotency-Key. | New key |
CHOOSE_PAYER | Pick one payer from the candidates in errors[0], then send the check with its payer ID. | New key |
CONTACT_SUPPORT | This needs Claim House. Contact support with the request_id. | Do not retry yet |
COMPLETE_SETUP | Finish the account or office setup step the error names, then send the request again. | Do not retry yet |
NONE | No action through the API. Read the message; the result may already be recorded. | Do not retry yet |
| Key | Meaning |
|---|---|
| Same key | Resend the same request with the same Idempotency-Key. |
| New key | Any new attempt is a new request with a new Idempotency-Key. |
| Do not retry yet | Do not retry until the named step is done. |
Eligibility
| Code | Status | Retry? | Key | When | What to do | Front desk sentence |
|---|---|---|---|---|---|---|
ANSWER_NOT_VERIFIED | 409 | No | Do not retry yet | Do 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_MISMATCH | 403, 422 | No | New key | Do 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. |
CAPACITY | 503 | Yes | Same key | Retry 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_REACHED | 429 | Yes | Same key | Wait 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_READY | 409 | No | Do not retry yet | Send 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_DENIED | 400 | No | New key | Do 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_ACTIVE | 409 | No | Do not retry yet | Read 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_FLIGHT | 409 | No | Do not retry yet | Wait, 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_PENDING | 409 | Yes | Same key | Retry 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_FAILURE | 409 | No | New key | Do 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_UNAVAILABLE | 503 | No | New key | Do 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_REQUEST | 422 | No | New key | Do 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_PATIENT | 422 | No | New key | Do 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_AMBIGUOUS | 422 | No | New key | Do 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_REQUIRED | 422 | No | New key | Do 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_REQUIRED | 409 | No | New key | Send 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_ELIGIBILITY | 422 | No | New key | Send 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_REJECTED | 422 | No | New key | Fix 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_UNAVAILABLE | 502 | No | New key | Do 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_MADE | 404 | No | New key | Make 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_VERIFIED | 409 | No | Do not retry yet | Do 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_MIXED | 422 | No | New key | Do 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_DISABLED | 403 | No | Do not retry yet | Do 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_UNKNOWN | 422 | No | New key | Do 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_ERROR | 502 | No | New key | Decide 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
| Code | Status | Retry? | Key | When | What to do | Front desk sentence |
|---|---|---|---|---|---|---|
BATCH_EMPTY | 422 | No | New key | Do 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_FAILED | 500 | No | New key | Do 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_LARGE | 422 | No | New key | Do 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_INVALID | 422 | No | New key | Do 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_LARGE | 413 | No | New key | Do 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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
| Code | Status | Retry? | Key | When | What to do | Front desk sentence |
|---|---|---|---|---|---|---|
PAYER_AMBIGUOUS | 409 | No | New key | Send 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_NETWORK | 422 | No | New key | Send 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_ENROLLED | 409 | No | Do not retry yet | Send 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
| Code | Status | Retry? | Key | When | What to do | Front desk sentence |
|---|---|---|---|---|---|---|
API_VERSION_UNKNOWN | 400 | No | New key | Do 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_INVALID | 400 | No | New key | Do 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_REQUIRED | 400 | No | New key | Add 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_REUSED | 422 | No | New key | Send 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_CURSOR | 400, 422 | No | New key | Do 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_REQUEST | 422 | No | New key | Do 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_FOUND | 404 | No | New key | Do 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_LARGE | 413 | No | New key | Do 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_REFUSED | 400, 405, 406, 415 | No | New key | Do 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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. |
VALIDATION | 422 | No | New key | Do 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
| Code | Status | Retry? | Key | When | What to do | Front desk sentence |
|---|---|---|---|---|---|---|
ENTITLEMENT_REGISTRY_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_GRANTED | 403 | No | New key | Do 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_ENTITLED | 403 | No | Do not retry yet | Send 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. |
FORBIDDEN | 403 | No | New key | Do 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_AVAILABLE | 403 | No | Do not retry yet | Send 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_CONFLICT | 400 | No | New key | Do 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_MISMATCH | 403 | No | New key | Do 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_DENIED | 403 | No | New key | Do 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_REQUIRED | 403 | No | New key | Do 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_EXPIRED | 401 | No | New key | Sign in again, then repeat the request. | The dashboard session token has expired. | Your session ended. Sign in again. |
SESSION_REQUIRED | 403 | No | New key | Do 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_REACHED | 429 | Yes | Same key | Wait 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_ONLY | 403 | No | New key | Do 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_LIMITED | 429 | Yes | Same key | Wait 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_REQUESTS | 429 | Yes | Same key | Retry 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. |
UNAUTHORIZED | 401 | No | New key | Do 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
| Code | Status | Retry? | Key | When | What to do | Front desk sentence |
|---|---|---|---|---|---|---|
KEYS_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_REVOKED | 409 | No | Do not retry yet | No retry is needed. | The key is already revoked. | This key was already revoked. |
KEY_ESCALATION | 403 | No | New key | Do 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
| Code | Status | Retry? | Key | When | What to do | Front desk sentence |
|---|---|---|---|---|---|---|
ACTIVATION_CONFLICT | 409 | No | New key | Read 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_IMMUTABLE | 409 | No | Do not retry yet | Do 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_REQUIRED | 409 | No | New key | Do 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_EXCEEDED | 403 | No | New key | Do 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_EXISTS | 409 | No | New key | Use the existing office. | An office with this identity already exists in the organization. | This office already exists. |
FACILITY_NOT_FOUND | 404 | No | New key | Check 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_REFUSED | 409 | No | Do not retry yet | Send 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_CANDIDATES | 422 | No | New key | Do 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_UNCONFIGURED | 503 | No | Do not retry yet | Do 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_MISMATCH | 403 | No | New key | Do 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_REFUSED | 409 | No | New key | Read 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_CONFLICT | 409 | No | New key | Read 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_REQUIRED | 403 | No | New key | Do 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_TAKEN | 409 | No | New key | Do 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_SANDBOX | 409 | No | Do not retry yet | Send 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_REQUIRED | 403 | No | New key | Do 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_REQUIRED | 403 | No | New key | Do 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_FAILED | 503 | No | Do not retry yet | Do 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_CONFLICT | 409 | No | Do not retry yet | No retry is needed. | An account for this organization already exists. | This organization already has an account. Sign in instead. |
SELF_SERVE_NOT_ALLOWED | 403 | No | New key | Do 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_LIMITED | 429 | Yes | Same key | Retry 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_STATE | 409 | No | New key | Read 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_REQUIRED | 403 | No | New key | Do 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
| Code | Status | Retry? | Key | When | What to do | Front desk sentence |
|---|---|---|---|---|---|---|
BILLING_ACCOUNT_REQUIRED | 409 | No | Do not retry yet | Send 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_REQUIRED | 409 | No | Do not retry yet | Send the request again once the setup step is done. | No card is on file for the organization. | Add a card first. |
BILLING_INTERNAL | 409 | No | Do not retry yet | No retry is needed. | Internal accounts need no card. | This account is never charged and needs no card. |
BILLING_PROCESSOR_MODE_MISMATCH | 409 | No | Do not retry yet | Do 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_REQUIRED | 402 | No | Do not retry yet | Send 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_UNAVAILABLE | 503 | No | Do not retry yet | Do 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_EVENT | 400 | No | Do not retry yet | No retry is needed. | The billing event is not one Claim House accepts. | This request could not be read. |
SIGNATURE_INVALID | 400 | No | Do not retry yet | No 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.
| Code | X12 AAA codes | Kind | Message | Fix | next_step |
|---|---|---|---|---|---|
ACCESS_RESTRICTED | 41 | REJECTED | The payer did not allow this check. | Call the payer to check eligibility, or contact Claim House support. | CONTACT_SUPPORT |
AGE_OR_GENDER_MISMATCH | 69, 70 | FIX_AND_RESEND | The 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_FINISHED | None | PAYER_UNAVAILABLE | This 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_SERVICE | 60 | FIX_AND_RESEND | The subscriber's date of birth is after the service date. | Check the date of birth and the service date. | FIX_REQUEST |
DATE_OF_BIRTH_INVALID | 58 | FIX_AND_RESEND | The 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_MISMATCH | 71 | FIX_AND_RESEND | The 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_FILE | 61 | REJECTED | The 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_REQUIRED | 66, 74 | REJECTED | The 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_DUPLICATE | 68, 76 | FIX_AND_RESEND | The 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_INVALID | 64, 72 | FIX_AND_RESEND | The 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_FOUND | 75 | FIX_AND_RESEND | The 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_INVALID | 65, 73 | FIX_AND_RESEND | The 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_GROUP | 78 | FIX_AND_RESEND | The 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_UNKNOWN | None | PAYER_UNAVAILABLE | The 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_NETWORK | 35 | REJECTED | The 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_FOUND | 67 | FIX_AND_RESEND | The 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_PLAN | 77 | FIX_AND_RESEND | The 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_INVALID | 79 | FIX_AND_RESEND | The payer did not accept the insurance chosen for this check. | Choose the insurance again from the list and check again. | CHOOSE_PAYER |
PAYER_NOT_ANSWERING | 42, 80 | PAYER_UNAVAILABLE | The payer is not answering right now. | Try again in a few minutes; nothing needs to change. | NEW_CHECK_LATER |
PAYER_REJECTED_OTHER | None | REJECTED | The 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_INVALID | 54, 55 | FIX_AND_RESEND | The 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_INVALID | 45, 46, 47, 48, 97 | REJECTED | The 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_INVALID | 43 | FIX_AND_RESEND | The 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_INVALID | 44 | FIX_AND_RESEND | The 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_ALLOWED | 49, 50, 53 | REJECTED | The 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_DATE | 52 | REJECTED | The 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_FILE | 51 | REJECTED | The payer does not have this provider on file. | Confirm the provider's enrollment with this payer, or contact Claim House support. | COMPLETE_SETUP |
REQUEST_INCOMPLETE | 15, 33 | FIX_AND_RESEND | The 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_INVALID | 56, 57 | FIX_AND_RESEND | The payer says the service date is missing or not valid. | Check the service date and check again. | FIX_REQUEST |
SERVICE_DATE_IN_FUTURE | 63 | FIX_AND_RESEND | The 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_RANGE | 62 | FIX_AND_RESEND | The 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.
| Code | Where | Field | Message | next_step |
|---|---|---|---|---|
CODE_INVALID | Batch rows (problems[].code) | None | This code is not valid. | FIX_REQUEST |
DAILY_LIMIT_REACHED | Batch rows (problems[].code) | None | Today's live check limit is reached, so this row was not sent. Send it again tomorrow. | NEW_CHECK_LATER |
DATE_INVALID | Batch rows (problems[].code) | None | Use YYYY-MM-DD, YYYYMMDD or MM/DD/YYYY. | FIX_REQUEST |
DATE_OF_BIRTH_IN_FUTURE | POST /v1/eligibility (errors[0].findings); Batch rows (problems[].code) | date_of_birth | The date of birth is after the service date. | FIX_REQUEST |
FIELD_INVALID | Batch rows (problems[].code) | None | This value is not text. | FIX_REQUEST |
FIELD_REQUIRED | Batch rows (problems[].code) | None | This field is required. | FIX_REQUEST |
FIELD_TOO_LONG | Batch rows (problems[].code) | None | This value is too long. | FIX_REQUEST |
MAX_AGE_CONFLICT | POST /v1/eligibility (errors[0].findings) | None | max_age_seconds in the body and in the query disagree. Send one, or make them agree. | FIX_REQUEST |
MAX_AGE_INVALID | Batch rows (problems[].code) | None | Use a whole number of seconds from 0 to 604800 (7 days). | FIX_REQUEST |
MODE_INVALID | POST /v1/eligibility (errors[0].findings) | None | Use mode standard, enhanced or auto. | FIX_REQUEST |
MODE_MISMATCH | Batch rows (problems[].code) | None | This office does not take checks in this mode. | FIX_REQUEST |
NOT_A_TEST_PATIENT | Batch rows (problems[].code) | None | Test mode checks sample patients and magic member IDs only. | FIX_REQUEST |
OFFICE_AMBIGUOUS | Batch rows (problems[].code) | None | More than one office matches; use the office id or code. | FIX_REQUEST |
OFFICE_NOT_GRANTED | Batch rows (problems[].code) | None | This office is not one you can check for. | FIX_REQUEST |
OFFICE_UNKNOWN | Batch rows (problems[].code) | None | No office you can use has this id, code or name. | FIX_REQUEST |
PATIENT_DATE_OF_BIRTH_REQUIRED | POST /v1/eligibility (errors[0].findings); Batch rows (problems[].code) | patient.date_of_birth | The patient's date of birth is required. | FIX_REQUEST |
PATIENT_IS_SUBSCRIBER | POST /v1/eligibility (errors[0].findings); Batch rows (problems[].code) | patient | The patient is the policy holder; use relationship self and leave the patient out. | FIX_REQUEST |
PATIENT_NAME_REQUIRED | POST /v1/eligibility (errors[0].findings); Batch rows (problems[].code) | patient.first_name | The patient's first and last name are required. | FIX_REQUEST |
PATIENT_NOT_ALLOWED | Batch rows (problems[].code) | None | Leave the patient out when the patient is the policy holder (relationship self). | FIX_REQUEST |
PATIENT_RELATIONSHIP_INVALID | POST /v1/eligibility (errors[0].findings); Batch rows (problems[].code) | relationship | Use spouse, child or other for a patient who is not the policy holder. | FIX_REQUEST |
PATIENT_RELATIONSHIP_REQUIRED | POST /v1/eligibility (errors[0].findings); Batch rows (problems[].code) | relationship | Say how the patient relates to the policy holder. | FIX_REQUEST |
PATIENT_REQUIRED | Batch rows (problems[].code) | None | A spouse, child or other check needs the patient's first name, last name and date of birth. | FIX_REQUEST |
PAYER_INPUT_CONFLICT | POST /v1/eligibility (errors[0].findings) | None | The payer ID and payer.id name two different payers. Send one, or make them agree. | FIX_REQUEST |
PAYER_NOT_SUPPORTED | Batch rows (problems[].code) | None | No supported eligibility payer matches this insurance. | CHOOSE_PAYER |
PAYER_REQUIRED | POST /v1/eligibility (errors[0].findings) | None | Name the payer: send tradingPartnerServiceId, or the payer object. | FIX_REQUEST |
PAYER_TEXT_INVALID | Batch rows (problems[].code) | None | Use up to 80 letters, digits, spaces, dots, dashes or underscores. | FIX_REQUEST |
PROCEDURE_CODE_INVALID | POST /v1/eligibility (errors[0].findings); Batch rows (problems[].code) | procedures | Use CDT procedure codes such as D0120. | FIX_REQUEST |
RELATIONSHIP_INVALID | Batch rows (problems[].code) | None | Use self, spouse, child or other (or 18, 01, 19, 34). | FIX_REQUEST |
SUBSCRIBER_DATE_OF_BIRTH_REQUIRED | POST /v1/eligibility (errors[0].findings); Batch rows (problems[].code) | date_of_birth | The policy holder's date of birth is required. | FIX_REQUEST |
SUBSCRIBER_MEMBER_ID_REQUIRED | POST /v1/eligibility (errors[0].findings); Batch rows (problems[].code) | member_id | The member ID is required. | FIX_REQUEST |
SUBSCRIBER_NAME_REQUIRED | POST /v1/eligibility (errors[0].findings); Batch rows (problems[].code) | first_name | The policy holder's first and last name are required. | FIX_REQUEST |
TOO_MANY_PROCEDURE_CODES | POST /v1/eligibility (errors[0].findings); Batch rows (problems[].code) | procedures | Send at most 10 procedure codes. | FIX_REQUEST |
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.
| Route | Style | Page size (default / max) | Order |
|---|---|---|---|
GET /v1/eligibility | before from the previous page's next; since sets the oldest time | 100 / 500 | Newest first |
GET /v1/eligibility/batches | limit only | 20 / 50 | Newest first |
GET /v1/eligibility/batches/{batch_id}/rows | cursor from next_cursor (same filters) | 500 / 1,000 | Row order |
GET /v1/payers | pageToken, nextPageToken | 50 / 50 | Payer id |
GET /v1/facilities/{facility_id}/eligibility | since and limit, no cursor | 100 / 500 | Newest 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.
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 month | Price 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:
| Reason | Label | What happened |
|---|---|---|
answered | Payer answered | The payer answered this check; checks the payer answers are charged. |
payer_rejected_patient | Payer could not find the member | The payer could not find this member; checks that reach the payer are charged. |
payer_rejected_provider | Payer did not accept the provider | The payer did not accept the provider on this check; checks that reach the payer are charged. |
payer_rejected_request | Payer rejected the request details | The 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.
| Reason | Label | What happened |
|---|---|---|
payer_unavailable | Payer was down | The payer could not answer at the time; not charged. |
request_rejected | Request refused before the payer | The request was refused before it reached the payer; not charged. |
vendor_input_error | Request refused before the payer | The request's details were refused before the payer saw them; not charged. |
transport_failure | Connection failed | The connection to the payer failed before an answer came back; not charged. |
not_sent | Never sent | The check was never sent to the payer; not charged. |
malformed_answer | Our error | The payer's answer could not be read; not charged. |
our_configuration | Our error | A Claim House setup problem stopped this check; not charged. |
cache_hit | Saved answer | A saved answer from a recent identical check was returned; not charged. |
test_mode | Test mode | Test mode checks never reach a payer and are never charged. |
operator_test | Claim House testing | Claim House ran this check to test the service; not charged. |
not_classified | Payer reply not classified | The 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, reasoncache_hit) and same-key replays. - Checks the payer did not answer (
payer_unavailable). - Checks refused before they reached the payer.
Under review
| Reason | Label | What happened |
|---|---|---|
under_review | Under review | The 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) carriesbilling:charged(true,false, ornullwhile under review),state,reason,labelandreason_label. GET /v1/usagecounts each product's units by reason and state (by_reason) and shows the month's tiers;GET /v1/usage/unitslists 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".
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.
| Limit | Value | Scope | Applies to | Over the limit | To raise it |
|---|---|---|---|---|---|
| Write requests per key | 20 a second | Per key | Requests 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 key | 100 a second | Per key | Reads: 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 key | 20 at once | Per key | Every 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 key | 5 failures in 60 seconds | Per key and address | After 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 day | 2,000 a day | Per organization | Live 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 organization | 20 at once | Per organization | Checks 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 organization | 10 a second | Per organization | Requests 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 day | 500 a day | Per organization | Test 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 day | 50 a day | Per organization | Test 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 batch | 10,000 rows | Per request | POST /v1/eligibility/batches, as rows or CSV lines. | 422 BATCH_TOO_LARGE. | Split the list into more batches. |
| Batch CSV size | 8 MB | Per request | The csv text in a batch request, at most 8 MB. | 413 CSV_TOO_LARGE. | Split the file into more batches. |
| Batch request body size | 12 MB | Per request | The 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 page | 1,000 rows | Per request | GET /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 page | 50 batches | Per request | GET /v1/eligibility/batches takes limit 1 to 50 (default 20). | 422 INVALID_REQUEST. | Not raisable. Follow the cursor. |
| Batch rows running at once per organization | 8 at once | Per organization | Rows 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 within | 24 hours | Per request | With 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
429carries aRetry-Afterheader andretry_after_secondsin the body. Wait Retry-After seconds, then resend the same request with the same Idempotency-Key. - A
429or503 CAPACITYis 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_UNAVAILABLEbefore anything is sent or charged. Test mode is not affected. - Contact Claim House support with your organization id and the volume you need.
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
| Version | Default | What it returns |
|---|---|---|
2026-11-01 | Yes | Eligibility 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-01 | No | The 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.
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.txtindexes every page.https://docs.claimhouse.ai/llms-full.txtis every page in one file.- Every page has a Markdown twin at
/docs/<page>.md, for examplehttps://docs.claimhouse.ai/docs/guide-quickstart.mdandhttps://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
claimhousecommand 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.
Command line
Check a patient, a day's schedule or an answer from your terminal with the claimhouse command. Not published yet.
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.
| Flag | Meaning |
|---|---|
--office | Office id, code or name; optional when your key reaches one office |
--insurance | Payer id, practice-system payer id or insurance name |
--member, --first, --last, --dob | The member ID and the patient |
--relationship child|spouse|other | The patient is a dependent; add --sub-first, --sub-last, --sub-dob for the policy holder |
--group, --visit-date, --procedures D1110,D0120, --reference | Optional |
--max-age SECONDS | Reuse an answer at most this old; 0 asks the payer again |
--view summary|complete | What to print (default summary) |
--json | Print 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 code | Meaning |
|---|---|
| 0 | Success |
| 1 | Refused: 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. |
| 2 | Usage: a bad or missing flag, no API key, an address that is not https |
| Variable | Use |
|---|---|
CLAIMHOUSE_KEY | The API key (used before the stored key) |
CLAIMHOUSE_API_BASE | The API address, default https://api.claimhouse.ai; plain http only on this computer |
PAGER | The pager for answer and check --view complete |
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.
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 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.
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.
- 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.
- An ID the network does not list, or no ID, uses the payer your office confirmed for that carrier.
- 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.
- 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.
Eligibility
Check a patient's dental coverage with the eligibility vendor, store the answer, and render it as a PDF.
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_idand returned as 502VENDOR_ERRORwith anerror_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 sameIdempotency-Keyreplays 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_extractednames 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-summarynot_returnedfield is deprecated and empty on new summaries. The readable answer has a separate section-levelnot_returnedlist for expected sections that are absent or empty; it is not proof that related information is absent elsewhere.
| Mode | What happens |
|---|---|
standard (default) | The vendor's standard eligibility answer. |
enhanced | Detailed benefits. Coming soon. Today it is refused with 503 ENHANCED_ELIGIBILITY_UNAVAILABLE before any payer is called and before anything is billed. |
auto | Runs 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_secondssets the window per request, 0 to 604800. Names, member id and group number match case insensitively. - A reused answer returns the original
eligibility_idandretrieved_atwithreused: true,cache.state: "hit"andcache.age_seconds. It makes no payer call, adds no history row and is free. It is recorded with yourIdempotency-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") ormax_age_seconds: 0when you need a new answer.
| You send | Result |
|---|---|
New Idempotency-Key | A saved answer within the reuse window if one matches, else one payer call. |
| Same key, same content | The 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 content | 422 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 running | 409 ELIGIBILITY_OPERATION_PENDING. Nothing new was sent: wait a few seconds and repeat the same request. |
| No key | 400 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.
Check 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. Withinclude=pdfalso stores a PDF artifact. - In the dashboard
- Eligibility > New check
Headers
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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-Key | string | Optional 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-Control | string | Any value containing no-cache skips the cache and makes a live vendor call.e.g. no-cache |
| Content-Type* | string | Must be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.e.g. application/json |
| X-Test-Scenario | string | Test 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-Version | string | Pins 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
| Name | Type | Description |
|---|---|---|
| mode | string | Level 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 |
| include | string | Comma list. pdf renders a PDF of the answer and adds artifact_id and pdf_filename to the response.e.g. pdf |
| 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. 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
| Name | Type | Description |
|---|---|---|
| office | string | The 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* | string | The 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* | string | The policy holder's member ID, as on the card. e.g. CH-ACTIVE-FULL |
| patient* | object | The person being seen. |
| first_name* | string | First name. e.g. Test |
| last_name* | string | Last name. e.g. Patient |
| date_of_birth* | string | YYYY-MM-DD, YYYYMMDD or MM/DD/YYYY.e.g. 19800101 |
| relationship | string | The 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 |
| subscriber | object | The 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* | string | First name. |
| last_name* | string | Last name. |
| date_of_birth* | string | YYYY-MM-DD, YYYYMMDD or MM/DD/YYYY. |
| group_number | string | The policy holder's group number. |
| visit_date | string | The visit date, in any of the three formats. Defaults to today (UTC). |
| procedures | array | Up to ten CDT codes to ask about, in any letter case. e.g. ["D0120","D1110"] |
| reference | string | Your own reference (up to 200 characters), returned in request.reference and kept with the check.e.g. appt-1001 |
| max_age_seconds | integer | Reuse 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 |
| view | string | The 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
| Name | Type | Description |
|---|---|---|
| id* | string | The check id, elg_.... A reused answer keeps the original check's id. |
| contract* | string | Always eligibility.v3.one of: eligibility.v3 |
| view* | string | The view served: complete (the default), summary, lines or payer.one of: complete · summary · lines · payer |
| status* | string | The 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* | string | When the payer answered (ISO 8601). |
| verified* | boolean | True 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_reason | string | Only with verified: false: why the organized answer is withheld. |
| office* | object | The office the check was made for: id and name. |
| payer* | object | id 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. |
| patient | object | The 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. |
| subscriber | object | The policy holder as returned, when the payer returned one apart from the patient. |
| dependents | array | Other people the payer listed. |
| as_requested | object | What 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. |
| plan | object | Plan 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. |
| totals | object | deductibles, 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_service | array | Lines 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_procedure | array | Every 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. |
| history | array | Every service date the payer sent, newest first: code, type as sent, date, ref. A copy sits under each code. |
| not_covered | array | The payer's not covered rows, one line each. |
| notes | array | Payer notes and disclaimers that belong to no other line. |
| rejection | object | The payer's refusal details, when it sent them, with its rows as lines. |
| other | object | Anything else the payer sent at the top level, verbatim. |
| missing | array | Sections an office usually expects that the payer did not send (deductible, maximums, coinsurance, limitations, not_covered, waiting_period). |
| not_read | array | Fields kept verbatim under a line's other because Claim House does not organize them. Nothing is dropped. |
| labels | object | Plain words for the payer tokens in this answer, by kind (network, level, period, service, ...). |
| counts* | object | payer_rows and lines (always equal), procedures, notes, history. A summary carries complete_lines and shown_lines instead. |
| excluded | array | Paths kept out on purpose (our own office identity echoed back, the network's computed summaries, social security numbers); their values are never shown. |
| links* | object | complete, summary, lines, payer_answer and pdf: where each view of this answer is read. |
| billing* | object | Whether 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* | object | What this call did. |
| reference | string | Your reference for this request, when you sent one. |
| idempotency_key* | string | The key the check ran under: yours, or the derived chk_ key. |
| idempotency_key_source* | string | header (yours), derived, or fresh (derived and made unique because you asked the payer again).one of: header · derived · fresh |
| replayed* | boolean | True when this replays the recorded result of the same request. |
| reused* | boolean | True when a saved answer was reused (free); id and checked_at are then the original check's. |
| view | string | The view you asked for, when you sent one. |
| corrections | array | Every normalization applied to the request (field, from, to); absent when none. A person's value is never repeated: a date names its formats. |
| payer_resolution | object | How the payer was matched: input, matched_payer_id, matched_name, method (EXACT, ALIAS, CONFIRMED, LEARNED), confidence. |
| idempotent_replay* | boolean | The same as request.replayed (the Idempotent-Replayed: true header says it too). |
| object | With include=pdf only: status ready with artifact_id and filename, or unavailable with error. The check stands either way. |
Responses
{
"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
}{
"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"
}
}
}{
"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
}{
"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
}{
"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"
}
]
}{
"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."
}{
"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."
}{
"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."
}{
"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."
}{
"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."
}{
"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."
}{
"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."
}{
"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."
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 400 | API_VERSION_UNKNOWN | Claim-House-Version names a version this API does not serve |
| 400 | IDEMPOTENCY_KEY_REQUIRED | A camelCase or snake_case body without the Idempotency-Key header (the flat request may leave it out) |
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 402 | BILLING_REQUIRED | Live mode: no card on file and not an internal account (errors[0].action_url is /settings/billing) |
| 403 | BILLING_IDENTITY_MISMATCH | provider.npi differs from the office billing NPI |
| 403 | FACILITY_NOT_GRANTED | No office you can use matches the id, code or name, or it is not granted (never 404) |
| 403 | MODE_MISMATCH | A test key at a live office, or a live key at a test office |
| 403 | ORG_SUSPENDED | Live mode: your organization or its account is suspended |
| 403 | PERMISSION_DENIED | Key lacks the route's permission |
| 409 | CAPABILITY_NOT_READY | Live mode: the office is not enabled for eligibility yet; errors[0].state names its state |
| 409 | ELIGIBILITY_OPERATION_PENDING | The same check is still running; nothing new was sent |
| 409 | OFFICE_NOT_LIVE | Live mode: the office is not live yet (take it live with POST /v1/facilities/{facility_id}/go-live) |
| 409 | PAYER_CHOICE_REQUIRED | The insurance sent matches more than one payer; pick one of the candidates and send its id |
| 422 | IDEMPOTENCY_KEY_REUSED | Key used before with different content |
| 422 | INVALID_ELIGIBILITY_REQUEST | Request rule findings in errors[0].findings, for example a missing dependent relationship, PAYER_INPUT_CONFLICT or MAX_AGE_CONFLICT |
| 422 | INVALID_REQUEST | Path, query or body fails the schema, including no payer at all (missing at tradingPartnerServiceId or payer_id) |
| 422 | NOT_A_TEST_PATIENT | Test mode: the request names no sample patient |
| 422 | OFFICE_AMBIGUOUS | The office code or name matches more than one office you can use; errors[0].candidates lists facility_id, name and code |
| 422 | OFFICE_REQUIRED | A 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 |
| 422 | PAYER_NOT_SUPPORTED_FOR_ELIGIBILITY | No supported eligibility payer matches the payer you sent |
| 422 | PAYER_REJECTED | The 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 |
| 422 | REQUEST_SHAPES_MIXED | A body that mixes flat fields with another shape's person fields; errors[0].flat_fields and other_fields name them |
| 422 | TEST_SCENARIO_UNKNOWN | Test mode: X-Test-Scenario names no test scenario |
| 429 | DAILY_LIMIT_REACHED | Live: 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 |
| 429 | TEST_LIMIT_REACHED | Test mode: today's limit is used up (Retry-After until midnight UTC) |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 502 | PAYER_UNAVAILABLE | The payer is not answering right now. Nothing needs to change; check again later with a new key |
| 502 | VENDOR_ERROR | Vendor did not answer usefully, or its answer could not be read |
| 503 | CAPACITY | No payer slot freed within 2 seconds; nothing was sent or charged (Retry-After) |
| 503 | ELIGIBILITY_UNAVAILABLE | Eligibility is not configured on this gateway |
| 503 | ENHANCED_ELIGIBILITY_UNAVAILABLE | You 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. |
| 503 | LIVE_LIMIT_UNAVAILABLE | Live admission quota cannot be verified; no new inquiry is started. |
VENDOR_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}.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.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.409 ELIGIBILITY_OPERATION_PENDING and nothing new is sent. Wait a few seconds, then repeat the same request.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.GET /v1/test/samples) at a sandbox office, answered by the test mode simulator and never charged (billing.reason test_mode).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.Idempotent-Replayed: true when the response replays a recorded result for this Idempotency-Key, and Claim-House-Version on every response.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.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.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).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.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.Check many patients
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/resolvedoes. 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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-Key | string | Required 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* | string | Must be application/json.e.g. application/json |
Request body
| Name | Type | Description |
|---|---|---|
| patients | array | 1 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. |
| office | string | Applies to every item, row or CSV line that leaves its own out: the office id, code or name. |
| visit_date | string | Applies to every item that leaves its own out, in any of the three date formats. |
| preview | boolean | true to validate and resolve only (free, nothing stored). Default false.e.g. true |
| reference | string | Your name for the batch, at most 200 characters. e.g. week-of-0928 |
| rows | array | 1 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. |
| reference | string | Your id for the row, at most 200 characters. Strongly recommended: it comes back on every result. e.g. appt-1001 |
| facility_id* | string | The 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* | string | A 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* | string | The policy holder's member ID, at most 80 characters. e.g. SYN000123456 |
| first_name* | string | The policy holder's first name, at most 35 characters. e.g. Sample |
| last_name* | string | The policy holder's last name, at most 60 characters. e.g. Subscriber |
| date_of_birth* | string | The policy holder's date of birth as YYYY-MM-DD, YYYYMMDD or MM/DD/YYYY.e.g. 1980-01-31 |
| group_number | string | Group number, at most 50 characters. |
| relationship | string | The 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 |
| patient | object | {first_name, last_name, date_of_birth}. Required when relationship is not self; leave it out when it is. |
| service_date | string | The date of service. Today (UTC) when blank. e.g. 2026-10-05 |
| csv | string | CSV 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_unavailable | object | Optional. 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* | integer | 1 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. The same value as the X-Request-Id header. |
| preview | boolean | Preview only: true. |
| counts* | object | Preview: 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_limit | object | Preview, live mode only: limit, used_today (live checks admitted today, UTC; reused answers do not count) and remaining. Null in test mode. |
| ignored_columns | array | Preview only: the columns or keys no field accepts. |
| rows | array | Preview 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_choices | array | Preview 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_id | string | Run only: the batch, bat_ plus 20 characters.e.g. bat_qtncqy7e316j97d2ft0x |
| state | string | Run only: RUNNING while any row waits or runs, else COMPLETE.one of: RUNNING · COMPLETE |
| idempotent_replay | boolean | Run only: true when this Idempotency-Key already made this batch. |
Responses
{
"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
}
}{
"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."
}{
"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."
}{
"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."
}{
"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": []
}{
"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
| Status | Code | When |
|---|---|---|
| 400 | IDEMPOTENCY_KEY_REQUIRED | preview is false and the Idempotency-Key header is missing or blank |
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | FEATURE_NOT_ENTITLED | Your organization is not enrolled for eligibility |
| 403 | PERMISSION_DENIED | Key lacks submit |
| 413 | CSV_TOO_LARGE | The CSV is over 8 MB |
| 413 | PAYLOAD_TOO_LARGE | The request body is over 12 MB |
| 422 | BATCH_TOO_LARGE | More than 10,000 rows |
| 422 | BATCH_EMPTY | No rows (a CSV with only a header) |
| 422 | CSV_INVALID | The CSV could not be read (unbalanced quotes) |
| 422 | INVALID_REQUEST | Neither 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 |
| 422 | IDEMPOTENCY_KEY_REUSED | The key made a different batch |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 503 | ELIGIBILITY_BATCHES_UNAVAILABLE | Batches are not configured on this gateway |
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.DUPLICATE with duplicate_of pointing at the first, and only the first runs.DONE with the same http_status and error the single check returns, and the rest of the batch keeps running.UNAUTHORIZED. A batch started from a dashboard session runs for 24 hours; rows still waiting after that finish as 401 SESSION_EXPIRED.List 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| limit | integer | Batches to return, 1 to 50. Default 20. e.g. 20 |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. The same value as the X-Request-Id header. |
| batches* | array | Batches, newest first. |
| batch_id* | string | The batch. e.g. bat_qtncqy7e316j97d2ft0x |
| reference | string | Your name for the batch. |
| state* | string | RUNNING while any row is PENDING or RUNNING; then CANCELLED for a cancelled batch, else COMPLETE.one of: RUNNING · COMPLETE · CANCELLED |
| created_at* | datetime | When the batch was made. |
| completed_at | datetime | When the last row finished. Null while running. |
| cancelled_at | datetime | When the batch was cancelled. Null unless cancelled. |
| retry_payer_unavailable | object | The payer-down opt-in the batch was made with, {"hours": n}, or null. |
| counts* | object | 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). |
Responses
{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | FEATURE_NOT_ENTITLED | Your organization is not enrolled for eligibility |
| 403 | PERMISSION_DENIED | Key lacks read |
| 422 | INVALID_REQUEST | limit outside 1 to 50 |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 503 | ELIGIBILITY_BATCHES_UNAVAILABLE | Batches are not configured on this gateway |
Read a batch
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| batch_id* | string | The batch_id from POST /v1/eligibility/batches.e.g. bat_qtncqy7e316j97d2ft0x |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. The same value as the X-Request-Id header. |
| batch_id* | string | The batch. e.g. bat_qtncqy7e316j97d2ft0x |
| reference | string | Your name for the batch. Null when not sent. e.g. week-of-0928 |
| mode* | string | The mode the batch runs in. one of: test · production e.g. test |
| state* | string | RUNNING 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* | datetime | When the batch was made. |
| completed_at | datetime | When the last row finished. Null while running. |
| cancelled_at | datetime | When the batch was cancelled. Null unless cancelled. |
| retry_payer_unavailable | object | The payer-down opt-in the batch was made with, {"hours": n}, or null. |
| counts* | object | 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). |
Responses
{
"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"
}{
"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"
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | FEATURE_NOT_ENTITLED | Your organization is not enrolled for eligibility |
| 403 | PERMISSION_DENIED | Key lacks read |
| 404 | NOT_FOUND | No such batch in your organization and key mode, or the batch names an office your credential cannot use |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 503 | ELIGIBILITY_BATCHES_UNAVAILABLE | Batches are not configured on this gateway |
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.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.List a batch's 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| batch_id* | string | The batch_id from POST /v1/eligibility/batches.e.g. bat_EXAMPLE0000000000001 |
Query parameters
| Name | Type | Description |
|---|---|---|
| state | string | Only rows in this state. one of: PENDING · RUNNING · DONE · REFUSED · NEEDS_PAYER · DUPLICATE · CANCELLED |
| result | string | Only rows with this result. one of: ACTIVE · INACTIVE · UNKNOWN · NOT_ANSWERED · REFUSED |
| limit | integer | Rows per page, 1 to 1,000. Default 500. e.g. 500 |
| cursor | string | The next_cursor from the previous page, with the same filters. Opaque. |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. The same value as the X-Request-Id header. |
| batch_id* | string | The batch. |
| rows* | array | This page's rows, in row order. |
| index* | integer | The row's position, starting at 0 (a CSV header row is not counted). |
| reference | string | Your reference for the row, as sent. Null when not sent. |
| facility_id | string | The office the row resolved to. Null when it did not resolve. |
| state* | string | Where 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_status | integer | The status POST /v1/eligibility returned for this row's last check. |
| eligibility_id | string | The check, when one was recorded (answers and recorded payer failures). Open it with GET /v1/eligibility/{eligibility_id}. |
| status | string | Coverage status of an answered check. Null otherwise. one of: ACTIVE · INACTIVE · UNKNOWN |
| error | string | For 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. |
| message | string | The plain message that came with error. |
| idempotent_replay | boolean | true when the row replayed an answer the same check already had (the same row sent earlier the same day). |
| billing | object | Whether this check is charged and why, the same object POST /v1/eligibility returns. |
| rejection | object | For a payer rejection: kind, and the first reason's code and field. Codes only. |
| problems | array | For a REFUSED row: {field, code, message} for each problem found before any check ran. |
| payer | object | How 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_of | integer | For a DUPLICATE row: the index of the earlier row that is the same check. |
| attempts* | integer | Checks this row has made: 0 before its first, 1 after it, up to 4 with retry_payer_unavailable. |
| next_try_at | datetime | When a payer-down row is checked again. Null otherwise. |
| next_cursor | string | Pass as cursor for the next page. Null at the end. |
| links | object | API 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
{
"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"
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | FEATURE_NOT_ENTITLED | Your organization is not enrolled for eligibility |
| 403 | PERMISSION_DENIED | Key lacks read |
| 404 | NOT_FOUND | No such batch in your organization and key mode, or the batch names an office your credential cannot use |
| 422 | INVALID_CURSOR | The cursor was changed, belongs to another batch, or is sent with other filters |
| 422 | INVALID_REQUEST | state or result is not an allowed value, or limit is outside 1 to 1,000 |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 503 | ELIGIBILITY_BATCHES_UNAVAILABLE | Batches are not configured on this gateway |
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.Download a batch's 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| batch_id* | string | The batch_id from POST /v1/eligibility/batches.e.g. bat_EXAMPLE0000000000001 |
Query parameters
| Name | Type | Description |
|---|---|---|
| format | string | File format. Default csv.one of: csv · jsonl |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| index* | integer | The row's position, starting at 0. |
| reference | string | Your reference for the row. |
| office_code | string | The office's code. |
| facility_id | string | The office the row resolved to. |
| state* | string | The row's state. one of: PENDING · RUNNING · DONE · REFUSED · NEEDS_PAYER · DUPLICATE · CANCELLED |
| result | string | The row's result word; empty for waiting, running, duplicate and cancelled rows. one of: ACTIVE · INACTIVE · UNKNOWN · NOT_ANSWERED · REFUSED |
| eligibility_id | string | The check, when one was recorded. |
| http_status | integer | The status of the row's last check. |
| error | string | The error code of the row's last check, when it failed. |
| message | string | The plain message that came with error. |
| rejection_code | string | For a payer rejection or payer down: the first reason's code. |
| rejection_field | string | For a payer rejection: the request field the reason names. |
| charged | boolean | Whether the check is charged. |
| billing_reason | string | Why, as the stable billing.reason code. |
Responses
"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"
"{\"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""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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | FEATURE_NOT_ENTITLED | Your organization is not enrolled for eligibility |
| 403 | PERMISSION_DENIED | Key lacks read |
| 404 | NOT_FOUND | No such batch in your organization and key mode, or the batch names an office your credential cannot use |
| 422 | INVALID_REQUEST | format is not csv or jsonl |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 503 | ELIGIBILITY_BATCHES_UNAVAILABLE | Batches are not configured on this gateway |
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.Cancel a batch
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-Keyaccepted, 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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-Key | string | Accepted and optional: cancel is idempotent by itself. |
Path parameters
| Name | Type | Description |
|---|---|---|
| batch_id* | string | The batch_id from POST /v1/eligibility/batches.e.g. bat_EXAMPLE0000000000001 |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. The same value as the X-Request-Id header. |
| batch_id* | string | The batch. |
| reference | string | Your name for the batch. |
| state* | string | RUNNING while any row is PENDING or RUNNING; then CANCELLED for a cancelled batch, else COMPLETE.one of: RUNNING · COMPLETE · CANCELLED |
| created_at* | datetime | When the batch was made. |
| completed_at | datetime | When the last row finished. Null while running. |
| cancelled_at | datetime | When the batch was cancelled. Null unless cancelled. |
| retry_payer_unavailable | object | The payer-down opt-in the batch was made with, {"hours": n}, or null. |
| counts* | object | 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). |
| mode* | string | The mode the batch runs in. one of: test · production |
| cancelled_rows* | integer | How many rows this call cancelled. |
Responses
{
"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
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | FEATURE_NOT_ENTITLED | Your organization is not enrolled for eligibility |
| 403 | PERMISSION_DENIED | Key lacks submit |
| 404 | NOT_FOUND | No such batch in your organization and key mode, or the batch names an office your credential cannot use |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 503 | ELIGIBILITY_BATCHES_UNAVAILABLE | Batches are not configured on this gateway |
Get an eligibility answer
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| eligibility_id* | string | The check id, elg_..., 1 to 64 characters.e.g. elg_hp130jp45188vw4wk5tz |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| id* | string | The check id, elg_.... A reused answer keeps the original check's id. |
| contract* | string | Always eligibility.v3.one of: eligibility.v3 |
| view* | string | The view served: complete (the default), summary, lines or payer.one of: complete · summary · lines · payer |
| status* | string | The 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* | string | When the payer answered (ISO 8601). |
| verified* | boolean | True 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_reason | string | Only with verified: false: why the organized answer is withheld. |
| office* | object | The office the check was made for: id and name. |
| payer* | object | id 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. |
| patient | object | The 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. |
| subscriber | object | The policy holder as returned, when the payer returned one apart from the patient. |
| dependents | array | Other people the payer listed. |
| as_requested | object | What 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. |
| plan | object | Plan 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. |
| totals | object | deductibles, 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_service | array | Lines 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_procedure | array | Every 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. |
| history | array | Every service date the payer sent, newest first: code, type as sent, date, ref. A copy sits under each code. |
| not_covered | array | The payer's not covered rows, one line each. |
| notes | array | Payer notes and disclaimers that belong to no other line. |
| rejection | object | The payer's refusal details, when it sent them, with its rows as lines. |
| other | object | Anything else the payer sent at the top level, verbatim. |
| missing | array | Sections an office usually expects that the payer did not send (deductible, maximums, coinsurance, limitations, not_covered, waiting_period). |
| not_read | array | Fields kept verbatim under a line's other because Claim House does not organize them. Nothing is dropped. |
| labels | object | Plain words for the payer tokens in this answer, by kind (network, level, period, service, ...). |
| counts* | object | payer_rows and lines (always equal), procedures, notes, history. A summary carries complete_lines and shown_lines instead. |
| excluded | array | Paths kept out on purpose (our own office identity echoed back, the network's computed summaries, social security numbers); their values are never shown. |
| links* | object | complete, summary, lines, payer_answer and pdf: where each view of this answer is read. |
| failure | object | Only on a check the payer did not answer: error_class and rejection. |
| billing* | object | Whether the check is charged and why. |
| request | object | What was sent: reference, idempotency_key, group_number, procedures (each only when present). |
Responses
{
"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"
}
}{
"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"
}
}{
"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
}
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks the route's permission |
| 404 | NOT_FOUND | No such check, or outside the key's office grants |
| 422 | INVALID_REQUEST | Path, query or body fails the schema |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
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.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.Read the payer's 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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-Match | string | An 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
| Name | Type | Description |
|---|---|---|
| eligibility_id* | string | The eligibility id returned by POST /v1/eligibility.e.g. elg_EXAMPLE0000000000000001 |
Query parameters
| Name | Type | Description |
|---|---|---|
| view | string | Contract 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 |
| contract | string | v3 (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 |
| fields | string | With 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
| Name | Type | Description |
|---|---|---|
| id* | string | The check id, elg_.... A reused answer keeps the original check's id. |
| contract* | string | Always eligibility.v3.one of: eligibility.v3 |
| view* | string | The view served: complete (the default), summary, lines or payer.one of: complete · summary · lines · payer |
| status* | string | The 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* | string | When the payer answered (ISO 8601). |
| verified* | boolean | True 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_reason | string | Only with verified: false: why the organized answer is withheld. |
| office* | object | The office the check was made for: id and name. |
| payer* | object | id 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. |
| patient | object | The 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. |
| subscriber | object | The policy holder as returned, when the payer returned one apart from the patient. |
| dependents | array | Other people the payer listed. |
| as_requested | object | What 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. |
| plan | object | Plan 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. |
| totals | object | deductibles, 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_service | array | Lines 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_procedure | array | Every 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. |
| history | array | Every service date the payer sent, newest first: code, type as sent, date, ref. A copy sits under each code. |
| not_covered | array | The payer's not covered rows, one line each. |
| notes | array | Payer notes and disclaimers that belong to no other line. |
| rejection | object | The payer's refusal details, when it sent them, with its rows as lines. |
| other | object | Anything else the payer sent at the top level, verbatim. |
| missing | array | Sections an office usually expects that the payer did not send (deductible, maximums, coinsurance, limitations, not_covered, waiting_period). |
| not_read | array | Fields kept verbatim under a line's other because Claim House does not organize them. Nothing is dropped. |
| labels | object | Plain words for the payer tokens in this answer, by kind (network, level, period, service, ...). |
| counts* | object | payer_rows and lines (always equal), procedures, notes, history. A summary carries complete_lines and shown_lines instead. |
| excluded | array | Paths kept out on purpose (our own office identity echoed back, the network's computed summaries, social security numbers); their values are never shown. |
| links* | object | complete, summary, lines, payer_answer and pdf: where each view of this answer is read. |
| summary | object | Summary view: the blocks and procedures shown and the source of each choice (request, office, organization or default). |
| lines | array | Lines view: every line once, each with its group (for example by_procedure/D1110) and its group key. |
| payer_answer | object | Payer view: the payer's answer as received. |
Responses
{
"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"
}
}{
"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"
}
}{
"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"
}
}{
"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]"
}
]
}{
"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": []
}{
"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."
}{
"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."
}{
"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."
}null
{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | missing, invalid or revoked credential |
| 403 | FACILITY_NOT_GRANTED | credential is not granted the check's office |
| 403 | PERMISSION_DENIED | credential lacks eligibility access |
| 404 | NOT_FOUND | no such eligibility result in your organization, grants and key mode |
| 409 | ANSWER_NOT_VERIFIED | the organized answer did not pass its truth checks; errors[0].payer_answer names the payer's answer as received, which still answers |
| 422 | INVALID_ELIGIBILITY_REQUEST | the check did not succeed, so there is no payer answer to read |
| 422 | INVALID_ELIGIBILITY_REQUEST | a fields token is not a summary block or a CDT code (errors[0].field is fields) |
| 422 | INVALID_REQUEST | view or contract is not one listed, or view=full without contract=v2, or fields without view=summary |
| 429 | TOO_MANY_REQUESTS | rate or concurrency limit reached |
| 503 | ELIGIBILITY_UNAVAILABLE | the eligibility rail is not configured on this gateway |
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.ETag of each view names that view (and, for a summary, its selection). Revalidate each view with its own tag.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.Read the summary settings
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| facility_id | string | An office your key reaches. Without it, the organization's setting. e.g. fac_EXAMPLE0000000000001 |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. |
| organization* | object | The organization's saved setting (blocks, procedures, version, updated_at, updated_by), or null when none is saved. |
| facility_id | string | With facility_id: the office. |
| office | object | With facility_id: the office's saved setting, or null. |
| effective* | object | What a summary for this office (or the organization) shows now: blocks, procedures and the source of each (office, organization or default). |
| defaults* | object | The default blocks and procedures. |
| blocks_available* | array | Every block a summary can show. |
Responses
{
"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"
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | FACILITY_NOT_GRANTED | facility_id is not an office your key reaches |
| 403 | PERMISSION_DENIED | Key lacks read |
Save the summary settings
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| facility_id | string | An office your key reaches. Without it, the organization's setting. e.g. fac_EXAMPLE0000000000001 |
Request body
| Name | Type | Description |
|---|---|---|
| blocks* | array | Blocks 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* | array | CDT 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. |
| organization* | object | The organization's saved setting (blocks, procedures, version, updated_at, updated_by), or null when none is saved. |
| facility_id | string | With facility_id: the office. |
| office | object | With facility_id: the office's saved setting, or null. |
| effective* | object | What a summary for this office (or the organization) shows now: blocks, procedures and the source of each (office, organization or default). |
| defaults* | object | The default blocks and procedures. |
| blocks_available* | array | Every block a summary can show. |
| saved* | object | The setting just saved. |
Responses
{
"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"
}
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks admin, or an office-scoped key saving the organization's setting |
| 403 | FACILITY_NOT_GRANTED | facility_id is not an office your key reaches |
| 422 | INVALID_ELIGIBILITY_REQUEST | A block is not in blocks_available or a code is not D and four digits (errors[0].field) |
| 422 | INVALID_REQUEST | An unknown field in the body |
Get the PDF of a check
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| eligibility_id* | string | The check id, elg_..., 1 to 64 characters. The check must have succeeded.e.g. elg_hp130jp45188vw4wk5tz |
Query parameters
| Name | Type | Description |
|---|---|---|
| kind | string | complete (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 |
| contract | string | v3 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Same as the X-Request-Id header. |
| eligibility_id* | string | The check. |
| artifact_id* | string | The stored PDF (art_...). |
| filename* | string | elig_<eligibility_id>-complete.pdf or elig_<eligibility_id>-streamlined.pdf; elig_<eligibility_id>.pdf for the 2026-10-01 PDF. No patient name. |
| bytes* | integer | PDF size in bytes. |
| contract | string | eligibility.v3 on the complete and streamlined PDFs; absent on the 2026-10-01 PDF.one of: eligibility.v3 |
| kind | string | complete or streamlined; absent on the 2026-10-01 PDF.one of: complete · streamlined |
| download_url* | string | Short-lived link to download the PDF. |
| expires_in_seconds* | integer | How long download_url stays valid. |
Responses
{
"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
}{
"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
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks read |
| 403 | FACILITY_NOT_GRANTED | The check belongs to an office your key or session cannot reach |
| 404 | NOT_FOUND | No such check for your organization and mode |
| 404 | PDF_NOT_MADE | No PDF has been made for this check's current answer yet |
| 422 | INVALID_REQUEST | Path or query fails the schema: for example kind is not complete or streamlined, or kind and contract disagree |
| 422 | INVALID_ELIGIBILITY_REQUEST | The check did not succeed, so it has no PDF |
PUT /v1/settings/eligibility-summary; a changed setting makes a new streamlined PDF on the next request.PDF_NOT_VERIFIED and nothing is stored. Lines show procedure codes only, never procedure names.Create an eligibility 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| eligibility_id* | string | The check id, elg_..., 1 to 64 characters. The check must have succeeded.e.g. elg_hp130jp45188vw4wk5tz |
Query parameters
| Name | Type | Description |
|---|---|---|
| kind | string | complete (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 |
| contract | string | v3 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. |
| eligibility_id* | string | The check. |
| artifact_id* | string | The stored PDF, art_.... Pass to GET /v1/artifacts/{artifact_id} for a download link. |
| filename* | string | elig_<eligibility_id>-complete.pdf or elig_<eligibility_id>-streamlined.pdf; elig_<eligibility_id>.pdf for the 2026-10-01 PDF. No patient name. |
| bytes* | integer | PDF size in bytes. |
| contract | string | eligibility.v3 on the complete and streamlined PDFs; absent on the 2026-10-01 PDF.one of: eligibility.v3 |
| kind | string | complete or streamlined; absent on the 2026-10-01 PDF.one of: complete · streamlined |
Responses
{
"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"
}{
"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"
}{
"livemode": false,
"request_id": "evt_rvcyagszp52bh453azw6",
"eligibility_id": "elg_m6ty5a8j8s4156mq1bs7",
"artifact_id": "art_1s3a6da4c52k11793nb8",
"filename": "elig_elg_m6ty5a8j8s4156mq1bs7.pdf",
"bytes": 87759
}{
"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."
}{
"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."
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks the route's permission |
| 403 | FACILITY_NOT_GRANTED | The check's office is not granted to your key |
| 404 | NOT_FOUND | No such check for your account |
| 422 | INVALID_REQUEST | Path or query fails the schema: for example kind is not complete or streamlined, or kind and contract disagree |
| 422 | INVALID_ELIGIBILITY_REQUEST | The check was a vendor failure or has no archived answer |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 503 | ELIGIBILITY_UNAVAILABLE | Eligibility is not configured on this gateway |
ELIGIBILITY_UNAVAILABLE when eligibility is not configured on the gateway, and the deployed configuration was not confirmed when these docs were written.PUT /v1/settings/eligibility-summary; a changed setting makes a new streamlined PDF on the next request.PDF_NOT_VERIFIED and nothing is stored. Lines show procedure codes only, never procedure names.List an office's eligibility checks
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| facility_id* | string | The office, 1 to 64 characters. Must be granted to your key. e.g. fac_q5s09nzww25ysd5a2f3g |
Query parameters
| Name | Type | Description |
|---|---|---|
| since | datetime | Only checks retrieved at or after this ISO 8601 time. e.g. 2026-09-01T00:00:00Z |
| limit | integer | Rows to return, 1 to 500. Default 100. e.g. 2 |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. |
| facility_id* | string | The office. |
| results* | array | Checks, newest first. |
| eligibility_id* | string | The check id, elg_.... |
| facility_id* | string | The office. |
| payer_id* | string | The payer id sent. |
| relationship* | string | Who was checked. one of: self · spouse · child · other |
| service_date* | date | Service date. |
| status* | string | Coverage status. one of: ACTIVE · INACTIVE · UNKNOWN |
| outcome* | string | OK or VENDOR_ERROR.one of: OK · VENDOR_ERROR |
| error_class | string | Vendor error class on failures. Null on success. |
| rejection_summary | string | Only on a failure the payer explained: one plain sentence saying why, from the stored rejection. Null otherwise. |
| vendor* | string | Always claimhouse. Kept so parsers that read it keep working. |
| vendor_transaction_id | string | Vendor transaction id. Null when none was read. |
| vendor_latency_ms* | integer | Vendor latency in milliseconds. |
| tenant_reference | string | Your reference. Null when not sent. |
| retrieved_at* | datetime | When the vendor call was made. |
| 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 | true when charged, false when free, null while the check is under review.e.g. true |
| state* | string | The unit's billable state. one of: BILLABLE · PENDING · NOT_BILLABLE |
| 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.e.g. answered |
| label* | string | A short plain label for the reason. e.g. Payer answered |
| reason_label* | string | One 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_micros | integer | Always null in lists; read the check by id for its price. e.g. null |
Responses
{
"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
}
}
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks the route's permission |
| 403 | FACILITY_NOT_GRANTED | Office not covered by the key's grants |
| 404 | NOT_FOUND | No such office for your account |
| 422 | INVALID_REQUEST | Path, query or body fails the schema |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
mode is not on list rows. Read a single check for it.since. Narrow since to walk older history.Poll an eligibility 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| eligibility_id* | string | The eligibility id returned by POST /v1/eligibility.e.g. elg_EXAMPLE0000000000000001 |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | Unique id for this request. Also returned in the X-Request-Id header.e.g. evt_EXAMPLE0000000000000031 |
| eligibility_id* | string | The eligibility id. e.g. elg_EXAMPLE0000000000000001 |
| facility_id* | string | The office the check ran under. e.g. fac_EXAMPLE0000000000000001 |
| environment* | string | The key mode the operation ran in, test or live.one of: test · live e.g. test |
| state* | string | Operation state. e.g. ANSWERED |
| response_mode* | string | How the answer was delivered. e.g. realtime |
| result_id | string | The retained result id once answered. Null while in flight. e.g. res_EXAMPLE0000000000000001 |
| request_archived* | boolean | The exact outbound request is durably archived. e.g. true |
| response_archived* | boolean | The raw payer response is durably archived. e.g. true |
| object | Latest PDF artifact metadata when one has been generated. e.g. {"artifact_id":"art_EXAMPLE0000000000000001","status":"ready"} |
Responses
{
"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
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | missing, invalid or revoked credential |
| 403 | PERMISSION_DENIED | credential lacks read or the operation's office |
| 404 | NOT_FOUND | no such eligibility operation in your seller, grants and key mode |
| 503 | ELIGIBILITY_UNAVAILABLE | the eligibility rail is not configured on this gateway |
| 429 | TOO_MANY_REQUESTS | rate or concurrency limit reached |
List eligibility checks
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| facility_id | string | Only 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 |
| status | string | ACTIVE, 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 |
| q | string | Search words, up to 120 characters. e.g. testpatient |
| before | string | The next value from the previous page, up to 120 characters.e.g. 2026-09-07T15:00:10+00:00|elg_skvgqer72n4zf02jz5rb |
| limit | integer | Rows to return, 1 to 500. Default 100. e.g. 2 |
| batch_id | string | Only the checks one batch made (bat_...).e.g. bat_EXAMPLE0000000000001 |
| since | string | An 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. The same value as the X-Request-Id header. |
| results* | array | Checks, newest first. |
| eligibility_id* | string | The check id, elg_....e.g. elg_skvgqer72n4zf02jz5rb |
| facility_id* | string | The office. e.g. fac_tycrfy0cs0qc7sq95eme |
| payer_id* | string | The payer id sent. e.g. TESTPAYER1 |
| relationship* | string | Who was checked. one of: self · spouse · child · other e.g. self |
| service_date* | date | Service date. e.g. 2026-09-07 |
| status* | string | Coverage status. one of: ACTIVE · INACTIVE · UNKNOWN e.g. ACTIVE |
| outcome* | string | OK for an answer, VENDOR_ERROR for a recorded failure.one of: OK · VENDOR_ERROR e.g. OK |
| error_class | string | Error class on failures. Null on success. |
| vendor_latency_ms* | integer | Time the payer call took, in milliseconds. e.g. 1840 |
| tenant_reference | string | Your reference. Null when not sent. |
| retrieved_at* | datetime | When the payer call was made. e.g. 2026-09-07T15:00:10+00:00 |
| rejection_summary | string | Only on a failure the payer explained: one plain sentence saying why. Null otherwise. |
| billing | object | Whether this check is charged and why. Null only for a check recorded before usage metering began. |
| charged | boolean | true when charged, false when free, null while the check is under review.e.g. true |
| state* | string | The billable state. one of: BILLABLE · PENDING · NOT_BILLABLE e.g. BILLABLE |
| reason* | string | Why, 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* | string | A short plain label for the reason. e.g. Payer answered |
| reason_label* | string | One 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_micros | integer | Always null in lists. Read the single check for its price. |
| source* | object | Where the answer came from. |
| network* | string | Always claimhouse.e.g. claimhouse |
| reference | string | The network's transaction id. Null when none was read. |
| mode* | string | The mode the check ran in. one of: test · production e.g. production |
| subscriber* | object | The subscriber named on the request. |
| first_name | string | First name as sent. e.g. Jane |
| last_name | string | Last name as sent. e.g. Testpatient |
| date_of_birth | date | Date of birth as sent. e.g. 1980-01-15 |
| member_id | string | Member id as sent. Null when not sent. e.g. SYN000123456 |
| patient | object | The dependent named on the request. Null when relationship is self. |
| first_name | string | First name as sent. e.g. Sam |
| last_name | string | Last name as sent. e.g. Testpatient |
| date_of_birth | date | Date of birth as sent. e.g. 2015-01-01 |
| batch_id | string | The 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. |
| reference | string | Your own id for the row: the same value as tenant_reference. |
| next | string | Pass 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
{
"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
}{
"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
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks read |
| 403 | FEATURE_NOT_ENTITLED | Your account is not enrolled for eligibility |
| 403 | FACILITY_NOT_GRANTED | A facility_id is not covered by the key's grants, or the key has no office grants |
| 422 | INVALID_CURSOR | before does not start with a valid timestamp |
| 422 | INVALID_REQUEST | status is not an allowed value, limit is out of range, since is not an ISO 8601 time, or a parameter is too long |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
facility_id that is not one of your offices is not refused. It simply returns no rows.billing.reason test_mode and is never charged.List test sample patients
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000401 |
| livemode* | boolean | Always false: this route answers in test mode only.e.g. false |
| payers* | array | The sample patients by payer. Today 5 payers with 20 patients each. |
| payer_id* | string | Payer id to send on a test check. e.g. 94276 |
| name* | string | Payer display name. e.g. Delta Dental |
| patients* | array | One entry per sample patient. |
| sample_id* | string | The sample id, smp_<payer id>_<name>. Stable.e.g. smp_94276_full |
| scenario* | string | The eligibility scenario key. e.g. active_full |
| scenario_number* | string | The scenario's number in the test scenario list. e.g. E1 |
| magic_member_id* | string | The magic member id for the same scenario. e.g. CH-ACTIVE-FULL |
| label* | string | A short plain label for the scenario. e.g. Active, full benefits |
| outcome* | string | What a test check for this patient does, in plain words, for example succeeds, payer rejects or retry, free.e.g. succeeds |
| outcome_tone* | string | The outcome as a stable tone. one of: success · inactive · rejected · retry |
| claim_outcome* | string | What the test payer does with a test claim for this patient. one of: paid_full · contractual · frequency_denial · xray_requested · rejected |
| claim_outcome_label* | string | A short plain label for claim_outcome.e.g. Paid in full |
| relationship* | string | self when the patient is the subscriber, else child.one of: self · child |
| subscriber* | object | The synthetic subscriber. |
| first_name* | string | Synthetic first name. e.g. Avery |
| last_name* | string | Synthetic last name. e.g. Molar |
| member_id* | string | Synthetic member id. Send it as the subscriber member id on a test check. e.g. TEST9427601 |
| date_of_birth* | date | Synthetic date of birth. e.g. 1970-01-10 |
| dependent | object | The synthetic dependent patient. Null when the patient is the subscriber. |
| first_name* | string | Synthetic first name. e.g. Mia |
| last_name* | string | Synthetic last name. e.g. Bridge |
| date_of_birth* | date | Synthetic date of birth. e.g. 2014-03-05 |
| scenarios* | array | Every magic member id, one per scenario, plus CH-RATE-LIMIT. Today 34 entries. Test outcomes renders the same table. |
| member_id* | string | The magic member id. Matched without regard to case. e.g. CH-ACTIVE-FULL |
| scenario* | string | The scenario key. e.g. active_full |
| scenario_number* | string | The scenario's number. Empty for CH-RATE-LIMIT.e.g. E1 |
| label* | string | A short plain label. e.g. Active, full benefits |
| outcome* | string | What a test check with this member id does, in plain words. e.g. succeeds |
| http_status* | integer | The HTTP status a check with this member id returns. |
| error | string | The error code it returns. Null for an answer. |
| result | string | The coverage status of an answer. Null for an error. one of: ACTIVE · INACTIVE |
| catalog* | boolean | True when the scenario also has sample patients in payers. |
| aliases* | array | Array of strings. Other magic member ids for the same scenario, for example CH-AAA-75. |
| note* | string | A plain note. Empty when there is none. |
Responses
{
"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."
}
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks read |
| 403 | FEATURE_NOT_ENTITLED | Your account is not enrolled for eligibility |
| 403 | TEST_MODE_ONLY | The key or dashboard session is in live mode |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 429 | TEST_LIMIT_REACHED | Over the test mode limit of requests a second for your organization (10 unless Claim House raised it) |
NOT_A_TEST_PATIENT. Test mode never sends a real patient to a payer.CH-RATE-LIMIT has no sample patient. A test check with it answers 429 at once; retry after the Retry-After seconds.read gets the whole catalog, and 403 FACILITY_NOT_GRANTED is never returned.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.
| Route | Accepts |
|---|---|
GET /v1/payers/{payer_id}/health | Primary id, internal id or alias |
GET /v1/payers/{payer_id}/doors | Primary id only |
POST /v1/eligibility | A 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 drafts | Primary id only |
POST /v1/dental-claims/submission | The claims payer ID only, as sent (never translated through an alias), or payerMapping |
primaryPayerId everywhere unless a route says otherwise. Store payerId as your database key: it never changes.transactionSupportdescribes the payer as the network lists it. Prefertransaction_support: it says what works through Claim House today, per transaction, asSUPPORTED,ENROLLMENT_REQUIRED,NOT_SUPPORTEDorCOMING_SOON(the payer takes it and the Claim House product for it is not released yet).transaction_support.eligibilityisSUPPORTEDexactly when Claim House can route a check to the payer by its id. A payer that isNOT_SUPPORTEDcan still match by insurance name, and the check may answer 409PAYER_CHOICE_REQUIRED.unsolicitedClaimAttachment: SUPPORTEDdoes not guarantee anetwork_Asend works: it also needsnetwork_Ain 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.
DOCUMENTATION_RULE_UNMET.POST /v1/payer-mapping/claims/confirm.Search payers
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| q | string | Search text, 2 to 120 characters. e.g. cigna |
| transaction | string | Keep 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 |
| state | string | Two letters, any case. Keeps payers tied to that state and payers not tied to a region. e.g. FL |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. |
| payers* | array | Matching payer records. Empty when nothing matches (never 404). |
| payerId* | string | Immutable internal id. Use it as your database key. |
| displayName* | string | Name to show. |
| primaryPayerId* | string | The id to show and to send on claims, eligibility and attachments. |
| aliases* | array | Array of strings. Other ids that resolve to this payer. |
| names* | array | Array of strings. Known names. Falls back to [displayName]. |
| transactionSupport* | object | Support level per transaction. |
| eligibilityCheck* | string | Eligibility checks. one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED |
| claimStatus* | string | Claim status. one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED |
| dentalClaimSubmission* | string | Dental claim submission. one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED |
| claimPayment* | string | 835 remittances. Never SUPPORTED unless set explicitly, since an 835 needs ERA enrollment.one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED |
| unsolicitedClaimAttachment* | string | Attachments sent after the claim. one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED |
| coverageTypes* | array | Array of strings. Falls back to ["dental"]. |
| attachmentDoors* | array | Array of strings. The payer's attachment door order, for example ["network_A", "paper"]. Empty when the payer has no routing. |
| eraEnrollmentCode | string | ERA enrollment code. Null when none. |
| paperEobShutoff | boolean | Whether paper EOBs stop after ERA enrollment. Null when unknown. |
| transaction_support* | object | What works through Claim House today, per transaction. Prefer it to transactionSupport. |
| eligibility* | string | SUPPORTED exactly when Claim House can route a check to the payer by its id.one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON |
| claims* | string | Dental claims. COMING_SOON while claims are not released.one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON |
| claim_status* | string | Claim status. one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON |
| remittance* | string | Remittances (835). COMING_SOON while payments are not released.one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON |
| attachments* | string | Attachments. one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON |
| enrollment_required* | object | Per 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* | array | Array of strings. Two-letter codes a regional payer is tied to. Empty means not tied to one region in our data. |
| accepted_searches* | array | Which 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* | string | The combination. one of: MEMBER_ID_NAME_DOB · MEMBER_ID_DOB · NAME_DOB_ONLY · SSN_AS_MEMBER_ID · SSN_WITH_NAME_OR_DOB |
| source* | string | PAYER_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_url | string | The payer's published guide, when public. Null otherwise. |
| note | string | A plain note on the source. |
| stats* | object | The 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_30d | number | 0 to 1, two decimals. Answered includes "member not found". |
| eligibility_median_latency_ms_30d | integer | Median time to an answer, rounded to 100 ms. |
| checks_30d | integer | Checks counted, rounded down to tens. |
| minimum_sample* | integer | 20: below it, every number is null. |
Responses
{
"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
}
}
]
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks read |
| 422 | VALIDATION | None of q, transaction and state was sent, or state is not a US state or territory code |
| 422 | INVALID_REQUEST | q shorter than 2 or longer than 120, or an unknown transaction |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
Get a payer's 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| payer_id* | string | The 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. |
| payer_id* | string | The payer's primary id. |
| display_name* | string | The payer's name. |
| transaction* | string | Always eligibility today.one of: eligibility |
| eligibility* | string | The payer's transaction_support.eligibility.one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON |
| measured* | boolean | False 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* | integer | 20: a window with fewer checks shows no numbers. |
| windows* | object | last_hour and last_day, each with the fields below. |
| checks | integer | Checks counted, rounded down to tens. |
| answered_rate | number | 0 to 1. Answered means the payer gave a definitive answer, including "member not found". |
| payer_unavailable_rate | number | 0 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_ms | integer | Median time of answered checks, rounded to 100 ms. |
| sufficient_sample* | boolean | True when the window has at least minimum_sample checks. |
Responses
{
"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
}
}
}{
"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
}
}
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks read |
| 404 | NOT_FOUND | No payer has this id or alias |
| 409 | PAYER_AMBIGUOUS | The alias belongs to more than one payer; send the primary id |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
read, and always on.List 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| format | string | Response format. Default json.one of: json · csv e.g. json |
| pageToken | string | The nextPageToken from the previous page, at most 200 characters. Ignored for CSV. |
| pageSize | integer | Payers per page, 10 to 50. Default 50. Ignored for CSV. e.g. 10 |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| payers* | array | Payer records for this page. |
| payerId* | string | Immutable internal id. Use it as your database key. |
| displayName* | string | Name to show. |
| primaryPayerId* | string | The id to show and to send on claims, eligibility and attachments. |
| aliases* | array | Array of strings. Other ids that resolve to this payer. |
| names* | array | Array of strings. Known names. Falls back to [displayName]. |
| transactionSupport* | object | Support level per transaction. |
| eligibilityCheck* | string | Eligibility checks. one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED |
| claimStatus* | string | Claim status. one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED |
| dentalClaimSubmission* | string | Dental claim submission. one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED |
| claimPayment* | string | 835 remittances. Never SUPPORTED unless set explicitly, since an 835 needs ERA enrollment.one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED |
| unsolicitedClaimAttachment* | string | Attachments sent after the claim. one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED |
| coverageTypes* | array | Array of strings. Falls back to ["dental"]. |
| attachmentDoors* | array | Array of strings. The payer's attachment door order, for example ["network_A", "paper"]. Empty when the payer has no routing. |
| eraEnrollmentCode | string | ERA enrollment code. Null when none. |
| paperEobShutoff | boolean | Whether paper EOBs stop after ERA enrollment. Null when unknown. |
| transaction_support* | object | What works through Claim House today, per transaction. Prefer it to transactionSupport. |
| eligibility* | string | SUPPORTED exactly when Claim House can route a check to the payer by its id.one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON |
| claims* | string | Dental claims. COMING_SOON while claims are not released.one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON |
| claim_status* | string | Claim status. one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON |
| remittance* | string | Remittances (835). COMING_SOON while payments are not released.one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON |
| attachments* | string | Attachments. one of: SUPPORTED · ENROLLMENT_REQUIRED · NOT_SUPPORTED · COMING_SOON |
| enrollment_required* | object | Per 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* | array | Array of strings. Two-letter codes a regional payer is tied to. Empty means not tied to one region in our data. |
| accepted_searches* | array | Which 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* | string | The combination. one of: MEMBER_ID_NAME_DOB · MEMBER_ID_DOB · NAME_DOB_ONLY · SSN_AS_MEMBER_ID · SSN_WITH_NAME_OR_DOB |
| source* | string | PAYER_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_url | string | The payer's published guide, when public. Null otherwise. |
| note | string | A plain note on the source. |
| stats* | object | The 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_30d | number | 0 to 1, two decimals. Answered includes "member not found". |
| eligibility_median_latency_ms_30d | integer | Median time to an answer, rounded to 100 ms. |
| checks_30d | integer | Checks counted, rounded down to tens. |
| minimum_sample* | integer | 20: below it, every number is null. |
| nextPageToken | string | Token for the next page. Null on the last page. |
Responses
{
"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
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks read |
| 422 | INVALID_REQUEST | pageSize outside 10 to 50, unknown format, or pageToken too long |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
request_id field. The X-Request-Id header is still set.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.Get a payerComing soon
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.
Get a payer's attachment doorsComing soon
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.
Get a payer's attachment profileComing soon
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.
List a payer's attachment plansComing soon
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.
List insurance 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| facility_id | string | Only 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 |
| state | string | Only 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. The same value as the X-Request-Id header. |
| mappings* | array | Mappings, most recently updated first. Empty when there are none. |
| mapping_id* | string | The mapping id: map_ plus 16 lowercase hex characters.e.g. map_4b19b5ec72e122ec |
| scope* | string | Who 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* | string | EXACT: 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 |
| reason | string | Why 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_id | string | The catalog payer id the mapping points to. Null while a choice is needed. |
| payer_name | string | The network's name for network_payer_id. Null when there is no payer or it is no longer in the catalog. |
| usable_for_eligibility* | boolean | True when a check can use this mapping: the state is EXACT, SUGGESTED, CONFIRMED or STALE and a payer is set. |
| needs_confirmation* | boolean | True only in state SUGGESTED: show the payer and ask the user to confirm it once. |
| resolved_by | string | How 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_by | string | user (this API or the dashboard), operator (Claim House) or payer_answer (a check through this mapping found the member). Null until confirmed. |
| confirmed_at | datetime | When it was confirmed. Null until confirmed. |
| candidates* | array | Payers offered for a choice, best first. Empty when there is nothing to choose. Kept after a confirmation. |
| payer_id* | string | A catalog payer id you can confirm. |
| name* | string | The network's name for that payer id. |
| states* | array | Array of strings. Up to 12 two letter state codes the payer is filed under. Often empty. |
| why* | string | Why it was suggested, in plain words, for example similar words or matches the name. |
| probability | number | Present only when the matching model scored this candidate. Rounded to 3 decimals. |
Responses
{
"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": []
}
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks read |
| 404 | NOT_FOUND | facility_id is not an office in your account. The message reads {'code': 'FACILITY_NOT_FOUND'} |
| 422 | INVALID_REQUEST | A parameter is too long |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 503 | REQUEST_REFUSED | Payer matching is not configured on this gateway. The message reads {'code': 'PAYER_MATCHING_UNAVAILABLE'} |
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.facility_id only has to be an office in your account, and 403 FACILITY_NOT_GRANTED is never returned.Confirm an insurance mapping
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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* | string | Must be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.e.g. application/json |
Path parameters
| Name | Type | Description |
|---|---|---|
| mapping_id* | string | The mapping id. e.g. map_4b19b5ec72e122ec |
Request body
| Name | Type | Description |
|---|---|---|
| network_payer_id* | string | The 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. The same value as the X-Request-Id header. |
| mapping* | object | The mapping after the confirmation. |
| mapping_id* | string | The mapping id: map_ plus 16 lowercase hex characters.e.g. map_4b19b5ec72e122ec |
| scope* | string | Who 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* | string | EXACT: 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 |
| reason | string | Why 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_id | string | The catalog payer id the mapping points to. Null while a choice is needed. |
| payer_name | string | The network's name for network_payer_id. Null when there is no payer or it is no longer in the catalog. |
| usable_for_eligibility* | boolean | True when a check can use this mapping: the state is EXACT, SUGGESTED, CONFIRMED or STALE and a payer is set. |
| needs_confirmation* | boolean | True only in state SUGGESTED: show the payer and ask the user to confirm it once. |
| resolved_by | string | How 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_by | string | user (this API or the dashboard), operator (Claim House) or payer_answer (a check through this mapping found the member). Null until confirmed. |
| confirmed_at | datetime | When it was confirmed. Null until confirmed. |
| candidates* | array | Payers offered for a choice, best first. Empty when there is nothing to choose. Kept after a confirmation. |
| payer_id* | string | A catalog payer id you can confirm. |
| name* | string | The network's name for that payer id. |
| states* | array | Array of strings. Up to 12 two letter state codes the payer is filed under. Often empty. |
| why* | string | Why it was suggested, in plain words, for example similar words or matches the name. |
| probability | number | Present only when the matching model scored this candidate. Rounded to 3 decimals. |
Responses
{
"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"
}
]
}
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks submit |
| 404 | NOT_FOUND | No such mapping in your account, including Claim House wide mappings. The message reads {'code': 'MAPPING_NOT_FOUND'} |
| 422 | REQUEST_REFUSED | network_payer_id is not a payer Claim House can check eligibility with. The message reads {'code': 'PAYER_NOT_SUPPORTED_FOR_ELIGIBILITY'} |
| 422 | INVALID_REQUEST | Body fails the schema, for example network_payer_id missing, empty or over 40 characters |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 503 | REQUEST_REFUSED | Payer matching is not configured on this gateway. The message reads {'code': 'PAYER_MATCHING_UNAVAILABLE'} |
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.CONFIRMED mapping with a different payer changes it. Show the current payer before you send.submit.List claims payer mappingsComing soon
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.
Confirm a carrier's claims payerComing soon
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.
Get the payer 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| facility_id* | string | The office, 1 to 64 characters. It must be an office in your account. e.g. fac_tycrfy0cs0qc7sq95eme |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. The same value as the X-Request-Id header. |
| office_state | string | The office's address state. Null when the office has none. e.g. GA |
| your_office* | array | Payers this office already uses. Empty when none. |
| label* | string | The network's name for the payer. e.g. Delta Dental of Ohio |
| payer_id* | string | The catalog payer id. e.g. DELTO |
| popular* | array | Payers Claim House lists as popular. Empty when none are set. |
| label* | string | The network's name for the payer. e.g. Cigna |
| payer_id* | string | The catalog payer id. e.g. 62308 |
| all* | array | Every 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* | string | The entry type. one of: family · payer e.g. family |
| family | string | Families only. The family code, for example delta_dental.e.g. delta_dental |
| label* | string | The family name, or the row label for a single payer. e.g. Delta Dental |
| hint | string | Families only. A plain hint for choosing inside the family. Null for most families. |
| count | integer | Families only. Number of rows in items.e.g. 3 |
| items | array | Families only. The family's rows, office state first, then by label. |
| label* | string | The name to show, as printed on member cards where Claim House has it. e.g. Delta Dental of Georgia |
| payer_id* | string | The catalog payer id this row maps to. Several rows can share one id. e.g. 94276 |
| network_name* | string | The network's own name for that id. e.g. Delta Dental - DDIC |
| states* | array | Array of strings. Two letter state codes the row is filed under. Often empty. e.g. ["GA"] |
| source* | string | network 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 |
| via | string | Present only when label differs from network_name: the network name the row goes through.e.g. Delta Dental - DDIC |
| payer_count* | integer | Distinct catalog payers. e.g. 5 |
| row_count* | integer | Rows across the whole list. One payer can have several rows. e.g. 6 |
Responses
{
"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
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks read |
| 404 | NOT_FOUND | facility_id is not an office in your account. The message reads {'code': 'FACILITY_NOT_FOUND'} |
| 422 | INVALID_REQUEST | facility_id missing, empty or over 64 characters |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 503 | REQUEST_REFUSED | Payer matching is not configured on this gateway. The message reads {'code': 'PAYER_MATCHING_UNAVAILABLE'} |
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.facility_id only has to be an office in your account, and 403 FACILITY_NOT_GRANTED is never returned.GET /v1/payers/resolve to match typed text.Match insurance to a payer
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| facility_id* | string | The office, 1 to 64 characters. It must be an office in your account. e.g. fac_tycrfy0cs0qc7sq95eme |
| insurance | string | The insurance name as typed, up to 200 characters. Required when payer_id is not sent.e.g. Delta Dental of Georgia |
| payer_id | string | A payer id as typed, up to 40 characters. Required when insurance is not sent.e.g. 94276 |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. The same value as the X-Request-Id header. |
| mapping* | object | The stored mapping for this input. |
| mapping_id* | string | The mapping id: map_ plus 16 lowercase hex characters.e.g. map_4b19b5ec72e122ec |
| scope* | string | Who 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* | string | EXACT: 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 |
| reason | string | Why 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_id | string | The catalog payer id the mapping points to. Null while a choice is needed. |
| payer_name | string | The network's name for network_payer_id. Null when there is no payer or it is no longer in the catalog. |
| usable_for_eligibility* | boolean | True when a check can use this mapping: the state is EXACT, SUGGESTED, CONFIRMED or STALE and a payer is set. |
| needs_confirmation* | boolean | True only in state SUGGESTED: show the payer and ask the user to confirm it once. |
| resolved_by | string | How 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_by | string | user (this API or the dashboard), operator (Claim House) or payer_answer (a check through this mapping found the member). Null until confirmed. |
| confirmed_at | datetime | When it was confirmed. Null until confirmed. |
| candidates* | array | Payers offered for a choice, best first. Empty when there is nothing to choose. Kept after a confirmation. |
| payer_id* | string | A catalog payer id you can confirm. |
| name* | string | The network's name for that payer id. |
| states* | array | Array of strings. Up to 12 two letter state codes the payer is filed under. Often empty. |
| why* | string | Why it was suggested, in plain words, for example similar words or matches the name. |
| probability | number | Present only when the matching model scored this candidate. Rounded to 3 decimals. |
Responses
{
"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": []
}
}{
"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"
}
]
}
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks submit |
| 404 | NOT_FOUND | facility_id is not an office in your account. The message reads {'code': 'FACILITY_NOT_FOUND'} |
| 422 | REQUEST_REFUSED | Neither insurance nor payer_id was sent. The message reads {'code': 'INSURANCE_REQUIRED'} |
| 422 | INVALID_REQUEST | facility_id missing or empty, or a parameter too long |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
| 503 | REQUEST_REFUSED | Payer matching is not configured on this gateway. The message reads {'code': 'PAYER_MATCHING_UNAVAILABLE'} |
GET that needs the submit permission, because a new input stores a mapping. A read only key receives 403 PERMISSION_DENIED.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.facility_id only has to be an office in your account, and 403 FACILITY_NOT_GRANTED is never returned.Read payer auto-correctComing soon
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.
Set payer auto-correctComing soon
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.
Import an office's carriersComing soon
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.
Get a carrier importComing soon
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.
Revoke a claims payer confirmationComing soon
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.
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).
| Field | Set by | Rules |
|---|---|---|
facility_id | Gateway | fac_ plus 20 lowercase base32 characters. Opaque. |
billing_npi | You, on create | Ten digits with a valid NPI check digit. Unique together with the TIN inside your seller. Cannot be changed. |
tin / tin_type | You, on create | Nine digits, no dashes. The TIN is never returned by any route; responses carry only tin_type (EI default, or SY). Cannot be changed. |
control_prefix | Gateway (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_kind | Gateway | sandbox 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_timezone | You, once | Form human claim references such as NORTH-20260914-0001. Permanent once saved. |
nea_facility_id | Claim House, when the office is registered for electronic attachments | The office's id on the electronic attachment network. Null until the office is registered for electronic attachments. |
status | Gateway | ACTIVE, 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 inclaim_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 state | Meaning | Claims to this payer |
|---|---|---|
NOT_REQUIRED | The payer needs no enrollment for this transaction. | Accepted |
REQUESTED | Claim House has requested enrollment. | Refused |
PENDING | The payer or clearinghouse is processing it. | Refused |
LIVE | Enrolled. | Accepted |
REJECTED | The payer refused the enrollment. | Refused |
List offices
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id, also sent in the X-Request-Id header.e.g. evt_EXAMPLE0000000000101 |
| facilities* | array | One entry per reachable office. |
| facility_id* | string | The office id. e.g. fac_EXAMPLE0000000000001 |
| name* | string | The office's name, computed on the server: the display name, else the legal name, else the office code. |
| group_id | string | The group the office belongs to. Null when the office is in no group. |
| billing_npi* | string | The office's billing NPI. e.g. 1234567893 |
| tin_type* | string | The TIN type. The TIN itself is never returned. one of: EI · SY |
| taxonomy* | string | Billing taxonomy code. Empty string when not set. e.g. 1223G0001X |
| control_prefix* | string | The three or four character code stamped into this office's X12 control numbers. e.g. AAB |
| claim_office_code | string | Office code used in claim references. Null until set. |
| claim_timezone | string | IANA timezone that decides the claim reference date. Null until set. |
| nea_facility_id | string | The office's id on the electronic attachment network. Null until the office is registered for electronic attachments. |
| binding_kind* | string | Whether the office accepts test or production keys. one of: sandbox · production |
| status* | string | The office's lifecycle status. one of: ACTIVE · SUSPENDED · RETIRED |
| address_line1 | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| address_line2 | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| city | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| contact_email | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| contact_name | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| contact_phone | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| country | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| display_name | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| identity_review_status | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| legal_name | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| partner_office_ref | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| postal_code | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| profile_source | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| profile_version | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| state | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| eligibility_state | string | The 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
{
"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
}
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, unknown or revoked key, or wrong secret |
| 403 | PERMISSION_DENIED | The credential lacks read |
| 403 | FACILITY_NOT_GRANTED | A group or office scope resolves to no office |
| 429 | TOO_MANY_REQUESTS | More than 20 requests in flight or the read bucket is empty |
officeId, the transport armed switch and the created time.display_name, city, state, partner_office_ref, identity_review_status) that this reference does not yet document. Treat them as unstable.Get an officeComing soon
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.
Create an office
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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* | string | Must be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.e.g. application/json |
Request body
| Name | Type | Description |
|---|---|---|
| billingNpi* | string | The office's billing NPI. Ten digits with a valid NPI check digit. e.g. 1234567893 |
| tin* | string | The billing TIN, nine digits with no dashes. Stored for billing identity checks and never returned. e.g. 000000000 |
| tinType | string | The TIN type. Defaults to EI.one of: EI · SY |
| taxonomy | string | Billing taxonomy code, up to 10 characters. Defaults to empty string. The API does not check the pattern. e.g. 1223G0001X |
| groupId | string | A group of your seller to place the office in. Up to 64 characters. There is no route to create or list groups. |
| neaFacilityId | string | An attachment network office id you already hold, up to 64 characters. When it is set, registering this office for electronic attachments answers 409. |
| officeId | string | Your own office reference, up to 64 characters. Stored but never returned. e.g. your-office-17 |
| controlPrefix | string | Import 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. |
| claimOfficeCode | string | Claim office code, matching ^[A-Z][A-Z0-9]{1,7}$. Send together with claimTimezone.e.g. NORTH |
| claimTimezone | string | A 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000102 |
| facility_id* | string | The new office id. e.g. fac_EXAMPLE0000000000001 |
| seller_id* | string | Your seller id. e.g. sel_EXAMPLE0000000000001 |
| group_id | string | The group id. Null when none was sent. |
| billing_npi* | string | The billing NPI. e.g. 1234567893 |
| tin_type* | string | The TIN type. one of: EI · SY |
| control_prefix* | string | The allocated or imported control prefix. e.g. AAB |
| claim_office_code | string | The claim office code. Null when not sent. |
| claim_timezone | string | The claim timezone. Null when not sent. |
| binding_kind* | string | Always sandbox for offices created through the API.one of: sandbox |
| status* | string | Always ACTIVE on create.one of: ACTIVE |
| address_line1* | string | Returned by the current gateway build; not yet described in this reference. |
| address_line2* | string | Returned by the current gateway build; not yet described in this reference. |
| capabilities* | array | Returned by the current gateway build; not yet described in this reference. |
| capability* | string | Returned by the current gateway build; not yet described in this reference. |
| state* | string | Returned by the current gateway build; not yet described in this reference. |
| city* | string | Returned by the current gateway build; not yet described in this reference. |
| contact_email* | string | Returned by the current gateway build; not yet described in this reference. |
| contact_name* | string | Returned by the current gateway build; not yet described in this reference. |
| contact_phone* | string | Returned by the current gateway build; not yet described in this reference. |
| country* | string | Returned by the current gateway build; not yet described in this reference. |
| display_name* | string | Returned by the current gateway build; not yet described in this reference. |
| legal_name | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| partner_office_ref | string | Returned by the current gateway build; not yet described in this reference. Can be null. |
| postal_code* | string | Returned by the current gateway build; not yet described in this reference. |
| profile_source* | string | Returned by the current gateway build; not yet described in this reference. |
| profile_version* | integer | Returned by the current gateway build; not yet described in this reference. |
| state* | string | Returned by the current gateway build; not yet described in this reference. |
Responses
{
"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"
}
]
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, unknown or revoked key, or wrong secret |
| 403 | PERMISSION_DENIED | The credential lacks admin |
| 409 | FACILITY_EXISTS | Same NPI and TIN, or the claim office code, already used in your seller |
| 422 | VALIDATION | NPI check digit fails, or groupId is not a group of your seller |
| 422 | INVALID_REQUEST | Missing field, wrong pattern, unknown field, office code without timezone, unknown timezone |
| 429 | TOO_MANY_REQUESTS | More than 20 requests in flight or the read bucket is empty |
FACILITY_EXISTS.controlPrefix that is malformed (for example AB) or already registered currently returns an unhandled 500 with a plain text body. Nothing is created.taxonomy and neaFacilityId are accepted but not echoed; read them back with List offices.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.Import offices in bulk
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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* | string | Must be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.e.g. application/json |
Request body
| Name | Type | Description |
|---|---|---|
| facilities* | array | Office rows, 1 to 500, processed in order. Each row takes the same fields and constraints as the Create an office body. |
| billingNpi* | string | The office's billing NPI. Ten digits with a valid NPI check digit. e.g. 1234567893 |
| tin* | string | The billing TIN, nine digits with no dashes. Stored for billing identity checks and never returned. e.g. 000000000 |
| tinType | string | The TIN type. Defaults to EI.one of: EI · SY |
| taxonomy | string | Billing taxonomy code, up to 10 characters. Defaults to empty string. The API does not check the pattern. e.g. 1223G0001X |
| groupId | string | A group of your seller to place the office in. Up to 64 characters. There is no route to create or list groups. |
| neaFacilityId | string | An attachment network office id you already hold, up to 64 characters. When it is set, registering this office for electronic attachments answers 409. |
| officeId | string | Your own office reference, up to 64 characters. Stored but never returned. e.g. your-office-17 |
| controlPrefix | string | Import 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. |
| claimOfficeCode | string | Claim office code, matching ^[A-Z][A-Z0-9]{1,7}$. Send together with claimTimezone.e.g. NORTH |
| claimTimezone | string | A 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000103 |
| received* | integer | Number of rows in the request. e.g. 3 |
| created* | integer | Number of rows with status created.e.g. 1 |
| results* | array | One entry per row, in request order. |
| index* | integer | Zero-based row index. e.g. 0 |
| status* | string | The verdict for this row. one of: created · duplicate · invalid |
| facility_id | string | The new office id. Present only when created. |
| control_prefix | string | The allocated or imported control prefix. Present only when created. |
| error | string | Why 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
{
"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"
}
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, unknown or revoked key, or wrong secret |
| 403 | PERMISSION_DENIED | The credential lacks admin |
| 422 | INVALID_REQUEST | Empty or over 500 rows, or any row fails the schema |
| 429 | TOO_MANY_REQUESTS | More than 20 requests in flight or the read bucket is empty |
duplicate.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.controlPrefix is reported per row as invalid with error rejected.Get office 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
readandoffices.read(API keys receive 404) - Idempotency
- none
- Side effects
- Read only. No audit entry and no vendor call.
- In the dashboard
- API only
Headers
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A signed-in dashboard session token as Bearer <session token>. API keys are refused (404).e.g. Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyX0VYQU1QTEUifQ.EXAMPLEsignature |
Path parameters
| Name | Type | Description |
|---|---|---|
| facility_id* | string | The office id (fac_...). Must be covered by the session's office access.e.g. fac_tycrfy0cs0qc7sq95eme |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000104 |
| capabilities* | array | One row per capability for this office. Empty when the office has no capability rows. |
| seller_id* | string | Your seller id. e.g. sel_EXAMPLE0000000000001 |
| facility_id* | string | The office id. e.g. fac_EXAMPLE0000000000001 |
| capability* | string | The service the row describes. one of: attachments · claims · eligibility · remittances |
| state* | string | The office's readiness for this service. New offices start at UNCONFIGURED.one of: UNCONFIGURED · PENDING_VERIFICATION · READY · BLOCKED · SUSPENDED |
| reason_code | string | Why the capability is in its state. Null when not set. |
| evidence_reference | string | Reference to the evidence reviewed for this state. Null when not set. |
| reviewed_by | string | Who last reviewed the capability. Null when never reviewed. |
| reviewed_at | datetime | When the capability was last reviewed. Null when never reviewed. |
| version* | integer | Row version, starting at 1. e.g. 1 |
Responses
{
"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
}
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, unknown or revoked key, or wrong secret |
| 403 | PERMISSION_DENIED | The credential lacks read |
| 404 | NOT_FOUND | Any API key, a session without offices.read, or an office outside the session's access |
| 429 | TOO_MANY_REQUESTS | More than 20 requests in flight or the read bucket is empty |
NOT_FOUND, even for their own offices.UNCONFIGURED until Claim House verifies the service for the office.capabilities array for an unknown id. Offices created before capability tracking also return an empty array.Set claim namingComing soon
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.
List office enrollmentsComing soon
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.
Register an office for electronic attachmentsComing soon
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.
Read an office's plan choiceComing soon
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.
Remember an office's plan choiceComing soon
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.
Forget an office's plan choiceComing soon
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.
Get office 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| facility_id* | string | The 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000511 |
| facility_id* | string | The office. e.g. fac_tycrfy0cs0qc7sq95eme |
| state* | string | sandbox: 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* | array | Array 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_at | datetime | When the review opened, or null. |
| decided_at | datetime | When the office went live or the review was decided, or null. |
| customer_message | string | Claim House's note when a review was declined, or null. |
Responses
{
"livemode": true,
"request_id": "evt_27epgwyqb17z10q384c1",
"facility_id": "fac_tycrfy0cs0qc7sq95eme",
"state": "sandbox",
"reasons": [],
"submitted_at": null,
"decided_at": null,
"customer_message": null
}Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed or unknown credential |
| 403 | PERMISSION_DENIED | The credential lacks read |
| 404 | FACILITY_NOT_FOUND | No such office for your key (another organization's office is also not found) |
Take an office 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A 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
| Name | Type | Description |
|---|---|---|
| facility_id* | string | The 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000511 |
| facility_id* | string | The office. e.g. fac_tycrfy0cs0qc7sq95eme |
| state* | string | sandbox: 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* | array | Array 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_at | datetime | When the review opened, or null. |
| decided_at | datetime | When the office went live or the review was decided, or null. |
| customer_message | string | Claim House's note when a review was declined, or null. |
Responses
{
"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
}{
"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
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed or unknown credential |
| 402 | BILLING_REQUIRED | No card on file and not an internal account |
| 403 | FEATURE_NOT_ENTITLED | Your organization is not enrolled for eligibility |
| 403 | ORG_SUSPENDED | Your account is suspended |
| 403 | PERMISSION_DENIED | The session is not an owner or admin holding offices.manage |
| 403 | SESSION_REQUIRED | Called with an API key |
| 404 | FACILITY_NOT_FOUND | No such office for your key |
| 409 | GO_LIVE_REFUSED | errors[0].reason: FACILITY_INACTIVE, FACILITY_ARMED, IDENTITY_INCOMPLETE (NPI, tax id, address or name missing) or CAPABILITY_BLOCKED |
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.
| Setting | Values | Meaning |
|---|---|---|
| Mode | test, production | A test key submits only to sandbox offices, a production key only to production offices. Reads are not mode filtered. |
Scope seller | Omit scopeIds | Every office of the seller, including offices created later. |
Scope group | Group ids of your seller | Every office currently in those groups, re-evaluated on each request. |
Scope facility | Office ids of your seller | Exactly those offices. |
| Permissions | submit, read, webhooks, admin | Any non-empty subset. GET /v1/me needs read, so a submit-only key cannot call it. |
| Minting caller | May create |
|---|---|
| Any caller | Only permissions it holds |
test mode caller | Only test keys |
seller scope | Any scope |
group scope | group keys for its own groups, or facility keys for offices in its groups. Not seller keys. |
facility scope | Only facility keys for its own offices |
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.List API 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Unique id for this request. Also returned in the X-Request-Id header.e.g. evt_EXAMPLE0000000000000031 |
| keys* | array | Array of key objects, every key of the seller, newest first. |
| key_id* | string | Key id. Safe to log. e.g. key_EXAMPLE0000000000000002 |
| name | string | Label given at creation. Null when empty. e.g. north office submitter |
| mode* | string | Key mode. one of: test · production e.g. test |
| scope_kind* | string | Scope kind. one of: seller · group · facility e.g. facility |
| scope_ids* | array | Array of strings. Granted ids; [<seller id>] for seller keys.e.g. ["fac_EXAMPLE0000000000000001"] |
| permissions* | array | Array of strings. Sorted permissions. e.g. ["read","submit"] |
| created_by | string | Key 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* | datetime | ISO 8601 creation time. e.g. 2026-09-14T15:00:00+00:00 |
| last_used_at | datetime | ISO 8601 time of the last successful authentication. Null if never used. e.g. null |
| revoked_at | datetime | ISO 8601 revocation time. Null while active. e.g. null |
| revoked_by | string | Key id or clerk: id that revoked the key. Null while active.e.g. null |
Responses
{
"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
}
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | missing, invalid or revoked credential |
| 403 | PERMISSION_DENIED | credential lacks read |
| 429 | TOO_MANY_REQUESTS | rate or concurrency limit reached |
Create an API key
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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* | string | Must be application/json.e.g. application/json |
Request body
| Name | Type | Description |
|---|---|---|
| name | string | Label shown in key lists. Up to 120 characters. Defaults to an empty string. e.g. north office submitter |
| mode | string | Key mode. Defaults to test.one of: test · production e.g. test |
| scopeKind | string | Scope kind. Defaults to seller.one of: seller · group · facility e.g. facility |
| scopeIds | array | Array 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* | array | Array 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Unique id for this request. Also returned in the X-Request-Id header.e.g. evt_EXAMPLE0000000000000031 |
| key_id* | string | The new key id. e.g. key_EXAMPLE0000000000000002 |
| name | string | Label. Null when empty. e.g. north office submitter |
| mode* | string | Key mode. one of: test · production e.g. test |
| scope_kind* | string | Scope kind. one of: seller · group · facility e.g. facility |
| scope_ids* | array | Array of strings. Stored grant ids; [<seller id>] when none were sent.e.g. ["fac_EXAMPLE0000000000000001"] |
| permissions* | array | Array of strings. Sorted permissions. e.g. ["read","submit"] |
| secret* | string | The 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* | boolean | Always true.e.g. true |
Responses
{
"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
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | missing, invalid or revoked credential |
| 403 | PERMISSION_DENIED | credential lacks admin |
| 403 | FACILITY_NOT_GRANTED | the caller's own group or office scope resolves to no office |
| 403 | KEY_ESCALATION | requested permissions, mode or scope beyond the caller's own |
| 422 | VALIDATION | scopeIds name offices or groups your seller does not have |
| 422 | INVALID_REQUEST | missing permissions, unknown permission or mode, more than 64 scopeIds, or an unknown field |
| 429 | TOO_MANY_REQUESTS | rate or concurrency limit reached |
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.VALIDATION, not INVALID_REQUEST. The body is strict: unknown fields are refused and strings are trimmed.Revoke an API key
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_atandrevoked_byand 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| key_id* | string | The key_... id, not the full key string. 1 to 64 characters.e.g. key_1n71fpwn02kz0k3m5bbw |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | Unique id for this request. Also returned in the X-Request-Id header.e.g. evt_EXAMPLE0000000000000031 |
| key_id* | string | The revoked key id. e.g. key_EXAMPLE0000000000000002 |
| revoked* | boolean | Always true.e.g. true |
Responses
{
"request_id": "evt_vc1amfhv11434kj9c446",
"key_id": "key_1n71fpwn02kz0k3m5bbw",
"revoked": true
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | missing, invalid or revoked credential, including a caller that revoked its own key earlier |
| 403 | PERMISSION_DENIED | credential lacks admin |
| 404 | NOT_FOUND | no such key in your seller |
| 409 | KEY_ALREADY_REVOKED | the key is already revoked |
| 422 | INVALID_REQUEST | key_id longer than 64 characters |
| 429 | TOO_MANY_REQUESTS | rate or concurrency limit reached |
KEY_ALREADY_REVOKED and changes nothing.Create the starter test key
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.manageaction (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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000403 |
| livemode* | boolean | Always false: this route answers in test mode only.e.g. false |
| created* | boolean | True 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_id | string | Only when created is true. The new key id.e.g. key_EXAMPLE0000000000000003 |
| name | string | Only when created is true. Always Test key (created at signup).e.g. Test key (created at signup) |
| mode | string | Only when created is true. Always test.e.g. test |
| scope_kind | string | Only when created is true. Always seller.e.g. seller |
| scope_ids | array | Only when created is true. Array of strings: your seller id.e.g. ["sel_EXAMPLE0000000000001"] |
| permissions | array | Only when created is true. Array of strings, sorted.e.g. ["read","submit","webhooks"] |
| secret | string | Only 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_once | boolean | Only when created is true. Always true.e.g. true |
Responses
{
"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
}{
"livemode": false,
"request_id": "evt_c0t1zjcdmh63f9789gx6",
"created": false
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, invalid or revoked credential |
| 403 | PERMISSION_DENIED | The credential lacks admin, or the signed-in member lacks the keys.manage action |
| 403 | SESSION_REQUIRED | The credential is an API key, not a dashboard session |
| 403 | TEST_MODE_ONLY | The dashboard session is in live mode |
| 429 | TOO_MANY_REQUESTS | Rate or concurrency limit reached |
| 429 | TEST_LIMIT_REACHED | Over the test mode limit of requests a second for your organization |
| 503 | KEYS_UNAVAILABLE | Key creation is not connected on this gateway |
DELETE /v1/keys/{key_id} and make a new one with POST /v1/keys.created: true.POST /v1/keys.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.
| Meter | Counts | Does not count |
|---|---|---|
claims_submitted | Submission records received, including held and rejected ones, in both test and production modes. A file with 12 claims counts as 1. | Idempotent replays |
eligibility_checks | Stored eligibility results, successful or vendor error. | Answers served from cache |
attachment_packets | Attachment packets created. | |
facilities_active | Offices on the account, regardless of status or period. |
Get 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| from | date | First day of the period, inclusive (YYYY-MM-DD). Defaults to the first day of the month that contains to.e.g. 2026-09-01 |
| to | date | Last day of the period, inclusive (YYYY-MM-DD). Defaults to today in UTC.e.g. 2026-09-30 |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000301 |
| seller_id* | string | Your seller id. e.g. sel_EXAMPLE0000000000001 |
| period* | object | The resolved period. |
| from* | date | The resolved first day. e.g. 2026-09-01 |
| to* | date | The resolved last day. e.g. 2026-09-30 |
| meters* | object | Counts for the period. Every meter is 0 when there is nothing to count. |
| claims_submitted* | integer | Submission 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* | integer | Stored eligibility results created, successful or vendor error. Cache answers are not counted. e.g. 130 |
| attachment_packets* | integer | Attachment packets created. e.g. 9 |
| facilities_active* | integer | Offices on your account regardless of status or period, counted up to 5,000. e.g. 3 |
| by_facility* | array | One entry per office with at least one submission in the period. Offices with none are omitted; order is not guaranteed. |
| facility_id* | string | The office id. e.g. fac_EXAMPLE0000000000001 |
| claims_submitted* | integer | Submissions for that office. The entries sum to meters.claims_submitted.e.g. 30 |
| billing | object | The 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* | string | Always USD.e.g. USD |
| billing_mode* | string | How you are billed. one of: CARD · INVOICE · INTERNAL |
| products* | array | One entry per product. |
| product* | string | The product. e.g. eligibility_check |
| units* | integer | Charged units this month. e.g. 260 |
| pending_units* | integer | Units under review, not charged unless they prove to be payer answers. e.g. 1 |
| free_units* | integer | Units counted but never charged. e.g. 31 |
| amount_micros* | integer | This product's charges so far. e.g. 76500000 |
| by_reason* | array | Every unit of the month by reason and state, charged first, largest first. The counts add up to units + pending_units + free_units. |
| reason* | string | A reason code from the pricing guide. e.g. answered |
| state* | string | Billable state. one of: BILLABLE · PENDING · NOT_BILLABLE |
| units* | integer | Units with this reason and state. e.g. 180 |
| label* | string | A short plain label. e.g. Payer answered |
| tiers* | array | How the charged units fall into the price tiers so far, for example units 251 to 3,500 at $0.15. |
| tier | integer | The tier number. Null on a minimum line. e.g. 2 |
| from_units | integer | The tier's first unit of the month. Null on a minimum line. e.g. 251 |
| to_units | integer | The tier's last unit. Null for the open top tier and on a minimum line. e.g. 3500 |
| units* | integer | Units priced in this tier. e.g. 10 |
| unit_price_micros* | integer | Price per unit, in micros. e.g. 150000 |
| amount_micros* | integer | Units times price, in micros. e.g. 1500000 |
| minimum* | object | The monthly minimum: amount_micros, covered_micros, true_up_micros, starts_on and full_monthly_micros. |
| estimate* | object | subtotal_micros (usage) and total_micros (with the minimum). |
| offices* | array | Per office: facility_id, group_id, units, free_units and amount_micros. |
| groups* | array | Per client group: group_id, offices and amount_micros. |
| statements* | array | Your last 12 statements, newest first. |
| statement_id* | string | The statement id. e.g. stm_EXAMPLE00000000001 |
| period* | date | The month, as its first day. e.g. 2026-09-01 |
| status* | string | DRAFT until the month closes.one of: DRAFT · FINAL |
| total_micros* | integer | The statement total. e.g. 1000000000 |
| billing_mode* | string | How it was billed. e.g. CARD |
| lines* | array | One line per product tier (PRODUCT_TIER) and the minimum top-up (MINIMUM), each with its tier bounds. |
| kind* | string | Line kind. one of: PRODUCT_TIER · MINIMUM |
| product | string | The product. Null on the minimum line. e.g. eligibility_check |
| tier | integer | The tier number. Null on a minimum line. e.g. 2 |
| from_units | integer | The tier's first unit of the month. Null on a minimum line. e.g. 251 |
| to_units | integer | The tier's last unit. Null for the open top tier and on a minimum line. e.g. 3500 |
| units* | integer | Units priced in this tier. e.g. 10 |
| unit_price_micros* | integer | Price per unit, in micros. e.g. 150000 |
| amount_micros* | integer | Units times price, in micros. e.g. 1500000 |
Responses
{
"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
}
]
}
]
}
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, unknown or revoked key, or wrong secret |
| 403 | PERMISSION_DENIED | The credential lacks read |
| 422 | VALIDATION | to is earlier than from |
| 422 | INVALID_REQUEST | from or to is not a valid date |
| 429 | TOO_MANY_REQUESTS | More than 20 requests in flight or the read bucket is empty |
VALIDATION, not INVALID_REQUEST.FACILITY_NOT_GRANTED is never returned.List 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| period | string | The billing month, YYYY-MM. Defaults to the current month in UTC.e.g. 2026-09 |
| product | string | Only this product. one of: eligibility_check · claim_status_check · claim_submission · adjudicated_claim · attachment |
| state | string | Only units in this state. one of: BILLABLE · PENDING · NOT_BILLABLE |
| reason | string | Only 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 |
| facilityId | string | Only this office. It must be granted to your key. e.g. fac_tycrfy0cs0qc7sq95eme |
| cursor | string | The next_cursor of the previous page: ASCII digits only.e.g. 18231 |
| limit | integer | Page size, 1 to 500. Default 100. e.g. 100 |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000301 |
| period* | string | The billing month, YYYY-MM.e.g. 2026-09 |
| data* | array | Units, newest first. |
| usage_id* | integer | The unit id. e.g. 18232 |
| occurred_at* | datetime | When it happened. |
| facility_id* | string | The office. |
| product* | string | The product. e.g. eligibility_check |
| state* | string | Billable state. one of: BILLABLE · PENDING · NOT_BILLABLE |
| reason* | string | A reason code. e.g. answered |
| label* | string | A short plain label. e.g. Payer answered |
| billing_period* | date | The first day of the month the unit is billed in. e.g. 2026-09-01 |
| source_id* | string | The eligibility id. For a saved answer, the check whose answer was served. |
| channel | string | Where it came from. one of: api · dashboard · agent · batch · system |
| actor* | object | Who sent it. |
| kind | string | api_key, member (the dashboard), operator (Claim House) or system. |
| id | string | The key id or the dashboard member's id. Null for Claim House. |
| name | string | The key's name, or Claim House. Null for a dashboard member: people's names are not stored with usage. |
| next_cursor | string | Pass as cursor for the next page. Null on the last page. |
Responses
{
"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
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, unknown or revoked key, or wrong secret |
| 403 | PERMISSION_DENIED | The credential lacks read |
| 403 | FACILITY_NOT_GRANTED | facilityId is not granted to your key |
| 422 | VALIDATION | reason is not a known reason code |
| 422 | INVALID_CURSOR | cursor is not a cursor from this list |
| 422 | INVALID_REQUEST | period, product, state or limit is not valid |
| 429 | TOO_MANY_REQUESTS | More than 20 requests in flight or the read bucket is empty |
reason of under_review with a state other than PENDING matches nothing.reason test_mode, the same as the billing object on a test mode check, whatever it was recorded as.Get 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000501 |
| state* | string | The billing state. ACTIVE once a card is saved.one of: CARD_REQUIRED · ACTIVE · PAST_DUE · SUSPENDED |
| mode* | string | How the organization is billed. INTERNAL accounts are never charged and need no card.one of: INTERNAL · CARD · INVOICE |
| processor_mode | string | test or live once a card processor customer exists for your organization, else null. |
| card | object | The card on file, or null. Brand, last four digits and expiry only: card numbers never reach Claim House. |
| brand* | string | The card brand. one of: visa · mastercard · amex · discover · diners · jcb · unionpay · unknown |
| last4* | string | The last four digits. e.g. 4242 |
| exp_month* | integer | Expiry month, 1 to 12. e.g. 4 |
| exp_year* | integer | Expiry year. e.g. 2028 |
| state_reason | string | Why the state last changed. one of: card_saved · card_removed · card_expired · customer_deleted · operator |
| state_changed_at | datetime | When the state last changed, or null. |
| live_billing_ok* | boolean | Whether billing lets your organization send live requests: an active card, or an internal account. e.g. true |
| can_manage* | boolean | Whether 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* | boolean | Whether card setup can be opened right now. False for internal accounts and while card processing is not configured. e.g. true |
Responses
{
"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
}{
"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
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed or unknown credential |
| 403 | PERMISSION_DENIED | The credential lacks read, or the session lacks billing.read |
| 503 | BILLING_UNAVAILABLE | Billing is not connected on this gateway |
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.Open card setup
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A 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
| Name | Type | Description |
|---|---|---|
| nonce* | string | A 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000502 |
| url* | string | The 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
{
"livemode": false,
"request_id": "evt_8sgg4m61en3dsc4ewj0d",
"url": "https://pay.example.com/card/cs_test_EXAMPLE"
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed or unknown credential |
| 403 | SESSION_REQUIRED | Called with an API key |
| 403 | PERMISSION_DENIED | The session lacks billing.manage |
| 409 | BILLING_INTERNAL | Your account is internal: never charged, no card needed |
| 409 | BILLING_ACCOUNT_REQUIRED | Your organization has no billing account yet |
| 409 | BILLING_PROCESSOR_MODE_MISMATCH | Your card was saved in the other card processor mode; contact support |
| 422 | VALIDATION | nonce is not a UUID |
| 503 | BILLING_UNAVAILABLE | Card setup is not available right now |
Open the card portal
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000502 |
| url* | string | The 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
{
"livemode": false,
"request_id": "evt_t9nsqb25r11sf2j4q3j7",
"url": "https://pay.example.com/manage/EXAMPLE"
}Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed or unknown credential |
| 403 | SESSION_REQUIRED | Called with an API key |
| 403 | PERMISSION_DENIED | The session lacks billing.manage |
| 409 | BILLING_CUSTOMER_REQUIRED | No card has been added yet; use card setup first |
| 409 | BILLING_INTERNAL | Your account is internal |
| 503 | BILLING_UNAVAILABLE | Card setup is not available right now |
Account and team
Confirm who a credential is, onboard a new organization, and manage the people who can use it.
| Route family | Credential | Needs an organization membership |
|---|---|---|
GET /v1/me | API key or dashboard session with read | Sessions: yes, active |
/v1/onboarding/* | Signed-in dashboard session only | No. Works before any organization exists |
/v1/members, /v1/invitations, /v1/access-requests | Dashboard session only, admin plus a member action | Yes, active. API keys are refused with 403 |
- Sign in to the dashboard, then call
GET /v1/onboarding/state. - New company: create an application, then submit it. Joining an existing company: request access with its partner reference.
- Claim House reviews the application. When the organization is
READY, the state route returnsallowed_actions: ["enter_partner"]. - Organization administrators prepare invitations for teammates and adjust each member's actions and office access.
| Record | States |
|---|---|
| Application | DRAFT > PENDING_REVIEW > NEEDS_INFORMATION | APPROVED > PROVISIONING > READY, or DECLINED / BLOCKED |
| Access request | PENDING > APPROVED_FOR_INVITATION | DECLINED |
| Invitation | PREPARED > 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.
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.Get the current identity
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id, same as the X-Request-Id header. |
| seller_id | string | API key only. Your seller id, sel_.... |
| seller_name | string | API key only. The seller's legal name. |
| seller_status | string | API key only. Seller status, for example ACTIVE. |
| principal* | object | Who is calling. |
| kind* | string | A machine key or dashboard-session principal; wire enum values appear below. one of: api_key · clerk |
| key_id | string | API key only. The key_... id. |
| subject | string | Session only. A stable pseudonymous id clerk:<24 hex> derived from the signed-in user. |
| mode* | string | test or production. For a key, the key's mode. For a session, the gateway's configured session mode.one of: test · production |
| scope | object | API key only. The key's grants. |
| kind* | string | Scope kind. one of: seller · group · facility |
| ids* | array | Array of strings. The raw grant ids. For a seller scope, [seller_id]. |
| permissions* | array | Array of strings. Sorted key permissions. one of: admin · read · submit · webhooks |
| reachable_facility_ids | array | API key only. Array of strings. Office ids the key reaches. For seller scope, every office of the seller (first 500). |
| reachable_facilities | array | The same offices as reachable_facility_ids (or office_scope.facility_ids for a session), in the same order, with names. Both shapes. |
| facility_id* | string | The office id. |
| name* | string | The display name, else the legal name, else the office code. |
| code* | string | The office code. |
| city | string | City as the office was entered. Null when not set. |
| state | string | State as the office was entered. Null when not set. |
| mode* | string | sandbox (test) or production.one of: sandbox · production |
| user | object | Session only. The signed-in person. |
| display_name* | string | Name from the session token. Empty string when the token carries none. |
| email* | string | Email from the session token. Empty string when the token carries none. |
| organization | object | Session only. The organization the session is signed into. |
| clerk_org_id* | string | The sign-in organization id. |
| seller_id* | string | The Claim House seller the organization is bound to. |
| name* | string | Seller display name, or legal name when no display name is set. |
| onboarding_state* | string | Seller onboarding status. Always READY for a session that can call this route.one of: APPLICATION · PROVISIONING · READY · BLOCKED |
| role | string | Session only. The membership role label. one of: owner · admin · submitter · viewer |
| permissions | array | Session 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_scope | object | Session only. The member's office access. |
| kind* | string | ALL, SUBSET or NONE.one of: ALL · SUBSET · NONE |
| facility_ids* | array | Array of strings. For ALL, every office of the seller. For SUBSET, the granted offices. For NONE, empty. |
| authorization_version | integer | Session only. The membership's authorization version. |
| capabilities | object | Session only. Reserved. Always an empty object today. |
Responses
{
"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
}
]
}{
"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
}
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, revoked or unverifiable credential |
| 401 | UNAUTHORIZED | Session with no active membership in a bound organization |
| 403 | PERMISSION_DENIED | Credential lacks read, or the session's membership, seller or onboarding is not active |
| 403 | FACILITY_NOT_GRANTED | API key whose group or office grants resolve to no office |
| 404 | NOT_FOUND | API key whose seller record does not exist |
| 429 | TOO_MANY_REQUESTS | Rate or concurrency limit reached |
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.seller_name, scope.office_scope and principal.role). The shapes above follow the current gateway; API key responses no longer carry scope.office_scope.Get 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id, same as the X-Request-Id header. |
| state* | string | READY 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* | array | The person's own applications, newest first. Each item has the same fields as Get an onboarding application. |
| application_id* | string | Application id, app_.... |
| status* | string | Application status. one of: DRAFT · PENDING_REVIEW · NEEDS_INFORMATION · DECLINED · APPROVED · PROVISIONING · READY · BLOCKED |
| version* | integer | Current version. |
| display_name* | string | Display name. |
| review_reason | string | Review guidance, or null. |
| invitation | object | The 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* | string | Invitation id, inv_.... |
| organization_name* | string | The inviting organization's name. |
| intended_email* | string | The email the invitation was addressed to. |
| state* | string | Invitation state. one of: PREPARED · DELIVERY_PENDING · SENT · ACCEPTED · RECONCILED · EXPIRED · REVOKED · DELIVERY_FAILED · OUTCOME_UNCERTAIN |
| version* | integer | Invitation version. |
| access_requests* | array | The person's own access requests, newest first. |
| request_id* | string | Access request id, arq_.... Not the trace id. |
| organization_reference* | string | The organization reference the request named. |
| relationship_reason* | string | Why the person asked for access. |
| status* | string | Review status. one of: PENDING · APPROVED_FOR_INVITATION · DECLINED |
| version* | integer | Current version. |
| created_at* | datetime | When it was created. |
| reviewed_at | datetime | When it was reviewed, or null. |
| allowed_actions* | array | Array of strings. ["enter_partner"] when state is READY, else ["create_application", "request_access"]. |
Responses
{
"request_id": "evt_nj662q095m3fjmnsbj9r",
"state": "READY",
"applications": [],
"invitation": null,
"access_requests": [],
"allowed_actions": [
"enter_partner"
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | No session token, an API key was presented, or session sign-in is not configured |
SUSPENDED is declared but not produced by the current organization statuses. An organization still in APPLICATION or PROVISIONING reports PENDING or NO_ORGANIZATION.Create an onboarding applicationComing soon
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.
Get an onboarding applicationComing soon
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.
Update an onboarding applicationComing soon
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.
Submit an onboarding applicationComing soon
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.
Accept an organization invitation
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
Request access to an organizationComing soon
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.
List 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.manageaction (API keys are refused) - Idempotency
- none
- Side effects
- None. Reads only.
- In the dashboard
- Settings > Organization > Team > Invite and review
Headers
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id, same as the X-Request-Id header. |
| access_requests* | array | Access requests, newest first. |
| seller_id* | string | Your seller id. |
| request_id* | string | The access request id, arq_.... |
| requester_issuer* | string | Sign-in issuer of the requester. |
| requester_user_id* | string | Sign-in user id of the requester. |
| organization_reference* | string | The reference the requester typed. |
| relationship_reason* | string | The requester's stated reason. |
| status* | string | Review status. one of: PENDING · APPROVED_FOR_INVITATION · DECLINED |
| reviewer_id | string | Reviewer, or null. |
| review_reason | string | Review reason, or null. |
| version* | integer | Current version. |
| idempotency_key* | string | The key the requester sent. |
| created_at* | datetime | When it was created. |
| reviewed_at | datetime | When it was reviewed, or null. |
Responses
{
"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
}
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, revoked or unverifiable credential |
| 403 | PERMISSION_DENIED | Lacks admin, is an API key, or the session lacks members.manage |
| 429 | TOO_MANY_REQUESTS | Rate or concurrency limit reached |
request_id is the access request id, while the top-level request_id is the trace id.List 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.readaction (API keys are refused) - Idempotency
- none
- Side effects
- None. Reads only.
- In the dashboard
- Settings > Organization > Team
Headers
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id, same as the X-Request-Id header. |
| members* | array | Members ordered by membership id. |
| membership_id* | string | The membership id, mem_.... |
| name* | string | Currently the member's sign-in user id, not a person name. |
| email* | string | Always an empty string today. |
| role* | string | Role label. one of: owner · admin · submitter · viewer |
| status* | string | Membership status. one of: PENDING · ACTIVE · SUSPENDED · REVOKED |
| actions* | array | Array 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* | string | Office access kind. one of: ALL · SUBSET · NONE |
| scope_ids* | array | Array of strings. Granted office ids. Empty for ALL and NONE. |
| scope_label* | string | Human label: All offices, <n> offices or No office access. |
| authorization_version* | integer | Send it back as expected_version when updating the member. |
| last_sign_in_at | datetime | Last time the membership was reconciled with sign-in, or null. Not a true last sign-in time. |
Responses
{
"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
}
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, revoked or unverifiable credential |
| 403 | PERMISSION_DENIED | Lacks read, is an API key, or the session lacks members.read |
| 429 | TOO_MANY_REQUESTS | Rate or concurrency limit reached |
name and email are placeholders until profile data is joined.Update a member
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.manageaction (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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A 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* | string | Must be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.e.g. application/json |
Path parameters
| Name | Type | Description |
|---|---|---|
| membership_id* | string | The membership id, mem_....e.g. mem_1w2pqxr89mss07rbry6s |
Request body
| Name | Type | Description |
|---|---|---|
| expected_version* | integer | The member's authorization_version from List members. Minimum 1.e.g. 3 |
| role* | string | The role label to record. one of: owner · admin · submitter · viewer e.g. viewer |
| actions | array | Array 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* | string | ALL 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_ids | array | Array 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* | string | Why 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
| Name | Type | Description |
|---|---|---|
| seller_id* | string | Your seller id. |
| membership_id* | string | The membership id, mem_.... |
| clerk_issuer* | string | The sign-in issuer of the member. |
| clerk_user_id* | string | The member's sign-in user id. |
| clerk_org_id* | string | The sign-in organization the membership belongs to. |
| role_template* | string | The member's role label after the change. one of: owner · admin · submitter · viewer |
| status* | string | Membership status. one of: PENDING · ACTIVE · SUSPENDED · REVOKED |
| authorization_version* | integer | Increments on every access change. Send it back as expected_version. |
| all_current_and_future_offices* | boolean | True when the new scope is ALL. |
| invitation_id | string | The invitation the membership came from, or null. |
| source* | string | How the membership was created, for example invitation. |
| activated_at | datetime | When it became active, or null. |
| suspended_at | datetime | When it was suspended, or null. |
| revoked_at | datetime | When it was revoked, or null. |
| last_reconciled_clerk_event | string | Last sign-in provider event applied, or null. |
| last_reconciled_at | datetime | When it was last reconciled, or null. |
Responses
{
"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
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, revoked or unverifiable credential |
| 403 | PERMISSION_DENIED | Lacks admin, is an API key, or the session lacks members.manage |
| 403 | DELEGATION_EXCEEDED | Actions or offices exceed yours, or office_ids do not fit scope_kind |
| 409 | STALE_VERSION_OR_STATE | expected_version is stale or the membership id is unknown |
| 409 | MEMBERSHIP_CHANGE_REFUSED | Demoting the last active owner, or an office id that is not yours |
| 422 | INVALID_REQUEST | Body, path or header does not fit the schema |
| 429 | TOO_MANY_REQUESTS | Rate or concurrency limit reached |
request_id, actions or office list. Call List members to see the new access.role is a label. What the member can do comes from actions and office scope.List 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.manageaction (API keys are refused) - Idempotency
- none
- Side effects
- None. Reads only.
- In the dashboard
- Settings > Organization > Team > Invite and review
Headers
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id, same as the X-Request-Id header. |
| invitations* | array | Invitations, newest first. |
| invitation_id* | string | The invitation id, inv_.... |
| organization_name* | string | Your organization's display name, or legal name. |
| intended_email* | string | The invitee email. |
| email* | string | Same value as intended_email. |
| role* | string | Proposed role label. one of: owner · admin · submitter · viewer |
| office_scope* | object | Proposed office access. |
| kind* | string | Scope kind. one of: ALL · SUBSET · NONE |
| facility_ids | array | Array of strings. Present only when kind is SUBSET. |
| state* | string | Invitation state. one of: PREPARED · DELIVERY_PENDING · SENT · ACCEPTED · RECONCILED · EXPIRED · REVOKED · DELIVERY_FAILED · OUTCOME_UNCERTAIN |
| version* | integer | Current version. |
| created_at* | datetime | When it was prepared. |
Responses
{
"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"
}
]
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, revoked or unverifiable credential |
| 403 | PERMISSION_DENIED | Lacks admin, is an API key, or the session lacks members.manage |
| 429 | TOO_MANY_REQUESTS | Rate or concurrency limit reached |
intended_email_display, role_template, proposed_scope_kind).Prepare an invitation
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.manageaction (API keys are refused) - Idempotency
- none
- Side effects
- Stores one
PREPAREDinvitation 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A 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* | string | Must be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.e.g. application/json |
Request body
| Name | Type | Description |
|---|---|---|
| email* | string | The invitee email. 3 to 254 characters, must contain @. Stored lowercased.e.g. sample.teammate@example.com |
| role* | string | The role label to propose. one of: owner · admin · submitter · viewer e.g. submitter |
| scope_kind* | string | Proposed office access. one of: ALL · SUBSET · NONE e.g. SUBSET |
| office_ids | array | Array 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"] |
| actions | array | Array 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* | datetime | When 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
| Name | Type | Description |
|---|---|---|
| seller_id* | string | Your seller id, sel_.... |
| invitation_id* | string | The invitation id, inv_.... |
| intended_email_digest* | string | SHA-256 hex digest of the lowercased invitee email. |
| intended_email_display* | string | The invitee email, lowercased. |
| role_template* | string | The role label proposed for the invitee. one of: owner · admin · submitter · viewer |
| proposed_scope_kind* | string | The office scope proposed for the invitee. one of: ALL · SUBSET · NONE |
| expires_at* | datetime | When the invitation stops being valid. |
| clerk_invitation_id | string | The sign-in provider's invitation id once delivered, else null. |
| delivery_operation_id | string | Id of the single delivery attempt once one starts, else null. |
| state* | string | Invitation state. one of: PREPARED · DELIVERY_PENDING · SENT · ACCEPTED · RECONCILED · EXPIRED · REVOKED · DELIVERY_FAILED · OUTCOME_UNCERTAIN |
| version* | integer | Increments on every change. Send it back as expected_version. |
| created_by* | string | The user id of the administrator who prepared it. |
| created_at* | datetime | When it was prepared. |
| revoked_at | datetime | When it was revoked, else null. |
| accepted_at | datetime | When acceptance was observed, else null. |
| reconciled_at | datetime | When membership was reconciled, else null. |
Responses
{
"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
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, revoked or unverifiable credential |
| 403 | PERMISSION_DENIED | Lacks admin, or is an API key |
| 403 | DELEGATION_EXCEEDED | Session lacks members.manage, actions or offices exceed yours, or office_ids do not fit scope_kind |
| 404 | NOT_FOUND | An office id outside your own office access |
| 422 | INVALID_REQUEST | Body, path or header does not fit the schema |
| 429 | TOO_MANY_REQUESTS | Rate or concurrency limit reached |
| 503 | REGISTRY_WRITE_FAILED | The invitation was not stored |
Send an invitation
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.manageaction (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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A 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* | string | Must be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.e.g. application/json |
Path parameters
| Name | Type | Description |
|---|---|---|
| invitation_id* | string | The invitation id, inv_....e.g. inv_c78sg2v0veqke88d7h7s |
Request body
| Name | Type | Description |
|---|---|---|
| expected_version* | integer | The invitation version you last read. Minimum 1.e.g. 1 |
| confirmed* | boolean | Must be true. Confirms you intend a real delivery.e.g. true |
Request example
{
"expected_version": 1,
"confirmed": true
}Response fields
| Name | Type | Description |
|---|---|---|
| seller_id* | string | Your seller id, sel_.... |
| invitation_id* | string | The invitation id, inv_.... |
| intended_email_digest* | string | SHA-256 hex digest of the lowercased invitee email. |
| intended_email_display* | string | The invitee email, lowercased. |
| role_template* | string | The role label proposed for the invitee. one of: owner · admin · submitter · viewer |
| proposed_scope_kind* | string | The office scope proposed for the invitee. one of: ALL · SUBSET · NONE |
| expires_at* | datetime | When the invitation stops being valid. |
| clerk_invitation_id | string | The sign-in provider's invitation id once delivered, else null. |
| delivery_operation_id | string | Id of the single delivery attempt once one starts, else null. |
| state* | string | Invitation state. one of: PREPARED · DELIVERY_PENDING · SENT · ACCEPTED · RECONCILED · EXPIRED · REVOKED · DELIVERY_FAILED · OUTCOME_UNCERTAIN |
| version* | integer | Increments on every change. Send it back as expected_version. |
| created_by* | string | The user id of the administrator who prepared it. |
| created_at* | datetime | When it was prepared. |
| revoked_at | datetime | When it was revoked, else null. |
| accepted_at | datetime | When acceptance was observed, else null. |
| reconciled_at | datetime | When membership was reconciled, else null. |
Responses
{
"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."
}{
"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
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, revoked or unverifiable credential |
| 403 | PERMISSION_DENIED | Lacks admin, is an API key, or the session lacks members.manage |
| 409 | CONFIRMATION_REQUIRED | confirmed is not true |
| 409 | STALE_VERSION_OR_STATE | Version mismatch, not PREPARED, or unknown id |
| 502 | DELIVERY_OUTCOME_UNCERTAIN | Delivery failed or could not be recorded; do not resend |
| 503 | INVITATION_DELIVERY_UNCONFIGURED | No delivery provider is configured (the current default) |
| 422 | INVALID_REQUEST | Body, path or header does not fit the schema |
| 429 | TOO_MANY_REQUESTS | Rate or concurrency limit reached |
INVITATION_DELIVERY_UNCONFIGURED and no email is sent.code, message and invitation, with no error or request_id. No route can clear OUTCOME_UNCERTAIN yet; contact Claim House support.Revoke an invitation
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.manageaction (API keys are refused) - Idempotency
- none
- Side effects
- Sets the invitation state to
REVOKEDand stampsrevoked_at. Does not contact the sign-in provider. - In the dashboard
- API only
Headers
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A 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* | string | Must be application/json. Without it the body is not parsed and the route answers 422 INVALID_REQUEST.e.g. application/json |
Path parameters
| Name | Type | Description |
|---|---|---|
| invitation_id* | string | The invitation id, inv_....e.g. inv_c78sg2v0veqke88d7h7s |
Request body
| Name | Type | Description |
|---|---|---|
| expected_version* | integer | The invitation version you last read. Minimum 1.e.g. 1 |
| reason* | string | Why 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
| Name | Type | Description |
|---|---|---|
| seller_id* | string | Your seller id, sel_.... |
| invitation_id* | string | The invitation id, inv_.... |
| intended_email_digest* | string | SHA-256 hex digest of the lowercased invitee email. |
| intended_email_display* | string | The invitee email, lowercased. |
| role_template* | string | The role label proposed for the invitee. one of: owner · admin · submitter · viewer |
| proposed_scope_kind* | string | The office scope proposed for the invitee. one of: ALL · SUBSET · NONE |
| expires_at* | datetime | When the invitation stops being valid. |
| clerk_invitation_id | string | The sign-in provider's invitation id once delivered, else null. |
| delivery_operation_id | string | Id of the single delivery attempt once one starts, else null. |
| state* | string | Invitation state. one of: PREPARED · DELIVERY_PENDING · SENT · ACCEPTED · RECONCILED · EXPIRED · REVOKED · DELIVERY_FAILED · OUTCOME_UNCERTAIN |
| version* | integer | Increments on every change. Send it back as expected_version. |
| created_by* | string | The user id of the administrator who prepared it. |
| created_at* | datetime | When it was prepared. |
| revoked_at | datetime | When it was revoked, else null. |
| accepted_at | datetime | When acceptance was observed, else null. |
| reconciled_at | datetime | When membership was reconciled, else null. |
Responses
{
"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
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, revoked or unverifiable credential |
| 403 | PERMISSION_DENIED | Lacks admin, is an API key, or the session lacks members.manage |
| 409 | STALE_VERSION_OR_STATE | Version mismatch, not PREPARED or SENT, or unknown id |
| 422 | INVALID_REQUEST | Body, path or header does not fit the schema |
| 429 | TOO_MANY_REQUESTS | Rate or concurrency limit reached |
reason is required but is not stored today.SENT invitation does not withdraw the email already delivered by the sign-in provider.Read notification preferencesComing soon
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.
Save notification preferencesComing soon
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.
Request a product entitlementComing soon
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.
Look up candidate 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | A 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
| Name | Type | Description |
|---|---|---|
| organization_ids* | string | Comma-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
| Name | Type | Description |
|---|---|---|
| request_id* | string | Unique id for this request. Also returned in the X-Request-Id header.e.g. evt_EXAMPLE0000000000000031 |
| organizations* | array | The candidates this identity belongs to, in candidate order. |
| organization_id* | string | The organization id. e.g. org_EXAMPLE0000000000000001 |
| name* | string | Organization display name. e.g. Northgate Dental Partners |
| state* | string | Membership readiness for this identity. one of: READY · SUSPENDED · PENDING · BLOCKED e.g. READY |
| authorization_version* | integer | The organization's authorization version at read time. e.g. 3 |
| can_enter* | boolean | True when the identity may enter this organization now (active membership, active organization, onboarding ready). e.g. true |
Responses
{
"request_id": "evt_ang0n1gexynjw0dmfh8v",
"organizations": [
{
"organization_id": "org_35ka7045j25e5w5h2a32",
"name": "Northgate Dental Partners",
"state": "READY",
"authorization_version": 3,
"can_enter": true
}
]
}Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | missing, invalid or expired session token |
| 422 | INVALID_ORGANIZATION_CANDIDATES | zero or more than 100 ids, an empty value, or an id over 200 characters |
| 503 | IDENTITY_REGISTRY_UNAVAILABLE | organization access cannot be verified |
| 429 | TOO_MANY_REQUESTS | rate or concurrency limit reached |
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.
| Type | Meaning | Claim state effect | artifact_id | Key summary fields |
|---|---|---|---|---|
claim.received | Submission stored but held at intake for review. | Created in HOLD. | none | submission_id, state, finding_codes |
claim.queued | Passed intake, waiting for a transport window. | Created in QUEUED. | none | submission_id, state, finding_codes |
submission.rejected_pre_transport | Intake edits rejected the submission, one event per claim. Nothing sent. | Created in REJECTED_PRE_TRANSPORT (terminal). | none | submission_id, state, finding_codes |
claim.transported | The outbound 837D file was uploaded once and verified by read-back. | Moves to TRANSPORTED. | The 837D file as sent | file_id, file_stem, window_id, session_id |
claim.transport_ambiguous | The single upload attempt failed or could not be verified. Never resent automatically. | Moves to TRANSPORT_AMBIGUOUS. | The 837D file attempted | file_id, reason (put_failed:<ErrorClass> or readback_mismatch) |
claim.operator_resolved | An operator settled an ambiguous file with the clearinghouse. | TRANSPORTED (delivered), QUEUED (not delivered) or CLOSED (dead). | none | resolution, resolved_by, file_id, note |
claim.ack_997 | A 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 file | group_code, transaction_code, ack_kind, accepted_with_errors, errors, error_count |
claim.ack_999 | A 999 acknowledgment arrived. | Same as claim.ack_997. | The 999 file | Same as claim.ack_997, ack_kind 999 |
claim.status_277 | A 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 file | category_code, status_code, entity_code, effective_date, payer_claim_number |
claim.stalled_997 | No 997 within the window after transport (default 4 hours). Raised once. | STALLED_997, only from TRANSPORTED. | none | expected_event_kind, due_at, sla_seconds |
claim.stalled_277 | No 277 within the window after transport (default 2 days). Raised once. | STALLED_277, only from TRANSPORTED. | none | expected_event_kind, due_at, sla_seconds |
claim.paid | An 835 line paid the claim fully or partly. | Moves to PAID (not from REJECTED_PRE_TRANSPORT). | The 835 file | claim_status_code, remittance_id, payment_id, charged_amount, paid_amount, patient_responsibility, trace_number, payment_date |
claim.denied | An 835 line with CLP02 4 denied the claim. | Moves to DENIED. | The 835 file | Same as claim.paid |
claim.reversed | An 835 line with CLP02 22 reversed a payment. | Moves to REVERSED. | The 835 file | Same as claim.paid |
remittance.received | An 835 file included at least one of your claims. One per seller per file. | None (applied: false). | The 835 file | remittance_id, claim_count, paid_amount, claim_ids, trace_number, payment_method, payer_id |
eligibility.checked | An eligibility check finished. | No claim (claim_id is null). | none | eligibility_id, payer_id, status, outcome, cache, mode |
eligibility.pdf_generated | A PDF of an eligibility answer was generated. | No claim. | The PDF | eligibility_id, artifact_id, filename, bytes |
attachment.sent | An attachment packet was delivered and named a resolvable claim. | None (applied: false). | none | packet_id, payer_id, door, outcome (OK), reference, send_id |
attachment.failed | An attachment send failed or was ambiguous and named a resolvable claim. | None. | none | Same as attachment.sent, outcome FAILED or AMBIGUOUS |
attachment.packet_created | A packet was created. | Written only to the packet's own timeline, so it does not appear in this feed today. | none | packet_id, attachment_count, deduplicated_count, kinds |
- Load your stored cursor (start at
0). The cursor is a plain integer and never expires. - Call
GET /v1/events?since_cursor=<cursor>&limit=500. Events come back oldest first in ascendingsequence. - Process each event, skipping any
event_idyou already processed.sequenceis shared by every seller, so gaps are normal. - Store
next_cursoronly after processing succeeds. On an empty page it echoes yoursince_cursor. - If
has_moreis 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 byevent_id.
- Out-of-order evidence is normal: a 277 can arrive before its 997. Use
appliedandstate, not the event type, to know the current claim state. occurred_atis not monotonic withsequence. 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.
| Record | Id | Where you find the id | What you get |
|---|---|---|---|
| Artifact | art_... | artifact_id on events, remittance records and the eligibility PDF response | A short-lived download URL for one stored document (837D, 997, 999, 277, 835 or eligibility PDF). |
| File | file_... | transport.file_id on a submission, or summary.file_id on transport events | The transport record of one outbound 837D file (control numbers, hash, state) plus a download URL when one exists. |
List eventsComing soon
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.
Get an artifact
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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| artifact_id* | string | The 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
| Name | Type | Description |
|---|---|---|
| request_id* | string | The request id. e.g. evt_EXAMPLE0000000000202 |
| artifact_id* | string | The id you asked for. e.g. art_EXAMPLE0000000000277 |
| download_filename | string | Suggested 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_id | string | Claim of the first event that references this artifact. Null for an eligibility PDF. |
| facility_id* | string | Office of that first event. e.g. fac_EXAMPLE0000000000001 |
| event_kind* | string | Type of that first event. e.g. claim.status_277 |
| url* | string | The download URL. Anyone holding it can download the file until it expires, so never log or store it. |
| expires_in_seconds* | integer | Lifetime of url in seconds.e.g. 600 |
Responses
{
"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
}{
"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."
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, unknown or revoked key, or wrong secret |
| 403 | PERMISSION_DENIED | The credential lacks read |
| 403 | FACILITY_NOT_GRANTED | The key has no office grant at all |
| 404 | NOT_FOUND | No event in your seller and grants references this id |
| 422 | INVALID_REQUEST | artifact_id longer than 64 characters |
| 429 | TOO_MANY_REQUESTS | More than 20 requests in flight or the read bucket is empty |
| 503 | ARTIFACT_URL_UNAVAILABLE | The archive store cannot produce a URL |
<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.expires_in_seconds (600 today). Do not cache it, log it or put it in page HTML.file:// path on the gateway machine instead of a signed URL.Get an outbound fileComing soon
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.
List 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
| Name | Type | Description |
|---|---|---|
| Authorization* | string | Your 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
| Name | Type | Description |
|---|---|---|
| facility_id | string | Only calls that named this office. Repeat the parameter for several offices. Each must be granted to your key. e.g. fac_tycrfy0cs0qc7sq95eme |
| outcome | string | ok (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 |
| source | string | Only API key calls or only dashboard calls. one of: api_key · dashboard e.g. api_key |
| product | string | Only this product area, up to 40 characters. See product below for the values. Any other value returns no rows.e.g. eligibility |
| key_id | string | Only calls made by this API key, up to 64 characters. e.g. key_7qm2x9d4hs3ve6kt8wbn |
| resource_id | string | Only 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_only | boolean | true leaves out GET calls, so only calls that could change something remain. Default false.e.g. true |
| before | string | The next_cursor from the previous page, up to 120 characters.e.g. 2026-09-28T16:39:48.842388+00:00|evt_f911mnkad52wv96ggzty |
| limit | integer | Rows to return, 1 to 500. Default 100. e.g. 2 |
Request example
null
Response fields
| Name | Type | Description |
|---|---|---|
| request_id* | string | Request id. The same value as the X-Request-Id header. |
| data* | array | Calls, newest first. |
| request_id* | string | The 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* | datetime | When the call arrived. e.g. 2026-09-28T16:39:48.843382+00:00 |
| method* | string | HTTP method. one of: GET · POST · PUT · PATCH · DELETE e.g. POST |
| route* | string | The route template, not the literal URL, so ids never appear here. For example /v1/eligibility/{eligibility_id}.e.g. /v1/eligibility |
| status* | integer | HTTP status the call answered with. e.g. 200 |
| latency_ms* | integer | Time taken in milliseconds. e.g. 412 |
| source* | string | api_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_id | string | The API key that made the call. Null for dashboard calls. e.g. key_7qm2x9d4hs3ve6kt8wbn |
| actor_id | string | The dashboard user who made the call. Null for API key calls. |
| mode | string | The 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_id | string | The office the call named, from the path, the query or the refusal. Null when the call named no office. e.g. fac_tycrfy0cs0qc7sq95eme |
| product* | string | The product area, from the route: eligibility, payers, claims, attachments, remittances, webhooks, artifacts, events, or account for everything else.e.g. eligibility |
| resource_ids* | array | Array 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_code | string | The error code the call answered with, for example FACILITY_NOT_GRANTED. Null on success. |
| next_cursor | string | Pass 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
{
"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"
}{
"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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, unknown or revoked |
| 403 | PERMISSION_DENIED | Key lacks read |
| 403 | FACILITY_NOT_GRANTED | A facility_id is not covered by the key's grants, or the key has no office grants |
| 422 | INVALID_CURSOR | before does not start with a valid timestamp |
| 422 | INVALID_REQUEST | outcome or source is not an allowed value, limit is out of range, or a parameter is too long |
| 429 | TOO_MANY_REQUESTS | More than 20 in flight or rate bucket empty |
GET /v1/me, are not shown to it.facility_id that is not one of your offices is not refused. It simply returns no rows.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.
Submit an 837D fileComing soon
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.
Submit a dental claim as JSONComing soon
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.
Submit raw X12 with a compat responseComing soon
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.
Check an 837D without sending itComing soon
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.
Inspect an 837D element by elementComing soon
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.
Get a submissionComing soon
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.
List claimsComing soon
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.
Get a claimComing soon
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.
Track a claimComing soon
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.
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.
Create a claim draftComing soon
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.
Get a claim draftComing soon
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.
Update a claim draftComing soon
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.
Build a claim draftComing soon
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.
Submit a claim draftComing soon
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.
List claim draftsComing soon
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.
Delete a claim draftComing soon
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.
Read draft historyComing soon
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.
Get a claim importComing soon
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.
Import claims as draftsComing soon
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.
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.
List attachment providersComing soon
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.
Save an attachment providerComing soon
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.
Create an attachment draftComing soon
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.
Retrieve an attachment draftComing soon
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.
Update an attachment draftComing soon
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.
Create an attachment packetComing soon
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.
Retrieve an attachment packetComing soon
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.
Validate an attachment draftComing soon
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.
Send an attachment draftComing soon
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.
Send an attachment packetComing soon
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.
List attachment draftsComing soon
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.
Get attachment requirementsComing soon
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.
Get attachment requirements in bulkComing soon
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.
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.
List remittancesComing soon
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.
Get a remittanceComing soon
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.
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.
Create a webhook endpointComing soon
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.
List webhook endpointsComing soon
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.
List webhook deliveriesComing soon
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.
Replay a webhook deliveryComing soon
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.
Rotate a webhook signing secretComing soon
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.