These reference docs are public — read the whole API before you sign up. Running the calls needs sandbox credentials, issued after business (KYB) and identity (KYC) verification. No live money or live patient data is reachable from the sandbox tier; production access is a separate approval.
Documentation menu
Clearinghouse, claims & eligibility
shteg.ai is the clearinghouse of record — a real Type-2 organizational NPI and a registered HIPAA clearinghouse. These endpoints move a coded ophthalmology encounter through the revenue cycle: submit a professional claim (837P) stamped with the shteg.ai billing identity, scrub it against NCCI/MUE edits, poll 276/277 status, post 835 remittances into the double-entry ledger, and verify 270/271 eligibility. Every request and response is JSON over HTTPS; the base URL is your sandbox origin.
Available in sandboxProduction access: not yet available
This is the sandbox surface — real logic, zero live data. No live money or live patient data is reachable from this tier; production access is a separate approval. Where a transport or payer credential is unconfigured, the endpoint returns a typed 503 with zero network calls — it never fabricates an acknowledgment, a remittance, or eligible coverage.
Conventions
Authentication & scopes
Every API request is authenticated before it reaches a handler. Requests are automatically scoped to your organization from your credentials — you never pass an organization or clinic identifier — and scopes are enforced per route.
claims:read — list claims, read scrub verdicts, poll status.
claims:write — submit, scrub, appeal, and post ERAs from staff.
eligibility:read — run and read 270/271 eligibility verification.
Tenant scoping: every request is automatically scoped to your organization from your credentials; claims and eligibility that touch a patient additionally require the patient to be enrolled with your organization.
Correlation: pass x-correlation-id and it is echoed back on every claim response for tracing; omit it and one is generated for you.
Money is always integer cents on the wire and in the ledger — charges and remittance amounts are conserving integer cents, never floating dollars.
Transmit a professional claim (837P) to shteg.ai, the clearinghouse of record. The 837P is built and stamped with shteg.ai's Type-2 NPI as the billing provider (loop 2010AA), then transmitted through the pluggable transport. Before anything leaves the gateway, the route runs an auto-scrubber pre-check (NCCI, laterality, prior-auth, global period); any blocking finding halts transmission with a 422. Pass a claimId to submit an already-persisted claim, or inline claim fields to persist-then-submit a new one.
Fail-closed. When the sanctioned transport or clearinghouse billing identity is not configured, the endpoint returns 503 with zero network calls. It never persists or returns a simulated ACCEPTED.
Request body
Name
Type
In
Required
Description
claimId
string
body
Optional
Submit an already-persisted claim. Provide this OR patientId.
patientId
string
body
Optional
Persist-then-submit a new claim for this clinic-enrolled patient.
payerId
string
body
Optional
Payer routing key used to select the transport (direct vs upstream).
payerName
string
body
Optional
Payer display name (inline-create).
payerEdiId
string
body
Optional
Payer EDI / trading-partner id (inline-create).
subscriberId
string
body
Optional
Subscriber / member id (inline-create).
serviceDate
string
body
Optional
Date of service (inline-create).
totalCharge
number
body
Optional
Total charge in dollars; stored as conserving integer cents.
diagnosisCodes
string[]
body
Optional
ICD-10 diagnosis codes (inline-create).
procedureCodes
string[]
body
Optional
CPT/HCPCS procedure codes (inline-create).
renderingNpi
string
body
Optional
Rendering provider NPI (inline-create).
idempotencyKey
string
body
Optional
Dedup key; a repeat key returns 409 rather than a duplicate claim.
x-correlation-id
string
header
Optional
Trace id echoed back on the response.
Response — 200
Field
Type
Description
ok
boolean
True when the clearinghouse accepted the 837P.
claimId
string
Persisted claim id.
status
string
Claim lifecycle status (e.g. SUBMITTED, ACCEPTED).
acknowledgmentId
string
Transport acknowledgment / transaction id for status polling.
transport
string
Which transport carried the claim.
mode
string
Transport mode used for this submission.
scrubWarnings
object[]
Non-blocking scrub findings, surfaced not dropped (omitted when none).
List professional (837P) claims for the tenant clinic together with their 835 remittance history. Reads only — no claim, remittance, or coding data is ever synthesized. Results are automatically scoped to your organization and capped at 100, newest first.
Name
Type
In
Required
Description
patientId
string
body
Optional
Query param ?patientId= — filter to one patient.
status
string
body
Optional
Query param ?status= — filter by claim lifecycle status.
Field
Type
Description
count
number
Number of claims returned.
claims
object[]
Claims with patient, encounter, lines, and up to 5 recent remittances (835 postings).
Report a claim's status: the locally-persisted status plus a live X12 276/277 claim-status inquiry to the payer through the pluggable transport. The response carries a real normalized payer status — RECEIVED, IN_PROCESS, FINALIZED_PAID, FINALIZED_PARTIAL, FINALIZED_DENIED, NOT_FOUND, or ERROR — never a fabricated "paid". Only gateway-minimized identifiers cross to the payer; no patient name or DOB leaves the gateway.
Fail-closed. With no upstream credentials, the route returns 503 claim_status_not_configured rather than a fabricated status. A transport or parse failure resolves to ERROR — it can never read as adjudicated or paid, and it moves no money.
Name
Type
In
Required
Description
id
string
path
Required
Claim id to inquire on.
x-correlation-id
string
header
Optional
Trace id echoed back.
Field
Type
Description
claimId
string
The claim inquired on.
localStatus
string
The locally-persisted claim status.
payerClaimId
string
Payer claim control number (ICN) when known.
transport.status
string
Real normalized payer status (RECEIVED … FINALIZED_DENIED / ERROR).
Run the pre-submission scrubber over the claim and its service lines — NCCI edits, MUE limits, laterality — and persist the verdict onto the claim. A scrub whose status is errors or not_verified is flagged not ready to submit. Use GET/api/claims/[id]/scrub (scope claims:read) to read the last persisted verdict without re-running.
Fail-closed. The verdict comes verbatim from the engine. If an edit set could not run (for example a missing MUE table), the status is not_verified and readyToSubmit is false — a scrub is never reported clean when it could not fully run.
Name
Type
In
Required
Description
id
string
path
Required
Claim id to scrub.
Field
Type
Description
claimId
string
The scrubbed claim.
status
string
clean | warnings | errors | not_verified.
readyToSubmit
boolean
False on any blocking error or unverified edit set.
Scrub engine unavailable; a claim is never reported clean when the edit set could not run.
Try it
POST
/api/claims/[id]/scrub
Example · sandbox-shaped
Run the NCCI/MUE scrubber and read the verdict. This panel makes no live request — the verdict is sandbox-shaped, never reported clean when an edit set could not run.
Appeal a claim by resubmitting it as a replacement (NUBC claim frequency type code 7) through the same sanctioned transport. The 837P is rebuilt with CLM05-3='7' and a loop-2300 REF*F8 carrying the original payer/clearinghouse claim control number, and stamped with the shteg.ai billing identity. A replacement must reference the claim it replaces: if there is no stored reference and none is supplied, the route returns 422.
Fail-closed. Returns 503 when the transport / clearinghouse identity is absent, and never fabricates an acknowledgment.
Name
Type
In
Required
Description
id
string
path
Required
Claim id being appealed.
originalClaimRef
string
body
Optional
Override the reference of the claim being replaced (defaults to the stored payer/clearinghouse ref).
No original claim reference to replace, or claim incomplete.
502
Transport threw during transmission.
503fail-closed
Clearinghouse transport / identity unconfigured. Fail-closed, zero network calls.
Remittance
Post an 835 ERA
POST
/api/claims/era-post
Ingest an 835 electronic remittance advice and auto-post it to the referenced claims via the reconciliation waterfall. Two authenticated entry paths share the route:
Signed inbound webhook. The clearinghouse-of-record POSTs the raw 835 (or { edi835, clinicId } JSON) with an X-Shteg-Signature header — a hex HMAC-SHA256 of the raw body under the signing secret issued to your organization. The signed body carries the clinic scope, so it cannot be tampered with independently.
Manual staff post. An authenticated staff member (scope claims:write) uploads an 835 from the dashboard; the posting is pinned to the caller's clinic and never trusts a body clinicId.
Fail-closed. If the signing secret is not configured, the signed path returns 503; a bad or absent signature is 401. An empty or invalid 835, or one with no resolvable claim references, is rejected — never counted as an invented acceptance. Posting is idempotent.
Invalid or absent HMAC signature on the signed path.
422
Body is not a valid 835, or no claim payments (CLP) found.
503fail-closed
ERA webhook signing secret not configured. Fail-closed on the signed path.
Eligibility
Verify eligibility (270/271)
POST
/api/eligibility/verify
scope: eligibility:read
Real-time insurance eligibility verification (X12 270/271). A live 270/271 runs under the practice's payer connections and returns insurance PHI, so the request is always scoped to your organization and pinned to a clinic-enrolled patient — patientId is mandatory. Results are cached for 24 hours, scoped to the exact clinic, patient, payer, and member. Use GET/api/eligibility/verify?patientId= to read the last cached 271.
Fail-closed. When the live payer credentials are absent in production, the route returns 503 eligibility_not_configured rather than fabricating "eligible" coverage that could let a claim or visit proceed on unverified insurance.
Name
Type
In
Required
Description
patientId
string
body
Required
Clinic-enrolled patient; required for the tenant + patient scope check.
firstName
string
body
Required
Subscriber first name.
lastName
string
body
Required
Subscriber last name.
dob
string
body
Required
Date of birth (YYYY-MM-DD).
memberId
string
body
Required
Insurance member id.
payerName
string
body
Required
Payer name (mapped to a payer id).
npi
string
body
Required
Rendering provider NPI.
payerId
string
body
Optional
Override the resolved payer / trading-partner id.
serviceType
string
body
Optional
Service type code ('30' vision, '5' diagnostic, '1' medical).
dos
string
body
Optional
Date of service (defaults to today).
Field
Type
Description
mode
string
'live' (real 271) — 'sandbox' is reachable in non-production only.
Invalid JSON or a missing required field (including patientId).
403
Patient not enrolled in the caller’s clinic, or missing eligibility:read.
404
GET only — no eligibility on file for the patient.
503fail-closed
Live payer credentials unconfigured in production. Fail-closed, no fabricated coverage.
These endpoints refuse loudly. They never fake success.
Every route here is a real path running on real logic in the sandbox. Where a transport or payer connection is unavailable, the endpoint returns a typed 503 with zero network calls — never a fabricated acknowledgment, remittance, status, or eligible coverage. No live money or live patient data is reachable from this tier; production access is a separate approval.