---
title: "Create or update a vehicle"
method: POST
path: "/public/v1/vehicles"
tags: ["Vehicle"]
---

# Create or update a vehicle

`POST /public/v1/vehicles`

Create or update a vehicle. This is a single upsert: omit `id` to create a new vehicle, or pass the `id` of an existing vehicle owned by your company to update it in place. Passing an `id` that does not exist, is soft-deleted, or belongs to another company returns 404 — this endpoint never creates a vehicle at a caller-chosen id.

On create, `make`, `model` and `license_plate_number` are required. Updates are sparse: only the fields you send are changed, and any field you omit keeps its current value. There is no way to clear a field back to null through this endpoint — sending a field always overwrites it with the value you provide, and omitting it leaves the stored value intact. `make`, `model` and `license_plate_number` can never be blank.

If your company has the BioTrack compliance integration enabled, this endpoint also pushes the vehicle to the state traceability system (BioTrack) as part of the same request. That sync is synchronous, so no polling is needed: a 200 means BioTrack accepted the vehicle too, and if BioTrack rejects it the whole call fails and nothing is saved (create and BioTrack sync commit or roll back together). For BioTrack-enabled companies the following fields become required in addition to the three above: `year`, `color`, `vin`, `license_plate_state` and `description`. Companies without BioTrack are not synced anywhere and only need `make`, `model` and `license_plate_number`.

On validation failure (missing required field, BioTrack rejection) the response is a 400 whose body is `{ "errors": [...] }`, each entry carrying a human-readable message pointing at the offending body field.

Vehicles are a settings-level record referenced by transfers and manifests; upserting one does not touch inventory, orders, or purchases.

Required permission: `settings_permissions_vehicles`.

## Request body

- object
  - `id` string — ID of the vehicle to update. Omit to create a new vehicle; when present it must identify a vehicle owned by your company.
  - `make` string — Manufacturer of the vehicle (e.g. "Ford"). Required on create and can never be cleared; on update, omit to leave unchanged.
  - `model` string — Model of the vehicle (e.g. "Transit"). Required on create and can never be cleared; on update, omit to leave unchanged.
  - `year` string — Model year of the vehicle, sent as a free-form string (e.g. "2021") — it is stored verbatim and never validated or coerced to a number. Optional for companies without BioTrack, but required when your company has BioTrack enabled. Omit to leave unchanged on update.
  - `color` string — Color of the vehicle (e.g. "White"). Optional, but required when your company has BioTrack enabled. Omit to leave unchanged on update.
  - `license_plate_number` string — License plate number. Required on create and can never be cleared; on update, omit to leave unchanged.
  - `license_plate_state` string — State the license plate is registered in, as a two-letter US state code (e.g. "CA"); must be one of the recognized US state/territory codes. Optional for companies without BioTrack, but required when your company has BioTrack enabled. Omit to leave unchanged on update.
  - `vin` string — Vehicle identification number (VIN). Optional, but required when your company has BioTrack enabled. Omit to leave unchanged on update.
  - `description` string — Free-text name or description for the vehicle. Optional, but required when your company has BioTrack enabled. Omit to leave unchanged on update.

## Response `200`

The created or updated vehicle

## Other responses

- `400` — Invalid parameters
- `401` — Missing or invalid API token
- `403` — The API token lacks the required permission
- `404` — Not Found

---

[API](https://skmtc.dev/distru/apis/distru-api.md) · [All operations](https://skmtc.dev/distru/apis/distru-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/distru/distru-api/revisions/eb775b7b6ee0/schema)