# Customize the ISA and GS headers
Source: https://www.stedi.com/docs/edi-platform/operate/generate-edi/envelope-overrides

***

title: Customize the ISA and GS headers
sidebarTitle: "Customize the envelope"
--------------------------------------

You can customize an EDI file's Interchange (`ISA`) and Group (`GS`) headers - also known as the envelope - using the [Create Outbound Interchange](/edi-platform/api-reference/post-generate-edi) endpoint.

<Tip>
  If you don't need to customize the envelope, we strongly recommend generating
  EDI files with the [Create Outbound
  Transaction](/edi-platform/operate/generate-edi) endpoint instead because it
  is simpler and easier to use.
</Tip>

## 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](/edi-platform/api-reference/post-transactions) documentation for more details.

<Tabs items={["cURL request", "Response"]}>
  <Tab value="cURL request">
    ```shell
    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": {}
            }
          ]
        }
      ]
    }'
    ```
  </Tab>

  <Tab value="Response">
    ```json
    {
      "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*marvin@acme.com~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"
    }
    ```
  </Tab>
</Tabs>

## 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.

<Tabs items={["cURL request", "Response"]}>
  <Tab value="cURL request">
    ```shell
    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": {}
            }
          ]
        }
      ]
    }'
    ```
  </Tab>

  <Tab value="Response">
    ```json
    {
      "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*marvin@acme.com~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"
    }
    ```
  </Tab>
</Tabs>

## Call the Interchange API

The [Create Outbound Interchange](/edi-platform/api-reference/post-generate-edi) 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](https://portal.stedi.com/app/core/partnerships) 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](/edi-platform/operate/transform-json/guide-json) 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](#interchange-overrides) and [`GS` header](#group-overrides).                                                                                                                                                   |

### 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.

<Tabs items={["cURL request (abbrieviated)", "cURL request (full)", "Response"]}>
  <Tab value="cURL request (abbrieviated)">
    ```shell
    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": {}
            }
          ]
        }
      ]
    }'
    ```
  </Tab>

  <Tab value="cURL request (full)">
    ```shell
    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"
                      }
                    }
                  }
                ]
              }
            }
          ]
        }
      ]
    }'
    ```
  </Tab>

  <Tab value="Response">
    ```json
    {
      "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"
    }
    ```
  </Tab>
</Tabs>