POST
/
change
/
medicalnetwork
/
professionalclaims
/
v3
/
submission

This endpoint sends 837P (professional) claims to payers. Visit Submit professional claims for a full how-to guide.

  • Call this endpoint with a JSON payload.
  • Stedi translates your request to the X12 837 EDI format and sends it to the payer.
  • The endpoint returns a response from Stedi in JSON format containing information about the claim you submitted and whether the submission was successful.

Send test claims

All claims you submit through this endpoint are sent to the payer as production claims unless you explicitly designate them as test data.

To send test claims, set the usageIndicator field in the test claim to T. This allows you to filter for test claims on the Transactions page in the Stedi app.

Note that you will receive a 277 Claim Acknowledgment in response to test claims, allowing you to test your workflow end to end, but you will not receive a test 835 (ERA) response.

Basic claim submission

The content of your claim submission depends on your use case and the payer’s requirements. However, a basic claim submission includes the following information in the request body:

InformationDescription
tradingPartnerServiceIdThis is the Payer ID. Visit the Payer Network for a complete list.
tradingPartnerNameThis is the payer’s business name, like Cigna or Aetna.
submitter objectInformation about the entity submitting the healthcare claim. This can be either an individual or an organization, such as a doctor, hospital, or insurance company.
receiver objectInformation about the payer, such as an insurance company or government agency.
subscriber and/or dependent objectsInformation about the patient who received the medical services. Note that if a dependent has their own, unique member ID for their health plan, you should submit their information in the subscriber object and omit the dependent object from the request. You can check whether the dependent has a unique member ID by submitting an Eligibility Check to the payer for the dependent. The payer will return the member ID in the dependents.memberId field, if present.
claimInformation objectInformation about the claim, such as the patient control number, claim charge amount, and place of service code. It also includes information about each individual service line included in the claim.
billing objectInformation about the billing provider, such as the NPI, taxonomy code, and organization name.

Character restrictions

Don’t include the following characters in your request data: ~, *, : and ^. They are reserved for delimiters in the resulting X12 EDI transaction, and X12 doesn’t support using escape sequences to represent delimiters or special characters. Stedi returns a 400 error if you include these restricted characters in your request.

Only use the X12 Basic and Extended character sets in request data. Using characters outside these sets may cause validation and HTTP 400 errors.

Identify service lines

A claim can contain multiple service lines. Since the payer may accept, reject, or pay a subset of those lines, you can receive an 835 response that references a patientControlNumber, but only pertains to some of the service lines.

However, the claimInformation.serviceLines.providerControlNumber serves as a unique identifier for each service line in your claim submission. This value appears in the 277CA and 835 ERA responses as the lineItemControlNumber, allowing you to correlate these responses to specific service lines from the original claim. If you don’t set the providerControlNumber for a service line, Stedi uses a random UUID.

Stedi returns service line identifiers in the claimReference.serviceLines object of the synchronous API response.

Conditional requirements

Note that objects marked as required are required for all requests, while others are conditionally required depending on the circumstances. When you include a conditionally required object, you must include all of its required properties.

For example, you must always include the subscriber object in your request, but you only need to include the supervising object when the rendering provider is supervised by a physician.

Enhanced validation

You can optionally set the Stedi-Validation header to snip for enhanced validation on your claim submission.

Enhanced validation uses hundreds of additional edits (the industry term for validation rules) to increase claim acceptance rates. These include Strategic National Implementation Process (SNIP) validations. Stedi also automatically fixes common errors and monitors payer rejections to proactively build out new rules.

There is an additional cost per claim submission when you use enhanced validation. Please reach out to support for access and pricing information.

Authorizations

Authorization
string
headerrequired

A Stedi API Key for authentication.

Headers

Stedi-Transaction-Setting-Id
string

The outbound transaction setting ID. This option only needs to be specified if a non-default release of the Professional Claims guide needs to be used.

Stedi-Validation
string

Set to snip for enhanced validation on this claim. Enhanced validation uses hundreds of additional 'edits' (the industry term for validation rules) to increase claims acceptance rates. Stedi also monitors your 277 rejections to proactively build rules based on previous failures. When possible, Stedi automatically fixes common errors (such as invalid date/time formats and character encoding issues) before sending the claim, reducing payer rejections. There is an additional cost per claim submission when you use enhanced validation. Please reach out to support for access and pricing information.

Body

application/json
tradingPartnerServiceId
string
required

This is the Payer ID. Visit the Payer Network for a complete list. You can send requests using the Primary Payer ID, the Stedi Payer ID, or any alias listed in the payer record.

Minimum length: 1
submitter
object
required

The entity submitting the healthcare claim. This can be either an individual or an organization, such as a doctor, hospital, or insurance company. You must submit at least organizationName or lastName properties and the contactInformation object. If you don't supply the submitterIdentification property, Stedi uses the value from billing.npi in the request.

receiver
object
required

The entity responsible for the payment of the claim, such as an insurance company or government agency.

subscriber
object
required

The person or entity who is the primary policyholder for the health plan or a dependent with their own member ID. The subscriber can be an individual or a business entity.

  • When a dependent has a unique, payer-assigned member ID, treat them as the subscriber for the claim submission - include their information here and omit the dependent object from the request. Stedi treats the subscriber as an individual when the request doesn't contain a value for the subscriber.organizationName property.
  • You can only set the dateOfBirth and gender properties when the subscriber is the patient. Stedi determines that the subscriber is the patient when the dependent object is not included in the request.
  • If either dateOfBirth or gender is set, you must include both properties. You can either include both properties or neither within a single request.
claimInformation
object
required

Information about the healthcare claim. Note that the objects and properties marked as required are required for all claims, while others are conditionally required, depending on type of claim and claim circumstances. For example, you must always provide the patient's diagnosis codes in the healthCareCodeInformation object, but you only need to provide the otherSubscriberInformation object in coordination of benefits scenarios. When you include a conditionally required object, you must provide all of its required properties.

billing
object
required

Information about the billing provider. For tax identification, you must include either the provider's Social Security Number (SSN) or their Employer Identification Number (EIN), but not both.

controlNumber
string

Not currently used.

dependent
object

Dependent who received the medical care associated with the claim. Note that if the dependent has their own member ID for the health plan, you should include the dependent's information in the subscriber object instead. To check whether a dependent has a member ID, submit an Eligibility Check to the payer. The payer returns the dependent's member ID in the dependents.memberId property in the response, if present.

providers
object[]
deprecated

Deprecated; please set all providers individually by type. For example, Referring. This shape is deprecated.

payToAddress
object

Use when the address for payment is different than that of the billing provider for this claim.

payToPlan
object

Use for subrogation payment requests. If you include this information, you must also set the claimInformation.otherSubscriberInformation.payerPaidAmount to the amount the payer (for example, Medicaid) actually paid.

payerAddress
object
usageIndicator
string

Whether you want to send a test or production claim. This property also allows you to filter claims in the Stedi app by production or test data. By default, this property is set to P for production data. Use T to designate a claim as test data.

referring
object

Information about the provider who directed the patient to the rendering provider for care. For example, a primary care physician may refer patients to a specialist. Use when the referring provider applies to the entire claim, not just a specific service line.

rendering
object

Information about the person or company (laboratory or other facility) who rendered the care. Use this object for all types of rendering providers including laboratories. When a substitute provider (locum tenens) was used, enter that provider's information here. Use when the provider applies to the entire claim, not just a specific service line.

ordering
object
deprecated

Deprecated; please use claimInformation.serviceLines.orderingProvider instead. This shape is deprecated.

supervising
object

The entity responsible for overseeing the rendering provider and the care reported in this claim. Applies when the rendering provider is supervised by a physician. Use when the provider applies to the entire claim, not just a specific service line.

tradingPartnerName
string

This is the payer's business name, like Cigna or Aetna.

Response

200 - application/json
status
string

The status of the claim submission.

controlNumber
string

An identifier for the transaction.

tradingPartnerServiceId
string

An ID for the payer you identified in the original claim. This value may differ from the tradingPartnerServiceId you submitted in the original request because it reflects the payer's internal concept of their ID, not necessarily the ID Stedi uses to route requests to this payer.

claimReference
object

Information about the claim.

errors
object[]

A list of errors. Currently not used.

httpStatusCode
enum<string>

A 200 response indicates that Stedi successfully generated the X12 EDI claim format required by the payer. It does not indicate whether the payer has accepted the claim - the payer will respond later with a 277CA containing this information. Learn more about 277CAs. A 400 response indicates one or more problems with the claim data in the request. Examples include missing required fields, invalid values, or incorrect data types. The response includes a message describing the problem.

Available options:
200 OK,
400 BAD_REQUEST
meta
object

Metadata from Stedi about the request.

editStatus
string

Currently not used.

editResponses
object[]

Currently not used.

payer
object

Information about the payer for the submitted claim.

failure
object

Currently not used.