What this does
The Mileage API lets sole-traders and field staff log mileage claims programmatically. The killer use case is "add 23 miles to today's site visit" via a chat or messenger client.
When to use it
Use this endpoint when a journey needs to be logged from a non-web context — a phone bot, an in-cab device, an automation that watches calendar events, etc.
Authentication and scopes
Requests must include Authorization: Bearer rly_your_key_here. Each endpoint requires one of:
mileage:read— list and retrieve claimsmileage:write— create and delete claims
Endpoints
List mileage claims
GET /api/v1/mileage
Returns a paginated list ordered newest-first. Supports ?page=1&limit=50.
Create a mileage claim
POST /api/v1/mileage
{
"date": "2026-04-25",
"description": "Site visit — 14 Acme Way",
"fromLocation": "Office",
"toLocation": "Acme Ltd",
"miles": 23.4,
"rate": 0.45
}
date, description, and a positive miles are required. rate defaults to HMRC's £0.45/mile if omitted. fromLocation and toLocation are optional free-text. Returns the created claim with amount = miles × rate (201).
If expense approval is enabled for the active entity, the claim is created in pending_approval status with the GL posting deferred until approval.
Get a single mileage claim
GET /api/v1/mileage/:id
Returns a single claim, scoped to the calling key's user.
Delete a mileage claim
DELETE /api/v1/mileage/:id
Removes the claim. Returns 404 not_found if the claim doesn't exist or doesn't belong to the calling key's user. The deletion is rejected with 403 PERIOD_LOCKED if the claim's date falls in a locked accounting period (enforced by the underlying service).
Test mode
Test-mode keys validate the request and return a stubbed claim with "test": true in the response envelope; no DB writes are performed.