X12 Operations Last updated: 2026-11-10

With EDI API you can translate X12 files to JSON, translate JSON to X12 files, validate X12 transactions, and generate X12 997 and 999 acknowledgments. API v3 does all of this with two operations, Parse X12 and Build X12. API v2 has separate operations.

API versions

The base URL is https://api.edination.com/v3 for v3 and https://api.edination.com/v2 for v2. v3 only supports X12 for now, so both versions are available side by side until v3 supports all EDI formats. See API versions.

Operation	Path	Version
Parse X12	`/x12/parse`	v3
Build X12	`/x12/build`	v3
Read X12	`/x12/read`	v2
Write X12	`/x12/write`	v2
Validate X12	`/x12/validate`	v2
Acknowledge X12	`/x12/ack`	v2

A Parse call counts as one operation in every mode. Translating, validating and acknowledging a file costs one operation on v3, where separate read, validate and ack calls on v2 cost three.

Parse X12

v3 only. Takes an X12 file and returns its JSON, optionally with validation results and acknowledgments, in one call.

Path: /x12/parse
HTTP Verb: POST
Required API Key: Ocp-Apim-Subscription-Key
Request body: a raw X12 file, as binary. Multipart form data and JSON are not supported.
Request Content-Type: application/octet-stream. Any other value returns HTTP 415.
Request limit: 5 MB
Response Content-Type: application/json in mode 1, application/octet-stream in modes 2 and 3
Response header: X-EdiFabric-Offset, where the report starts in the response

Modes

Mode	Name	Instead of, on v2	Response
`1`	`Json`	`/x12/read`	An array of X12Interchange objects. `X-EdiFabric-Offset` is 0.
`2`	`JsonValidate`	`/x12/validate`	The same array, followed by the validation report.
`3`	`JsonValidateAck`	`/x12/ack`	The same array, followed by the validation report with the acknowledgment in `ack`.

Read the response

In modes 2 and 3 the response is two JSON documents back to back, so it is not valid JSON as a whole. Split the body at the byte offset in X-EdiFabric-Offset: the bytes before it are the interchanges, and the bytes from it onwards are the report.

curl -X POST "https://api.edination.com/v3/x12/parse?mode=3" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SERIAL_KEY" \
  -H "Content-Type: application/octet-stream" \
  -D headers.txt -o response.bin \
  --data-binary @purchase-order.edi

import json, requests

res = requests.post(
    "https://api.edination.com/v3/x12/parse",
    params={"mode": 3},
    headers={"Ocp-Apim-Subscription-Key": "YOUR_SERIAL_KEY",
             "Content-Type": "application/octet-stream"},
    data=open("purchase-order.edi", "rb"))
res.raise_for_status()

offset = int(res.headers["X-EdiFabric-Offset"])
interchanges = json.loads(res.content[:offset])
report = json.loads(res.content[offset:])

Errors

200: Success. Validation errors in the file are returned in the report.
400: The request body is empty, or mode, config or charSet is invalid. The model or a transaction in the file can't be found, for example parse: error 201: Model MyModel was not found.
413: The request body is larger than 5 MB.
415: The Content-Type is not application/octet-stream.
500: The file could not be translated, or something went wrong on our end. Details has the reason, for example parse: error 429: Can't find ISA segment.

Parameters

mode enumeration

One of the modes above, as the number or the name. The default is 1.
charSet string

The encoding of the X12 file. The default is utf-8. The available values are utf-8, utf-16, unicodeFFFE, utf-32, utf-32BE, us-ascii and iso-8859-1.
model string

The model to use, by its identifier, for example EdiNation.X12.HIPAA.005010 or the name of a custom model that you manage in the EDI Spec Builder. By default, the API will infer the model based on the transaction and version identifiers, and will use the closest model for versions without a model of their own. The Model property in the response shows which model was used.

The identifier is case-sensitive and can end with .dll. The model applies to every transaction in the request, so it must contain each transaction and version in the file. If it doesn't, the API returns an error and doesn't try another model. When you change or delete a custom model in the EDI Spec Builder, the change takes effect within about a minute.
config string

The validation and acknowledgment options, as URL-escaped JSON. All sections and properties are optional. validate applies in modes 2 and 3, and ack in mode 3.

{
  "validate": {
    "snip_level": 2,
    "max_errors": 100,
    "regex": null,
    "date_format": null,
    "time_format": null,
    "skip_seq_count": false,
    "skip_hl_seq": false
  },
  "ack": {
    "gen997": false,
    "gen_for_valid": false,
    "supress_ta1": false,
    "ak901_p": false
  }
}

Config options

validate.snip_level integer
The validation level, from 1 to 4: 1 syntax only, 2 limits and codes, 3 balancing, 4 inter-segment. The default is 2.
validate.max_errors integer
The maximum number of errors to report. The default is 100.
validate.regex string
A regular expression that alphanumeric data elements must match. By default, no syntax set is applied.
validate.date_format string
The date pattern to validate against, for example yyyyMMdd. By default, 6-digit dates use yyMMdd and 8-digit dates use yyyyMMdd.
validate.time_format string
The time pattern to validate against. By default, the pattern follows the length of the value.
validate.skip_seq_count boolean
Whether to skip validating sequence numbers that the model defines. The default is false.
validate.skip_hl_seq boolean
Whether to skip validating that HL segments are numbered in sequence. The default is false.
ack.gen997 boolean
Whether to generate a 997 instead of a 999. The default is false, so v3 generates a 999 by default, while v2 generates a 997.
ack.gen_for_valid boolean
Whether to include acknowledgment loops for valid transactions as well. The default is false.
ack.supress_ta1 boolean
Whether to suppress the TA1 that X12Interchange.ISA.AcknowledgementRequested_14 asks for. The default is false.
ack.ak901_p boolean
Whether to set the first element of AK9 to "P" when only some transactions are accepted. The default is false.

The spelling of supress_ta1 and ak901_p is intentional.

Build X12

v3 only. Translates JSON to a raw X12 interchange and returns it as a stream.

Path: /x12/build
HTTP Verb: POST
Required API Key: Ocp-Apim-Subscription-Key
Request body: an X12Interchange object or an array of them, in the v3 format
Request Content-Type: application/json. Any other value returns HTTP 415.
Request limit: 50 MB
Response Content-Type: application/octet-stream; charset=utf-8

Trailers

Build writes the segments in the JSON as they are. Unlike v2 Write, it does not add missing trailers, so include SE, GE and IEA with the correct counts.

Errors

200: Success
400: The request body is empty.
413: The request body is larger than 50 MB.
415: The Content-Type is not application/json.
500: The JSON is invalid, including v2 JSON with GETrailers or IEATrailers, or something went wrong on our end. Details has the reason, for example build: error 637: Invalid JSON.

Parameters

postfix string

The postfix to apply at the end of each segment, just after the segment separator. URL-escape it, for example %0D%0A for a new line. By default, there is none.

Moving from v2 to v3

v3 does not have the v2 operations, so moving means changing your calls. The JSON also differs, as described in X12 Resources.

v3 has no model operations and is not compatible with the v2 Model operations. All custom model operations are in the EDI Spec Builder. The EDI Spec Builder needs a free ediFabric account on the Community plan or a paid plan.

v2	v3	What changes
`/x12/read`	`/x12/parse`, mode 1	`charSet` and `model` stay. There is no `Result`: a file that can't be translated returns an HTTP error instead of 200, and a secondary model doesn't add a warning. There is no multipart upload, `ignoreNullValues` or `continueOnError`.
`/x12/write`	`/x12/build`	`postfix` stays. Missing trailers are not added. The delimiters come from the JSON. There is no `preserveWhitespace` or `charSet`, and the output is UTF-8 without a byte order mark.
`/x12/validate`	`/x12/parse`, mode 2	The body is a raw X12 file instead of JSON. To validate an X12Interchange, call Build X12 first, which counts as a separate operation. The response has the JSON, then a validation report instead of an OperationResult. `basicSyntax` and `syntaxSet` become `validate.regex`, and `structureOnly` becomes `validate.snip_level` 1. There is no `skipTrailer`.
`/x12/ack`	`/x12/parse`, mode 3	The body is a raw X12 file instead of JSON. To acknowledge an X12Interchange, call Build X12 first, which counts as a separate operation. The acknowledgment is raw X12 in the validation report instead of an X12Interchange, and the default is a 999 instead of a 997. `ack=997` becomes `ack.gen997`, `ackForValidTrans` becomes `ack.gen_for_valid`, `technicalAck` becomes `ack.supress_ta1`, and `ak901isP` becomes `ack.ak901_p`. There is no `batchAcks`, `detectDuplicates` or reference number parameters.

Read X12

Reads an X12 file and returns its contents translated to JSON as an array of X12Interchange objects.

v2 only. On v3, use Parse X12 in mode 1.

Path: /x12/read
HTTP Verb: POST
Required API Key: Ocp-Apim-Subscription-Key
Request Content-Type: application/octet-stream or multipart/form-data
Request limit: 3 MB
Response Content-Type: application/json

Errors

200: Success
400: When the file stream is invalid, or the form-data is not set properly.
500: Something went wrong on our end. Please report at support@edifabric.com

Note

The API will respond with HTTP 200 OK even if the contents of the file can't be translated. Error details will be included in the Result section of X12Interchange.

Parameters

ignoreNullValues boolean

Whether to ignore all null values in the response. The default is false.
continueOnError boolean

Whether to continue reading if a corrupt interchange is encountered. The default is false.

charSet enumeration

The encoding of the file contents. The default is utf-8.

The available values are:

Value	Description
utf-16	Unicode
unicodeFFFE	Unicode (Big endian)
utf-32	Unicode (UTF-32)
utf-32BE	Unicode (UTF-32 Big endian)
us-ascii	US-ASCII
iso-8859-1	Western European (ISO)
utf-7	Unicode (UTF-7)
utf-8	Unicode (UTF-8)

model string

The model to use. By default, the API will infer the model based on the transaction and version identifiers.

Write X12

Translates an X12Interchange object to a raw X12 interchange and returns it as a stream.

v2 only. On v3, use Build X12.

Path: /x12/write
HTTP Verb: POST
Required API Key: Ocp-Apim-Subscription-Key
Request Content-Type: application/json
Request limit: 28.6 MB
Response Content-Type: application/octet-stream

Errors

200: Success
400: When the X12Interchange has an invalid JSON structure.
500: Something went wrong on our end. Please report at support@edination.com

Parameters

preserveWhitespace boolean

Whether to preserve blank data elements so the output contains multiple delimiters instead of omitting any excess delimiters. The default is false.

charSet string

The encoding of the resulting stream. The default is utf-8.

The available values are:

Value	Description
utf-16	Unicode
unicodeFFFE	Unicode (Big endian)
utf-32	Unicode (UTF-32)
utf-32BE	Unicode (UTF-32 Big endian)
us-ascii	US-ASCII
iso-8859-1	Western European (ISO)
utf-7	Unicode (UTF-7)
utf-8	Unicode (UTF-8)

postfix string

The postfix to be applied at the end of each segment, just after the segment separator. This is usually a carriage return (CR), line feed (LF), or both. By default, there is no postfix.

Custom delimiters

If you need to generate an X12 with non-default separators, set the following items as part of the X12Interchange payload:

Segment separator: X12Interchange.SegmentDelimiter
Data element separator: X12Interchange.DataElementDelimiter
Repetition separator: X12Interchange.ISA.InterchangeControlStandardsIdentifier_11
Component data element separator: X12Interchange.ISA.ComponentElementSeparator_16

Validate X12

Validates an X12Interchange object according to the X12 standard rules for each version and transaction. Returns an OperationResult object with a status field and an array of error details if any.

v2 only. On v3, use Parse X12 in mode 2.

Path: /x12/validate
HTTP Verb: POST
Required API Key: Ocp-Apim-Subscription-Key
Request Content-Type: application/json. A raw X12 file returns HTTP 415.
Request limit: 28.6 MB
Response Content-Type: application/json

Errors

200: Success
400: When the X12Interchange has an invalid JSON structure.
500: Something went wrong on our end. Please report at support@edination.com

Parameters

basicSyntax boolean

All data elements with alpha (A) or alphanumeric (AN) data types are validated against a syntax set of allowed characters. The default syntax set is the Extended, hence the default for this parameter is false. By setting this to true, validation will use the Basic syntax set.

Extended
```
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!&()*+,-./:;?='"%@[]_{}\|<>~#$
```
Basic
```
ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!&()*+,-./:;?= '"
```
syntaxSet string

In case you need to validate against a syntax set, different than Basic and Extended, populate this field with all of the allowed symbols, URL-escaped.
skipTrailer boolean

You are allowed to validate an X12Interchange with missing interchange, functional group, or transaction trailers (IEA, GE, SE). This is because these will be automatically applied during the Write operation so you don't have to worry about counting the items. By default, it is expected that all trailers are present when you validate the X12Interchange and by default, this is set to false. To skip all trailer validation, set this to true.
structureOnly boolean

This is equivalent to HIPAA Snip level 1, where only the structure and control segments are validated. By default, this is set to false, however, if you want to not validate things such as data types, the number of repetitions, or dates, set this to true.

Acknowledge X12

Generates an X12Interchange object that contains the functional/implementation and/or technical acknowledgment(s) for the requested X12Interchange. The resulting X12Interchange uses the ISA and GS of the request, with the sender and receiver id/qualifier exchanged. The interchange reference number is set to 1.

v2 only. On v3, use Parse X12 in mode 3.

Path: /x12/ack
HTTP Verb: POST
Required API Key: Ocp-Apim-Subscription-Key
Request Content-Type: application/json. A raw X12 file returns HTTP 415.
Request limit: 28.6 MB
Response Content-Type: application/json

Errors

200: Success
400: When the X12Interchange has an invalid JSON structure.
500: Something went wrong on our end. Please report at support@edination.com

Parameters

basicSyntax boolean

All data elements with alpha (A) or alphanumeric (AN) data types are validated against a syntax set of allowed characters. The default syntax set is the Extended, hence the default for this parameter is false. By setting this to true, validation will use the Basic syntax set.

Extended
```
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!&()*+,-./:;?='"%@[]_{}\|<>~#$
```
Basic
```
ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!&()*+,-./:;?= '"
```
syntaxSet string

In case you need to validate against a syntax set, different than Basic and Extended, populate this field with all of the allowed symbols, URL-escaped.
detectDuplicates boolean

If you need to detect duplicates as in functional groups or transactions with the same reference number, set this flag to true. The default is false.
tranRefNumber integer

The default is 1. Set this to whatever the 997 or 999 X12Interchange.ST.TransactionSetControlNumber_02 needs to be. In case there are multiple acknowledgments (for multiple functional groups), this will be starting reference number and every subsequent acknowledgment will have the previous reference number incremented with 1.
interchangeRefNumber integer

The default is 1. Set this to whatever the 997 or 999 X12Interchange.ISA.InterchangeControlNumber_13 needs to be.
ackForValidTrans boolean

The default is false. Set this to true if you need AK2 loops included for all valid transactions as well. By default, AK2 loops are generated only for invalid transactions.
batchAcks boolean

The default is true. Set this to false if you need to generate a separate X12Interchange for each acknowledgment. By default, all acknowledgments are batched in the same X12Interchange.
technicalAck enumeration

The default technical acknowledgment TA1 is generated according to X12Interchange.ISA.AcknowledgementRequested_14. You can either enforce it to always generate TA1s or suppress it to never generate any TA1s. This will override the flag in X12Interchange.ISA.AcknowledgementRequested_14.

The available values are:

Value Description

enforce Always generate TA1

suppress Never generate TA1

default Generate TA1 according to AcknowledgementRequested_14
ack enumeration

The default value is 997. The type of acknowledgment being generated. Set this to 999 if you need to generate an implementation instead of functional acknowledgment.

The available values are:

Value Description

997 Generate 997 functional acknowledgment

999 Generate 999 implementation acknowledgment
ak901isP boolean

The value of the AK9's first element. By default it is "E". Set this to true if you want this value to be "P" instead.

Value	Description
enforce	Always generate TA1
suppress	Never generate TA1
default	Generate TA1 according to AcknowledgementRequested_14

Value	Description
997	Generate 997 functional acknowledgment
999	Generate 999 implementation acknowledgment

API Tutorials

To learn more about how to translate and validate EDI files with EDI API try these tutorials:

API versions

Parse X12

Modes

Read the response

Errors

Parameters

Config options

Build X12

Trailers

Errors

Parameters

Moving from v2 to v3

Read X12

Errors

Note

Parameters

Write X12

Errors

Parameters

Custom delimiters

Validate X12

Errors

Parameters

Extended

Basic

Acknowledge X12

Errors

Parameters

Extended

Basic

API Tutorials