Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.have-foresight.app/llms.txt

Use this file to discover all available pages before exploring further.

A claim moves through a deterministic state machine. Each transition is either driven by an API call you make, or by an external event (payer acknowledgement, ERA receipt) that we surface as a webhook.

​
State machine

draft → validated → scrubbed → submitted → accepted → paid
                                       └──→ rejected (clearinghouse)
                                       └──→ denied (payer adjudication)
                                                └──→ appealed → reopened
StateSet byDescription
draftPOST /v1/claimsCreated but not validated.
validatedPOST /v1/claims/{id}/validatePassed structural validation.
scrubbedPOST /v1/claims/{id}/scrubPassed payer-specific edits + medical-necessity.
submitted(auto) clearinghouse sendSent to clearinghouse.
accepted(auto) 277CA receiptPayer acknowledged the claim.
rejected(auto) 277CA receiptFront-end / clearinghouse rejection.
denied(auto) 835 receiptAdjudicated and denied.
paid(auto) 835 receiptPaid (full or partial).
appealedPOST /v1/appealsAn appeal has been opened.
reopened(auto) appeal outcomeOutcome reversal; back into the lifecycle.

​
Typical sequence

​
1. Create the draft

POST /v1/claims
Body includes patient, insurance policy, clinician, place of service, service lines (CPT codes, units, charges in cents), and diagnosis pointers.

​
2. Validate

POST /v1/claims/{id}/validate
Runs structural validation — required fields, code format, NPI checks, DOB-vs-service-date sanity. Returns a list of errors and warnings. 
POST /v1/claims/{id}/check-eligibility
Verifies the patient’s policy is active for the service date and that the policy covers the service types on the claim.

​
4. Scrub

POST /v1/claims/{id}/scrub
Applies payer-specific edits (modifier rules, bundling, frequency limits) and Foresight’s medical-necessity DNF engine. Returns suggested fixes.

​
5. Apply suggested fixes

POST /v1/claims/{id}/apply-fixes
Or apply individually with POST /v1/claims/{id}/apply-fix.

​
6. Submit

Submission is automatic when the claim transitions to submitted after successful scrubbing, OR you can explicitly batch-submit a set of encounters with: 
POST /v1/encounters/batch-create-claims

​
7. Track to payment

Subscribe to claim.accepted, claim.denied, and claim.paid webhooks. Or poll list endpoints.

​
Required documents

Some claims require attached documents (operative reports, medical necessity letters, etc.). Foresight tells you which: 
GET /v1/claims/{id}/required-documents
Attach documents with: 
POST /v1/claims/{id}/documents

​
ETA prediction

For high-value claims, you can request a payment-ETA prediction: 
POST /v1/claims/calculate-eta
Returns the predicted business-day window based on payer historical behavior.

​
Reference

See the full Claims API reference.