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.
BearerAuthorizationBearer <token>API token generated in Distru (Settings → Distru API). Send it on every request as Authorization: Bearer YOUR_API_TOKEN.
application/json- body
id?stringID 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?stringThe driver's first name. Required on create for every compliance type. On update, omit to leave unchanged.
last_name?stringThe driver's last name. Required on create for every compliance type. On update, omit to leave unchanged.
email?stringThe driver's email. Required on create for BIOTRACK companies; ignored for METRC companies (stored null). On update, omit to leave unchanged.
phone_number?stringThe 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?stringThe driver's license number. Required on create for both METRC and BIOTRACK companies. On update, omit to leave unchanged.
us_state?stringThe 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?stringThe 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?stringThe 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?stringThe driver's occupational license number. Required on create for METRC companies; ignored for BIOTRACK companies (stored null). On update, omit to leave unchanged.
The updated driver
*/*- response
A single driver
data?A driver
curl -X POST 'https://app.distru.com/public/v1/drivers' \ -H 'Content-Type: application/json' \ -d '{ "driver_license": "D1234567", "first_name": "Sam", "last_name": "Rivera", "occupational_license_number": "OCC-889", "phone_number": "555-0100"}'{ "data": { "birth_date": "string", "driver_license": "string", "email": "string", "first_name": "string", "hire_date": "string", "id": "string", "inserted_datetime": "string", "last_name": "string", "occupational_license_number": "string", "phone_number": "string", "updated_datetime": "string", "us_state": "string" }}