Sign in
Driver

Upsert a driver

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.

post/public/v1/drivers

Request body

idstring

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_namestring

The driver's first name. Required on create for every compliance type. On update, omit to leave unchanged.

last_namestring

The driver's last name. Required on create for every compliance type. On update, omit to leave unchanged.

emailstring

The driver's email. Required on create for BIOTRACK companies; ignored for METRC companies (stored null). On update, omit to leave unchanged.

phone_numberstring

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_licensestring

The driver's license number. Required on create for both METRC and BIOTRACK companies. On update, omit to leave unchanged.

us_statestring

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_datestring

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_datestring

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_numberstring

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

The updated driver

Changes

No recorded changes to this endpoint across all 1 revision of this API.