Skip to main content

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.

ServiceUse
payerlistpayer ids and which services each payer supports; becomes the payers Directory
eligdataone real-time 270/271 eligibility inquiry
uploadtransmit claims as a multipart JSON claim file
responseclaim acceptance, rejection and payer acknowledgement (cursor: ResponseID)
eralistnewly received remittances (cursor: ERAID)
eradataone remittance in structured form
archivewithdraw 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.

SlugParametersNotes
claim_md.eligibility_checkproviderId, coverageId?, serviceDate?Subject is the Current Member. providerId is required. A missing provider skips the action. Records an eligibility_check row.
claim_md.submit_claimpreview? (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_statusclaimIdReads one of the Member's claims back from Claim.MD and records it; returns the stored status when nothing is newer.
claim_md.archive_claimclaimIdWithdraws one of the Member's transmitted claims.
claim_md.list_open_denialslimit? (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​

ConditionBehaviour
403Claim.MD's rate-limit/security block (100 requests per minute). Retried with the provider's stated wait, then surfaced; a batch pass stops.
408, 5xxRetried, 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.