Shiftmove Drivers API

openapi: 3.2.0
info:
  version: 1.2.3
  title: Fleet API Specifications Custom fields Drivers API
  x-logo:
    url: logo.svg
  description: "# Introduction\nThe Avrios Fleet-API allows syncing fleet data with our system. The provided API allows you to persist, update, delete and query various entities. Refer to the current [Release Notes](release-notes.html) for relevant changes in the API. \n# Access and usage\n## Authorization\nIn order to use the API a basic auth header must be set on each request: `Authorization: Basic {base64 of username:password}`.\n## Rate limiting\nRequests are limited to 300 requests per minute.\n## Response objects \nIn all API responses, only populated fields will be returned - `null` fields are stripped from the response object.\n## Update endpoints\nWhen updating existing entities, unless otherwise specified we will only update properties sent in the request, and all properties are optional. Clearing a property can be performed by explicitly sending `null`.\n## Date interpretation \nFor consistency with the Avrios UI, some APIs accept dates in the format `yyyy-MM-dd` rather than timestamps. If these are used for filtering or business logic, they will be interpreted as the first second of the day in the company timezone (e.g. `2020-01-01` in CET becomes `2019-12-31T23:00:00Z)`."
servers:
- url: https://api.avrios.com
tags:
- name: Drivers
paths:
  /v1/drivers:
    get:
      tags:
      - Drivers
      summary: GET paginated drivers
      description: Access pages of drivers
      operationId: getAllDrivers
      parameters:
      - name: limit
        in: query
        description: Number of items in a page
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
      - name: pageNumber
        in: query
        description: Number of the page
        required: false
        schema:
          type: integer
          minimum: 1
      - name: sortBy
        in: query
        description: Sorting key
        required: false
        schema:
          type: string
          enum:
          - uuid
          - firstName
          - lastName
          - internalId
          - state
      - name: reverse
        in: query
        description: Sorting order
        required: false
        schema:
          type: boolean
          enum:
          - 'false'
          - 'true'
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiPageMinimalDriverDto'
        '400':
          description: Bad request - information on the invalid fields will be provided in the response body
    post:
      tags:
      - Drivers
      summary: POST driver
      description: Create a new driver.
      operationId: createDriver
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverDto'
        '400':
          description: Bad request - information on the invalid fields will be provided in the response body
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DriverCreateApiParams'
  /v1/drivers/query:
    post:
      tags:
      - Drivers
      summary: QUERY paginated drivers
      description: Query drivers based on specific criteria. The result is paginated
      operationId: queryDrivers
      parameters:
      - name: limit
        in: query
        description: Number of items in a page
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
      - name: pageNumber
        in: query
        description: Number of the page
        required: false
        schema:
          type: integer
          minimum: 1
      - name: sortBy
        in: query
        description: Sorting key
        required: false
        schema:
          type: string
          enum:
          - uuid
          - firstName
          - lastName
          - internalId
          - state
      - name: reverse
        in: query
        description: Sorting order
        required: false
        schema:
          type: boolean
          enum:
          - 'false'
          - 'true'
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiPageMinimalDriverDto'
        '400':
          description: Bad request - information on the invalid fields will be provided in the response body
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DriverQueryApiParams'
  /v1/drivers/{uuid}:
    get:
      tags:
      - Drivers
      summary: GET driver by UUID
      description: Get detailed information about a specific driver.
      operationId: findDriverByUuid
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverDto'
        '400':
          description: Bad request - information on the invalid fields will be provided in the response body
        '404':
          description: Driver not found.
    post:
      tags:
      - Drivers
      summary: UPDATE a specific driver
      description: Post a map of key value pairs for fields with the new value. A value of `null` is accepted (where marked as nullable) and will clear that field. Cleared fields will not be shown in the response, as `null` fields are stripped by default. If a field is not present in the map it will not be altered. **Fields not marked as nullable can be left out of the map all together so as not to be changed**
      operationId: updateDriverByUuid
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverDto'
        '400':
          description: Bad request - information on the invalid fields will be provided in the response body
        '404':
          description: Driver not found.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DriverUpdateApiParams'
  /v1/drivers/{uuid}/customFieldValues/{customFieldUuid}:
    post:
      tags:
      - Drivers
      summary: UPDATE driver custom field value
      description: Update a custom field value for a driver, identified by driver UUID and custom field UUID. It doesn't matter whether the custom field value has been set for this driver previously.
      operationId: setDriverCustomFieldValue
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: customFieldUuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldValueDto'
        '400':
          description: Bad request - information on the invalid fields will be provided in the response body
        '404':
          description: Driver or custom field not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldValueUpdateRequest'
  /v1/drivers/{uuid}/stateHistory:
    post:
      tags:
      - Drivers
      summary: CREATE driver state history entry
      description: Adds an entry to the driver state history. This cannot be added on the same day as an existing entry. If the driver is archived, any fuel card or vehicle assignments associated with this driver will be automatically ended on the archive date.
      operationId: setDriverState
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverStateHistoryDto'
        '400':
          description: Bad request - information on the invalid fields will be provided in the response body
        '409':
          description: There is an existing driver state entry on this date
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DriverStateHistoryApiParams'
components:
  schemas:
    DateRangeDto:
      type: object
      properties:
        startDate:
          type: string
          format: date
          description: Inclusive start date.
        endDate:
          type: string
          format: date
          description: Exclusive end date.
    MonetaryAmountApiParams:
      type: object
      properties:
        amount:
          type: number
        currency:
          type: string
          description: ISO 4217 alphabetic currency code
    PhoneNumberDto:
      type: object
      properties:
        number:
          type: string
          description: A valid phone number.
        country:
          type: string
          description: ISO 3166-1 Alpha-2 country code
    PhoneNumberApiParams:
      type: object
      properties:
        number:
          type: string
          description: A valid phone number.
        country:
          type: string
          description: ISO 3166-1 Alpha-2 country code
    CustomFieldCategoryWithValuesDto:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
        position:
          type: integer
          format: int32
        customFieldValues:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldValueDto'
    DriverQueryApiParams:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        firstName:
          type: string
        lastName:
          type: string
        internalId:
          type: string
        state:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - LEAVE
        lastModified:
          $ref: '#/components/schemas/InstantRangeApiParams'
    DriverStateHistoryApiParams:
      type: object
      properties:
        date:
          type: string
          format: date
        state:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - LEAVE
    MonetaryAmountDto:
      type: object
      properties:
        amount:
          type: number
        currency:
          type: string
          description: ISO 4217 alphabetic currency code
    CustomFieldValueUpdateRequest:
      type: object
      properties:
        textValue:
          type: string
        dateValue:
          type: string
          format: date-time
        booleanValue:
          type: boolean
        integerValue:
          type: integer
          format: int32
        decimalValue:
          type: number
        monetaryAmountValue:
          $ref: '#/components/schemas/MonetaryAmountApiParams'
        exactlyOneValueSet:
          type: boolean
    CustomFieldValueDto:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        textValue:
          type: string
        dateValue:
          type: string
          format: date-time
        booleanValue:
          type: boolean
        integerValue:
          type: integer
          format: int32
        decimalValue:
          type: number
        monetaryAmountValue:
          $ref: '#/components/schemas/MonetaryAmountDto'
    InstantRangeApiParams:
      type: object
      properties:
        atOrAfter:
          type: string
          format: date-time
        before:
          type: string
          format: date-time
    ApiPageMinimalDriverDto:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MinimalDriverDto'
        page:
          $ref: '#/components/schemas/ApiPageInformation'
        totalItems:
          type: integer
          format: int64
    DriverUpdateApiParams:
      type: object
      properties:
        startDate:
          type:
          - string
          - 'null'
          format: date
        organizationUuid:
          type: string
          format: uuid
        gender:
          type:
          - string
          - 'null'
          enum:
          - MALE
          - FEMALE
        firstName:
          type: string
        middleName:
          type:
          - string
          - 'null'
        lastName:
          type: string
        emailWork:
          type:
          - string
          - 'null'
          description: A valid email address.
        emailPrivate:
          type:
          - string
          - 'null'
          description: A valid email address.
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumberDto'
        mobilePhoneNumber:
          $ref: '#/components/schemas/PhoneNumberDto'
        notificationChannel:
          type:
          - string
          - 'null'
          enum:
          - EMAIL
          - SMS
        address:
          type:
          - string
          - 'null'
        zipCode:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
          description: ISO 3166-1 Alpha-2 country code
        language:
          type:
          - string
          - 'null'
          description: ISO 639-1 Language Code
        nationality:
          type:
          - string
          - 'null'
          description: ISO 3166-1 Alpha-2 country code
        placeOfBirth:
          type:
          - string
          - 'null'
        birthDate:
          type:
          - string
          - 'null'
          format: date
        internalId:
          type:
          - string
          - 'null'
        costCenter:
          type:
          - string
          - 'null'
        subCompany:
          type:
          - string
          - 'null'
        department:
          type:
          - string
          - 'null'
        location:
          type:
          - string
          - 'null'
        comment:
          type:
          - string
          - 'null'
        distanceToWorkplace:
          type:
          - number
          - 'null'
        employeePayment:
          type:
          - number
          - 'null'
    DriverCreateApiParams:
      type: object
      properties:
        state:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - LEAVE
        startDate:
          type: string
          format: date
        organizationUuid:
          type: string
          format: uuid
          description: If not provided the organization will be set to that of the API token
        gender:
          type: string
          enum:
          - MALE
          - FEMALE
        firstName:
          type: string
        middleName:
          type: string
        lastName:
          type: string
        emailWork:
          type: string
          description: A valid email address.
        emailPrivate:
          type: string
          description: A valid email address.
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumberApiParams'
        mobilePhoneNumber:
          $ref: '#/components/schemas/PhoneNumberApiParams'
        notificationChannel:
          type: string
          enum:
          - EMAIL
          - SMS
        address:
          type: string
        zipCode:
          type: string
        city:
          type: string
        country:
          type: string
          description: ISO 3166-1 Alpha-2 country code
        language:
          type: string
          description: ISO 639-1 language code
        nationality:
          type: string
          description: ISO 3166-1 Alpha-2 country code
        placeOfBirth:
          type: string
        birthDate:
          type: string
          format: date
        internalId:
          type: string
        costCenter:
          type: string
        subCompany:
          type: string
        department:
          type: string
        location:
          type: string
        comment:
          type: string
        distanceToWorkplace:
          type: number
        employeePayment:
          type: number
    DriverDto:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        state:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - LEAVE
        startDate:
          type: string
          format: date
        gender:
          type: string
          enum:
          - MALE
          - FEMALE
        firstName:
          type: string
        middleName:
          type: string
        lastName:
          type: string
        emailWork:
          type: string
          description: A valid email address.
        emailWorkType:
          type: string
          enum:
          - MANUAL
          - AUTOMATIC
        emailPrivate:
          type: string
          description: A valid email address.
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumberDto'
        mobilePhoneNumber:
          $ref: '#/components/schemas/PhoneNumberDto'
        notificationChannel:
          type: string
          enum:
          - EMAIL
          - SMS
        address:
          type: string
        zipCode:
          type: string
        city:
          type: string
        country:
          type: string
          description: ISO 3166-1 Alpha-2 country code
        language:
          type: string
          description: ISO 639-1 Language Code
        nationality:
          type: string
          description: ISO 3166-1 Alpha-2 country code
        placeOfBirth:
          type: string
        birthDate:
          type: string
          format: date
        internalId:
          type: string
        costCenter:
          type: string
        subCompany:
          type: string
        department:
          type: string
        location:
          type: string
        comment:
          type: string
        distanceToWorkplace:
          type: number
        employeePayment:
          type: number
        eligibleForDriverBriefings:
          type: boolean
        eligibleForDriverLicenseChecks:
          type: boolean
        managementType:
          type: string
          enum:
          - MANUAL
          - AUTOMATIC
        customFieldValuesByCategory:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldCategoryWithValuesDto'
        organizationUuid:
          type: string
          format: uuid
    MinimalDriverDto:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        firstName:
          type: string
        lastName:
          type: string
        internalId:
          type: string
        state:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - LEAVE
        lastModified:
          type: string
          format: date-time
    ApiPageInformation:
      type: object
      properties:
        pageNumber:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
    DriverStateHistoryDto:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        driverUuid:
          type: string
          format: uuid
        state:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - LEAVE
        dateRange:
          $ref: '#/components/schemas/DateRangeDto'
x-tagGroups:
- name: Vehicles
  tags:
  - Vehicles
  - Vehicle license plates
  - Vehicle assignments
  - Vehicle usages
  - Vehicle custom fields
  - Vehicle financing
- name: Drivers
  tags:
  - Drivers
  - Driver assignments
  - Driver custom fields
- name: Other
  tags:
  - Custom fields
  - Invoices
  - Organizations