openapi: 3.2.0
info:
  title: HyperTrack Export 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: Export
paths:
  /orders/export:
    post:
      parameters: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderExportResponse'
          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:
      - Export
      summary: Create an order export job
      description: Creates an asynchronous job to export orders to CSV.gz file. Returns a job_id that can be used to check status. Download link will be sent via email when ready.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderExportRequest'
      security:
      - BasicAuth: []
      - TokenAuth: []
  /orders/export/{job_id}:
    get:
      parameters:
      - in: path
        name: job_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderExportStatusResponse'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Export
      summary: Get export job status
      description: Check the status of an export job by job_id. Returns current status, progress, and download URL when completed.
      security:
      - BasicAuth: []
      - TokenAuth: []
components:
  schemas:
    OrderExportRequest:
      type: object
      properties:
        worker_handle:
          type:
          - string
          - 'null'
          description: Unique customer provided identifier of the worker to used retrieve orders associated with the specified worker
        place_handle:
          type:
          - string
          - 'null'
          description: Unique customer provided identifier of the place to be used retrieve orders associated with the specified place
        search_term:
          type:
          - string
          - 'null'
          description: String representing the search term. Search will be done on order_handle, ops_group_handle, worker_handle and metadata fields.
        ops_group_handle:
          type:
          - string
          - 'null'
          description: Unique Handle of Ops Group to fetch orders for
        order_metadata_filter:
          type:
          - string
          - 'null'
          description: JSON encoded string for order metadata to filter orders by
        risk_status:
          type:
          - string
          - 'null'
          description: Filter for risk status of order
        region_filter:
          type:
          - string
          - 'null'
          description: JSON object containing `city`, `state`, or `country` used to filter orders
        status:
          type:
          - string
          - 'null'
          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
        device_id:
          type:
          - string
          - 'null'
          description: Filter for orders associated with this device id.
        destination_geohash:
          type:
          - string
          - 'null'
          description: Geohash of the area where order destination must lie.
        plan_mode:
          enum:
          - on_demand
          - scheduled
          - manual
          - pool
          description: Mode of planning to be used to filter orders
        plan_id:
          type:
          - string
          - 'null'
          description: Filter for orders in this plan id.
        route_handle:
          type:
          - string
          - 'null'
          description: Unique Handle of the route to fetch orders for
        track_mode:
          enum:
          - on_time
          - flex
          - pre_shift
          - on_shift
          - full_shift
          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.
        device_switch_mode:
          enum:
          - manual
          - login
          - closest_to_destination
          description: Device switch mode to filter orders by.
        created_at_date:
          type:
          - string
          - 'null'
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are created on a given date.
        created_at_from:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve orders that created within a timeframe.
        created_at_to:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve orders that created within a timeframe.
        planned_at_date:
          type:
          - string
          - 'null'
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are planned on a given date.
        planned_at_from:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve orders planned within a timeframe.
        planned_at_to:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve orders planned within a timeframe.
        scheduled_at_date:
          type:
          - string
          - 'null'
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are scheduled on a given date.
        scheduled_at_date_without_tz:
          type:
          - string
          - 'null'
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are scheduled on a given date irrespective of timezone.
        completed_at_date_without_tz:
          type:
          - string
          - 'null'
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are completed on a given date irrespective of timezone.
        scheduled_at_from:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve orders which have scheduled_at within a timeframe.
        scheduled_at_to:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve orders that which have scheduled_at within a timeframe.
        scheduled_at_without_tz_from:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve orders of that day in all timezone.
        scheduled_at_without_tz_to:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve orders of that day in all timezone.
        cancelled_at_date:
          type:
          - string
          - 'null'
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are cancelled on a given date.
        cancelled_at_from:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve orders that cancelled within a timeframe.
        cancelled_at_to:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve orders that cancelled within a timeframe.
        completed_at_date:
          type:
          - string
          - 'null'
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are completed on a given date.
        completed_at_from:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve orders that completed within a timeframe.
        completed_at_to:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve orders that completed within a timeframe.
        rescheduled_marked_at_date:
          type:
          - string
          - 'null'
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are rescheduled on a given date.
        rescheduled_marked_at_from:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve orders that rescheduled within a timeframe.
        rescheduled_marked_at_to:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve orders that rescheduled within a timeframe.
        route_started_at_date:
          type:
          - string
          - 'null'
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders for which route started on a given date.
        route_started_at_from:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the start of window to retrieve orders for which route started within a timeframe.
        route_started_at_to:
          type:
          - string
          - 'null'
          description: Timestamp (YYYY-MM-DD HH:mm:ss) of the end of window to retrieve orders for which route started within a timeframe.
        completed_at_without_tz_from:
          type:
          - string
          - 'null'
          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.
        completed_at_without_tz_to:
          type:
          - string
          - 'null'
          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.
        created_at_without_tz_from:
          type:
          - string
          - 'null'
          description: Start Date (YYYY-MM-DD ) of the window to retrieve orders from that day for all timezone for created orders.
        created_at_without_tz_to:
          type:
          - string
          - 'null'
          description: End Date (YYYY-MM-DD ) of the window to retrieve orders till that day for all timezone for created orders.
        created_at_date_without_tz:
          type:
          - string
          - 'null'
          description: Date (YYYY-MM-DD) used as a filter to retrieve orders that are created on a given date irrespective of timezone.
        driver_handle:
          type:
          - string
          - 'null'
          description: Unique customer provided identifier of the driver to used retrieve orders associated with the specified driver
          deprecated: true
        sort_direction:
          enum:
          - desc
          - asc
          description: String indicating the preferred sorting type
        fulfillment_attempt:
          type:
          - integer
          - 'null'
          description: Filter for fulfillment attempt number
        aggregate:
          type:
          - boolean
          - 'null'
          description: Flag to fetch order's aggregated data.
        limit:
          type:
          - integer
          - 'null'
          description: Limit to number of results in response
        pagination_token:
          type:
          - string
          - 'null'
          description: Encoded value provided by our API to retrieve the next page of orders
        send_outage:
          type:
          - boolean
          - 'null'
          description: Boolean to send the outage in aggregation
        tracking_status:
          type:
          - string
          - 'null'
          enum:
          - tracked
          - untracked
          description: Parameter to filter for tracked and untracked orders
        filter_outage_category:
          type:
          - string
          - 'null'
          description: List of outage category as comma separated strings used for filtering associated orders within time range
        worker_profile_filter:
          type:
          - string
          - 'null'
          format: Encoded JSON
          description: JSON encoded string metadata associated with the worker to filter orders
        worker_inside_destination:
          type:
          - boolean
          - 'null'
          description: Boolean flag to filter orders based on whether the worker is inside the destination or not.
        email_recipients:
          type: array
          description: Optional list of email addresses to send the export download link. Falls back to the account email when omitted.
          items:
            type: string
    OrderExportResponse:
      type: object
      properties:
        job_id:
          type: string
          description: Unique identifier for the export job
        status:
          type: string
          description: 'Current status of the export job: pending, processing, completed, failed'
        message:
          type: string
          description: Human-readable message about the job
      required:
      - job_id
      - message
      - status
    OrderExportStatusResponse:
      type: object
      properties:
        job_id:
          type: string
          description: Unique identifier for the export job
        status:
          type: string
          description: 'Current status: pending, processing, completed, failed'
        rows_processed:
          type: integer
          default: 0
          description: Number of rows processed so far
        presigned_url:
          type:
          - string
          - 'null'
          description: Presigned S3 URL to download the export (available when completed)
        error_message:
          type:
          - string
          - 'null'
          description: Error message if job failed
        created_at:
          type:
          - string
          - 'null'
          description: Job creation timestamp (ISO 8601)
        started_at:
          type:
          - string
          - 'null'
          description: Job start timestamp (ISO 8601)
        completed_at:
          type:
          - string
          - 'null'
          description: Job completion timestamp (ISO 8601)
      required:
      - job_id
      - status
    HTTPError:
      properties:
        detail:
          type: object
        message:
          type: string
      type: object
    ValidationError:
      properties:
        detail:
          type: object
          properties:
            <location>:
              type: object
              properties:
                <field_name>:
                  type: array
                  items:
                    type: string
        message:
          type: string
      type: object
    Error:
      type: object
      properties:
        code:
          type: string
          description: error code for the type of error
        title:
          type: string
          description: error title
        detail:
          type: string
          description: error detail
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    TokenAuth:
      type: http
      scheme: bearer
    BearerAuth:
      type: http
      scheme: bearer