API Reference

x12port exposes two sets of API endpoints. Programmatic API key endpoints (/api/v1/*) are authenticated with a Bearer token and designed for server-to-server integrations. Session endpoints (/api/*) are used internally by the x12port web app and require an active browser session.

Authentication

Authorization: Bearer xp_test_YOUR_KEY

Base URL

All /api/v1 endpoints are relative to https://x12port.com. There is no separate API subdomain — do not use api.x12port.com.

Environments

Response format

All endpoints return JSON. Every response includes an ok boolean. Check ok before reading other fields.

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

// Error
{ "ok": false, "error": "Human-readable description of the problem" }

Endpoints — Programmatic (API key)

Health check

Confirms that your API key is valid and shows which environment it belongs to. Good first call when setting up an integration.

Response:

{
  "ok": true,
  "message": "API key is valid.",
  "environment": "sandbox",
  "account": "Acme Corp",
  "account_type": "developer"
}

Parse a document

Parses an EDI or structured document and returns all extracted fields. Supports X12 EDI, JSON, XML, and CSV.

Response:

{
  "ok": true,
  "fields": {
    "ISA.06": "ACME-CORP",
    "ISA.08": "PARTNER",
    "BEG.03": "PO-88241",
    "BEG.05": "20260416",
    "PO1.02": "50",
    "PO1.04": "29.99"
  },
  "format": "x12",
  "tx_set": "850",
  "elem_sep": "*",
  "seg_term": "~",
  "field_count": 24,
  "environment": "sandbox"
}

Convert a document

Converts a source document into a target format using a saved map ID or an inline field_map array. Use map_id to reference a map you built in the Visual Mapping GUI — this is the recommended approach for production integrations.

Inline field_map rule object:

{
  "src":       "BEG.03",           // source field (segment.element notation)
  "tgt":       "order.po_number",  // target field (dot-notation for nested JSON)
  "transform": "none",             // none | uppercase | lowercase | trim | date_iso
  "note":      "PO number"         // optional description
}

Response:

{
  "ok": true,
  "output": "{\"order\":{\"po_number\":\"PO-88241\",\"date\":\"2026-04-16\"}}",
  "doc_id": 42,
  "environment": "sandbox"
}

List trading partners

Returns trading partners associated with your account. Sandbox keys return only partners in testing status.

{
  "ok": true,
  "count": 2,
  "environment": "sandbox",
  "partners": [
    {
      "id": 1,
      "name": "Walmart",
      "partner_status": "testing",
      "inbound_url_test": "https://x12port.com/edi/receive/TOKEN?env=test"
    }
  ]
}

List transactions

Returns EDI transactions. Supports filtering and pagination.

Submit a transaction

Submits an EDI transaction to a trading partner.

List acknowledgements

Returns 997/999 functional acknowledgements received for your transactions.

Endpoints — Session-authenticated (internal/browser)

The following endpoints require a logged-in session. They are used by the Visual Mapping GUI and are not intended for server-to-server integrations. For programmatic map execution, use POST /api/v1/convert with a map_id instead.

List mapping projects

Returns all mapping projects belonging to the authenticated user.

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

Get a mapping project

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

Get a vault document

Returns metadata and content of a stored Document Vault record.

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

HTTP status codes

Quick example

# 1. Verify your key
curl https://x12port.com/api/v1/ping \
  -H "Authorization: Bearer xp_test_YOUR_KEY"

# 2. Parse an X12 document
curl https://x12port.com/api/v1/parse \
  -X POST \
  -H "Authorization: Bearer xp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"x12","document":"ISA*00*..."}'

# 3. Convert using a saved map (map_id from your dashboard)
curl https://x12port.com/api/v1/convert \
  -X POST \
  -H "Authorization: Bearer xp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"map_id":1,"document":"ISA*00*...","save_to_vault":true}'