Stedi home page
Docs

Submit professional claims - API

You can submit 837P professional claims programmatically through Stedi using JSON or X12 EDI. You can also submit claims manually through the Stedi portal, through SFTP, or as paper claims.

Once you send a claim, Stedi automatically receives and processes 277CA claim acknowledgments and 835 Electronic Remittance Advice (ERA) responses.

Before sending claims

You may need to complete the following steps before sending claims.

Transaction enrollment

Transaction enrollment is the process of registering a provider to exchange specific healthcare transactions with a payer. Some payers require enrollment before allowing providers to submit 837 claims through a new clearinghouse.

You can check whether a specific payer requires transaction enrollment for 837 claims in the Payer Network or through the Payers API.

To enroll, complete the following steps:

  1. Create a provider record with the information required for enrollment. If you already have a record for the provider, you can skip this step. Stedi portal | API endpoint
  2. Submit an enrollment request for the claim type. Stedi portal | API endpoint

For most payers that require enrollment for claim submission, enrolling through Stedi won't impact your ability to send transactions to your original clearinghouse. Only a few payers require the 837 claim to be sent to the same clearinghouse as the 835 ERA enrollment. For any questions on payer nuances, contact Stedi's support team.

Best practices

  • Leverage batch enrollments when onboarding new provider groups or many providers at a time.
  • For ERAs, you can only be enrolled through one clearinghouse at a time per payer per provider. When your ERA enrollment is accepted through Stedi, you'll stop receiving ERAs through the previous clearinghouse. Every other transaction type accepts enrollment through more than one clearinghouse.

Coordination of benefits check

We recommend running a coordination of benefits (COB) check to ensure you submit claims to the correct payer. COB checks can help you determine:

  • If a patient is covered by more than one health plan
  • Whether coverage overlap requires coordination of benefits
  • Each payer's responsibility for payment (primacy) in coordination of benefits scenarios

Visit Coordination of benefits (COB) checks for more information.

Test claims

Stedi sends all API claim submissions as production claims unless you explicitly designate them as test data. Visit Test claim workflows for complete instructions on sending test claims and receiving test responses.

Submit professional claims

Call one of the following endpoints to submit 837P professional claims. The JSON endpoints translate your request to X12 837 EDI format before sending to the payer. All endpoints return a synchronous response from Stedi in JSON format, and the payer later responds with a 277CA claim acknowledgment.

EndpointDescription and when to use
Create Professional Claim JSONUses a JSON structure that mirrors the CMS-1500 paper form layout, making it intuitive for developers and AI agents. Use cases:
  • Build a CMS-1500 form interface in your application.
  • Build an integration with AI agents that are likely to be more familiar with the CMS-1500 form's structure.
  • Use event destinations for claim responses.
  • Use Stedi's TypeScript or Python SDKs.
Not compatible with: Webhooks, programmatic PDF download, or secondary and tertiary claims.
837P JSON (Legacy)Uses an X12-based JSON structure that maps directly to the 837P transaction. Use cases:
  • Submit claims to secondary or tertiary payers (coordination of benefits).
  • Submit complex claims that include X12 fields not typically available in the CMS-1500 form.
  • Use webhooks or programmatic PDF download.
837P Raw X12Accepts raw X12 837P EDI format. Use cases:
  • You already have X12 claim data from another system.
  • You need complete control over every X12 segment and element.

Headers

When constructing the request, you must include the following information in HTTP headers:

  • Authorization: Generate an API key to use for authentication. Use a test API key when submitting test claims.
  • Content-Type: Set to application/json.

Idempotency key

We strongly recommend including an idempotency key in the Idempotency-Key header to prevent sending duplicate claims to payers in the case of network errors or other intermittent failures. You can safely retry requests with the same idempotency key as many times as necessary within 24 hours after making the first request.

Body - JSON

The information you submit for a claim depends on your use case. Refer to the Create Professional Claim JSON endpoint for a complete list of properties. However, all claims require the following high-level information:

InformationDescription
purpose objectThe purpose of the submission. Use CHARGEABLE for standard fee-for-service claims, which covers most submissions.
payer objectInformation about the payer, including the payer ID and business name. The payer ID can be the primary payer ID, the Stedi payer ID, or any alias listed in the payer record. Visit the Payer Network for a complete list.
insured objectInformation about the insured person (policyholder). If the patient is a dependent with their own unique member ID, include their information here and omit the patient object. You can check whether the dependent has a unique member ID by submitting an Eligibility Check to the payer.
patient object (conditional)Information about the patient when they are someone other than the insured. See Patient versus insured for details.
encounter objectInformation about the medical encounter, such as diagnosis codes.
serviceLines arrayInformation about each individual service line included in the claim, such as procedure codes, charges, and dates of service.
authorization objectSignature 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.
submitter objectInformation about the entity submitting the claim. This can be either an individual or an organization, such as a doctor, hospital, or billing service.
billing objectInformation about the billing provider and claim details, including the patient control number, total charge, and billing provider details such as NPI.

Patient Control Number

You must submit a Patient Control Number (PCN) with each claim. The payer returns this value in related transactions, such as the 277CA claim acknowledgment and 835 Electronic Remittance Advice (ERA), so you can correlate responses and real-time claim status checks with the original claim.

When assigning a PCN, follow these best practices:

  • Use a unique PCN for each claim. The identifier should be more complex than a simple sequential number and should be hard to guess.
  • Use random strings. Formats with patient initials or the date of service in them can create duplicates. We recommend using nanoid or a similar library configured with the characters available in the basic character set to create a strong, unique 17-character PCN for each claim.
  • Keep it 17 characters or less. Some payers cut off values longer than 17 characters in ERAs and claim acknowledgments, which makes it hard to match them with the original claim.
  • Use only characters available in the basic character set, and avoid special characters that are only available in the extended character set. Payers are permitted to return data using the basic character set. Using other characters may result in data loss or mismatches when correlating claims with responses.
  • Treat PCN values as case-insensitive when matching transactions, even if the submitted value included both lower and uppercase characters.

Service line identification

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 ERA that references a patient control number but only pertains to some of the service lines.

You can set a provider control number as a unique identifier for each service line in your claim submission. This value appears in the 277CA claim acknowledgment and 835 ERA as the lineItemControlNumber, allowing you to correlate these responses to specific service lines from the original claim. If you don't set the provider control number for a service line, Stedi uses a random UUID.

Patient versus insured

This section applies to the Create Professional Claim JSON endpoint.

The insured (subscriber) is the person who holds the insurance policy. The patient is the person who received care. These may be the same person or different people:

  • When the patient is the insured: Only include the insured object. Leave the patient object empty.
  • When the patient is a dependent: Include both the insured object (with the policyholder's information) and the patient object (with the dependent's information).

Special case - dependents with their own member ID

If a dependent has their own unique member ID assigned by the payer, treat them as the insured for claim submission purposes. Include their information in the insured object and omit the patient object. 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.

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.

  • Professional Claim JSON: For example, you must always include the insured object in your request, but you only need to include the patient object when the patient is someone other than the insured.
  • 837P JSON (Legacy): For example, you must always include the subscriber object in your request, but you only need to include the supervising object when a physician supervises the rendering provider.

275 claim attachments

If the claim requires attachments, you must include additional details about the attachments in the appropriate objects:

Professional Claim JSON

837P JSON (Legacy)

Visit Claim attachments for complete instructions.

Body - X12 EDI

You must send a payload in 837 X12 EDI format.

Note the following requirements and behavior when sending professional claims through the raw X12 endpoint.

Envelope and header

Stedi generates its own ISA and GS headers and IEA and GE trailers before sending your claim to the payer. You can submit your claim to Stedi with any values in these segments, as long as they conform to the X12 EDI specification.

However, you must set ST03 (Implementation Guide Version Name) to 005010X222A1.

Payer ID

You must submit a payer identifier in Loop 2010BB (Payer Name) NM109 so Stedi can route your claim to the correct payer. This identifier must be a payer ID or payer ID alias listed in the Payer Network. If you don't already have payer IDs you use today, we recommend using the primary Payer ID.

You must include leading 0 characters in payer IDs. For example, use 00540 for SISCO, not 540.

CLM01 (Patient Control Number)

We strongly recommend submitting a unique value for Loop 2300 (Claim Information) CLM01 (Patient Control Number). The payer returns this value in related transactions, such as the 277CA claim acknowledgment and 835 Electronic Remittance Advice (ERA), so you can correlate responses and real-time claim status checks with the original claim.

When assigning a PCN, follow these best practices:

  • Use a unique PCN for each claim. The identifier should be more complex than a simple sequential number and should be hard to guess.
  • Use random strings. Formats with patient initials or the date of service in them can create duplicates. We recommend using nanoid or a similar library configured with the characters available in the basic character set to create a strong, unique 17-character PCN for each claim.
  • Keep it 17 characters or less. Some payers cut off values longer than 17 characters in ERAs and claim acknowledgments, which makes it hard to match them with the original claim.
  • Use only characters available in the basic character set, and avoid special characters that are only available in the extended character set. Payers are permitted to return data using the basic character set. Using other characters may result in data loss or mismatches when correlating claims with responses.
  • Treat PCN values as case-insensitive when matching transactions, even if the submitted value included both lower and uppercase characters.

Claim identifier

Loop 2300 REF02 (Claim Identifier for Transmission Intermediaries) has different usage rules depending on your role:

  • Providers: Don't include Loop 2300 REF02 when REF01 = D9 in your claim submission. It's reserved for clearinghouses and intermediaries. You can use Loop 2300 CLM01 (Patient Control Number) to correlate claims with responses instead.
  • Clearinghouses and intermediaries: You can optionally include REF*D9 in your 837 submissions. Stedi always returns this value in Loop 2200D REF*D9 of 277CA claim acknowledgments, allowing you to match these responses to the claim.

Service line identification

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 patient control number, but only pertains to some of the service lines.

However, the line item control number serves as a unique identifier for each service line in your claim submission.

  • You can set the line item control number in Loop 2400 REF02, when REF01 = 6R. The line item control number 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 line item control number for a service line, Stedi uses a ULID.

275 claim attachments

If the claim requires attachments, you must include specific elements to identify the attachment in either Loop 2300 (claim-level attachments) or Loop 2400 (service line attachments):

  • PWK01 - Attachment Report Type Code. This code identifies the type of report or document you plan to submit as an attachment. Visit Code lists for a complete list of valid codes.
  • PWK02 - Attachment Transmission Code. Set to EL when submitting attachments through Stedi. This indicates you send the attachment in a separate, electronic 275 transaction.
  • PWK06 - Attachment Control Number. A unique identifier for the attachment. The payer uses this value to match the attachment to the claim. We recommend using a ULID or UUID of up to 50 characters.

Only include attachment details when you plan to submit an attachment. Some payers stall claim processing indefinitely if you include a PWK segment without sending an associated attachment.

After submitting the claim, you must submit the attachment through the Submit Claim Attachment (275) X12 EDI endpoint. The attachment control number in Loop 2000A TRN02 must match the PWK06 value from the claim.

Visit Claim attachments for complete instructions.

Sample request and response

The following examples send a professional claim through each endpoint. All endpoints return a JSON response from Stedi containing information about the claim submission and whether it was successful.

Professional Claim JSON

The following example sends a professional claim through the Create Professional Claim (CMS-1500) JSON endpoint. The endpoint returns an HTTP 201 whether Stedi's edits pass or fail. Monitor the response shape to determine success or failure.

The response contains summary information from Stedi about the claim submission:

  • claimId: 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.
  • submissionId: 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.
  • errors (optional): An array of errors when the claim fails one or more of Stedi's edits and repairs. When present, Stedi stores the claim with status REJECTED and never sends it to the payer. When absent, the claim passed Stedi's edits, and Stedi sent it to the payer.

The Create Professional Claim JSON endpoint is available in the Stedi TypeScript and Python SDKs. Visit SDKs for installation and usage details.

 
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"
  }
}'
{
  "claimId": "clm_01K6XFP3TZ8RA9X84963NMW40M",
  "submissionId": "sbm_01K6XFP3TZ8RA9X84963NMW40N"
}
{
  "claimId": "clm_5RPQXX5FM3A83RMYPQ5X2YW7KX",
  "submissionId": "sbm_7K4JDJKN3ABBH9MCAW6NE86DYV",
  "errors": [
    {
      "description": "Invalid NPI. The Billing Provider NPI of 1730289013 is invalid. The National Provider Identifier must be valid with 10 digits and no prefixes or dashes. Correct and resubmit."
    },
    {
      "description": "Invalid Taxonomy Code. The taxonomy code for Billing Provider does not meet the required format. Taxonomy codes must be 10 uppercase alphanumeric characters ending with 'X'. Correct and resubmit."
    }
  ]
}

837P JSON (Legacy)

The following example sends a professional claim through the Professional Claims (837P) JSON - Legacy endpoint. The response contains summary information from Stedi about the claim submission and whether it was successful.

The response also includes an initial 277CA claim acknowledgment from Stedi in the x12 property, which indicates whether the claim passed Stedi's claim edits.

curl --request POST \
  --url https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/professionalclaims/v3/submission \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{
  "usageIndicator": "T",
  "tradingPartnerServiceId": "62308",
  "submitter": {
    "organizationName": "Test Data Health Services, Inc.",
    "submitterIdentification": "<YOUR-SUBMITTER-ID>",
    "contactInformation": {
      "name": "Test Data Health Services, Inc.",
      "phoneNumber": "5552223333"
    }
  },
  "receiver": {
    "organizationName": "Cigna"
  },
  "subscriber": {
    "memberId": "U7777788888",
    "paymentResponsibilityLevelCode": "P",
    "subscriberGroupName": "Cigna",
    "firstName": "John",
    "lastName": "Anon",
    "gender": "M",
    "dateOfBirth": "20000101",
    "groupNumber": "3335555",
    "address": {
      "address1": "2222 Random St",
      "city": "A City",
      "state": "NY",
      "postalCode": "123450000"
    }
  },
  "billing": {
    "providerType": "BillingProvider",
    "npi": "<YOUR-BILLING-PROVIDER-NPI>",
    "employerId": "123456789",
    "taxonomyCode": "2084P0800X",
    "organizationName": "Therapy Associates",
    "address": {
      "address1": "123 Some St",
      "address2": "Floor 1",
      "city": "A City",
      "state": "NY",
      "postalCode": "123450000"
    },
    "contactInformation": {
      "name": "Test Data Health Services, Inc.",
      "phoneNumber": "5553334444"
    }
  },
  "claimInformation": {
    "claimFilingCode": "CI",
    "patientControlNumber": "<YOUR-CLAIM-ID>",
    "claimChargeAmount": "109.20",
    "placeOfServiceCode": "02",
    "claimFrequencyCode": "1",
    "signatureIndicator": "Y",
    "planParticipationCode": "A",
    "benefitsAssignmentCertificationIndicator": "Y",
    "releaseInformationCode": "Y",
    "healthCareCodeInformation": [
      {
        "diagnosisTypeCode": "ABK",
        "diagnosisCode": "F1111"
      }
    ],
    "serviceFacilityLocation": {
      "organizationName": "Smith Associates",
      "address": {
        "address1": "1234 Other St",
        "city": "A City",
        "state": "NY",
        "postalCode": "123450000"
      },
      "npi": "1999999984"
    },
    "serviceLines": [
      {
        "serviceDate": "20240101",
        "professionalService": {
          "procedureIdentifier": "HC",
          "procedureCode": "90837",
          "procedureModifiers": [
            "95"
          ],
          "lineItemChargeAmount": "109.20",
          "measurementUnit": "UN",
          "serviceUnitCount": "1",
          "compositeDiagnosisCodePointers": {
            "diagnosisCodePointers": [
              "1"
            ]
          }
        },
        "providerControlNumber": "111222333",
        "renderingProvider": {
          "providerType": "RenderingProvider",
          "npi": "<YOUR-PROVIDER-NPI>",
          "taxonomyCode": "111YP2000X",
          "firstName": "Jane",
          "lastName": "Smith"
        }
      }
    ]
  },
  "tradingPartnerName": "Cigna"
}'
curl --request POST \
  --url https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/professionalclaims/v3/raw-x12-submission \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{
  "x12": "ISA*00*          *00*          *ZZ*574183004559   *ZZ*STEDITEST      *260213*2039*^*00501*000000039*0*T*>~GS*HC*574183004559*STEDITEST*20260213*203918*39*X*005010X222A1~ST*837*0001*005010X222A1~BHT*0019*00*01KHCBK84E40QQYJVXA5VVXG54*20260213*2038*CH~NM1*41*2*Test Data Health Services, Inc.*****46*123435~PER*IC**TE*5552223333~NM1*40*2*Cigna*****46*62308~HL*1**20*1~PRV*BI*PXC*2084P0800X~NM1*85*2*Therapy Associates*****XX*1999999984~N3*123 Some St*Floor 1~N4*A City*NY*123450000~REF*EI*123456789~PER*IC*Test Data Health Services, Inc.*TE*5553334444~HL*2*1*22*0~SBR*P*18*3335555******CI~NM1*IL*1*Anon*John****MI*U7777788888~N3*2222 Random St~N4*A City*NY*123450000~DMG*D8*20000101*M~NM1*PR*2*Cigna*****PI*62308~CLM*123456789*109.2***02>B>1*Y*A*Y*Y~HI*ABK>F1111~NM1*77*2*Smith Associates~N3*1234 Other St~N4*A City*NY*123450000~LX*1~SV1*HC>90837>95*109.2*UN*1***1~DTP*472*D8*20240101~REF*6R*111222333~SE*29*0001~GE*1*39~IEA*1*000000039~"
}'
{
  "status": "SUCCESS",
  "controlNumber": "1",
  "tradingPartnerServiceId": "62308",
  "claimReference": {
    "correlationId": "01KHC8Y4HNP0GVQ5NSVTPZBC0F",
    "patientControlNumber": "111222333",
    "timeOfResponse": "2026-02-13T19:51:51.496Z",
    "payerId": "62308",
    "formatVersion": "5010",
    "rhclaimNumber": "01KHC8Y4HNP0GVQ5NSVTPZBC0F",
    "serviceLines": [
      {
        "lineItemControlNumber": "111222333"
      }
    ]
  },
  "meta": {
    "traceId": "d61ca4bc-e9e7-4d0f-93d0-6f7ff810b0e6"
  },
  "payer": {
    "payerName": "Cigna",
    "payerId": "62308"
  },
  "x12": "ISA*00*          *00*          *ZZ*STEDITEST      *ZZ*574183004559   *260213*1951*^*00501*980180479*0*T*`~GS*HN*STEDITEST*574183004559*20260213*195151*1*X*005010X214~ST*277*0001*005010X214~BHT*0085*08*01KHC8YJE8EY6A5HFR00Z5H305*20260213*195151*TH~HL*1**20*1~NM1*AY*2*STEDI INC*****46*117151744~TRN*1*01KHC8YJE8EY6A5HFR00Z5H305~DTP*050*D8*20260213~DTP*009*D8*20260213~HL*2*1*21*1~NM1*41*2*Test Data Health Services, Inc.*****46*123456~TRN*2*01KHC8Y4HNP0GVQ5NSVTPZBC0F~STC*A0`17`AY*20260213*WQ*109.2~QTY*90*1~AMT*YU*109.2~HL*3*2*19*1~NM1*85*2*Therapy Associates*****XX*1234567890~TRN*1*0~REF*TJ*123456789~QTY*QA*1~AMT*YU*109.2~HL*4*3*PT*0~NM1*QC*1*Anon*John****MI*U7777788888~TRN*2*111222333~STC*A1`20*20260213*WQ*109.2~DTP*472*RD8*20240101-20240101~SE*25*0001~GE*1*1~IEA*1*980180479~",
  "httpStatusCode": "200 OK"
}

837P Raw X12

The following example sends a professional claim through the Professional Claims (837P) Raw X12 endpoint. The response contains summary information from Stedi about the claim submission and whether it was successful.

The response also includes an initial 277CA claim acknowledgment from Stedi in the x12 property, which indicates whether the claim passed Stedi's claim edits.

curl --request POST \
  --url https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/professionalclaims/v3/raw-x12-submission \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{
  "x12": "ISA*00*          *00*          *ZZ*574183004559   *ZZ*STEDITEST      *260213*2039*^*00501*000000039*0*T*>~GS*HC*574183004559*STEDITEST*20260213*203918*39*X*005010X222A1~ST*837*0001*005010X222A1~BHT*0019*00*01KHCBK84E40QQYJVXA5VVXG54*20260213*2038*CH~NM1*41*2*Test Data Health Services, Inc.*****46*123435~PER*IC**TE*5552223333~NM1*40*2*Cigna*****46*6400~HL*1**20*1~PRV*BI*PXC*2084P0800X~NM1*85*2*Therapy Associates*****XX*1999999984~N3*123 Some St*Floor 1~N4*A City*NY*123450000~REF*EI*123456789~PER*IC*Test Data Health Services, Inc.*TE*5553334444~HL*2*1*22*0~SBR*P*18*3335555******CI~NM1*IL*1*Anon*John****MI*U7777788888~N3*2222 Random St~N4*A City*NY*123450000~DMG*D8*20000101*M~NM1*PR*2*Cigna*****PI*6400~CLM*123456789*109.2***02>B>1*Y*A*Y*Y~HI*ABK>F1111~NM1*77*2*Smith Associates~N3*1234 Other St~N4*A City*NY*123450000~LX*1~SV1*HC>90837>95*109.2*UN*1***1~DTP*472*D8*20240101~REF*6R*111222333~SE*29*0001~GE*1*39~IEA*1*000000039~"
}'
{
  "claimReference": {
    "correlationId": "01J1M588QT2TAV2N093GNJ998T",
    "formatVersion": "5010",
    "patientControlNumber": "123456789",
    "payerId": "6400",
    "rhClaimNumber": "01J1M588QT2TAV2N093GNJ998T",
    "serviceLines": [
      {
        "lineItemControlNumber": "1"
      }
    ],
    "timeOfResponse": "2024-07-10T22:05:32.203Z"
  },
  "controlNumber": "000000039",
  "httpStatusCode": "200 OK",
  "meta": {
    "traceId": "b727b8e7-1f00-4011-bc6e-e41444d406d8"
  },
  "payer": {
    "payerID": "6400",
    "payerName": "Cigna"
  },
  "status": "SUCCESS",
  "tradingPartnerServiceId": "6400"
}

Character restrictions

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

In addition, the following characters are reserved for delimiters in the final X12 EDI transaction to the payer: ~, *, :, ^, and >. X12 doesn't support using escape sequences to represent delimiters or special characters. Stedi returns a 400 error if you use these restricted characters improperly.

  • JSON endpoints: Don't include delimiter characters anywhere in your request data.
  • 837P Raw X12 endpoint: You can use these characters as delimiters, but not in the body of the request data.

Concurrency and rate limits

Professional claim submission endpoints share both a rate limit pool and a concurrency pool with other claim endpoints. For more information, visit Limits.

You may want to use an API client to make testing and debugging easier.

We don't recommend using Postman for requests containing Protected Health Information (PHI) because Postman defaults to storing request history - including full request payloads - on its cloud servers. You can't turn this feature off without impractical workarounds.

Visit API clients for a list of recommended clients you can use instead.

View submitted claims

In the claims view, you can review and filter every claim in your account. Toggle Test mode in the side navigation to view test or production claims. Click any claim to review its details and download the auto-generated CMS-1500 claim form PDF.

Submit to a secondary or tertiary payer

The Create Professional Claim JSON endpoint doesn't support coordination of benefits. To submit claims to secondary and tertiary payers, you must use the 837P JSON (Legacy) endpoint or the 837P Raw X12 endpoint.

In coordination of benefits (COB) scenarios, you'll need to submit a claim to multiple payers.

You must set the subscriber.paymentResponsibilityLevelCode to either S (when submitting to the secondary payer) or T (when submitting to the tertiary payer).

You must also include the following information about how prior payers have adjudicated the claim. For example, if a patient's private insurance plan (primary payer) adjusted the requested reimbursement amount and paid for its portion of the services, you must include that information in the claim you submit to Medicare (secondary payer). You can find these details in 835 ERA responses from prior payers.

Claim information

You must submit one object in the claimInformation.otherSubscriberInformation array for each prior payer. Supply all the required properties in the object plus the following additional information:

  • claimLevelAdjustments: Provide if the prior payer made adjustments at the claim level. Codes and their associated amounts must come from ERAs sent by the prior payers. You can find these codes in the ERA's transactions[].detailInfo[].paymentInfo[].claimAdjustments array.
  • medicareInpatientAdjudication (institutional claims only): You must include this if Medicare was one of the prior payers and reported inpatient adjudication information on the ERA.
  • medicareOutpatientAdjudication: You must include this if Medicare was one of the prior payers and reported outpatient adjudication information on the ERA.
  • otherPayerName.otherPayerAdjudicationOrPaymentDate: The date the payer adjudicated or paid the claim. You must provide this if you aren't providing a value in the claimInformation.serviceLines[].lineAdjudicationInformation[].adjudicationOrPaymentDate property.
  • payerPaidAmount: This is the total amount in dollars the payer paid on this claim.

Service line information

You must submit serviceLines[].lineAdjudicationInformation objects when the prior payers provided line-level adjudication information. Submit one object for each prior payer. For each object, you should include the following properties.

  • adjudicationOrPaymentDate: The date the payer adjudicated or paid the claim. Don't include this if you're providing a date in the otherPayerName.otherPayerAdjudicationOrPaymentDate property.
  • claimAdjustmentInformation: You can find this information in the ERA's transactions[].detailInfo[].paymentInfo[].serviceLines[].serviceAdjustments array.
  • otherPayerPrimaryIdentifier: The identifier for the other payer. This value should match the identifier you supplied for the payer in the claimInformation.otherSubscriberInformation[].otherPayerName.otherPayerIdentifier property.
  • procedureCode: The adjudicated procedure code for the service line.
  • serviceIdQualifier: A code identify the type of procedure code. Visit Claims code lists for a complete list.
  • serviceLinePaidAmount: The total amount in dollars the prior payer paid on this service line.
  • paidServiceUnitCount: The number of paid units for the service line. When paid units are not present on the remittance advice, use the original billed units.
  • remainingPatientLiability: The amount of the service line the patient is responsible for paying.

Claim Filing Indicator Code

The Claim Filing Indicator Code indicates the type of health insurance plan you're billing, such as Medicare, Medicaid, or commercial insurance.

Choosing the correct claim filing indicator code is important for successful claim submission. Visit the Claims code lists documentation for best practices for selecting the appropriate code.

Set a claim's correlation ID

A claim's correlation ID is a business identifier that you can use to track and manage claims.

  • Professional Claim JSON doesn't include a correlation ID in the response.
  • When you submit claims through 837P JSON (Legacy), Stedi generates the correlation ID for you, and this value is unique for each claim.
  • When you submit claims through 837P Raw X12 or an SFTP connection, you can specify your own correlation ID in the BHT03 element. This lets you use the same value for multiple claims if needed.

CMS-1500 claim form PDF

Stedi automatically generates a PDF CMS-1500 claim form for each professional claim you submit. You can retrieve PDFs through the Stedi portal or programmatically through the API.

Visit CMS-1500 Claim Form PDF for instructions on retrieving PDFs, information about how to structure claim submissions for optimal PDF generation, printer settings, and general best practices.

Test claim workflows
Manual submission

On this page

Before sending claimsTransaction enrollmentBest practicesCoordination of benefits checkTest claimsSubmit professional claimsHeadersIdempotency keyBody - JSONPatient Control NumberService line identificationPatient versus insuredConditional requirements275 claim attachmentsBody - X12 EDIEnvelope and headerPayer IDCLM01 (Patient Control Number)Claim identifierService line identification275 claim attachmentsSample request and responseProfessional Claim JSON837P JSON (Legacy)837P Raw X12Character restrictionsConcurrency and rate limitsRecommended API clientsView submitted claimsSubmit to a secondary or tertiary payerClaim informationService line informationClaim Filing Indicator CodeSet a claim's correlation IDCMS-1500 claim form PDF