openapi: 3.0.1
info:
  description: Gain greater visibility by connecting your fleets, equipment, sites, and people.
  title: Samsara Status API
  version: '2024-11-18'
servers:
- url: https://api.samsara.com/
- url: https://api.eu.samsara.com/
security:
- AccessTokenHeader: []
tags:
- name: Status
paths:
  /v1/fleet/drivers/{driver_id}/hos/duty_status:
    post:
      description: "<n class=\"warning\">\n<nh>\n<i class=\"fa fa-exclamation-circle\"></i>\nThis endpoint is still on our legacy API.\n</nh>\n</n>\n\nSet an individual drivers current duty status to 'On Duty' or 'Off Duty'.\n\n To ensure compliance with the ELD Mandate, only  authenticated drivers can make direct duty status changes on their own logbook. Any system external to the Samsara Driver App using this endpoint to trigger duty status changes must ensure that such changes are only triggered directly by the driver in question and that the driver has been properly authenticated. This endpoint should not be used to algorithmically trigger duty status changes nor should it be used by personnel besides the driver to trigger duty status changes on the drivers behalf. Carriers and their drivers are ultimately responsible for maintaining accurate logs and should confirm that their use of the endpoint is compliant with the ELD Mandate. \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 ELD Hours of Service (US)** under the Compliance 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: setCurrentDutyStatus
      parameters:
      - description: ID of the driver for whom the duty status is being set.
        in: path
        name: driver_id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/inline_object_1'
        content:
          application/json:
            schema:
              properties:
                duty_status:
                  description: Duty status to set the driver to. The only supported values are 'ON_DUTY' and 'OFF_DUTY'.
                  example: ON_DUTY
                  type: string
                location:
                  description: Location to associate the duty status change with.
                  example: Loading dock
                  type: string
                remark:
                  description: Remark to associate the duty status change with.
                  example: Beginning On Duty Shift
                  type: string
                status_change_at_ms:
                  description: Timestamp that the duty status will begin at specified in milliseconds UNIX time. Defaults to the current time if left blank. This can only be set to up to 8 hours in the past.
                  example: 1580834793568
                  format: int64
                  type: number
                vehicle_id:
                  description: Vehicle ID to associate the duty status change with.
                  example: 1234
                  format: int64
                  type: number
              required:
              - duty_status
              type: object
        required: false
      responses:
        '200':
          content: {}
          description: Successfully changed duty status. No response body is returned.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Unexpected error.
      summary: Set a Duty Status for a Specific Driver
      tags:
      - Status
      x-codegen-request-body-name: dutyStatusParams
components:
  schemas:
    V1ErrorResponse:
      description: Error message describing why the request failed.
      type: string
    inline_object_1:
      properties:
        duty_status:
          description: Duty status to set the driver to. The only supported values are 'ON_DUTY' and 'OFF_DUTY'.
          example: ON_DUTY
          type: string
        location:
          description: Location to associate the duty status change with.
          example: Loading dock
          type: string
        remark:
          description: Remark to associate the duty status change with.
          example: Beginning On Duty Shift
          type: string
        status_change_at_ms:
          description: Timestamp that the duty status will begin at specified in milliseconds UNIX time. Defaults to the current time if left blank. This can only be set to up to 8 hours in the past.
          example: 1580834793568
          format: int64
          type: number
        vehicle_id:
          description: Vehicle ID to associate the duty status change with.
          example: 1234
          format: int64
          type: number
      required:
      - duty_status
      type: object
  requestBodies:
    inline_object_1:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/inline_object_1'
      required: false
  securitySchemes:
    AccessTokenHeader:
      type: http
      scheme: bearer
x-original-swagger-version: '2.0'
x-readme:
  explorer-enabled: true
  proxy-enabled: true