Documentation

X12 Operations

Article author
Admin
  • Updated

With EDI API you can translate X12 files to JSON (read X12), translate JSON to X12 file (write X12), validate an X12 transaction (validate X12), or generate X12 997 and 999 acknowledgments.

 

Read X12

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

  • 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: 28.6 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

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.

  • 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.

  • Path: /x12/validate
  • HTTP Verb: POST
  • Required API Key: Ocp-Apim-Subscription-Key
  • Request Content-Type: application/json
  • 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.

    • ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!&()*+,-./:;?='"%@[]_{}\|<>~#$
    • 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.

  • Path: /x12/ack
  • HTTP Verb: POST
  • Required API Key: Ocp-Apim-Subscription-Key
  • Request Content-Type: application/json
  • 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.

    • ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!&()*+,-./:;?='"%@[]_{}\|<>~#$
    • 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.

 

API Tutorials

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

Share this:

Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.