API DOCUMENTATION
Today you can post and manage loads via CSV upload (see Bulk CSV upload) and the logged-in JSON endpoints below (session cookie after login). Perfect for recurring files or scripts that reuse your web login; separate API-key access for unattended TMS hooks is not available yet.
Authentication
JSON endpoints use the same session cookie as the web app after /login. There is no Bearer token today.
Open-load discovery (Find Backhaul) uses the same core logic as GET /api/matches/find-for-vehicle: results are sorted on the server so better vehicle/load fit comes first, then road distance to the pickup (ascending). Distances use road routing where configured — not straight-line “as the crow flies”.
If a load specifies a required vehicle type (artic/rigid/van), only that type is returned — mismatches are filtered out, not shown as “near match”. Remaining candidates are scored “perfect” vs near match (trailer preference, equipment flags), then:
# Order of results returned to the client
pairs.sort(key=lambda x: (not x.is_perfect_match, x.distance_miles))
Loads that fail hard requirements (wrong vehicle type, weight over capacity, missing required tail lift / temp / ADR) are omitted entirely.
GET /api/matches/find-for-vehicle
Query parameters:
Example: GET /api/matches/find-for-vehicle?vehicle_id=123&origin_postcode=M1%201AA&radius_miles=25
Each item is a LoadMatchResult: the nested load plus distance_miles. Match quality is reflected in the order of the array (best matches first). The dashboard may show extra flags (e.g. perfect vs near); ask us if you need those fields exposed in JSON for integrations.
[
{
"load": {
"id": 456,
"pickup_postcode": "M2 5DB",
"delivery_postcode": "B1 1AA",
"budget_gbp": 300,
"status": "open",
"weight_kg": 5000,
"requirements": { "vehicle_type": "rigid", "trailer_type": "curtain_sider" }
},
"distance_miles": 8.3
},
{
"load": {
"id": 789,
"pickup_postcode": "M15 6AZ",
"delivery_postcode": "L1 8JQ",
"budget_gbp": 250,
"status": "open"
},
"distance_miles": 12.1
}
]
When you use Find Backhaul in the web app with both origin and destination, we also blend corridor matches (loads near your return route) with origin-radius matches — still sorted by match quality then distance. There is no separate public JSON endpoint documented here for corridor; behaviour is described in Terms (section 11).
For the philosophy behind ranking (no pay-to-rank, no random ordering), see Terms — Smart Matching Algorithm.
Base URL: https://platoonix.co.uk
Create a new load
Request body:
{
"shipper_name": "Acme Ltd",
"pickup_postcode": "M1 1AD",
"delivery_postcode": "LS1 1UR",
"pickup_window_start": "2026-04-08T09:00:00Z",
"pickup_window_end": "2026-04-08T17:00:00Z",
"budget_gbp": 300,
"pickup_site_name": "Manchester depot",
"pickup_address": "1 Depot Rd, Manchester",
"pickup_contact_name": "Gate",
"pickup_contact_phone": "07700900123",
"delivery_site_name": "Leeds store",
"delivery_address": "2 High St, Leeds",
"delivery_contact_name": "Receiving",
"delivery_contact_phone": "+447700900456",
"delivery_contact_email": "recv@example.com",
"delivery_link_self_send": false,
"contacts_share_permission": true
}
Required: shipper_name, postcodes, pickup/delivery windows, budget_gbp (greater than zero), pickup window not in the past, all site contact fields above, contacts_share_permission: true, and either delivery_contact_email or delivery_link_self_send: true.
Optional booking_ref: updates an existing open load for your loader (no job, no payment) instead of creating a duplicate; otherwise 409 Conflict with a clear message.
422 Unprocessable: {"errors": [{"field": "pickup_site_name", "message": "..."}]}
Site contacts are not returned on GET load/match responses (haulier sees them only after job payment is reserved).
Response (201 Created):
{
"id": 123,
"status": "open",
"pickup_postcode": "M1 1AD",
"delivery_postcode": "LS1 1UR",
"budget_gbp": 300,
"created_at": "2026-04-07T14:30:00Z"
}
List loads visible to your account (loaders: own loads; hauliers: loads tied to their jobs; admins: all). No query parameters.
Example: GET /api/loads
Response (200 OK):
[
{
"id": 123,
"shipper_name": "Acme Ltd",
"pickup_postcode": "M1 1AD",
"delivery_postcode": "LS1 1UR",
"budget_gbp": 300,
"status": "open",
"created_at": "2026-04-07T14:30:00Z"
}
]
Get single load details (if your account may access it).
Response (200 OK):
{
"id": 123,
"shipper_name": "Acme Ltd",
"pickup_postcode": "M1 1AD",
"delivery_postcode": "LS1 1UR",
"budget_gbp": 300,
"status": "open",
"created_at": "2026-04-07T14:30:00Z"
}
Admin only. Permanently delete a load with no backhaul jobs. Returns 204 No Content on success. Loaders cancel open loads via the dashboard, not this route.
Multipart file upload (file field). Same site-contact rules as POST /api/loads. Templates: loads.csv, loaders_loads.csv.
POST /api/upload/loads
Loader (own company) or admin. Response includes created, updated, rejected, and errors. Any validation error rejects the entire file (nothing committed).
booking_ref: when set and the uploading user has a loader_id, rows with the same reference update an existing open load that has no job and no payment; otherwise the row fails with a clear reason. Blank booking_ref always creates a new load. The web dashboard forms do not upsert — duplicate references are rejected there.
budget_gbp is required on every row and must be greater than zero. Pickup must be provided (pickup_window_start or pickup_date on consolidated files) and cannot be in the past (UTC calendar day).
In Excel, format phone columns as Text so numbers stay as 07… or +44… (a 10-digit value starting with 7 is accepted and normalised to 07…).
Columns (loads.csv)
POST /api/upload/loaders-loads
Creates loader companies (by contact_email) and loads in one file. Admin or loader with permission.
Columns (loaders_loads.csv)
FastAPI returns JSON {"detail": …} unless noted.
CSV upload and the logged-in JSON endpoints are included at no additional cost beyond normal platform fees.
Standard platform fees apply:
Same pricing whether you use web, CSV, or API.
Log in first; reuse the session cookie. Request body must include all required site-contact fields (same rules as the web form).
Python (requests.Session):
import requests
BASE = "https://platoonix.co.uk"
session = requests.Session()
session.post(f"{BASE}/login", data={
"email": "loader@example.com",
"password": "YOUR_PASSWORD",
})
payload = {
"shipper_name": "Acme Ltd",
"pickup_postcode": "M1 1AD",
"delivery_postcode": "LS1 1UR",
"pickup_window_start": "2026-04-08T09:00:00+00:00",
"pickup_window_end": "2026-04-08T17:00:00+00:00",
"delivery_window_start": "2026-04-09T08:00:00+00:00",
"delivery_window_end": "2026-04-09T18:00:00+00:00",
"budget_gbp": 300,
"pickup_site_name": "Manchester depot",
"pickup_address": "1 Depot Rd, Manchester",
"pickup_contact_name": "Gate",
"pickup_contact_phone": "07700900123",
"delivery_site_name": "Leeds store",
"delivery_address": "2 High St, Leeds",
"delivery_contact_name": "Receiving",
"delivery_contact_phone": "07700900456",
"delivery_contact_email": "recv@example.com",
"delivery_link_self_send": False,
"contacts_share_permission": True,
}
r = session.post(f"{BASE}/api/loads", json=payload)
print(r.status_code, r.json())
cURL (cookie jar):
# 1) Log in and save session cookie
curl -c cookies.txt -X POST https://platoonix.co.uk/login \
-d "email=loader@example.com" -d "password=YOUR_PASSWORD"
# 2) Create load with the same cookie jar
curl -b cookies.txt -X POST https://platoonix.co.uk/api/loads \
-H "Content-Type: application/json" \
-d '{
"shipper_name": "Acme Ltd",
"pickup_postcode": "M1 1AD",
"delivery_postcode": "LS1 1UR",
"pickup_window_start": "2026-04-08T09:00:00Z",
"pickup_window_end": "2026-04-08T17:00:00Z",
"delivery_window_start": "2026-04-09T08:00:00Z",
"delivery_window_end": "2026-04-09T18:00:00Z",
"budget_gbp": 300,
"pickup_site_name": "Manchester depot",
"pickup_address": "1 Depot Rd, Manchester",
"pickup_contact_name": "Gate",
"pickup_contact_phone": "07700900123",
"delivery_site_name": "Leeds store",
"delivery_address": "2 High St, Leeds",
"delivery_contact_name": "Receiving",
"delivery_contact_phone": "07700900456",
"delivery_contact_email": "recv@example.com",
"delivery_link_self_send": false,
"contacts_share_permission": true
}'
Standard Support (Included):
Need integration help or bulk automation beyond the dashboard?
Email support@platoonix.co.uk (subject: Integration) — e.g. TMS hooks, high-volume CSV, or future API keys.