This article will walk you through the process of generating an acknowledgement using our API service.  This service call is not tied to a flow and will not run a flow.  This is will simply generate an acknowledgement for any corresponding EDI file.


Endpoint

POST /api/docs/generate-ack

Description

This API generates one or more EDI acknowledgment files (997 for X12 or CONTRL for EDIFACT) based on an uploaded EDI file.
The file may contain one or more interchanges (ISA), functional groups (GS), and transaction sets (ST). If so, the file will be split automatically into multiple EDI documents, and an acknowledgment will be generated for each one.

Authorization

  • Requires: AccessToken

Request Body (JSON Format)

{  
    "file": "string",  
    "status": "A",  
    "rejectReasons": [    
    {      
        "controlNumber": "string",      
        "segmentErrors": [        
        {          
            "segment": "string",          
            "segmentPosition": 0,          
            "errorCode": 0,          
            "elementErrors": [            
            {              
                "elementPosition": 0,              
                "componentPosition": 0,              
                "errorCode": 0,              
                "errorValue": "string"            
            }          
          ]     
        }      
      ]    
    }  
  ] 
}

Field Explanation

?️ Top-level fields

FieldTypeRequiredDescription
filestring (Base64)✅ YesThe original EDI content, base64-encoded.
status"A" or "R"✅ YesGlobal status to apply to all acknowledgment files unless overridden by rejectReasons. "A" = Accept, "R" = Reject.
rejectReasonsarray❌ OptionalList of specific rejection reasons for individual transaction sets (ST), identified by control number.

rejectReasons[] (optional)

Used only if specific transactions inside the uploaded file should be rejected with detailed error information.

FieldTypeRequiredDescription
controlNumberstring✅ YesThe value of ST02 — identifies the transaction set (ST segment) to which the rejection applies.
segmentErrorsarray✅ YesList of segment-level errors and any nested element-level errors.

? segmentErrors[]

FieldTypeRequiredDescription
segmentstring✅ YesSegment ID in the EDI document (e.g., "N1", "REF", etc.).
segmentPositionnumber✅ YesLine position of the segment in the transaction set (starting from 1).
errorCodenumber❌ OptionalSegment-level error code. See SegmentErrorCode enum.
elementErrorsarray✅ YesElement-level validation errors inside this segment.

elementErrors[]

FieldTypeRequiredDescription
elementPositionnumber✅ YesIndex of the data element in the segment (starting from 1).
componentPositionnumber or null❌ OptionalIf the element is composite, this specifies the index of the component. Null if not composite.
errorCodenumber✅ YesElement-level validation error code. See ElementErrorCode enum.
errorValuestring✅ YesThe invalid value found in the document.

Enum Reference

SegmentErrorCode

CodeMeaning
1Unrecognized Segment ID
2Unexpected Segment
3Mandatory Segment Missing
4Loop Occurs Over Maximum Times
5Segment Exceeds Maximum Use
6Segment Not in Defined Set
7Segment Not in Proper Sequence
8Segment Has Data Element Errors

ElementErrorCode

CodeMeaning
1Mandatory Data Element Missing
2Conditional Required Element Missing
3Too Many Data Elements
4Data Element Too Short
5Data Element Too Long
6Invalid Character in Data Element
7Invalid Code Value
8Invalid Date
9Invalid Time
10Exclusion Condition Violated

Responses

✅ 200 OK

  • Returns an EDI acknowledgment file (application/octet-stream)

  • Filename: Ack_{yyyyMMddHHmmss}.edi

❌ 400 Bad Request

When:

  • File is null or empty

  • File is not in EDI format

Notes

  • ACK generation respects standard formats (997, CONTRL) based on input detection.

  • Each acknowledgment has its own counter (ISA, GS, ST).

  • You may use the ackContent in the response as a downloadable .edi file.

Example Use Cases

✅ 1. Accept All Transactions

json

{ "file": "VGVzdCBFREkgY29udGVudA==", "status": "A" }

All transactions will be accepted, no rejectReasons provided.

❌ 2. Reject All Transactions (no error detail)

json

{ "file": "VGVzdCBFREkgY29udGVudA==", "status": "R" }

All transactions will be rejected without specifying segment/element errors.

⚠️ 3. Conditional Reject with Error Details

json

{  
    "file": "VGVzdCBFREkgY29udGVudA==",  
    "status": "A",  
    "rejectReasons": [    
    {      
        "controlNumber": "0002",      
        "segmentErrors": [        
        {          
            "segment": "N1",          
            "segmentPosition": 5,          
            "errorCode": 5,          
            "elementErrors": [            
            {              
                "elementPosition": 2,              
                "componentPosition": null,              
                "errorCode": 7,              
                "errorValue": "ABC"            
            }          
          ]        
        }      
      ]    
    }  
  ] 
}
  • Global status is Accept
  • But transaction 0002 will be Rejected due to errors