API docs by Redocly

Surpass EDI Workflow API (1.0.4)

Download OpenAPI specification:

RESTful API for EDI document processing and workflow automation. Trigger asynchronous workflows to parse, transform, and route EDI transactions between trading partners and your ERP system.

OAuth2 Client Credentials Token Exchange

Obtain a JWT access token using the OAuth 2.0 Client Credentials Flow. IMPORTANT: This endpoint is designed for server-to-server authentication only. Never expose your client_secret in frontend applications (browsers, mobile apps). Your credentials (client_id and client_secret) are issued by Surpass and tied to your integration account. Contact Surpass support to obtain credentials.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "client_credentials"

Must be 'client_credentials'

client_id
required
string

Your Surpass-issued client ID

client_secret
required
string

Your Surpass-issued client secret

audience
required
string

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjJJTzFm...",
  • "token_type": "Bearer",
  • "expires_in": 86400
}

Test token validity

Verify that your access token is valid and inspect its contents. This is a simple health check endpoint to confirm your authentication is working correctly.

Authorizations:
OAuth2ClientCredentials
Request Body schema: application/json
required
object

Empty object or any valid JSON

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "status": "ok",
  • "message": "Token is valid",
  • "clientId": "JWwtFLcgEyD1Gxq2rZehcwzDPn81zV2a@clients",
  • "audience": "https://edi-api.surpass.biz",
  • "issuedAt": "2026-02-13T15:31:52.000Z",
  • "expiresAt": "2026-02-14T15:31:52.000Z"
}

Trigger a new workflow

Starts a new Surpass workflow to process an inbound or outbound EDI document.

This endpoint queues a workflow for asynchronous processing and returns immediately with a 202 Accepted status. The workflow executes in the background - use GET /workflow/{id} to check status and results.

Supported EDI Types: 850 (Purchase Order), 855 (PO Acknowledgement), 856 (Advance Ship Notice), 810 (Invoice), 997 (Functional Acknowledgement), or use docType "edi" to auto-detect from raw EDI.

Each request must include:

  • platform, client, and partner identifiers
  • A docType and direction
  • A payload containing either Surpass JSON (payload.json) or raw EDI (payload.edi)

šŸ”— Linking Related Workflows

Optionally pass a workflowId to group related workflows together.

Example: When processing a purchase order lifecycle:

  1. Trigger 850 Purchase Order ā†’ receive workflowId: "wf_123"
  2. Trigger 855 PO Acknowledgement with workflowId: "wf_123"
  3. Trigger 856 Shipping Notice with workflowId: "wf_123"
  4. Trigger 810 Invoice with workflowId: "wf_123"

Then GET /workflow/wf_123 returns a unified view of all linked workflows.

This enables full transaction lifecycle visibility including retries, ACKs, and chained outputs.

If omitted, a new workflowId is generated automatically.

šŸ“¤ Payload Formats

  • payload.json: For outbound documents where you provide data in Surpass JSON format. Requires a specific docType (810, 850, etc.).

  • payload.edi: For inbound or outbound documents where you provide raw EDI (X12 format). Can use docType: "edi" to auto-detect the document type from the EDI.

šŸ” Authentication is required via OAuth 2.0 Client Credentials.

Authorizations:
OAuth2ClientCredentials
Request Body schema: application/json
required
workflowId
string

Optional. Provide an existing workflowId to link this workflow with related workflows. If omitted, a new workflowId is generated automatically.

platform
required
string

Platform identifier (provided by Surpass)

client
required
string

Your client identifier (provided by Surpass)

partner
required
string

Trading partner identifier (e.g., walmart, target, costco)

docType
required
string

EDI document type. Use specific types (810, 850, 855, 856, 997) when known, or "edi" to auto-detect from raw EDI payload.

direction
required
string
Enum: "inbound" "outbound"

Workflow direction. - inbound: Processing EDI received from partner - outbound: Generating EDI to send to partner

select
Array of strings

Optional. Array of JMESPath queries to filter the response payload. Use this to extract specific data from workflow results. If omitted, the full workflow result is returned.

required
object

The EDI document to be processed. Must contain either json or edi.

  • json: Surpass JSON format for outbound documents (requires specific docType like 810, 850) - edi: Raw X12 EDI string for inbound or outbound (can use docType "edi" for auto-detection)

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "platform": "surpass-edi",
  • "client": "your-client",
  • "partner": "walmart",
  • "docType": "810",
  • "direction": "outbound",
  • "test": true,
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "workflowId": "wf_1770997534718_0f16d641",
  • "platform": "surpass-edi",
  • "client": "your-client",
  • "partner": "target",
  • "docType": "850",
  • "direction": "inbound",
  • "result": {
    }
}

Callback payload samples

Callback
POST: Surpass webhook notification
Content type
application/json
{
  • "workflowId": "string",
  • "event": "workflowStarted",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": { }
}

Get workflow details

Returns the current status, metadata, and step history for all workflows associated with the given workflowId.

This endpoint provides a unified view of multi-step or related workflows initiated with the same workflowId.

Response Format: Always returns an array of workflow objects (even if only one workflow exists).

Linked Workflows: A single workflowId may include multiple document types and directions for a complete transaction lifecycle.

Example: Order-to-cash flow using the same workflowId:

  • 850 (Purchase Order) inbound
  • 855 (PO Acknowledgement) outbound
  • 856 (Advance Ship Notice) outbound
  • 810 (Invoice) outbound
  • 997 (Functional ACK) for each document

For each workflow, the response includes:

  • workflowId, timestamp, platform, client, partner, docType, and direction
  • A context object with metadata, original payload (JSON/EDI), transformation results, and ERP responses
  • A steps array showing execution order, status, duration, and output for each workflow step

šŸŽÆ Selective Responses

Use the select query parameter to extract specific data instead of the full workflow response. This is useful when you only need certain outputs like EDI strings, JSON payloads, or ACK statuses.

Available select values:

  • query850Json - Returns Surpass JSON representation of 850 documents
  • query855Edi - Returns raw EDI string of 855 documents
  • query856Edi - Returns raw EDI string of 856 documents
  • query810Edi - Returns raw EDI string of 810 documents
  • query997Edi - Returns raw EDI string of 997 documents
  • query997AckStatus - Returns acknowledgment status of documents
  • queryLabelUrl - Returns shipping label URLs

Multiple selections: You can specify multiple values by repeating the parameter: ?select=query850Json&select=query997AckStatus

šŸ’” Pro Tip: Use a shared workflowId across related document types to retrieve the entire transaction history in a single call.

šŸ” Authentication is required via OAuth 2.0 Client Credentials.

Authorizations:
OAuth2ClientCredentials
path Parameters
workflowId
required
string
Example: wf_1770986683729_9e18b2ac

Unique workflow identifier

query Parameters
select
string
Enum: "query850Json" "query855Edi" "query856Edi" "query810Edi" "query997Edi" "query997AckStatus" "queryLabelUrl"
Examples:
  • select=query850Json - Get 850 JSON only
  • select=query850Json&select=query997AckStatus - Get 850 JSON and ACK status

Filter response to specific workflow outputs. Can be specified multiple times.

Supported values:

  • query850Json - 850 Surpass JSON
  • query855Edi - 855 raw EDI
  • query856Edi - 856 raw EDI
  • query810Edi - 810 raw EDI
  • query997Edi - 997 raw EDI
  • query997AckStatus - ACK status objects
  • queryLabelUrl - Shipping label URLs

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Parse EDI Document

Accepts structured EDI input and returns a parsed JSON representation based on document type and version.

Request Body schema: application/json
required
edi
required
string

Raw EDI string to be parsed.

hasEnvelope
required
boolean

Indicates if the EDI input includes envelope segments (ISA, GS, ST).

object
documentType
string

Optional fallback document type if envelope is missing.

version
string

Optional fallback version if envelope is missing.

Responses

Request samples

Content type
application/json
{
  • "edi": "ISA*00* *00* *ZZ*ABCDEFGHIJKLMNO*ZZ*123456789012345*210101*1253*U*00401*000000001*0*T*>~GS*PO*...~",
  • "hasEnvelope": true,
  • "metadata": {
    },
  • "documentType": "string",
  • "version": "string"
}

Response samples

Content type
application/json
{ }

Generate EDI from Surpass JSON

Converts Surpass JSON into a normalized EDI string for supported document types and versions.

Request Body schema: application/json
required
json
required
object

Surpass JSON representation of the EDI document to convert.

documentType
required
string
Enum: 990 210 846 810 850 940 945

EDI transaction set to generate.

version
required
string
Enum: "004010" "005010"

EDI version number.

required
object

Responses

Request samples

Content type
application/json
{
  • "json": { },
  • "documentType": "850",
  • "version": "004010",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "edi": "string"
}