---
title: "Upsert a driver"
method: POST
path: "/public/v1/drivers"
tags: ["Driver"]
---

# Upsert a driver

`POST /public/v1/drivers`

Creates or updates a single driver in one call. Omit `id` to create a new driver; pass the
`id` of an existing driver to update it. Responds 201 on create and 200 on update, with
the full saved driver as the body.

Only companies whose compliance type is METRC or BIOTRACK can manage drivers. A request from a
company with any other compliance type is rejected with a 400 and a single human-readable error
message — no driver is created or changed.

Which fields are required depends on the company's compliance type, and the requirement is
enforced only when CREATING (no `id`). On update, every field is optional: this is a sparse
update, so only the fields you send are changed and any field you omit keeps its stored value.
Sending an empty string for an optional contact or license field (`email`, `us_state`,
`driver_license`, `phone_number`, `occupational_license_number`) stores null rather than an
empty string; leading and trailing whitespace on those fields is trimmed.
• METRC create requires: `first_name`, `last_name`, `phone_number`, `driver_license`,
  `occupational_license_number`. The BIOTRACK-only fields (`email`, `us_state`, `birth_date`,
  `hire_date`) are ignored for METRC companies.
• BIOTRACK create requires: `first_name`, `last_name`, `birth_date`, `email`, `driver_license`,
  `us_state`, `hire_date`. The METRC-only fields (`phone_number`, `occupational_license_number`)
  are ignored for BIOTRACK companies.

Compliance side effects: for a BIOTRACK company, a successful save queues an asynchronous push
to BioTrack — a 200/201 confirms the driver was stored in Distru, not that BioTrack accepted it,
so poll `GET /public/v1/drivers/{id}` to observe the stored record. The save is rejected up
front with a 400 (and nothing is stored) when your company or user BioTrack credentials are
missing or lack permission for this operation; once the push is queued, a later rejection by
BioTrack does not undo the Distru save. For a METRC company, the driver is stored for use when
building Metrc transfer templates and transfers and is not pushed to Metrc on save.

Required permission: `settings_permissions_drivers`.

## Request body

- object
  - `id` string — ID of the driver to update, as returned by the list, fetch, and upsert endpoints. Omit to create a new driver. When present but not matching a driver in your company, the request fails.
  - `first_name` string — The driver's first name. Required on create for every compliance type. On update, omit to leave unchanged.
  - `last_name` string — The driver's last name. Required on create for every compliance type. On update, omit to leave unchanged.
  - `email` string — The driver's email. Required on create for BIOTRACK companies; ignored for METRC companies (stored null). On update, omit to leave unchanged.
  - `phone_number` string — The driver's phone number. Required on create for METRC companies; ignored for BIOTRACK companies (stored null). May contain only digits, parentheses, `+`, `-`, and spaces (e.g. `+1 (415) 555-0100`). On update, omit to leave unchanged.
  - `driver_license` string — The driver's license number. Required on create for both METRC and BIOTRACK companies. On update, omit to leave unchanged.
  - `us_state` string — The US state that issued the driver's license, as a free-form string (e.g. `CA`). Required on create for BIOTRACK companies; ignored for METRC companies (stored null). On update, omit to leave unchanged.
  - `birth_date` string — The driver's date of birth as an ISO-8601 calendar date, `YYYY-MM-DD` (e.g. `1990-05-15`), no time component. Required on create for BIOTRACK companies; ignored for METRC companies (stored null). On update, omit to leave unchanged.
  - `hire_date` string — The date the driver was hired as an ISO-8601 calendar date, `YYYY-MM-DD` (e.g. `2023-01-09`), no time component. Required on create for BIOTRACK companies; ignored for METRC companies (stored null). On update, omit to leave unchanged.
  - `occupational_license_number` string — The driver's occupational license number. Required on create for METRC companies; ignored for BIOTRACK companies (stored null). On update, omit to leave unchanged.

## Response `200`

The updated driver

## Other responses

- `201` — The created driver
- `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)