> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsert Driver

> Create or update a driver in your internal fleet, keyed on your own `externalIdentifier`. There is no separate create vs. update call — sending the same `externalIdentifier` again updates the existing driver. The response's `created` field tells you which happened. To disable a driver, upsert with `isShiftActive: false` (or `enabled: false`) — there is no separate delete/disable call.



## OpenAPI

````yaml put /v1/fleet/drivers/upsert
openapi: 3.1.0
info:
  title: Nash API
  version: 1.0.0
servers:
  - url: https://api.sandbox.usenash.com
    description: Sandbox API
  - url: https://api.sandbox.ap-southeast-2.usenash.com
    description: Sandbox API (Australia)
  - url: https://api.usenash.com
    description: Production API
  - url: https://api.ap-southeast-2.usenash.com
    description: Production API (Australia)
security: []
tags:
  - name: Notifications
    description: Notifications
    x-nash-topic: config
  - name: Annotate
    description: Annotate
    x-nash-topic: wismo
  - name: Notifications — Send
    description: One-off notification send without a NotificationTrigger.
    x-nash-topic: notifications
  - name: Shipping
    description: Shipping operations
    x-nash-topic: shipping
  - name: Workflow
    description: Workflow automation management
    x-nash-topic: scheduling
  - name: Workflow Execution
    description: Workflow execution history and monitoring
    x-nash-topic: scheduling
  - name: Optimization Strategies
    description: Create, read, update, and delete route optimization strategies.
    x-nash-topic: scheduling
  - name: AI Agents
    description: AI agent management — create, read, update, and delete agents
    x-nash-topic: config
  - name: AI Functions
    description: LLM-backed domain tools
    x-nash-topic: ai
  - name: Webhooks
    description: Webhook delivery inspection
    x-nash-topic: webhooks
  - name: Miscellaneous
    description: Miscellaneous
  - name: Job
    description: Job
    x-nash-topic: wismo
  - name: Batch Job
    description: Batch Job
    x-nash-topic: wismo
  - name: Order
    description: Order
    x-nash-topic: wismo
  - name: Route
    description: Route
    x-nash-topic: scheduling
  - name: Provider
    description: Provider
    x-nash-topic: provider
  - name: Dispatch Strategies
    description: Dispatch Strategies
    x-nash-topic: scheduling
  - name: Store Locations
    description: Store Locations
    x-nash-topic: config
  - name: Vehicles
    description: Vehicles
    x-nash-topic: provider
  - name: Couriers
    description: Couriers
    x-nash-topic: provider
  - name: Shifts
    description: Shifts
    x-nash-topic: provider
  - name: Delivery Windows
    description: Delivery Windows
    x-nash-topic: config
  - name: Templates
    description: Templates
    x-nash-topic: config
  - name: Zones
    description: Zones
    x-nash-topic: config
  - name: Feedback
    description: Feedback
    x-nash-topic: reporting
  - name: Organizations
    description: Organizations
    x-nash-topic: config
  - name: Store Catalog
    description: Store Catalog
    x-nash-topic: config
  - name: Messaging
    description: Messaging
    x-nash-topic: config
  - name: Billing
    description: Invoice-aligned customer billing usage
    x-nash-topic: config
  - name: Contracts
    description: Provider contract pricing and version listings
    x-nash-topic: provider
  - name: Embed Sessions
    description: >-
      Mint short-lived, browser-safe sessions for embedded Nash Widgets.
      Authenticated with an org embed credential, which must stay on your
      backend.
    x-nash-topic: config
  - name: Event Timeline
    description: Entity-scoped event timeline + outbound provider traffic for one entity.
    x-nash-topic: internal
  - name: Inventory
    description: Store inventory catalog sync to SFTP retail destinations (e.g. Uber).
    x-nash-topic: store_catalog
  - name: Fleet
    description: Inbound endpoints fleets call to update in-flight deliveries.
    x-nash-topic: delivery
  - name: Route Restrictions
    description: Org-scoped geographic areas the route optimizer must avoid traversing.
    x-nash-topic: config
  - name: Users
    description: User, role, and organization-membership management.
    x-nash-topic: config
  - name: Widgets
    description: >-
      Org configuration for embedded Nash Widgets: parent origins, enablement,
      and embed credentials.
    x-nash-topic: config
paths:
  /v1/fleet/drivers/upsert:
    put:
      tags:
        - Fleet
      summary: Upsert Driver
      description: >-
        Create or update a driver in your internal fleet, keyed on your own
        `externalIdentifier`. There is no separate create vs. update call —
        sending the same `externalIdentifier` again updates the existing driver.
        The response's `created` field tells you which happened. To disable a
        driver, upsert with `isShiftActive: false` (or `enabled: false`) — there
        is no separate delete/disable call.
      operationId: drivers_v1_upsert_driver_route_upsert_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CourierUpsert'
        required: true
      responses:
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
components:
  schemas:
    CourierUpsert:
      title: CourierUpsert
      required:
        - externalIdentifier
      type: object
      properties:
        externalIdentifier:
          title: Externalidentifier
          type: string
          description: Caller's own id for this driver; the upsert identity key.
        phoneNumber:
          title: Phonenumber
          anyOf:
            - type: string
            - type: 'null'
          default: null
        email:
          title: Email
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Provisions (or links) a Nash driver-app login for this email,
            mirroring the portal's own driver create/edit behavior: creates or
            reuses a User and its Auth0 email identity.
          default: null
        firstName:
          title: Firstname
          anyOf:
            - type: string
            - type: 'null'
          default: null
        lastName:
          title: Lastname
          anyOf:
            - type: string
            - type: 'null'
          default: null
        vehicleInfo:
          title: Vehicleinfo
          anyOf:
            - type: object
              additionalProperties: true
            - type: 'null'
          default: null
        vehicleIds:
          title: Vehicleids
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: Existing Vehicle ids to link to this driver.
          default: null
        storeLocationIds:
          title: Storelocationids
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          default: null
        firstVersionContractIds:
          title: Firstversioncontractids
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: >-
            Driver group membership, by first_version_contract_id. Omit to leave
            unchanged.
          default: null
        isShiftActive:
          title: Isshiftactive
          type: boolean
          description: >-
            Whether the driver is available. Defaults to true for a newly
            created driver when omitted; an update call that omits it leaves the
            existing value unchanged.
          default: true
        enabled:
          title: Enabled
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
        dateOfBirth:
          title: Dateofbirth
          anyOf:
            - type: string
              format: date
            - type: 'null'
          default: null
        workRelationship:
          anyOf:
            - $ref: '#/components/schemas/WorkRelationship'
            - type: 'null'
          default: null
        driversLicense:
          title: Driverslicense
          anyOf:
            - type: string
            - type: 'null'
          default: null
      additionalProperties: false
      description: >-
        ``PUT /v1/fleet/drivers/upsert`` request body — see FLE-2224.


        Identity key is ``external_identifier``, scoped to the calling org's own

        internal-fleet provider (not phone/email — this endpoint never touches

        ``User``/Auth0 identity, unlike the GraphQL
        ``CreateCourier``/``UpdateCourier``

        mutations). No driver-group/contract fields — that assignment is out of

        scope for this endpoint; see the FLE-2224 plan for the deferred
        follow-up.


        Wire format is camelCase, matching the rest of Nash's customer-facing
        REST

        API (``populate_by_name=True`` also accepts snake_case).
    NashValidationError:
      title: NashValidationError
      required:
        - error
        - response_status
        - RequestID
      type: object
      properties:
        error:
          $ref: '#/components/schemas/NashErrorDetails'
        response_status:
          title: Response Status
          type: string
        RequestID:
          title: Requestid
          type: string
    WorkRelationship:
      title: WorkRelationship
      enum:
        - EMPLOYEE
        - CONTRACTOR
      type: string
    NashErrorDetails:
      title: NashErrorDetails
      required:
        - code
        - message
      type: object
      properties:
        code:
          title: Code
          type: string
        message:
          title: Message
          type: string
        details:
          title: Details
          anyOf:
            - type: object
              additionalProperties: true
            - type: 'null'
          description: >-
            Structured error context; shape depends on `code`. For
            `VALIDATION_ERRORS` (HTTP 422) it is `{"fields": [{"loc": [...],
            "msg": "...", "type": "..."}]}` — one entry per invalid field, where
            `loc` is the field path, `msg` the human-readable message, and
            `type` the machine-readable error type (e.g. `string_type`,
            `missing`).
          default: null

````