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 fromPOST /api/auth/login. See Authentication for exactly which endpoints accept which.
Authentication
API keys (recommended for integrations)
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
401Invalid or expired tokenlog 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, codeSESSION_REVOKED) on force-logout, role change, deactivation or password reset. A deactivated user receives403 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,lastUsedIpandrequestCountin 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/loadsandPUT /api/loads/:idalso acceptmultipart/form-data(up to 10documents). - Dates: ISO 8601 in UTC, for example
2026-11-08T22:56:54.799Z. Request dates may be any stringDatecan 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/*andPATCH /api/loads/:id/location, 4 KB on tracking-link creation (413, codePAYLOAD_TOO_LARGE; malformed JSON gives400, codeINVALID_JSON). - Pagination: list endpoints take
page(1-based, default 1) andlimit. Loads: default 20, max 100. Invoices: default 20, max 200. Responses containpagination: { 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.
Share links
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).
Tracking consent (drivers)
| 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
graceHoursof0(default) the old secret stops working immediately.With a grace window, every delivery until
previousSecretExpiresAtcarries 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 sametimestamp.body). After the window the header has a singlev1=value again. The old secret is stored encrypted and discarded when the window ends;GET /api/api-keys/webhookshowspreviousSecretExpiresAtwhile 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 (
pingis 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:
- Read the raw body and the two headers.
- 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. - Reject if the timestamp is more than 5 minutes from your clock (replay protection).
- 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-Signaturewithout 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
2xxwithin 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,425and429are retried; other4xxand3xxare 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, alsoidin the body). Retries reuse it, so de-duplicate on it. - Ordering: not guaranteed, especially across retries. Use
timestampand object timestamps to order.load.location_updatedis 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/resendre-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/loadsandPUT /api/loads/:idacceptvisibility(PUBLICdefault,NETWORK_ONLY,NETWORK_THEN_PUBLIC),networkId(optional when your company has exactly one active network) andreleaseAfterMinutes(5 to 10080, forNETWORK_THEN_PUBLIC). Errors are400/404/409/422 { error, code, message }, for exampleNETWORK_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 answer404 Load not foundexactly as for an unknown id. A release is computed at read time, so it takes effect atreleaseAteven if no job runs. - Webhooks, delivered to the owning company only:
load.released(the load became visible to everyone,manualsays whether you released it),network.member.joined,network.member.removed.load.creatednow also carriesvisibility,networkIdandreleaseAt. 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 anAuthorization: Bearerheader). Errors:AUTH_REQUIRED,INVALID_TOKEN, then after connectAUTH_EXPIRED,SESSION_REVOKED,ACCOUNT_DISABLED. - Rooms:
user-<id>is joined automatically;join-loadjoinsload:<id>with the same access rules as the location history (FORBIDDEN,NOT_FOUND,INVALID_LOAD,TOKEN_EXPIRED).load-room-evictedis sent when access is lost.leave-loadleaves. - 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 answers403 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_TRANSITor 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,releaseAfterMinuteson loads; webhooksload.released,network.member.joined,network.member.removed; private loads answer 404 to non-members. - Carrier verification:
/api/verification/*, theread:verificationscope,requireVerifiedCarrieron loads (403 CARRIER_NOT_VERIFIED), verification level on bid / interest / company objects, and the webhook eventscarrier.verification.changed,carrier.document.expiring,carrier.document.expired. - Backloads: validated parameters, pagination, vehicle-aware compatibility and class defaults, honest statistics names, privacy of
hideExactLocationloads; see the Backloads section. - Vans: documented vehicle classes and the van-friendly load fields (
weightUnit,cargoLengthM,cargoWidthM,cargoHeightM,isUrgent); new loads list filtersvehicleType,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 webhooksload.arrived,load.departed. - ETA service (
GET /api/loads/:id/eta),NEAR_DELIVERYandDELAY_30/60/120events and theload.delayedwebhook;eta,etaMethod,etaConfidenceadded toload.location_updated. - Share links for read-only public tracking (
/api/loads/:id/tracking-shares,/api/public/tracking/:token). load.location_updatedwebhooks 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-KeyorAuthorization: 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)withX-LoadEireann-Timestamp,X-LoadEireann-Delivery-Idand bodyid(breaking: the old scheme signed only the body); automatic retries (8 attempts over about 22 hours), delivery log, resend, auto-disable, secret rotation,pingtest event,load.updatesubscribable, SSRF protection (HTTPS and public hosts only). - This guide rewritten against the code.
- Invoice webhooks are now emitted:
invoice.created,invoice.paidand the newinvoice.refundedandinvoice.disputed(load invoices only, to the shipper and carrier companies, once per transition). - Webhook secret rotation grace window:
rotate-secretacceptsgraceHours(0 to 72); during the window deliveries carryX-LoadEireann-Signature: v1=<new>,v1=<old>. Receivers must accept any matchingv1=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_ALLOWEDinstead of401 No token provided. GET /api/api-keys/keysreturns per-keyusage(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.