openapi: 3.0.1
info:
  description: Gain greater visibility by connecting your fleets, equipment, sites, and people.
  title: Samsara Dvirs API
  version: '2024-11-18'
servers:
- url: https://api.samsara.com/
- url: https://api.eu.samsara.com/
security:
- AccessTokenHeader: []
tags:
- name: Dvirs
paths:
  /fleet/dvirs:
    post:
      description: "Creates a new mechanic DVIR in the organization. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Write DVIRs** under the Maintenance category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
      operationId: createDvir
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDvirRequest'
        description: The DVIR to create.
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DvirResponse'
          description: Newly created DVIR.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/standardErrorResponse'
          description: Error response
      summary: Create a Mechanic DVIR
      tags:
      - Dvirs
      x-codegen-request-body-name: dvir
  /fleet/dvirs/history:
    get:
      description: "Returns a list of all DVIRs in an organization. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Read DVIRs** under the Maintenance category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
      operationId: getDvirHistory
      parameters:
      - description: The limit for how many objects will be in the response. Default and max for this value is 512 objects.
        in: query
        name: limit
        schema:
          format: int64
          maximum: 512
          minimum: 1
          type: integer
      - description: If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
        in: query
        name: after
        schema:
          type: string
      - description: 'A filter on the data based on this comma-separated list of parent tag IDs, for use by orgs with tag hierarchies. Specifying a parent tag will implicitly include all descendent tags of the parent tag. Example: `parentTagIds=345,678`'
        explode: false
        in: query
        name: parentTagIds
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'A filter on the data based on this comma-separated list of tag IDs. Example: `tagIds=1234,5678`'
        explode: false
        in: query
        name: tagIds
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'A start time in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00).'
        in: query
        name: startTime
        required: true
        schema:
          type: string
      - description: 'An end time in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00).'
        in: query
        name: endTime
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DvirsListResponse'
          description: List of all DVIRs in the organization
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/standardErrorResponse'
          description: Error response
      summary: Get All DVIRs
      tags:
      - Dvirs
  /fleet/dvirs/{id}:
    patch:
      description: "Resolves a given DVIR by marking its `isResolved` field to `true`. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Write DVIRs** under the Maintenance category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
      operationId: updateDvir
      parameters:
      - description: ID of the DVIR.
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDvirRequest'
        description: The dvir fields to update.
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DvirResponse'
          description: Updated dvir object with ID.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/standardErrorResponse'
          description: Error response
      summary: Resolve a DVIR
      tags:
      - Dvirs
      x-codegen-request-body-name: dvir
components:
  schemas:
    DvirVehicle:
      allOf:
      - description: The vehicle the DVIR was submitted for. Only included for tractor or tractor+trailer DVIRs.
        type: object
      - $ref: '#/components/schemas/vehicleTinyResponse'
    CreateDvirRequest:
      description: DVIR creation body
      properties:
        authorId:
          description: Samsara user ID of the mechanic creating the DVIR.
          example: '11'
          type: string
        licensePlate:
          description: The license plate of this vehicle.
          example: XHK1234
          maxLength: 12
          type: string
        location:
          description: Optional string if your jurisdiction requires a location of the DVIR.
          example: 350 Rhode Island St Ste. 400S, San Francisco, CA 94103
          type: string
        mechanicNotes:
          description: The mechanics notes on the DVIR.
          example: Replaced headlight on passenger side.
          type: string
        odometerMeters:
          description: The odometer reading in meters.
          example: 14010293
          type: integer
        resolvedDefectIds:
          description: Array of ids for defects being resolved with this DVIR.
          items:
            type: string
          type: array
        safetyStatus:
          description: Whether or not this vehicle or trailer is safe to drive.
          enum:
          - safe
          - unsafe
          example: safe
          type: string
        trailerId:
          description: Id of trailer being inspected. Either vehicleId or trailerId must be provided.
          example: '11'
          type: string
        type:
          description: Only type 'mechanic' is currently accepted.
          enum:
          - mechanic
          example: mechanic
          type: string
        vehicleId:
          description: Id of vehicle being inspected. Either vehicleId or trailerId must be provided.
          example: '10'
          type: string
      required:
      - authorId
      - safetyStatus
      - type
      type: object
    DvirsListResponse:
      description: A list of DVIRs and pagination information.
      properties:
        data:
          description: A list of DVIRs.
          items:
            $ref: '#/components/schemas/Dvir'
          type: array
        pagination:
          $ref: '#/components/schemas/paginationResponse'
      required:
      - data
      - pagination
      type: object
    DvirSignature:
      description: DVIR Signure.
      properties:
        signatoryUser:
          allOf:
          - description: The user who signed the DVIR.
            type: object
          - $ref: '#/components/schemas/userTinyResponse'
          type: object
        signedAtTime:
          description: 'The time when the DVIR was signed. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        type:
          default: driver
          description: 'Whether the DVIR was submitted by a `driver` or `mechanic`. Valid values: `driver`, `mechanic`.'
          enum:
          - driver
          - mechanic
          example: driver
          type: string
      type: object
    vehicleTinyResponse:
      description: A minified vehicle object.
      properties:
        ExternalIds:
          additionalProperties:
            type: string
          description: The [external IDs](https://developers.samsara.com/docs/external-ids) for the given object.
          example:
            maintenanceId: '250020'
            payrollId: ABFS18600
          type: object
        id:
          description: ID of the vehicle.
          example: '123456789'
          type: string
        name:
          description: Name of the vehicle.
          example: 'Midwest Truck #4'
          type: string
      type: object
    DvirVehicleDefects:
      description: Defects registered for the vehicle which was part of the DVIR.
      items:
        $ref: '#/components/schemas/dvirTrailerDefectsItems'
      type: array
    standardErrorResponse:
      description: Error response
      properties:
        message:
          description: The message of the error.
          example: An error has occurred.
          type: string
        requestId:
          description: The ID of the request.
          example: 8916e1c1
          type: string
      type: object
    DvirTrailerDefects:
      description: Defects registered for the trailer which was part of the DVIR.
      items:
        $ref: '#/components/schemas/dvirTrailerDefectsItems'
      type: array
    DvirSecondSignature:
      allOf:
      - description: An author signature object which has a signatory mini object with the signed time. Second Signature.
        type: object
      - $ref: '#/components/schemas/DvirSignature'
    DvirLicensePlate:
      description: The license plate of this vehicle.
      example: XHK1234
      maxLength: 12
      type: string
    dvirTrailerDefectsItems:
      properties:
        comment:
          description: Comment on the defect.
          example: Air Compressor not working
          type: string
        createdAtTime:
          description: 'Time when the defect was created. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        defectType:
          description: The type of DVIR defect.
          example: Air Compressor
          type: string
        id:
          description: ID of the defect.
          example: '18'
          type: string
        isResolved:
          description: Signifies if this defect is resolved.
          example: true
          type: boolean
        mechanicNotes:
          description: The mechanics notes on the defect.
          example: Extremely large oddly shaped hole in passenger side window.
          type: string
        mechanicNotesUpdatedAtTime:
          description: 'Time when mechanic notes were last updated. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        resolvedAtTime:
          description: 'Time when this defect was resolved. Will not be returned if the defect is unresolved. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        resolvedBy:
          $ref: '#/components/schemas/Defect_resolvedBy'
        trailer:
          allOf:
          - description: The trailer this defect was submitted for.
            type: object
          - description: A minified trailer object.
            properties:
              id:
                description: ID of the trailer.
                example: '123456789'
                type: string
              name:
                description: Name of the trailer.
                example: 'Midwest Trailer #5'
                type: string
            type: object
          type: object
        vehicle:
          allOf:
          - description: The vehicle this defect was submitted for.
            type: object
          - description: A minified vehicle object.
            properties:
              ExternalIds:
                additionalProperties:
                  type: string
                description: The [external IDs](https://developers.samsara.com/docs/external-ids) for the given object.
                example:
                  maintenanceId: '250020'
                  payrollId: ABFS18600
                type: object
              id:
                description: ID of the vehicle.
                example: '123456789'
                type: string
              name:
                description: Name of the vehicle.
                example: 'Midwest Truck #4'
                type: string
            type: object
          type: object
      required:
      - id
      - isResolved
      type: object
      x-go-gen-location: models
    Defect_resolvedBy:
      description: The person who resolved this defect.  Will not be returned if the defect is unresolved.
      properties:
        id:
          description: ID of the entity that resolved this defect. If the defect was resolved by a driver, this will be a Samsara Driver ID. If the defect was resolved by a mechanic, this will be the Samsara Dashboard User ID of the mechanic.
          example: '11'
          type: string
        name:
          description: Name of the person who resolved this defect.
          example: Christopher 'The Handyman' Zhen
          type: string
        type:
          description: Indicates whether this defect was resolved by a `driver` or a `mechanic`.
          enum:
          - driver
          - mechanic
          type: string
      type: object
    userTinyResponse:
      description: A minified user object.
      properties:
        id:
          description: ID of the user.
          example: '88668'
          type: string
        name:
          description: Name of the user.
          example: Susan Bob
          type: string
      type: object
    trailerTinyResponse:
      description: A minified trailer object.
      properties:
        id:
          description: ID of the trailer.
          example: '123456789'
          type: string
        name:
          description: Name of the trailer.
          example: 'Midwest Trailer #5'
          type: string
      type: object
    UpdateDvirRequest:
      description: Information about resolving a DVIR.
      properties:
        authorId:
          description: The user who is resolving the dvir.
          example: '11'
          type: string
        isResolved:
          description: Resolves the DVIR. Must be `true`.
          type: boolean
        mechanicNotes:
          description: The mechanics notes on the DVIR.
          example: Replaced headlight on passenger side.
          type: string
        signedAtTime:
          description: 'Time when user signed this DVIR. Defaults to now. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
      required:
      - authorId
      - isResolved
      type: object
    DvirAuthorSignature:
      allOf:
      - description: An author signature object which has a signatory mini object with the signed time. Author Signature.
        type: object
      - $ref: '#/components/schemas/DvirSignature'
    DvirTrailer:
      allOf:
      - description: The trailer the DVIR was submitted for. Only included for trailer only DVIRs.
        type: object
      - $ref: '#/components/schemas/trailerTinyResponse'
    DvirOdometerMeters:
      description: The odometer reading in meters.
      example: 14010293
      type: integer
    DvirLocation:
      description: Optional string if your jurisdiction requires a location of the DVIR.
      example: 350 Rhode Island St Ste. 400S, San Francisco, CA 94103
      type: string
    DvirThirdSignature:
      allOf:
      - description: An author signature object which has a signatory mini object with the signed time. Third Signature.
        type: object
      - $ref: '#/components/schemas/DvirSignature'
    paginationResponse:
      description: Pagination parameters.
      properties:
        endCursor:
          description: Cursor identifier representing the last element in the response. This value should be used in conjunction with a subsequent request's 'after' query parameter. This may be an empty string if there are no more pages left to view.
          example: MjkY
          format: string
          type: string
        hasNextPage:
          description: True if there are more pages of results immediately available after this endCursor.
          example: true
          type: boolean
      required:
      - endCursor
      - hasNextPage
      type: object
    DvirResponse:
      description: The DVIR response.
      properties:
        data:
          $ref: '#/components/schemas/Dvir'
      type: object
    Dvir:
      description: Information about a DVIR.
      properties:
        authorSignature:
          $ref: '#/components/schemas/DvirAuthorSignature'
        endTime:
          description: 'Time when driver signed and completed this DVIR. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        id:
          description: Unique Samsara ID for the DVIR.
          example: '7107471'
          type: string
        licensePlate:
          $ref: '#/components/schemas/DvirLicensePlate'
        location:
          $ref: '#/components/schemas/DvirLocation'
        mechanicNotes:
          $ref: '#/components/schemas/DvirMechanicNotes'
        odometerMeters:
          $ref: '#/components/schemas/DvirOdometerMeters'
        safetyStatus:
          default: unsafe
          description: 'The condition of vehicle on which DVIR was done. Valid values: `safe`, `unsafe`, `resolved`.'
          enum:
          - safe
          - unsafe
          - resolved
          example: unsafe
          type: string
        secondSignature:
          $ref: '#/components/schemas/DvirSecondSignature'
        startTime:
          description: 'Time when driver began filling out this DVIR. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        thirdSignature:
          $ref: '#/components/schemas/DvirThirdSignature'
        trailer:
          $ref: '#/components/schemas/DvirTrailer'
        trailerDefects:
          $ref: '#/components/schemas/DvirTrailerDefects'
        trailerName:
          description: The name of the trailer the DVIR was submitted for.  Only included for tractor+trailer DVIRs.
          example: 'Midwest Trailer #5'
          type: string
        type:
          default: unspecified
          description: 'Inspection type of the DVIR. Valid values: `preTrip`, `postTrip`, `mechanic`, `unspecified`.'
          enum:
          - preTrip
          - postTrip
          - mechanic
          - unspecified
          example: preTrip
          type: string
        vehicle:
          $ref: '#/components/schemas/DvirVehicle'
        vehicleDefects:
          $ref: '#/components/schemas/DvirVehicleDefects'
      required:
      - id
      type: object
    DvirMechanicNotes:
      description: The mechanics notes on the DVIR.
      example: Replaced headlight on passenger side.
      type: string
  securitySchemes:
    AccessTokenHeader:
      type: http
      scheme: bearer
x-original-swagger-version: '2.0'
x-readme:
  explorer-enabled: true
  proxy-enabled: true