OpenAPI Specification
openapi: 3.0.3
info:
contact:
email: healthcare@stedi.com
license:
name: Proprietary
url: https://stedi.com
title: Stedi Healthcare Claims Claim acknowledgments X12 API
version: '2025-03-07'
servers:
- description: Production
url: https://claims.us.stedi.com/2025-03-07
security:
- httpApiKeyAuth: []
tags:
- name: X12
paths:
/x12/partnerships/{partnershipId}/generate-edi:
post:
description: This endpoint generates and delivers fully-formed EDI files to your trading partners.
operationId: GenerateEdi
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateEdiRequestContent'
examples:
GenerateEdi_example1:
summary: Generate EDI
description: ''
value:
filename: my-output-file.edi
overrides:
interchangeUsageIndicator: T
acknowledgmentRequestedCode: '1'
transactionGroups:
- transactionSettingId: some-setting-id
overrides:
localApplicationId: customLocal
partnerApplicationId: customPartner
transactions:
- heading:
transaction_set_header_ST:
transaction_set_identifier_code_01: '850'
transaction_set_control_number_02: 1
beginning_segment_for_purchase_order_BEG:
transaction_set_purpose_code_01: XX
purchase_order_type_code_02: XX
purchase_order_number_03: XXXXX
date_05: '2023-08-11'
detail:
baseline_item_data_PO1_loop:
- baseline_item_data_PO1: {}
summary:
transaction_set_trailer_SE:
number_of_included_segments_01: 4
transaction_set_control_number_02: 1
required: true
parameters:
- name: partnershipId
in: path
description: A unique ID for this partnership within Stedi. You can find this ID on the [Trading partners](https://www.stedi.com/app/core/partnerships) page under **Partnership identifier**.
schema:
type: string
maxLength: 81
minLength: 1
pattern: ^([a-zA-Z0-9._-]+)$
description: A unique ID for this partnership within Stedi. You can find this ID on the [Trading partners](https://www.stedi.com/app/core/partnerships) page under **Partnership identifier**.
required: true
examples:
GenerateEdi_example1:
summary: Generate EDI
description: ''
value: ACME_BSW
- name: Idempotency-Key
in: header
description: A unique string to identify this request to the server. The key can be up to 255 characters. You can safely retry requests with the same idempotency key within 24 hours of making the first request. This prevents sending duplicate data to your trading partners in case of network errors or other intermittent failures. [Learn more](https://www.stedi.com/docs/api-reference/index#idempotency-keys).
schema:
type: string
description: A unique string to identify this request to the server. The key can be up to 255 characters. You can safely retry requests with the same idempotency key within 24 hours of making the first request. This prevents sending duplicate data to your trading partners in case of network errors or other intermittent failures. [Learn more](https://www.stedi.com/docs/api-reference/index#idempotency-keys).
responses:
'200':
description: GenerateEdi 200 response
headers:
idempotent-replayed:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateEdiResponseContent'
examples:
GenerateEdi_example1:
summary: Generate EDI
description: ''
value:
edi: ISA*00* *00* *14*ANOTHERMERCH *ZZ*THISISME *230828*0900*^*00801*000000002*1*P*>~GS*PO*ANOTHERMERCH*THISISME*20230828*090020*000000002*X*008010~ST*850*0001~BEG*XX*XX*XXXXX**20230811~PO1~SE*4*0001~GE*1*000000002~IEA*1*000000002~
artifactId: f75168e4-e682-4410-bfec-b5b1541c7f21.x12
fileExecutionId: f75168e4-e682-4410-bfec-b5b1541c7f21
metadata:
interchangeMetadata:
- interchangeControlNumber: 2
functionalGroupControlNumbers:
- 2
'400':
description: BadRequestException 400 response
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestExceptionResponseContent'
'401':
description: UnauthorizedException 401 response
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedExceptionResponseContent'
'403':
description: AccessDeniedException 403 response
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedExceptionResponseContent'
'404':
description: ResourceNotFoundException 404 response
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundExceptionResponseContent'
'409':
description: ResourceUnderChangeException 409 response
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceUnderChangeExceptionResponseContent'
'422':
description: UnprocessableEntityException 422 response
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityExceptionResponseContent'
'429':
description: ThrottlingException 429 response
content:
application/json:
schema:
$ref: '#/components/schemas/ThrottlingExceptionResponseContent'
'500':
description: ServiceException 500 response
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceExceptionResponseContent'
'503':
description: ServiceUnavailableException 503 response
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableExceptionResponseContent'
'504':
description: GatewayTimeoutException 504 response
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutExceptionResponseContent'
tags:
- X12
components:
schemas:
GenerateEdiRequestContent:
type: object
properties:
characterSet:
$ref: '#/components/schemas/CoreCharacterSet'
repairOptions:
$ref: '#/components/schemas/RepairOptions'
transactionGroups:
type: array
items:
$ref: '#/components/schemas/TransactionGroup'
minItems: 1
description: Contains one or more EDI functional groups, each containing the data for one or more EDI transactions. You can override the Application IDs (GS-02 and GS-03) for each group individually. The outbound transaction setting for each group must be configured to use the same connection. If you need to send transactions to different connections, you must call the endpoint multiple times.
filename:
type: string
maxLength: 300
minLength: 1
pattern: ^([a-zA-Z0-9.*'()!_-]+)$
description: Set a custom name for the generated EDI file. Stedi overwrites files with the same name, so we recommend making the filename unique by including a timestamp or other identifier. If you do not specify a filename, Stedi autogenerates a unique name using an ID.
overrides:
$ref: '#/components/schemas/InterchangeOverrides'
interchangeUsageIndicatorOverride:
$ref: '#/components/schemas/X12UsageIndicator'
interchangeAuthorization:
$ref: '#/components/schemas/X12InterchangeAuthorization'
required:
- transactionGroups
InterchangeMetadata:
type: object
description: Metadata for a single interchange within the EDI file.
properties:
interchangeControlNumber:
type: number
maximum: 999999999
minimum: 0
functionalGroupControlNumbers:
type: array
items:
type: number
maximum: 999999999
minimum: 0
minItems: 1
description: A list of functional group control numbers within an interchange.
required:
- functionalGroupControlNumbers
- interchangeControlNumber
X12AcknowledgmentRequestedCode:
type: string
description: Set [ISA-14](https://www.stedi.com/edi/x12/segment/ISA#ISA-14) to a different value. If not set, the default value is `0 (No Interchange Acknowledgment Requested)`.
enum:
- '0'
- '1'
- '2'
- '3'
ServiceExceptionResponseContent:
type: object
properties:
message:
type: string
exceptionCause:
$ref: '#/components/schemas/ExceptionCause'
required:
- message
ServiceUnavailableExceptionResponseContent:
type: object
description: The server cannot handle the request due to technical reasons.
properties:
message:
type: string
code:
type: string
required:
- message
AccessDeniedExceptionResponseContent:
type: object
description: The server response for authorization failure.
properties:
message:
type: string
code:
type: string
required:
- message
ExceptionCause:
type: object
properties:
name:
type: string
message:
type: string
stack:
type: string
ResourceNotFoundExceptionResponseContent:
type: object
description: The server response when the specified resource cannot be found after an API request passes authentication and authorization.
properties:
message:
type: string
code:
type: string
required:
- message
X12UsageIndicator:
type: string
description: Set [ISA-15](https://www.stedi.com/edi/x12/segment/ISA#ISA-15) to a different value. If not set, the default value is `P (Production Data)`.
enum:
- I
- T
- P
InterchangeOverrides:
type: object
properties:
interchangeUsageIndicator:
$ref: '#/components/schemas/X12UsageIndicator'
acknowledgmentRequestedCode:
$ref: '#/components/schemas/X12AcknowledgmentRequestedCode'
interchangeControlVersionNumberCode:
type: string
maxLength: 5
minLength: 5
description: Set [ISA-12](https://www.stedi.com/edi/x12/segment/ISA#ISA-12) to a different value. This code indicates the version of the `ISA` header segments included in the EDI file. By default, Stedi sets `ISA-12` to to be the X12 release number of the guide associated with the transaction setting.
delimiters:
$ref: '#/components/schemas/X12Delimiters'
TransactionGroupOverrides:
type: object
description: Customize the Application IDs for you or your trading partner.
properties:
localApplicationId:
type: string
maxLength: 15
minLength: 2
description: Set the [GS-02](https://www.stedi.com/edi/x12/segment/GS#GS-02) element to a custom value. If not set, Stedi uses the Application ID for the local profile associated with the partnership.
partnerApplicationId:
type: string
maxLength: 15
minLength: 2
description: Set the [GS-03](https://www.stedi.com/edi/x12/segment/GS#GS-03) element to a custom value. If not set, Stedi uses the Application ID for the partner profile associated with the partnership.
X12InterchangeAuthorization:
type: object
description: Set values for [ISA header](https://www.stedi.com/edi/x12/segment/ISA) elements (ISA-01 to ISA-04).
properties:
authorizationInformationQualifier:
$ref: '#/components/schemas/X12AuthorizationInformationQualifier'
authorizationInformation:
type: string
maxLength: 10
pattern: ^.*[^ ].*$
description: Information used for additional identification or authorization of the interchange sender or the data in the interchange (`ISA-02`). The type of information is set by the `authorizationInformationQualifier`.
securityInformationQualifier:
$ref: '#/components/schemas/X12SecurityInformationQualifier'
securityInformation:
type: string
maxLength: 10
pattern: ^.*[^ ].*$
description: The security information referenced by the `securityInformationQualifier` (`ISA-04`). Typically, this is a password.
RepairOptions:
type: object
description: Options for repairing EDI data during generation to ensure it meets X12 requirements
properties:
trimTrailingSpaces:
type: boolean
description: Whether to trim trailing spaces from data elements
uppercase:
type: boolean
description: Whether to convert text to uppercase
replaceConfusable:
type: boolean
description: Whether to replace characters that are visually similar but technically different
removeDiacritical:
type: boolean
description: Whether to remove diacritical marks from characters
replaceNonBasicCharacters:
type: boolean
description: Whether to replace non-basic characters with their basic equivalents
replaceStediCanonicalDelimitersConflicts:
type: boolean
description: Whether to replace characters that conflict with Stedi canonical delimiters
trimTrailingZeroes:
type: boolean
description: Whether to trim trailing zeros from numeric data elements
UnauthorizedExceptionResponseContent:
type: object
description: The server response when the authorizer failed to authenticate the caller.
properties:
message:
type: string
code:
type: string
required:
- message
GatewayTimeoutExceptionResponseContent:
type: object
description: The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.
properties:
message:
type: string
code:
type: string
required:
- message
TransactionGroup:
type: object
description: A transaction group contains data for one or more EDI transactions in [Guide JSON](https://www.stedi.com/docs/edi-platform/operate/transform-json/guide-json) format.
properties:
transactionSettingId:
type: string
maxLength: 50
pattern: ^([a-zA-Z0-9_-]+)$
description: A unique ID outbound transaction setting Stedi should use to determine the correct guide for validation and generation. To find this ID, go to the partnership and use the **Transaction Setting ID** field for the outbound transaction setting.
transactions:
type: array
items: {}
minItems: 1
description: This payload contains the transaction data. It must conform to the JSON Schema for the guide associated with each transaction setting (Guide JSON format).
overrides:
$ref: '#/components/schemas/TransactionGroupOverrides'
required:
- transactionSettingId
- transactions
CoreCharacterSet:
type: string
description: When generating EDI, the character set determines the set of characters allowed in the EDI message. Characters outside of the specified set (after applying any repairs specified in RepairOptions) will result in an error.
enum:
- Basic
- Extended
- ExtendedHipaa
UnprocessableEntityExceptionResponseContent:
type: object
description: The request parameters do not match a previous request with the same idempotency key.
properties:
message:
type: string
code:
type: string
required:
- message
Metadata:
type: object
description: Metadata about the generated EDI file.
properties:
interchangeMetadata:
type: array
items:
$ref: '#/components/schemas/InterchangeMetadata'
minItems: 1
description: A list of interchange metadata for all interchanges in the EDI file.
required:
- interchangeMetadata
ThrottlingExceptionResponseContent:
type: object
description: The server response when usage plan or account-level throttling limits exceeded.
properties:
message:
type: string
code:
type: string
required:
- message
X12AuthorizationInformationQualifier:
type: string
description: Identifies the type of information in the Authorization Information (`ISA-01`). Default is `00 - No Authorization Information Present`.
enum:
- '00'
- '01'
- '02'
- '03'
- '04'
- '05'
- '06'
- '07'
- 08
X12SecurityInformationQualifier:
type: string
description: Identifies the type of information in the Security Information (ISA-03). Default is `00 - No Security Information Present`.
enum:
- '00'
- '01'
X12Delimiters:
type: object
properties:
element:
type: string
pattern: ^[\W|_]{1}$
description: The data element separator character.
composite:
type: string
pattern: ^[\W|_]{1}$
description: The component element separator character.
repetition:
type: string
pattern: ^[\W|_]{1}$
description: The repetition separator character.
segment:
type: string
pattern: ^[\W|_]{1}$
description: The segment terminator character.
required:
- composite
- element
- repetition
- segment
ResourceUnderChangeExceptionResponseContent:
type: object
properties:
message:
type: string
required:
- message
GenerateEdiResponseContent:
type: object
properties:
edi:
type: string
description: The EDI Stedi generated from the JSON transaction data.
artifactId:
type: string
description: An ID for the generated EDI file.
fileExecutionId:
type: string
description: A ID for the process Stedi uses to generate the EDI file. This ID appears on the details page for this file execution in the Stedi portal. Internally, Stedi uses this ID to place the file in Stedi's outbound queue.
metadata:
$ref: '#/components/schemas/Metadata'
required:
- artifactId
- fileExecutionId
- metadata
BadRequestExceptionResponseContent:
type: object
description: The server cannot process the request due to an apparent client error.
properties:
message:
type: string
code:
type: string
required:
- message
securitySchemes:
httpApiKeyAuth:
description: A [Stedi API Key](https://www.stedi.com/app/settings/api-keys) for authentication.
in: header
name: Authorization
type: apiKey
x-stedi:
lifecycle: general_availability
product: claims
public: true