Stedi API Integration Guide: Access, Cost, Limits (2026)

Stedi is a US healthcare clearinghouse, a company that carries insurance transactions between providers and payers. Its eligibility API accepts JSON and converts it to X12, the standard format for US healthcare transactions, and a second API accepts X12 directly. The developer documents are public: 192 pages, 66 of which each describe one endpoint with its method and path.

This guide is for the product lead who has to decide on Stedi and for the engineer who will build on it. It lists every use case Stedi supports today, every documented endpoint, the published limits and the published prices. It also lists what Stedi leaves unpublished and what to ask before you commit. Last checked: Nov 14, 2026.

Stedi API at a glance

What can you build with the Stedi API?

You can build twelve things on Stedi today, from a real-time eligibility check to a full claim cycle with remittances. Each use case below is one documented capability, and each points to a row in the read and write table in section 6.

Build complexity is our own rating, and this guide gives no build estimate.

The Stedi use cases compared

Stedi's documents name more builds on the same endpoints. An eligibility response gives patient responsibility amounts, such as copays and deductibles. It also shows whether prior authorization is required for specific services. A stored claim can pre-fill a resubmission form. A billing agency can check the status of a claim that its provider customer submitted. Claims can go to secondary or tertiary payers, to payers that take only paper, and for atypical providers that have no NPI. An existing system that generates X12 files can connect over SFTP with no API integration. A revenue cycle workflow agent can validate coverage before scheduling or before a claim. For health systems, Stedi says it finds coverage for up to 60% of self-pay accounts from demographic data.

How do you get access to the Stedi API?

You sign up yourself on the Stedi portal and start with a free sandbox account. Production access is an upgrade inside the portal, where you set up multi-factor authentication and agree to a BAA.

The steps, in order

1. Sign up. The sign-up has three parts: a form, email confirmation and a company name. Stedi says it takes less than two minutes, needs no credit card and gives test API keys right away.
2. Build in the sandbox. A new account is a free sandbox account, limited to test mode. You build and test an eligibility integration with test API keys.
3. Upgrade to production. Click Upgrade account in the portal and follow the upgrade flow.
4. Set up MFA and accept the BAA. The upgrade makes you set up multi-factor authentication (MFA) and agree to a BAA. Once MFA is enabled for an account, it cannot be disabled.
5. Fund the account. On the pay-as-you-go plan you add a credit card and fund a starting balance of at least $25.
6. Create API keys. There are two types, test and production. Stedi shows a key once, at creation. A production key inherits the permissions of the member who created it and keeps them if that member's role changes. Keys do not expire automatically.
7. Enroll providers where the payer requires it. For 835 ERAs enrollment is always required. For other transactions it depends on the payer.

The BAA and who signs

The BAA is accepted through Stedi's online enrollment process or through an order form that references it. Stedi's service terms are accepted the same way. The pricing page lists a signed BAA as part of the pay-as-you-go plan. The Trust Center gives a second route, a request through the contact form. The current BAA is public and carries an effective date of Apr 14, 2025.

Stedi does not name a job title for the signer on the customer side. Decide inside your company who has the authority to accept a BAA before someone clicks through the upgrade.

Authority to sign payer forms

By submitting an enrollment request, the customer grants Stedi limited authority to complete, sign and submit payer enrollment forms. The customer can revoke that authority by written notice, and the revocation applies to the future only.

The Medicare attestation for each NPI

Medicare eligibility checks need one more step. Each provider completes an attestation with CMS, the federal agency that runs Medicare. Stedi cannot complete it for the provider, there is no bulk attestation across NPIs, and it takes about 5 to 15 minutes per NPI. After attestation the provider can send checks immediately, even if the enrollment status is not yet Live. Without it, CMS rejects the check with AAA error 41.

The US-only IP rule for Medicare checks

Stedi blocks eligibility requests to CMS when any IP address in the chain is outside the United States. That covers the originating address and every address in the X-Forwarded-For header. This matters for any team or server outside the United States.

A platform that calls Stedi on behalf of providers must collect the IP addresses of upstream requests and pass them in the X-Forwarded-For header.

Platforms: OAuth apps and integrated accounts

A software vendor can give each provider or practice its own Stedi account, with its own credentials. Stedi's example is an EHR that builds eligibility checks and claim submission into its own screens. The vendor's app connects to each account with the OAuth 2.1 authorization code flow and PKCE. OAuth is a standard way for an app to get a token to act in someone's account. New apps must use OAuth.

An app starts in development mode, unlisted, with at most 5 active installs. To lift the limit you submit the app for review, and after Stedi approves it you switch it to live mode. Customers can install an app only in a new Stedi account. Stedi does not publish the review criteria or how long the review takes.

The custom plan

Volume discounts, single sign-on, directory sync and consolidated billing sit on a custom plan, which you request by contacting Stedi.

What Stedi does not do

Stedi does not handle credentialing or payer enrollment, which providers complete directly with each payer or through a credentialing service. Transaction enrollment, which Stedi does handle, registers a provider to exchange specific transaction types with a payer.

Ask Stedi:

• Who on our side must accept the BAA and the service terms, and can we sign by order form?
• What are the review criteria for an OAuth app, and how long does review take?
• Which of our providers need the CMS attestation before go-live?

What does Stedi API access give you?

A sandbox account gives you test mode, mock eligibility checks, the portal and test API keys. A production account processes real transactions with payers and keeps test mode available.

What opens at each stage

Test mode

Test mode is a separate test environment inside the account. It holds no patient data and sends nothing to payers. Stedi decides whether a request is test or production from the type of API key.

Eligibility testing uses mock requests. These are predefined requests for well-known payers, and the page names Aetna, Cigna, UnitedHealthcare and CMS. They work with the JSON, raw X12 and SOAP endpoints. You cannot supply your own mock data or choose the payer.

Event destinations created in test mode receive only test events. Test transactions are free. Stedi applies fair use limits to test volume and can reject, throttle or disable traffic above them. The limits are not published.

Test claims

Test claims need a production account. Two workflows exist:

• Any payer, acknowledgment only. You submit a test claim to any payer and receive a test 277CA from Stedi.
• Stedi Test Payer, full cycle. Only test claims sent to the Stedi Test Payer generate a test 835 ERA. The provider must first be enrolled with the Stedi Test Payer, and that enrollment is made in production, not with a test key. Stedi sets it to Live within one minute. A prefix on the member ID, such as STEDI_DENIED_, selects the outcome.

New accounts can no longer mark a claim as a test inside production. They submit test claims with a test API key, test SFTP credentials or test mode in the portal.

People and roles

Admins assign account members to one of five roles. The portal requires every user to sign in again every 12 hours.

Support

Support requests go by email to support@stedi.com, and Stedi sets up a dedicated Slack or Teams channel on request. The pricing page lists support as free.

What are the ways to integrate with Stedi?

Stedi offers JSON APIs, raw X12 APIs, a SOAP endpoint, SFTP, events, the portal, an MCP server, SDKs and OAuth apps. Every REST call carries the API key in the Authorization header.

The "Fits when" column below is our reading.

Three notes on the table.

The event types cover transaction enrollment, file processing and OAuth apps. To learn about new 277CAs and 835 ERAs, a destination subscribes to the transaction.processed event type.

For a firewall allow list, Stedi publishes two static IP addresses for its SFTP server.

Every docs page is also offered in a form made for AI coding tools.

Want a second opinion on the route before you build? See our payer and clearinghouse integration service.

What can you read and write with the Stedi API?

The API reference documents 66 endpoints. Rows P1 to P25 below list every one with its method and path, and rows P26 to P28 cover functions that run through other routes.

Base addresses

Each path below sits under a base address with a dated version.

Which endpoints are new and which are legacy

Three groups of endpoints were announced on Sep 9, 2026: the redesigned JSON eligibility endpoint (row P1), the CMS-1500 professional claim endpoints (row P10) and the claim record endpoints (row P19). Stedi labels two endpoints "Legacy": the older JSON eligibility endpoint (row P2) and the older 837P JSON claim endpoint (the first path in row P11). Every other endpoint carries no such label.

The column "X12 transaction (our mapping)" is our reading of each reference page. Stedi does not print that column itself.

Functions with no endpoint of their own

Four functions run through the endpoints above.

• Secondary and tertiary claims use the legacy 837P JSON endpoint or the 837P raw X12 endpoint.
• Resubmitting or canceling a claim uses the claim endpoints with a claim frequency code that tells the payer the claim is an original, a replacement or a cancellation.
• Dental insurance discovery is the discovery endpoint with service type code 35.
• Enrollment requirements for each payer are fields on the payer record.

One reference page has no endpoint. It lists the mock requests for eligibility testing.

What is not possible with the Stedi API?

Stedi's documents show no 278 prior authorization endpoint. They also state limits on the new claim endpoint, on test mode and on ERA enrollment, and each one is listed below with its source.

No 278 prior authorization endpoint

The X12 278 is the transaction that requests a prior authorization from a payer. None of the 66 documented endpoints is for a 278. A keyword search of the 192 docs pages found one mention: the provider-facing test mode page lists "278 prior authorization" among the features that test mode does not support. No page says how to send a 278, and whether Stedi supports it at all is not answered in its public pages.

What the documents do offer is reading the benefit entries in an eligibility response to see whether prior authorization or a referral is required.

What the new CMS-1500 claim endpoint cannot do

• No secondary or tertiary claims. The Create Professional Claim JSON endpoint does not support coordination of benefits.
• No legacy webhooks and no PDF download by API. Stedi lists the endpoint as not compatible with legacy webhooks, programmatic PDF download, or secondary and tertiary claims.
• A shorter insurance type list. The endpoint uses a simplified subset of the X12 values.

Test mode gaps

• Test mode does not support transaction enrollment, Agentic Discovery, batch eligibility checks, insurance discovery, COB checks, real-time claim status, or custom mock data.
• Sandbox accounts cannot submit test claims through the API or SFTP.
• Real-time claim status checks run only for production claims that have entered the payer's system.
• Paper claims can be submitted in test mode, but Stedi does not generate the test acknowledgment that says a claim was mailed.
• Enrollment with the Stedi Test Payer cannot be submitted with a test API key or in test mode.
• Stedi warns against sending test checks for fake patients to live payers. Some payers, CMS in particular, prohibit it and can block access.

ERA enrollment is exclusive

ERA enrollment is exclusive to one clearinghouse. Switching a provider to Stedi stops ERA delivery through the previous clearinghouse. Stedi cannot cancel an enrollment that is in PROVISIONING or LIVE status.

Three more rules shape a migration. You can send claims through Stedi without enrolling for ERAs, and the ERAs keep going to your current clearinghouse. A few payers require the claim to go through the same clearinghouse as the ERA enrollment. Some payers enroll by tax ID, so enrolling one NPI moves every NPI under that tax ID to Stedi. Stedi says payers do not always disclose how they scope enrollment. For a staged move, Stedi describes routing rules that send your top 10 to 20 payers to Stedi and keep the rest on the existing clearinghouse.

What else the documents rule out

• No solicited attachments. Only unsolicited claim attachments go through the APIs and SFTP. Stedi does not say whether a payer's request for more documents reaches the customer through Stedi.
• No attachments to payers that do not support them. Stedi blocks the submission before it reaches the payer.
• No COB check for Medicare plans.
• No payer order from insurance discovery. Discovery cannot determine which payer is primary.
• No status for claims the payer has not accepted. Payers often archive claims older than 18 months.
• No bulk checks through the MCP server. Its OAuth sign-in supports email and password only, not single sign-on.
• No procedure code in a CSV batch upload. CSV uploads support fewer properties than the batch API.
• No dependents for most Medicaid plans.
• No edits to a submitted enrollment. Only enrollments in DRAFT status can be updated.
• No change of NPI or tax ID on a provider record.
• No OAuth app install into an existing Stedi account.
• No attachment format other than PDF on paper claims.
• No transaction a payer does not support. Some payers in the network do not support a given transaction type, and Stedi then returns an error.
• No transaction type other than claims and attachments over SFTP.
• No credentialing. Providers complete credentialing and payer enrollment with each payer.

Workers' compensation, auto and liability claims have a price on the pricing page. How to send them is not explained in Stedi's public pages.

The usual workarounds

• Prior authorization. Read whether it is required from the eligibility response. Submitting the request needs a route outside the documented API.
• Secondary claims. Build the legacy 837P JSON mapping or the raw X12 path beside the CMS-1500 endpoint.
• Moving without losing ERAs. Start claims at Stedi and leave ERAs where they are, payer by payer.
• A full test cycle. Send test claims to the Stedi Test Payer to get a test 835.
• A payer that takes only paper. Set the receiver ID to PAPER and Stedi prints and mails the claim.
• An unknown member or payer. Run insurance discovery as the backup.
• A duplicate or wrong claim. Cancel it with a cancellation claim.

What are the Stedi API limits?

Stedi publishes rate limits for two endpoint groups and concurrency limits for the real-time endpoints. A request over either kind of limit is rejected with HTTP 429.

Concurrency means the number of requests in flight at the same moment.

Published numbers

Retry rules for AAA 42 and 80

A payer rejects an eligibility check with an AAA error that carries a code and a follow-up action. Before a retry, check the follow-up action.

Three design points follow. Canceling and resending before Stedi's own retry period ends can create several live requests and use more of the concurrency limit. For a slow payer, Stedi describes request hedging: send a second request at a cutoff such as 30 seconds, without canceling the first. Batch checks do not count toward the real-time concurrency limit.

What Stedi does not publish about limits

• A per-second rate limit for eligibility, claim status, payers or events. The rate limit table has only the claims and enrollment groups.
• Payload size limits for a claim request or a batch request. A large 835 ERA can exceed the response size limit and return HTTP 413, and the page gives no number.
• How long eligibility checks, claims, acknowledgments and remittances stay retrievable. The Trust Center lists a data retention control by name only.
• The fair use limits in test mode.

Ask Stedi:

• What is the rate limit on the eligibility, claim status and payer endpoints?
• What is the largest request body and the largest 835 response you return?
• How long can we retrieve a claim, a 277CA and an 835 by API?
• What are the fair use limits on test traffic?

How much does the Stedi API cost?

Stedi publishes per-transaction prices with no monthly minimum, no per-provider fee and no per-payer fee. All prices below are the pay-as-you-go rates as published on Nov 14, 2026.

Tiers are by monthly volume, and each unit is billed at the price of the tier it falls into.

Tiered prices

Flat prices

What is free

• 277CA claim acknowledgments.
• The Transaction Enrollment API and the Payers API.
• The MCP server, test mode and support.
• Test transactions.
• A month with no transactions.

What is not billed

• Eligibility. Checks that return AAA 42 or AAA 80 errors.
• Claims and attachments. API calls that return 4xx or 5xx errors.
• Claim status. Responses that hold only claim status codes 484, 494, 667 or 689.

A bulk SFTP file is billed per claim inside it. A batch eligibility check costs the same as the equal number of real-time checks.

How you pay

Pay-as-you-go is prepaid. You add a credit card and fund a starting balance of at least $25. An automatic recharge can be set, with a trigger balance of at least $10.

When the balance reaches $0, access is suspended immediately and no new transactions are processed. Treat a failed recharge as a production outage risk. After 30 consecutive days suspended, the account becomes eligible for closure.

Custom pricing

Stedi says that at $1,000 or more a month you pay less on a custom plan, which includes volume discounts. Custom prices are not published.

On order-form contracts, past due invoices carry interest of the lesser of 1.5% a month or the legal maximum. Order forms renew automatically unless either side gives notice at least 30 days before the term ends.

Before pay-as-you-go pricing, which Stedi announced on Jun 1, 2026, API and SFTP access needed a plan with a $500 monthly minimum. Older accounts stay on their plan unless they ask to switch. Treat any page that still quotes a monthly minimum as out of date.

What Stedi does not publish about cost

• Custom plan prices and the size of the discount.
• Which payers add their own fees, and how much. Stedi says a small number do, and that it bills those fees at cost.
• Treasury payment processing fees.

Our clearinghouse API comparison also lists Stedi prices beside four other vendors. This guide carries the full dated table.

Ask Stedi:

• What are the custom plan rates at our volume?
• Which of our payers add a fee, and what is it?
• What does Treasury payment processing cost?

How long does a Stedi API integration take?

The account takes minutes and enrollment takes days. Stedi says most transaction enrollments complete within 24 to 48 hours, and some payers take up to 30 days.

Published times

The per-payer enrollment times are estimates, based on Stedi's operational data and payer rules.

What holds enrollment up

• Provider action. When a payer needs something from the provider, the enrollment waits in a provider-action status until the task is done.
• Credentialing. A rejection usually means the provider is not credentialed with the payer. Stedi puts credentialing at 90 to 180 days and payer enrollment at 60 to 120 days after that. Both happen outside Stedi.
• Drafts. Stedi does not process an enrollment until it is in STEDI_ACTION_REQUIRED status.
• Status email timing. Stedi checks for enrollment status changes once an hour.

One-click enrollment removes the wait for provider action: Stedi handles the whole process after the request. Stedi says one-click ERA enrollment covers 1,500+ payers.

What Stedi does not publish about time

Stedi does not publish how long an OAuth app review, a custom plan negotiation or a concurrency limit increase takes. The support page gives no committed response time. Support hours are not defined in public.

Stedi's product pages say "Onboard in a day" and describe a working insurance verification app in under 30 minutes with its tutorial and a coding agent. Neither figure includes transaction enrollment.

Ask Stedi:

• What is the expected enrollment time for each of our top payers, for ERAs and for eligibility?
• Which of our payers need provider action, and what do they ask for?
• How long does an OAuth app review take?

How do you build a Stedi API integration, step by step?

Stedi documents three build orders: an eligibility check, a claim from submission to remittance, and transaction enrollment. Each is below in the documented order, with Stedi's own sample requests.

(a) An eligibility check

1. Find the payer ID and check whether the payer needs enrollment. Use the Payer Network or the Payers API.
2. Enroll if the payer requires it. Submit an enrollment request for real-time eligibility checks.
3. Test with mock requests first. Stedi calls mock requests the best way to test real-time checks.
4. Call the eligibility endpoint. Send POST /eligibility-check on https://healthcare.us.stedi.com/2026-06-01. Stedi lists the minimum information each request body must hold.
5. Read the answer. Stedi recommends always starting with real-time checks when you integrate a new payer.
6. Retry only on payer connectivity failures. Stedi strongly recommends automatic retries for every request that fails because of payer connectivity.
7. Fall back to insurance discovery. Use it as a backup when a check fails or is not possible.

This is the sample request, copied from Stedi's eligibility guide.

curl --request POST \
  --url https://healthcare.us.stedi.com/2026-06-01/eligibility-check \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
      "payerId": "61101",
      "subscriber": {
        "dateOfBirth": "1975-05-05",
        "memberId": "HUMANA123",
        "name": {
          "person": {
            "firstName": "Jane",
            "lastName": "Doe"
          }
        }
      },
      "provider": {
        "name": {
          "organization": "Provider Name"
        },
        "npi": "1999999984"
      },
      "encounter": {
        "services": [
          {
            "value": "30",
            "system": "STC"
          }
        ]
      }
   }'

This is Stedi's shortest documented example of a response from the same endpoint, copied from its page on response shapes. It is not the answer to the request above: the payer ID differs, and Stedi prints the raw X12 value as three dots. The full sample response on the eligibility guide runs to 273 lines.

{
  "id": "ec_550e8400-e29b-41d4-a716-446655440000",
  "payerId": "87726",
  "payer": {
    "type": "PAYER",
    "name": { "organization": "HUMANA" }
  },
  "x12": "...",
  "subscriber": {
    "memberId": "123456789",
    "dates": {
      "plan": { "start": "2024-01-01" },
      "service": { "start": "2024-09-17" }
    }
  },
  "plans": [
    {
      "name": "Humana Gold Plan",
      "benefits": {
        "statuses": [
          {
            "status": "ACTIVE_COVERAGE",
            "coverageLevel": "EMPLOYEE_ONLY",
            "insuranceType": "PREFERRED_PROVIDER_ORGANIZATION_PPO",
            "network": { "indicator": "IN_AND_OUT_OF_NETWORK" },
            "service": {
              "system": "STC",
              "value": "30",
              "definition": "Health Benefit Plan Coverage"
            },
            "messages": ["Medicare PPO"]
          }
        ],
        "coPayment": [
          {
            "amount": "2000",
            "coverageLevel": "INDIVIDUAL",
            "insuranceType": "PREFERRED_PROVIDER_ORGANIZATION_PPO",
            "network": { "indicator": "IN_NETWORK" },
            "service": {
              "system": "STC",
              "value": "49",
              "definition": "Hospital - Room and Board"
            },
            "timePeriod": "ADMISSION",
            "messages": ["INPATIENT HOSPITAL ROOM AND BOARD"]
          }
        ]
      }
    }
  ]
}

Each check gets a Stedi ID in the form ec_ plus a UUID. The new JSON endpoint groups benefits under plans.

What to put in an eligibility request

• Patient data. The API requires at least one of member ID, date of birth or last name. When you supply member ID, date of birth, first name and last name, the payer must return a response if the member is in its database. Some payers require the member ID, and Stedi returns a warning when you leave it out for one of them.
• Provider name. A placeholder name in place of the provider's real name can make a payer return a limited set of benefits, or out-of-network benefits.
• Service date. With no date, the payer uses the current date in its own time zone. Stedi recommends dates up to 12 months in the past or up to the end of the current month.
• Names. Keep suffixes such as Jr. out of the first and last name properties.
• Provider PIN. Three payers named on the troubleshooting page require the provider's Medi-Cal PIN in the request.

(b) A professional claim, from submission to 277CA to 835

Stedi lists the steps below as its example API implementation.

1. Enroll the provider. Submit the required transaction enrollment requests through the Providers and Enrollments APIs.
2. Set up event destinations. Listen for the events Stedi emits when it processes new 277CAs and 835 ERAs. Subscribe to the transaction.processed event type.
3. Run a COB check. Stedi recommends one before submission so the claim goes to the correct payer.
4. Submit the claim. Call POST /professional-claim-submissions on https://claims.us.stedi.com/2025-03-07, or the legacy 837P JSON endpoint. Include an idempotency key in the Idempotency-Key header. An idempotency key is a value that makes a repeated request safe, so a retry does not send a second claim.
5. Fetch each 277CA. In the event, the transaction type tells a 277CA from an 835. Call GET /change/medicalnetwork/reports/v2/{transactionId}/277.
6. Fix and resubmit a rejected claim. If the 277CA shows a rejection, correct the errors and submit again.
7. Fetch the 835 ERA. Call GET /change/medicalnetwork/reports/v2/{transactionId}/835.
8. Match responses to the claim. The payer returns your patient control number in the 277CA and the 835. The claim record endpoints do the matching for you.
9. Check status when needed. Call the real-time claim status endpoint for claims that have entered the payer's system. Stedi's claim status page gives two waits before a first check: at least 2 to 3 days after submission, and at least a week after submission. Send only the data needed, because too much information in the request can hurt the results.

Without events, poll for transactions and start each polling window at least one day before your last processed transaction.

This is the sample request for the CMS-1500 endpoint, copied in full from Stedi's professional claims guide. It is the only sample request Stedi documents for this endpoint.

curl --request POST \
  --url https://claims.us.stedi.com/2025-03-07/professional-claim-submissions \
  --header 'Authorization: Key <YOUR-API-KEY>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 0e1f9a8d-6c5b-4a3f-9d2e-7b8c1a0f4e6d' \
  --data '{
  "purpose": "CHARGEABLE",
  "payer": {
    "id": "60054",
    "name": {
      "organization": "Aetna"
    }
  },
  "insured": {
    "memberId": "W123456789",
    "name": {
      "person": {
        "firstName": "June",
        "lastName": "Doe"
      }
    },
    "dateOfBirth": "1990-01-01",
    "gender": "FEMALE",
    "insuranceType": "OTHER",
    "paymentResponsibilityLevelCode": "PRIMARY",
    "address": {
      "addressLine1": "111 A Place",
      "city": "Somewhere",
      "postalCode": "123450000",
      "state": "IL"
    }
  },
  "patient": {
    "address": {
      "addressLine1": "111 A Place",
      "city": "Somewhere",
      "postalCode": "123450000",
      "state": "IL"
    },
    "dateOfBirth": "1900-02-02",
    "gender": "MALE",
    "name": {
      "person": {
        "firstName": "Liam",
        "lastName": "Doe"
      }
    },
    "relationshipToInsured": "CHILD"
  },
  "otherInsured": [
    {
      "address": {
        "addressLine1": "111 A Place",
        "city": "Somewhere",
        "postalCode": "123450000",
        "state": "IL"
      },
      "authorization": {
        "insuredAuthorizesAssignment": "YES",
        "patientReleasesMedicalInfo": "YES",
        "providerGeneratedPatientSignature": false
      },
      "claimFilingIndicator": "BLUE_CROSS_BLUE_SHIELD",
      "memberId": "BCBS-IL-554433221",
      "name": {
        "person": {
          "firstName": "Michael",
          "lastName": "Doe"
        }
      },
      "otherPayer": {
        "id": {
          "payerId": "00621"
        },
        "name": {
          "organization": "Blue Cross Blue Shield of Illinois"
        }
      },
      "planName": "BCBS PPO",
      "policyOrGroupNumber": "BCBS-GRP-3344",
      "relationshipToInsured": "SPOUSE",
      "responsibilityLevel": "SECONDARY"
    }
  ],
  "encounter": {
    "attachments": [
      {
        "attachmentControlNumber": "PWK-2026-0001",
        "reportTypeCode": "PROGRESS_REPORT",
        "transmissionCode": "ELECTRONICALLY_ONLY"
      }
    ],
    "claimCodes": [
      "AV"
    ],
    "claimNote": {
      "additionalInformation": "Patient presented with persistent cough and bronchospasm; treated in office."
    },
    "clinicalDates": {
      "hospitalization": {
        "end": "2026-03-06",
        "start": "2026-03-04"
      },
      "initialTreatment": "2026-03-03",
      "onsetOfCurrentIllness": "2026-03-02",
      "unableToWork": {
        "end": "2026-03-10",
        "start": "2026-03-03"
      }
    },
    "patientCondition": {
      "isAutoAccidentRelated": false,
      "isEmploymentRelated": false,
      "isOtherAccidentRelated": false
    },
    "primaryDiagnosisCode": "J0190",
    "priorReferringProvider": {
      "identifiers": {
        "npi": "1999999984"
      },
      "name": {
        "person": {
          "firstName": "John",
          "lastName": "Doe"
        }
      }
    },
    "referenceNumbers": {
      "clia": "14D2089999",
      "priorAuthorization": "PA-2026-11111",
      "referral": "REF-4321"
    },
    "referringProvider": {
      "identifiers": {
        "npi": "1999999984"
      },
      "name": {
        "person": {
          "firstName": "Jane",
          "lastName": "Doe"
        }
      }
    },
    "resubmission": {
      "code": "REPLACEMENT_OF_PRIOR_CLAIM",
      "originalReferenceNumber": "CLM-ORIG-998877"
    },
    "supervisingProvider": {
      "identifiers": {
        "npi": "1999999984"
      },
      "name": {
        "person": {
          "firstName": "Jane",
          "lastName": "Smith"
        }
      }
    }
  },
  "serviceLines": [
    {
      "procedureCode": {
        "code": "99213"
      },
      "lineItemChargeAmount": "100.00",
      "placeOfService": "11",
      "datesOfService": {
        "start": "2026-03-03",
        "end": "2026-03-03"
      },
      "diagnosisCodes": [
        "J0190"
      ],
      "units": "1"
    }
  ],
  "authorization": {
    "providerSignature": "ON_FILE",
    "providerAcceptsAssignment": "ASSIGNED",
    "insuredAuthorizesAssignment": "YES",
    "patientReleasesMedicalInfo": "YES"
  },
  "submitter": {
    "name": {
      "organization": "Test Submitter"
    },
    "etin": "TEST001",
    "contact": {
      "phoneNumber": "5555551234"
    }
  },
  "billing": {
    "billingProvider": {
      "name": {
        "organization": "Test Provider"
      },
      "identifiers": {
        "npi": "1999999984",
        "taxonomyCode": "207Q00000X"
      },
      "address": {
        "addressLine1": "123 St",
        "city": "City",
        "state": "IL",
        "postalCode": "12345"
      }
    },
    "taxId": {
      "ein": "123456789"
    },
    "patientControlNumber": "TEST-004",
    "totalCharge": "100.00"
  }
}'

The sample sends the key as Authorization: Key <YOUR-API-KEY>. Stedi supports that prefix for backward compatibility.

The response carries a claim ID that stays the same for the claim's whole life cycle.

If you send raw X12 or use SFTP

• Name the implementation guide. For a professional claim, ST03 must be 005010X222A1.
• Match the envelope to the SFTP user. ISA08 is STEDITEST for test claims or STEDI for production claims.
• Give each claim a unique GS06. Without it you cannot tell which claim was rejected.
• Expect one claim per transmission to the payer. Stedi splits a bulk 837 into single claims and sends each one separately.
• Watch for 999 files. Stedi returns a 999 within minutes of the file submission. Without that check, a claim or attachment can fail silently, because Stedi does not send rejected transactions to the payer.

(c) Transaction enrollment

1. Create a provider record. Call POST /providers.
2. Create one enrollment request per transaction type. Call POST /enrollments for each provider, payer and transaction type. Each request needs a primary contact, where the payer sends communications about the enrollment.
3. Submit it. A request can sit in draft. Stedi processes it only in STEDI_ACTION_REQUIRED status.
4. Wait for provisioning. When Stedi begins the process with the payer, it sets the status to PROVISIONING.
5. Complete any task. If the payer needs something from the provider, the status becomes PROVIDER_ACTION_REQUIRED and a task appears with instructions. Complete it in the portal or with POST /tasks/{taskId}.
6. Go live. Once approved, the status is LIVE and the provider can exchange the enrolled transactions.
7. Listen for enrollment events. Stedi emits an event when an enrollment is set to LIVE.

For many providers at once, the portal imports enrollment requests from a CSV file. A group that bills under one NPI and tax ID does not need separate requests for individual rendering providers. Providers with no NPI use the placeholder 1999999984.

Which Stedi API quirks should you know?

Eighteen details from Stedi's documents can change a design or a test plan. Each one below carries its source.

What should you check before you sign with Stedi?

Check four things before you sign: consent, security, testing and support. Then put the ten questions at the end of this section to Stedi in writing.

Consent

A claim carries indicators for whether the provider has the patient's and the insured's authorizations on file. Stedi's public pages give no guidance on patient consent for eligibility checks or insurance discovery. Under the service terms, the customer has sole responsibility for the accuracy, quality and legality of the data it sends.

Security and compliance

Stedi's statements about itself, as it publishes them:

• Stedi states that it is HITRUST r2 certified, SOC 2 Type II compliant and HIPAA compliant. It announced the HITRUST r2 certification on Jun 19, 2026.
• The Trust Center lists HITRUST r2, SOC 2 Type II, SOC 1 Type II, HIPAA and CAQH Core under compliance. The reports sit behind an access request. It also lists a penetration test report.
• Under the BAA, Stedi reports a security incident involving patient data within five business days. It reports a breach within five business days of determining that one occurred.
• Subcontractors that handle patient data enter a written agreement. The public pages do not name them, or the hosting regions.
• At the end of the BAA, Stedi keeps no copies of patient data and can keep de-identified data.
• The BAA allows data analysis to review, improve or validate a product, feature or service.
• Stedi can end the BAA on 90 days' written notice.
• Stedi says it runs entirely on AWS, across more than one region. The APIs sit behind the AWS web application firewall. Stedi says it offers redundant connections with automatic failover where possible.

Service terms that affect a production system:

• The uptime commitment is 99.9% a month, on a commercially reasonable efforts basis. Only 500 and 503 responses count as errors. Outages at payers or external clearinghouses are excluded. Service credits run from 10% to 100% of the month's fees by uptime band, and must be claimed by opening a case.
• Liability for direct damages is capped at the fees paid in the 12 months before the event.
• The service terms carry an effective date of Sep 9, 2026.

Your own duties:

• Rotate API keys yourself, because they do not expire. Event signing secrets can be rotated with an overlap period.
• Keep patient data out of support requests, screenshots included.
• Stedi advises against Postman for requests that hold patient data.

Testing

Build against mock requests and test claims before any live traffic. Do not send invented patients to live payers. Breaking changes come as a new dated version, so pin the version in your base address.

Support

Support runs by email and by a dedicated Slack or Teams channel. The support page promises a response as soon as possible and no fixed time. The status page has four components and publishes no historical uptime figure.

What named companies document about their own Stedi integrations

These are statements by each company about its own product. None is a statement by Stedi.

• Medplum documents that it integrates with Stedi for billing and revenue cycle workflows. It documents that its claim integration supports professional claims only. It documents that its integration receives claim responses by webhook, with an optional poller as a safety net. It documents that its processing is idempotent on the Stedi transaction ID, not the webhook event ID. It tells its own users to test with its sample data, because the sandbox validates only a few payloads. Stedi's test mode page agrees that mock requests are predefined.
• Candid Health documents that it is deprecating its Availity eligibility endpoint and recommends its own Stedi passthrough endpoint.
• Scalekit documents that its Stedi connector for AI agents has 17 tools.
• Medi states that its product routes claims, eligibility and ERAs through Stedi.

Questions to ask Stedi before you sign

1. Do you support the 278 prior authorization transaction, and if so, through which route?
2. How do we send workers' compensation, auto and liability claims, and to which payers?
3. Does a payer's request for more documents reach us through Stedi, and how do we answer it?
4. What are the rate limits on the eligibility, claim status, payer and event endpoints?
5. How long do you keep eligibility checks, claims, 277CAs and 835s, and how do we export them if we leave?
6. What are the custom plan prices at our volume, and which payers add their own fees?
7. Which of our payers need the claim and the ERA at the same clearinghouse, and which enroll by tax ID?
8. What are your support hours, and is there a committed response time?
9. Where is our data hosted, and who are your subcontractors?
10. Do you detect a duplicate claim when no idempotency key is sent?

Next step

Planning a Stedi API integration? We scope the route, the access steps and the build with you. Start at our payer and clearinghouse integration service.