Lyverto API

Overview

The Lyverto API connects the systems you already run — a TMS, a warehouse spreadsheet, a carrier feed, Zapier — to Lyverto. Lyverto does not replace them. It carries data in (consignments and shipment updates, in your own format if you like) and out (to your customers’ tracking pages, email and WhatsApp, to your partners, and back to your tools as events).

What you can build

• Sync consignments from your TMS or spreadsheet, and keep them in step as they change.
• Push shipment updates — one consignment or a whole container — with the reason and next step customers plan around.
• Send your own JSON through a mapping you build once, without changing your system.
• Feed carrier events in the DCSA Track & Trace format.
• React to events by webhook or by polling the event stream.
• Power your own website with consignment status and ready-made customer tracking links.
• Automate without code in Zapier, Make, n8n or Power Automate.

Quickstart

1. In Lyverto, open Settings → Integrations → API keys and create a key with the tracking:write and tracking:read scopes. Copy it — it is shown once.
2. Check the key:

curl https://lyverto.com/api/v1/me \
  -H "Authorization: Bearer lyv_YOUR_API_KEY"

{
  "success": true,
  "data": {
    "organizationId": "<uuid>",
    "scopes": ["tracking:write", "tracking:read"],
    "keyId": "<uuid>"
  }
}

1. Create your first consignment:

curl -X POST https://lyverto.com/api/v1/consignments \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "LC-0142",
    "customerName": "Ama Mensah",
    "customerPhone": "+233 24 123 4567",
    "consolidationRef": "MSKU1234567",
    "destination": "Tema",
    "publish": true
  }'

The customer now has a live tracking page (trackingUrl in the response) and, because you published it, has been notified.

Authentication

Every request except GET /openapi.json needs an API key, sent as a bearer token (or in an X-Api-Key header). Keys start with lyv_ and act for one business — nothing in a request body can name another.

Conventions

Responses

Successful responses wrap the result in data. Errors carry a human-readable error and a stable machine-readable reason.

{ "success": true, "data": { … } }

Request IDs

Every response has a Request-Id header (req_…). It is recorded in your request log; quote it when you contact support.

Batches and per-item results

Endpoints that take many items (/events, /ingest/{mapping}, /feeds/dcsa) answer one result per item, in order. One bad item never fails the batch: it comes back skipped with a reason, and the rest are written.

{
  "success": true,
  "data": [
    { "index": 0, "status": "proposed", "proposalId": "<uuid>" },
    { "index": 1, "status": "duplicate", "id": "<uuid>" },
    { "index": 2, "status": "skipped", "reason": "no consignment or container of yours matches the target" }
  ]
}

Safe retries

Give every update an externalEventId (your own id for it). Sending the same id again is answered duplicate, so a retry after a timeout never records an event twice. Consignments are keyed by reference, so re-sending one updates it instead of creating a copy.

Dates

Send ISO 8601 (2026-10-20T08:00:00Z). Through a mapping, 20/10/2026 (day first) and Unix seconds or milliseconds are also understood.

Plans and rate limits

Limits count per business, across all of its keys. The free plan is meant for real use: one system or a couple of zaps, every day.

Every response tells you where you stand:

Request-Id: req_4f0c2b9e7a1d3c5e8f6a2b1c
RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1790640060
X-Quota-Limit: 2000
X-Quota-Remaining: 1873
X-Plan: free

Over a limit you get 429 with Retry-After (seconds) and a reason: rate_limited means slow down and retry; quota_exceeded means the day’s quota is used (it resets at 00:00 UTC).

{
  "error": "Too many requests: your plan allows 60 per minute. Retry in 18s.",
  "reason": "rate_limited",
  "requestId": "req_…"
}

Sync consignments from your system

Use case: your TMS or spreadsheet is where bookings start. Push each one to Lyverto so the customer gets a tracking page, and push changes as they happen.

POST /consignments creates a consignment, or updates the one with the same reference. Only the fields you send are changed — a sync that does not know the customer’s email never erases the one your team typed.

curl -X POST https://lyverto.com/api/v1/consignments \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "LC-0142", "eta": "2026-10-24T00:00:00Z" }'

Moving a consignment along

Change the status with PATCH /consignments/{reference}. Moving a draft to published, in_transit or delivered publishes it first, and the customer is told once. A published consignment cannot go back to draft — its customer has already seen it.

curl -X PATCH https://lyverto.com/api/v1/consignments/LC-0142 \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "delivered" }'

Push shipment updates

Use case: the container departed, a consignment is held at customs, the ETA moved. Tell Lyverto once and every affected customer can see it — with the reason and the next step, which is what they plan their cash, trucks and stock around.

curl -X POST https://lyverto.com/api/v1/events \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "target": { "reference": "LC-0142" },
      "externalEventId": "tms-88121",
      "label": "Customs hold",
      "code": "exception",
      "reason": "Physical inspection requested on HS 8517",
      "nextStep": "Clearance expected in 3–5 working days. No action needed from you.",
      "location": "Tema",
      "eta": "2026-10-24T00:00:00Z"
    }]
  }'

Review or write directly

By default ("mode": "propose") updates wait in your Review queue until a person approves them — or an automation you set up does. Use "mode": "append" when the update comes from your own system and should go straight onto the timeline.

Send your own JSON with a mapping

Use case: your system already produces JSON in its own shape, and changing it is not an option. Build a mapping once, point your system at its URL, and send the JSON as it is.

1. In Settings → Integrations → Data mappings, choose New mapping, paste one sample of what your system sends, and choose Read sample.
2. For each Lyverto field, pick which of your fields fills it — or a fixed value, or a combination such as {{status}} at {{port}}. Translate your own codes with a lookup (DEP=in_transit).
3. Preview, then Save. You get a URL like https://lyverto.com/api/v1/ingest/warehouse-sheet.

curl -X POST https://lyverto.com/api/v1/ingest/warehouse-sheet \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "Ref No": "LC-0142", "Client": "Ama Mensah", "Container": "msku1234567", "ETA": "20/10/2026" },
      { "Ref No": "", "Client": "Unknown" }
    ]
  }'

Add ?dryRun=true to see what each item would become without writing anything — useful while you wire up a new source.

{
  "success": true,
  "dryRun": true,
  "data": [
    { "index": 0, "ok": true, "value": { "reference": "LC-0142", "customerName": "Ama Mensah", "consolidationRef": "MSKU1234567", "eta": "2026-10-20T00:00:00.000Z" } },
    { "index": 1, "ok": false, "errors": ["Reference is empty."] }
  ]
}

Feed carrier events (DCSA)

Use case: you receive container events from a shipping line or a tracking aggregator. Forward them in the DCSA Track & Trace format; Lyverto matches each to your container by equipmentReference (or a document reference) and proposes a customer-friendly update.

curl -X POST https://lyverto.com/api/v1/feeds/dcsa \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{
    "eventID": "7c1e…",
    "eventType": "EQUIPMENT",
    "eventClassifierCode": "ACT",
    "equipmentEventTypeCode": "DISC",
    "eventDateTime": "2026-10-19T22:10:00Z",
    "equipmentReference": "MSKU1234567",
    "eventLocation": { "locationName": "Tema", "UNLocationCode": "GHTEM" }
  }]'

That event becomes the proposal “Discharged from vessel at Tema (GHTEM)”. Estimated vessel arrivals (EST + ARRI) become ETA-change proposals. To skip review for routine events, turn on the “Approve routine carrier events automatically” automation in Lyverto.

React to events: webhooks and polling

Use case: your system should know when something happens in Lyverto — a customer was told, an update was approved, a customer sent a WhatsApp message.

Webhooks (push)

Add an endpoint in Settings → Integrations → Webhooks (or subscribe with POST /hooks). Lyverto POSTs batches of events, in order, and resumes where it stopped if your endpoint is down. Delivery is at least once: respond 2xx quickly and de-duplicate on seq.

{
  "id": "<delivery-uuid>",
  "organizationId": "<uuid>",
  "sentAt": "2026-09-29T08:10:05.000Z",
  "events": [
    {
      "seq": 1042,
      "hash": "<sha256>",
      "action": "tracking.event.appended",
      "subjectType": "tracking_record",
      "subjectId": "<uuid>",
      "summary": "Added checkpoint \"Customs hold\" on consignment LC-0142",
      "payload": { "reference": "LC-0142", "label": "Customs hold", "reason": "Physical inspection requested", "nextStep": "Clearance in 3–5 days", "…": "…" },
      "actorKind": "human",
      "source": "api",
      "occurredAt": "2026-09-29T08:10:00.000Z"
    }
  ]
}

Verify every delivery. The Lyverto-Signature header is t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>"> using your endpoint’s signing secret. Reject signatures older than five minutes.

import crypto from "node:crypto";

export function verifyLyverto(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Polling (pull)

No public endpoint? Poll GET /events with the cursor from your last call. Store cursor.after and pass it back as after.

curl "https://lyverto.com/api/v1/events?after=1041&limit=100" \
  -H "Authorization: Bearer lyv_YOUR_API_KEY"

Event types

Power your own website

Use case: keep your own site and portal, and use Lyverto as the backend for shipment status. Each consignment carries trackingUrl — the customer’s live tracking page — once published, so you can link to it, or read the status and timeline and show them in your own design.

curl https://lyverto.com/api/v1/consignments/LC-0142 \
  -H "Authorization: Bearer lyv_YOUR_API_KEY"

Zapier, Make, n8n and Power Automate

Use case: connect Lyverto to Google Sheets, a CRM, email or accounting without writing code.

• Zapier: use the Lyverto app. Triggers: *New Event* (instant) and *New or Updated Consignment*. Actions: *Create or Update Consignment*, *Add Shipment Update*, *Send Data Through a Mapping*. Search: *Find Consignment*. Give its key the webhooks:manage scope for instant triggers.
• Make, n8n, Power Automate, Postman: import the OpenAPI description at https://lyverto.com/api/v1/openapi.json, or use an HTTP step with your key.
• Instant triggers in your own tool: subscribe a URL with POST /hooks and remove it with DELETE /hooks/{id}.

curl -X POST https://lyverto.com/api/v1/hooks \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/catch/123", "events": ["tracking.event.appended"] }'

Account

curl https://lyverto.com/api/v1/me -H "Authorization: Bearer lyv_YOUR_API_KEY"

curl https://lyverto.com/api/v1/usage -H "Authorization: Bearer lyv_YOUR_API_KEY"

Consignments

curl "https://lyverto.com/api/v1/consignments?status=in_transit&limit=20" \
  -H "Authorization: Bearer lyv_YOUR_API_KEY"

curl -X POST https://lyverto.com/api/v1/consignments \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "LC-0142", "customerName": "Ama Mensah", "publish": true }'

curl https://lyverto.com/api/v1/consignments/LC-0142 -H "Authorization: Bearer lyv_YOUR_API_KEY"

curl -X PATCH https://lyverto.com/api/v1/consignments/LC-0142 \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "in_transit", "eta": "2026-10-24T00:00:00Z" }'

curl https://lyverto.com/api/v1/consignments/LC-0142/events -H "Authorization: Bearer lyv_YOUR_API_KEY"

Updates and the event stream

curl -X POST https://lyverto.com/api/v1/events \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "events": [{ "target": { "reference": "LC-0142" }, "externalEventId": "tms-1", "label": "Picked up", "code": "picked_up" }] }'

curl "https://lyverto.com/api/v1/events?after=0" -H "Authorization: Bearer lyv_YOUR_API_KEY"

Mappings

curl -X POST "https://lyverto.com/api/v1/ingest/warehouse-sheet?dryRun=true" \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rows": [{ "Ref No": "LC-0142", "Client": "Ama Mensah" }] }'

curl https://lyverto.com/api/v1/mappings -H "Authorization: Bearer lyv_YOUR_API_KEY"

Carrier feeds

curl -X POST https://lyverto.com/api/v1/feeds/dcsa \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{ "eventID": "…", "eventType": "TRANSPORT", "eventClassifierCode": "ACT", "transportEventTypeCode": "DEPA", "eventDateTime": "2026-09-29T06:00:00Z", "equipmentReference": "MSKU1234567" }]'

Webhook subscriptions

curl -X POST https://lyverto.com/api/v1/hooks \
  -H "Authorization: Bearer lyv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-system.example.com/lyverto" }'

curl -X DELETE https://lyverto.com/api/v1/hooks/<id> -H "Authorization: Bearer lyv_YOUR_API_KEY"

Errors

Fields the API does not recognise are ignored, not refused, so an extra field never breaks a request. The response lists each one in warnings — for example { "field": "custmerEmail", "message": "Unknown field; ignored." } — so a typo shows up in your logs instead of silently doing nothing.