Customize the ISA and GS headers

You can customize an EDI file’s Interchange (ISA) and Group (GS) headers - also known as the envelope - using the Create Outbound Interchange endpoint.

If you don’t need to customize the envelope, we strongly recommend generating EDI files with the Create Outbound Transaction endpoint instead because it is simpler and easier to use.

Interchange overrides

You can customize the following elements in the ISA header:

• Interchange Authorization values (ISA01 to ISA04): Some trading partners require additional information in these elements to verify the transaction.
• Interchange Version Control Number Code (ISA12): Stedi defaults to using the X12 release number of the guide associated with the transaction. However, some partners require a different release for the ISA envelope.
• Acknowledgment Requested Code (ISA14): This code indicates whether you are requesting a TA1 Interchange Acknowledgments.
• Interchange Usage Indicator Code (ISA15): This code indicates whether data is test, production, or information. Stedi defaults to P for production data, but you may need to set this to T when sending test data.

Visit the Create Outbound Transaction documentation for more details.

cURL request

curl --location 'https://core.us.stedi.com/2023-08-01/x12/partnerships/<PARTNERSHIP_ID>/generate-edi' \
--header 'Content-Type: application/json' --header "Authorization: ${STEDI_API_KEY}" \
--data-raw '{
  "filename": "my-output-file.edi",
  "overrides": {
    "acknowledgmentRequestedCode": "1",
    "interchangeUsageIndicator": "T",
    "interchangeControlVersionNumberCode": "00200"
  },
  "transactionGroups": [
    {
      "transactionSettingId": "<TRANSACTION_SETTING_ID>",
      "transactions": [
        {
          "heading": {},
          "detail": {},
          "summary": {}
        }
      ]
    }
  ]
}'

{
  "edi": "ISA*00*          *00*          *ZZ*THISISME       *14*ANOTHERMERCH   *230628*1159*U*00200*000000024*1*T*>~GS*PO*MINE*MYAPPID*20230628*115907*000000024*X*005010~ST*850*0001~BEG*00*DS*365465413**20220830~REF*CO*ACME-4567~REF*ZZ*Thank you for your business~PER*OC*Marvin Acme*TE*973-555-1212*EM*[e-mail]~TD5****ZZ*FHD~N1*ST*Wile E Coyote*92*123~N3*111 Canyon Court~N4*Phoenix*AZ*85001*US~PO1*item-1*0008*EA*400**VC*VND1234567*SK*ACM/8900-400~PID*F****400 pound anvil~PO1*item-2*0004*EA*125**VC*VND000111222*SK*ACM/1100-001~PID*F****Detonator~CTT*2~AMT*TT*3700~SE*16*0001~GE*1*000000024~IEA*1*000000024~",
  "artifactId": "my-output-file.edi",
  "fileExecutionId": "b70199fa-4a11-4610-861e-aa7fff4ae09b"
}

Group overrides

By default, Stedi generates EDI files using the application IDs (GS-02 and GS-03 elements) configured for each profile within the partnership. However, some partners use multiple application IDs to route files to different locations.

To set custom application IDs, set the localApplicationId and the partnerApplicationId properties in the override object. These values are optional; you should only send them when you need to override the application IDs configured within each profile.

You can include multiple overrides objects to customize the application IDs for each transaction group in the file.

cURL request

curl --location 'https://core.us.stedi.com/2023-08-01/x12/partnerships/<PARTNERSHIP_ID>/generate-edi' \
--header 'Content-Type: application/json' --header "Authorization: ${STEDI_API_KEY}" \
--data-raw '{
  "filename": "my-output-file.edi",
  "transactionGroups": [
    {
      "transactionSettingId": "<TRANSACTION_SETTING_ID>",
      "overrides": {
        "localApplicationId": "LOC1",
        "partnerApplicationId": "PART1"
      },
      "transactions": [
        {
          "heading": {},
          "detail": {},
          "summary": {}
        }
      ]
    },
     {
      "transactionSettingId": "<TRANSACTION_SETTING_ID>",
      "overrides": {
        "localApplicationId": "LOC2",
        "partnerApplicationId": "PART2"
      },
      "transactions": [
        {
          "heading": {},
          "detail": {},
          "summary": {}
        }
      ]
    }
  ]
}'

{
  "edi": "ISA*00*          *00*          *ZZ*THISISME       *14*ANOTHERMERCH   *230628*1159*U*00501*000000024*1*T*>~GS*PO*LOC*PART*20230628*115907*000000024*X*005010~ST*850*0001~BEG*00*DS*365465413**20220830~REF*CO*ACME-4567~REF*ZZ*Thank you for your business~PER*OC*Marvin Acme*TE*973-555-1212*EM*[e-mail]~TD5****ZZ*FHD~N1*ST*Wile E Coyote*92*123~N3*111 Canyon Court~N4*Phoenix*AZ*85001*US~PO1*item-1*0008*EA*400**VC*VND1234567*SK*ACM/8900-400~PID*F****400 pound anvil~PO1*item-2*0004*EA*125**VC*VND000111222*SK*ACM/1100-001~PID*F****Detonator~CTT*2~AMT*TT*3700~SE*16*0001~GE*1*000000024~IEA*1*000000024~",
  "artifactId": "my-output-file.edi",
  "fileExecutionId": "b70199fa-4a11-4610-861e-aa7fff4ae09b"
}

Call the Interchange API

The Create Outbound Interchange endpoint can generate fully-formed EDI files containing multiple transactions and even multiple transaction types.

Request data

The API uses the following data to generate and deliver an EDI file.

Data	Required	Description
partnershipId	Yes	Include this ID within the API route to identify the associated partnership. You can find this ID on the Trading partners page under Partnership identifier.
transactionGroups	Yes	The Generate API accepts multiple arrays of transactions in a single API call, allowing you to send multiple transactions or even multiple functional groups in a single file. If you only plan to send a single type of transaction (such as a Purchase Order), then your API request should have one transaction group.
transactionGroups.transactionSettingId	Yes	This ID specifies the outbound transaction setting Stedi should use to validate the transaction data and generate the file. To find this ID, go to the partnership, find the outbound transaction setting, and copy its Transaction Setting ID.
transactionGroups.transactions	Yes	This object contains the transaction data. It must conform to the Guide JSON format for the specified transaction setting.
filename		Specify the name of 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 a UUID.
Envelope overrides		You can use several optional parameters to customize aspects of the EDI envelope - both the ISA header and GS header.

Sample request and response

The following example shows a cURL request and response.

The API returns the full X12 EDI file in the response. The response also includes an artifactId (equivalent to the file name) and a globally unique fileExecutionId that you can use to locate the generated file.

cURL request (abbrieviated)

curl --request POST \
  --url https://core.us.stedi.com/2023-08-01/x12/partnerships/{partnershipId}/generate-edi \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filename": "<OPTIONAL_FILENAME>",
  "transactionGroups": [
    {
      "transactionSettingId": "<TRANSACTION_SETTING_ID>",
      "transactions": [
        {
          "heading": {},
          "detail": {}
        }
      ]
    }
  ]
}'

curl --request POST \
  --url https://core.us.stedi.com/2023-08-01/x12/partnerships/{partnershipId}/generate-edi \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filename": "test-interchange.edi",
  "transactionGroups": [
    {
      "transactionSettingId": "005010X220A1-834",
      "transactions": [
        {
          "heading": {
            "transaction_set_header_ST": {
              "transaction_set_identifier_code_01": "834",
              "transaction_set_control_number_02": 12345,
              "implementation_convention_reference_03": "005010X220A1"
            },
            "beginning_segment_BGN": {
              "transaction_set_purpose_code_01": "00",
              "transaction_set_reference_number_02": "12456",
              "transaction_set_creation_date_03": "2002-06-01",
              "transaction_set_creation_time_04": "12:00",
              "action_code_08": "2"
            },
            "transaction_set_policy_number_REF": {
              "reference_identification_qualifier_01": "38",
              "master_policy_number_02": "ABCD012354"
            },
            "sponsor_name_N1_loop": {
              "sponsor_name_N1": {
                "entity_identifier_code_01": "P5",
                "identification_code_qualifier_03": "FI",
                "sponsor_identifier_04": "999888777"
              }
            },
            "payer_N1_loop": {
              "payer_N1": {
                "entity_identifier_code_01": "IN",
                "identification_code_qualifier_03": "FI",
                "insurer_identification_code_04": "654456654"
              }
            }
         },
         "detail": {
            "member_level_detail_INS_loop": [
              {
                "member_level_detail_INS": {
                  "member_indicator_01": "Y",
                  "individual_relationship_code_02": "18",
                  "maintenance_type_code_03": "025",
                 "benefit_status_code_05": "A",
                  "employment_status_code_08": "FT"
                },
                "subscriber_identifier_REF": {
                  "reference_identification_qualifier_01": "0F",
                   "subscriber_identifier_02": "202443307"
                },
                "member_policy_number_REF": {
                  "reference_identification_qualifier_01": "1L",
                  "member_group_or_policy_number_02": "123456001"
                },
                "member_name_NM1_loop": {
                  "member_name_NM1": {
                    "entity_identifier_code_01": "IL",
                    "entity_type_qualifier_02": "1",
                    "member_last_name_03": "SMITH",
                    "member_first_name_04": "WILLIAM",
                    "identification_code_qualifier_08": "ZZ",
                    "member_identifier_09": "202443307"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}'

{
  "edi":"ISA*00*          *00*          *ZZ*LOCAL          *ZZ*TEST           *250519*2310*^*00501*000000002*0*P*>~GS*BE*LOCAL*TEST*20250519*231001*2*X*005010X220A1~ST*834*12345*005010X220A1~BGN*00*12456*20020601*1200****2~REF*38*ABCD012354~N1*P5**FI*999888777~N1*IN**FI*654456654~INS*Y*18*025**A***FT~REF*0F*202443307~REF*1L*123456001~NM1*IL*1*SMITH*WILLIAM****ZZ*202443307~SE*10*12345~GE*1*2~IEA*1*000000002~",
  "artifactId":"test-interchange.edi","fileExecutionId":"f47a0697-d06c-47f0-a5a5-fa79994f3ce0"
}