Skip to main content

Stedi

Stedi is an App Connection with multiple practice accounts per workspace. Each account authorizes the platform's OAuth app. Access and rotating refresh tokens are encrypted on the workspace connection; client credentials remain global to the deployment. A Stedi account cannot be attached to a second workspace.

Connection lifecycle​

The base path is /api/v2/w/{workspace_uuid}/app-connections/stedi.

Method and pathScopeResult
GET /statusapps:readList connections and setup state.
POST /installapps:adminCreate a connection with an optional name.
GET /{connection_uuid}/statusapps:readRead one connection's state.
POST /{connection_uuid}/configureapps:admin and medical_billing:admin for provider changesSelect a native billing provider.
POST /{connection_uuid}/oauth/startapps:adminSend {} and follow the returned authorizeUrl.
POST /{connection_uuid}/disconnectapps:adminSend {} to remove the local grant.

The global callback validates signed, single-use state and S256 PKCE, checks the initiating Member's current permissions, and binds the returned account. Connection responses use the common id, uuid and connectionType fields and expose setup indicators, never tokens or the billing tax ID value. Installed Stedi connections also appear in GET /api/v2/w/{workspace_uuid}/app-connections. Disconnect retains the account identity and historical records. An invalid refresh grant requires reauthorization.

Stedi currently supports OAuth installation into new accounts and has no OAuth Test mode. Existing-account onboarding requires vendor confirmation. The initial build has no live account validation; platformAppAvailable remains false until platform credentials are configured.

Connector operations​

The Connector Operation action selects an installed Stedi connection. Member operations require medical billing scopes and access to the Current Member.

OperationParameters
stedi.eligibility_checkcoverageId?, providerId?, serviceDate? as YYYY-MM-DD.
stedi.submit_claimcoverageId?, providerId?, chargeIds?, claimId?, submissionId?, preview? (default true), required insuranceType and authorization, optional renderingProviders.
stedi.claim_statusclaimId — the native claim UUID.
stedi.list_open_denialslimit? from 1–100, after? as a native claim UUID cursor.
stedi.payer_visibilitystediId, providerId?, pageToken? for enrollment pagination.
stedi.set_payer_routecoverageId, stediId.

insuranceType accepts MEDICARE, MEDICAID, TRICARE, CHAMPVA, FECA_BLK_LUNG or OTHER. The required authorization object carries facts from your billing process:

{
"insuranceType": "MEDICARE",
"authorization": {
"insuredAuthorizesAssignment": "YES",
"patientReleasesMedicalInfo": "YES",
"providerAcceptsAssignment": "ASSIGNED",
"providerSignature": "ON_FILE"
},
"preview": true
}

This example illustrates structure; it does not establish consent or assignment. Accepted values are:

FieldValues
insuredAuthorizesAssignmentYES, NO, NOT_APPLICABLE
patientReleasesMedicalInfoYES, INFORMED_CONSENT
providerAcceptsAssignmentASSIGNED, NOT_ASSIGNED, CLINICAL_LAB_ONLY
providerSignatureON_FILE, NOT_ON_FILE

For charges with a rendering NPI, renderingProviders maps each NPI to {"firstName": "...", "lastName": "..."}. The provider's actual name is required; the billing entity's name is not a substitute.

Previews return IDs, line count and status. They do not transmit PHI or reserve charges. Reuse the returned claimId and submissionId for submission with preview: false. A claim identifies the frozen billing record; a submission identifies its transmission. Detailed eligibility and payment values stay in the native medical billing domain. Denial pagination returns count, claims, hasMore and nextAfter; continue while hasMore is true.

Sources and submission safety​

Native coverage and charges belong to the workspace's medical billing domain. Coverage uses a destination-specific payer route; Claim.MD payer IDs do not identify Stedi payers. Billing provider identity belongs to the workspace and can be selected by either adapter.

Before a real request, the connector commits charge reservations, a claim with frozen service lines and a submission containing the exact request, version, digest, control number and idempotency identity. The database prevents active charge reservations from overlapping across clearinghouses. Acceptance retains the hold. Confirmed submission rejection releases it. Uncertain outcomes remain held for reconciliation. Payer adjudication is a separate state.

Stedi's idempotency window is finite. An uncertain existing submission requires reconciliation; the connector does not blindly rebuild or resend it after the window. Domain operations reject edits to reserved charges.

Read clinical records through /api/v2/w/{workspace_uuid}/medical-billing. Coverage and charge identifiers name native entities, not Form records. The non-PHI payers Directory remains available through the connector catalog.

Events and reconciliation​

Healthcare events use POST /webhooks/stedi/events/{workspace_uuid}/{connection_uuid}. Verification uses the exact body, Standard Webhooks signature, configured destination and account. A durable receipt commits before acknowledgment. Duplicate deliveries reuse the same receipt. If immediate processing cannot start, the receipt remains available for the periodic recovery pass.

Reconciliation uses the authenticated Events API and independently revisits local claims. Account and grant generation are checked again before writes. Matched 835 service lines upsert deterministically; missing amounts remain unknown. The connector never matches a payment to a Member by name. Unmatched or ambiguous claim identities require investigation rather than guessed writes.

Developer-account installation/uninstallation events are a separate Stedi surface and are not accepted by practice healthcare ingress. Live account setup must verify actual signatures, OAuth refresh and report correlation. Event history gaps beyond vendor retention require explicit recovery review.