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

# Get Workers

> Returns all workers matching the specified filters along with a totals breakdown by account status. This endpoint is not paginated — all matching workers are returned in a single response.

<Info>
  This endpoint returns **all** workers matching your filters in a single response — it is not paginated. The response includes a `totals` object with a breakdown of worker counts by account status (`activeTotal`, `inactiveTotal`, `pendingTotal`, `firstLoginTotal`, `onboardingTotal`, `allTotal`).
</Info>

<Tip>
  **Custom fields filter** — To filter by a custom field, use the query parameter format `customFields[{id}]={field_type}|{comparator}|{value}`. For example, `customFields[116]=dropdown|is|some_value` filters by custom field 116 (a dropdown) where the value equals `some_value`. Comparators vary by field type: text fields support basic matching, date fields support `is_before`, `is_after`, and `is`, and dropdown fields support `is`.
</Tip>


## OpenAPI

````yaml api-reference/v01.12.00/openapi-v01.12.00.json GET /workers
openapi: 3.0.0
info:
  title: Roosted
  version: 0.1.12
  contact:
    name: Support
    url: https://support.roostedhr.com/support/home
    email: support@roostedhr.com
  description: |-
    Enterprise API

    Sandbox keys and Production keys are requested from support
servers:
  - url: https://api.roostedhr.com/api/1_12
  - url: https://sandbox.roostedhr.com/api/1_12
security:
  - X-API-KEY: []
tags:
  - name: Announcements
  - name: Areas
  - name: Clients
  - name: Company
  - name: Configuration
  - name: Events
  - name: Locations
  - name: Payroll Groups
  - name: Rate Cards
  - name: Shifts
  - name: Skillsets
  - name: Time Tracking
  - name: Wage Rules
  - name: Workers
paths:
  /workers:
    parameters: []
    get:
      tags:
        - Workers
      summary: Get Workers
      description: >-
        Returns all workers matching the specified filters along with a totals
        breakdown by account status. This endpoint is not paginated — all
        matching workers are returned in a single response.
      operationId: get-workers
      parameters:
        - name: workerStatus
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Filter by account status: `0` = pending, `1` = active, `2` =
            inactivated, `3` = all
        - name: areas
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated area IDs to filter by
        - name: skillsets
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated skillset IDs to filter by
        - name: tags
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated tag IDs to filter by
        - name: customFields
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated custom field filter values
        - name: workerCreated
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter by worker signup date (ISO 8601 format)
        - name: workerCreatedOperator
          in: query
          required: false
          schema:
            type: string
            enum:
              - is_before
              - is_after
              - is
          description: Comparator for the `workerCreated` filter
        - name: nextWorking
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter by next scheduled shift date (ISO 8601 format)
        - name: nextWorkingOperator
          in: query
          required: false
          schema:
            type: string
            enum:
              - is_before
              - is_after
              - is
          description: Comparator for the `nextWorking` filter
        - name: nextWorkingHasOperator
          in: query
          required: false
          schema:
            type: string
            enum:
              - has
              - does_not_have
          description: Filter by whether the worker has a next scheduled shift
        - name: lastShift
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter by last shift date (ISO 8601 format)
        - name: lastShiftOperator
          in: query
          required: false
          schema:
            type: string
            enum:
              - is_before
              - is_after
              - is
          description: Comparator for the `lastShift` filter
        - name: lastShiftHasOperator
          in: query
          required: false
          schema:
            type: string
            enum:
              - has
              - does_not_have
          description: Filter by whether the worker has a recorded last shift
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  workers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Worker'
                    description: Array of worker objects matching the filters
                  totals:
                    $ref: '#/components/schemas/WorkerTotals'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Machine-readable error code.
                  error:
                    type: string
                    description: Human-readable error message.
              examples:
                Worker name is required:
                  value:
                    code: WRK-100
                    error: Worker name is required
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Machine-readable error code.
                  error:
                    type: string
                    description: Human-readable error message.
              examples:
                Invalid or missing API key:
                  value:
                    code: ATH-100
                    error: Invalid or missing API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Machine-readable error code.
                  error:
                    type: string
                    description: Human-readable error message.
              examples:
                Insufficient permissions to list workers:
                  value:
                    code: WRK-800
                    error: Insufficient permissions to list workers
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Machine-readable error code.
                  error:
                    type: string
                    description: Human-readable error message.
              examples:
                Worker not found:
                  value:
                    code: WRK-300
                    error: Worker not found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Machine-readable error code.
                  error:
                    type: string
                    description: Human-readable error message.
              examples:
                Failed to create worker:
                  value:
                    code: WRK-200
                    error: Failed to create worker
components:
  schemas:
    Worker:
      type: object
      description: >-
        A worker profile with personal information, status flags, and assigned
        skillsets/areas.
      properties:
        id:
          type: string
          description: Worker identifier
        reference_id:
          type: string
          description: External reference identifier
        signup_date:
          type: string
          description: Formatted signup date (e.g. "September 28th 2019")
        signup_date_original:
          type: string
          description: Raw signup timestamp (YYYY-MM-DD HH:mm:ss)
        last_login:
          type: string
          nullable: true
          description: Formatted last login date
        last_login_original:
          type: string
          nullable: true
          description: Raw last login timestamp
        next_shift_date:
          type: string
          nullable: true
          description: Formatted next scheduled shift date
        next_shift_date_original:
          type: string
          nullable: true
          description: Raw next shift timestamp
        last_shift_date:
          type: string
          nullable: true
          description: Formatted last shift date
        last_shift_date_original:
          type: string
          nullable: true
          description: Raw last shift timestamp
        account_status:
          type: integer
          enum:
            - 0
            - 2
            - 86
          description: 'Worker account status: `0` = pending, `2` = active, `86` = inactive'
        name_first:
          type: string
          description: Worker's first name
        email:
          type: string
          nullable: true
          description: Worker's email address
        phone:
          type: string
          nullable: true
          description: Worker's phone number
        address:
          type: string
          description: Street address
        city:
          type: string
          description: City
        zip:
          type: string
          description: ZIP/postal code
        country_id:
          type: number
          description: Country identifier
        areas:
          type: array
          items:
            $ref: '#/components/schemas/WorkerArea'
          description: Areas assigned to this worker
        bad_phone_number:
          type: integer
          enum:
            - 0
            - 1
          description: Whether the phone number is flagged as bad
        texting_off:
          type: integer
          nullable: true
          enum:
            - 0
            - 1
          description: Whether texting is disabled for this worker
        latitude:
          type: string
          nullable: true
          description: Worker's latitude coordinate
        longitude:
          type: string
          nullable: true
          description: Worker's longitude coordinate
        multilogin:
          type: integer
          enum:
            - 0
            - 1
          description: Whether multi-login is enabled
        onboarded:
          type: integer
          enum:
            - 0
            - 1
          description: Whether the worker has completed onboarding
        app_notifications_active:
          type: integer
          enum:
            - 0
            - 1
          description: Whether app notifications are active
        app_notifications_preferred:
          type: integer
          nullable: true
          enum:
            - 0
            - 1
          description: Whether app notifications are the preferred method
        current_worker:
          type: integer
          enum:
            - 0
            - 1
          description: Whether this is a current worker
        admin:
          type: integer
          enum:
            - 0
            - 1
          description: Whether the worker has admin privileges
        owner:
          type: integer
          enum:
            - 0
            - 1
          description: Whether the worker is an owner
        selected:
          type: string
          nullable: true
          description: Selection state
        selected_picture_location:
          type: string
          nullable: true
          description: Profile picture path
        pending_document_signing_count:
          type: integer
          description: Number of documents awaiting the worker's signature
        total_shifts:
          type: string
          description: Total number of shifts worked
        last_noshow:
          type: string
          nullable: true
          description: Date of last no-show, if any
        no_id:
          type: boolean
          description: Whether the worker lacks an ID on file
        stars:
          type: integer
          nullable: true
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
          description: Worker star rating (1–5)
        skillsets:
          type: array
          items:
            $ref: '#/components/schemas/WorkerSkillset'
          description: Skillsets assigned to this worker
        pullTimestamp:
          type: integer
          description: Unix timestamp of when this data was retrieved
    WorkerTotals:
      type: object
      description: Breakdown of worker counts by account status.
      properties:
        pendingTotal:
          type: integer
          description: Number of workers with pending status
        activeTotal:
          type: integer
          description: Number of active workers
        inactiveTotal:
          type: integer
          description: Number of inactive workers
        firstLoginTotal:
          type: integer
          description: Number of workers awaiting first login
        onboardingTotal:
          type: integer
          description: Number of workers in onboarding
        allTotal:
          type: integer
          description: Total number of workers across all statuses
    WorkerArea:
      type: object
      description: Area assigned to a worker.
      properties:
        id:
          type: string
          description: Area identifier
        name:
          type: string
          description: Area display name
    WorkerSkillset:
      type: object
      description: Skillset assigned to a worker.
      properties:
        roles_id:
          type: string
          description: Skillset identifier
        role_title:
          type: string
          description: Skillset display name
  securitySchemes:
    X-API-KEY:
      name: X-API-KEY
      type: apiKey
      in: header

````