> ## Documentation Index > Fetch the complete documentation index at: https://docs.conductor.is/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve an employee > Retrieves an employee by ID. **IMPORTANT:** If you need to fetch multiple specific employees by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster. ## OpenAPI ````yaml GET /quickbooks-desktop/employees/{id} openapi: 3.1.0 info: title: Conductor API version: 0.0.1 servers: - url: https://api.conductor.is/v1 security: - BearerAuth: [] paths: /quickbooks-desktop/employees/{id}: get: summary: Retrieve an employee description: >- Retrieves an employee by ID. **IMPORTANT:** If you need to fetch multiple specific employees by ID, use the list endpoint instead with the `ids` parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster. parameters: - in: path name: id description: >- The QuickBooks-assigned unique identifier of the employee to retrieve. schema: type: string description: >- The QuickBooks-assigned unique identifier of the employee to retrieve. example: 80000001-1234567890 required: true - in: header name: Conductor-End-User-Id description: The ID of the End-User to receive this request. schema: type: string description: The ID of the End-User to receive this request. example: end_usr_1234567abcdefg x-stainless-naming: typescript: method_argument: conductorEndUserId mcp: method_argument: conductorEndUserId required: true responses: '200': description: Returns the specified employee. headers: Conductor-Request-Id: schema: type: string description: The unique identifier for this API request. example: req_1234567abcdefg required: true content: application/json: schema: $ref: '#/components/schemas/qbd_employee' security: - BearerAuth: [] x-codeSamples: - lang: JavaScript source: >- import Conductor from 'conductor-node'; const conductor = new Conductor({ apiKey: process.env['CONDUCTOR_SECRET_KEY'], // This is the default and can be omitted }); const employee = await conductor.qbd.employees.retrieve('80000001-1234567890', { conductorEndUserId: 'end_usr_1234567abcdefg', }); console.log(employee.id); - lang: Python source: |- import os from conductor import Conductor conductor = Conductor( api_key=os.environ.get("CONDUCTOR_SECRET_KEY"), # This is the default and can be omitted ) employee = conductor.qbd.employees.retrieve( id="80000001-1234567890", conductor_end_user_id="end_usr_1234567abcdefg", ) print(employee.id) components: schemas: qbd_employee: type: object properties: id: type: string description: >- The unique identifier assigned by QuickBooks to this employee. This ID is unique across all employees but not across different QuickBooks object types. example: 80000001-1234567890 objectType: type: string const: qbd_employee description: The type of object. This value is always `"qbd_employee"`. example: qbd_employee createdAt: type: string description: >- 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. example: '2025-01-01T12:34:56.000Z' updatedAt: type: string description: >- 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. example: '2025-02-01T12:34:56.000Z' revisionNumber: type: string description: >- 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. example: '1721172183' name: type: string description: >- 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. example: John Doe isActive: type: boolean description: >- Indicates whether this employee is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`. example: true salutation: type: - string - 'null' description: >- The employee's formal salutation title that precedes their name, such as "Mr.", "Ms.", or "Dr.". example: Dr. firstName: type: - string - 'null' description: The employee's first name. example: John middleName: type: - string - 'null' description: The employee's middle name. example: A. lastName: type: - string - 'null' description: The employee's last name. example: Doe jobTitle: type: - string - 'null' description: The employee's job title. example: Purchasing Manager supervisor: type: - object - 'null' properties: id: type: - string - 'null' description: >- 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. example: 80000001-1234567890 fullName: type: - string - 'null' description: >- 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. example: Parent:Child:Grandchild required: - id - fullName additionalProperties: false description: >- The employee's supervisor. Found in the "employment job details" section of the employee's record in QuickBooks. example: id: 80000001-1234567890 fullName: John Doe department: type: - string - 'null' description: >- The employee's department. Found in the "employment job details" section of the employee's record in QuickBooks. example: Sales description: type: - string - 'null' description: >- A description of this employee. Found in the "employment job details" section of the employee's record in QuickBooks. example: This employee is a key employee. targetBonus: type: - string - 'null' description: >- 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. example: '10000.00' address: oneOf: - $ref: '#/components/schemas/qbd_employee_address' - type: 'null' description: >- The employee's address. If the company uses QuickBooks Payroll for this employee, this address must specify a complete address, including city, state, ZIP (or postal) code, and at least one line of the street address. printAs: type: - string - 'null' description: >- The name to use when printing this employee from QuickBooks. By default, this is the same as the `name` field. example: John Doe phone: type: - string - 'null' description: The employee's primary telephone number. example: +1-555-123-4567 mobile: type: - string - 'null' description: The employee's mobile phone number. example: +1-555-555-1212 pager: type: - string - 'null' description: The employee's pager number. example: +1-555-555-1212 pagerPin: type: - string - 'null' description: The employee's pager PIN. example: '1234' alternatePhone: type: - string - 'null' description: The employee's alternate telephone number. example: +1-555-987-6543 fax: type: - string - 'null' description: The employee's fax number. example: +1-555-555-1212 ssn: type: - string - 'null' description: >- 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. example: 123-45-6789 email: type: - string - 'null' description: The employee's email address. example: employee@example.com customContactFields: type: array items: $ref: '#/components/schemas/qbd_custom_contact_field' description: >- Additional custom contact fields for this employee, such as phone numbers or email addresses. emergencyContact: oneOf: - $ref: '#/components/schemas/qbd_emergency_contact_set' - type: 'null' description: The employee's emergency contacts. employeeType: type: - string - 'null' enum: - officer - owner - regular - statutory - null description: >- 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`. example: regular employmentStatus: type: - string - 'null' enum: - full_time - part_time - null description: >- Indicates whether this employee is a part-time or full-time employee. example: full_time overtimeExemptStatus: type: - string - 'null' enum: - exempt - non_exempt - null description: > Indicates whether this employee is exempt from overtime pay. This classification is based on U.S. labor laws (FLSA). example: exempt keyEmployeeStatus: type: - string - 'null' enum: - key_employee - non_key_employee - null description: Indicates whether this employee is a key employee. example: key_employee gender: type: - string - 'null' enum: - male - female - null description: This employee's gender. example: male hiredDate: type: - string - 'null' format: date description: The date this employee was hired, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01' originalHireDate: type: - string - 'null' format: date description: >- The original hire date for this employee, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01' adjustedServiceDate: type: - string - 'null' format: date description: >- 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. example: '2024-01-01' terminationDate: type: - string - 'null' format: date description: >- 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. example: '2024-01-01' birthDate: type: - string - 'null' format: date description: This employee's date of birth, in ISO 8601 format (YYYY-MM-DD). example: '1990-01-01' usCitizenshipStatus: type: - string - 'null' enum: - citizen - non_citizen - null description: Indicates whether this employee is a U.S. citizen. example: citizen ethnicity: type: - string - 'null' enum: - american_indian - asian - black - hawaiian - hispanic - white - two_or_more_races - null description: This employee's ethnicity. example: asian disabilityStatus: type: - string - 'null' enum: - disabled - non_disabled - null description: Indicates whether this employee is disabled. example: disabled disabilityDescription: type: - string - 'null' description: A description of this employee's disability. example: Cerebral Palsy i9OnFileStatus: type: - string - 'null' enum: - on_file - not_on_file - null description: Indicates whether this employee's I-9 is on file. example: on_file workAuthorizationExpirationDate: type: - string - 'null' format: date description: >- The date this employee's work authorization expires, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01' usVeteranStatus: type: - string - 'null' enum: - veteran - non_veteran - null description: Indicates whether this employee is a U.S. veteran. example: veteran militaryStatus: type: - string - 'null' enum: - active - reserve - null description: This employee's military status if they are a U.S. veteran. example: active accountNumber: type: - string - 'null' description: >- 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. example: '1010' note: type: - string - 'null' description: A note or comment about this employee. example: This employee is a key employee. additionalNotes: type: array items: $ref: '#/components/schemas/qbd_note' description: Additional notes about this employee. billingRate: type: - object - 'null' properties: id: type: - string - 'null' description: >- 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. example: 80000001-1234567890 fullName: type: - string - 'null' description: >- 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. example: Parent:Child:Grandchild required: - id - fullName additionalProperties: false description: >- The employee's billing rate, used to override service item rates in time tracking activities. example: id: 80000001-1234567890 fullName: Standard Rate employeePayroll: oneOf: - $ref: '#/components/schemas/qbd_employee_payroll_info' - type: 'null' description: The employee's payroll information. externalId: type: - string - 'null' description: >- 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. example: 12345678-abcd-1234-abcd-1234567890ab customFields: type: array items: $ref: '#/components/schemas/qbd_custom_field' description: >- The custom fields for the employee object, added as user-defined data extensions, not included in the standard QuickBooks object. required: - id - objectType - createdAt - updatedAt - revisionNumber - name - isActive - salutation - firstName - middleName - lastName - jobTitle - supervisor - department - description - targetBonus - address - printAs - phone - mobile - pager - pagerPin - alternatePhone - fax - ssn - email - customContactFields - emergencyContact - employeeType - employmentStatus - overtimeExemptStatus - keyEmployeeStatus - gender - hiredDate - originalHireDate - adjustedServiceDate - terminationDate - birthDate - usCitizenshipStatus - ethnicity - disabilityStatus - disabilityDescription - i9OnFileStatus - workAuthorizationExpirationDate - usVeteranStatus - militaryStatus - accountNumber - note - additionalNotes - billingRate - employeePayroll - externalId - customFields additionalProperties: false title: The Employee object x-conductor-object-type: other summary: >- An employee represents a person employed by the company. It stores personal information, employment details, and payroll data used for personnel management and payroll processing. qbd_employee_address: type: object properties: line1: type: - string - 'null' description: >- The first line of the employee address (e.g., street, PO Box, or company name). example: Conductor Labs Inc. line2: type: - string - 'null' description: >- The second line of the employee address, if needed (e.g., apartment, suite, unit, or building). example: 540 Market St. line3: type: - string - 'null' description: The third line of the employee address, if needed. example: Suite 100 line4: type: - string - 'null' description: The fourth line of the employee address, if needed. example: '' city: type: - string - 'null' description: >- The city, district, suburb, town, or village name of the employee address. example: San Francisco state: type: - string - 'null' description: >- The U.S. state of the employee address. QuickBooks requires this field to be a U.S. state abbreviation (e.g., "CA" for California). See enum for all possible values. **NOTE:** This `state` field stays enum-constrained when creating or updating an employee because QuickBooks Desktop rejects non-standard values on input. In responses, though, we've seen QuickBooks return values outside its own enum (like 'ON'), so Conductor surfaces the raw QuickBooks string unchanged instead of enforcing the enum. example: CA postalCode: type: - string - 'null' description: The postal code or ZIP code of the employee address. example: '94110' country: type: - string - 'null' description: The country name of the employee address. example: United States required: - line1 - line2 - line3 - line4 - city - state - postalCode - country additionalProperties: false title: The Employee Address object x-conductor-object-type: nested qbd_custom_contact_field: type: object properties: name: type: string description: >- The name of the contact field (e.g., "old address", "secondary phone"). example: Main Phone value: type: - string - 'null' description: The value of the contact field. example: 555-123-4567 required: - name - value additionalProperties: false title: The Custom Contact Field object x-conductor-object-type: nested qbd_emergency_contact_set: type: object properties: primaryContact: oneOf: - $ref: '#/components/schemas/qbd_emergency_contact' - type: 'null' description: The employee's primary emergency contact. secondaryContact: oneOf: - $ref: '#/components/schemas/qbd_emergency_contact' - type: 'null' description: The employee's secondary emergency contact. required: - primaryContact - secondaryContact additionalProperties: false title: The Emergency Contacts object x-conductor-object-type: nested qbd_note: type: object properties: id: type: number description: >- The auto-incrementing identifier assigned by QuickBooks to this note. example: 1 date: type: - string - 'null' format: date description: >- The date this note was last updated, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01' note: type: string description: The text of this note. example: This is a fun note. required: - id - date - note additionalProperties: false title: The Note object x-conductor-object-type: nested qbd_employee_payroll_info: type: object properties: payPeriod: type: - string - 'null' enum: - biweekly - daily - monthly - quarterly - semimonthly - weekly - yearly - null description: >- How frequently this employee is paid (e.g., weekly, biweekly, monthly). This determines the schedule for generating paychecks. example: weekly class: type: - object - 'null' properties: id: type: - string - 'null' description: >- 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. example: 80000001-1234567890 fullName: type: - string - 'null' description: >- 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. example: Parent:Child:Grandchild required: - id - fullName additionalProperties: false description: >- 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. example: id: 80000001-1234567890 fullName: Payroll earnings: type: array items: $ref: '#/components/schemas/qbd_earnings' description: The employee's earnings. useTimeDataToCreatePaychecks: type: - string - 'null' enum: - does_not_use_time_data - not_set - uses_time_data - null description: >- Indicates whether this employee is using time-tracking data to create paychecks. example: uses_time_data sickHours: oneOf: - $ref: '#/components/schemas/qbd_sick_hours' - type: 'null' description: >- The employee's sick hours, including how sick time is accrued and the total hours accrued. vacationHours: oneOf: - $ref: '#/components/schemas/qbd_vacation_hours' - type: 'null' description: >- The employee's vacation hours, including how vacation time is accrued and the total hours accrued. required: - payPeriod - class - earnings - useTimeDataToCreatePaychecks - sickHours - vacationHours additionalProperties: false title: The Employee Payroll Info object x-conductor-object-type: nested qbd_custom_field: type: object properties: ownerId: type: string description: >- 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. example: '0' name: type: string description: >- 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. example: Customer Rating type: type: string enum: - amount_type - date_time_type - integer_type - percent_type - price_type - quantity_type - string_1024_type - string_255_type description: The data type of this custom field. example: string_1024_type value: type: string description: >- The value of this custom field. The maximum length depends on the field's data type. example: Premium required: - ownerId - name - type - value additionalProperties: false title: The Custom Field object x-conductor-object-type: nested qbd_emergency_contact: type: object properties: name: type: string description: >- The name of the contact field (e.g., "old address", "secondary phone"). example: Main Phone value: type: - string - 'null' description: The value of the contact field. example: 555-123-4567 relation: type: - string - 'null' enum: - brother - daughter - father - friend - mother - other - partner - sister - son - spouse - null description: The relationship of the employee to the employee. example: spouse required: - name - value - relation additionalProperties: false title: The Emergency Contact object x-conductor-object-type: nested qbd_earnings: type: object properties: payrollWageItem: type: object properties: id: type: - string - 'null' description: >- 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. example: 80000001-1234567890 fullName: type: - string - 'null' description: >- 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. example: Parent:Child:Grandchild required: - id - fullName additionalProperties: false description: >- 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. example: id: 80000001-1234567890 fullName: Regular Pay rate: type: - string - 'null' description: The hourly rate for this employee, represented as a decimal string. example: '10.00' ratePercent: type: - string - 'null' description: The hourly rate for this employee expressed as a percentage. example: '10.5' required: - payrollWageItem - rate - ratePercent additionalProperties: false title: The Earnings object x-conductor-object-type: nested qbd_sick_hours: type: object properties: hoursAvailable: type: - string - 'null' description: >- 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. example: PT8H30M accrualPeriod: type: - string - 'null' enum: - accrues_annually - accrues_hourly - accrues_per_paycheck - null description: How frequently the employee's sick hours are accrued. example: accrues_per_paycheck hoursAccruedPerPeriod: type: - string - 'null' description: >- 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. example: PT8H0M maximumHours: type: - string - 'null' description: >- 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. example: PT80H0M resetsHoursEachYear: type: - boolean - 'null' description: >- Indicates whether the employee's sick hours reset to zero at the beginning of the new year. example: false hoursUsed: type: - string - 'null' description: >- 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. example: PT2H45M accrualStartDate: type: - string - 'null' format: date description: >- The date the employee's sick hours began to accrue, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01' required: - hoursAvailable - accrualPeriod - hoursAccruedPerPeriod - maximumHours - resetsHoursEachYear - hoursUsed - accrualStartDate additionalProperties: false title: The Sick Hours object x-conductor-object-type: nested qbd_vacation_hours: type: object properties: hoursAvailable: type: - string - 'null' description: >- 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. example: PT8H30M accrualPeriod: type: - string - 'null' enum: - accrues_annually - accrues_hourly - accrues_per_paycheck - null description: How frequently the employee's vacation hours are accrued. example: accrues_per_paycheck hoursAccruedPerPeriod: type: - string - 'null' description: >- 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. example: PT8H0M maximumHours: type: - string - 'null' description: >- 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. example: PT80H0M resetsHoursEachYear: type: - boolean - 'null' description: >- Indicates whether the employee's vacation hours reset to zero at the beginning of the new year. example: false hoursUsed: type: - string - 'null' description: >- 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. example: PT2H45M accrualStartDate: type: - string - 'null' format: date description: >- The date the employee's vacation hours began to accrue, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01' required: - hoursAvailable - accrualPeriod - hoursAccruedPerPeriod - maximumHours - resetsHoursEachYear - hoursUsed - accrualStartDate additionalProperties: false title: The Vacation Hours object x-conductor-object-type: nested securitySchemes: BearerAuth: type: http scheme: bearer description: >- Your Conductor secret key using Bearer auth (e.g., `"Authorization: Bearer {{YOUR_SECRET_KEY}}"`). ```` Built with [Mintlify](https://mintlify.com).