Partner API · v1.0.0

Build on the GoVantage fleet

Check what is available, price a hire, request a booking, pull your invoices into your accounts system and feed tracker readings back to us. One key, one contract, no surprises.

Ask for an API key OpenAPI 3.1

Endpoints: 16
Scopes: 7
Standard limit: 120/min

first call

curl "https://app.govantage.uk/api/v1/partner/availability?startDate=2026-10-12&weeks=12&classCode=MWB" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

{
  "items": [
    {
      "classCode": "MWB",
      "className": "Medium van",
      "depotCode": "STK",
      "depotName": "Stoke-on-Trent",
      "fleetSize": 14,
      "available": 3,
      "nextAvailableDate": null
    }
  ]
}

Base address

https://app.govantage.uk/api/v1/partner

Before you start

Six things that hold everywhere

Authentication

Send your key on every request as a bearer token. Keys start with gvk_test_ or gvk_live_ and are shown once when created, so keep them in a secret manager and never in a browser or a mobile app.

Two kinds of key

An account key belongs to one customer and only ever sees that customer's vans, bookings and invoices. A platform key is for partners: it sees the fleet and the bookings it created, and never a customer's invoices.

Rate limits

120 requests a minute per key unless agreed otherwise. Every response carries X-RateLimit-Remaining; a 429 tells you how many seconds to wait in Retry-After. Availability, quotes and writes count for more than one request.

Safe retries

Calls that create something need an Idempotency-Key header. Send the same key again after a timeout and you get the first answer back, not a second booking. Keys are remembered for 24 hours.

Pagination

Lists return items and nextCursor. Pass nextCursor as cursor to get the next page; null means you have everything. Pages hold 25 items by default and 100 at most.

Formats

JSON in and out. Money is an integer number of pence. Timestamps are ISO-8601 in UTC and dates are YYYY-MM-DD. Vans are identified by registration, everything else by its reference or code.

Scopes

vehicles:read Read vehicles and classes
availability:read Check availability and quotes
bookings:read Read bookings
bookings:write Create booking requests
customers:read Read customers (own account)account key
invoices:read Read invoices (own account)account key
telematics:write Push GPS / odometer readings

Errors

Every error has the same shape. Branch on code, log requestId, show title.

400 IDEMPOTENCY_KEY_REQUIREDThis call creates something, so it needs an Idempotency-Key header.
401 INVALID_API_KEYThe key is missing, mistyped, expired or revoked.
403 SCOPE_REQUIREDThe key works but was not given the scope this call needs.
403 ACCOUNT_KEY_REQUIREDOnly a key limited to one customer account can call this.
404 NOT_FOUNDNothing with that reference exists, or it belongs to another account.
409 IDEMPOTENCY_KEY_REUSEDThat Idempotency-Key was already used with a different request body.
422 VALIDATION_FAILEDThe request did not match the contract. fields says which values to fix.
422 NOT_AVAILABLENo van of that class can be promised for the dates asked for.
429 RATE_LIMITEDToo many requests this minute. Wait for Retry-After seconds.

Key

GET /partner/me Check a key

Confirms the key works and shows what it may do. Use it as a health check when you deploy.

Request

curl "https://app.govantage.uk/api/v1/partner/me" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "key": {
    "name": "Route planner",
    "prefix": "a1B2c3D4",
    "scopes": [
      "vehicles:read",
      "bookings:read"
    ],
    "expiresAt": null,
    "rateLimitPerMinute": 120
  },
  "account": {
    "reference": "CUS-001002",
    "name": "Potteries Parcels Ltd"
  },
  "environment": "test",
  "apiVersion": "1.0.0"
}

Catalogue

GET /partner/vehicle-classes vehicles:read List van classes

The kinds of van that can be hired, with load space and the lowest weekly price.

Request

curl "https://app.govantage.uk/api/v1/partner/vehicle-classes" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "items": [
    {
      "code": "MWB",
      "name": "Medium van",
      "category": "VAN",
      "tagline": "The courier favourite",
      "description": null,
      "seats": 3,
      "payloadKg": 1000,
      "loadLengthMm": 2555,
      "loadHeightMm": 1406,
      "loadVolumeM3": 6,
      "fuelType": "DIESEL",
      "transmission": "MANUAL",
      "exampleModels": [
        "Ford Transit Custom",
        "Vauxhall Vivaro"
      ],
      "features": [
        "Bluetooth",
        "Ply-lined"
      ],
      "imageUrl": null,
      "depositMinor": 50000,
      "fromWeeklyMinor": 15000
    }
  ]
}

GET /partner/plans vehicles:read List hire plans

Plans on public sale with the price of each van class.

Request

curl "https://app.govantage.uk/api/v1/partner/plans" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "items": [
    {
      "code": "FLEX",
      "name": "Flex",
      "tagline": "Week to week",
      "interval": "WEEK",
      "minTermIntervals": 4,
      "noticeDays": 7,
      "mileageAllowance": 1000,
      "excessMileageMinor": 12,
      "insuranceIncluded": false,
      "prices": [
        {
          "classCode": "MWB",
          "priceMinor": 15000
        }
      ]
    }
  ]
}

GET /partner/depots vehicles:read List depots

Where vans are collected and returned.

Request

curl "https://app.govantage.uk/api/v1/partner/depots" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "items": [
    {
      "code": "STK",
      "name": "Stoke-on-Trent",
      "addressLine1": "Unit 4, Festival Park",
      "addressLine2": null,
      "city": "Stoke-on-Trent",
      "postcode": "ST1 5NX",
      "latitude": 53.0335,
      "longitude": -2.1995,
      "phone": "01782 000000",
      "openingHours": {
        "mon": [
          "08:00",
          "18:00"
        ],
        "sat": [
          "09:00",
          "13:00"
        ]
      }
    }
  ]
}

GET /partner/vehicles vehicles:read List vans

On an account key: the vans on hire to that account. On a platform key: the fleet, without any customer detail.

Parameters

limitinteger · default 25 — Items per page
cursorstring — `nextCursor` from the previous page
classCodestring — Van class code, from List van classes
statusstring — Platform keys only, e.g. AVAILABLE or ON_RENT

Request

curl "https://app.govantage.uk/api/v1/partner/vehicles?limit=25" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "items": [
    {
      "registration": "VD70 ABC",
      "make": "Ford",
      "model": "Transit Custom",
      "variant": "280 L1 H1",
      "colour": "White",
      "year": 2020,
      "fuelType": "DIESEL",
      "transmission": "MANUAL",
      "classCode": "MWB",
      "className": "Medium van",
      "depotCode": "STK",
      "status": "ON_RENT",
      "mileage": 48210,
      "mileageRecordedAt": "2026-09-28T07:41:00.000Z",
      "motExpiresAt": "2027-03-14",
      "taxDueAt": "2027-02-01",
      "serviceDueAt": "2026-12-01",
      "rental": {
        "reference": "RN-2026-00010",
        "startedAt": "2026-09-21T08:30:00.000Z",
        "driverName": "Priya Nair"
      },
      "lastPosition": {
        "latitude": 53.0027,
        "longitude": -2.1794,
        "recordedAt": "2026-09-29T12:58:00.000Z",
        "speedMph": 0
      }
    }
  ],
  "nextCursor": null
}

GET /partner/vehicles/{registration} vehicles:read Get one van

Spaces and case in the registration are ignored.

Parameters

registrationpathRegistration mark e.g. VD70ABC

Request

curl "https://app.govantage.uk/api/v1/partner/vehicles/VD70ABC" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "registration": "VD70 ABC",
  "make": "Ford",
  "model": "Transit Custom",
  "variant": "280 L1 H1",
  "colour": "White",
  "year": 2020,
  "fuelType": "DIESEL",
  "transmission": "MANUAL",
  "classCode": "MWB",
  "className": "Medium van",
  "depotCode": "STK",
  "status": "ON_RENT",
  "mileage": 48210,
  "mileageRecordedAt": "2026-09-28T07:41:00.000Z",
  "motExpiresAt": "2027-03-14",
  "taxDueAt": "2027-02-01",
  "serviceDueAt": "2026-12-01",
  "rental": {
    "reference": "RN-2026-00010",
    "startedAt": "2026-09-21T08:30:00.000Z",
    "driverName": "Priya Nair"
  },
  "lastPosition": {
    "latitude": 53.0027,
    "longitude": -2.1794,
    "recordedAt": "2026-09-29T12:58:00.000Z",
    "speedMph": 0
  }
}

Availability & price

GET /partner/availability availability:read Check availability

How many vans of each class can be promised from each depot for the whole window. Counts as 3 requests against the rate limit.

Parameters

startDaterequireddate — First day of hire
weeksinteger — Length of hire; omit for open-ended
classCodestring — Van class code, from List van classes
depotCodestring — Depot code, from List depots

Request

curl "https://app.govantage.uk/api/v1/partner/availability?startDate=2026-10-12&weeks=12&classCode=MWB" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "items": [
    {
      "classCode": "MWB",
      "className": "Medium van",
      "depotCode": "STK",
      "depotName": "Stoke-on-Trent",
      "fleetSize": 14,
      "available": 3,
      "nextAvailableDate": null
    }
  ]
}

GET /partner/quote availability:read Price a hire

The same pricing engine the website and the staff console use, including promotions. Account keys get that account's negotiated rates. Counts as 3 requests against the rate limit.

Parameters

planCoderequiredstring — Plan code, from List hire plans
classCoderequiredstring — Van class code, from List van classes
depotCoderequiredstring — Depot code, from List depots
startDaterequireddate — First day of hire
weeksinteger — Length of hire; omit for open-ended
vehiclesinteger · default 1 — How many vans
promoCodestring — Promotion code, if the customer has one

Request

curl "https://app.govantage.uk/api/v1/partner/quote?planCode=FLEX&classCode=MWB&depotCode=STK&startDate=2026-10-12&weeks=12" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "planCode": "FLEX",
  "classCode": "MWB",
  "depotCode": "STK",
  "startDate": "2026-10-12",
  "vehicles": 1,
  "recurringMinor": 15000,
  "recurringExVatMinor": 12500,
  "vatMinor": 2500,
  "depositMinor": 50000,
  "upfrontMinor": 65000,
  "termIntervals": 12,
  "termTotalMinor": 180000,
  "lines": [
    {
      "label": "Medium van — Flex",
      "amountMinor": 15000
    }
  ],
  "rejectedPromo": null,
  "available": 3
}

Bookings

GET /partner/bookings bookings:read List bookings

Newest first. Account keys see their own bookings; platform keys see bookings they created.

Parameters

limitinteger · default 25 — Items per page
cursorstring — `nextCursor` from the previous page
statusstring — For example AWAITING_REQUIREMENTS, CONFIRMED or CANCELLED
fromdate — Start date on or after
todate — Start date on or before

Request

curl "https://app.govantage.uk/api/v1/partner/bookings?status=REQUESTED" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "items": [
    {
      "reference": "BK-2026-00042",
      "status": "REQUESTED",
      "planCode": "FLEX",
      "classCode": "MWB",
      "className": "Medium van",
      "depotCode": "STK",
      "startDate": "2026-10-12",
      "termIntervals": 12,
      "recurringMinor": 15000,
      "depositMinor": 50000,
      "customerReference": "CUS-001002",
      "customerName": "Potteries Parcels Ltd",
      "vehicleRegistration": null,
      "rentalReference": null,
      "holdExpiresAt": "2026-10-02T13:00:00.000Z",
      "notes": "Second van for the Christmas peak",
      "createdAt": "2026-09-29T13:00:00.000Z"
    }
  ],
  "nextCursor": null
}

GET /partner/bookings/{reference} bookings:read Get one booking

Follow a request through confirmation to the rental it becomes.

Parameters

referencepathBooking reference e.g. BK-2026-00042

Request

curl "https://app.govantage.uk/api/v1/partner/bookings/BK-2026-00042" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "reference": "BK-2026-00042",
  "status": "REQUESTED",
  "planCode": "FLEX",
  "classCode": "MWB",
  "className": "Medium van",
  "depotCode": "STK",
  "startDate": "2026-10-12",
  "termIntervals": 12,
  "recurringMinor": 15000,
  "depositMinor": 50000,
  "customerReference": "CUS-001002",
  "customerName": "Potteries Parcels Ltd",
  "vehicleRegistration": null,
  "rentalReference": null,
  "holdExpiresAt": "2026-10-02T13:00:00.000Z",
  "notes": "Second van for the Christmas peak",
  "createdAt": "2026-09-29T13:00:00.000Z"
}

POST /partner/bookings bookings:write idempotent Request a booking

Creates a booking request priced by the pricing engine and holds a van of that class. Staff confirm it after the usual driver and payment checks — the API cannot put a van on the road by itself. Counts as 5 requests against the rate limit.

Body

planCoderequiredstring — Plan code, from List hire plans
classCoderequiredstring — Van class code, from List van classes
depotCoderequiredstring — Depot code, from List depots
startDaterequireddate — First day of hire
weeksinteger — Length of hire; omit for open-ended
customerReferencestring — Required on a platform key; ignored on an account key
usageProfileDELIVERY_COURIER | TRADES | REMOVALS | BUSINESS_FLEET | PERSONAL | OTHER — What the van will be used for
promoCodestring — Promotion code, if the customer has one
notesstring — Shown to staff with the request

Request

curl -X POST "https://app.govantage.uk/api/v1/partner/bookings" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"planCode":"FLEX","classCode":"MWB","depotCode":"STK","startDate":"2026-10-12","weeks":12,"notes":"Second van for the Christmas peak"}'

Response · 201

{
  "reference": "BK-2026-00042",
  "status": "REQUESTED",
  "planCode": "FLEX",
  "classCode": "MWB",
  "className": "Medium van",
  "depotCode": "STK",
  "startDate": "2026-10-12",
  "termIntervals": 12,
  "recurringMinor": 15000,
  "depositMinor": 50000,
  "customerReference": "CUS-001002",
  "customerName": "Potteries Parcels Ltd",
  "vehicleRegistration": null,
  "rentalReference": null,
  "holdExpiresAt": "2026-10-02T13:00:00.000Z",
  "notes": "Second van for the Christmas peak",
  "createdAt": "2026-09-29T13:00:00.000Z"
}

Account

GET /partner/account customers:read account key Get the account

Balance, payment method and what is on hire for the account the key belongs to.

Request

curl "https://app.govantage.uk/api/v1/partner/account" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "reference": "CUS-001002",
  "name": "Potteries Parcels Ltd",
  "type": "BUSINESS",
  "status": "ACTIVE",
  "email": "accounts@potteriesparcelsltd.co.uk",
  "phone": "01782 111222",
  "paymentMethod": "DIRECT_DEBIT",
  "paymentReference": "GV1002",
  "balanceMinor": 30000,
  "overdueMinor": 0,
  "activeRentals": 2,
  "vansOnHire": 2
}

GET /partner/invoices invoices:read account key List invoices

Issued invoices for the account, newest first, with their lines. Drafts are never shown.

Parameters

limitinteger · default 25 — Items per page
cursorstring — `nextCursor` from the previous page
statusstring — ISSUED, PART_PAID, OVERDUE, PAID, VOID, WRITTEN_OFF, ARRANGED (on a payment plan) or CARRIED (moved onto later invoices)
fromdate — Issued on or after
todate — Issued on or before

Request

curl "https://app.govantage.uk/api/v1/partner/invoices?status=ISSUED&from=2026-09-01" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "items": [
    {
      "number": "INV-2026-00142",
      "status": "ISSUED",
      "issueDate": "2026-09-27",
      "dueDate": "2026-10-03",
      "periodStart": "2026-09-27",
      "periodEnd": "2026-10-03",
      "rentalReference": "RN-2026-00010",
      "subtotalMinor": 12500,
      "vatMinor": 2500,
      "totalMinor": 15000,
      "paidMinor": 0,
      "balanceMinor": 15000,
      "lines": [
        {
          "description": "Weekly hire — Medium van, week commencing 28 Sept 2026",
          "quantity": 1,
          "unitMinor": 12500,
          "totalMinor": 15000,
          "vehicleRegistration": "VD70 ABC"
        }
      ]
    }
  ],
  "nextCursor": null
}

GET /partner/invoices/{number} invoices:read account key Get one invoice

One invoice by its number.

Parameters

numberpathInvoice number e.g. INV-2026-00142

Request

curl "https://app.govantage.uk/api/v1/partner/invoices/INV-2026-00142" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY"

Response · 200

{
  "number": "INV-2026-00142",
  "status": "ISSUED",
  "issueDate": "2026-09-27",
  "dueDate": "2026-10-03",
  "periodStart": "2026-09-27",
  "periodEnd": "2026-10-03",
  "rentalReference": "RN-2026-00010",
  "subtotalMinor": 12500,
  "vatMinor": 2500,
  "totalMinor": 15000,
  "paidMinor": 0,
  "balanceMinor": 15000,
  "lines": [
    {
      "description": "Weekly hire — Medium van, week commencing 28 Sept 2026",
      "quantity": 1,
      "unitMinor": 12500,
      "totalMinor": 15000,
      "vehicleRegistration": "VD70 ABC"
    }
  ]
}

Telematics

POST /partner/telematics/readings telematics:write Push tracker readings

Send positions, odometer, ignition, fuel and battery readings in batches of up to 500. Name the device (IMEI or serial, as registered under Fleet, Trackers & cameras) to keep its live position and health current. A reading already stored for the same van and instant is skipped, so a batch can be replayed safely. Odometer readings only ever move a van's mileage forward; a battery low at rest raises an alert for the fleet team. Counts as 5 requests against the rate limit.

Body

readingsrequiredobject[]

Request

curl -X POST "https://app.govantage.uk/api/v1/partner/telematics/readings" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"readings":[{"registration":"VD70 ABC","recordedAt":"2026-09-29T12:58:00Z","latitude":53.0027,"longitude":-2.1794,"speedMph":0,"odometerMiles":48225,"ignition":false,"deviceId":"356307042441013","batteryVolts":12.6}]}'

Response · 200

{
  "accepted": 1,
  "duplicates": 0,
  "mileageUpdated": 1,
  "rejected": []
}

POST /partner/telematics/events telematics:write Push fault codes, driving and dashcam events

Send engine fault codes, harsh driving, impacts, tamper alerts and dashcam clips in batches of up to 200. Give each event the vendor id as externalId and it is stored once however often it is sent. Warnings and critical events go straight to the fleet team. Counts as 5 requests against the rate limit.

Body

eventsrequiredobject[]

Request

curl -X POST "https://app.govantage.uk/api/v1/partner/telematics/events" \
  -H "Authorization: Bearer $GOVANTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"registration":"VD70 ABC","deviceId":"356307042441013","kind":"FAULT_CODE","code":"P0420","occurredAt":"2026-09-29T12:58:00Z","detail":"Catalyst system efficiency below threshold (bank 1)","externalId":"evt_8812"}]}'

Response · 200

{
  "accepted": 1,
  "duplicates": 0,
  "rejected": []
}

Webhooks

Rather than polling, give us an address and we will tell you when something happens. Each delivery is signed, retried with growing gaps for about a day, and carries the event id so you can ignore one you have already handled.

Events

Bookings & rentals

booking.created
booking.confirmed
booking.cancelled
rental.activated
rental.return_scheduled
rental.closed

Money

invoice.issued
payment.recorded
credit_note.issued
deposit.released
deposit.deducted

Fleet & operations

vehicle.grounded
vehicle.released
inspection.finalised
damage.reported
recovery.requested
maintenance.completed

Customers

customer.created
driver.status_changed
document.reviewed

Check the signature (Node.js)

import { createHmac, timingSafeEqual } from 'node:crypto';

// x-gv-signature: t=1759150000,v1=5f2b…
export function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // too old
  const expected = createHmac('sha256', secret).update(t + '.' + rawBody).digest();
  const given = Buffer.from(v1, 'hex');
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Ready to try it?

Tell us what you are building and which scopes you need. Test keys work against demonstration data, so nothing you do there touches a real van or a real invoice.

Ask for an API key