X12 Resources Last updated: 2026-11-03

EDI API defines X12 resources for all X12 core items, such as control segments, interchange, group, transaction, and the validation/operation result, that are represented by JSON. Some of them differ between API v2 and v3.

Differences between v2 and v3

The X12Interchange JSON differs between API v2 and v3. The transaction content, the ISA and GS segments, and the X12Group structure are otherwise the same.

	v2	v3
Functional group trailer	`GETrailers`, an array of GE objects	`GE`, a single GE object
Interchange trailer	`IEATrailers`, an array of IEA objects	`IEA`, a single IEA object
Operation result	`Result` in every X12Interchange	No `Result`. Failures are HTTP errors, and validation results are in the validation report.
TA1	Always present, and null unless the X12Interchange is an acknowledgment	Not present. The TA1 is part of the raw X12 in the validation report's `ack`.

JSON is not interchangeable

v3 rejects v2 JSON with an invalid JSON error. v2 Write accepts v3 JSON, but v2 Validate reports that the trailers are missing. When you move to v3, change the code that reads or creates the trailers, and don't send stored v2 JSON to v3 without converting it.

X12Interchange

X12Interchange object represents an X12 interchange, ISA/IEA block. You get an array of X12 interchanges as part of the Parse operation on v3, or the Read operation on v2, when translating an X12 file to JSON. These operations support X12 files that contain multiple interchanges, that's why the response is an array. In most situations, the array will contain only a single item.

On v3, the X12Interchange object can be used with the Build operation, to translate it into an X12 file. To validate it or to generate 997, 999, and/or TA1 acknowledgment, pass that X12 file to the Parse operation.

On v2, the X12Interchange object can be used with the Write operation, to translate it into an X12 file, with the Validate operation, to validate that the interchange is compliant, and with the Ack operation, to generate 997, 999, and/or TA1 acknowledgment.

Endpoints

`POST /x12/parse` (v3)	Response
`POST /x12/build` (v3)	Request
`POST /x12/read` (v2)	Response
`POST /x12/write` (v2)	Request
`POST /x12/validate` (v2)	Request
`POST /x12/ack` (v2)	Request and Response

Example (v2)

{
    "SegmentDelimiter": "~",
    "DataElementDelimiter": "*",
    "ISA": {
        "AuthorizationInformationQualifier_1": "00",
        "AuthorizationInformation_2": "          ",
        "SecurityInformationQualifier_3": "00",
        "SecurityInformation_4": "          ",
        "SenderIDQualifier_5": "16",
        "InterchangeSenderID_6": "SENDER1        ",
        "ReceiverIDQualifier_7": "14",
        "InterchangeReceiverID_8": "RECEIVER1      ",
        "InterchangeDate_9": "071216",
        "InterchangeTime_10": "1406",
        "InterchangeControlStandardsIdentifier_11": "U",
        "InterchangeControlVersionNumber_12": "00204",
        "InterchangeControlNumber_13": "000000263",
        "AcknowledgementRequested_14": "1",
        "UsageIndicator_15": "T",
        "ComponentElementSeparator_16": ">"
    },
    "Groups": [{
        "GS": {
            "CodeIdentifyingInformationType_1": "IN",
            "SenderIDCode_2": "SENDER1",
            "ReceiverIDCode_3": "RECEIVER1",
            "Date_4": "20071216",
            "Time_5": "1406",
            "GroupControlNumber_6": "000000001",
            "TransactionTypeCode_7": "X",
            "VersionAndRelease_8": "004010"
        },
        "Transactions": [{
            "ST": {
                "TransactionSetIdentifierCode_01": "850",
                "TransactionSetControlNumber_02": "0001"
            },
            "_comment": "... model specific content goes here ...",
            "SE": {
                "NumberofIncludedSegments_01": "15",
                "TransactionSetControlNumber_02": "0001"
            },
            "Model": "EdiNation.X12.ASC.004010"
        }],
        "GETrailers": [{
            "NumberOfIncludedSets_1": "1",
            "GroupControlNumber_2": "000000001"
        }]
    }],
    "IEATrailers": [{
        "NumberOfIncludedGroups_1": "1",
        "InterchangeControlNumber_2": "000000263"
    }],
    "Result": {
        "LastIndex": 19,
        "Details": [],
        "Status": "success"
    }
}

Example (v3)

{
    "SegmentDelimiter": "~",
    "DataElementDelimiter": "*",
    "ISA": {
        "AuthorizationInformationQualifier_1": "00",
        "AuthorizationInformation_2": "          ",
        "SecurityInformationQualifier_3": "00",
        "SecurityInformation_4": "          ",
        "SenderIDQualifier_5": "16",
        "InterchangeSenderID_6": "SENDER1        ",
        "ReceiverIDQualifier_7": "14",
        "InterchangeReceiverID_8": "RECEIVER1      ",
        "InterchangeDate_9": "071216",
        "InterchangeTime_10": "1406",
        "InterchangeControlStandardsIdentifier_11": "U",
        "InterchangeControlVersionNumber_12": "00204",
        "InterchangeControlNumber_13": "000000263",
        "AcknowledgementRequested_14": "1",
        "UsageIndicator_15": "T",
        "ComponentElementSeparator_16": ">"
    },
    "Groups": [{
        "GS": {
            "CodeIdentifyingInformationType_1": "IN",
            "SenderIDCode_2": "SENDER1",
            "ReceiverIDCode_3": "RECEIVER1",
            "Date_4": "20071216",
            "Time_5": "1406",
            "GroupControlNumber_6": "000000001",
            "TransactionTypeCode_7": "X",
            "VersionAndRelease_8": "004010"
        },
        "Transactions": [{
            "ST": {
                "TransactionSetIdentifierCode_01": "850",
                "TransactionSetControlNumber_02": "0001"
            },
            "_comment": "... model specific content goes here ...",
            "SE": {
                "NumberofIncludedSegments_01": "15",
                "TransactionSetControlNumber_02": "0001"
            },
            "Model": "EdiNation.X12.ASC.004010"
        }],
        "GE": {
            "NumberOfIncludedSets_1": "1",
            "GroupControlNumber_2": "000000001"
        }
    }],
    "IEA": {
        "NumberOfIncludedGroups_1": "1",
        "InterchangeControlNumber_2": "000000263"
    }
}

Attributes

SegmentDelimiter string
The value of ISA16.
DataElementDelimiter string
The value at position 4 in the ISA segment.
ISA ISA object
The ISA segment.
TA1 TA1 object
v2 only. The TA1 segment. Included only when the X12Interchange is the result of an acknowledgment (997 or 999) operation.
Groups list of X12Group objects
The list of functional groups.
IEATrailers list of IEA objects
v2 only. The list of interchange trailers. Always contains one item for valid interchanges.
IEA IEA object
v3 only. The interchange trailer.
Result OperationResult object
v2 only. The operation result.

ISA

ISA object is only used as part of the X12Interchange object and represents the standard X12 ISA segment, interchange header.

Example

{
  "AuthorizationInformationQualifier_1": "00",
  "AuthorizationInformation_2": "          ",
  "SecurityInformationQualifier_3": "00",
  "SecurityInformation_4": "          ",
  "SenderIDQualifier_5": "16",
  "InterchangeSenderID_6": "SENDER1        ",
  "ReceiverIDQualifier_7": "14",
  "InterchangeReceiverID_8": "RECEIVER1      ",
  "InterchangeDate_9": "071216",
  "InterchangeTime_10": "1406",
  "InterchangeControlStandardsIdentifier_11": "U",
  "InterchangeControlVersionNumber_12": "00204",
  "InterchangeControlNumber_13": "000000263",
  "AcknowledgementRequested_14": "1",
  "UsageIndicator_15": "T",
  "ComponentElementSeparator_16": ">"
}

Attributes

AuthorizationInformationQualifier_1 string
Code identifying the type of information in the Authorization Information.
AuthorizationInformation_2 string
Information used for additional identification or authorization of the interchange sender or the data in the interchange; the type of information is set by ISA1.
SecurityInformationQualifier_3 string
Code identifying the type of information in the Security Information.
SecurityInformation_4 string
This is used for identifying the security information about the interchange sender or the data in the interchange; the type of information is set by ISA4.
SenderIDQualifier_5 string
Code indicating the system/method of code structure used to designate the sender or receiver ID element being qualified.
InterchangeSenderID_6 string
Identification code published by the sender for other parties to use as the receiver ID to route data to them; the sender always codes this value in the sender ID element.
ReceiverIDQualifier_7 string
Code indicating the system/method of code structure used to designate the sender or receiver ID element being qualified.
InterchangeReceiverID_8 string
Identification code published by the receiver of the data; When sending, it is used by the sender as their sending ID, thus other parties sending to them will use this as a receiving ID to route data to them.
InterchangeDate_9 string
Date of the interchange.
InterchangeTime_10 string
Time of the interchange.
InterchangeControlStandardsIdentifier_11 string
Type is not applicable; the repetition separator is a delimiter and not a data element; this field provides the delimiter used to separate repeated occurrences of a simple data element or a composite data structure; this value must be different than the data element separator, component element separator, and the segment terminator.
InterchangeControlVersionNumber_12 string
Code specifying the version number of the interchange control segments.
InterchangeControlNumber_13 string
A control number assigned by the interchange sender.
AcknowledgementRequested_14 string
Code indicating the sender’s request for an interchange acknowledgment.
UsageIndicator_15 string
Code indicating whether data enclosed by this interchange envelope is test, production, or information.
ComponentElementSeparator_16 string
Type is not applicable; the component element separator is a delimiter and not a data element; this field provides the delimiter used to separate component data elements within a composite data structure; this value must be different than the data element separator and the segment terminator.

TA1

TA1 object is only used as part of the X12Interchange object when a TA1 acknowledgment is generated and represents the standard TA1 segment.

Example

{
  "InterchangeControlNumber_1": "810000263",
  "InterchangeDate_2": "071214",
  "InterchangeTime_3": "1406",
  "InterchangeAcknowledgmentCode_4": "A",
  "InterchangeNoteCode_5": "000"
}

Attributes

InterchangeControlNumber_1 string
A control number assigned by the interchange sender.
InterchangeDate_2 string
Date of the interchange.
InterchangeTime_3 string
Time of the interchange.
InterchangeAcknowledgmentCode_4 string
Code indicating the status of the receipt of the interchange control structure.
InterchangeNoteCode_5 string
Code specifying the error found processing the interchange control structure.

X12Group

X12Group object represents an X12 functional group, GS/GE block. X12Group object is only used as part of the X12Interchange object.

Example (v2)

{
    "GS": {
        "CodeIdentifyingInformationType_1": "IN",
        "SenderIDCode_2": "SENDER1",
        "ReceiverIDCode_3": "RECEIVER1",
        "Date_4": "20071216",
        "Time_5": "1406",
        "GroupControlNumber_6": "000000001",
        "TransactionTypeCode_7": "X",
        "VersionAndRelease_8": "004010"
    },
    "Transactions": [{
        "ST": {
            "TransactionSetIdentifierCode_01": "850",
            "TransactionSetControlNumber_02": "0001"
        },
        "_comment": "... model specific content goes here ...",
        "SE": {
            "NumberofIncludedSegments_01": "15",
            "TransactionSetControlNumber_02": "0001"
        },
        "Model": "EdiNation.X12.ASC.004010"
    }],
    "GETrailers": [{
        "NumberOfIncludedSets_1": "1",
        "GroupControlNumber_2": "000000001"
    }]
}

In v3, the GETrailers array is replaced by a single object:

"GE": {
    "NumberOfIncludedSets_1": "1",
    "GroupControlNumber_2": "000000001"
}

Attributes

GS GS object
The GS segment.
Transactions list of Transaction objects
The list of transactions. This can be any type that represents a transaction which is also recognized as a model by EdiNation.

The following transaction models are available as System models:
- X12 Transaction Models
- HIPAA Transaction Models
GETrailers list of GE objects
v2 only. The list of group trailers. It always contains one item for valid groups.
GE GE object
v3 only. The group trailer.

GS

GS object is only used as part of the X12Interchange object and represents the standard X12 GS segment, functional group header.

Example

{
  "CodeIdentifyingInformationType_1": "IN",
  "SenderIDCode_2": "SENDER1",
  "ReceiverIDCode_3": "RECEIVER1",
  "Date_4": "20071216",
  "Time_5": "1406",
  "GroupControlNumber_6": "000000001",
  "TransactionTypeCode_7": "X",
  "VersionAndRelease_8": "004010"
}

Attributes

CodeIdentifyingInformationType_1 string
Code identifying a group of application-related transaction sets.
SenderIDCode_2 string
Code identifying party sending transmission; codes agreed to by trading partners.
ReceiverIDCode_3 string
Code identifying party receiving transmission; codes agreed to by trading partners.
Date_4 string
Date expressed as CCYYMMDD where CC represents the first two digits of the calendar year.
Time_5 string
Time expressed in 24-hour clock time as follows: HHMM, or HHMMSS, or HHMMSSD, or HHMMSSDD, where H = hours (00-23), M = minutes (00-59), S = integer seconds (00-59) and DD = decimal seconds; decimal seconds are expressed as follows: D = tenths (0-9) and DD = hundredths (00-99).
GroupControlNumber_6 string
Assigned number originated and maintained by the sender.
TransactionTypeCode_7 string
Code identifying the issuer of the standard; this code is used in conjunction with Data Element 480.
VersionAndRelease_8 string
Code indicating the version, release, sub release, and industry identifier of the EDI standard being used, including the GS and GE segments; if code in DE455 in GS segment is X, then in DE 480 positions 1-3 are the version number; positions 4-6 are the release and sub release, level of the version; and positions 7-12 are the industry or trade association identifiers (optionally assigned by the user); if code in DE455 in GS segment is T, then other formats are allowed.

GE

GE object is only used as part of the X12Interchange object and represents the standard X12 GE segment, functional group trailer. In v2 it is an item of GETrailers, and in v3 it is the value of GE.

Example

{
  "NumberOfIncludedSets_1": "1",
  "GroupControlNumber_2": "000000001"
}

Attributes

NumberOfIncludedSets_1 string
The total number of transaction sets included in the functional group or interchange (transmission) group terminated by the trailer containing this data element.
GroupControlNumber_2 string
Assigned number originated and maintained by the sender.

IEA

IEA object is only used as part of the X12Interchange object and represents the standard X12 IEA segment, interchange trailer. In v2 it is an item of IEATrailers, and in v3 it is the value of IEA.

Example

{
  "NumberOfIncludedGroups_1": "1",
  "InterchangeControlNumber_2": "000000263"
}

Attributes

NumberOfIncludedGroups_1 string
A count of the number of functional groups included in an interchange.
InterchangeControlNumber_2 string
A control number assigned by the interchange sender.

Validation report

v3 only. The second part of the Parse response in modes 2 and 3. On v2, Validate returns an OperationResult and Acknowledge returns an X12Interchange. Unlike the other resources, its property names are in lower case with underscores.

Example

{
  "errors": [{
    "index": 25,
    "element_index": 0,
    "composite_index": 0,
    "repetition_index": 0,
    "code": 204,
    "message": "Number of included segments does not match actual count"
  }],
  "errors_count": 1,
  "data_count": 27,
  "ack": "ISA*00*          *00*          *ZZ*11111          *ZZ*1234567        *261103*1034*^*00501*000000001*0*P*:~..."
}

Attributes

errors list of objects
The validation errors. It is empty when the file is valid.
- index integer: the position of the segment in the file.
- element_index integer: the position of the data element in the segment.
- composite_index integer: the position of the component in a composite data element.
- repetition_index integer: the repetition of the data element.
- code integer: the error code.
- message string: the error message.
errors_count integer
The number of errors.
data_count integer
The number of segments.
ack string
The generated acknowledgment as raw X12: a 999 by default or a 997 on request, with a TA1 if the interchange asks for one. It is present only in mode 3.