Once you add a trading partner, you can use Stedi’s API to generate and deliver fully-formed EDI files to your trading partners.

​
Get a Stedi API key

You need an API key to use any Stedi API. You pass the API key in the Authorization header of every request, and it determines which resources you can access.

You can create an API key in the Stedi app.

​
Create request

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

DataRequiredDescription
partnershipIdYesYou must 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.
transactionSettingIdYesThis ID specifies the 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.
transactionsYesThis payload contains the transaction data. It must conform to the JSON Schema for the guide associated with each transaction setting. 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.
filenameSpecify 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 overridesYou can use several optional parameters to customize aspects of the EDI envelope (both the ISA and GS portions).

Visit the Generate EDI API documentation for a full list of request and response parameters.

​
Call the API

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 --location 'https://core.us.stedi.com/2023-08-01/x12/partnerships/<PARTNERSHIP_ID>/generate-edi' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: ${STEDI_API_KEY}" \
  --data '{
  "filename": "<OPTIONAL_FILENAME>",
  "transactionGroups": [
    {
      "transactionSettingId": "<TRANSACTION_SETTING_ID>",
      "transactions": [
        {
          "heading": {},
          "detail": {},
          "summary": {}
        }
      ]
    }
  ]
}'

​
Format transaction data

The transaction payload must match the JSON Schema of the guide associated with the outbound transaction setting.

You have three options to programatically transform your system’s format into Guide JSON prior to calling the Generate EDI API. Visit Transformation approaches for details.

​
Find a guide’s JSON schema

To find the JSON Schema for a guide:

  1. Navigate to the Trading partners page.
  2. Select the partnership.
  3. Click the name of the guide associated with the outbound transaction setting.
  4. Open the Actions menu and select View schema.
  5. Copy the schema. The transaction_set_trailer_SE object is marked as optional. You do not need to include it because Stedi does not use it to generate EDI files.
  6. Save this as a .json file. This file contains the schema you must use when sending payloads to the Generate EDI API.

​
Generate sample Guide JSON

You can use the send outbound test files feature to generate a sample JSON payload that matches your guide’s JSON Schema. You can then edit the sample payload as needed.

​
Use Stedi Mappings

This functionality is available in a Stedi module. Contact us for details.

The Stedi Mappings module is a powerful JSON-to-JSON transformation engine. Once you create a mapping for an outbound transaction setting, you can use it to transform JSON from your business systems into Guide JSON.

  1. Invoke your mapping. The endpoint returns the mapped data in Guide JSON format.
  2. Use the Guide JSON to create a request for the Generate EDI API.

​
Envelope overrides

You can customize aspects of the Interchange (ISA) and Group (GS) headers in the generated file, also known as the envelope.

​
Interchange

Stedi generates EDI files with the following interchange envelope defaults:

  • Acknowledgment Requested Code (ISA-14) set to 0 (No Interchange Acknowledgment Requested)
  • Interchange Usage Indicator Code (ISA-15) set to P (Production Data) However some partnership agreements may require the use of TA1 Interchange Acknowledgments, and integration testing may require sending test data via the API.
  • Interchange Version Control Number Code (ISA-12) set to the X12 version number of the guide associated with the transaction setting.

To request interchange acknowledgments, or indicate that an EDI file contains test data, set the acknowledgmentRequestedCode or interchangeUsageIndicator respectively. You can also set a custom interchangeControlVersionNumberCode to override the default X12 version number.

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": {}
        }
      ]
    }
  ]
}'

​
Group

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 for an EDI file, 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.

If you are sending multiple transaction groups in a single file, you can include multiple overrides objects to customize the application IDs for each group.”

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": {}
        }
      ]
    }
  ]
}'

​
Acknowledgments

Stedi can automatically generate 997 or 999 acknowledgments for every inbound transaction associated with a partnership, so you should not need to use the Generate API to send 997s or 999s. Visit Acknowledgments for details on enabling this functionality.

​
Limits

The Generate EDI API accepts JSON payloads up to 5MB in size. If this presents issues for your integration, please reach out and we can help develop a solution.

Was this page helpful?