API Reference

x12port exposes a set of API endpoints for parsing, converting, and managing EDI documents and mapping projects programmatically. All endpoints require an authenticated session.

ℹ️

Authentication: All API endpoints require an active x12port login session. API key support (xp_live_... / xp_test_... keys generated from your developer dashboard) is used for managing endpoint credentials and future programmatic access. For current server-to-server integrations, authenticate via session cookie from a logged-in request.

Base URL

https://x12port.com

All endpoints are relative to this base URL. In development, replace with your local address.

Response format

All endpoints return JSON. Every response includes an ok boolean:

// Success
{ "ok": true, ... }

// Failure
{ "ok": false, "error": "Human-readable error message" }

Endpoints

Parse a document

POST /api/parse

Parses an EDI or structured document and extracts its fields.

Parameter	Type	Required	Description
`content`	string	Yes	The raw document content (X12 EDI string, JSON, CSV, or XML)
`format`	string	No	Document format: `x12` (default), `json`, `csv`, `xml`

Success response:

{
  "ok": true,
  "fields": { "BEG03": "PO-12345", "BEG05": "20230101", ... },
  "format": "x12",
  "tx_set": "850",
  "field_count": 42
}

Convert a document

POST /api/convert

Applies a set of mapping rules to transform a source document into a target format.

Parameter	Type	Required	Description
`content`	string	Yes	Raw source document
`source_format`	string	No	Source format: `x12` (default), `json`, `csv`, `xml`
`target_format`	string	No	Target format: `json` (default), `x12`, `csv`, `xml`
`field_map`	array	Yes	Array of mapping rule objects (see below)
`save_to_vault`	boolean	No	If `true`, the converted output is saved to your Document Vault
`direction`	string	No	`inbound` (default) or `outbound`

field_map rule object:

{
  "src": "BEG03",              // source field key (dot-notation for nested)
  "tgt": "order.po_number",   // target field key
  "transform": "none",         // none | uppercase | lowercase | trim | date_iso
  "note": "PO number"          // human-readable description
}

Success response:

{
  "ok": true,
  "output": "{ \"order\": { \"po_number\": \"PO-12345\" } }",
  "doc_id": 42    // null if save_to_vault was false
}

List mapping projects

GET /api/maps

Returns all mapping projects belonging to the authenticated user.

Success response:

{
  "ok": true,
  "maps": [
    {
      "id": 1,
      "name": "Walmart 850 → Internal Order",
      "source_fmt": "x12",
      "target_fmt": "json",
      "tx_set": "850",
      "updated_at": "Apr 20, 2026"
    }
  ]
}

Save a mapping project

POST /api/maps/save

Creates a new mapping project or updates an existing one.

Parameter	Type	Required	Description
`name`	string	No	Project name (default: "Untitled Map")
`id`	integer	No	Existing project ID — if provided, updates that project
`source_fmt`	string	No	Source format
`target_fmt`	string	No	Target format
`tx_set`	string	No	Transaction set (e.g., `850`)
`rules`	array	No	Array of mapping rule objects

Success response:

{ "ok": true, "id": 7 }

Get a mapping project

GET /api/maps/{id}

Returns the full detail of a single mapping project, including all rules.

Success response:

{
  "ok": true,
  "map": {
    "id": 7,
    "name": "Target 856 → WMS",
    "source_fmt": "x12",
    "target_fmt": "json",
    "tx_set": "856",
    "rules": [ { "src": "...", "tgt": "...", "transform": "none", "note": "..." } ]
  }
}

Delete a mapping project

POST /api/maps/{id}/delete

Permanently deletes a mapping project. This action cannot be undone.

Success response:

{ "ok": true }

Get a vault document

GET /api/vault/doc/{id}

Returns the metadata and content of a stored document from your Document Vault.

Success response:

{
  "ok": true,
  "doc": {
    "id": 42,
    "filename": "converted_20260420_120000.json",
    "fmt": "json",
    "direction": "outbound",
    "content": "{ ... }",
    "file_size": 1024,
    "transaction_set": "850",
    "status": "processed",
    "created_at": "2026-04-20T12:00:00"
  }
}

Error codes

HTTP Status	Meaning
`200`	Success — check `ok` field for application-level status
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — not logged in
`403`	Forbidden — resource belongs to another user
`404`	Not found — resource does not exist
`429`	Rate limited — too many requests
`500`	Server error — try again or file a support ticket