openapi: 3.2.0
info:
  title: HyperTrack Worker 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: WorkerExport
paths:
  /workers/export:
    post:
      parameters: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerExportResponse'
          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:
      - WorkerExport
      summary: Create a worker export job
      description: Creates an asynchronous job to export workers 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/WorkerExportRequest'
      security:
      - BasicAuth: []
      - TokenAuth: []
  /workers/export/{job_id}:
    get:
      parameters:
      - in: path
        name: job_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerExportStatusResponse'
          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:
      - WorkerExport
      summary: Get worker export job status
      description: Check the status of a worker export job by job_id. Returns current status, progress, and download URL when completed.
      security:
      - BasicAuth: []
      - TokenAuth: []
components:
  schemas:
    WorkerExportResponse:
      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
    WorkerExportRequest:
      type: object
      properties:
        from_date:
          type:
          - string
          - 'null'
          description: 'ISO 8601 date format (''yyyy-MM-dd'') indicating the start date to be used for the summary computation.<br>Default: Current date in UTC.'
        to_date:
          type:
          - string
          - 'null'
          description: 'ISO 8601 date format (''yyyy-MM-dd'') indicating the end date to be used for the summary computation.<br>Default: Current date in UTC.'
        limit:
          type:
          - integer
          - 'null'
          default: 25
          description: Number of workers to be sent in response
        include_schedule:
          type: boolean
          default: true
          description: Flag to include worker's schedule in the response.
        include_summary:
          type: boolean
          default: true
          description: Flag to include worker's summary stats in the response.
        ops_group_handle:
          type:
          - string
          - 'null'
          description: List of ops group handles as comma separated strings used to filter workers.
        profile:
          type:
          - string
          - 'null'
          description: Profile filter to be applied on the list of workers
        worker_handle:
          type:
          - string
          - 'null'
          description: List of worker handles as comma separated strings used for fetching associated workers
        search_term:
          type:
          - string
          - 'null'
          description: Keyword to match against worker handle, name, or profile
        pagination_token:
          type:
          - string
          - 'null'
          description: Identifier used to fetch the next page of data
        device_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Unique identifier for a worker's device. This field is present in case the worker is currently linked with a device
        include_deleted:
          type: boolean
          default: false
          description: Flag to include deleted workers
        from_time:
          type:
          - string
          - 'null'
          format: date-time
          description: ISO 8601 datetime indicating the start time to be used for computing summary, status.
          deprecated: true
        to_time:
          type:
          - string
          - 'null'
          format: date-time
          description: ISO 8601 datetime indicating the end time to be used for computing summary, status.
          deprecated: true
        filter_outage:
          type:
          - string
          - 'null'
          description: Filter workers on a particular outage code.
        filter_outage_category:
          type:
          - string
          - 'null'
          description: 'List of comma separated outage categories to be used for filtering workers. Valid categories: `behavioural`,`adversarial`,`reachability`,`os`,`sporadic`'
        filter_geofence_metadata:
          type:
          - string
          - 'null'
          description: geofence_metadata filter for aggregate response
        aggregate:
          type: boolean
          default: false
          description: Flag set to retrieve aggregated data over the provided time range
        work_status:
          type:
          - string
          - 'null'
          description: URL-encoded json string specifying filters on availability or tracking.
        filter_status:
          type:
          - string
          - 'null'
          enum:
          - active
          - inactive
          - disconnected
          description: Only list workers that are currently active/inactive/disconnected.
        tracked:
          type:
          - boolean
          - 'null'
          description: If set to true, only shows workers that were actually tracked during the specified period.
        worked:
          type:
          - boolean
          - 'null'
          description: If set to true, only shows workers that actually during the specified period.
        intended_to_track:
          type:
          - boolean
          - 'null'
          description: If set to true, only shows workers that was supposed to be tracked during the specified period.
        include_lp:
          type:
          - boolean
          - 'null'
          default: false
          description: Flag to include location permission stats in response (only applicable when `aggregate=True`).
        region_filter:
          type:
          - string
          - 'null'
          description: URL-encoded JSON string used to filter workers from a particular region. Ex `{"city":"Detroit"}`
        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
    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
    WorkerExportStatusResponse:
      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
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    TokenAuth:
      type: http
      scheme: bearer
    BearerAuth:
      type: http
      scheme: bearer