Vehiso API
The Vehiso API lets a dealer, and the partner apps a dealer connects, read and write the dealer's own data from outside Vehiso: bespoke websites, DMS tooling, data warehouses, automation tools and AI assistants.
Authentication
Every request except the OAuth endpoints carries a bearer token:
Authorization: Bearer <key>. One host serves every dealer, so the key is
what names the dealer. Keys are created in the Vehiso DMS (Dealer
Management System) under Administration > Developers and are shown once.
| Prefix | Kind | Use |
|---|---|---|
vh_live_sk_ | secret key | servers, scripts, ETL, against the dealer's data |
vh_live_pk_ | publishable key | a visitor's browser on a bespoke website |
vh_test_sk_, vh_test_pk_ | sandbox keys | building and testing, against the dealer's own sandbox |
vh_oat_ | OAuth access token | partner apps, see OAuth below |
vh_live_ak_, vh_test_ak_ | agency key | an agency, across the dealerships it manages, see Agencies below |
A secret key must never be sent from a browser: a request with an
Origin header made with one is refused (secret_key_in_browser), so
the key is noticed and rolled. A publishable key is checked against its
list of allowed origins instead.
A key acts as its owner, a user of the dealership. What a key can do
is its scopes AND its owner's current permissions: a scope whose
permission the owner has lost stops working (403
scope_not_permitted_for_owner), and a key whose owner is deleted or
banned stops working altogether (401 key_owner_inactive). A key may also
be restricted to some branches, in which case it sees and writes only
their data.
Sandbox
Test keys work against the dealership's own sandbox: a separate
dealership holding demo stock, enquiries, appointments, a deal and a
workshop job, with none of the dealer's real data. It is set up the first
time a test key is used; until it is ready, requests get 503
sandbox_not_ready with a Retry-After header. Test keys need a paid
plan (403 plan_not_entitled).
The sandbox follows the dealership's plan, with some differences:
- it sends no email or text messages, and takes no payments;
- registration lookups and valuations are answered with made-up data instead of calling a data provider: a part exchange is filled in with invented vehicle details, and a valuation request always quotes an instant figure. The same registration and mileage always give the same answer, so tests can assert on them, but the figures are not market values;
- AI theme generation is refused with 403
not_available_in_sandbox; - it holds at most 50 vehicles in stock (403
sandbox_stock_cap_reached).
Records you create are deleted 30 days after they were created; the demo data stays. A sandbox no test key has used for 30 days is deleted, and a new one is set up the next time a test key is used. Resetting the sandbox from the DMS starts a fresh one with new demo data and keeps your webhook endpoints; the old one serves requests until the new one is ready.
Scopes
Each operation names the scope it needs in x-required-scope and in its
description. GET /me and GET /reference/{list} work with any key.
Publishable keys always carry exactly vehicles:read (public fields of
website-visible stock only), branches:read, public:enquiries and
public:valuation_requests, and can be given nothing more. Secret keys,
OAuth and webhooks need a paid plan (403 plan_not_entitled).
Responses
JSON throughout. A single object is returned flat under data; a list
is data (an array) plus meta. Ids are UUIDs; numeric ids never
appear.
Pagination and syncing
Lists use cursor pagination: ?limit= (1 to 100, default 25) and
?cursor=, the meta.next_cursor of the previous page. meta.has_more
says whether another page follows. Lists are ordered by updated_at,
then id, ascending, so a sync job can page to the end and remember the
last updated_at it saw for next time. Every list takes
?updated_since= (an ISO 8601 date-time), and lists of records that can
be deleted take ?include_deleted=true, which returns deleted rows as
tombstones ({ "id": "...", "deleted": true, "deleted_at": "..." }) so a
mirror can apply deletes. GET /events is the exception: events never
change, so it is ordered by when they happened.
Idempotency
Send an Idempotency-Key header (up to 255 characters) on any POST. A
retry with the same key and the same body within 24 hours gets the stored
response, marked Idempotent-Replayed: true, instead of doing the work
twice. The same key with a different body is refused with 409
idempotency_key_reused, and a retry that arrives while the first
attempt is still running gets 409 idempotency_key_in_use. Server errors
are not stored, so they can always be retried.
Errors
Errors share one body:
{ "success": false, "message": "...", "code": "not_found", "request_id": "...", "errors": { "field": ["..."] } }.
code is a stable, machine-readable string to branch on; message is
for people and may change. errors is present on 422 only, keyed by
field. Status codes: 401 for a missing or bad key, 403 for a scope, plan
or key restriction, 404, 409 for a conflict with the record's state, 422
for validation, 429 for rate limiting and 5xx for our faults. The OAuth
endpoints are the exception: they answer RFC 6749
{ "error", "error_description" } bodies, which is what OAuth client
libraries expect.
Every response carries X-Request-Id. Quote it to support.
Rate limits
Limits are per key, per minute: 120 for secret keys and OAuth tokens, 300
for publishable keys and 600 for agency keys. The two public writes are further limited to 10 per
minute per visitor address. Responses carry X-RateLimit-Limit and
X-RateLimit-Remaining; a 429 carries Retry-After in seconds.
Money, times and codes
Money is an object in minor units with its currency:
{ "amount": 1499500, "currency": "GBP" } is 14,995.00 pounds. Money in a
request body (a vehicle's price, say) is an integer in minor units of
the dealer's currency. Times are ISO 8601 in UTC
(2026-09-27T14:02:11Z); dates are YYYY-MM-DD. Statuses, types and
sources are codes; GET /reference/{list} lists them with the dealer's
names for them.
OAuth
A partner serving many dealers uses the authorisation code flow with PKCE
(S256) instead of asking dealers for keys: send the dealer to
GET /oauth/authorize, exchange the code at POST /oauth/token for an
access token (vh_oat_, one hour) and a refresh token (vh_ort_, 90
days, rotated on every use), and revoke at POST /oauth/revoke.
Agencies
An agency that manages dealerships in Vehiso can use the API for all of
them with one agency key, created by an agency administrator in the
agency portal under Developers. An agency key acts as that administrator
and stops working if they leave the agency or stop being an
administrator (401 key_owner_inactive).
It carries two kinds of scope. Agency scopes (agency:dealerships:read,
agency:dealerships:write, agency:keys:write, agency:staff:read,
agency:domains:read, agency:usage:read, agency:webhooks:manage)
cover the /agency endpoints. Dealer scopes, the same ones a dealer key
carries, are the most it can do inside a dealership.
To act for one dealership, call any endpoint below with the
dealership's id in the Vehiso-Dealer header:
Vehiso-Dealer: 0f6c1b9e-.... The request runs as the agency's own user
in that dealership, so its changes show in the DMS as the agency's.
Without the header an agency key reaches only /agency (400
dealer_header_required). A dealership the agency does not manage is
404 dealership_not_found; one still being set up is 409
dealership_not_ready; one whose dealer has turned the agency's access
off in the DMS is 403 agency_access_revoked. A test agency key acts in
each dealership's sandbox.
For a tool that serves one dealer only, create an ordinary secret key
for that dealership with POST /agency/dealerships/{id}/keys, so a
leaked key exposes one dealership rather than all of them.
One rate limit covers everything an agency key does, across all its dealerships: 600 requests a minute.
Versioning
/v1 is in the path. Changes within v1 are additive only: new endpoints,
new optional request fields and new response fields. Treat unknown
response fields as normal.
Authentication
- HTTP: Bearer Auth
- OAuth 2.0: oauth2
An API key or an OAuth access token, as Authorization: Bearer <token>.
Secret keys start vh_live_sk_ (sandbox vh_test_sk_), publishable
keys vh_live_pk_ (sandbox vh_test_pk_), agency keys vh_live_ak_
(sandbox vh_test_ak_) and OAuth access tokens vh_oat_. An agency
key names the dealership it acts for in the Vehiso-Dealer header.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | vh_live_sk_... / vh_oat_... |
For partner apps. Authorisation code flow with PKCE (S256); the access token is then sent as a bearer token.
Security Scheme Type: | oauth2 |
|---|---|
OAuth Flow (authorizationCode): | Token URL: https://api.vehiso.com/v1/oauth/token Authorization URL: https://api.vehiso.com/v1/oauth/authorize Refresh URL: https://api.vehiso.com/v1/oauth/token Scopes:
|