Claim.MD
Claim.MD is a medical claims clearinghouse. Gravity Rail connects to the practice's own Claim.MD account and uses seven of its services.
Authentication
Claim.MD has no partner app model and no OAuth. A workspace supplies one
AccountKey, created by an account user in the Claim.MD portal under
Settings → Account Settings. The key authorises every service on the account
(read all claims and ERAs, submit, archive); there are no scopes, so least
privilege is enforced by Gravity Rail, not by the vendor.
The key is stored encrypted on the workspace's connection row. It is never logged, never returned by an API response and never written to a Form. Rotation is manual: regenerate it in the Claim.MD portal, then paste the new one.
Endpoints used
All calls are POST to https://svc.claim.md/services/<name>/ with
Accept: application/json and the AccountKey in the form body.
| Service | Use |
|---|---|
payerlist | payer ids and which services each payer supports; becomes the payers Directory |
eligdata | one real-time 270/271 eligibility inquiry |
upload | transmit claims as a multipart JSON claim file |
response | claim acceptance, rejection and payer acknowledgement (cursor: ResponseID) |
eralist | newly received remittances (cursor: ERAID) |
eradata | one remittance in structured form |
archive | withdraw a claim (by Claim.MD's claim id, not the caller's) |
Test and production accounts share the host and the payer ids; only the
AccountKey differs. The workspace records which environment its account is.
Operations
The Connector Operation action invokes these operations for an installed Claim.MD connection.
| Slug | Parameters | Notes |
|---|---|---|
claim_md.eligibility_check | providerId, coverageId?, serviceDate? | Subject is the Current Member. providerId is required. A missing provider skips the action. Records an eligibility_check row. |
claim_md.submit_claim | preview? (default true), chargeIds[]?, coverageId?, providerId?, claimId?, submissionId? | Builds a claim from the Member's draft charges (exactly chargeIds, or the draft charges for the coverage). An explicit providerId must match those charges. A preview validates and transmits nothing; preview: false uploads. Pass the preview's claimId and submissionId back unchanged. Both are canonical UUIDs; malformed values return invalid_claim_parameters. |
claim_md.claim_status | claimId | Reads one of the Member's claims back from Claim.MD and records it; returns the stored status when nothing is newer. |
claim_md.archive_claim | claimId | Withdraws one of the Member's transmitted claims. |
claim_md.list_open_denials | limit? (1–100, default 100), after? (native claim UUID cursor) | One page of the Member's open denials. Returns count, claims, hasMore, nextAfter. Pass nextAfter back as after while hasMore is true. Invalid parameters return invalid_page. |
claimId is Gravity Rail's native claim UUID. submissionId identifies the
separate transmission and its frozen vendor request.
Operation results carry ids, counts, status and closed codes. Eligibility benefit
values, including plan name, deductible, co-pay, co-insurance and visit limits,
remain in native eligibility records. Read them through medical billing APIs
with medical billing scopes, Member access and PHI audit. A refusal is a closed error_code: for example no_coverage,
no_charges, missing_provider, mixed_billing_providers, submission_already_started,
charge_not_draft, charge_billing_mismatch, missing_billing_address, claim_rejected,
claim_not_found, missing_patient_identity or claim_not_transmitted.
Uploads reserve charges before transmission. A timeout or missing acknowledgement keeps the charges reserved for reconciliation. A confirmed rejection makes the charges available for a corrected claim with a new id.
Data model
Medical billing owns typed workspace records for providers, coverage, charges,
claims, submissions, eligibility checks and remittances. Claim.MD and Stedi are
adapters over that domain. Clinical data does not depend on mutable Form schemas.
The payers Directory remains a vendor catalog refreshed from payerlist.
Claims freeze selected charge lines. Submissions persist the exact vendor request before transmission and retain acceptance separately from adjudication. A database reservation prevents the same charge from being submitted concurrently to either provider. Coverage payer routes name their destination explicitly.
Submissions and withdrawals emit an IDs-only PHI_RECORD_EXPORTED event for
each real vendor-call attempt. Its destination is Claim.MD; uncertain transport
outcomes remain recorded as attempts. Previews and blocked operations emit no
export event. History pages have no lifetime cap and carry explicit continuation; too_many_lines refuses an oversized claim selection.
PHI responsibilities
Native claims, coverage, eligibility and remittance records contain PHI. Restrict access to authorized Members, encrypt any exported data at rest and in transit, and keep patient values out of logs, traces and rule-result payloads. Follow the PHI handling guide when storing or transmitting these records. The AccountKey must remain server-side.
Errors
| Condition | Behaviour |
|---|---|
| 403 | Claim.MD's rate-limit/security block (100 requests per minute). Retried with the provider's stated wait, then surfaced; a batch pass stops. |
| 408, 5xx | Retried, then surfaced as a transient failure. |
HTTP 200 with error[] | A Claim.MD-level failure. The known numeric code (63) is recorded; other codes record the class only. |
HTTP 200 with elig.error[] | A payer-level answer. Recorded as payer_error with typed error details, never retried. |
claim[].status == "R" | A claim rejection. The reason is stored on the claim row. |