QuickBooks Desktop API
Core Resources
- Auth Sessions
- End Users
General
- Accounts
- Classes
- Customers
- Date-Driven Terms
- Employees
- Inventory Sites
- Payroll Wage Items
- Sales Representatives
- Sales-Tax Codes
- Standard Terms
- Vendors
Transactions
- Bill Check Payments
- Bill Credit Card Payments
- Bills
- Checks
- Credit Card Charges
- Credit Card Credits
- Credit Memos
- Estimates
- Inventory Adjustments
- Invoices
- Journal Entries
- Purchase Orders
- Receive-Payments
- Sales Orders
- Sales Receipts
- Time Tracking Activities
- Transfers
- Vendor Credits
Items
- Discount Items
- Inventory Assembly Items
- Inventory Items
- Non-Inventory Items
- Sales-Tax Items
- Service Items
- Subtotal Items
List all employees
Returns a list of employees. Use the cursor parameter to paginate through the results.
import Conductor from 'conductor-node';
const client = new Conductor({
apiKey: process.env['CONDUCTOR_SECRET_KEY'], // This is the default and can be omitted
});
async function main() {
// Automatically fetches more pages as needed.
for await (const employee of client.qbd.employees.list({ conductorEndUserId: 'end_usr_1234567abcdefg' })) {
console.log(employee.id);
}
}
main();{
"objectType": "list",
"url": "/v1/quickbooks-desktop/employees",
"data": [
{
"id": "80000001-1234567890",
"objectType": "qbd_employee",
"createdAt": "2021-10-01T17:34:56.000Z",
"updatedAt": "2021-10-01T20:45:30.000Z",
"revisionNumber": "1721172183",
"name": "John Doe",
"isActive": true,
"salutation": "Dr.",
"firstName": "John",
"middleName": "A.",
"lastName": "Doe",
"jobTitle": "Purchasing Manager",
"supervisor": {
"id": "80000001-1234567890",
"fullName": "John Doe"
},
"department": "Sales",
"description": "This employee is a key employee.",
"targetBonus": "10000.00",
"address": {
"line1": "Conductor Labs Inc.",
"line2": "540 Market St.",
"line3": "Suite 100",
"line4": "",
"city": "San Francisco",
"state": "CA",
"postalCode": "94110",
"country": "United States"
},
"printAs": "John Doe",
"phone": "+1-555-123-4567",
"mobile": "+1-555-555-1212",
"pager": "+1-555-555-1212",
"pagerPin": "1234",
"alternatePhone": "+1-555-987-6543",
"fax": "+1-555-555-1212",
"ssn": "123-45-6789",
"email": "employee@example.com",
"customContactFields": [
{
"name": "Main Phone",
"value": "555-123-4567"
}
],
"emergencyContact": {
"primaryContact": {
"name": "Main Phone",
"value": "555-123-4567",
"relation": "spouse"
},
"secondaryContact": {
"name": "Main Phone",
"value": "555-123-4567",
"relation": "spouse"
}
},
"employeeType": "regular",
"employmentStatus": "full_time",
"overtimeExemptStatus": "exempt",
"keyEmployeeStatus": "key_employee",
"gender": "male",
"hiredDate": "2024-01-01T00:00:00.000Z",
"originalHireDate": "2024-01-01T00:00:00.000Z",
"adjustedServiceDate": "2024-01-01T00:00:00.000Z",
"terminationDate": "2024-01-01T00:00:00.000Z",
"birthDate": "1990-01-01T00:00:00.000Z",
"usCitizenshipStatus": "citizen",
"ethnicity": "asian",
"disabilityStatus": "disabled",
"disabilityDescription": "Cerebral Palsy",
"i9OnFileStatus": "on_file",
"workAuthorizationExpirationDate": "2024-01-01T00:00:00.000Z",
"usVeteranStatus": "veteran",
"militaryStatus": "active",
"accountNumber": "1010",
"note": "This employee is a key employee.",
"additionalNotes": [
{
"id": 1,
"date": "2021-01-01T00:00:00.000Z",
"note": "This is a fun note."
}
],
"billingRate": {
"id": "80000001-1234567890",
"fullName": "Standard Rate"
},
"employeePayroll": {
"payPeriod": "weekly",
"class": {
"id": "80000001-1234567890",
"fullName": "Payroll"
},
"earnings": [
{
"payrollWageItem": {
"id": "80000001-1234567890",
"fullName": "Regular Pay"
},
"rate": "10.00",
"ratePercent": "10.5"
}
],
"useTimeDataToCreatePaychecks": "uses_time_data",
"sickHours": {
"hoursAvailable": "PT8H30M",
"accrualPeriod": "accrues_per_paycheck",
"hoursAccruedPerPeriod": "PT8H0M",
"maximumHours": "PT80H0M",
"resetsHoursEachYear": false,
"hoursUsed": "PT2H45M",
"accrualStartDate": "2024-01-01T00:00:00.000Z"
},
"vacationHours": {
"hoursAvailable": "PT8H30M",
"accrualPeriod": "accrues_per_paycheck",
"hoursAccruedPerPeriod": "PT8H0M",
"maximumHours": "PT80H0M",
"resetsHoursEachYear": false,
"hoursUsed": "PT2H45M",
"accrualStartDate": "2024-01-01T00:00:00.000Z"
}
},
"externalId": "12345678-abcd-1234-abcd-1234567890ab",
"customFields": [
{
"ownerId": "0",
"name": "Customer Rating",
"type": "string_1024_type",
"value": "Premium"
}
]
}
],
"nextCursor": "12345678-abcd-abcd-example-1234567890ab",
"remainingCount": 10,
"hasMore": true
}Authorizations
Your Conductor secret key using Bearer auth (e.g., "Authorization: Bearer {{YOUR_SECRET_KEY}}").
Headers
The ID of the EndUser to receive this request (e.g., "Conductor-End-User-Id: {{END_USER_ID}}").
Query Parameters
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.
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.
The maximum number of objects to return. Accepts values ranging from 1 to 150, defaults to 150. When used with cursor-based pagination, this parameter controls how many results are returned per page. To paginate through results, combine this with the cursor parameter. Each response will include a nextCursor value that can be passed to subsequent requests to retrieve the next page of results.
1 < x < 150The pagination token to fetch the next set of results when paginating with the limit parameter. Do not include this parameter on the first call. Use the nextCursor value returned in the previous response to request subsequent results.
Filter for employees that are active, inactive, or both.
active, all, inactive Filter for employees updated on or after this date and time, in ISO 8601 format (YYYY-MM-DDTHH:mm:ss). If you only provide a date (YYYY-MM-DD), the time is assumed to be 00:00:00 of that day.
Filter for employees updated on or before this date and time, in ISO 8601 format (YYYY-MM-DDTHH:mm:ss). If you only provide a date (YYYY-MM-DD), the time is assumed to be 23:59:59 of that day.
Filter for employees whose name contains this substring, case-insensitive. NOTE: If you use this parameter, you cannot also use nameStartsWith or nameEndsWith.
Filter for employees whose name starts with this substring, case-insensitive. NOTE: If you use this parameter, you cannot also use nameContains or nameEndsWith.
Filter for employees whose name ends with this substring, case-insensitive. NOTE: If you use this parameter, you cannot also use nameContains or nameStartsWith.
Filter for employees whose name is alphabetically greater than or equal to this value.
Filter for employees whose name is alphabetically less than or equal to this value.
Response
The type of object. This value is always "list".
"list"The endpoint URL where this list can be accessed.
The array of employees.
The unique identifier assigned by QuickBooks to this employee. This ID is unique across all employees but not across different QuickBooks object types.
The type of object. This value is always "qbd_employee".
"qbd_employee"The date and time when this employee was created, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm). The time zone is the same as the user's time zone in QuickBooks.
The date and time when this employee was last updated, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm). The time zone is the same as the user's time zone in QuickBooks.
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.
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.
Indicates whether this employee is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to true.
The employee's formal salutation title that precedes their name, such as "Mr.", "Ms.", or "Dr.".
The employee's first name.
The employee's middle name.
The employee's last name.
The employee's job title.
The employee's supervisor. Found in the "employment job details" section of the employee's record in QuickBooks.
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.
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.
The employee's department. Found in the "employment job details" section of the employee's record in QuickBooks.
A description of this employee. Found in the "employment job details" section of the employee's record in QuickBooks.
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.
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.
The first line of the employee address (e.g., street, PO Box, or company name).
The second line of the employee address, if needed (e.g., apartment, suite, unit, or building).
The third line of the employee address, if needed.
The fourth line of the employee address, if needed.
The city, district, suburb, town, or village name of the employee address.
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.
none, armed_forces_americas, armed_forces_europe, armed_forces_pacific, AK, AL, AR, AZ, CA, CO, CT, DC, DE, FL, GA, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MI, MN, MO, MS, MT, NB, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, RI, SC, SD, TN, TX, UT, VA, VT, WA, WI, WV, WY The postal code or ZIP code of the employee address.
The country name of the employee address.
The name to use when printing this employee from QuickBooks. By default, this is the same as the name field.
The employee's primary telephone number.
The employee's mobile phone number.
The employee's pager number.
The employee's pager PIN.
The employee's alternate telephone number.
The employee's fax number.
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.
The employee's email address.
The employee's emergency contacts.
The employee's primary emergency contact.
The name of the contact field (e.g., "old address", "secondary phone").
The value of the contact field.
The relationship of the employee to the employee.
brother, daughter, father, friend, mother, other, partner, sister, son, spouse The employee's secondary emergency contact.
The name of the contact field (e.g., "old address", "secondary phone").
The value of the contact field.
The relationship of the employee to the employee.
brother, daughter, father, friend, mother, other, partner, sister, son, spouse 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.
officer, owner, regular, statutory Indicates whether this employee is a part-time or full-time employee.
full_time, part_time Indicates whether this employee is exempt from overtime pay. This classification is based on U.S. labor laws (FLSA).
exempt, non_exempt Indicates whether this employee is a key employee.
key_employee, non_key_employee This employee's gender.
male, female The date this employee was hired, in ISO 8601 format (YYYY-MM-DD).
The original hire date for this employee, in ISO 8601 format (YYYY-MM-DD).
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.
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.
This employee's date of birth, in ISO 8601 format (YYYY-MM-DD).
Indicates whether this employee is a U.S. citizen.
citizen, non_citizen This employee's ethnicity.
american_indian, asian, black, hawaiian, hispanic, white, two_or_more_races Indicates whether this employee is disabled.
disabled, non_disabled A description of this employee's disability.
Indicates whether this employee's I-9 is on file.
on_file, not_on_file The date this employee's work authorization expires, in ISO 8601 format (YYYY-MM-DD).
Indicates whether this employee is a U.S. veteran.
veteran, non_veteran This employee's military status if they are a U.S. veteran.
active, reserve 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.
A note or comment about this employee.
Additional notes about this employee.
The employee's billing rate, used to override service item rates in time tracking transactions.
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.
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.
The employee's payroll information.
How frequently this employee is paid (e.g., weekly, biweekly, monthly). This determines the schedule for generating paychecks.
biweekly, daily, monthly, quarterly, semimonthly, weekly, yearly 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.
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.
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.
The employee's earnings.
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.
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.
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.
The hourly rate for this employee, represented as a decimal string.
The hourly rate for this employee expressed as a percentage.
Indicates whether this employee is using time-tracking data to create paychecks.
does_not_use_time_data, not_set, uses_time_data The employee's sick hours, including how sick time is accrued and the total hours accrued.
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.
How frequently the employee's sick hours are accrued.
accrues_annually, accrues_hourly, accrues_per_paycheck 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.
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.
Indicates whether the employee's sick hours reset to zero at the beginning of the new year.
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.
The date the employee's sick hours began to accrue, in ISO 8601 format (YYYY-MM-DD).
The employee's vacation hours, including how vacation time is accrued and the total hours accrued.
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.
How frequently the employee's vacation hours are accrued.
accrues_annually, accrues_hourly, accrues_per_paycheck 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.
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.
Indicates whether the employee's vacation hours reset to zero at the beginning of the new year.
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.
The date the employee's vacation hours began to accrue, in ISO 8601 format (YYYY-MM-DD).
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.
The custom fields for the employee object, added as user-defined data extensions, not included in the standard QuickBooks object.
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.
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.
The data type of this custom field.
amount_type, date_time_type, integer_type, percent_type, price_type, quantity_type, string_1024_type, string_255_type The value of this custom field. The maximum length depends on the field's data type.
The nextCursor is a pagination token returned in the response when you use the limit parameter in your request. To retrieve subsequent pages of results, include this token as the value of the cursor request parameter in your following API calls.
NOTE: The nextCursor value remains constant throughout the pagination process for a specific list instance; continue to use the same nextCursor token in each request to fetch additional pages.
The number of objects remaining to be fetched.
Indicates whether there are more objects to be fetched.
import Conductor from 'conductor-node';
const client = new Conductor({
apiKey: process.env['CONDUCTOR_SECRET_KEY'], // This is the default and can be omitted
});
async function main() {
// Automatically fetches more pages as needed.
for await (const employee of client.qbd.employees.list({ conductorEndUserId: 'end_usr_1234567abcdefg' })) {
console.log(employee.id);
}
}
main();{
"objectType": "list",
"url": "/v1/quickbooks-desktop/employees",
"data": [
{
"id": "80000001-1234567890",
"objectType": "qbd_employee",
"createdAt": "2021-10-01T17:34:56.000Z",
"updatedAt": "2021-10-01T20:45:30.000Z",
"revisionNumber": "1721172183",
"name": "John Doe",
"isActive": true,
"salutation": "Dr.",
"firstName": "John",
"middleName": "A.",
"lastName": "Doe",
"jobTitle": "Purchasing Manager",
"supervisor": {
"id": "80000001-1234567890",
"fullName": "John Doe"
},
"department": "Sales",
"description": "This employee is a key employee.",
"targetBonus": "10000.00",
"address": {
"line1": "Conductor Labs Inc.",
"line2": "540 Market St.",
"line3": "Suite 100",
"line4": "",
"city": "San Francisco",
"state": "CA",
"postalCode": "94110",
"country": "United States"
},
"printAs": "John Doe",
"phone": "+1-555-123-4567",
"mobile": "+1-555-555-1212",
"pager": "+1-555-555-1212",
"pagerPin": "1234",
"alternatePhone": "+1-555-987-6543",
"fax": "+1-555-555-1212",
"ssn": "123-45-6789",
"email": "employee@example.com",
"customContactFields": [
{
"name": "Main Phone",
"value": "555-123-4567"
}
],
"emergencyContact": {
"primaryContact": {
"name": "Main Phone",
"value": "555-123-4567",
"relation": "spouse"
},
"secondaryContact": {
"name": "Main Phone",
"value": "555-123-4567",
"relation": "spouse"
}
},
"employeeType": "regular",
"employmentStatus": "full_time",
"overtimeExemptStatus": "exempt",
"keyEmployeeStatus": "key_employee",
"gender": "male",
"hiredDate": "2024-01-01T00:00:00.000Z",
"originalHireDate": "2024-01-01T00:00:00.000Z",
"adjustedServiceDate": "2024-01-01T00:00:00.000Z",
"terminationDate": "2024-01-01T00:00:00.000Z",
"birthDate": "1990-01-01T00:00:00.000Z",
"usCitizenshipStatus": "citizen",
"ethnicity": "asian",
"disabilityStatus": "disabled",
"disabilityDescription": "Cerebral Palsy",
"i9OnFileStatus": "on_file",
"workAuthorizationExpirationDate": "2024-01-01T00:00:00.000Z",
"usVeteranStatus": "veteran",
"militaryStatus": "active",
"accountNumber": "1010",
"note": "This employee is a key employee.",
"additionalNotes": [
{
"id": 1,
"date": "2021-01-01T00:00:00.000Z",
"note": "This is a fun note."
}
],
"billingRate": {
"id": "80000001-1234567890",
"fullName": "Standard Rate"
},
"employeePayroll": {
"payPeriod": "weekly",
"class": {
"id": "80000001-1234567890",
"fullName": "Payroll"
},
"earnings": [
{
"payrollWageItem": {
"id": "80000001-1234567890",
"fullName": "Regular Pay"
},
"rate": "10.00",
"ratePercent": "10.5"
}
],
"useTimeDataToCreatePaychecks": "uses_time_data",
"sickHours": {
"hoursAvailable": "PT8H30M",
"accrualPeriod": "accrues_per_paycheck",
"hoursAccruedPerPeriod": "PT8H0M",
"maximumHours": "PT80H0M",
"resetsHoursEachYear": false,
"hoursUsed": "PT2H45M",
"accrualStartDate": "2024-01-01T00:00:00.000Z"
},
"vacationHours": {
"hoursAvailable": "PT8H30M",
"accrualPeriod": "accrues_per_paycheck",
"hoursAccruedPerPeriod": "PT8H0M",
"maximumHours": "PT80H0M",
"resetsHoursEachYear": false,
"hoursUsed": "PT2H45M",
"accrualStartDate": "2024-01-01T00:00:00.000Z"
}
},
"externalId": "12345678-abcd-1234-abcd-1234567890ab",
"customFields": [
{
"ownerId": "0",
"name": "Customer Rating",
"type": "string_1024_type",
"value": "Premium"
}
]
}
],
"nextCursor": "12345678-abcd-abcd-example-1234567890ab",
"remainingCount": 10,
"hasMore": true
}