PulseRoute integration documentation

Overview

There are four ways to connect a system to PulseRoute. Pick whichever your platform supports — you can mix and match.

Authentication

API requests authenticate with your organization API key. Find and rotate it under Settings → API access. Pass it in theX-API-Key header (preferred) or theapi_key query parameter.

curl https://logistics.metis.gold/api/v1/shipments \
  -H "X-API-Key: pr_your_api_key_here"

Keys are secret — never expose them in browser or mobile client code. Rotate immediately if leaked; rotation invalidates the old key.

REST API

Create a shipment

POST /api/v1/shipments — creates a shipment and automatically triggers AI risk scoring in the background. Provide coordinates, or an address we can geocode.

curl -X POST https://logistics.metis.gold/api/v1/shipments \
  -H "X-API-Key: pr_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "SHP-10231",
    "carrier": "DHL",
    "originAddress": "Houston, Texas, United States",
    "destinationAddress": "Miami, Florida, United States",
    "cargoDescription": "Electronics, high value",
    "scheduledDeparture": "2026-07-04T12:00:00Z",
    "scheduledArrival": "2026-07-05T12:00:00Z"
  }'

Optional fields: status, and explicit originLat/originLng/destinationLat/destinationLng to skip geocoding.

List shipments

GET /api/v1/shipments returns your latest shipments including their risk score and level.

{
  "shipments": [
    {
      "id": "clx...",
      "reference": "SHP-10231",
      "carrier": "DHL",
      "status": "in-transit",
      "riskAssessment": { "score": 34, "riskLevel": "medium", "summary": "..." }
    }
  ]
}

Webhooks

Configure a receiving URL and secret under Settings → Outbound webhooks. PulseRoute POSTs a JSON payload for each subscribed event and signs it with HMAC-SHA256.

Example payload:

{
  "event": "risk.alert",
  "timestamp": "2026-07-04T12:03:22.000Z",
  "data": { "shipmentId": "clx...", "reference": "SHP-10231", "score": 82 }
}

Verify the X-PulseRoute-Signature header before trusting a payload:

import crypto from 'crypto';

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

File & EDI import

For systems that only export files, use Settings → Bulk upload. Choose your source system to auto-map its columns, or select EDI X12 for 204/214 files. Rows are geocoded and risk-scored automatically.

CSV field reference

Vendor presets (Oracle OTM, SAP TM, Manhattan, Samsara, Geotab) automatically recognize each system’s native column names, so you can drop an unmodified export.

EDI X12 204 / 214

PulseRoute parses the 204 Motor Carrier Load Tender into shipments (reference, carrier SCAC, stops via S5/N4, dates via G62) and the 214 Shipment Status into status updates. Send via SFTP, AS2 or VAN, or upload the file directly.

ST*204*0001~
B2**DHLC**SHP-EDI-001*L~
L11*ORDER-88213*CO~
G62*10*20260704~
G62*02*20260705~
S5*1*LD~
N4*Houston*TX*77002*US~
S5*2*UL~
N4*Miami*FL*33101*US~
SE*10*0001~

System guides

Step-by-step connection notes for the platforms most logistics teams run.

Enterprise SSO

PulseRoute supports Google Workspace SSO out of the box and SAML 2.0 for enterprise identity providers (Okta, Azure AD, OneLogin, Ping).

1. Go to Settings → Enterprise SSO and enable SAML.
2. Give your IdP admin the SP metadata URL /api/auth/saml/metadata and ACS URL /api/auth/saml/acs.
3. Paste your IdP SSO URL and metadata XML back into PulseRoute and save.
4. Users are provisioned on first login with the analyst role; admins can elevate access.