Distru Driver API

openapi: 3.2.0
info:
  license:
    name: Proprietary
    url: https://www.distru.com/legal/terms-of-service
  title: Distru Driver API
  version: '1.0'
servers:
- url: https://app.distru.com
security:
- Bearer: []
tags:
- name: Driver
paths:
  /public/v1/drivers:
    get:
      description: 'Lists the drivers belonging to the authenticated company, oldest first (ordered by creation

        time ascending). Soft-deleted drivers are excluded, and results never cross company

        boundaries.


        Drivers only exist for companies whose compliance type is METRC or BIOTRACK; a company with

        any other compliance type simply returns an empty list here.


        Results are paginated. The response `next_page` holds the URL of the following page, or null on

        the last page.


        Required permission: `settings_permissions_drivers`.'
      operationId: DistruPublic.V1.DriverController.index
      parameters:
      - description: Restrict the result to specific drivers by ID (the same ID returned as each driver's `id`). Repeat the bracketed key once per ID. Unknown IDs simply match nothing; an empty list is treated as no filter. At most 200 IDs may be given.
        in: query
        name: ids
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: 'Filter to drivers by their creation datetime, given as a comma-separated `start,end` pair of ISO8601 datetimes (inclusive). Either bound may be omitted for an open-ended range: `2022-07-10T00:00:00Z,` matches on or after that instant, `,2022-07-10T00:00:00Z` matches on or before it.'
        in: query
        name: inserted_datetime
        required: false
        example: ?inserted_datetime=2022-07-10T00:00:00Z,2022-07-31T00:00:00Z
        schema:
          type: string
      - description: Filter to drivers by their last-updated datetime, given as a comma-separated `start,end` pair of ISO8601 datetimes (inclusive). Either bound may be omitted for an open-ended range.
        in: query
        name: updated_datetime
        required: false
        example: ?updated_datetime=2022-07-10T00:00:00Z,2022-07-31T00:00:00Z
        schema:
          type: string
      - description: Page selector. Page size is fixed by the server; paginate by following the `next_page` URL in each response rather than building page selectors yourself — it is null on the last page. `next_page` uses `page[after]=<cursor>`, an opaque token marking where the next page resumes; pass it back exactly as given, and only to the endpoint that issued it. This is seek-based, so every page stays fast no matter how deep you page.
        in: query
        name: page
        required: false
        example: ?page[after]=cursor
        schema:
          type: string
      responses:
        '200':
          description: A list of drivers
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Drivers'
        '400':
          description: Invalid parameters
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API token
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The API token lacks the required permission
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests — the account's list rate limit (3000 calls, refilling at 5 per minute, one per page) was exceeded. Retry after the period in the Retry-After header. Calls with an `updated_datetime` lower bound within the last 30 days are free and never refused; see [Incremental Sync](#incremental-sync).
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Get drivers
      tags:
      - Driver
    post:
      description: '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`.'
      operationId: DistruPublic.V1.DriverController.upsert
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: 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:
                  type: string
                  description: The driver's first name. Required on create for every compliance type. On update, omit to leave unchanged.
                last_name:
                  type: string
                  description: The driver's last name. Required on create for every compliance type. On update, omit to leave unchanged.
                email:
                  type: string
                  description: The driver's email. Required on create for BIOTRACK companies; ignored for METRC companies (stored null). On update, omit to leave unchanged.
                phone_number:
                  type: string
                  description: 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:
                  type: string
                  description: The driver's license number. Required on create for both METRC and BIOTRACK companies. On update, omit to leave unchanged.
                us_state:
                  type: string
                  description: 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:
                  type: string
                  description: 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:
                  type: string
                  description: 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:
                  type: string
                  description: The driver's occupational license number. Required on create for METRC companies; ignored for BIOTRACK companies (stored null). On update, omit to leave unchanged.
      responses:
        '200':
          description: The updated driver
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DriverResponse'
        '201':
          description: The created driver
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DriverResponse'
        '400':
          description: Invalid parameters
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API token
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The API token lacks the required permission
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Upsert a driver
      tags:
      - Driver
  /public/v1/drivers/{id}:
    delete:
      description: 'Deletes a driver. This is a soft delete: the driver stops appearing in the list and fetch

        endpoints and can no longer be updated, but the record is retained. Returns 404 if no matching

        driver exists in your company or it was already deleted. Responds 204 with no body on success.


        Deleting does not remove the driver from transfers, transfer templates, or manifests that

        already reference it. For a BIOTRACK company, a successful delete queues an asynchronous removal

        in BioTrack — a 204 means the driver was removed in Distru, not that BioTrack has processed the

        removal. The delete is rejected up front (and nothing is removed) when your company or user

        BioTrack credentials are missing or lack permission for this operation; once queued, a later

        rejection by BioTrack does not restore the Distru record. METRC companies have no such sync.


        Required permission: `settings_permissions_drivers`.'
      operationId: DistruPublic.V1.DriverController.delete
      parameters:
      - description: ID of the driver to delete, as returned by the list, fetch, and upsert endpoints.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '400':
          description: Invalid parameters
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API token
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The API token lacks the required permission
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Delete a driver
      tags:
      - Driver
    get:
      description: 'Fetches a single driver by its ID, scoped to the authenticated company. Returns 404 if no

        driver with that ID exists in your company or if it has been soft-deleted.


        Which contact fields are populated depends on the company''s compliance type: METRC drivers

        carry `phone_number` and `occupational_license_number` (and leave `birth_date`, `email`,

        `us_state`, `hire_date` null), while BIOTRACK drivers carry `birth_date`, `email`, `us_state`

        and `hire_date` (and leave `phone_number` and `occupational_license_number` null).


        Required permission: `settings_permissions_drivers`.'
      operationId: DistruPublic.V1.DriverController.show
      parameters:
      - description: ID of the driver to fetch, as returned by the list and upsert endpoints.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A single driver
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DriverResponse'
        '400':
          description: Invalid parameters
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API token
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The API token lacks the required permission
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Get a driver
      tags:
      - Driver
components:
  schemas:
    ErrorResponse:
      description: The envelope returned by every failed request (400, 401, 403, 404, 429). `errors` always holds at least one entry.
      properties:
        errors:
          description: One or more errors describing why the request failed.
          items:
            $ref: '#/components/schemas/Error'
          type: array
      required:
      - errors
      title: ErrorResponse
      type: object
    Drivers:
      description: A collection of drivers
      properties:
        data:
          description: Drivers
          items:
            $ref: '#/components/schemas/Driver'
          type: array
        next_page:
          description: URL for the next page of results; null when there is no next page
          type: string
      title: Drivers
      type: object
    Driver:
      description: A driver
      properties:
        birth_date:
          description: The driver's date of birth as an ISO-8601 calendar date, `YYYY-MM-DD` (e.g. `1990-05-15`). Populated for BIOTRACK drivers; null for METRC drivers.
          type: string
        driver_license:
          description: The driver's license number. Populated for both METRC and BIOTRACK drivers, but may be null on older records.
          type: string
        email:
          description: The driver's email. Populated for BIOTRACK drivers; null for METRC drivers.
          type: string
        first_name:
          description: The driver's first name. Always present.
          type: string
        hire_date:
          description: The date the driver was hired as an ISO-8601 calendar date, `YYYY-MM-DD` (e.g. `2023-01-09`). Populated for BIOTRACK drivers; null for METRC drivers.
          type: string
        id:
          description: ID of this driver. Use it to fetch, update, or delete the driver.
          type: string
        inserted_datetime:
          description: When the driver was created, as a UTC ISO-8601 timestamp. Always present.
          type: string
        last_name:
          description: The driver's last name. Always present.
          type: string
        occupational_license_number:
          description: The driver's occupational license number. Populated for METRC drivers; null for BIOTRACK drivers.
          type: string
        phone_number:
          description: The driver's phone number. Populated for METRC drivers; null for BIOTRACK drivers.
          type: string
        updated_datetime:
          description: When the driver was last updated, as a UTC ISO-8601 timestamp. Always present.
          type: string
        us_state:
          description: The US state that issued the driver's license (e.g. `CA`). Populated for BIOTRACK drivers; null for METRC drivers.
          type: string
      required:
      - updated_datetime
      - inserted_datetime
      - last_name
      - first_name
      - id
      title: Driver
      type: object
    DriverResponse:
      description: A single driver
      properties:
        data:
          $ref: '#/components/schemas/Driver'
      title: Driver Response
      type: object
    Error:
      description: A single error describing one problem with the request.
      properties:
        message:
          description: Human-readable, customer-facing description of what went wrong.
          type: string
        pointer:
          description: 'Path to the offending field in the request: field names and, for items in a list, their integer position — e.g. ["items", 0, "quantity"]. ["base"] means the error applies to the request as a whole rather than one field.'
          items: {}
          type: array
      required:
      - message
      - pointer
      title: Error
      type: object
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: 'API token generated in Distru (Settings → Distru API). Send it on every request as `Authorization: Bearer YOUR_API_TOKEN`.'