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.