Skip to main content

Agencies

An agency that manages several dealerships in Vehiso can use the API for all of them with one agency key, instead of asking each dealer for a key of their own. With it you can:

  • act for any of your dealerships, on every endpoint a dealer key can call;
  • list your dealerships, and create new ones, billed exactly as the agency portal bills them;
  • create an ordinary secret key for one dealership;
  • receive the webhooks of every dealership at one endpoint.

This guide is for agencies. If you build for a single dealer, use an ordinary secret key. If you build a product that many unrelated dealers connect to, use OAuth.

Creating an agency key​

An agency administrator creates agency keys in the agency portal, under Developers. The agency must be approved; until it is, agency keys are refused with 403 agency_not_approved.

PrefixTypeData it reaches
vh_live_ak_Agency key/v1/agency, and every live dealership the agency manages
vh_test_ak_Agency key (test)/v1/agency (creating a dealership only validates), and each dealership's sandbox

Like any key, an agency key is shown once, when it is created or rolled. It can have an IP allowlist and an expiry date.

An agency key acts as the administrator who created it. If they leave the agency, stop being an administrator or are banned, the key stops working with 401 key_owner_inactive. Roll the key, or create a new one, from another administrator's account.

Two kinds of scope​

An agency key carries two sets of scopes, chosen when it is created.

Agency scopes cover the /v1/agency endpoints:

ScopeAllows
agency:dealerships:readList and read your dealerships
agency:dealerships:writeCreate dealerships, turn a dealership's website on or off, and list the prices dealerships can be created on
agency:keys:writeCreate, list and revoke secret keys for a dealership
agency:staff:readList the agency's own staff
agency:domains:readList a dealership's domains
agency:usage:readRead what each dealership costs the agency
agency:webhooks:manageManage the agency's webhook endpoints

Dealer scopes are the same scopes a dealer key carries (vehicles:read, enquiries:write and so on). On an agency key they are the most the key may do inside any one dealership, whether it acts there itself or through a key it creates.

GET /v1/agency returns the agency and both of the key's scope lists, which is a quick way to check a key:

curl https://api.vehiso.com/v1/agency \
-H "Authorization: Bearer $VEHISO_AGENCY_KEY"
{
"data": {
"id": "3a8e1c52-9b7d-4f0e-a6c1-2d5b8f9e0a14",
"name": "Northgate Digital",
"currency": "gbp",
"key": {
"id": "9d2f6b1a-4c8e-4e3d-b7a5-0f1c2e3d4a5b",
"name": "Stock sync",
"environment": "live",
"agency_scopes": ["agency:dealerships:read", "agency:webhooks:manage"],
"dealer_scopes": ["vehicles:read", "vehicles:write", "enquiries:read"]
}
}
}

Only an agency key can call /v1/agency; any other key is refused with 403 agency_key_required.

Acting for a dealership​

To call any endpoint outside /v1/agency (vehicles, enquiries, webhooks and so on), name the dealership in the Vehiso-Dealer header. Its value is the dealership's id from GET /v1/agency/dealerships.

curl https://api.vehiso.com/v1/vehicles?limit=100 \
-H "Authorization: Bearer $VEHISO_AGENCY_KEY" \
-H "Vehiso-Dealer: 0f6c1b9e-5a2d-4c7e-8b3f-6d1e9a0c2b47"
curl https://api.vehiso.com/v1/customers \
-H "Authorization: Bearer $VEHISO_AGENCY_KEY" \
-H "Vehiso-Dealer: 0f6c1b9e-5a2d-4c7e-8b3f-6d1e9a0c2b47" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: crm-import-customer-1042" \
-d '{"first_name": "Sam", "last_name": "Patel", "email": "sam@example.com"}'

Everything else about the request is exactly as the API reference describes it for a dealer key. To work with a different dealership, send its id instead: one key, one header per request.

  • The request runs as your agency's own user in that dealership, an administrator created for the agency. Its changes show in the DMS as made by your agency, not by one of the dealer's staff.
  • Your dealer scopes are the ceiling. A request needing a scope that is not among the key's dealer scopes is refused with 403 insufficient_scope.
  • The dealership's plan must include the API, as it must for the dealer's own secret keys. Otherwise the request is refused with 403 plan_not_entitled.
  • Idempotency keys are kept per dealership, so the same Idempotency-Key sent for two dealerships does two separate pieces of work.

Without the header, an agency key reaches only /v1/agency. The errors that come from the header are listed under Errors.

Listing and creating dealerships​

GET /v1/agency/dealerships lists every dealership the agency manages, newest first. It is not paginated. meta.can_add_dealership says whether the agency's billing allows another one.

curl https://api.vehiso.com/v1/agency/dealerships \
-H "Authorization: Bearer $VEHISO_AGENCY_KEY"

Each dealership has an id (for the Vehiso-Dealer header), a status (provisioning, active or failed) and api_access, which is revoked when the dealer has turned your access off.

Creating a dealership​

A dealership is created on one of the prices from GET /v1/agency/prices (unit_amount is in minor units, in the agency's currency). Billing is the same as in the agency portal: the dealership becomes a tier on the agency's consolidated subscription, in the agency's currency, and never on the Free plan. The agency's first dealership needs a payment method on the agency. Anything the portal would refuse, the API refuses too.

curl https://api.vehiso.com/v1/agency/dealerships \
-H "Authorization: Bearer $VEHISO_AGENCY_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: new-dealership-hartley-motors" \
-d '{"name": "Hartley Motors", "price_id": "c4e2a9b1-7d3f-4a6e-9c8b-1f0e2d3c4b5a"}'

Send an Idempotency-Key, so that a retry after a network error does not create (and bill for) a second dealership.

The API answers 202 Accepted straight away, with the new dealership's id and status: provisioning:

{
"data": {
"id": "0f6c1b9e-5a2d-4c7e-8b3f-6d1e9a0c2b47",
"name": "Hartley Motors",
"status": "provisioning",
"api_access": "enabled"
}
}

Setting the dealership up takes a few minutes. While it does, GET /v1/agency/dealerships/{id} reports provisioning, and a request with its id in the Vehiso-Dealer header is refused with 409 dealership_not_ready. When it is ready:

  1. its status becomes active;
  2. a dealership.provisioned event, carrying the dealership's id and name, is sent to the agency's webhook endpoints;
  3. it answers to the Vehiso-Dealer header.

Wait for the webhook rather than polling, or poll GET /v1/agency/dealerships/{id} gently if you have no endpoint.

DMS-only dealerships​

A dealership can have the full DMS without a website. Send "website": false when you create it, or switch an existing one either way with PATCH /v1/agency/dealerships/{id}:

curl -X PATCH https://api.vehiso.com/v1/agency/dealerships/$DEALERSHIP_ID \
-H "Authorization: Bearer $VEHISO_AGENCY_KEY" \
-H "Content-Type: application/json" \
-d '{"website": false}'

A DMS-only dealership's DMS hides the website features, and its website shows visitors only who to contact. Payment, signing and other links the DMS sends to customers keep working. Nothing is deleted and the price does not change, so "website": true brings the website back as it was. The dealership's website field says which it is. A test key checks the request and changes nothing.

Your white label​

If Vehiso has set up white label for your agency, your dealers see your name, colour and logos in their DMS, and can sign in on your own DMS domain. GET /v1/agency/white-label shows how it is set up. Any agency key can read it.

curl https://api.vehiso.com/v1/agency/white-label \
-H "Authorization: Bearer $VEHISO_AGENCY_KEY"
{
"data": {
"status": "active",
"started_at": "2026-11-18T10:00:00Z",
"display_name": "Northgate DMS",
"primary_colour": "#1B3A8F",
"logo_light_url": "https://...",
"logo_dark_url": "https://...",
"mark_url": "https://...",
"dms_domain": {
"suffix": "dms.northgate.example",
"status": "awaiting_dns",
"checked_at": "2026-11-19T08:00:00Z",
"live_at": null,
"dns_record": { "type": "CNAME", "name": "*.dms.northgate.example", "value": "..." }
}
}
}

status is active once white label is running. dms_domain is null until you have your own DMS domain, and its dns_record is the one record to add in your own DNS. Its status moves from awaiting_dns to live once the record is found. The endpoint is read-only: to set up white label or change your branding, contact Vehiso.

Keys for one dealership​

POST /v1/agency/dealerships/{id}/keys creates an ordinary secret key (vh_live_sk_, or vh_test_sk_ with "environment": "test") for one dealership. It needs the agency:keys:write scope.

curl https://api.vehiso.com/v1/agency/dealerships/0f6c1b9e-5a2d-4c7e-8b3f-6d1e9a0c2b47/keys \
-H "Authorization: Bearer $VEHISO_AGENCY_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Hartley website feed", "scopes": ["vehicles:read", "branches:read"], "allowed_ips": ["203.0.113.10"]}'

The response holds the key's secret. It is shown in this response only.

Use one when a tool serves one dealer only: a website feed, a single dealer's DMS integration, a script running on the dealer's own server. An agency key reaches every dealership you manage, so if it leaks, all of them are exposed. A per-dealership key exposes one, and you can revoke it without touching anything else.

  • Its scopes must be among the agency key's dealer scopes.
  • It acts as your agency's user in the dealership, like the agency key does, and needs no Vehiso-Dealer header.
  • It appears in the dealer's own API key list in the DMS, owned by your agency.
  • It stops working if the dealer turns your agency's access off, or the dealership leaves your agency.

GET /v1/agency/dealerships/{id}/keys lists the active keys your agency made for a dealership, and DELETE /v1/agency/dealerships/{id}/keys/{key} revokes one at once.

One webhook endpoint for all dealerships​

An agency webhook endpoint receives the events of every live dealership the agency manages, including dealerships created after the endpoint. Manage them with the agency:webhooks:manage scope:

EndpointDoes
GET /v1/agency/webhook-endpointsLists endpoints
POST /v1/agency/webhook-endpointsCreates an endpoint
GET, PATCH, DELETE /v1/agency/webhook-endpoints/{id}Reads, changes or deletes one
POST /v1/agency/webhook-endpoints/{id}/roll-secretIssues a new signing secret for every dealership's deliveries
curl https://api.vehiso.com/v1/agency/webhook-endpoints \
-H "Authorization: Bearer $VEHISO_AGENCY_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/hooks/vehiso", "events": ["vehicle.updated", "enquiry.created", "dealership.provisioned"]}'

The request body, the signing secret (shown once), signing, retries and automatic disabling all work as described in Webhooks and events. An agency can have up to 20 endpoints. Two things differ:

  • The body carries dealership_id, the dealership the event happened in. It is part of the signed body, so verify the signature before trusting it.
  • A Vehiso-Dealer header names the same dealership, so you can route a delivery before parsing it.
{
"id": "evt_2c9d1f4e-7a3b-4e8c-9d6f-1b2a3c4d5e6f",
"type": "vehicle.updated",
"dealership_id": "0f6c1b9e-5a2d-4c7e-8b3f-6d1e9a0c2b47",
"created_at": "2026-09-27T14:02:11Z",
"data": {
"object": {
"id": "5f0c6a8e-2d41-4f7b-9a53-1f0e8c2b7d19"
}
}
}

Sandboxes do not send to agency endpoints. To test webhooks, create an ordinary endpoint inside a dealership's sandbox with a test key: POST /v1/webhook-endpoints with a vh_test_ak_ key and the Vehiso-Dealer header.

A dealership whose dealer has turned your agency's access off stops sending to your endpoints.

Test agency keys​

A test agency key (vh_test_ak_) is for building and testing:

  • With the Vehiso-Dealer header it acts in that dealership's sandbox, never in its live data. Send the dealership's real id; the sandbox is found from it. The sandbox works as it does for the dealer's own test keys: it is set up on first use (503 sandbox_not_ready until then), and the request runs as the sandbox's own user.
  • Creating a dealership with a test key only validates. It checks the request, including billing, and creates and bills nothing. The answer is 200 with status: not_created, id: null and livemode: false.

The dealer's switch​

A dealer can turn your agency's API access off for their dealership in the DMS, under Administration > Developers. While it is off:

  • your agency key is refused for that dealership with 403 agency_access_revoked;
  • the keys your agency created for that dealership are refused with 403 agency_access_revoked;
  • your agency webhook endpoints stop receiving that dealership's events;
  • the dealership shows api_access: revoked in GET /v1/agency/dealerships.

It changes nothing else: the dealership stays with your agency, your staff can still sign in to its DMS, and billing carries on as before. Only the dealer can turn it back on; agency staff cannot reach that page. Ask the dealer if you need access again.

Errors​

On top of the usual authentication errors, an agency key can see:

StatuscodeMeaning
400dealer_header_requiredAn agency key called an endpoint outside /v1/agency without a Vehiso-Dealer header.
401key_owner_inactiveThe administrator who created the key left the agency, stopped being an administrator or was banned.
403agency_key_requiredA key that is not an agency key called /v1/agency.
403agency_not_approvedThe agency is not approved for the API.
403agency_access_revokedThe dealership has turned your agency's API access off in the DMS.
403plan_not_entitledThe dealership's plan does not include the API.
404dealership_not_foundYour agency manages no dealership with that id. A sandbox's own id answers this too: send the live dealership's id.
409dealership_not_readyThe dealership is still being set up. Wait for dealership.provisioned.

Rate limit​

An agency key has one allowance of 600 requests a minute, shared across /v1/agency and every dealership it acts for. Ten requests for ten dealerships use ten requests of it. Each dealership's own keys, including the keys your agency created for it, have their own separate limits and do not draw on it.

If one busy dealership's sync could starve the others, give that sync a per-dealership key. See Rate limits.