Skip to main content
Version: 1.0.0

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.

PrefixKindUse
vh_live_sk_secret keyservers, scripts, ETL, against the dealer's data
vh_live_pk_publishable keya visitor's browser on a bespoke website
vh_test_sk_, vh_test_pk_sandbox keysbuilding and testing, against the dealer's own sandbox
vh_oat_OAuth access tokenpartner apps, see OAuth below
vh_live_ak_, vh_test_ak_agency keyan 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​

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

Contact

Vehiso developer support: support@vehiso.com

URL: https://developers.vehiso.com