Platoonix

API Documentation

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.

API access for external systems (API keys) is not yet available. The endpoints below work for a logged-in session. For recurring uploads, use the CSV upload, or contact support@platoonix.co.uk to discuss integration.

GETTING STARTED

Authentication

JSON endpoints use the same session cookie as the web app after /login. There is no Bearer token today.

  1. POST /login with email and password (form body, same as the login page).
  2. Send subsequent /api/… requests with that session cookie (browser, requests.Session, or cURL -b cookie jar).
  3. Use Content-Type: application/json for POST /api/loads.

MATCHING ALGORITHM

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”.

Sorting logic (conceptual)

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.

Match endpoint

GET /api/matches/find-for-vehicle

Query parameters:

  • vehicle_id (required)
  • origin_postcode (required) — search origin; road miles to each load’s pickup
  • radius_miles (optional) — defaults to platform setting (often 25)

Example: GET /api/matches/find-for-vehicle?vehicle_id=123&origin_postcode=M1%201AA&radius_miles=25

Response shape

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
  }
]

Corridor (origin + destination)

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.

API ENDPOINTS

Base URL: https://platoonix.co.uk

POST /api/loads

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"
}

GET /api/loads

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 /api/loads/{load_id}

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"
}

DELETE /api/loads/{load_id}

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.

Bulk CSV upload

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)

  • Required row: shipper_name, pickup_postcode, delivery_postcode, budget_gbp, pickup_window_start (or end); pickup_site_name, pickup_address, pickup_contact_name, pickup_contact_phone; delivery_site_name, delivery_address, delivery_contact_name, delivery_contact_phone; contacts_share_permission (yes/true/1); delivery_contact_email unless delivery_link_self_send is yes/true/1
  • Optional: booking_ref, booking_name, pickup_window_end, delivery_window_start, delivery_window_end, weight_kg, pallets, volume_m3, required_vehicle_type, required_trailer_type, delivery_link_self_send

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)

  • Required row: company_name, contact_email, pickup_postcode, delivery_postcode, budget_gbp, pickup date or window (same site-contact and permission columns as loads.csv above)
  • Optional: contact_phone, contact_name, shipper_name, booking_ref, booking_name, weight_kg, pallets, pickup_date, pickup_window_start, pickup_window_end, delivery_window_start, delivery_window_end, vehicle_type_required, trailer_type_required, delivery_link_self_send
  • Same booking_ref upsert rules and response counts as POST /api/upload/loads (loads_created, loads_updated, loads_rejected).

COMMON ERRORS

FastAPI returns JSON {"detail": …} unless noted.

  • 401 — not logged in: {"detail": "Login required"}
  • 403 — wrong role or access: e.g. {"detail": "Loader login required"} or {"detail": "Not allowed"}
  • 404 — unknown load: {"detail": "Load not found"}
  • 422 — site contacts or request validation: {"detail": {"errors": [{"field": "pickup_site_name", "message": "This field is required"}]}}

PRICING

CSV upload and the logged-in JSON endpoints are included at no additional cost beyond normal platform fees.

Standard platform fees apply:

  • Loader (shipper): Platform fee: £5 or 2% of the job value, whichever is greater, charged to the shipper at collection on top of the agreed job price.
  • Haulier: 8% service fee; loader: £5 or 2% at collection

Same pricing whether you use web, CSV, or API.

CODE EXAMPLES

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
  }'

SUPPORT

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.

Terms • Privacy • Pricing • API Docs • Login