Create outbound transaction

Generate and deliver fully-formed EDI files to your trading partners with the Create Outbound Transaction endpoint.

This is the simplest way to send EDI files with Stedi.

​

Format transaction data

Unless you’re using mappings, you must submit transaction data to the API in Guide JSON, a format that matches the JSON Schema of the guide associated with the outbound transaction setting.

​

Guide JSON schema

To find the JSON Schema for a transaction:

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. This is the JSON Schema you must use when sending transaction data to the API. You must include every segment and element marked as required in the guide.

You can also 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.

​

Mapping ID and schema

You can optionally specify a mapping to transform transaction data from your system into Guide JSON format. In this case, you must send data to the API in the mapping’s source JSON Schema.

To find the mapping ID and schema:

1. Go to the Mappings page and copy the ID field for the mapping you want to use.
2. Click the mapping’s name to view its details.
3. Click Test mapping. The test input JSON shape is the shape you must use when sending transaction data to the API.

​

Call the API

When you call the Create Outbound Transaction endpoint, Stedi:

1. Applies the mapping (if present) to the provided transaction data.
2. Adds fragments from specified fragment groups (if present).
3. Generates an EDI file according to the Stedi guide attached to the outbound transaction setting. This includes adding required envelope information (ISA and GS headers) and autogenerated control numbers.
4. Delivers the EDI file to your trading partner through the connection specified in the outbound transaction setting.

​

Create request

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

Data	Required	Description
API key	Yes	You must pass a Stedi API key in the Authorization header of every request. You can create an API key in the Stedi app.
partnershipId	Yes	Include this ID in the API route to identify the associated partnership. You can find this ID on the Trading partners page under Partnership identifier.
transactionSettingId	Yes	Include this ID in the API route to identify 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.
transaction	Yes	This payload contains the transaction data. Without a mapping, this transaction data must be < 5MB and the shape must match the Guide JSON format for the specified outbound transaction setting. With a mapping, this transaction data must be < 4MB and the shape must match the mapping’s source schema.
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. The filename you specify here takes precedence over the Filename expression (if present) set on the outbound transaction setting. If you do not specify a filename, and there isn’t one set on the outbound transaction setting, Stedi autogenerates a unique name using a UUID.
fragmentGroupIds		Specify which fragments Stedi should insert into the transaction. Visit outbound fragments for details.
mappingId		Specify the mapping Stedi should use to transform the transaction data to Guide JSON format.

​

Sample request and response

The following example shows a cURL request and response.

The API returns a globally unique fileExecutionId that you can use to locate the generated file.

​

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 API to send 997s or 999s. Visit Acknowledgments for details on enabling this functionality.

​

Timezone and time format

Stedi uses the following default values:

• Timezone: UTC | Used in the ISA and GS segments
• Time format: HHMMSS | The GS-05 time element

You can change these values in the partnership’s Advanced settings menu.

​

Character sets

By default, Stedi doesn’t enforce any character restrictions for outbound files. As long as the payload is valid JSON that meets the guide’s JSON Schema, Stedi can generate an EDI file and deliver it to your trading partner.

However, some trading partners may have restrictions on the characters they can accept. For example, certain partners may only accept a subset of characters called the Basic Character Set, which doesn’t include lowercase or special characters. Others may accept the Extended Character Set, which has a more expansive set of character options. Others in the healthcare industry may use the HIPAA Extended Character Set, which is a subset of the Extended Character Set (note that HIPAA guidelines require the use of either the Basic or HIPAA Extended character set for HIPAA transactions).

​

Restrict characters in outbound files

You can select a character set to use when generating outbound files in the partnership’s Advanced settings menu.

Once you select a character set, Stedi rejects EDI generation requests that contain characters outside of the specified set. For example, if you select the Basic character set, Stedi rejects requests that contain lowercase letters and other unsupported characters.

There are three character set options.

​

Basic Character Set

Includes uppercase letters, digits, space, and some special characters. Lowercase letters and special language characters like ñ are not included.

In order to be compliant with X12 HIPAA guidelines, all trading partners must support the Basic Character Set at a minimum.

The following special characters are included:

​

HIPAA Extended Character Set

Includes the characters listed in Basic, plus lowercase letters and additional special characters, such as @ and #.

X12 HIPAA guidelines state the following:

In the absence of a specific trading partner agreement to the contrary, trading partners will assume that the [HIPAA] extended character set is acceptable.

The following additional special characters are included:

​

Standard Extended Character Set

Includes the characters in HIPAA Extended, plus select additional language characters, such as ñ. The standard Extended Character Set is the most common character set outside of healthcare (for example, in retail and logistics).

According to HIPAA guidelines, the Standard Extended character set is not allowed in HIPAA-compliant transactions (see X12 RFI 2212).

The following additional language characters are included:

​

Character set questionnaire

You can send the X12 Character Set questionnaire to your trading partners to determine which characters they support, and thus which character set you should use when generating outbound files.

​

Custom filenames

You can specify a custom filename for the generated EDI file either in the outbound transaction setting or with the filename field in your API request. If you don’t specify a filename, Stedi autogenerates one using a UUID.

​

Payload limits

Without a mapping, the Create Outbound Transaction endpoint accepts payloads up to 5MB. With a mapping, the payload must be < 4MB. You can use outbound fragments to split larger transactions into smaller chunks before sending them to the API.

If this presents issues for your integration, please let us know, and we can help develop a solution.