Skip to documentation

API Integration Guide

REST API, webhooks and tracking documentation for shippers, carriers and TMS vendors

Source of truth: app/docs/content/tms-integration.md, served at /docs/tms-integration. Machine-readable description: /api/docs/openapi.json (OpenAPI 3.1).
Version: 2026.11 (last reviewed 8 November 2026). Every request and response in this guide was run against the live API of this code base; values such as ids and names are examples.

Overview

Load Éireann exposes a JSON REST API under /api that is the same API used by the web app. You can use it to post and manage loads, receive bids, push GPS positions from a TMS or telematics unit, read ETAs and tracking events, share read-only tracking links with customers, read invoices, and receive real-time events through webhooks.

Production base URL https://www.loadeireann.ie/api
Sandbox None. There is no separate sandbox. Create test data under a dedicated test company and clean it up yourself.
Format JSON (Content-Type: application/json), UTF-8
Authentication API key (X-API-Key) or Authorization: Bearer <JWT> (see Authentication)
Real-time Webhooks (outbound HTTPS POST) and Socket.IO
Support info@loadeireann.ie

Two ways to authenticate. Server-to-server integrations should use a company API key (le_..., created in Settings, API Management, with limited scopes). The web app and anything that needs the full API (bids, cancel, tracking links, payments) uses a JWT from POST /api/auth/login. See Authentication for exactly which endpoints accept which.

Authentication

Create a key in Settings, API Management (or POST /api/api-keys/keys). Choose a name, the scopes it needs, an optional expiry (30, 90 or 365 days, or none), an optional IP allow-list (single IPs or CIDR ranges) and an environment label (live or test). The full key is shown once; only its SHA-256 hash is stored. A company can have up to 20 active keys, so give every system its own key.

Send the key in a header:

curl -s "https://www.loadeireann.ie/api/loads?limit=1&status=POSTED,BIDDING" -H "X-API-Key: $LE_API_KEY"
# or
curl -s "https://www.loadeireann.ie/api/loads?limit=1" -H "Authorization: Bearer $LE_API_KEY"

Keys look like le_ followed by 64 hex characters and a 6-character checksum (73 characters; older 67-character keys remain valid). A key in the query string is rejected:

{
  "error": "API keys must be sent in the X-API-Key or Authorization header, never in the URL",
  "code": "API_KEY_IN_QUERY",
  "message": "API keys must be sent in the X-API-Key or Authorization header, never in the URL"
}

A key acts as the company owner of the company that created it and can only call the endpoints listed below. Everything else answers 403 API_KEY_ROUTE_NOT_ALLOWED. This includes the JWT-only routers (for example GET /api/bids/my-bids): a request that presents a key (X-API-Key or Bearer le_...) there is answered with 403 {"error":"This endpoint does not accept API keys","code":"API_KEY_ROUTE_NOT_ALLOWED","message":"This endpoint does not accept API keys"}, never with 401 No token provided.

Scope Endpoints
read:loads GET /api/loads, GET /api/loads/:id
write:loads POST /api/loads, PUT /api/loads/:id, PATCH /api/loads/:id/status
tracking:read GET /api/loads/:id/location-history, GET /api/loads/:id/tracking-events, GET /api/loads/:id/eta
tracking:write PATCH /api/loads/:id/location, POST /api/tracking/batch
invoices:read GET /api/invoices, GET /api/invoices/:id, GET /api/invoices/load/:loadId
read:verification GET /api/verification/public/:companyId (public-safe carrier verification status)

Not available with an API key (JWT only): bids, cancel, delete, delivery confirmation, tracking share links, tracking consent, invoice status and payments, team, accounting, administration and the API-key and webhook management endpoints themselves. The list of scopes and routes is also available from GET /api/api-keys/scopes.

A key created by a shipper company sees that company's loads; a key of a carrier company sees open loads and the loads assigned to it, and can update their status and post GPS. Use a carrier key for telematics.

Key errors (always { error, code, message }):

HTTP code Meaning
401 API_KEY_INVALID Unknown key
401 API_KEY_REVOKED Key was revoked
401 API_KEY_EXPIRED Key has expired
401 API_KEY_IN_QUERY Key sent in the URL
403 API_KEY_SCOPE_DENIED Missing scope (requiredScope tells you which)
403 API_KEY_ROUTE_NOT_ALLOWED Endpoint cannot be called with a key (also JWT-only routers: This endpoint does not accept API keys)
403 API_KEY_IP_DENIED Caller IP not on the key's allow-list
403 COMPANY_INACTIVE Company owner account is deactivated
429 RATE_LIMITED Per-key limit (600 per minute) or too many invalid keys from one IP (30 per minute)
{
  "error": "Invalid API key",
  "code": "API_KEY_INVALID",
  "message": "Invalid API key"
}
{
  "error": "This API key lacks the required scope: write:loads",
  "code": "API_KEY_SCOPE_DENIED",
  "message": "This API key lacks the required scope: write:loads",
  "requiredScope": "write:loads"
}

Every key request returns X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds); a 429 also has Retry-After.

Create, rotate, revoke

These management endpoints need a JWT of a company owner or admin (permission api); an API key can never manage keys.

Action Endpoint
List keys (masked) GET /api/api-keys/keys
Create POST /api/api-keys/keys with { name, scopes[], expiresInDays?, ipAllowlist?[], environment? }
Rotate POST /api/api-keys/keys/:id/rotate with { graceHours?: 0..72 } (the old key keeps working for the grace period)
Revoke DELETE /api/api-keys/keys/:id
Scopes GET /api/api-keys/scopes
curl -s -X POST https://www.loadeireann.ie/api/api-keys/keys \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"name":"TMS production","scopes":["read:loads","write:loads","tracking:read","tracking:write","invoices:read"],"expiresInDays":90}'
{
  "success": true,
  "message": "API key created. Store it securely - it will not be shown again.",
  "key": {
    "id": "755947b0-2351-4571-b960-5e0c98e75ba3",
    "name": "TMS production",
    "prefix": "le_9e1a6675",
    "last4": "8cb6",
    "masked": "le_9e1a6675…8cb6",
    "scopes": [
      "read:loads",
      "write:loads",
      "tracking:read",
      "tracking:write",
      "invoices:read"
    ],
    "environment": "live",
    "ipAllowlist": [],
    "status": "active",
    "createdAt": "2026-11-09T03:42:13.010Z",
    "createdById": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
    "lastUsedAt": null,
    "lastUsedIp": null,
    "requestCount": 0,
    "expiresAt": "2027-02-07T03:42:13.006Z",
    "revokedAt": null
  },
  "secret": "le_9e1a6675<...rest of the 73-character key, shown once>"
}

Rotation returns the new key (secret, once) and previous (the old key with its new expiresAt when a grace period was requested):

{
  "success": true,
  "message": "API key rotated. Store the new key securely - it will not be shown again.",
  "key": {
    "id": "6c0c4de3-28f1-438c-b050-ee2255f0a62a",
    "name": "BI read only",
    "prefix": "le_1f482111",
    "last4": "55c5",
    "masked": "le_1f482111…55c5",
    "scopes": [
      "read:loads"
    ],
    "environment": "live",
    "ipAllowlist": [],
    "status": "active",
    "createdAt": "2026-11-09T03:42:15.915Z",
    "createdById": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
    "lastUsedAt": null,
    "lastUsedIp": null,
    "requestCount": 0,
    "expiresAt": null,
    "revokedAt": null
  },
  "secret": "le_1f482111<...rest of the 73-character key, shown once>",
  "previous": {
    "id": "b77eec91-894b-4002-8e95-338ef63ee572",
    "name": "BI read only",
    "prefix": "le_f53d28c9",
    "last4": "2b38",
    "masked": "le_f53d28c9…2b38",
    "scopes": [
      "read:loads"
    ],
    "environment": "live",
    "ipAllowlist": [],
    "status": "active",
    "createdAt": "2026-11-09T03:42:13.049Z",
    "createdById": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
    "lastUsedAt": null,
    "lastUsedIp": null,
    "requestCount": 0,
    "expiresAt": "2026-11-09T04:42:15.912Z",
    "revokedAt": null
  }
}

Usage

GET /api/api-keys/keys also returns a usage object per key (shown as a sparkline and totals in API Management), counted from authenticated requests:

"usage": { "last24h": 1240, "last7d": 8312, "hourly": [0,0,3,12,40,95,110,90,70,64,52,58,61,49,44,38,35,22,18,9,4,2,1,1] }

hourly has 24 points, oldest first; the last one is the current UTC hour. Counts come from hourly buckets that are flushed together with lastUsedAt (at most once a minute per key), so the newest requests can lag by up to a minute; requestCount is the all-time total. Buckets are kept for 8 days.

Revoking takes effect immediately for new requests. The legacy single-key endpoints POST /api/api-keys/generate, DELETE /api/api-keys/revoke and GET /api/api-keys/config still work.

JWT (web app and full API access)

curl -s -X POST https://www.loadeireann.ie/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"integration@example.com","password":"********"}'

Response 200 (trimmed):

{
  "message": "Login successful",
  "user": {
    "id": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
    "email": "shipper@example.com",
    "accountType": "SHIPPER",
    "firstName": "Jane",
    "lastName": "Shipper",
    "role": null,
    "companyId": null
  },
  "token": "eyJhbGciOi...(JWT)"
}

Send it as Authorization: Bearer <token>.

  • Tokens expire after 7 days by default; on 401 Invalid or expired token log in again. Do not log in on every request.
  • POST /api/auth/login (and register / password reset) is limited to 5 attempts per 15 minutes per IP. Cache the token.
  • Prefer a dedicated service user with the least role that works (for example DISPATCHER) over an owner login.
  • A token is revoked server-side (401, code SESSION_REVOKED) on force-logout, role change, deactivation or password reset. A deactivated user receives 403 Account is deactivated.
  • Registration and password-reset requests may require a CAPTCHA (CAPTCHA_REQUIRED, CAPTCHA_VERIFICATION_FAILED); login does not.
  • Browsers can only call the API from the configured web origin (CORS allows only FRONTEND_URL). Server-to-server calls are not affected.

Without any credentials:

{
  "error": "No token provided"
}

Security best practices

  • Keep keys, tokens and the webhook secret in a secrets manager, never in source control, mobile apps or browsers.
  • Grant the minimum scopes, set an expiry and an IP allow-list for fixed-address servers, and use one key per system so you can revoke one without breaking the others.
  • Rotate keys regularly using the grace period for zero-downtime rotation.
  • Always verify the webhook signature on the raw body and reject old timestamps.
  • Never put a key or token in a URL.
  • Watch lastUsedAt, lastUsedIp and requestCount in API Management for unexpected use.

Permissions

With a JWT the API enforces account type and company role on every call (an API key acts as the company owner within its scopes).

Account type / role What it can do through the API
SHIPPER owner (and ADMIN/DISPATCHER staff with loads permission) Create, update, delete loads; accept/reject bids; confirm delivery; create tracking links; read invoices
CARRIER owner and staff List open loads, bid, update status (IN_TRANSIT, DELIVERED), cancel, post GPS, create invoices where applicable
DRIVER Post GPS for the load of their active assignment (needs consent), mark pickup/delivery (POD required)
ACCOUNTANT Read invoices (finances:view)
VIEWER Read-only

A call outside your permissions returns 403:

{
  "error": "Insufficient permissions",
  "required": [
    "SHIPPER",
    "ADMIN"
  ],
  "current": "CARRIER"
}

Request and response conventions

  • Content type: JSON bodies with Content-Type: application/json. POST /api/loads and PUT /api/loads/:id also accept multipart/form-data (up to 10 documents).
  • Dates: ISO 8601 in UTC, for example 2026-11-08T22:56:54.799Z. Request dates may be any string Date can parse; send ISO 8601.
  • Money: amounts are numbers in EUR (currency: "EUR"), major units with two decimals. VAT (23 percent) is added on invoices.
  • Units: weight in kilograms, volume in cubic metres, distance in kilometres, GPS speed in metres per second, heading in degrees clockwise from north (0 to 360), accuracy and altitude in metres.
  • Ids: UUID strings.
  • Body limits: 10 MB general, 256 KB on /api/tracking/* and PATCH /api/loads/:id/location, 4 KB on tracking-link creation (413, code PAYLOAD_TOO_LARGE; malformed JSON gives 400, code INVALID_JSON).
  • Pagination: list endpoints take page (1-based, default 1) and limit. Loads: default 20, max 100. Invoices: default 20, max 200. Responses contain pagination: { total, page, limit, totalPages }. Location history uses a time cursor instead (see Tracking).
  • Caching: authenticated responses are not cacheable by intermediaries; do not cache them yourself longer than you need.

Errors

Errors are JSON. The minimum shape is { "error": "<message>" }. Tracking, session and some newer endpoints add a stable machine-readable code and a message:

{ "error": "Too many location updates for this load", "code": "RATE_LIMITED", "message": "Too many location updates for this load", "retryAfter": 5 }

Switch on the HTTP status and, when present, on code, never on the text. Some endpoints add detail fields (required, current, invalidEvents, validEvents).

HTTP code Meaning
400 INVALID_JSON Body is not valid JSON
400 INVALID_EVENTS, WEBHOOK_URL_NOT_HTTPS, WEBHOOK_URL_PRIVATE Webhook configuration rejected
400 INVALID_COORDINATES, INVALID_ACCURACY, INVALID_SPEED, INVALID_HEADING, INVALID_ALTITUDE, INVALID_TIMESTAMP, TIMESTAMP_IN_FUTURE, TIMESTAMP_TOO_OLD, INVALID_DEVICE_INFO A GPS point failed validation (see limits)
400 INVALID_BATCH, BATCH_TOO_LARGE Batch body is empty / over 500 points
400 INVALID_LIMIT, INVALID_SINCE, INVALID_BEFORE, INVALID_TOLERANCE Bad location-history query
400 LOAD_NOT_IN_TRANSIT GPS posted for a load that does not accept points (not ASSIGNED/IN_TRANSIT, or more than 24 h after delivery)
400 INVALID_CONSENT, INVALID_AUTO_TRACKING, INVALID_TRACKING_INTERVAL Bad tracking-consent body
400 INVALID_LABEL, INVALID_EXPIRY, TRACKING_CLOSED Tracking-link creation rejected
400 INVALID_LOAD Missing or invalid loadId (batch item, socket join)
401 API_KEY_INVALID, API_KEY_REVOKED, API_KEY_EXPIRED, API_KEY_IN_QUERY API key problems (see API keys)
401 SESSION_REVOKED Token valid but the session was revoked server-side
401 none No token provided (no credentials at all), Invalid or expired token, User not found
403 API_KEY_SCOPE_DENIED, API_KEY_ROUTE_NOT_ALLOWED, API_KEY_IP_DENIED, COMPANY_INACTIVE API key restrictions (API_KEY_ROUTE_NOT_ALLOWED is also returned by JWT-only routers when a key is presented)
403 FORBIDDEN Authenticated but not allowed for this load or action
403 TRACKING_CONSENT_REQUIRED Driver has not consented to tracking for this load
403 POD_REQUIRED Driver tried to mark DELIVERED without proof of delivery
403 none Insufficient permissions (with required and current), Account is deactivated
404 NOT_FOUND, LOAD_NOT_FOUND, SHARE_NOT_FOUND, DOC_NOT_FOUND Unknown or invisible resource. Resources you may not see are reported as 404, not 403, in tracking.
409 TOO_MANY_LINKS 10 active tracking links per load
413 PAYLOAD_TOO_LARGE Body too large
429 RATE_LIMITED Per-load GPS limit, API-key limit or too many invalid keys; honour Retry-After
500 INTERNAL_ERROR Unexpected error; safe to retry with backoff

The no company condition (NO_COMPANY) is returned by company-scoped endpoints for users that are not attached to a company. Socket.IO uses AUTH_REQUIRED, INVALID_TOKEN, TOKEN_EXPIRED, AUTH_EXPIRED, ACCOUNT_DISABLED and SESSION_REVOKED.

Example (404):

{
  "error": "Load not found"
}

Rate limits

Scope Limit Over the limit
All /api/* (per IP, in addition to the key limit) 1000 requests per 15 minutes per IP. Headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy: 1000;w=900 429, plain-text body Too many requests from this IP, please try again later.
API key requests 600 per minute per key (X-RateLimit-* headers); 30 invalid-key attempts per minute per IP 429 RATE_LIMITED with Retry-After
/api/auth/login, /register, password reset 5 per 15 minutes per IP 429, plain text
PATCH /api/loads/:id/location 1 point per 5 seconds per user and load 429 RATE_LIMITED with Retry-After header and retryAfter seconds. A retry of an already-stored point is answered as a duplicate, not 429.
GET /api/public/tracking/:token 60 per minute per IP (valid and invalid tokens count) 429 RATE_LIMITED
load.location_updated webhook at most one delivery per load every 30 s (latest point wins) coalesced
POST /api/api-keys/webhook/test 10 per minute 429

POST /api/tracking/batch is not subject to the 5-second rule; use it for anything faster than one point per 5 seconds.

Loads

A load moves through DRAFT, POSTED, BIDDING, ASSIGNED, IN_TRANSIT, DELIVERED or CANCELLED. Accepting a bid moves it to ASSIGNED; the carrier then moves it to IN_TRANSIT and DELIVERED. Cancelling an assigned load returns it to POSTED.

List loads

GET /api/loads

Auth: JWT or API key (read:loads). Shippers see their own loads; carriers see open loads (POSTED, BIDDING) plus their own assigned loads. Exact addresses may be hidden from carriers when the load has hideExactLocation.

Query Description
page, limit Pagination (limit max 100, default 20)
status One status or a comma-separated list, for example POSTED,BIDDING
minPrice, maxPrice Price range (EUR)
minWeight, maxWeight Weight range (kg)
pickupDateFrom, pickupDateTo ISO dates, filter on pickupDate
originCounty, destinationCounty, cargoType Case-insensitive contains
requiredEquipment One or more of STANDARD, PALLET_JACK, FORKLIFT, CRANE, TAILGATE, STRAPS, BLANKETS, TEMPERATURE_CONTROLLED, comma-separated; matches any
isHazmat, requiresRefrigeration true or 1 to filter; any other value means no filter
vehicleType Comma-separated requiredVehicleType values (VAN, LUTON, SMALL_TRUCK, RIGID_TRUCK, ARTICULATED); add ANY to include loads with no vehicle restriction
vehicleGroup van (VAN and LUTON loads) or truck (SMALL_TRUCK, RIGID_TRUCK, ARTICULATED)
vehicleFit One vehicle type: returns loads that vehicle could carry (unrestricted loads plus loads whose requirement it satisfies; a LUTON fits VAN and LUTON loads)
includeUnspecified, maxPallets, isUrgent true adds unrestricted loads to a vehicle filter; maximum pallets or items; true for same-day loads only
sortBy createdAt (default), updatedAt, price, pickupDate, deliveryDate, distance, weight
sortOrder desc (default) or asc

Invalid numbers and dates are ignored rather than rejected.

curl -s "https://www.loadeireann.ie/api/loads?limit=2&sortBy=price&sortOrder=asc&minPrice=100&maxPrice=1000" -H "Authorization: Bearer $TOKEN"
{
  "loads": [
    {
      "id": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
      "shipperId": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
      "carrierId": null,
      "title": "Pallets Dublin to Cork",
      "description": "12 pallets of ambient goods",
      "cargoType": "General Freight",
      "weight": 8000,
      "pallets": 12,
      "originCity": "Dublin",
      "originCounty": "Dublin",
      "destinationCity": "Cork",
      "destinationCounty": "Cork",
      "price": 650,
      "currency": "EUR",
      "vatIncluded": false,
      "pickupDate": "2026-11-08T23:56:54.799Z",
      "deliveryDate": "2026-11-09T22:56:54.799Z",
      "status": "POSTED",
      "requiredVehicleType": "ARTICULATED",
      "distance": 220,
      "createdAt": "2026-11-08T22:56:54.863Z",
      "updatedAt": "2026-11-08T22:56:55.019Z",
      "shipper": {
        "id": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
        "firstName": "Jane",
        "lastName": "Shipper",
        "company": {
          "name": "Example Shipping Ltd",
          "city": "Dublin",
          "county": "Dublin"
        }
      },
      "carrier": null,
      "_count": {
        "bids": 0
      }
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 2,
    "totalPages": 1
  }
}

Get a load

Auth: JWT or API key (read:loads). GET /api/loads/:id returns { "load": { ... } } with the same fields as above plus related shipper, carrier, bids count and documents.

Create a load

POST /api/loads (shipper accounts; JWT or API key with write:loads). Required unless status is DRAFT: title, description, cargoType, weight, pallets, originAddress, destinationAddress, price, pickupDate, deliveryDate. Also accepted: volume, originName, originEircode, originCity, originCounty, originLat, originLng, the same for destination*, currency (default EUR), vatIncluded, pickupTimeWindow, deliveryTimeWindow, requiredVehicleType, requiredTrailerType, requiresRefrigeration, requiresTailLift, hideExactLocation, specialInstructions, plus the van-friendly fields weightUnit (kg default, or t; weight is always stored and returned in kg), cargoLengthM, cargoWidthM, cargoHeightM (metres) and isUrgent (same-day job). If you do not send coordinates the server geocodes the addresses. Posting (non-draft) requires a payment card and a VAT number on the company (403 otherwise). Eircodes and UK postcodes are validated.

curl -s -X POST https://www.loadeireann.ie/api/loads \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Pallets Dublin to Cork","description":"12 pallets of ambient goods","cargoType":"General Freight",
       "weight":8000,"pallets":12,"originName":"Origin","originAddress":"1 Docks Rd","originCity":"Dublin","originCounty":"Dublin",
       "originEircode":"D01 F5P2","originLat":53.3498,"originLng":-6.2603,
       "destinationName":"Dest","destinationAddress":"5 Quay St","destinationCity":"Cork","destinationCounty":"Cork",
       "destinationEircode":"T12 AB34","destinationLat":51.8985,"destinationLng":-8.4756,
       "price":650,"currency":"EUR","vatIncluded":false,
       "pickupDate":"2026-11-09T09:00:00Z","deliveryDate":"2026-11-10T09:00:00Z","requiredVehicleType":"ARTICULATED"}'

Response 201 (the load object is trimmed to the main fields; the real one also carries route, fuel and CO2 estimates):

{
  "message": "Load created successfully",
  "load": {
    "id": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
    "shipperId": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
    "carrierId": null,
    "title": "Pallets Dublin to Cork",
    "description": "12 pallets of ambient goods",
    "cargoType": "General Freight",
    "weight": 8000,
    "pallets": 12,
    "originCity": "Dublin",
    "originCounty": "Dublin",
    "destinationCity": "Cork",
    "destinationCounty": "Cork",
    "price": 650,
    "currency": "EUR",
    "vatIncluded": false,
    "pickupDate": "2026-11-08T23:56:54.799Z",
    "deliveryDate": "2026-11-09T22:56:54.799Z",
    "status": "POSTED",
    "requiredVehicleType": "ARTICULATED",
    "distance": 220,
    "createdAt": "2026-11-08T22:56:54.863Z",
    "updatedAt": "2026-11-08T22:56:55.019Z"
  }
}

A load.created webhook is sent to the shipper company.

Vehicle types

Loads and vehicles use five vehicle classes, from small vans to articulated trucks. requiredVehicleType takes one of these values, or null / ANY for no restriction. Request-only selectors ANY_VAN (stored as VAN) and ANY_TRUCK (stored as SMALL_TRUCK) are also accepted.

Value Class Typical payload Typical pallets Licence (Ireland / UK)
VAN Van, small to large (up to 3.5 t gross) 400 to 1,400 kg up to 3 B
LUTON Box van with tail lift (up to 3.5 t gross) 800 to 1,300 kg 4 to 5 B
SMALL_TRUCK 7.5 t truck 2.5 to 4 t 8 to 10 C1
RIGID_TRUCK Rigid truck (up to 18 t and above) 8 to 18 t 14 to 18 C
ARTICULATED Tractor and trailer 24 to 29 t 26 to 33 CE

The figures are typical, for guidance only. Weights are always kilograms in the API, including for vans. A load that requires VAN can be carried by a VAN or a LUTON; a truck requirement can be carried by that class or a larger truck. Vans are never matched to truck loads and trucks are not offered van-only loads. A van needs no HGV licence: a category B licence is enough up to 3.5 t gross, so van assignments do not require HGV-only details.

Example of a van-sized load:

curl -s -X POST https://www.loadeireann.ie/api/loads \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"4 pallets Naas to Dublin 12","description":"Palletised stock, same day","cargoType":"Palletised Goods",
       "weight":1200,"weightUnit":"kg","pallets":4,"cargoLengthM":1.2,"cargoWidthM":1.0,"cargoHeightM":1.4,"isUrgent":true,
       "originName":"Origin","originAddress":"1 Main St","originCity":"Naas","originCounty":"Kildare",
       "destinationName":"Dest","destinationAddress":"9 Park Rd","destinationCity":"Dublin","destinationCounty":"Dublin",
       "price":95,"pickupDate":"2026-11-10T09:00:00Z","deliveryDate":"2026-11-10T12:00:00Z","requiredVehicleType":"LUTON"}'

To list only van work: GET /api/loads?vehicleGroup=van&status=POSTED.

Update a load

PUT /api/loads/:id (shipper, while editable; JWT or write:loads). Send only the fields to change.

curl -s -X PUT https://www.loadeireann.ie/api/loads/$LOAD_ID \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"price":675,"specialInstructions":"Call 30 minutes before arrival"}'
{
  "message": "Load updated successfully",
  "load": {
    "id": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
    "shipperId": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
    "carrierId": null,
    "title": "Pallets Dublin to Cork",
    "description": "12 pallets of ambient goods",
    "cargoType": "General Freight",
    "weight": 8000,
    "pallets": 12,
    "originCity": "Dublin",
    "originCounty": "Dublin",
    "destinationCity": "Cork",
    "destinationCounty": "Cork",
    "price": 675,
    "currency": "EUR",
    "vatIncluded": false,
    "pickupDate": "2026-11-08T23:56:54.799Z",
    "deliveryDate": "2026-11-09T22:56:54.799Z",
    "status": "POSTED",
    "requiredVehicleType": "ARTICULATED",
    "distance": 220,
    "createdAt": "2026-11-08T22:56:54.863Z",
    "updatedAt": "2026-11-08T22:56:55.119Z"
  }
}

DELETE /api/loads/:id deletes a load (the load owner only; IN_TRANSIT and DELIVERED loads cannot be deleted) and returns { "message": "Load deleted successfully" }.

Update status (carrier)

PATCH /api/loads/:id/status (carrier; JWT or write:loads) with { "status": "IN_TRANSIT" | "DELIVERED" | "CANCELLED", "location"?: { "latitude", "longitude" }, "deliveryNotes"? }. Valid transitions: ASSIGNED to IN_TRANSIT, IN_TRANSIT to DELIVERED. Anything else is 400 Cannot transition from X to Y. CANCELLED is handled as POST /api/loads/:id/cancel. Drivers may only set IN_TRANSIT or DELIVERED, and DELIVERED needs proof of delivery (a photo file in a multipart request, or an existing POD / eCMR signature), otherwise 403 POD_REQUIRED. Delivering a load creates its invoice automatically.

curl -s -X PATCH https://www.loadeireann.ie/api/loads/$LOAD_ID/status \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"IN_TRANSIT","location":{"latitude":53.3498,"longitude":-6.2603}}'
{
  "message": "Load status updated to IN_TRANSIT",
  "load": {
    "id": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
    "shipperId": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
    "carrierId": "9a54a1d9-6fe0-4f91-8735-1c6a75d883ac",
    "title": "Pallets Dublin to Cork",
    "description": "12 pallets of ambient goods",
    "cargoType": "General Freight",
    "weight": 8000,
    "pallets": 12,
    "originCity": "Dublin",
    "originCounty": "Dublin",
    "destinationCity": "Cork",
    "destinationCounty": "Cork",
    "price": 640,
    "currency": "EUR",
    "vatIncluded": false,
    "pickupDate": "2026-11-08T23:56:54.799Z",
    "deliveryDate": "2026-11-09T22:56:54.799Z",
    "status": "IN_TRANSIT",
    "requiredVehicleType": "ARTICULATED",
    "distance": 220,
    "createdAt": "2026-11-08T22:56:54.863Z",
    "updatedAt": "2026-11-08T22:56:55.242Z"
  }
}

Invalid transition:

{
  "error": "Cannot transition from IN_TRANSIT to ASSIGNED"
}

Cancel (carrier)

POST /api/loads/:id/cancel with { "reason": "..." }, allowed before IN_TRANSIT. The carrier is unassigned and the load returns to POSTED.

{
  "message": "Load cancelled successfully. Load is now available for other carriers.",
  "load": {
    "id": "64c342d3-039a-4239-ae52-1277d3841a29",
    "shipperId": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
    "carrierId": null,
    "title": "cancelme",
    "description": "x",
    "cargoType": "General Freight",
    "weight": 500,
    "pallets": 1,
    "originCity": "Dublin",
    "originCounty": "Dublin",
    "destinationCity": "Galway",
    "destinationCounty": "Galway",
    "price": 290,
    "currency": "EUR",
    "vatIncluded": false,
    "pickupDate": "2026-11-09T00:03:20.143Z",
    "deliveryDate": "2026-11-09T23:03:20.143Z",
    "status": "POSTED",
    "requiredVehicleType": null,
    "distance": 185.6,
    "createdAt": "2026-11-08T23:03:20.157Z",
    "updatedAt": "2026-11-08T23:03:20.519Z"
  }
}

Delivery confirmation (shipper)

POST /api/loads/:id/confirm-delivery with { "confirmed": true, "issues"?: "text" } (confirmed must be a boolean). Only the shipper of the load can confirm.

{
  "message": "Delivery confirmed successfully",
  "load": {
    "id": "81deb7eb-45b8-408c-85fb-e8fb34822297",
    "shipperId": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
    "carrierId": "9a54a1d9-6fe0-4f91-8735-1c6a75d883ac",
    "title": "Short hop",
    "description": "2 pallets",
    "cargoType": "General Freight",
    "weight": 900,
    "pallets": 2,
    "originCity": "Dublin",
    "originCounty": "Dublin",
    "destinationCity": "Dublin",
    "destinationCounty": "Dublin",
    "price": 110,
    "currency": "EUR",
    "vatIncluded": false,
    "pickupDate": "2026-11-08T23:57:51.731Z",
    "deliveryDate": "2026-11-08T20:57:51.731Z",
    "status": "DELIVERED",
    "requiredVehicleType": null,
    "distance": 1.3,
    "createdAt": "2026-11-08T22:57:51.792Z",
    "updatedAt": "2026-11-08T22:58:41.000Z"
  }
}

Bids

Method and path Who Notes
POST /api/bids Carrier Body { loadId, amount, message?, estimatedPickup?, estimatedDelivery? }. One bid per carrier and load (409). Load must be open (400).
POST /api/bids/accept-price Carrier Instant accept at the asking price: { loadId, estimatedPickup?, estimatedDelivery? }
GET /api/bids/my-bids Carrier { "bids": [...] }
GET /api/bids/load/:loadId Shipper of the load / bidding carrier { "bids": [...] }
PUT /api/bids/:id/accept Shipper Assigns the carrier, load becomes ASSIGNED, other bids are rejected
PUT /api/bids/:id/reject Shipper Pending bids only
PUT /api/bids/:id/withdraw Carrier Pending bids only

Bid statuses: PENDING, ACCEPTED, REJECTED, WITHDRAWN.

curl -s -X POST https://www.loadeireann.ie/api/bids \
  -H "Authorization: Bearer $CARRIER_TOKEN" -H "Content-Type: application/json" \
  -d '{"loadId":"'$LOAD_ID'","amount":640,"message":"Can collect tomorrow morning"}'
{
  "message": "Bid placed successfully",
  "bid": {
    "id": "8d38ad59-d6ca-42ea-82d9-1f0dcfc783e0",
    "loadId": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
    "carrierId": "9a54a1d9-6fe0-4f91-8735-1c6a75d883ac",
    "amount": 640,
    "currency": "EUR",
    "message": "Can collect tomorrow morning",
    "status": "PENDING",
    "estimatedPickup": "2026-11-09T00:56:54.799Z",
    "estimatedDelivery": "2026-11-09T21:10:14.799Z",
    "createdAt": "2026-11-08T22:56:55.138Z",
    "updatedAt": "2026-11-08T22:56:55.138Z",
    "carrier": {
      "id": "9a54a1d9-6fe0-4f91-8735-1c6a75d883ac",
      "firstName": "Jane",
      "lastName": "Carrier",
      "company": {
        "name": "Example Haulage Ltd",
        "creditScore": 0,
        "insuranceVerified": false,
        "fleetSize": 0
      }
    }
  }
}

Accept:

{
  "message": "Bid accepted successfully",
  "bid": {
    "id": "8d38ad59-d6ca-42ea-82d9-1f0dcfc783e0",
    "loadId": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
    "carrierId": "9a54a1d9-6fe0-4f91-8735-1c6a75d883ac",
    "amount": 640,
    "currency": "EUR",
    "message": "Can collect tomorrow morning",
    "status": "ACCEPTED",
    "estimatedPickup": "2026-11-09T00:56:54.799Z",
    "estimatedDelivery": "2026-11-09T21:10:14.799Z",
    "createdAt": "2026-11-08T22:56:55.138Z",
    "updatedAt": "2026-11-08T22:56:55.189Z"
  }
}

Withdraw:

{
  "message": "Bid withdrawn successfully",
  "bid": {
    "id": "cb507309-5849-43b4-9259-347301970075",
    "loadId": "0e487e29-d305-47e2-926c-8c0592cd0b07",
    "carrierId": "9a54a1d9-6fe0-4f91-8735-1c6a75d883ac",
    "amount": 190,
    "currency": "EUR",
    "message": null,
    "status": "WITHDRAWN",
    "estimatedPickup": null,
    "estimatedDelivery": null,
    "createdAt": "2026-11-08T23:03:20.651Z",
    "updatedAt": "2026-11-08T23:03:20.676Z"
  }
}

Tracking

Tracking is available while a load is ASSIGNED or IN_TRANSIT (and for 24 hours after DELIVERED). Positions can be posted by the carrier owner, carrier staff, an admin, or the driver of the active assignment. Loads in other states reject points with 400 LOAD_NOT_IN_TRANSIT (admins excepted). Driver-originated points need the driver's per-load consent (403 TRACKING_CONSENT_REQUIRED); carrier owner, staff and admin updates are not consent-gated. See Data protection.

Point validation

Field Rule Error code
latitude, longitude finite numbers in range; (0, 0) rejected INVALID_COORDINATES
accuracy 0 to 2000 m (above 100 m is flagged lowAccuracy) INVALID_ACCURACY
speed 0 to 70 m/s INVALID_SPEED
heading 0 to 360 degrees INVALID_HEADING
altitude finite, absolute value up to 100000 m INVALID_ALTITUDE
timestamp ISO string or epoch milliseconds; not more than 5 minutes in the future and not older than 24 hours; defaults to now INVALID_TIMESTAMP, TIMESTAMP_IN_FUTURE, TIMESTAMP_TOO_OLD
deviceInfo optional object, max 2048 bytes, only whitelisted keys are kept INVALID_DEVICE_INFO
Batch size 1 to 500 points INVALID_BATCH, BATCH_TOO_LARGE

Points are stored once per (load, timestamp, user): re-sending the same point is answered as a duplicate. A point whose implied speed from the previous trusted point exceeds 250 km/h (jumps under 500 m are ignored) is stored with suspect: true; suspect points are hidden from non-admin readers and do not trigger events, ETA or webhooks.

Post one position

PATCH /api/loads/:id/location (note PATCH; there is no POST on this path). JWT or API key with tracking:write.

curl -s -X PATCH https://www.loadeireann.ie/api/loads/$LOAD_ID/location \
  -H "Authorization: Bearer $CARRIER_TOKEN" -H "Content-Type: application/json" \
  -d '{"latitude":53.2707,"longitude":-6.5,"accuracy":8,"speed":22.5,"heading":215,"altitude":70,"timestamp":"2026-11-08T22:57:19.872Z"}'
{
  "message": "Location updated successfully",
  "location": {
    "id": "2f4233df-a468-4e37-809b-c42abc67d40b",
    "latitude": 53.2707,
    "longitude": -6.5,
    "accuracy": 8,
    "speed": 22.5,
    "heading": 215,
    "altitude": 70,
    "timestamp": "2026-11-08T22:57:22.872Z",
    "userType": "CARRIER",
    "lowAccuracy": false,
    "suspect": true
  }
}

(suspect: true here because the previous point was 22 km away three seconds earlier.) A second request within 5 seconds:

{
  "error": "Too many location updates for this load",
  "code": "RATE_LIMITED",
  "message": "Too many location updates for this load",
  "retryAfter": 5
}

with the response header Retry-After: 5. Validation failure:

{
  "error": "speed must be between 0 and 70 m/s",
  "code": "INVALID_SPEED",
  "message": "speed must be between 0 and 70 m/s"
}

Post a batch

POST /api/tracking/batch (JWT or tracking:write) with { "locations": [ { "loadId", "latitude", "longitude", ...same fields } ] }. Up to 500 points, possibly for several loads. Each item succeeds or fails on its own; the response is always 200 unless the body itself is invalid.

curl -s -X POST https://www.loadeireann.ie/api/tracking/batch \
  -H "Authorization: Bearer $CARRIER_TOKEN" -H "Content-Type: application/json" \
  -d '{"locations":[{"loadId":"'$LOAD_ID'","latitude":53.0,"longitude":-7.0,"timestamp":"2026-11-08T22:32:25.872Z","accuracy":10,"speed":24,"heading":220},
       {"loadId":"'$LOAD_ID'","latitude":52.8,"longitude":-7.5,"timestamp":"2026-11-08T22:37:25.872Z","accuracy":12,"speed":24}]}'
{
  "success": true,
  "processed": 5,
  "successful": 3,
  "duplicates": 0,
  "failed": 2,
  "results": [
    {
      "index": 0,
      "loadId": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
      "success": true,
      "id": "cfac58ad-6463-421b-9cca-1dde52537444"
    },
    {
      "index": 1,
      "loadId": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
      "success": true,
      "id": "af68b185-76f4-4a82-8b94-2c0a0048e270",
      "suspect": true
    },
    {
      "index": 2,
      "loadId": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
      "success": true,
      "id": "ee46b951-3c9a-4b5f-8627-0a673020afd6",
      "suspect": true
    }
  ],
  "errors": [
    {
      "index": 3,
      "loadId": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
      "code": "INVALID_COORDINATES",
      "error": "latitude must be between -90 and 90"
    },
    {
      "index": 4,
      "loadId": "00000000-0000-0000-0000-000000000000",
      "code": "LOAD_NOT_FOUND",
      "error": "Load not found"
    }
  ]
}

Re-sending an item is idempotent:

{
  "success": true,
  "processed": 1,
  "successful": 1,
  "duplicates": 1,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "loadId": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
      "success": true,
      "duplicate": true,
      "id": "cfac58ad-6463-421b-9cca-1dde52537444"
    }
  ],
  "errors": []
}

Empty batch:

{
  "error": "Locations array is required",
  "code": "INVALID_BATCH",
  "message": "Locations array is required"
}

Location history

GET /api/loads/:id/location-history (JWT or tracking:read; same visibility rules as the live view).

Query Description
limit 1 to 5000, default 1000 (the most recent points are returned, oldest first)
since ISO date, lower bound (inclusive)
before ISO date, exclusive upper bound; pass nextBefore from the previous page to page backwards
simplify true to downsample with Douglas-Peucker
tolerance metres (1 to 1000, default 25) used with simplify
curl -s "https://www.loadeireann.ie/api/loads/$LOAD_ID/location-history?limit=3" -H "Authorization: Bearer $TOKEN"
{
  "loadId": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
  "loadStatus": "IN_TRANSIT",
  "trackingPoints": 2,
  "locations": [
    {
      "id": "cfac58ad-6463-421b-9cca-1dde52537444",
      "latitude": 53,
      "longitude": -7,
      "accuracy": 10,
      "speed": 24,
      "heading": 220,
      "altitude": null,
      "timestamp": "2026-11-08T22:32:25.872Z",
      "userType": "CARRIER",
      "lowAccuracy": false
    },
    {
      "id": "f251ce00-f739-4b14-8486-6852b6d2e645",
      "latitude": 53.3498,
      "longitude": -6.2603,
      "accuracy": null,
      "speed": null,
      "heading": null,
      "altitude": null,
      "timestamp": "2026-11-08T22:56:55.211Z",
      "userType": "CARRIER",
      "lowAccuracy": false
    }
  ],
  "currentLocation": {
    "id": "f251ce00-f739-4b14-8486-6852b6d2e645",
    "latitude": 53.3498,
    "longitude": -6.2603,
    "accuracy": null,
    "speed": null,
    "heading": null,
    "altitude": null,
    "timestamp": "2026-11-08T22:56:55.211Z",
    "userType": "CARRIER",
    "lowAccuracy": false
  },
  "hasMore": false,
  "nextBefore": null,
  "limit": 3
}

ETA

GET /api/loads/:id/eta (JWT or tracking:read; IN_TRANSIT only; otherwise { "eta": null, "reason": "NOT_IN_TRANSIT" }, or reason: "NO_POSITION" before the first point).

{
  "loadId": "ffebbe3d-494a-4772-990b-c9ac339e2b7e",
  "eta": {
    "etaAt": "2026-11-09T02:08:23.555Z",
    "distanceRemainingKm": 275,
    "method": "estimate",
    "confidence": "low",
    "updatedAt": "2026-11-08T22:56:55.211Z",
    "speedKmh": 86,
    "speedSamples": 1,
    "breakMinutes": 0,
    "assumptions": [
      "Straight-line distance x 1.25 road factor",
      "Median moving speed of last 30 min (1 samples), capped at 90 km/h",
      "EU rule: 45 min break per 4.5 h of remaining driving (hours already driven unknown)"
    ]
  },
  "delayMinutes": -1249,
  "deliveryWindowEnd": "2026-11-09T22:56:54.799Z"
}

method is route when the vehicle is within 3 km of the planned route, otherwise estimate (straight line times 1.25). confidence is high, medium or low; delay alerts are only raised for non-low confidence. delayMinutes is negative when early.

Tracking events

GET /api/loads/:id/tracking-events (JWT or tracking:read) returns the geofence and ETA milestones recorded once per load: ARRIVED_PICKUP, DEPARTED_PICKUP, NEAR_DELIVERY, ARRIVED_DELIVERY, DELAY_30, DELAY_60, DELAY_120. Geofence radius is 500 m; arrival needs an accurate point plus a second consecutive point or a 60 s dwell.

{
  "loadId": "81deb7eb-45b8-408c-85fb-e8fb34822297",
  "status": "IN_TRANSIT",
  "events": [
    {
      "id": "c7afb36b-e5e3-4f48-b21b-7b26650d1872",
      "type": "ARRIVED_PICKUP",
      "occurredAt": "2026-11-08T22:52:51.935Z",
      "lat": 53.3498,
      "lng": -6.2603,
      "source": "GEOFENCE",
      "meta": {
        "radiusM": 500,
        "distanceM": 13,
        "confirmedBy": "consecutive"
      }
    },
    {
      "id": "6e54f03f-9b81-4ba6-9e09-8b6151e45f03",
      "type": "DEPARTED_PICKUP",
      "occurredAt": "2026-11-08T22:56:13.513Z",
      "lat": 53.3592,
      "lng": -6.2688,
      "source": "GEOFENCE",
      "meta": {
        "radiusM": 500,
        "distanceM": 1188
      }
    },
    {
      "id": "8a9bfcad-7c1e-4008-965f-3a4e0752d47f",
      "type": "ARRIVED_DELIVERY",
      "occurredAt": "2026-11-08T22:56:13.513Z",
      "lat": 53.3592,
      "lng": -6.2688,
      "source": "GEOFENCE",
      "meta": {
        "radiusM": 500,
        "distanceM": 13,
        "suggestion": "CONFIRM_DELIVERY",
        "confirmedBy": "consecutive"
      }
    }
  ],
  "milestones": {
    "assignedAt": "2026-11-08T22:57:51.922Z",
    "pickedUpAt": "2026-11-08T22:57:53.472Z",
    "deliveredAt": null
  },
  "permissions": {
    "canShare": true
  }
}

ARRIVED_DELIVERY carries meta.suggestion: "CONFIRM_DELIVERY". Departing the pickup geofence never changes the load status; the carrier or driver sets IN_TRANSIT explicitly.

Read-only links for customers (JWT only). Owners, dispatcher-level staff of either company and admins can manage them (permissions.canShare).

POST /api/loads/:id/tracking-shares with { "label"?: string, "expiresIn"?: "DELIVERY_PLUS_24H" | "24H" | "7D" | "14D" | "30D" }. The default is delivery plus 24 hours (or 14 days if that is in the past); links never live longer than 30 days. At most 10 active links per load.

curl -s -X POST https://www.loadeireann.ie/api/loads/$LOAD_ID/tracking-shares \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"label":"Customer ABC","expiresIn":"7D"}'
{
  "id": "63b185a5-3776-43df-8d3f-957cac39b8dc",
  "label": "Customer ABC",
  "createdAt": "2026-11-08T22:57:26.072Z",
  "expiresAt": "2026-11-15T22:57:26.068Z",
  "revokedAt": null,
  "lastViewedAt": null,
  "viewCount": 0,
  "createdBy": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
  "active": true,
  "url": "https://www.loadeireann.ie/track/<one-time-token>"
}

The url (token) is returned once; only its hash is stored. GET /api/loads/:id/tracking-shares lists links without tokens (maxActive: 10); DELETE /api/loads/:id/tracking-shares/:shareId revokes (idempotent, { "success": true }).

{
  "shares": [
    {
      "id": "63b185a5-3776-43df-8d3f-957cac39b8dc",
      "label": "Customer ABC",
      "createdAt": "2026-11-08T22:57:26.072Z",
      "expiresAt": "2026-11-15T22:57:26.068Z",
      "revokedAt": null,
      "lastViewedAt": null,
      "viewCount": 0,
      "createdBy": "0a4de0b9-7307-4800-94db-eb0cbaccdf58",
      "active": true
    }
  ],
  "maxActive": 10
}

Public tracking view

GET /api/public/tracking/:token needs no authentication, is rate limited to 60 per minute per IP, and sends Cache-Control: no-store, X-Robots-Tag: noindex, nofollow and Referrer-Policy: no-referrer. The response is an explicit allow-list: coarse position, speed in km/h, a thinned route, origin and destination city and county only, ETA and milestone times. It never contains ids, street addresses, names, phone numbers, prices or driver details. Unknown, expired and revoked tokens all return the same 404.

{
  "status": "IN_TRANSIT",
  "trackingEnded": false,
  "position": {
    "lat": 53.3498,
    "lng": -6.2603,
    "timestamp": "2026-11-08T22:56:55.211Z",
    "speedKmh": null
  },
  "staleness": {
    "ageSeconds": 31,
    "stale": false
  },
  "route": [],
  "origin": {
    "city": "Dublin",
    "county": "Dublin"
  },
  "destination": {
    "city": "Cork",
    "county": "Cork"
  },
  "eta": {
    "etaAt": "2026-11-09T02:08:23.555Z",
    "distanceRemainingKm": 275,
    "method": "estimate",
    "confidence": "low",
    "updatedAt": "2026-11-08T22:56:55.211Z"
  },
  "etaToPickup": null,
  "events": {
    "pickedUpAt": "2026-11-08T22:56:55.242Z",
    "arrivedPickupAt": null,
    "departedPickupAt": null,
    "nearDeliveryAt": null,
    "arrivedDeliveryAt": null,
    "deliveredAt": null
  },
  "serverTime": "2026-11-08T22:57:26.090Z"
}
{
  "error": "Not found",
  "code": "NOT_FOUND"
}

Position tracking stops 24 hours after delivery (trackingEnded: true).

Endpoint Purpose
POST /api/tracking/consent/:loadId { "consented": boolean, "autoTrackingEnabled"?: boolean, "trackingInterval"?: 120..900 }. Carrier owners and the assigned driver only.
GET /api/tracking/consent/:loadId Read the current consent
GET /api/tracking/driver/status The driver's current tracking status

Invoices

An invoice is created automatically when a load is marked DELIVERED (a later POST /api/invoices for the same load returns 409 Invoice already exists for this load). Auth: JWT or API key (invoices:read) for the three read endpoints. Visible to the shipper and carrier companies of the load (staff need finances:view/invoices:view); admins see all.

Method and path Notes
GET /api/invoices Query status, page, limit (max 200). Response { invoices, pagination }
GET /api/invoices/:id { "invoice": { ... } }
GET /api/invoices/load/:loadId Invoice of a load
GET /api/invoices/:id/pdf Printable HTML document of the invoice (text/html)
PUT /api/invoices/:id/status Restricted: manual PAID is administrator-only; use the payment flow (POST /api/invoices/:id/pay-with-stripe, shippers) otherwise. 403 for everyone else.

Invoice statuses: DRAFT, PENDING, PAID, OVERDUE, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, DISPUTED. REFUNDED, PARTIALLY_REFUNDED and DISPUTED are set by Stripe events only and populate refundedAmount, refundedAt, disputedAt, disputeStatus.

curl -s "https://www.loadeireann.ie/api/invoices?limit=5&status=PENDING" -H "Authorization: Bearer $CARRIER_TOKEN"
{
  "invoices": [
    {
      "id": "240539ef-262c-4516-8597-14531350f08b",
      "loadId": "81deb7eb-45b8-408c-85fb-e8fb34822297",
      "invoiceNumber": "INV-20261108-CB9WB",
      "subtotal": 110,
      "vatRate": 0.23,
      "vatAmount": 26.57,
      "commissionRate": 0.05,
      "commissionAmount": 5.5,
      "total": 142.07,
      "currency": "EUR",
      "issueDate": "2026-11-08T22:58:40.952Z",
      "dueDate": "2026-12-08T22:58:40.952Z",
      "paidDate": null,
      "status": "PENDING",
      "paymentMethod": null,
      "refundedAmount": null,
      "disputedAt": null,
      "disputeStatus": null,
      "pdfUrl": null,
      "notes": null,
      "createdAt": "2026-11-08T22:58:40.952Z",
      "gpsData": "{ pickup, delivery, loadDetails, routeMapUrl, scheduledDates }"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 5,
    "totalPages": 1
  }
}
{
  "error": "Only an administrator can manually mark an invoice as paid. Use the invoice payment flow to pay."
}

Proof of delivery

Digital proof of delivery (recipient, signature or recorded refusal, photos, condition and exceptions, pallets, advisory location check) with a PDF certificate and an optional read-only consignee link. It is an electronic delivery record, not a legal CMR / e-CMR consignment note, not eFTI-compliant and not a customs document. Full reference: docs/POD.md.

Method and path Who Notes
GET /api/pod/load/:loadId, GET /api/pod/records/:id Parties of the load (JWT) or an API key with read:pod API keys get metadata only: status, recipient name, time, condition, exception count, pallets, photo count, verification code. No files, signature or coordinates
POST /api/pod/load/:loadId Carrier owner / dispatcher, assigned driver (JWT) Idempotent by clientRequestId. Completes delivery of an IN_TRANSIT load exactly once (load.delivered still fires once)
POST /api/pod/records/:id/accept, /dispute Shipper Dispute needs a reason; the carrier answers with /addendum
GET /api/pod/records/:id/pdf, GET /api/pod/attachments/:id Parties Authorised streaming; no public file URLs

Webhook events load.pod.submitted, load.pod.accepted, load.pod.disputed are delivered to the shipper and carrier companies (signature scheme unchanged). Invoice responses include pod: { available, status, podId }. Invoicing is not gated on proof of delivery.

Carrier verification

Carriers upload licence, insurance and tax documents; platform administrators review them; a company whose required documents are all reviewed and in date has level VERIFIED (PARTIAL when some are, UNVERIFIED when none are). Expiry is a calendar date, valid through the end of that day in Europe/Dublin. Which document types are required is platform policy and is listed by GET /api/verification/config. Full description: docs/VERIFICATION.md.

Method and path Who Notes
GET /api/verification/public/:companyId Any authenticated user, or an API key with read:verification Public-safe status: { verification: { companyId, level, verifiedAt, requiredTotal, requiredVerified, requiredMissing, nextExpiryAt, expiringSoon, coverBand, documents: [{ type, label, required, status, expiresAt }] } }. No document numbers, issuers, file names, exact cover amounts, or documents that are pending or rejected. coverBand is UNDER_100K, 100K_TO_500K, 500K_TO_1M, OVER_1M or null.
GET /api/verification/me, GET /api/verification/documents Carrier owner / staff with documents:view The company's own checklist and documents (JWT only)
POST /api/verification/documents (multipart), POST /api/verification/documents/:id/replace, DELETE /api/verification/documents/:id, PATCH /api/verification/me/settings Carrier owner / company admin (documents:manage) Upload (PDF, JPEG or PNG, up to 10 MB, 4 MB on Vercel; 30 per hour), replace, withdraw, mark the company as carrying dangerous goods
GET /api/verification/documents/:id/file Owning company staff, platform admins Authorised stream, never a public or pre-signed URL; other companies and shippers get 404

Require verified carriers on a load. POST /api/loads and PUT /api/loads/:id accept requireVerifiedCarrier (boolean, default false). When it is true, a carrier whose company is not VERIFIED cannot bid, accept the price, or register interest, and the shipper cannot accept such a bid or select such an interest: the API answers 403 { "error", "code": "CARRIER_NOT_VERIFIED", "message", "required": "load" | "platform", "level" } (carrier-side responses add "link": "/verification"). A platform administrator can also switch on a platform-wide requirement for assignment (required: "platform"); it is off by default. The check uses the live document dates, so a document that expired today blocks immediately.

Bid, interest and company objects returned to the other side of a load carry verificationLevel, verificationVerifiedAt and verificationNextExpiryOn (a date) under carrier.company. GET /api/bids/load/:loadId?verified=first|only lists verified carriers first or only.

Webhook events carrier.verification.changed, carrier.document.expiring (30, 14, 7 and 1 days before expiry) and carrier.document.expired are delivered to the carrier company itself, signed like every other event, with no document numbers or file details:

{
  "id": "evt_...",
  "event": "carrier.document.expiring",
  "timestamp": "2026-12-01T06:15:03.100Z",
  "data": { "document": { "id": "...", "type": "GOODS_IN_TRANSIT_INSURANCE", "label": "Goods in transit insurance", "status": "VERIFIED", "expiresAt": "2026-12-31", "daysUntilExpiry": 30, "thresholdDays": 30, "companyId": "..." } }
}

Ratings and reviews are not part of verification yet; a later version will add them to the same status object.

Fleet

Drivers (/api/drivers) and vehicles (/api/vehicles) are managed by carrier companies with the drivers:* permissions and are available with a JWT like everything else. They are used by the web app; they are not part of the stable public contract and are not covered by the OpenAPI file.

Backloads (return loads)

Carriers (and carrier staff) can ask for open loads near where a vehicle finishes a job. These endpoints are JWT only; API keys are not accepted. The full rules are in the product documentation (docs/BACKLOAD.md).

Endpoint Purpose
GET /api/backhaul/return-loads/:loadId Backloads near the drop-off of a load you carry; searches as that assignment's vehicle
GET /api/backhaul/search-by-location Backloads near location (city, county or eircode) or lat and lng
GET /api/backhaul/source-loads Your assigned, in-transit and delivered loads (search and pagination)
GET /api/backhaul/statistics?days=30 Backload rate and empty km from delivered loads, chained per vehicle

Parameters: maxRadiusKm (1 to 500; default by vehicle class: van 40, Luton 60, 7.5 t 100, rigid 150, artic 250), daysWindow (0 to 30; 1 for vans, 3 for trucks), limit (1 to 50), offset, vehicleId or vehicleType, includeIncompatible, sort (best, nearest, soonest, rate, home), minWeightKg, minPallets, minPricePerKm, baseLat and baseLng or towardsCounty, and the capability hints tailLift, refrigerated, adr.

Responses are { items, total, limit, offset, hasMore, meta }. Each item carries compatibility (fits true, false or "unknown", reasons, warnings) and backhaul (score 0 to 100 with scoreBreakdown, deadheadKm, loadedKm, emptyKmAvoided, estimatedRevenue, revenuePerKm, earliestPickup, feasibility). Loads with hideExactLocation return city and county only. Each item has backhaul.distanceSource (road or estimate, straight line x 1.25) and meta.distanceSource. For trucks backhaul.feasibility.driverHours { ok, remainingDailyMin, nextBreakInMin, requiredMin, note, label } is an advisory estimate from platform data, not a compliance record. Errors use { error, code, message }.

Deprecated: returnLoads and backloads (use items); statistics keys backhaulUtilization (use backloadRate), backhaulLoads (backloadedLegs), emptyMiles (emptyKmIncurred, it is kilometres) and potentialSavings (potentialRevenueLost, an estimate); the per-load estimatedDeadheadSavings was removed.

Webhooks

Webhooks push events to your HTTPS endpoint. Configure them in Settings, API Management or with PUT /api/api-keys/webhook (JWT of an owner or admin).

curl -s -X PUT https://www.loadeireann.ie/api/api-keys/webhook \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"webhookUrl":"https://example.com/hooks/loadeireann","webhookEvents":["load.created","load.status_changed","load.delivered"]}'

The signing secret (whsec_...) is returned once, when you first save a URL, and again whenever you rotate it with POST /api/api-keys/webhook/rotate-secret:

{
  "success": true,
  "message": "Signing secret rotated. Store it now - it will not be shown again.",
  "webhookSecret": "whsec_<64 hex characters, shown once>",
  "secretHint": "whsec_…0b5e",
  "secretRotatedAt": "2026-11-09T03:41:53.833Z"
}

Secrets are stored encrypted. GET /api/api-keys/webhook shows status, URL, subscribed events and a secretHint, never the secret.

Rotating the secret without downtime (grace window)

POST /api/api-keys/webhook/rotate-secret accepts an optional graceHours (number from 0 to 72, default 0, anything else is 400 INVALID_GRACE):

curl -s -X POST https://www.loadeireann.ie/api/api-keys/webhook/rotate-secret \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" -d '{"graceHours":24}'
{
  "success": true,
  "message": "Signing secret rotated. Store it now - it will not be shown again.",
  "webhookSecret": "whsec_<64 hex characters, shown once>",
  "secretHint": "whsec_…0b5e",
  "secretRotatedAt": "2026-11-09T04:01:50.100Z",
  "graceHours": 24,
  "previousSecretExpiresAt": "2026-11-10T04:01:50.100Z"
}
  • With graceHours of 0 (default) the old secret stops working immediately.

  • With a grace window, every delivery until previousSecretExpiresAt carries two signatures in the same header, new secret first: X-LoadEireann-Signature: v1=<hmac with the new secret>,v1=<hmac with the old secret> (comma separated, no spaces, both computed over the same timestamp.body). After the window the header has a single v1= value again. The old secret is stored encrypted and discarded when the window ends; GET /api/api-keys/webhook shows previousSecretExpiresAt while it is active.

  • Your receiver must accept the request if ANY v1= value matches (the samples below do). Then switch it to the new secret at any point inside the window and nothing is dropped. A receiver that compares the whole header as one string will reject deliveries during a grace window.

  • Saving a URL for the first time (which generates a secret) and rotating without a grace window both clear any previous secret. Resent and retried deliveries are signed with the secrets valid at the time of that attempt.

  • URL rules: HTTPS only, at most 2048 characters, no embedded credentials, and a public host. localhost, private ranges, link-local and cloud metadata addresses are rejected when you save the URL and again at send time (the host is re-resolved and the connection is pinned to the checked address). Redirects are not followed.

  • Load events (load.*) are sent to the shipper's company, for the loads that company posted. Invoice events (invoice.*) are sent to both the shipper company and the carrier company of the load, each only if that company configured a webhook and subscribed; a company never receives events for another company's invoices.

  • You only receive events you subscribed to (ping is always deliverable).

Rejected URLs:

{
  "error": "Webhook URL must use HTTPS",
  "code": "WEBHOOK_URL_NOT_HTTPS",
  "message": "Webhook URL must use HTTPS"
}
{
  "error": "Webhook URL must not point to a private or reserved address",
  "code": "WEBHOOK_URL_PRIVATE",
  "message": "Webhook URL must not point to a private or reserved address"
}
{
  "error": "Invalid webhook events",
  "code": "INVALID_EVENTS",
  "message": "Invalid webhook events",
  "invalidEvents": [
    "nope.event"
  ],
  "validEvents": [
    "load.created",
    "load.bid_received",
    "load.assigned",
    "load.status_changed",
    "load.delivered",
    "load.update",
    "load.location_updated",
    "load.arrived",
    "load.departed",
    "load.delayed",
    "invoice.created",
    "invoice.paid",
    "ping"
  ]
}

Request format

Each delivery is a POST with a JSON body and these headers:

Header Value
Content-Type application/json
User-Agent LoadEireann-Webhooks/1.0
X-LoadEireann-Event event name, for example load.status_changed
X-LoadEireann-Delivery-Id evt_..., stable across retries; the same value is id in the body
X-LoadEireann-Timestamp Unix seconds when this attempt was made
X-LoadEireann-Signature v1= followed by the hex HMAC-SHA256 (see below). During a secret-rotation grace window: v1=<new>,v1=<old>; accept the request if any value matches

Body envelope: id (string), event (string), timestamp (ISO time the event was produced) and data (event specific).

{
  "id": "evt_db6b1b047a194cee93b257ee0e93db26",
  "data": {
    "loadId": "dbd44990-559f-47ce-968f-999fef10c0f5",
    "timestamp": "2026-11-09T03:44:57.167Z",
    "currentStatus": "IN_TRANSIT",
    "previousStatus": "ASSIGNED",
    "referenceNumber": "Late run"
  },
  "event": "load.status_changed",
  "timestamp": "2026-11-09T03:44:57.169Z"
}

Signature verification

signature = "v1=" + hex(HMAC_SHA256(secret, timestamp + "." + rawBody)), where timestamp is the value of X-LoadEireann-Timestamp and rawBody is the exact raw request body (before JSON parsing). Steps:

  1. Read the raw body and the two headers.
  2. Recompute the signature and compare it in constant time against each comma-separated v1= value in the header (there are two only while a secret rotation grace window is active); accept if any matches.
  3. Reject if the timestamp is more than 5 minutes from your clock (replay protection).
  4. De-duplicate on X-LoadEireann-Delivery-Id.

This scheme replaces the earlier one that signed only the body and sent bare hex in X-LoadEireann-Signature without a timestamp. If you have an old receiver, update it.

Node.js (Express):

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/hooks/loadeireann', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-LoadEireann-Timestamp') || '';
  const given = (req.get('X-LoadEireann-Signature') || '').split(',').map((v) => v.trim()); // "v1=<new>,v1=<old>" during a rotation grace window
  const expected = 'v1=' + crypto.createHmac('sha256', process.env.LE_WEBHOOK_SECRET)
    .update(`${ts}.`).update(req.body).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
  const matches = given.some((g) => g.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(g), Buffer.from(expected)));
  const ok = fresh && matches;
  if (!ok) return res.status(401).end();
  const event = JSON.parse(req.body.toString('utf8'));
  // store event.id first; ignore it if you have seen it before, then process asynchronously
  res.status(200).json({ received: true });
});

Python (Flask):

import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/hooks/loadeireann")
def hook():
    raw = request.get_data()  # raw bytes, before parsing
    ts = request.headers.get("X-LoadEireann-Timestamp", "")
    given = [v.strip() for v in request.headers.get("X-LoadEireann-Signature", "").split(",")]  # "v1=<new>,v1=<old>" during a rotation grace window
    signed = ts.encode() + b"." + raw
    expected = "v1=" + hmac.new(os.environ["LE_WEBHOOK_SECRET"].encode(), signed, hashlib.sha256).hexdigest()
    matches = any(hmac.compare_digest(g, expected) for g in given)
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300 or not matches:
        abort(401)
    event = request.get_json(force=True)
    return {"received": True}

PHP:

<?php
$raw = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_LOADEIREANN_TIMESTAMP'] ?? '';
$given = array_map('trim', explode(',', $_SERVER['HTTP_X_LOADEIREANN_SIGNATURE'] ?? '')); // "v1=<new>,v1=<old>" during a rotation grace window
$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $raw, getenv('LE_WEBHOOK_SECRET'));
$matches = count(array_filter($given, fn($g) => hash_equals($expected, $g))) > 0;
if (!ctype_digit($ts) || abs(time() - (int)$ts) > 300 || !$matches) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
http_response_code(200);
echo json_encode(['received' => true]);

C# (ASP.NET Core minimal API):

app.MapPost("/hooks/loadeireann", async (HttpRequest req) =>
{
    using var ms = new MemoryStream();
    await req.Body.CopyToAsync(ms);
    var ts = req.Headers["X-LoadEireann-Timestamp"].ToString();
    var given = req.Headers["X-LoadEireann-Signature"].ToString().Split(',', StringSplitOptions.TrimEntries); // "v1=<new>,v1=<old>" during a rotation grace window
    var signed = Encoding.UTF8.GetBytes(ts + ".").Concat(ms.ToArray()).ToArray();
    var key = Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("LE_WEBHOOK_SECRET")!);
    var expected = "v1=" + Convert.ToHexString(HMACSHA256.HashData(key, signed)).ToLowerInvariant();
    var fresh = long.TryParse(ts, out var t) && Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) <= 300;
    var matches = given.Any(g => Encoding.UTF8.GetBytes(g).Length == Encoding.UTF8.GetBytes(expected).Length &&
        CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(g), Encoding.UTF8.GetBytes(expected)));
    if (!fresh || !matches)
        return Results.Unauthorized();
    return Results.Ok(new { received = true });
});

(The Node.js and Python samples were executed against real deliveries from this API, including a rejected bad signature and, for the multi-value header, a delivery signed with two secrets; the PHP and C# samples use the same algorithm and were not executed in this environment.)

Delivery semantics

  • Success: any 2xx within 8 seconds. The 8 seconds are a hard overall deadline for DNS, connecting, sending and receiving the response: a receiver that is unreachable or silent is cut off at 8 s and the attempt counts as a retryable timeout (Timed out after 8s). Respond immediately and process asynchronously.
  • Retries: network errors, timeouts, 5xx, 408, 425 and 429 are retried; other 4xx and 3xx are final. Up to 8 attempts in total, with delays after attempts 1 to 7 of about 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours and 12 hours (each with plus or minus 20 percent jitter), roughly 22 hours overall. The retry job runs every minute.
  • Idempotency: every delivery has a stable id (X-LoadEireann-Delivery-Id, also id in the body). Retries reuse it, so de-duplicate on it.
  • Ordering: not guaranteed, especially across retries. Use timestamp and object timestamps to order. load.location_updated is throttled to one delivery per load every 30 seconds with the newest point.
  • Auto-disable: after 50 consecutive failed attempts spanning at least 3 days the webhook is disabled and company admins are notified. Saving the webhook settings again re-enables it.
  • Delivery log: every attempt is recorded for 30 days and visible in API Management or via GET /api/api-keys/webhook/deliveries (page, limit, event, status); POST /api/api-keys/webhook/deliveries/:id/resend re-sends a delivery. At most 5 deliveries per company are in flight at once.
  • IP allow-listing: requests originate from the hosting platform and the source addresses are not fixed; rely on the signature, not on IP filtering.
{
  "deliveries": [
    {
      "id": "5b6f535b-8239-45cc-b864-c1220a6ff8e5",
      "event": "load.status_changed",
      "url": "https://example.com/hooks/loadeireann",
      "status": "retrying",
      "success": false,
      "statusCode": 500,
      "durationMs": 4,
      "attempt": 1,
      "maxAttempts": 8,
      "error": "HTTP 500",
      "nextRetryAt": "2026-11-09T03:43:07.260Z",
      "requestId": "evt_c615e374a71a4d90a82913029a651282",
      "isTest": false,
      "createdAt": "2026-11-09T03:42:16.056Z"
    },
    {
      "id": "6561d1bb-d02f-4102-b9f0-018c71c1b48e",
      "event": "load.delivered",
      "url": "https://example.com/hooks/loadeireann",
      "status": "success",
      "success": true,
      "statusCode": 200,
      "durationMs": 3,
      "attempt": 1,
      "maxAttempts": 8,
      "error": null,
      "nextRetryAt": null,
      "requestId": "evt_610dea6967ac42418e2ef77d2900f0fa",
      "isTest": false,
      "createdAt": "2026-11-09T03:42:16.059Z"
    }
  ],
  "...": "total, page and limit omitted"
}

A failed delivery that is scheduled for retry shows status: "retrying", the statusCode your endpoint returned and nextRetryAt; after the retry succeeds it shows status: "success" with attempt: 2.

Event catalogue

Subscribable events (GET /api/api-keys/webhook/events returns the live list): load.created, load.bid_received, load.assigned, load.status_changed, load.delivered, load.update, load.location_updated, load.arrived, load.departed, load.delayed, load.released, network.member.joined, network.member.removed, invoice.created, invoice.paid, invoice.refunded, invoice.disputed, load.pod.submitted, load.pod.accepted, load.pod.disputed, carrier.verification.changed, carrier.document.expiring, carrier.document.expired. ping is the test event and needs no subscription.

load.created (non-draft load posted):

{
  "id": "evt_ea3650547896476d8c00b914dd4ef7d8",
  "data": {
    "price": 150,
    "loadId": "dbd44990-559f-47ce-968f-999fef10c0f5",
    "status": "POSTED",
    "currency": "EUR",
    "originCity": "Dublin",
    "pickupDate": "2026-11-09T04:44:54.717Z",
    "destinationCity": "Cork",
    "referenceNumber": "Late run"
  },
  "event": "load.created",
  "timestamp": "2026-11-09T03:44:57.083Z"
}

load.bid_received:

{
  "id": "evt_e55ba80aa0c9476a96404e96f49c3895",
  "data": {
    "bidId": "d8494cbe-2300-4248-9421-b835450e24be",
    "amount": 140,
    "loadId": "dbd44990-559f-47ce-968f-999fef10c0f5",
    "message": null,
    "currency": "EUR",
    "carrierId": "9a54a1d9-6fe0-4f91-8735-1c6a75d883ac",
    "carrierName": "Example Haulage Ltd",
    "referenceNumber": "Late run"
  },
  "event": "load.bid_received",
  "timestamp": "2026-11-09T03:44:57.115Z"
}

load.assigned (bid accepted or instant accept):

{
  "id": "evt_6b70f50e82e54b53a1ba77bdd05460b4",
  "data": {
    "loadId": "dbd44990-559f-47ce-968f-999fef10c0f5",
    "carrierId": "9a54a1d9-6fe0-4f91-8735-1c6a75d883ac",
    "assignedAt": "2026-11-09T03:44:57.142Z",
    "carrierName": "Example Haulage Ltd",
    "referenceNumber": "Late run"
  },
  "event": "load.assigned",
  "timestamp": "2026-11-09T03:44:57.144Z"
}

load.status_changed (shown above) is sent for ASSIGNED to IN_TRANSIT and IN_TRANSIT to DELIVERED.

load.location_updated (eta is an ISO time, distanceRemaining is kilometres):

{
  "id": "evt_6d109d2c6fc84fc6a66df8f403369bbe",
  "data": {
    "eta": "2026-11-09T03:47:20.694Z",
    "speed": 2,
    "loadId": "c7c7c66d-abb3-4948-ac44-7cf1597c9b5e",
    "heading": null,
    "latitude": 53.3599,
    "etaMethod": "estimate",
    "longitude": -6.2699,
    "timestamp": "2026-11-09T03:44:36.977Z",
    "etaConfidence": "low",
    "distanceRemaining": 1.6
  },
  "event": "load.location_updated",
  "timestamp": "2026-11-09T03:45:25.446Z"
}

load.arrived (geofence; stop is pickup or delivery):

{
  "id": "evt_0b0186ad14c94ea095ad402c4890f4e6",
  "data": {
    "stop": "delivery",
    "loadId": "c7c7c66d-abb3-4948-ac44-7cf1597c9b5e",
    "latitude": 53.3592,
    "eventType": "ARRIVED_DELIVERY",
    "longitude": -6.2688,
    "occurredAt": "2026-11-09T03:43:16.977Z",
    "suggestion": "CONFIRM_DELIVERY"
  },
  "event": "load.arrived",
  "timestamp": "2026-11-09T03:44:57.030Z"
}

load.departed:

{
  "id": "evt_461ff26859fa4c00a65ca21278f66289",
  "data": {
    "stop": "pickup",
    "loadId": "c7c7c66d-abb3-4948-ac44-7cf1597c9b5e",
    "latitude": 53.3592,
    "eventType": "DEPARTED_PICKUP",
    "longitude": -6.2688,
    "occurredAt": "2026-11-09T03:43:16.977Z"
  },
  "event": "load.departed",
  "timestamp": "2026-11-09T03:44:57.017Z"
}

load.delayed (predicted delivery late by 30, 60 or 120 minutes; thresholdMinutes says which):

{
  "id": "evt_021ce33dfe7f4502a64d6bb61aa85e12",
  "data": {
    "eta": "2026-11-09T06:15:15.050Z",
    "loadId": "dbd44990-559f-47ce-968f-999fef10c0f5",
    "latitude": null,
    "eventType": "DELAY_120",
    "longitude": null,
    "occurredAt": "2026-11-09T03:44:57.234Z",
    "delayMinutes": 330,
    "thresholdMinutes": 120
  },
  "event": "load.delayed",
  "timestamp": "2026-11-09T03:44:57.273Z"
}

load.delivered:

{
  "id": "evt_610dea6967ac42418e2ef77d2900f0fa",
  "data": {
    "loadId": "fcd2c149-1818-4112-be49-8e30dc2564b7",
    "deliveredAt": "2026-11-09T03:42:16.056Z",
    "referenceNumber": "Pallets Dublin to Galway",
    "signedByReceiver": false
  },
  "event": "load.delivered",
  "timestamp": "2026-11-09T03:42:16.059Z"
}

load.update is a generic event sent in addition to load.assigned, load.status_changed, load.location_updated and load.delivered; its data is the same as that event plus updateType. Subscribe to it instead of the individual events if you want a single stream.

Invoice events

Invoice events cover load invoices (the invoice created when a load is delivered, or manually by the carrier). Warehouse billing invoices do not emit webhooks. They go to the shipper company and the carrier company of the load (each only if subscribed), are sent once per transition (the delivery id is derived from the invoice and the transition, so a Stripe redelivery or a second code path never produces a duplicate), and are never sent for DRAFT or CANCELLED invoices.

Event When
invoice.created A load invoice is issued (automatically on delivery, or POST /api/invoices)
invoice.paid The invoice becomes PAID (card payment, Stripe confirmation, or an administrator marks it paid)
invoice.refunded The invoice becomes REFUNDED or PARTIALLY_REFUNDED, including a lost dispute (data.dispute.outcome is lost). Further partial refunds with a larger refundedAmount produce further events
invoice.disputed A card dispute is opened (data.dispute.outcome is opened, invoice status DISPUTED) or won (won, the invoice is back to PAID or PARTIALLY_REFUNDED)

Payload (all amounts in the invoice currency, rounded to cents; paidAmount is the invoice total once paid and 0 before; no bank details or personal data are included, fetch the full invoice with GET /api/invoices/:id if you need more):

{
  "id": "evt_f96628050345e5b35d560e49359788b1",
  "event": "invoice.created",
  "timestamp": "2026-11-09T04:01:45.340Z",
  "data": {
    "invoice": {
      "id": "6df9dc4f-c1a3-41c8-9946-b8d6fbe62d5b",
      "number": "INV-20261109-GMD2A",
      "status": "PENDING",
      "currency": "EUR",
      "subtotal": 100,
      "vatAmount": 24.15,
      "commissionAmount": 5,
      "total": 129.15,
      "paidAmount": 0,
      "refundedAmount": 0,
      "loadId": "2008774b-bcd2-4286-ac9e-8897c1651cc9",
      "issuedAt": "2026-11-09T04:01:45.279Z",
      "dueDate": "2026-12-09T04:01:45.276Z",
      "paidAt": null
    }
  }
}

invoice.paid has status: "PAID", paidAmount equal to total and paidAt set; invoice.refunded has refundedAmount. Events caused by a dispute add "dispute": { "id": "dp_...", "outcome": "opened" | "won" | "lost" } next to invoice. The payload shape changed from the never-emitted draft of invoice.created / invoice.paid documented in earlier versions of this guide (flat invoiceId, amount, ...); nothing was ever delivered in that shape.

referenceNumber is the load's title (there is no separate reference field).

Test webhook

POST /api/api-keys/webhook/test sends a signed ping to the configured URL (same SSRF rules, 8 second timeout, no redirects, limited to 10 per minute) and returns the receiver's status and latency:

{
  "success": true,
  "message": "Test webhook delivered",
  "deliveryId": "evt_7aec88ac6df8490ea0f69f7964eeb702",
  "statusCode": 200,
  "durationMs": 15,
  "error": null,
  "responseSnippet": "{\"received\":true}"
}

The receiver sees:

{
  "id": "evt_7aec88ac6df8490ea0f69f7964eeb702",
  "data": {
    "message": "This is a test webhook from Load Éireann.",
    "companyId": "61abe193-d959-4ab6-8df1-4304c9fa32eb"
  },
  "event": "ping",
  "timestamp": "2026-11-09T03:41:53.845Z"
}

Private networks

A shipper can keep a closed network of carriers and offer loads to it first. Network management (/api/networks) is for the web app and accepts a login token only; API keys are not accepted there. What an integration can do:

  • POST /api/loads and PUT /api/loads/:id accept visibility (PUBLIC default, NETWORK_ONLY, NETWORK_THEN_PUBLIC), networkId (optional when your company has exactly one active network) and releaseAfterMinutes (5 to 10080, for NETWORK_THEN_PUBLIC). Errors are 400/404/409/422 { error, code, message }, for example NETWORK_EMPTY, NETWORK_REQUIRED, INVALID_RELEASE, NON_MEMBER_BIDS_EXIST.
  • Private loads are invisible to everyone outside the network: list, GET /api/loads/:id, bids and interest answer 404 Load not found exactly as for an unknown id. A release is computed at read time, so it takes effect at releaseAt even if no job runs.
  • Webhooks, delivered to the owning company only: load.released (the load became visible to everyone, manual says whether you released it), network.member.joined, network.member.removed. load.created now also carries visibility, networkId and releaseAt. Signatures are unchanged. A carrier subscription never receives another company's private load events.

Real-time with Socket.IO (optional)

Connect to the API origin with the JWT:

import { io } from 'socket.io-client';
const socket = io('https://www.loadeireann.ie', { auth: { token } });
socket.emit('join-load', { loadId }, (ack) => console.log(ack)); // { ok: true, loadId } or { ok: false, code }
socket.on('load-location-updated', (p) => console.log(p));       // { loadId, lat, lng, speed, heading, accuracy, timestamp, eta? }
socket.on('load-tracking-event', (e) => console.log(e));          // geofence / ETA milestones
  • Authentication: auth.token (or an Authorization: Bearer header). Errors: AUTH_REQUIRED, INVALID_TOKEN, then after connect AUTH_EXPIRED, SESSION_REVOKED, ACCOUNT_DISABLED.
  • Rooms: user-<id> is joined automatically; join-load joins load:<id> with the same access rules as the location history (FORBIDDEN, NOT_FOUND, INVALID_LOAD, TOKEN_EXPIRED). load-room-evicted is sent when access is lost. leave-load leaves.
  • This section was derived from the source and was not exercised live for this version.

Accounting integrations

Connect Xero, QuickBooks Online, Sage or FreeAgent in Settings, Accounting integrations; invoices then sync automatically when created, paid or refunded, and failed syncs are retried and visible in the sync log. Step-by-step guides: Overview, Xero, QuickBooks, Sage, FreeAgent. The integration endpoints under /api/accounting (providers, status, connect, disconnect, sync, sync logs) are used by the web app and are not part of the stable public API.

Data protection

  • Driver GPS consent: a driver's positions are only accepted after the driver consents for that load (POST /api/tracking/consent/:loadId); without consent the API answers 403 TRACKING_CONSENT_REQUIRED. Carrier owner, staff and admin updates are made on behalf of the carrier company and are not consent-gated.
  • Purpose and visibility: location is only visible to the shipper, the carrier side, the assigned driver and admins, and only while a load is ASSIGNED, IN_TRANSIT or up to 24 hours after delivery.
  • Retention: raw GPS points are deleted by a daily job after 90 days by default (LOCATION_RETENTION_DAYS).
  • Data minimisation on public links: the public tracking view returns coarse data only (see above), is revocable, expires within 30 days at most, and is never indexed.
  • You are the controller of the personal data you send to or retrieve from the API for your own drivers; make sure drivers have received your privacy notice.

Versioning and deprecation

The API is currently unversioned (/api/...). Changes are additive where possible: new fields and new webhook events may appear at any time, so parse leniently and ignore unknown fields. Breaking changes will be announced in this changelog and by email to company owners, with at least 90 days notice and a parallel path where feasible. Pin your integration to the behaviour documented here and test against the OpenAPI file.

Changelog

2026-11

  • Private networks: visibility, networkId, releaseAfterMinutes on loads; webhooks load.released, network.member.joined, network.member.removed; private loads answer 404 to non-members.
  • Carrier verification: /api/verification/*, the read:verification scope, requireVerifiedCarrier on loads (403 CARRIER_NOT_VERIFIED), verification level on bid / interest / company objects, and the webhook events carrier.verification.changed, carrier.document.expiring, carrier.document.expired.
  • Backloads: validated parameters, pagination, vehicle-aware compatibility and class defaults, honest statistics names, privacy of hideExactLocation loads; see the Backloads section.
  • Vans: documented vehicle classes and the van-friendly load fields (weightUnit, cargoLengthM, cargoWidthM, cargoHeightM, isUrgent); new loads list filters vehicleType, vehicleGroup, vehicleFit, includeUnspecified, maxPallets, isUrgent.
  • Tracking hardening: strict point validation with stable error codes, 24 h age limit, 5-second per-load limit with Retry-After, idempotent batch (/api/tracking/batch, max 500), suspect-point detection, driver consent enforcement.
  • Geofence events (ARRIVED_PICKUP, DEPARTED_PICKUP, ARRIVED_DELIVERY) and webhooks load.arrived, load.departed.
  • ETA service (GET /api/loads/:id/eta), NEAR_DELIVERY and DELAY_30/60/120 events and the load.delayed webhook; eta, etaMethod, etaConfidence added to load.location_updated.
  • Share links for read-only public tracking (/api/loads/:id/tracking-shares, /api/public/tracking/:token).
  • load.location_updated webhooks throttled to one per load per 30 seconds.
  • Session revocation (SESSION_REVOKED) on force-logout, role change, deactivation and password reset.
  • Permission model tightened (owner, admin, dispatcher, driver, accountant, viewer; company-scoped invoice access).
  • Accounting integrations (Xero, QuickBooks, Sage, FreeAgent) with sync log and retry.
  • New invoice statuses REFUNDED, PARTIALLY_REFUNDED, DISPUTED.
  • Loads list filters: minPrice, maxPrice, minWeight, maxWeight, pickupDateFrom, pickupDateTo, requiredEquipment, isHazmat, requiresRefrigeration, sortBy, sortOrder.
  • API keys are now accepted as credentials (X-API-Key or Authorization: Bearer le_...) with per-key scopes (read:loads, write:loads, tracking:read, tracking:write, invoices:read), expiry, IP allow-list, rotation with grace period, revocation, usage tracking and a 600 per minute rate limit. Keys are stored hashed.
  • Webhooks: new signature v1=HMAC(secret, timestamp.body) with X-LoadEireann-Timestamp, X-LoadEireann-Delivery-Id and body id (breaking: the old scheme signed only the body); automatic retries (8 attempts over about 22 hours), delivery log, resend, auto-disable, secret rotation, ping test event, load.update subscribable, SSRF protection (HTTPS and public hosts only).
  • This guide rewritten against the code.
  • Invoice webhooks are now emitted: invoice.created, invoice.paid and the new invoice.refunded and invoice.disputed (load invoices only, to the shipper and carrier companies, once per transition).
  • Webhook secret rotation grace window: rotate-secret accepts graceHours (0 to 72); during the window deliveries carry X-LoadEireann-Signature: v1=<new>,v1=<old>. Receivers must accept any matching v1= value.
  • A hard 8 second overall deadline now applies to every delivery (connect plus response).
  • API keys presented to JWT-only endpoints now get 403 API_KEY_ROUTE_NOT_ALLOWED instead of 401 No token provided.
  • GET /api/api-keys/keys returns per-key usage (last 24 h, last 7 d, 24 hourly points).

Support

Questions, bugs or integration help: info@loadeireann.ie. Privacy questions: privacy@loadeireann.ie. Include the request path, the time (UTC) and the code of the error you received; never send tokens or the webhook secret.

Base URL

All endpoints live under https://www.loadeireann.ie/api

Authentication

Server-to-server integrations send a scoped API key in X-API-Key. The web app and the full API use a JWT as Authorization: Bearer <token> from POST /api/auth/login.

Webhooks

Configure your webhook URL and events in API Management.

Need help?

Our team can help you integrate Load Éireann with your systems.

Contact support