Stedi home page
Docs

Create Professional Claim (CMS-1500) JSON

Submit a professional claim in JSON modeled after the CMS-1500 form structure

POST/professional-claim-submissions

Submit 837P professional claims to payers using a JSON request structure that follows the CMS-1500 paper form layout.

This endpoint is especially useful if you want to build a CMS-1500 form interface in your application. It's also useful when you're building an integration using AI agents, which are likely familiar with the data fields and requirements of the CMS-1500 form.

  1. Call this endpoint with a JSON payload.
  2. Stedi runs our suite of edits and repairs on the claim data. On success, Stedi translates the request to the X12 837 EDI format and sends it to the payer.
  3. The endpoint returns an HTTP 201 whether Stedi's edits pass or fail. Monitor the response shape for failures:
    • Success: The endpoint returns only a claimId and submissionId when the claim passes Stedi's edits.
    • Failures: The endpoint also returns an errors array when the claim fails one or more of Stedi's edits. Address all issues before resubmitting.

When a claim fails edits, Stedi stores it with status REJECTED and displays it on the claims view in the Stedi portal. You can use the submissionId to retrieve the data with the Retrieve Professional Claim JSON endpoint.

This endpoint isn't compatible with webhooks (legacy), programmatic PDF download, or secondary and tertiary claims. Visit Submit professional claims for details.

Authorizations

Authorization
RequiredHeader

A production Stedi API Key for authentication.

Headers

Idempotency-Key
StringLength: 1 - 255

A unique string to identify this request to the server. You can safely retry requests with the same idempotency key within 24 hours of making the first request. This prevents you from sending duplicate claims due to network errors or other intermittent failures. If you reuse a key on a new request while Stedi is still processing the original, Stedi returns a 409 Conflict error. Learn more.

Body

application/json
authorization
ObjectRequired

[CMS-1500 Box 12, 13, 27, 31] Signature and assignment-of-benefits indicators for the claim, covering whether the provider has the patient's and insured's authorizations on file and whether the provider accepts the payer's terms.

Show attributes
billing
ObjectRequired

[CMS-1500 Box 25, 26, 28, 29, 32, 32a, 32b, 33, 33a, 33b] Billing details for the claim, including the billing provider, service facility, tax identification, and total charges.

Show attributes
encounter
ObjectRequired

[CMS-1500 Box 10a, 10b, 10c, 10d, 14, 15, 16, 17, 17a, 17b, 18, 19, 21, 22, 23, 24h] Clinical details about the encounter, including diagnosis codes, the related providers, relevant dates, and supporting information for the claim.

Show attributes
insured
ObjectRequired

[CMS-1500 Box 1, 1a, 4, 7, 11, 11a, 11b, 11c] The person who carries the insurance policy being billed. The insured is also called the subscriber, primary policyholder, or primary cardholder, and may be a different person from the patient. For example, when a spouse or child receives care under an employee's plan, the employee is the insured.

Show attributes
otherInsured
Array of ObjectsMax items: 10

[CMS-1500 Box 9, 9a, 9d] Coverage the patient holds under another insurance policy, relevant to coordination of benefits. Include this when the patient has coverage from another payer in addition to the one you're billing.

Array item
patient
Object

[CMS-1500 Box 2, 3, 5, 6] The person who received care. Only include this object when the patient is someone other than the insured, such as a spouse or dependent on the insured's plan. When the patient is the insured, leave this empty.

Show attributes
payer
ObjectRequired

[CMS-1500 Carrier Block] The payer being billed for this claim, identified by a Stedi payer ID. Visit the Payer Network for a complete list of payers and their IDs.

Show attributes
purpose
StringRequired

[CMS-1500 Carrier Block] The purpose of the submission. Use CHARGEABLE for standard fee-for-service claims, which covers most submissions.

Possible values
SUBROGATION_DEMAND
CHARGEABLE
REPORTING
serviceLines
Array of ObjectsRequiredItems: 1 - 50

[CMS-1500 Box 17, 17a, 17b, 20, 24a-24j] The individual services, procedures, or supplies being billed. Each service line corresponds to one row in Box 24 of the CMS-1500 form.

Array item
submitter
ObjectRequired

[CMS-1500 Carrier Block] The entity submitting the claim to Stedi.

Show attributes

Response

application/json
claimId
StringRequiredRegex pattern: ^(clm_)?[0-7][0-9A-HJKMNP-TV-Z]{25}$

A unique identifier for the claim within Stedi. This ID stays the same throughout the claim's entire lifecycle. For example, the claim ID is the same for the initial submission and any resubmissions. This is how Stedi links a particular claim to responses, such as 277CA claim acknowledgments.

errors
Array of Objects

Failed claim edits that caused Stedi to reject the claim.

  • When present, Stedi stored the claim and generated a 277CA claim acknowledgment for the rejection, but didn't send the claim to the payer. You must fix all errors before resubmitting.
  • When absent, the claim data passed Stedi's edits and Stedi sent the claim to the payer.
Array item
submissionId
StringRequiredMax length: 40

A unique identifier for a specific submission of a claim within Stedi. Stedi generates a submission ID for the initial submission and then a new submission ID for every resubmission of the same claim. This is different from the claim ID, which doesn't change throughout the claim's lifecycle.

Validate Professional Claim JSON
Retrieve Professional Claim JSON