Stedi Claim acknowledgments API

openapi: 3.2.0
info:
  contact:
    email: healthcare@stedi.com
  license:
    name: Proprietary
    url: https://stedi.com
  title: Stedi Healthcare Claim acknowledgments API
  version: '2024-04-01'
servers:
- description: Production
  url: https://healthcare.us.stedi.com/2024-04-01
- description: Production (2026-06-01)
  url: https://healthcare.us.stedi.com/2026-06-01
security:
- httpApiKeyAuth: []
tags:
- name: Claim acknowledgments
paths:
  /change/medicalnetwork/reports/v2/{transactionId}/277:
    get:
      description: Retrieve a 277CA claim acknowledgment in JSON format
      operationId: ConvertReport277
      parameters:
      - description: A unique identifier for the processed 277 transaction within Stedi. This ID is included in the transaction processed event, which you can receive automatically through Stedi [webhooks](https://www.stedi.com/docs/healthcare/configure-webhooks). You can also retrieve it through the [Poll Transactions endpoint](https://www.stedi.com/docs/healthcare/api-reference/get-poll-transactions).
        examples:
          ConvertReport277_example1:
            description: ''
            summary: Accepted claim
            value: d567c2ae-f073-4725-8b8c-06c473b738a6
          ConvertReport277_example2:
            description: ''
            summary: Denied claim
            value: 71716ec5-0e96-462f-bb77-869941bb27ab
        in: path
        name: transactionId
        required: true
        schema:
          description: A unique identifier for the processed 277 transaction within Stedi. This ID is included in the transaction processed event, which you can receive automatically through Stedi [webhooks](https://www.stedi.com/docs/healthcare/configure-webhooks). You can also retrieve it through the [Poll Transactions endpoint](https://www.stedi.com/docs/healthcare/api-reference/get-poll-transactions).
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                ConvertReport277_example1:
                  description: ''
                  summary: Accepted claim
                  value:
                    meta:
                      transactionId: 71716ec5-0e96-462f-bb77-869941bb27ab
                    transactions:
                    - controlNumber: '1001'
                      payers:
                      - claimStatusTransactions:
                        - claimStatusDetails:
                          - patientClaimStatusDetails:
                            - claims:
                              - claimStatus:
                                  claimServiceBeginDate: '20240101'
                                  claimServiceEndDate: '20240101'
                                  clearinghouseTraceNumber: 01J1SNT1FQC8ABWD44MAMBDYKA
                                  informationClaimStatuses:
                                  - informationStatuses:
                                    - healthCareClaimStatusCategoryCode: A1
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Receipt - The claim/encounter has been received. This does not mean that the claim has been accepted for adjudication.
                                      statusCode: '20'
                                      statusCodeValue: Accepted for processing.
                                    statusInformationEffectiveDate: '20240702'
                                    totalClaimChargeAmount: '109.20'
                                  patientAccountNumber: '11122233'
                                  referencedTransactionTraceNumber: '11122233'
                              subscriber:
                                firstName: JOHN
                                lastName: ANON
                                memberId: U7777788888
                            providerOFServiceInformationTraceIdentifier: '0'
                            serviceProvider:
                              npi: '1235600834'
                              organizationName: THERAPY ASSOCIATES
                          claimTransactionBatchNumber: 01J1SNRJ0FP4ZE6EFWM4G4XB3N
                          provider:
                            etin: '1235600834'
                            organizationName: TEST DATA HEALTH SERVICES, INC.
                          providerClaimStatuses:
                          - providerStatuses:
                            - healthCareClaimStatusCategoryCode: A1
                              healthCareClaimStatusCategoryCodeValue: Acknowledgement/Receipt - The claim/encounter has been received. This does not mean that the claim has been accepted for adjudication.
                              statusCode: '20'
                              statusCodeValue: Accepted for processing.
                            statusInformationEffectiveDate: '20240702'
                        entityIdentifierCode: AY
                        entityIdentifierCodeValue: Clearinghouse
                        organizationName: STEDI INC
                      referenceIdentification: '1511096803'
                      transactionSetCreationDate: '20240702'
                      transactionSetCreationTime: 0815
                ConvertReport277_example2:
                  description: ''
                  summary: Denied claim
                  value:
                    meta:
                      transactionId: 71716ec5-0e96-462f-bb77-869941bb27ab
                    transactions:
                    - controlNumber: '1001'
                      payers:
                      - claimStatusTransactions:
                        - claimStatusDetails:
                          - patientClaimStatusDetails:
                            - claims:
                              - claimStatus:
                                  claimServiceBeginDate: '20250101'
                                  claimServiceEndDate: '20250109'
                                  clearinghouseTraceNumber: NA
                                  informationClaimStatuses:
                                  - informationStatuses:
                                    - healthCareClaimStatusCategoryCode: A3
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Returned as unprocessable claim - The claim/encounter has been rejected and has not been entered into the adjudication system.
                                      statusCode: '21'
                                      statusCodeValue: Missing or invalid information.
                                    statusInformationEffectiveDate: '20250201'
                                    totalClaimChargeAmount: '3459.3'
                                  patientAccountNumber: AAA11111
                                  referencedTransactionTraceNumber: AAA11111
                                serviceLines:
                                - beginServiceLineDate: '20250101'
                                  lineItemControlNumber: ABCD1234
                                  service:
                                    chargeAmount: '379.39'
                                    procedureCode: '97153'
                                    serviceIdQualifierCode: HC
                                    serviceIdQualifierCodeValue: Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes
                                    submittedUnits: '11'
                                  serviceClaimStatuses:
                                  - serviceStatuses:
                                    - entityIdentifierCode: IL
                                      entityIdentifierCodeValue: Insured or Subscriber
                                      healthCareClaimStatusCategoryCode: A3
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Returned as unprocessable claim - The claim/encounter has been rejected and has not been entered into the adjudication system.
                                      statusCode: '164'
                                      statusCodeValue: Entity's contract/member number.
                                - beginServiceLineDate: '20250101'
                                  lineItemControlNumber: DCBA4321
                                  service:
                                    chargeAmount: '206.94'
                                    procedureCode: '97155'
                                    serviceIdQualifierCode: HC
                                    serviceIdQualifierCodeValue: Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes
                                    submittedUnits: '6'
                                  serviceClaimStatuses:
                                  - serviceStatuses:
                                    - entityIdentifierCode: IL
                                      entityIdentifierCodeValue: Insured or Subscriber
                                      healthCareClaimStatusCategoryCode: A3
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Returned as unprocessable claim - The claim/encounter has been rejected and has not been entered into the adjudication system.
                                      statusCode: '164'
                                      statusCodeValue: Entity's contract/member number.
                                - beginServiceLineDate: '20250101'
                                  lineItemControlNumber: WXYZ1234
                                  service:
                                    chargeAmount: '413.92'
                                    procedureCode: '97154'
                                    serviceIdQualifierCode: HC
                                    serviceIdQualifierCodeValue: Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes
                                    submittedUnits: '16'
                                  serviceClaimStatuses:
                                  - serviceStatuses:
                                    - entityIdentifierCode: IL
                                      entityIdentifierCodeValue: Insured or Subscriber
                                      healthCareClaimStatusCategoryCode: A3
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Returned as unprocessable claim - The claim/encounter has been rejected and has not been entered into the adjudication system.
                                      statusCode: '164'
                                      statusCodeValue: Entity's contract/member number.
                                - beginServiceLineDate: '20250101'
                                  lineItemControlNumber: ZYXW4321
                                  service:
                                    chargeAmount: '138.72'
                                    procedureCode: '97156'
                                    procedureModifiers:
                                    - GT
                                    - '59'
                                    serviceIdQualifierCode: HC
                                    serviceIdQualifierCodeValue: Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes
                                    submittedUnits: '4'
                                  serviceClaimStatuses:
                                  - serviceStatuses:
                                    - entityIdentifierCode: IL
                                      entityIdentifierCodeValue: Insured or Subscriber
                                      healthCareClaimStatusCategoryCode: A3
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Returned as unprocessable claim - The claim/encounter has been rejected and has not been entered into the adjudication system.
                                      statusCode: '164'
                                      statusCodeValue: Entity's contract/member number.
                                - beginServiceLineDate: '20250101'
                                  lineItemControlNumber: EFGH5678
                                  service:
                                    chargeAmount: '413.92'
                                    procedureCode: '97154'
                                    serviceIdQualifierCode: HC
                                    serviceIdQualifierCodeValue: Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes
                                    submittedUnits: '16'
                                  serviceClaimStatuses:
                                  - serviceStatuses:
                                    - entityIdentifierCode: IL
                                      entityIdentifierCodeValue: Insured or Subscriber
                                      healthCareClaimStatusCategoryCode: A3
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Returned as unprocessable claim - The claim/encounter has been rejected and has not been entered into the adjudication system.
                                      statusCode: '164'
                                      statusCodeValue: Entity's contract/member number.
                                - beginServiceLineDate: '20250102'
                                  lineItemControlNumber: HGFE8765
                                  service:
                                    chargeAmount: '413.92'
                                    procedureCode: '97154'
                                    serviceIdQualifierCode: HC
                                    serviceIdQualifierCodeValue: Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes
                                    submittedUnits: '16'
                                  serviceClaimStatuses:
                                  - serviceStatuses:
                                    - entityIdentifierCode: IL
                                      entityIdentifierCodeValue: Insured or Subscriber
                                      healthCareClaimStatusCategoryCode: A3
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Returned as unprocessable claim - The claim/encounter has been rejected and has not been entered into the adjudication system.
                                      statusCode: '164'
                                      statusCodeValue: Entity's contract/member number.
                                - beginServiceLineDate: '20250105'
                                  lineItemControlNumber: IJKL1234
                                  service:
                                    chargeAmount: '137.96'
                                    procedureCode: '97155'
                                    serviceIdQualifierCode: HC
                                    serviceIdQualifierCodeValue: Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes
                                    submittedUnits: '4'
                                  serviceClaimStatuses:
                                  - serviceStatuses:
                                    - entityIdentifierCode: IL
                                      entityIdentifierCodeValue: Insured or Subscriber
                                      healthCareClaimStatusCategoryCode: A3
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Returned as unprocessable claim - The claim/encounter has been rejected and has not been entered into the adjudication system.
                                      statusCode: '164'
                                      statusCodeValue: Entity's contract/member number.
                                - beginServiceLineDate: '20250105'
                                  lineItemControlNumber: LKJI4321
                                  service:
                                    chargeAmount: '388.05'
                                    procedureCode: '97154'
                                    serviceIdQualifierCode: HC
                                    serviceIdQualifierCodeValue: Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes
                                    submittedUnits: '15'
                                  serviceClaimStatuses:
                                  - serviceStatuses:
                                    - entityIdentifierCode: IL
                                      entityIdentifierCodeValue: Insured or Subscriber
                                      healthCareClaimStatusCategoryCode: A3
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Returned as unprocessable claim - The claim/encounter has been rejected and has not been entered into the adjudication system.
                                      statusCode: '164'
                                      statusCodeValue: Entity's contract/member number.
                                - beginServiceLineDate: '20250107'
                                  lineItemControlNumber: MNOP5678
                                  service:
                                    chargeAmount: '138.72'
                                    procedureCode: '97156'
                                    procedureModifiers:
                                    - GT
                                    - '59'
                                    serviceIdQualifierCode: HC
                                    serviceIdQualifierCodeValue: Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes
                                    submittedUnits: '4'
                                  serviceClaimStatuses:
                                  - serviceStatuses:
                                    - entityIdentifierCode: IL
                                      entityIdentifierCodeValue: Insured or Subscriber
                                      healthCareClaimStatusCategoryCode: A3
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Returned as unprocessable claim - The claim/encounter has been rejected and has not been entered into the adjudication system.
                                      statusCode: '164'
                                      statusCodeValue: Entity's contract/member number.
                                - beginServiceLineDate: '20250107'
                                  lineItemControlNumber: PONM8765
                                  service:
                                    chargeAmount: '413.88'
                                    procedureCode: '97153'
                                    serviceIdQualifierCode: HC
                                    serviceIdQualifierCodeValue: Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes
                                    submittedUnits: '12'
                                  serviceClaimStatuses:
                                  - serviceStatuses:
                                    - entityIdentifierCode: IL
                                      entityIdentifierCodeValue: Insured or Subscriber
                                      healthCareClaimStatusCategoryCode: A3
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Returned as unprocessable claim - The claim/encounter has been rejected and has not been entered into the adjudication system.
                                      statusCode: '164'
                                      statusCodeValue: Entity's contract/member number.
                                - beginServiceLineDate: '20250109'
                                  lineItemControlNumber: QRST6789
                                  service:
                                    chargeAmount: '413.88'
                                    procedureCode: '97153'
                                    serviceIdQualifierCode: HC
                                    serviceIdQualifierCodeValue: Health Care Financing Administration Common Procedural Coding System (HCPCS) Codes
                                    submittedUnits: '12'
                                  serviceClaimStatuses:
                                  - serviceStatuses:
                                    - entityIdentifierCode: IL
                                      entityIdentifierCodeValue: Insured or Subscriber
                                      healthCareClaimStatusCategoryCode: A3
                                      healthCareClaimStatusCategoryCodeValue: Acknowledgement/Returned as unprocessable claim - The claim/encounter has been rejected and has not been entered into the adjudication system.
                                      statusCode: '164'
                                      statusCodeValue: Entity's contract/member number.
                              subscriber:
                                firstName: JOHN
                                lastName: DOE
                                memberId: XYZ1234567
                            providerOFServiceInformationTraceIdentifier: '0'
                            serviceProvider:
                              npi: '1234567890'
                              organizationName: Provider Organization Name
                          claimTransactionBatchNumber: 387DKEO986DMGN98733S
                          provider:
                            etin: '1234567890'
                            organizationName: Provider Organization Name
                          providerClaimStatuses:
                          - providerStatuses:
                            - healthCareClaimStatusCategoryCode: A1
                              healthCareClaimStatusCategoryCodeValue: Acknowledgement/Receipt - The claim/encounter has been received. This does not mean that the claim has been accepted for adjudication.
                              statusCode: '20'
                              statusCodeValue: Accepted for processing.
                            statusInformationEffectiveDate: '20250201'
                        entityIdentifierCode: PR
                        entityIdentifierCodeValue: Payer
                        organizationName: AZ BLUE
                        payerIdentification: BCBSAZ
                      referenceIdentification: '94846578362'
                      transactionSetCreationDate: '20250201'
                      transactionSetCreationTime: '1439'
              schema:
                $ref: '#/components/schemas/ConvertReport277ResponseContent'
          description: ConvertReport277 200 response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationExceptionResponseContent'
          description: ValidationException 400 response
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedExceptionResponseContent'
          description: AccessDeniedException 403 response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundExceptionResponseContent'
          description: ResourceNotFoundException 404 response
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingExceptionResponseContent'
          description: ThrottlingException 429 response
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalFailureExceptionResponseContent'
          description: InternalFailureException 500 response
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableExceptionResponseContent'
          description: ServiceUnavailableException 503 response
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeoutExceptionResponseContent'
          description: GatewayTimeoutException 504 response
      tags:
      - Claim acknowledgments
components:
  schemas:
    ReportsClaimAcknowledgmentResponse:
      properties:
        controlNumber:
          description: The control number the payer provided in the claim status response. This is used to identify the transaction.
          type: string
        payers:
          description: Information about the payer (or intermediary clearinghouse) and the claim status transactions included in the response.
          items:
            $ref: '#/components/schemas/ClaimAcknowledgmentPayer'
          type: array
        referenceIdentification:
          description: A number the payer assigns to the transaction to identify it within their system.
          type: string
        transactionSetCreationDate:
          description: The date the payer created the transaction.
          pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$
          type: string
        transactionSetCreationTime:
          description: 'The time the payer created the transaction, expressed in 24-hour clock time. May be formatted as HHMM, HHMMSS, HHMMSSD, or HHMMSSDD, where H = hours (00-23), M = minutes (00-59), S = integer seconds (00-59) and DD = decimal seconds; decimal seconds are expressed as follows: D = tenths (0-9) and DD = hundredths (00-99).'
          pattern: ^([01]\d|2[0-3])[0-5]\d$|^([01]\d|2[0-3])[0-5]\d[0-5]\d$|^([01]\d|2[0-3])[0-5]\d[0-5]\d\d$|^([01]\d|2[0-3])[0-5]\d[0-5]\d\d\d$
          type: string
      type: object
    Meta:
      description: Metadata that helps Stedi track and debug the response.
      properties:
        applicationMode:
          description: Whether this is a test or production ERA.
          type: string
        senderId:
          description: An identifier for the most recent sender of the ERA. This is usually not the original sender, so this value is unlikely to be a payer ID. When Stedi processes and delivers ERAs through the clearinghouse, this value is always `STEDI`.
          type: string
        traceId:
          description: Not currently used.
          type: string
        transactionId:
          description: The Stedi transaction identifier.
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          type: string
      type: object
    ServiceEntityIdentifierCode:
      description: Entity identifier code for service lines in claim status reports
      enum:
      - '03'
      - '36'
      - '40'
      - '41'
      - '71'
      - '72'
      - '73'
      - '77'
      - '82'
      - '85'
      - '87'
      - 1P
      - 1Z
      - DK
      - DN
      - DQ
      - FA
      - GB
      - HK
      - IL
      - LI
      - MSC
      - PR
      - PRP
      - QB
      - QC
      - QD
      - SEP
      - TL
      - TTP
      - TU
      type: string
    PayerEntityIdentifierCode:
      description: Entity identifier code for payers in claim status reports
      enum:
      - AY
      - PR
      type: string
    ServiceClaimStatus:
      properties:
        effectiveDate:
          deprecated: true
          description: The date the status information is effective.
          type: string
        serviceStatuses:
          description: The status of the service.
          items:
            $ref: '#/components/schemas/ServiceLineStatus'
          type: array
      type: object
    ServiceLineStatus:
      properties:
        entityIdentifierCode:
          $ref: '#/components/schemas/ServiceEntityIdentifierCode'
          description: A code indicating the entity that is responsible for the service line.
        entityIdentifierCodeValue:
          $ref: '#/components/schemas/ServiceEntityIdentifierCodeValue'
          description: The description of the `entityIdentifierCode`.
        healthCareClaimStatusCategoryCode:
          $ref: '#/components/schemas/HealthCareClaimStatusCategoryCode'
        healthCareClaimStatusCategoryCodeValue:
          description: Description of the `healthCareClaimStatusCategoryCode` property. Visit [277CA code lists](https://www.stedi.com/docs/healthcare/claims-code-lists#claim-status-category-code) for a complete list.
          type: string
        nationalCouncilForPrescriptionDrugProgramsRejectPaymentCodes:
          deprecated: true
          description: A National Council for Prescription Drug Programs (NCPDP) reject code.
          type: string
        statusCode:
          $ref: '#/components/schemas/HealthCareClaimStatusCode'
          description: A code indicating the status.
        statusCodeValue:
          description: The description of the `statusCode`.
          type: string
      type: object
    ClaimLevelEntityIdentifierCodeValue:
      description: Human-readable descriptions for claim level entity identifier codes
      enum:
      - Dependent
      - Employer
      - Receiver
      - Submitter
      - Attending Physician
      - Operating Physician
      - Other Physician
      - Service Location
      - Rendering Provider
      - Billing Provider
      - Pay-to Provider
      - Provider
      - Home Health Care
      - Ordering Physician
      - Referring Provider
      - Supervising Physician
      - Facility
      - Other Insured
      - Subscriber
      - Insured or Subscriber
      - Independent Lab
      - Mammography Screening Center
      - Payer
      - Primary Payer
      - Purchase Service Provider
      - Patient
      - Responsible Party
      - Secondary Payer
      - Testing Laboratory
      - Tertiary Payer
      - Third Party Repricing Organization (TPO)
      type: string
    ReportsClaims:
      properties:
        claimStatus:
          $ref: '#/components/schemas/ClaimsClaimStatus'
          description: Status information for the claim. This object includes the `referencedTransactionTraceNumber` you can use to correlate the 277CA with the original claim.
        serviceLines:
          description: Information about specific services within a claim. This object is only included in the 277CA when the claim is rejected because of errors with the service line information provided.
          items:
            $ref: '#/components/schemas/ClaimAcknowledgmentServiceLines'
          type: array
      type: object
    ClaimAcknowledgmentServiceIdQualifierCode:
      description: Code identifying the source of the procedure code in claim status reports.
      enum:
      - AD
      - ER
      - HC
      - HP
      - IV
      - NU
      - WK
      type: string
    ProviderEntityIdentifierCodeValue:
      description: Human-readable descriptions for provider entity identifier codes
      enum:
      - Employer
      - Receiver
      - Submitter
      - Clearinghouse
      - Payer
      type: string
    PayerContactInformation:
      description: The payer's business contact information.
      properties:
        contactMethods:
          description: Each contact will have a single property set, except for phone with extension.
          items:
            $ref: '#/components/schemas/ContactMethods'
          type: array
        contactName:
          description: The name of the contact person or entity.
          type: string
      type: object
    ClaimAcknowledgmentServiceLines:
      properties:
        beginServiceLineDate:
          description: The starting date of the service.
          pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$
          type: string
        endServiceLineDate:
          description: The ending date of the service.
          pattern: ^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$
          type: string
        lineItemControlNumber:
          description: A unique identifier for the service line that matches the `providerControlNumber` submitted in the original claim. You can use this value to correlate the payer's response with specific service lines from the original claim.
          type: string
        service:
          $ref: '#/components/schemas/ClaimAcknowledgmentServiceLinesService'
        serviceClaimStatuses:
          description: The status of the specific service line.
          items:
            $ref: '#/components/schemas/ServiceClaimStatus'
          type: array
        service

# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stedi/refs/heads/main/openapi/stedi-claim-acknowledgments-api-openapi.yml