Trimble Appointments API

openapi: 3.2.0
info:
  title: TruckMate REST Appointments API
  description: 'The TruckMate REST APIs are a comprehensive set of RESTful services, allowing you to seamlessly integrate with major TruckMate product areas. The TruckMate REST APIs allow developers to integrate the TruckMate product with custom or 3rd party applications, automate tasks, and much more.


    Business use cases of the TruckMate REST APIs include:


    - Internal systems: Use the APIs to share data and streamline internal business processes.

    - External data sharing: In addition to internal networking, the APIs allow sharing TruckMate data with third party systems to connect and share information.

    - App integrations: Access TruckMate data in real time.

    - Embedded content: Request data from the TruckMate REST APIs to embed pieces of content onto your corporate site.


    The endpoints and methods available are dependent on the license keys and authorization methods used. Use the following documentation to determine how to interact with the various available components.


    Download latest released OpenAPI


    This documentation is based on the most currently released version of TruckMate. Documentation for previous versions can be accessed by navigating to the openapi.json endpoint for any given API (the service must be set up and running). For example: http://DOMAIN/openapi.json


    ---


    © 2026, Trimble Inc. All rights reserved. Unauthorized copying prohibited. Software functions, including our APIs and their specification, are subject to change without notice. Information contained herein is Trimble Confidential Information, used under license.


    ---'
  version: '1'
  x-tm-release: 26.3.125.0
tags:
- name: Appointments
  description: The Appointments API allows e-commerce partners to select a delivery appointment for orders not yet created in TruckMate. The list of available appointment windows can be constrained to be not earlier than the Earliest Delivery Date provided by TruckMate's Transit Time API, to ensure that delivery appointments are feasible according to service standards.
paths:
  /appointments:
    get:
      summary: Retrieve existing appointments
      description: Retrieves an array of pre-booked appointments providing visibility to appointments made. The filter query parameter allows searching for specific appointments (e.g., by customer and/or external identifier). Use the optional limit and offset query parameters to page through the resulting sets of data.
      operationId: GetAppointments
      security:
      - truckmateApiKeyAuth: []
      - tidJwtAuth: []
      tags:
      - Appointments
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/orderBy'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAppointments200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
    post:
      summary: Create a new appointment
      description: Creates a single new pre-booked appointment. Use the external identifier and source fields to uniquely identify the external system that is maintaining this appointment. A valid TruckMate customer who is placing this appointment is required. The appointment type, either pickup or delivery, is also required.
      operationId: PostAppointment
      security:
      - truckmateApiKeyAuth: []
      - tidJwtAuth: []
      tags:
      - Appointments
      requestBody:
        description: A single JSON object containing the properties of the new appointment to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreappointmentPostRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/appointment'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
  /appointments/{appointmentId}:
    get:
      summary: Retrieve an appointment
      description: Retrieves a pre-booked appointment as specified by the appointment identifier in the target path parameter.
      operationId: GetAppointment
      security:
      - truckmateApiKeyAuth: []
      - tidJwtAuth: []
      tags:
      - Appointments
      parameters:
      - name: appointmentId
        in: path
        description: appointment identifier
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/appointment'
                - type: object
                  properties:
                    href:
                      type: string
                      readOnly: true
                      description: Self-referencing URL for this resource
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
    put:
      summary: Update an appointment
      description: Updates a pre-booked appointment as specified by the appointment identifier in the target path parameter. Can be used for partial updates as only the properties sent in the request will be updated. Will return a 409 Conflict response if the appointment has already been matched to an order.
      operationId: PutAppointment
      security:
      - truckmateApiKeyAuth: []
      - tidJwtAuth: []
      tags:
      - Appointments
      requestBody:
        description: A single JSON object containing the properties to be updated. All fields are optional, but at least one field must be sent.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreappointmentPutRequest'
      parameters:
      - name: appointmentId
        in: path
        description: appointment identifier
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/appointment'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ARTErrors'
components:
  parameters:
    orderBy:
      name: $orderBy
      in: query
      description: Field(s) to order returned resource by, with optional direction. E.g., "fieldName desc, fieldName2"
      required: false
      style: form
      explode: true
      schema:
        type: string
    offset:
      name: offset
      in: query
      description: Specifies the number of items to skip before beginning to select the records to return.
      required: false
      style: form
      explode: true
      schema:
        type: integer
        default: 0
    limit:
      name: limit
      in: query
      description: Specifies the maximum number of items to include in the response results.
      required: false
      style: form
      explode: true
      schema:
        type: integer
        default: 20
    filter:
      name: $filter
      in: query
      description: Filter items by property values, see [Filtering](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_SystemQueryOptionfilter). Note, not all features of oData filter syntax are supported.
      required: false
      style: form
      explode: true
      schema:
        type: string
  schemas:
    PreappointmentPutRequest:
      type: object
      properties:
        externalId:
          type: string
          description: 'An identifier that uniquely identifies this booking in an external system identified by externalSource. If specified, must be accompanied by externalSource. '
          maxLength: 40
        externalSource:
          type: string
          description: 'An identifier that uniquely identifies the external system that is maintaining this appointment. Required if externalId is specified. '
          maxLength: 255
        customer:
          type: string
          description: 'TruckMate client ID. Identifies the customer placing this appointment. Required if customerOrderReference is specified. '
          maxLength: 10
        customerType:
          type: string
          description: Identifies the role of the party specified in customer. Required if customerOrderReference is specified. Valid values are caller, shipper, consignee, bill-to, other.
          enum:
          - caller
          - shipper
          - consignee
          - bill-to
          - other
        customerOrderReference:
          type: string
          description: Identifies this shipment uniquely from other shipments to which customer is a party. This value should be included later in an electronic shipment tender for matching up to the appointment. If specified, must be accompanied by customer and customerType.
          maxLength: 100
        appointmentType:
          type: string
          description: 'Valid values: pickup, delivery. A single value for customerOrderReference may have a separate appointment for each value of appointmentType.'
          enum:
          - pickup
          - delivery
        terminalZone:
          type: string
          description: TruckMate zone code. Identifies the zone corresponding to the terminal that will be responsible for managing this appointment.
          maxLength: 10
        earliestDateTime:
          type: string
          description: If specified, must be accompanied by latestDateTime. The beginning of the appointment window during which the freight may be delivered.
          pattern: ^\d{4}-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12]\d)((T| )([01]\d|2[0-3]):([0-5]\d):([0-5]\d))?$
        latestDateTime:
          type: string
          description: If specified, must be accompanied by earliestDateTime. The end of the appointment window during which the freight may be delivered.
          pattern: ^\d{4}-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12]\d)((T| )([01]\d|2[0-3]):([0-5]\d):([0-5]\d))?$
        status:
          type: string
          description: Allows the external system to cancel an appointment request. Valid values for this property include PENDING, MATCHED, or CANCELLED, but only CANCELLED will be accepted in a PUT request. (Changing to PENDING or MATCHED is reserved behaviour.)
          maxLength: 15
    appointment:
      type: object
      properties:
        appointmentId:
          type: integer
          description: Unique resource identifier for the appointment.
        externalId:
          type: string
          maxLength: 40
          description: An identifier that uniquely identifies this booking in an external system identified by externalSource.
        externalSource:
          type: string
          maxLength: 255
          description: An identifier that uniquely identifies the external system that is maintaining this appointment.
        customer:
          type: string
          maxLength: 10
          description: TruckMate client ID. Identifies the customer placing this appointment.
        customerType:
          type: string
          description: Identifies the role of the party specified in customer. Valid values are caller, shipper, consignee, bill-to, other.
          enum:
          - caller
          - shipper
          - consignee
          - bill-to
          - other
          - ''
        customerOrderReference:
          type: string
          maxLength: 100
          description: Identifies this shipment uniquely from other shipments to which customer is a party. This value should be included later in an electronic shipment tender for matching up to the appointment. If specified, must be accompanied by customer and customerType.
        appointmentType:
          type: string
          description: 'Valid values: pickup, delivery. A single value for customerOrderReference may have a separate appointment for each value of appointmentType.'
          enum:
          - pickup
          - delivery
          - ''
        terminalZone:
          type: string
          maxLength: 10
          description: TruckMate zone code. Identifies the zone corresponding to the terminal that will be responsible for managing this appointment.
        earliestDateTime:
          type:
          - string
          - 'null'
          description: ISO 8601-1:2019 date. The beginning of the appointment window during which the freight may be delivered.
          oneOf:
          - enum:
            - ''
          - pattern: ^\d{4}-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12]\d)((T| )([01]\d|2[0-3]):([0-5]\d):([0-5]\d))?$
        latestDateTime:
          type:
          - string
          - 'null'
          description: ISO 8601-1:2019 date. The end of the appointment window during which the freight may be delivered.
          oneOf:
          - enum:
            - ''
          - pattern: ^\d{4}-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12]\d)((T| )([01]\d|2[0-3]):([0-5]\d):([0-5]\d))?$
        status:
          type: string
          maxLength: 15
          description: Current status of the appointment pre-booking. Valid values are PENDING (not yet matched to an order), MATCHED (matched to an order by the system), and CANCELLED.
        billNumber:
          type: string
          maxLength: 20
          description: Bill number of the order to which the appointment has been matched, if applicable.
        detailLineId:
          type:
          - integer
          - 'null'
          description: Unique order identifier for the order to which the appointment has been matched, if applicable.
    ARTError:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        code:
          type: string
          description: Error code (optional, deprecated; omitted in Mobile Comm)
          deprecated: true
        description:
          type: string
          description: Human-readable description (optional, deprecated; omitted in Mobile Comm)
          deprecated: true
    ARTErrors:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
          enum:
          - 400
          - 401
          - 403
          - 404
          - 405
          - 409
          - 429
          - 500
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ARTError'
    GetAppointments200:
      type: object
      properties:
        href:
          type: string
          readOnly: true
          description: Self-referencing URL for this resource
        offset:
          type: integer
        limit:
          type: integer
        filter:
          type: string
        sort:
          type: string
        appointments:
          type: array
          items:
            $ref: '#/components/schemas/appointment'
    PreappointmentPostRequest:
      type: object
      properties:
        externalId:
          type: string
          description: 'An identifier that uniquely identifies this booking in an external system identified by externalSource. If specified, must be accompanied by externalSource. '
          maxLength: 40
        externalSource:
          type: string
          description: An identifier that uniquely identifies the external system that is maintaining this appointment. Required if externalId is specified.
          maxLength: 255
        customer:
          type: string
          description: TruckMate client ID. Identifies the customer placing this appointment.
          maxLength: 10
        customerType:
          type: string
          description: Identifies the role of the party specified in customer. Valid values are caller, shipper, consignee, bill-to, other.
          enum:
          - caller
          - shipper
          - consignee
          - bill-to
          - other
        customerOrderReference:
          type: string
          description: Identifies this shipment uniquely from other shipments to which customer is a party. This value should be included later in an electronic shipment tender for matching up to the appointment.
          maxLength: 100
        appointmentType:
          type: string
          description: 'Valid values: pickup, delivery. A single value for customerOrderReference may have a separate appointment for each value of appointmentType.'
          enum:
          - pickup
          - delivery
        terminalZone:
          type: string
          description: TruckMate zone code. Identifies the zone corresponding to the terminal that will be responsible for managing this appointment.
          maxLength: 10
        earliestDateTime:
          type: string
          description: The beginning of the appointment window during which the freight may be delivered.
          pattern: ^\d{4}-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12]\d)((T| )([01]\d|2[0-3]):([0-5]\d):([0-5]\d))?$
        latestDateTime:
          type: string
          description: The end of the appointment window during which the freight may be delivered.
          pattern: ^\d{4}-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12]\d)((T| )([01]\d|2[0-3]):([0-5]\d):([0-5]\d))?$
      required:
      - customer
      - customerType
      - customerOrderReference
      - appointmentType
      - terminalZone
      - earliestDateTime
      - latestDateTime
  securitySchemes:
    tidJwtAuth:
      type: http
      description: A time-limited JSON Web Token generated via separate POST request using TID
      scheme: bearer
    webuserJwtAuth:
      type: http
      description: A fresh JSON Web Token expires in four hours. It can be renewed by making a GET request to /login endpoint, or generated by making a POST request to /login endpoint
      scheme: bearer
    clientApiKeyAuth:
      type: http
      description: Client API Key
      scheme: bearer
    truckmateApiKeyAuth:
      type: http
      description: TruckMate API Key
      scheme: bearer
    vendorApiKeyAuth:
      type: http
      description: Vendor API Key
      scheme: bearer
externalDocs:
  url: https://learn.transportation.trimble.com/