The vehReports API lets you connect vehReports to your own systems — your booking platform, fleet management software, dealer management system or website — so vehicles, customers, inspections, rental agreements and licence checks can flow between them automatically. This article covers turning the API on, looking after your key, authenticating your requests, what the API can do, and exactly which calls use a credit so there are no billing surprises.
If you want vehReports to push events back out to your systems as they happen (a report being completed, an agreement signed, a licence flagged for points), that's handled separately — see setting up and verifying webhooks.
Who the API is for
The API is for businesses that already run vehReports day to day and want their other systems to talk to it without anyone re-keying data. Typical uses:
- A booking or rental platform that creates a rental agreement in vehReports the moment a hire is confirmed.
- Fleet software that adds new vehicles by registration and keeps your records in step.
- A website form that creates a customer record, or runs a driver licence check before a hire.
- A back-office tool that watches your credit balance and tops up before you run low.
You don't need the API to use vehReports — everything is available in the app. The API simply removes manual steps when you've got another system in the mix.
Before you start
A few things worth having in place:
- A role that can manage account-level settings. Turning the API on and handling the key are account-level settings, so you'll need an Owner, who has full access to the account. If you only need to read reports or run inspections, you don't need the API at all. See roles explained.
- Someone to do the wiring. The API is used by software, not by clicking around the app. You (or your developer) will be writing or configuring something that makes the calls.
- An understanding of credits. Only two actions ever cost anything, and the API follows the same rule as the app. We cover this in full below, and in understanding credits.
Turning on API access
Go to the API area and open API access. Enable the API for your company. Once it's on, you'll be given two things:
- An API key — a long secret string that identifies your account on every request.
- A base address — the web address all your requests are sent to. This is your account's API root. Every endpoint hangs off this base, for example
/vehiclesor/inspections.
You can turn API access off again at any time; while it's off, no requests are accepted.
Authenticating your requests
Requests are authenticated with your API key, sent as a bearer token. In plain terms: your software includes the key with every call (in the request's authorisation header) so vehReports knows the request genuinely comes from your account. A request without a valid key — or with a key that's been switched off or regenerated — is refused.
The in-app API documentation (under the API area) shows the exact header format and includes ready-to-copy examples, so you can paste a working request straight into your tooling and see a real response.
Treat the key like a password. Anyone who has it can act on your account through the API — read your data, create records, and trigger the two actions that spend credits. Never put it in front-end website code, a public repository, or anywhere a customer could see it. Keep it on your server side only.
Looking after your API key
Your key lives under API → API access. There are two controls worth knowing.
Regenerating the key
You can refresh (regenerate) the key whenever you like — for example if you suspect it has been exposed, or when a developer who had it leaves. Regenerating is immediate and final:
- The old key stops working straight away.
- Any system still using the old key will start getting refused until you update it.
So the safe sequence is: regenerate, then update every place that uses the key with the new one. If you've only got one integration, that's a quick swap; if you've got several, line them up before you regenerate so nothing is left stranded.
Restricting by IP address (IP whitelist)
You can add an IP whitelist so the API only accepts requests from addresses you trust — typically your server's fixed IP. Requests from anywhere else are refused, even if they carry a valid key. This is a strong extra layer: if a key ever leaks, it's useless to anyone whose machine isn't on your list.
A few practical notes:
- Use the public IP your server sends requests from, not an internal address.
- If your hosting changes IP, remember to update the whitelist or your own calls will start failing.
- Leave the whitelist empty if you can't pin down a fixed IP — but then lean harder on keeping the key secret and rotating it if you've any doubt.
If your key suddenly stops working
The two usual causes:
- The key was regenerated. A new key was issued (perhaps by a colleague) and the old one is now dead. Grab the current key from API → API access and update your software.
- The request came from an address that isn't whitelisted. If you've set an IP whitelist, anything off the list is refused regardless of the key. Check the request is leaving from a whitelisted IP, or add the new IP to the list.
Check both before assuming anything more serious is wrong.
What the API can do
The API works with the same data you manage in the app:
- Vehicles — add by registration (with the DVLA and MOT details pulled in automatically), read and update records. See adding and managing a vehicle.
- Customers — create and read customer records, including the licence details kept on file. See managing customers.
- Inspections — create inspection reports and read existing ones, including fetching the generated PDF of a signed-off report. See creating and completing an inspection report.
- Rental agreements — create agreements and read existing ones, again including the generated document. See creating and completing a rental agreement.
- Driver licence checks — run a check against a licence number and DVLA share code, and read the saved results. See running a driver licence check.
- Credits — read your current credit balance, so your own system can keep an eye on credits and prompt a top-up in good time.
In short: you can read records, create them, and fetch the documents they produce. The full, up-to-date list of endpoints — with the exact paths, methods, parameters and example responses — lives under API → API documentation in the app. That page is the authoritative list; this article describes the shape of things, but the in-app documentation is what you build against.
What uses a credit over the API
This is the question everyone asks, and the answer is reassuringly simple: the API follows exactly the same rule as the app.
Only two calls ever cost a credit (£1 each):
- Creating an inspection report.
- Creating a rental agreement.
These are the equivalent of producing those documents in the app, where signing off a report and signing an agreement each cost one credit.
Everything else is free and unlimited, including:
- Reading any data — vehicles, customers, reports, agreements, balances.
- Running driver licence checks.
- Vehicle lookups (the DVLA and MOT details pulled in when you add a vehicle).
- Creating and updating vehicles and customers.
- Fetching generated PDFs of documents you've already produced.
The in-app API documentation marks each operation as free or uses a credit, so you can see the cost of every call before you write a line of code. As a rule of thumb: if a call creates an inspection or a rental agreement, it spends a credit; if it does anything else, it's free.
Watching your balance
Because your own system can read the credit balance endpoint at any time, it's good practice to check the balance before a run of bulk document creation, and to alert your team (or top up) when it's getting low. New companies start with around 10 free welcome credits to get going. For pricing, packs and subscriptions, see credits, pricing, top-ups and subscriptions.
What if I run out of credits?
The same as in the app: you can still do everything that's free — read data, run licence checks, add vehicles and customers — but the two credit-using calls (creating an inspection or a rental agreement) will be refused until you top up. Nothing breaks; the credit-using actions simply wait. Build your integration to handle a "no credits" response gracefully rather than treating it as a hard failure, and consider topping up automatically when the balance endpoint reports a low figure.
Versioning and stability
The base address includes a version, so the shape of requests and responses stays stable as we develop the product. Build against the version in your base address and you won't be caught out by future changes. The in-app API documentation always reflects the version you're entitled to use.
Tips and common pitfalls
- Keep the key server-side. Never embed it in a website's front-end or a mobile app where a user could extract it. Calls should be made from your own backend.
- Update everywhere before you regenerate. Regenerating kills the old key instantly. Line up your systems first so none are left failing.
- Mind the IP whitelist when things move. A new server, a changed hosting IP or a different office connection can all start getting refused if you've whitelisted addresses. Update the list when your infrastructure changes.
- Read the in-app documentation for exact details. Field names, required parameters and the free/paid marker for each call are all there and always current — this article is the overview, that page is the reference.
- Don't expect licence checks to cost anything. They're free over the API just as they are in the app. Note that Northern Ireland licence checks are not yet available.
- Use webhooks for "tell me when something happens". Polling the API repeatedly to spot a signed agreement or a flagged licence is wasteful. Have vehReports push those events to you instead — see setting up and verifying webhooks.
Where to go next
- To receive events as they happen rather than polling for them: setting up and verifying webhooks.
- To understand the credit system the API follows: understanding credits and credits, pricing, top-ups and subscriptions.
- To control who can manage account-level settings like the API key: roles explained and managing your team.