Import API

Keep your Driv.one inventory in step with your DMS or stock system. Create and update vehicles, push complete inventories, manage photos — through a versioned REST API scoped to your workshop.

The API is for professional sellers, dealer groups, DMS vendors and integration partners. Records you create appear on driv.one under your workshop, exactly as if they had been added by hand — and they can still be edited by hand afterwards.

Quickstart

1. Create an API key

Sign in to driv.one → Dashboard → API keys, pick the workshop, give the key a name and copy it. The key is shown once; if you lose it, revoke it and create another.

2. Test authentication

Copycurl https://api.driv.one/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

3. Create a vehicle

Copycurl -X POST https://api.driv.one/v1/vehicles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "STOCK-4821",
  "external_updated_at": "2026-09-05T08:30:00Z",
  "make": "Volkswagen",
  "model": "Golf",
  "year": 2022,
  "vin": "WVWZZZAUZNW123456",
  "license_plate": "1-ABC-123",
  "mileage": 41200,
  "first_registration": "2022-03-15",
  "fuel_type": "petrol",
  "gearbox_type": "dct",
  "body_type": "hatchback",
  "power_hp": 150,
  "num_doors": 5,
  "num_seats": 5,
  "color": "gray",
  "interior_material": "fabric",
  "vehicle_condition": "used",
  "asking_price": 24950,
  "is_tax_vehicle": true,
  "short_description": "Golf 1.5 TSI Life, first owner, full history",
  "seller_description": "Serviced at the dealership, two keys, winter tyres included.",
  "features": [
    "appleCarplay",
    "androidAuto",
    "adaptiveCruiseControl",
    "ledHeadlights",
    "alloyWheels"
  ],
  "parking_assist": [
    "sens_front",
    "sens_rear",
    "cam_rear"
  ],
  "image_urls": [
    "https://cdn.example-dealer.be/stock/4821/front.jpg",
    "https://cdn.example-dealer.be/stock/4821/interior.jpg"
  ]
}'

The response is the stored vehicle including its uuid, public_url, currency and photos, plus a warnings array when something non-fatal happened (a photo that could not be fetched, a model that was created).

Base URL & versioning

Copyhttps://api.driv.one/v1

The major version is part of the path. Backwards-incompatible changes get a new major version; /v1 keeps its behaviour. Additive changes (new optional fields, new enumeration values) can appear within v1 — read GET /v1/options rather than hard-coding lists.

Paths are shown without a trailing slash; one is accepted.

Authentication

Bearer-token authentication with a workshop API key. Keys start with wsk_.

CopyAuthorization: Bearer wsk_…

X-API-Key: wsk_… is accepted as an alternative header. A key is either read-write or read-only; a read-only key gets 403 read_only_key on any write.

Request headers

Vehicle data model

Fields accepted on POST, PUT and PATCH. Responses return the same names, plus read-only uuid, status (published / unlisted), public_url, currency, images, for_sale_since and created_at.

Endpoints

Account

Reference (no key needed)

Vehicles

Photos

Full request and response schemas, with every enumeration inlined: Swagger UI · ReDoc · openapi.json.

List response

{
  "count": 37, "limit": 50, "offset": 0, "next_offset": null,
  "results": [ { "uuid": "…", "external_id": "STOCK-4821", "status": "published", … } ]
}

Upsert & stale updates

POST /v1/vehicles with an external_id that your workshop already uses updates that vehicle (HTTP 200) instead of creating a second one (HTTP 201). This makes a naive "push everything every night" integration idempotent.

When you also send external_updated_at, an update whose timestamp is older than the one stored is refused with 409 stale_update, so a delayed event can never overwrite a newer one. Inside a sync such a vehicle is reported as skipped_stale and the rest proceeds.

PATCH changes only the fields you send. PUT is a full replacement: optional fields you leave out are cleared. Both accept the same body as create.

Inventory sync

POST /v1/vehicles/sync upserts a whole inventory in one call (≤200 vehicles; call it repeatedly for more). Every vehicle needs an external_id.

Copy{
  "complete": true,
  "vehicles": [
    {
      "external_id": "STOCK-4821",
      "make": "Volkswagen",
      "model": "Golf",
      "year": 2022,
      "asking_price": 24950,
      "fuel_type": "petrol",
      "mileage": 41200
    },
    {
      "external_id": "STOCK-4835",
      "make": "Audi",
      "model": "A4",
      "year": 2021,
      "asking_price": 28900,
      "fuel_type": "diesel",
      "body_type": "estate"
    }
  ]
}

• All-or-nothing validation. The whole payload is validated first. One invalid vehicle rejects the call with 422 and a per-vehicle vehicles map; nothing is written.
• complete: true declares the payload to be your entire stock. API-managed vehicles (those carrying one of your external ids) that are missing from it are unlisted, never deleted — they stay in your dashboard and come back if you send them again.
• Empty protection. A complete sync with zero vehicles needs allow_empty: true, otherwise 409 empty_snapshot.
• dry_run: true returns would_create, would_update, would_unlist and writes nothing.
• Slots. Vehicles beyond your sale-slot allowance are saved unlisted with a sale_limit_reached warning instead of failing the sync.

Vehicles added by hand on the website are never touched by a sync.

Sale slots

Each workshop account has an allowance of vehicles that may be for sale at the same time (free tier, subscription tiers, or an amount assigned by Driv.one). GET /v1/me returns slots.used, slots.limit and slots.available.

A single create or update that would exceed the allowance fails with 403 sale_limit_reached. To free a slot, PATCH {"is_for_sale": false} a vehicle — it stays stored and can be re-listed later. More slots can be bought on driv.one.

Photos

Photos are ordered; order 0 is the main photo shown on listing cards. Large images are resized to a 2560 px long edge and re-encoded; anything above 15 MB after that is refused.

With the vehicle

Send image_urls in create/update. The photos are downloaded from your servers in the order given and replace the whole photo set. Omit the field to leave photos untouched. If none of the URLs can be fetched the existing photos are kept and a warning is returned.

One at a time

Copycurl -X POST https://api.driv.one/v1/vehicles/STOCK-4821/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://cdn.example-dealer.be/stock/4821/rear.jpg", "order": 1}'

Copycurl -X POST https://api.driv.one/v1/vehicles/STOCK-4821/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@rear.jpg" -F "order=1"

Reorder

Copycurl -X PUT https://api.driv.one/v1/vehicles/STOCK-4821/images/order \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"ids": [912, 910, 911]}'

Equipment (106 values)

Send equipment as slugs in features, and parking aids in parking_assist. Only the values below are accepted; unknown slugs return 422 naming them. Omitting the field on PATCH keeps the equipment; sending [] clears it. Labels in every language: GET /v1/options.

Parking assist

Enumerations

English and Dutch labels shown; French, Spanish and Portuguese are in GET /v1/options. Unknown values are rejected rather than guessed.

vehicle_type

year

1990 – 2027

fuel_type

gearbox_type

body_type

drivetrain

steering_position

emission_standard

color

interior_material

vehicle_condition

maintenance_history

airbags

air_conditioning

Errors

Errors are JSON with a stable error code and a human message; some carry extra keys.

{
  "error": "validation_error",
  "message": "One or more fields are invalid.",
  "fields": {
    "fuel_type": [
      "\"gasoline\" is not a valid choice."
    ],
    "features": [
      "Unknown features: sunroof. GET /v1/options lists the accepted values."
    ]
  }
}

Successful responses: 200 read or update, 201 created, 204 deleted.

Rate limits

Each key may make 3 000 requests per hour. Above that the API answers 429 with a Retry-After header. A full nightly sync of a few hundred cars uses a handful of calls; if you need more, contact Driv.one.

Photo downloads count against the same budget through the calls that trigger them, not per image.