---
title: "List all employees"
method: GET
path: "/quickbooks-desktop/employees"
---

# List all employees

`GET /quickbooks-desktop/employees`

Returns a list of employees.

**NOTE:** QuickBooks Desktop does not support pagination for employees; hence, there is no `cursor` parameter. Users typically have few employees.

## Query parameters

- `ids` string[] — Filter for specific employees by their QuickBooks-assigned unique identifier(s). **IMPORTANT**: If you include this parameter, QuickBooks will ignore all other query parameters for this request. **NOTE**: If any of the values you specify in this parameter are not found, the request will return an error.
- `names` string[] — Filter for specific employees by their name(s), case-insensitive. Like `id`, `name` is a unique identifier for an employee. **IMPORTANT**: If you include this parameter, QuickBooks will ignore all other query parameters for this request. **NOTE**: If any of the values you specify in this parameter are not found, the request will return an error.
- `limit` integer — The maximum number of objects to return. **IMPORTANT**: QuickBooks Desktop does not support cursor-based pagination for employees. This parameter will limit the response size, but you cannot fetch subsequent results using a cursor. For pagination, use the name-range parameters instead (e.g., `nameFrom=A&nameTo=B`). When this parameter is omitted, the endpoint returns all employees without limit, unlike paginated endpoints which default to 150 records. This is acceptable because employees typically have low record counts.
- `status` 'active' | 'all' | 'inactive' — Filter for employees that are active, inactive, or both.
- `updatedAfter` string — Filter for employees updated on or after this date/time. Accepts the following ISO 8601 formats: - **date-only** (YYYY-MM-DD) - QuickBooks Desktop interprets the date as the **start of the specified day** in the local timezone of the end-user's computer (e.g., `2025-01-01` → `2025-01-01T00:00:00`). - **datetime without timezone** (YYYY-MM-DDTHH:mm:ss) - QuickBooks Desktop interprets the timestamp in the local timezone of the end-user's computer. - **datetime with timezone** (YYYY-MM-DDTHH:mm:ss±HH:mm) - QuickBooks Desktop interprets the timestamp using the specified timezone.
- `updatedBefore` string — Filter for employees updated on or before this date/time. Accepts the following ISO 8601 formats: - **date-only** (YYYY-MM-DD) - QuickBooks Desktop interprets the date as the **end of the specified day** in the local timezone of the end-user's computer (e.g., `2025-01-01` → `2025-01-01T23:59:59`). - **datetime without timezone** (YYYY-MM-DDTHH:mm:ss) - QuickBooks Desktop interprets the timestamp in the local timezone of the end-user's computer. - **datetime with timezone** (YYYY-MM-DDTHH:mm:ss±HH:mm) - QuickBooks Desktop interprets the timestamp using the specified timezone.
- `nameContains` string — Filter for employees whose `name` contains this substring, case-insensitive. **NOTE**: If you use this parameter, you cannot also use `nameStartsWith` or `nameEndsWith`.
- `nameStartsWith` string — Filter for employees whose `name` starts with this substring, case-insensitive. **NOTE**: If you use this parameter, you cannot also use `nameContains` or `nameEndsWith`.
- `nameEndsWith` string — Filter for employees whose `name` ends with this substring, case-insensitive. **NOTE**: If you use this parameter, you cannot also use `nameContains` or `nameStartsWith`.
- `nameFrom` string — Filter for employees whose `name` is alphabetically greater than or equal to this value.
- `nameTo` string — Filter for employees whose `name` is alphabetically less than or equal to this value.

## Headers

- `Conductor-End-User-Id` string, required — The ID of the End-User to receive this request.

## Response `200`

Returns a list of employees.

- object
  - `objectType` 'list', required — The type of object. This value is always `"list"`.
  - `url` string, required — The endpoint URL where this list can be accessed.
  - `data` QbdEmployee[], required — The array of employees.
    - `id` string, required — The unique identifier assigned by QuickBooks to this employee. This ID is unique across all employees but not across different QuickBooks object types.
    - `objectType` 'qbd_employee', required — The type of object. This value is always `"qbd_employee"`.
    - `createdAt` string, required — The date and time when this employee was created, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm), which QuickBooks Desktop interprets in the local timezone of the end-user's computer.
    - `updatedAt` string, required — The date and time when this employee was last updated, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm), which QuickBooks Desktop interprets in the local timezone of the end-user's computer.
    - `revisionNumber` string, required — The current QuickBooks-assigned revision number of this employee object, which changes each time the object is modified. When updating this object, you must provide the most recent `revisionNumber` to ensure you're working with the latest data; otherwise, the update will return an error.
    - `name` string, required — The case-insensitive unique name of this employee, unique across all employees. A concatenation of the employee's `firstName`, `middleName`, and `lastName` fields. **NOTE**: Employees do not have a `fullName` field because they are not hierarchical objects, which is why `name` is unique for them but not for objects that have parents.
    - `isActive` boolean, required — Indicates whether this employee is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`.
    - `salutation` string, nullable, required — The employee's formal salutation title that precedes their name, such as "Mr.", "Ms.", or "Dr.".
    - `firstName` string, nullable, required — The employee's first name.
    - `middleName` string, nullable, required — The employee's middle name.
    - `lastName` string, nullable, required — The employee's last name.
    - `jobTitle` string, nullable, required — The employee's job title.
    - `supervisor` object, nullable, required — The employee's supervisor. Found in the "employment job details" section of the employee's record in QuickBooks.
      - `id` string, nullable, required — The unique identifier assigned by QuickBooks to this object. This ID is unique across all objects of the same type, but not across different QuickBooks object types.
      - `fullName` string, nullable, required — The fully-qualified unique name for this object, formed by combining the names of its parent objects with its own `name`, separated by colons. Not case-sensitive.
    - `department` string, nullable, required — The employee's department. Found in the "employment job details" section of the employee's record in QuickBooks.
    - `description` string, nullable, required — A description of this employee. Found in the "employment job details" section of the employee's record in QuickBooks.
    - `targetBonus` string, nullable, required — The target bonus for this employee, represented as a decimal string. Found in the "employment job details" section of the employee's record in QuickBooks.
    - `address` QbdEmployeeAddress, required
      - `line1` string, nullable, required — The first line of the employee address (e.g., street, PO Box, or company name).
      - `line2` string, nullable, required — The second line of the employee address, if needed (e.g., apartment, suite, unit, or building).
      - `line3` string, nullable, required — The third line of the employee address, if needed.
      - `line4` string, nullable, required — The fourth line of the employee address, if needed.
      - `city` string, nullable, required — The city, district, suburb, town, or village name of the employee address.
      - `state` string, nullable, required — The U.S. state or Canadian province of the employee address. QuickBooks requires this field to be a two-letter abbreviation (e.g., "CA" for California or "ON" for Ontario). See enum for all possible values. QuickBooks may reject values that the connected company file's edition does not support (e.g., a Canadian province on a U.S. company file). **NOTE:** This `state` field stays enum-constrained when creating or updating an employee, but we've seen QuickBooks return values outside its own enum in responses, so Conductor surfaces the raw QuickBooks string unchanged instead of enforcing the enum.
      - `postalCode` string, nullable, required — The postal code or ZIP code of the employee address.
      - `country` string, nullable, required — The country name of the employee address.
    - `printAs` string, nullable, required — The name to use when printing this employee from QuickBooks. By default, this is the same as the `name` field.
    - `phone` string, nullable, required — The employee's primary telephone number.
    - `mobile` string, nullable, required — The employee's mobile phone number.
    - `pager` string, nullable, required — The employee's pager number.
    - `pagerPin` string, nullable, required — The employee's pager PIN.
    - `alternatePhone` string, nullable, required — The employee's alternate telephone number.
    - `fax` string, nullable, required — The employee's fax number.
    - `ssn` string, nullable, required — The employee's Social Security Number. The value can be with or without dashes. **NOTE**: This field cannot be changed after the employee is created.
    - `email` string, nullable, required — The employee's email address.
    - `customContactFields` QbdCustomContactField[], required — Additional custom contact fields for this employee, such as phone numbers or email addresses.
      - `name` string, required — The name of the contact field (e.g., "old address", "secondary phone").
      - `value` string, nullable, required — The value of the contact field.
    - `emergencyContact` QbdEmergencyContactSet, required
      - `primaryContact` QbdEmergencyContact, required
        - `name` string, required — The name of the contact field (e.g., "old address", "secondary phone").
        - `value` string, nullable, required — The value of the contact field.
        - `relation` 'brother' | 'daughter' | 'father' | 'friend' | 'mother' | 'other' | 'partner' | 'sister' | 'son' | 'spouse', nullable, required — The relationship of the employee to the employee.
      - `secondaryContact` QbdEmergencyContact, required
        - `name` string, required — The name of the contact field (e.g., "old address", "secondary phone").
        - `value` string, nullable, required — The value of the contact field.
        - `relation` 'brother' | 'daughter' | 'father' | 'friend' | 'mother' | 'other' | 'partner' | 'sister' | 'son' | 'spouse', nullable, required — The relationship of the employee to the employee.
    - `employeeType` 'officer' | 'owner' | 'regular' | 'statutory', nullable, required — The employee type. This affects payroll taxes - a statutory employee is defined as an employee by statute. Note that owners/partners are typically on the "Other Names" list in QuickBooks, but if listed as an employee their type will be `owner`.
    - `employmentStatus` 'full_time' | 'part_time', nullable, required — Indicates whether this employee is a part-time or full-time employee.
    - `overtimeExemptStatus` 'exempt' | 'non_exempt', nullable, required — Indicates whether this employee is exempt from overtime pay. This classification is based on U.S. labor laws (FLSA).
    - `keyEmployeeStatus` 'key_employee' | 'non_key_employee', nullable, required — Indicates whether this employee is a key employee.
    - `gender` 'male' | 'female', nullable, required — This employee's gender.
    - `hiredDate` string, date, nullable, required — The date this employee was hired, in ISO 8601 format (YYYY-MM-DD).
    - `originalHireDate` string, date, nullable, required — The original hire date for this employee, in ISO 8601 format (YYYY-MM-DD).
    - `adjustedServiceDate` string, date, nullable, required — The adjusted service date for this employee, in ISO 8601 format (YYYY-MM-DD). This date accounts for previous employment periods or leaves that affect seniority.
    - `terminationDate` string, date, nullable, required — The date this employee's employment ended with the company, in ISO 8601 format (YYYY-MM-DD). This is also known as the released date or separation date.
    - `birthDate` string, date, nullable, required — This employee's date of birth, in ISO 8601 format (YYYY-MM-DD).
    - `usCitizenshipStatus` 'citizen' | 'non_citizen', nullable, required — Indicates whether this employee is a U.S. citizen.
    - `ethnicity` 'american_indian' | 'asian' | 'black' | 'hawaiian' | 'hispanic' | 'white' | 'two_or_more_races', nullable, required — This employee's ethnicity.
    - `disabilityStatus` 'disabled' | 'non_disabled', nullable, required — Indicates whether this employee is disabled.
    - `disabilityDescription` string, nullable, required — A description of this employee's disability.
    - `i9OnFileStatus` 'on_file' | 'not_on_file', nullable, required — Indicates whether this employee's I-9 is on file.
    - `workAuthorizationExpirationDate` string, date, nullable, required — The date this employee's work authorization expires, in ISO 8601 format (YYYY-MM-DD).
    - `usVeteranStatus` 'veteran' | 'non_veteran', nullable, required — Indicates whether this employee is a U.S. veteran.
    - `militaryStatus` 'active' | 'reserve', nullable, required — This employee's military status if they are a U.S. veteran.
    - `accountNumber` string, nullable, required — The employee's account number, which appears in the QuickBooks chart of accounts, reports, and graphs. Note that if the "Use Account Numbers" preference is turned off in QuickBooks, the account number may not be visible in the user interface, but it can still be set and retrieved through the API.
    - `note` string, nullable, required — A note or comment about this employee.
    - `additionalNotes` QbdNote[], required — Additional notes about this employee.
      - `id` number, required — The auto-incrementing identifier assigned by QuickBooks to this note.
      - `date` string, date, nullable, required — The date this note was last updated, in ISO 8601 format (YYYY-MM-DD).
      - `note` string, required — The text of this note.
    - `billingRate` object, nullable, required — The employee's billing rate, used to override service item rates in time tracking activities.
      - `id` string, nullable, required — The unique identifier assigned by QuickBooks to this object. This ID is unique across all objects of the same type, but not across different QuickBooks object types.
      - `fullName` string, nullable, required — The fully-qualified unique name for this object, formed by combining the names of its parent objects with its own `name`, separated by colons. Not case-sensitive.
    - `employeePayroll` QbdEmployeePayrollInfo, required
      - `payPeriod` 'biweekly' | 'daily' | 'monthly' | 'quarterly' | 'semimonthly' | 'weekly' | 'yearly', nullable, required — How frequently this employee is paid (e.g., weekly, biweekly, monthly). This determines the schedule for generating paychecks.
      - `class` object, nullable, required — The employee's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.
        - `id` string, nullable, required — The unique identifier assigned by QuickBooks to this object. This ID is unique across all objects of the same type, but not across different QuickBooks object types.
        - `fullName` string, nullable, required — The fully-qualified unique name for this object, formed by combining the names of its parent objects with its own `name`, separated by colons. Not case-sensitive.
      - `earnings` QbdEarnings[], required — The employee's earnings.
        - `payrollWageItem` object, required — The payroll wage item that defines how this employee is paid (e.g., Regular Pay, Overtime Pay). This determines the payment scheme used for payroll calculations.
          - `id` string, nullable, required — The unique identifier assigned by QuickBooks to this object. This ID is unique across all objects of the same type, but not across different QuickBooks object types.
          - `fullName` string, nullable, required — The fully-qualified unique name for this object, formed by combining the names of its parent objects with its own `name`, separated by colons. Not case-sensitive.
        - `rate` string, nullable, required — The hourly rate for this employee, represented as a decimal string.
        - `ratePercent` string, nullable, required — The hourly rate for this employee expressed as a percentage.
      - `useTimeDataToCreatePaychecks` 'does_not_use_time_data' | 'not_set' | 'uses_time_data', nullable, required — Indicates whether this employee is using time-tracking data to create paychecks.
      - `sickHours` QbdSickHours, required
        - `hoursAvailable` string, nullable, required — The total number of sick hours currently available for the employee to use, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M. Defaults to 0.
        - `accrualPeriod` 'accrues_annually' | 'accrues_hourly' | 'accrues_per_paycheck', nullable, required — How frequently the employee's sick hours are accrued.
        - `hoursAccruedPerPeriod` string, nullable, required — The number of sick hours the employee will accrue per accrual period, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.
        - `maximumHours` string, nullable, required — The maximum number of sick hours the employee can accrue, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.
        - `resetsHoursEachYear` boolean, nullable, required — Indicates whether the employee's sick hours reset to zero at the beginning of the new year.
        - `hoursUsed` string, nullable, required — The number of sick hours the employee has used, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.
        - `accrualStartDate` string, date, nullable, required — The date the employee's sick hours began to accrue, in ISO 8601 format (YYYY-MM-DD).
      - `vacationHours` QbdVacationHours, required
        - `hoursAvailable` string, nullable, required — The total number of vacation hours currently available for the employee to use, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M. Defaults to 0.
        - `accrualPeriod` 'accrues_annually' | 'accrues_hourly' | 'accrues_per_paycheck', nullable, required — How frequently the employee's vacation hours are accrued.
        - `hoursAccruedPerPeriod` string, nullable, required — The number of vacation hours the employee will accrue per accrual period, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.
        - `maximumHours` string, nullable, required — The maximum number of vacation hours the employee can accrue, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.
        - `resetsHoursEachYear` boolean, nullable, required — Indicates whether the employee's vacation hours reset to zero at the beginning of the new year.
        - `hoursUsed` string, nullable, required — The number of vacation hours the employee has used, in ISO 8601 format for time intervals (PTnHnMnS). For example, 1 hour and 30 minutes is represented as PT1H30M.
        - `accrualStartDate` string, date, nullable, required — The date the employee's vacation hours began to accrue, in ISO 8601 format (YYYY-MM-DD).
    - `externalId` string, nullable, required — A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.
    - `customFields` QbdCustomField[], required — The custom fields for the employee object, added as user-defined data extensions, not included in the standard QuickBooks object.
      - `ownerId` string, required — The identifier of the owner of the custom field, which QuickBooks internally calls a "data extension". For public custom fields visible in the UI, such as those added by the QuickBooks user, this is always "0". For private custom fields that are only visible to the application that created them, this is a valid GUID identifying the owning application. Internally, Conductor always fetches all public custom fields (those with an `ownerId` of "0") for all objects.
      - `name` string, required — The name of the custom field, unique for the specified `ownerId`. For public custom fields, this name is visible as a label in the QuickBooks UI.
      - `type` 'amount_type' | 'date_time_type' | 'integer_type' | 'percent_type' | 'price_type' | 'quantity_type' | 'string_1024_type' | 'string_255_type', required — The data type of this custom field.
      - `value` string, required — The value of this custom field. The maximum length depends on the field's data type.

---

[API](https://skmtc.net/conductor-is/apis/conductor-api.md) · [All operations](https://skmtc.net/conductor-is/apis/conductor-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/conductor-is/conductor-api/revisions/0b07b3ebe160/schema)