HyperTrack API

# Synced from feature-foundation's public OpenAPI spec via scripts/sync-openapi.mjs.
# Manually-added endpoints live in content/reference/_supplement.yaml.
# Do not edit this file by hand.
openapi: 3.0.3
info:
  title: HyperTrack API
  version: "1.0"
  description: HyperTrack API Reference — Orders, Workers, Places, Routes, and more.
  contact:
    name: HyperTrack support
    url: https://hypertrack.com/contact
    email: help@hypertrack.com
servers:
  - url: https://v3.api.hypertrack.com
tags:
  - name: Authentication
    description: Obtain and use access tokens for the HyperTrack API.
  - name: Geotags
  - name: Ops Group
  - name: Ops Groups
  - name: Timeline
  - name: Workers
  - name: Orders
  - name: OrderPlans
  - name: Routes
  - name: Tracking
  - name: Visits
  - name: Trip Orders
  - name: Nearby
  - name: OrderTasks
  - name: OrderApprovals
  - name: Approvals
  - name: WorkerApprovers
  - name: Order_Acceptances_Order
  - name: Order_Acceptances_All
  - name: TaskDefinitions
  - name: EstimatedRoutes
  - name: Export
  - name: WorkerExport
  - name: Places
paths:
  /oauth/token:
    post:
      tags:
        - Authentication
      operationId: postOauthToken
      summary: Create access token
      description: >
        Exchange your `client_id` and `client_secret` for a short-lived bearer
        token using the OAuth 2.0 `client_credentials` grant. Send the returned
        `access_token` as `Authorization: Bearer <access_token>` on all API
        requests.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - client_id
                - client_secret
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                  description: Must be `client_credentials`.
                client_id:
                  type: string
                  description: Your account's client ID.
                client_secret:
                  type: string
                  description: Your account's client secret.
                scope:
                  type: string
                  description: Optional space-delimited list of scopes.
      responses:
        "200":
          description: Token issued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: Bearer token to use on subsequent API requests.
                  token_type:
                    type: string
                    example: Bearer
                  expires_in:
                    type: integer
                    description: Token lifetime in seconds.
        "401":
          description: Invalid client credentials.
  /oauth/embed-token:
    post:
      tags:
        - Authentication
      operationId: postOauthEmbedToken
      summary: Secure embed view
      description: >
        Exchange an embeddable view URL for a short-lived secure URL with an
        access token appended, for safely embedding HyperTrack views (such as an
        order view or dashboard) in your own UI. Authenticate with HTTP Basic
        auth using your account ID and secret key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - embed_url
                - grant_type
              properties:
                embed_url:
                  type: string
                  description: URL to be embedded securely (e.g. an order view or dashboard).
                  example: https://embed.hypertrack.com/orders/my_order_handle?fulfillment-attempt=0&show-visits-only=true
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                  description: Must be `client_credentials`.
      responses:
        "200":
          description: Secure embed URL issued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: The OAuth access token.
                  token_type:
                    type: string
                    example: Bearer
                  expires_in:
                    type: integer
                    description: Token lifetime in seconds.
                  embed_url:
                    type: string
                    description: Original URL to be embedded.
                  secure_embed_url:
                    type: string
                    description: Secure URL with the token appended for embedding.
        "400":
          description: Invalid parameters (missing `embed_url` or invalid `grant_type`).
        "401":
          description: Authentication failed.
        "404":
          description: Order or device not found.
  /orders/:
    get:
      parameters:
        - in: query
          name: worker_handle
          description: Unique customer provided identifier of the worker to used retrieve
            orders associated with the specified worker
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: place_handle
          description: Unique customer provided identifier of the place to be used
            retrieve orders associated with the specified place
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: search_term
          description: String representing the search term. Search will be done on
            order_handle, ops_group_handle, worker_handle and metadata fields.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: ops_group_handle
          description: Unique Handle of Ops Group to fetch orders for
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: order_metadata_filter
          description: JSON encoded string for order metadata to filter orders by
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: risk_status
          description: Filter for risk status of order
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: region_filter
          description: JSON object containing `city`, `state`, or `country` used to filter
            orders
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: status
          description: String representation of Order status to fetch orders for. It can
            be comma separated list, each item in list can be one of
            `completed`, `cancelled`, `rescheduled`, `disabled`, `ongoing`,
            `unplanned`, `assigned`, `planned`. eg.
            `?status=completed,cancelled` or `?status=completed` to filter for
            one status
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: device_id
          description: Filter for orders associated with this device id.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: destination_geohash
          description: Geohash of the area where order destination must lie.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: plan_mode
          description: Mode of planning to be used to filter orders
          schema:
            enum:
              - on_demand
              - scheduled
              - manual
              - pool
            nullable: true
          required: false
        - in: query
          name: plan_id
          description: Filter for orders in this plan id.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: route_handle
          description: Unique Handle of the route to fetch orders for
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: track_mode
          description: Tracking mode to filter orders by. See
            [pre_shift](https://hypertrack.com/docs/shift-tracking#pre-shift-tracking),
            [on_shift](https://hypertrack.com/docs/shift-tracking#on-shift-tracking)
            documentation. `full_shift` includes both pre-shift and on-shift
            tracking. Note that `on_time` and `flex` are deprecated modes.
          schema:
            enum:
              - on_time
              - flex
              - pre_shift
              - on_shift
              - full_shift
            nullable: true
          required: false
        - in: query
          name: device_switch_mode
          description: Device switch mode to filter orders by.
          schema:
            enum:
              - manual
              - login
              - closest_to_destination
            nullable: true
          required: false
        - in: query
          name: created_at_date
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are
            created on a given date.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: created_at_from
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve
            orders that created within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: created_at_to
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve
            orders that created within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: planned_at_date
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are
            planned on a given date.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: planned_at_from
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve
            orders planned within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: planned_at_to
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve
            orders planned within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: scheduled_at_date
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are
            scheduled on a given date.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: scheduled_at_date_without_tz
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are
            scheduled on a given date irrespective of timezone.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: completed_at_date_without_tz
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are
            completed on a given date irrespective of timezone.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: scheduled_at_from
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve
            orders which have scheduled_at within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: scheduled_at_to
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve
            orders that which have scheduled_at within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: scheduled_at_without_tz_from
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve
            orders of that day in all timezone.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: scheduled_at_without_tz_to
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve
            orders of that day in all timezone.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: cancelled_at_date
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are
            cancelled on a given date.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: cancelled_at_from
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve
            orders that cancelled within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: cancelled_at_to
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve
            orders that cancelled within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: completed_at_date
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are
            completed on a given date.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: completed_at_from
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve
            orders that completed within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: completed_at_to
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve
            orders that completed within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: rescheduled_marked_at_date
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are
            rescheduled on a given date.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: rescheduled_marked_at_from
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve
            orders that rescheduled within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: rescheduled_marked_at_to
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve
            orders that rescheduled within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: route_started_at_date
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders for which
            route started on a given date.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: route_started_at_from
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve
            orders for which route started within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: route_started_at_to
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve
            orders for which route started within a timeframe.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: completed_at_without_tz_from
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve
            orders of that day for all timezone for completed orders.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: completed_at_without_tz_to
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve
            orders of that day for all timezone for completed orders.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: created_at_without_tz_from
          description: Start Date (YYYY-MM-DD ) of the window to retrieve orders from that
            day for all timezone for created orders.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: created_at_without_tz_to
          description: End Date (YYYY-MM-DD ) of the window to retrieve orders till that
            day for all timezone for created orders.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: created_at_date_without_tz
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are
            created on a given date irrespective of timezone.
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: driver_handle
          description: Unique customer provided identifier of the driver to used retrieve
            orders associated with the specified driver
          schema:
            type: string
            nullable: true
            deprecated: true
          required: false
        - in: query
          name: sort_direction
          description: String indicating the preferred sorting type
          schema:
            enum:
              - desc
              - asc
            nullable: true
          required: false
        - in: query
          name: fulfillment_attempt
          description: Filter for fulfillment attempt number
          schema:
            type: integer
            nullable: true
          required: false
        - in: query
          name: aggregate
          description: Flag to fetch order's aggregated data.
          schema:
            type: boolean
            nullable: true
          required: false
        - in: query
          name: limit
          description: Limit to number of results in response
          schema:
            type: integer
            nullable: true
          required: false
        - in: query
          name: pagination_token
          description: Encoded value provided by our API to retrieve the next page of orders
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: send_outage
          description: Boolean to send the outage in aggregation
          schema:
            type: boolean
            nullable: true
          required: false
        - in: query
          name: tracking_status
          description: Parameter to filter for tracked and untracked orders
          schema:
            type: string
            enum:
              - tracked
              - untracked
            nullable: true
          required: false
        - in: query
          name: filter_outage_category
          description: List of outage category as comma separated strings used for
            filtering associated orders within time range
          schema:
            type: string
            nullable: true
          required: false
        - in: query
          name: worker_profile_filter
          description: JSON encoded string metadata associated with the worker to filter
            orders
          schema:
            type: string
            nullable: true
            format: Encoded JSON
          required: false
        - in: query
          name: worker_inside_destination
          description: Boolean flag to filter orders based on whether the worker is inside
            the destination or not.
          schema:
            type: boolean
            nullable: true
          required: false
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetOrdersResponse"
              examples:
                Filtered on date, ops_group_handle and status:
                  summary: Filtered on date, ops_group_handle and status
                  value:
                    orders:
                      - order_handle: order-1
                        fulfillment_attempt: 0
                        status: completed
                        destination:
                          geometry:
                            type: Point
                            coordinates:
                              - -121.9007247
                              - 37.3811932
                          address: 1028 E Brokaw Rd, San Jose, CA 95131
                          radius: 100
                        ops_group_handle: store-SF
                        track_mode: on_time
                        plan_mode: manual
                        scheduled_at: 2023-10-31T04:00:00.000Z
                        type: drop
                        type_index: 0
                        expected_service_time: 0
                        capacity_used: 1
                        metadata:
                          customerID: "12654"
                        region:
                          country: United States
                          city: San Jose
                          state: California
                        product_type:
                          - frozen
                          - fragile
                        completed_at: 2023-10-31T23:13:21.287Z
                        device_id: 52193948-1A79-14GF-AB81-2FB0A59536S3
                        worker_handle: james@ht.com
                        created_at: 2023-10-30T23:41:47.489Z
                        assigned_at: 2023-10-31T23:13:03.712Z
                        route_handle: a3f6e79c-c830-4766-8a3d-9eeaa5099ce2
                Filtered on date, worker and status:
                  summary: Filtered on date, worker and status
                  value:
                    orders:
                      - order_handle: order-1
                        fulfillment_attempt: 0
                        status: completed
                        destination:
                          geometry:
                            type: Point
                            coordinates:
                              - -121.9007247
                              - 37.3811932
                          address: 1028 E Brokaw Rd, San Jose, CA 95131
                          radius: 100
                        ops_group_handle: store-SF
                        track_mode: on_time
                        plan_mode: manual
                        scheduled_at: 2023-10-31T04:00:00.000Z
                        type: drop
                        type_index: 0
                        expected_service_time: 0
                        capacity_used: 1
                        metadata:
                          customerID: "12654"
                        region:
                          country: United States
                          city: San Jose
                          state: California
                        product_type:
                          - frozen
                          - fragile
                        completed_at: 2023-10-31T23:13:21.287Z
                        device_id: 52193948-1A79-14GF-AB81-2FB0A59536S3
                        worker_handle: james@ht.com
                        created_at: 2023-10-30T23:41:47.489Z
                        assigned_at: 2023-10-31T23:13:03.712Z
                        route_handle: a3f6e79c-c830-4766-8a3d-9eeaa5099ce2
                Filtered on date and status:
                  summary: Filtered on date and status
                  value:
                    orders:
                      - order_handle: order-1
                        fulfillment_attempt: 0
                        status: cancelled
                        destination:
                          geometry:
                            type: Point
                            coordinates:
                              - -121.8871193
                              - 37.390611
                          address: 1709 Automation Pkwy, San Jose, CA 95101
                          radius: 100
                        ops_group_handle: store-SF
                        track_mode: on_time
                        plan_mode: scheduled
                        scheduled_at: 2023-10-31T02:00:00.000Z
                        type: pick
                        type_index: 0
                        expected_service_time: 0
                        capacity_used: 1
                        metadata:
                          customerID: "12654"
                        region:
                          country: United States
                          city: San Jose
                          state: California
                        product_type:
                          - frozen
                          - fragile
                        cancelled_at: 2023-10-31T23:13:13.926Z
                        device_id: 52393948-1A79-47CC-AB81-2FB0A59536D1
                        worker_handle: james@ht.com
                        created_at: 2023-10-30T23:42:28.655Z
                        assigned_at: 2023-10-31T23:13:03.617Z
                        route_handle: a3f6e79c-c830-4766-8a3d-9eeaa5099ce2
                        plan_id: a7a9c72e-bf31-44f5-8a59-c4fffb5fb9d4
                      - order_handle: order-2
                        fulfillment_attempt: 0
                        status: cancelled
                        destination:
                          geometry:
                            type: Point
                            coordinates:
                              - -121.8871193
                              - 37.390611
                          address: 1709 Automation Pkwy, San Jose, CA 95101
                          radius: 100
                        ops_group_handle: store-SF
                        track_mode: on_time
                        plan_mode: manual
                        scheduled_at: 2023-10-31T02:00:00.000Z
                        type: pick
                        type_index: 0
                        expected_service_time: 0
                        capacity_used: 1
                        metadata:
                          customerID: "12654"
                        region:
                          country: United States
                          city: San Jose
                          state: California
                        product_type:
                          - frozen
                          - fragile
                        cancelled_at: 2023-10-31T00:13:01.073Z
                        created_at: 2023-10-30T23:41:47.489Z
                        route_handle: afb94d64-2702-4efa-b938-d1facfd7832c
                      - order_handle: order-4
                        fulfillment_attempt: 0
                        status: cancelled
                        destination:
                          geometry:
                            type: Point
                            coordinates:
                              - -121.8970798
                              - 37.3838274
                          address: 1710 Old Oakland Rd, San Jose, CA 95131
                        ops_group_handle: store-SF
                        track_mode: on_time
                        plan_mode: manual
                        scheduled_after: 2023-10-31T02:00:00.000Z
                        scheduled_at: 2023-10-31T04:00:00.000Z
                        type: drop
                        type_index: 0
                        expected_service_time: 0
                        capacity_used: 1
                        metadata:
                          customerId: "1442"
                          name: Jordan
                        region:
                          country: United States
                          city: San Jose
                          state: California
                        product_type:
                          - frozen
                          - fragile
                          - valuable
                        cancelled_at: 2023-10-31T00:12:56.688Z
                        created_at: 2023-10-30T22:22:54.071Z
                        route_handle: afb94d64-2702-4efa-b938-d1facfd7832c
                Unplanned orders with planning failure reason:
                  summary: Unplanned orders with planning failure reason
                  value:
                    orders:
                      - order_handle: order-5
                        fulfillment_attempt: 0
                        status: unplanned
                        destination:
                          geometry:
                            type: Point
                            coordinates:
                              - -121.8970798
                              - 37.3838274
                          address: 1710 Old Oakland Rd, San Jose, CA 95131
                          radius: 100
                        ops_group_handle: store-SF
                        plan_mode: scheduled
                        plan_id: a7a9c72e-bf31-44f5-8a59-c4fffb5fb9d4
                        scheduled_after: 2023-10-31T02:00:00.000Z
                        scheduled_at: 2023-10-31T04:00:00.000Z
                        type: drop
                        expected_service_time: 0
                        capacity_used: 1
                        created_at: 2023-10-30T22:22:54.071Z
                        planning_failure_reason: The optimizer dropped this order to satisfy planning
                          constraints for the overall plan.
          description: Successful response
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPError"
          description: Authentication error
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
          description: Validation error
      tags:
        - Orders
      summary: Get Orders
      description: >-
        ### Planning failure reasons


        When an order is left unplanned by automated planning,
        `planning_failure_reason` may contain one of these values:


        - `No Worker was available for this plan.`

        - `No Worker schedule overlaps with this order's time window.`

        - `This order is outside the available Worker working hours.`

        - `Worker location is unavailable, so travel time could not be
        evaluated.`

        - `Worker start location is unavailable for the configured route start
        setting.`

        - `No Worker supports the required product type for this order.`

        - `Route was being modified concurrently and this order needs to be
        re-planned.`

        - `The optimizer dropped this order to satisfy planning constraints for
        the overall plan.`

        - `The optimizer could not find a feasible plan for the provided
        constraints.`

        - `Travel time calculation failed for this planning attempt.`

        - `Ops group configuration is incomplete for automated planning.`

        - `Assigning this order would exceed route or Worker capacity.`

        - `No Worker can reach this order before s

# --- truncated at 32 KB (1210 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hypertrack/refs/heads/main/openapi/hypertrack-openapi.yaml