raute-io Drivers API

openapi: 3.2.0
info:
  title: Raute Partner Drivers API
  version: 1.0.0
  summary: Push delivery orders into Raute and read tracking back out.
  description: 'Raute plans multi-stop delivery routes, tracks drivers live and captures proof of delivery. This API is how another system hands Raute the stops it needs delivered and reads back where each one is.


    Keys are issued by the account holder at https://www.raute.io/api-keys and are available on every plan. A key belongs to one company and can only ever see that company''s data; the company is taken from the key, never from the request.'
  contact:
    name: Raute
    url: https://www.raute.io/developers
servers:
- url: https://www.raute.io/api/v1
security:
- apiKey: []
tags:
- name: Drivers
  description: Read drivers and link them to ids in your own system.
paths:
  /drivers:
    get:
      tags:
      - Drivers
      summary: List drivers
      description: Requires the orders:read scope, not the narrower tracking scope.
      parameters:
      - name: source
        in: query
        schema:
          type: string
      - name: unlinked
        in: query
        schema:
          type: string
        description: Return only drivers with no external id for this source.
      responses:
        '200':
          description: The company's drivers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Driver'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
      operationId: getDrivers
      x-operation-id-source: derived
  /drivers/{id}:
    patch:
      tags:
      - Drivers
      summary: Link a driver to an id in your own system
      description: Requires the orders:write scope.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                external_source:
                  type: string
                external_id:
                  type: string
      responses:
        '200':
          description: The updated driver.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Driver'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: patchDriversById
      x-operation-id-source: derived
components:
  responses:
    Unauthorized:
      description: The key is missing, unknown or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientScope:
      description: The key is valid but does not carry the scope this endpoint needs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such record on this company.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Driver:
      type: object
      properties:
        id:
          type: string
        name:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
        external_id:
          type:
          - string
          - 'null'
        external_source:
          type:
          - string
          - 'null'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              examples:
              - insufficient_scope
              - missing_field
              - invalid_json
            message:
              type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: 'A key created at https://www.raute.io/api-keys. The secret is shown once at creation and never again, because only its hash is stored. Each key carries scopes: tracking:read, orders:read, orders:write.'