TMS Integration API

Quickstart

Three steps to push your first vessel:

1. Generate an API key from your developer portal
2. POST vessel data to /api/v1/vessels
3. Data auto-fills your filing wizards

# Push a vessel — replace with your API key and real IMO
curl -X POST https://canalclear.org/api/v1/vessels \
  -H "Authorization: Bearer cc_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "imo": "9321483",
    "vessel_name": "EVER GIVEN",
    "flag": "PA",
    "gross_tonnage": 219079,
    "loa": 399.94,
    "beam": 58.8,
    "draft": 14.5,
    "vessel_type": "container"
  }'

const res = await fetch('https://canalclear.org/api/v1/vessels', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer cc_live_YOUR_KEY_HERE',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    imo: '9321483',
    vessel_name: 'EVER GIVEN',
    flag: 'PA',
    gross_tonnage: 219079,
    loa: 399.94,
    beam: 58.8,
    draft: 14.5,
    vessel_type: 'container',
  }),
});
const data = await res.json();
console.log(data.vessel.imo_number); // "9321483"

import requests

response = requests.post(
    "https://canalclear.org/api/v1/vessels",
    headers={
        "Authorization": "Bearer cc_live_YOUR_KEY_HERE",
        "Content-Type": "application/json",
    },
    json={
        "imo": "9321483",
        "vessel_name": "EVER GIVEN",
        "flag": "PA",
        "gross_tonnage": 219079,
        "loa": 399.94,
        "beam": 58.8,
        "draft": 14.5,
    },
)
print(response.json())

Authentication

Every request must include your API key as a Bearer token:

Authorization: Bearer cc_live_YOUR_KEY_HERE

API keys are generated from your developer portal. Each key is scoped to your account. Keys start with cc_live_ followed by 32 hex characters.

Rate Limits

100 requests per minute per API key. Rate limit state is tracked in a sliding window per key.

Every response includes rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1748000060    # Unix timestamp when window resets

Exceeding the limit returns 429 with a retry_after field (seconds).

Error Responses

All errors return JSON with consistent structure:

{
  "success": false,
  "error": "validation_failed",
  "message": "Payload failed validation",
  "errors": [
    { "field": "imo", "message": "IMO check digit invalid (expected 3, got 2)" }
  ]
}

Vessels

Push vessel particulars. Data is stored against the IMO number — subsequent pushes update the existing record (upsert).

// Returns the stored/updated vessel record
{
  "success": true,
  "vessel": {
    "id": 42,
    "imo_number": "9321483",
    "vessel_name": "EVER GIVEN",
    "flag": "PA",
    "gross_tonnage": 219079,
    "loa": "399.94",
    "source": "api",
    "updated_at": "2026-05-13T10:22:00Z"
  }
}

curl https://canalclear.org/api/v1/vessels/9321483 \
  -H "Authorization: Bearer cc_live_YOUR_KEY"

Voyages

Push voyage scheduling data. If voyage_ref is provided, subsequent pushes with the same ref update the record. Otherwise a new voyage is created.

Crew

Push crew manifests for a vessel. Each POST appends the provided members — it does not replace existing crew.

# Example: push 2 crew members
curl -X POST https://canalclear.org/api/v1/crew \
  -H "Authorization: Bearer cc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vessel_imo": "9321483",
    "voyage_ref": "VOY-2026-041",
    "crew": [
      {
        "full_name": "Juan Santos",
        "nationality": "PH",
        "rank": "Master",
        "cert_number": "STCW-PH-20241",
        "cert_expiry": "2028-03-15"
      },
      {
        "full_name": "Li Wei",
        "nationality": "CN",
        "rank": "Chief Officer"
      }
    ]
  }'

Webhook Receiver

Configure your TMS to send webhooks to a single endpoint. CanalClear logs every delivery and optionally maps fields using a stored template before ingesting.

https://canalclear.org/api/v1/webhook?source=veson&mapping_id=1
Authorization: Bearer cc_live_YOUR_KEY

{
  "success": true,
  "delivery_id": 187,          // use this to inspect the delivery log
  "status": "ingested",
  "ingested": {
    "vessel": "9321483",
    "voyage": 55
  }
}

Field Mapping

TMS systems use different field names. Create a mapping template once, then reference it with ?mapping_id=N on the webhook endpoint.

Mapping keys are CanalClear target fields. Values are dot-notation paths into the source JSON payload.

# Create a mapping template for Veson IMOS
curl -X POST https://canalclear.org/api/developer/webhook-mappings \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Veson IMOS Vessel Update",
    "source_name": "veson",
    "mapping": {
      "imo": "vessel.imo_no",
      "vessel_name": "vessel.vessel_code",
      "vessel_type": "vessel.vessel_type_description",
      "gross_tonnage": "vessel.gt",
      "loa": "vessel.loa",
      "beam": "vessel.beam",
      "draft": "vessel.draft_max"
    }
  }'

TMS Compatibility

Works with any system that can make HTTP POST requests. Pre-built field mapping templates available for:

API Key Management

These endpoints use session auth (your dashboard login), not API key auth — use them from your fleet dashboard or internal scripts.

Webhook Delivery Log

Every webhook delivery is logged. Use this to debug failed pushes or inspect raw payloads.

Outbound Webhooks — Push Events to Your Systems

Subscribe to compliance events with a signed POST to your endpoint. Use the inbound /app/settings/webhooks page (or /api/developer/webhooks) to create a subscription. Each webhook is scoped to one of your API keys and signed with an HMAC-SHA256 secret you choose.

Supported event types

Delivery semantics

• First attempt — fires inline from the approval workflow, target seconds < 30.
• Retries — 3 attempts total with exponential backoff: 1 minute → 5 minutes → 15 minutes.
• Timeout — 10 seconds per attempt. Aborted requests count as failed.
• Success — any 2xx HTTP response. The connection is marked delivered.
• Failure — non-2xx, network error, or timeout. After 3 attempts the delivery is flagged admin_review and the subscription's failed_at is set so admins can investigate.

Request headers

Content-Type:        application/json
X-CanalClear-Signature: sha256=<hex hmac of raw body>
X-CanalClear-Event:     filing.approved
X-CanalClear-Delivery:  12345  (delivery row id for log lookup)
User-Agent:            CanalClear-Webhook/1.0

Payload envelope

{
  "event":     "filing.approved",
  "timestamp": "2026-06-16T10:30:00.000Z",
  "data": {
    "filing_id":      "42",
    "filing_type":     "sp1",
    "vessel_name":     "MV Northern Star",
    "vessel_imo":      "9876543",
    "waterway":        "bosporus",
    "status":          "approved",
    "submitted_at":    "2026-06-15T08:12:00.000Z",
    "approved_at":     "2026-06-16T10:30:00.000Z",
    "confirmation_number": null
  }
}

Verifying the signature

Compute HMAC-SHA256 over the raw request body (do not re-serialise a parsed JSON object) using the secret you set when creating the webhook. Compare the result to the X-CanalClear-Signature header using a constant-time comparison to avoid timing attacks.

Node.js:

const crypto = require('crypto');

function verify(req, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(req.rawBody)               // raw bytes — keep rawBody before JSON.parse
    .digest('hex');

  const provided = req.headers['x-canalclear-signature'] || '';

  // timingSafeEqual requires equal-length buffers
  const expBuf = Buffer.from(expected);
  const gotBuf = Buffer.from(provided);
  if (expBuf.length !== gotBuf.length) return false;
  return crypto.timingSafeEqual(expBuf, gotBuf);
}

Python:

import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header or '')

curl (compute signature on the command line for one-off debugging):

SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')
echo "sha256=$SIG"

API endpoints