Create Outbound Interchange

This endpoint generates and delivers fully-formed EDI files to your trading partners.

POST /x12/partnerships/{partnershipId}/generate-edi

When you call this endpoint, Stedi:

1. Generates a single EDI file containing all transactions according to the Stedi guide attached to each outbound transaction setting. This includes adding required envelope information (ISA and GS headers) and autogenerated control numbers.
2. Delivers the EDI file to your trading partner through the connection specified in the transaction settings.

Transaction data

You must provide transaction data in Guide JSON format. The transaction data must be < 5MB.

Delivery attempts

Stedi attempts to deliver a file to all configured connections every 6 minutes for up to 3 total attempts. If it cannot deliver the file after the third attempt, it marks the file execution as FAILED and emits the file.failed.v2 event. Stedi displays each delivery attempt and the failure details on the Files page.

Customize generated files

You can change the timezone, time format, character set (which characters are allowed), and filename for generated files. Learn more.

Inbound processing

There is no equivalent endpoint for parsing EDI files into JSON. To parse inbound files, you or your partner can send EDI files to an SFTP/FTPS or AS2 connection, and Stedi sends the JSON payload to the configured Destination webhook.

Authorizations

Authorization · Required Header

A Stedi API Key for authentication.

Path Parameters

partnershipId · String Regex pattern: ^([a-zA-Z0-9._-]+)$ Length: 1 - 81

A unique ID for this partnership within Stedi. You can find this ID on the Trading partners page under Partnership identifier.

Headers

Idempotency-Key · String

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.

Body

application/json

characterSet · String

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.

Possible values

Basic

Extended

ExtendedHipaa

repairOptions · Object

Options for repairing EDI data during generation to ensure it meets X12 requirements

trimTrailingSpaces · repairOptions.trimTrailingSpaces · Boolean

Whether to trim trailing spaces from data elements

uppercase · repairOptions.uppercase · Boolean

Whether to convert text to uppercase

replaceConfusable · repairOptions.replaceConfusable · Boolean

Whether to replace characters that are visually similar but technically different

removeDiacritical · repairOptions.removeDiacritical · Boolean

Whether to remove diacritical marks from characters

trimTrailingZeroes · repairOptions.trimTrailingZeroes · Boolean

Whether to trim trailing zeros from numeric data elements

transactionGroups · Array of Objects Required Min items: 1

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.

transactionSettingId · transactionGroups[].transactionSettingId · String Required Regex pattern: ^([a-zA-Z0-9_-]+)$ Max length: 50

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 · transactionGroups[].transactions · Array of Items Required Min items: 1

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 · transactionGroups[].overrides · Object

Customize the Application IDs for you or your trading partner.

localApplicationId · transactionGroups[].overrides.localApplicationId · String Length: 2 - 15

Set the GS-02 element to a custom value. If not set, Stedi uses the Application ID for the local profile associated with the partnership.

partnerApplicationId · transactionGroups[].overrides.partnerApplicationId · String Length: 2 - 15

Set the GS-03 element to a custom value. If not set, Stedi uses the Application ID for the partner profile associated with the partnership.

filename · String Regex pattern: ^([a-zA-Z0-9.*'()!_-]+)$ Length: 1 - 300

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 · Object

interchangeUsageIndicator · overrides.interchangeUsageIndicator · String

Set ISA-15 to a different value. If not set, the default value is P (Production Data).

Possible values

I

T

P

acknowledgmentRequestedCode · overrides.acknowledgmentRequestedCode · String

Set ISA-14 to a different value. If not set, the default value is 0 (No Interchange Acknowledgment Requested).

Possible values

0

1

2

3

interchangeControlVersionNumberCode · overrides.interchangeControlVersionNumberCode · String Length: 5

Set 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 · overrides.delimiters · Object

element · overrides.delimiters.element · String Required Regex pattern: ^[\W|_]{1}$

The data element separator character.

composite · overrides.delimiters.composite · String Required Regex pattern: ^[\W|_]{1}$

The component element separator character.

repetition · overrides.delimiters.repetition · String Required Regex pattern: ^[\W|_]{1}$

The repetition separator character.

segment · overrides.delimiters.segment · String Required Regex pattern: ^[\W|_]{1}$

The segment terminator character.

interchangeUsageIndicatorOverride · String

Set ISA-15 to a different value. If not set, the default value is P (Production Data).

Possible values

I

T

P

interchangeAuthorization · Object

Set values for ISA header elements (ISA-01 to ISA-04).

authorizationInformationQualifier · interchangeAuthorization.authorizationInformationQualifier · String

Identifies the type of information in the Authorization Information (ISA-01). Default is 00 - No Authorization Information Present.

Possible values

00

01

02

03

04

authorizationInformation · interchangeAuthorization.authorizationInformation · String Regex pattern: ^.*[^ ].*$ Max length: 10

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 · interchangeAuthorization.securityInformationQualifier · String

Identifies the type of information in the Security Information (ISA-03). Default is 00 - No Security Information Present.

Possible values

00

01

securityInformation · interchangeAuthorization.securityInformation · String Regex pattern: ^.*[^ ].*$ Max length: 10

The security information referenced by the securityInformationQualifier (ISA-04). Typically, this is a password.

Response

application/json

GenerateEdi 200 response

edi · String

The EDI Stedi generated from the JSON transaction data.

artifactId · String Required

An ID for the generated EDI file.

fileExecutionId · String Required

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 · Object Required

Metadata about the generated EDI file.

interchangeMetadata · metadata.interchangeMetadata · Array of Objects Required Min items: 1

A list of interchange metadata for all interchanges in the EDI file.

interchangeControlNumber · metadata.interchangeMetadata[].interchangeControlNumber · Number Required Range: ≥ 0 and ≤ 999999999

functionalGroupControlNumbers · metadata.interchangeMetadata[].functionalGroupControlNumbers · Array of Numbers Required Min items: 1

A list of functional group control numbers within an interchange.

cURL

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

JavaScript

const body = JSON.stringify({
  "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
            }
          }
        }
      ]
    }
  ]
})

fetch("https://core.us.stedi.com/2023-08-01/x12/partnerships/{partnershipId}/generate-edi", {
  headers: {
    "Authorization": "<api_key>"
  },
  body
})

Go

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  url := "https://core.us.stedi.com/2023-08-01/x12/partnerships/{partnershipId}/generate-edi"
  body := strings.NewReader(`{
    "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
              }
            }
          }
        ]
      }
    ]
  }`)
  req, _ := http.NewRequest("POST", url, body)
  req.Header.Add("Authorization", "<api_key>")
  req.Header.Add("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

Python

import requests

url = "https://core.us.stedi.com/2023-08-01/x12/partnerships/{partnershipId}/generate-edi"
body = {
  "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
            }
          }
        }
      ]
    }
  ]
}
response = requests.request("POST", url, json = body, headers = {
  "Authorization": "<api_key>",
  "Content-Type": "application/json"
})

print(response.text)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;
import java.net.http.HttpRequest.BodyPublishers;

var body = BodyPublishers.ofString("""{
  "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
            }
          }
        }
      ]
    }
  ]
}""");
HttpClient client = HttpClient.newBuilder()
  .connectTimeout(Duration.ofSeconds(10))
  .build();

HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
  .uri(URI.create("https://core.us.stedi.com/2023-08-01/x12/partnerships/{partnershipId}/generate-edi"))
  .header("Content-Type", "application/json")
  .header("Authorization", "<api_key>")
  .POST(body)
  .build();

try {
  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());
  System.out.println("Status code: " + response.statusCode());
  System.out.println("Response body: " + response.body());
} catch (Exception e) {
  e.printStackTrace();
}

200

{
  "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

{
  "message": "string",
  "code": "string"
}

401

{
  "message": "string",
  "code": "string"
}

403

{
  "message": "string",
  "code": "string"
}

404

{
  "message": "string",
  "code": "string"
}

409

{
  "message": "string"
}

429

{
  "message": "string",
  "code": "string"
}

500

{
  "message": "string",
  "cause": {
    "name": "string",
    "message": "string",
    "stack": "string"
  }
}

503

{
  "message": "string",
  "code": "string"
}

504

{
  "message": "string",
  "code": "string"
}