> ## 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. # Create an employee > Creates an employee record that captures personal details, contact information, employment dates, and payroll settings in a single request so the employee is ready for scheduling, time tracking, and payroll processing. ## OpenAPI ````yaml POST /quickbooks-desktop/employees 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: post: summary: Create an employee description: >- Creates an employee record that captures personal details, contact information, employment dates, and payroll settings in a single request so the employee is ready for scheduling, time tracking, and payroll processing. parameters: - in: header name: Conductor-End-User-Id 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 description: The ID of the End-User to receive this request. requestBody: required: true content: application/json: schema: type: object properties: isActive: description: >- Indicates whether this employee is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to `true`. example: true default: true type: boolean salutation: description: >- The employee's formal salutation title that precedes their name, such as "Mr.", "Ms.", or "Dr.". example: Dr. type: string firstName: description: |- The employee's first name. Maximum length: 25 characters. example: John type: string maxLength: 25 middleName: description: |- The employee's middle name. Maximum length: 5 characters. example: A. type: string maxLength: 5 lastName: description: |- The employee's last name. Maximum length: 25 characters. example: Doe type: string maxLength: 25 jobTitle: description: The employee's job title. example: Purchasing Manager type: string supervisorId: description: >- The employee's supervisor. Found in the "employment job details" section of the employee's record in QuickBooks. example: 80000001-1234567890 type: string maxLength: 36 department: description: >- The employee's department. Found in the "employment job details" section of the employee's record in QuickBooks. example: Sales type: string description: 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. type: string targetBonus: 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' type: string address: 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. type: object properties: line1: description: >- The first line of the employee address (e.g., street, PO Box, or company name). Maximum length: 41 characters. example: Conductor Labs Inc. type: string maxLength: 41 line2: description: >- The second line of the employee address, if needed (e.g., apartment, suite, unit, or building). Maximum length: 41 characters. example: 540 Market St. type: string maxLength: 41 line3: description: |- The third line of the employee address, if needed. Maximum length: 41 characters. example: Suite 100 type: string maxLength: 41 line4: description: |- The fourth line of the employee address, if needed. Maximum length: 41 characters. example: '' type: string maxLength: 41 city: description: >- The city, district, suburb, town, or village name of the employee address. Maximum length: 31 characters. example: San Francisco type: string maxLength: 31 state: description: >- 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). example: CA type: string enum: - none - armed_forces_americas - armed_forces_europe - armed_forces_pacific - AB - AK - AL - AR - AZ - BC - CA - CO - CT - DC - DE - FL - GA - HI - IA - ID - IL - IN - KS - KY - LA - MA - MB - MD - ME - MI - MN - MO - MS - MT - NB - NC - ND - NE - NH - NJ - NL - NM - NS - NT - NU - NV - NY - OH - OK - 'ON' - OR - PA - PE - PR - QC - RI - SC - SD - SK - TN - TX - UT - VA - VT - WA - WI - WV - WY - YT postalCode: description: |- The postal code or ZIP code of the employee address. Maximum length: 13 characters. example: '94110' type: string maxLength: 13 country: description: The country name of the employee address. example: United States type: string additionalProperties: false printAs: description: >- The name to use when printing this employee from QuickBooks. By default, this is the same as the `name` field. example: John Doe type: string phone: description: |- The employee's primary telephone number. Maximum length: 21 characters. example: +1-555-123-4567 type: string maxLength: 21 mobile: description: |- The employee's mobile phone number. Maximum length: 21 characters. example: +1-555-555-1212 type: string maxLength: 21 pager: description: |- The employee's pager number. Maximum length: 21 characters. example: +1-555-555-1212 type: string maxLength: 21 pagerPin: description: The employee's pager PIN. example: '1234' type: string alternatePhone: description: |- The employee's alternate telephone number. Maximum length: 21 characters. example: +1-555-987-6543 type: string maxLength: 21 fax: description: |- The employee's fax number. Maximum length: 21 characters. example: +1-555-555-1212 type: string maxLength: 21 ssn: 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 type: string email: description: The employee's email address. example: employee@example.com type: string customContactFields: description: >- Additional custom contact fields for this employee, such as phone numbers or email addresses. minItems: 1 type: array items: 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 description: The value of the contact field. example: 555-123-4567 required: - name - value additionalProperties: false emergencyContact: description: The employee's emergency contacts. type: object properties: primaryContact: description: The employee's primary 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 description: The value of the contact field. example: 555-123-4567 relation: description: The relationship of the employee to the employee. example: spouse type: string enum: - brother - daughter - father - friend - mother - other - partner - sister - son - spouse required: - name - value additionalProperties: false secondaryContact: description: The employee's secondary 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 description: The value of the contact field. example: 555-123-4567 relation: description: The relationship of the employee to the employee. example: spouse type: string enum: - brother - daughter - father - friend - mother - other - partner - sister - son - spouse required: - name - value additionalProperties: false additionalProperties: false employeeType: 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 type: string enum: - officer - owner - regular - statutory default: regular employmentStatus: description: >- Indicates whether this employee is a part-time or full-time employee. example: full_time type: string enum: - full_time - part_time overtimeExemptStatus: description: > Indicates whether this employee is exempt from overtime pay. This classification is based on U.S. labor laws (FLSA). example: exempt type: string enum: - exempt - non_exempt keyEmployeeStatus: description: Indicates whether this employee is a key employee. example: key_employee type: string enum: - key_employee - non_key_employee gender: description: This employee's gender. example: male type: string enum: - male - female hiredDate: description: >- The date this employee was hired, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01' type: string format: date originalHireDate: description: >- The original hire date for this employee, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01' type: string format: date adjustedServiceDate: 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' type: string format: date terminationDate: 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' type: string format: date birthDate: description: >- This employee's date of birth, in ISO 8601 format (YYYY-MM-DD). example: '1990-01-01' type: string format: date usCitizenshipStatus: description: Indicates whether this employee is a U.S. citizen. example: citizen type: string enum: - citizen - non_citizen ethnicity: description: This employee's ethnicity. example: asian type: string enum: - american_indian - asian - black - hawaiian - hispanic - white - two_or_more_races disabilityStatus: description: Indicates whether this employee is disabled. example: disabled type: string enum: - disabled - non_disabled disabilityDescription: description: A description of this employee's disability. example: Cerebral Palsy type: string i9OnFileStatus: description: Indicates whether this employee's I-9 is on file. example: on_file type: string enum: - on_file - not_on_file workAuthorizationExpirationDate: description: >- The date this employee's work authorization expires, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01' type: string format: date usVeteranStatus: description: Indicates whether this employee is a U.S. veteran. example: veteran type: string enum: - veteran - non_veteran militaryStatus: description: This employee's military status if they are a U.S. veteran. example: active type: string enum: - active - reserve accountNumber: 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' type: string note: description: A note or comment about this employee. example: This employee is a key employee. type: string additionalNotes: description: Additional notes about this employee. minItems: 1 type: array items: type: object properties: note: type: string description: The text of this note. example: This is a fun note. required: - note additionalProperties: false billingRateId: description: >- The employee's billing rate, used to override service item rates in time tracking activities. example: 80000001-1234567890 type: string maxLength: 36 employeePayroll: description: The employee's payroll information. type: object properties: payPeriod: description: >- How frequently this employee is paid (e.g., weekly, biweekly, monthly). This determines the schedule for generating paychecks. example: weekly type: string enum: - biweekly - daily - monthly - quarterly - semimonthly - weekly - yearly classId: 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: 80000001-1234567890 type: string maxLength: 36 earnings: description: The employee's earnings. minItems: 1 type: array items: type: object properties: payrollWageItemId: 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: 80000001-1234567890 type: string maxLength: 36 rate: description: >- The hourly rate for this employee, represented as a decimal string. Decimal string format: up to 5 decimal places and up to 10 digits before the decimal point (for example, "123.45"). example: '10.00' type: string ratePercent: description: >- The hourly rate for this employee expressed as a percentage. example: '10.5' type: string required: - payrollWageItemId additionalProperties: false useTimeDataToCreatePaychecks: description: >- Indicates whether this employee is using time-tracking data to create paychecks. example: uses_time_data type: string enum: - does_not_use_time_data - not_set - uses_time_data sickHours: description: >- The employee's sick hours, including how sick time is accrued and the total hours accrued. type: object properties: hoursAvailable: 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 type: string accrualPeriod: description: >- How frequently the employee's sick hours are accrued. example: accrues_per_paycheck type: string enum: - accrues_annually - accrues_hourly - accrues_per_paycheck hoursAccruedPerPeriod: 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 type: string maximumHours: 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 type: string resetsHoursEachYear: description: >- Indicates whether the employee's sick hours reset to zero at the beginning of the new year. example: false type: boolean hoursUsed: 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 type: string accrualStartDate: description: >- The date the employee's sick hours began to accrue, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01' type: string format: date additionalProperties: false vacationHours: description: >- The employee's vacation hours, including how vacation time is accrued and the total hours accrued. type: object properties: hoursAvailable: 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 type: string accrualPeriod: description: >- How frequently the employee's vacation hours are accrued. example: accrues_per_paycheck type: string enum: - accrues_annually - accrues_hourly - accrues_per_paycheck hoursAccruedPerPeriod: 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 type: string maximumHours: 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 type: string resetsHoursEachYear: description: >- Indicates whether the employee's vacation hours reset to zero at the beginning of the new year. example: false type: boolean hoursUsed: 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 type: string accrualStartDate: description: >- The date the employee's vacation hours began to accrue, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01' type: string format: date additionalProperties: false additionalProperties: false externalId: type: string format: uuid 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. **IMPORTANT**: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error. example: 12345678-abcd-1234-abcd-1234567890ab additionalProperties: false responses: '200': description: Returns the newly created employee. headers: Conductor-Request-Id: required: true description: The unique identifier for this API request. schema: type: string description: The unique identifier for this API request. example: req_1234567abcdefg 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.create({ 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.create( 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: description: The type of object. This value is always `"qbd_employee"`. example: qbd_employee type: string const: 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: anyOf: - type: string - type: 'null' description: >- The employee's formal salutation title that precedes their name, such as "Mr.", "Ms.", or "Dr.". example: Dr. firstName: anyOf: - type: string - type: 'null' description: The employee's first name. example: John middleName: anyOf: - type: string - type: 'null' description: The employee's middle name. example: A. lastName: anyOf: - type: string - type: 'null' description: The employee's last name. example: Doe jobTitle: anyOf: - type: string - type: 'null' description: The employee's job title. example: Purchasing Manager supervisor: anyOf: - type: object properties: id: anyOf: - type: string - type: '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: anyOf: - type: string - type: '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 - type: 'null' 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: anyOf: - type: string - type: 'null' description: >- The employee's department. Found in the "employment job details" section of the employee's record in QuickBooks. example: Sales description: anyOf: - type: string - type: '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: anyOf: - type: string - type: '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: anyOf: - $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: anyOf: - type: string - type: '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: anyOf: - type: string - type: 'null' description: The employee's primary telephone number. example: +1-555-123-4567 mobile: anyOf: - type: string - type: 'null' description: The employee's mobile phone number. example: +1-555-555-1212 pager: anyOf: - type: string - type: 'null' description: The employee's pager number. example: +1-555-555-1212 pagerPin: anyOf: - type: string - type: 'null' description: The employee's pager PIN. example: '1234' alternatePhone: anyOf: - type: string - type: 'null' description: The employee's alternate telephone number. example: +1-555-987-6543 fax: anyOf: - type: string - type: 'null' description: The employee's fax number. example: +1-555-555-1212 ssn: anyOf: - type: string - type: '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: anyOf: - type: string - type: '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: anyOf: - $ref: '#/components/schemas/qbd_emergency_contact_set' - type: 'null' description: The employee's emergency contacts. employeeType: anyOf: - type: string enum: - officer - owner - regular - statutory - type: '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: anyOf: - type: string enum: - full_time - part_time - type: 'null' description: >- Indicates whether this employee is a part-time or full-time employee. example: full_time overtimeExemptStatus: anyOf: - type: string enum: - exempt - non_exempt - type: 'null' description: > Indicates whether this employee is exempt from overtime pay. This classification is based on U.S. labor laws (FLSA). example: exempt keyEmployeeStatus: anyOf: - type: string enum: - key_employee - non_key_employee - type: 'null' description: Indicates whether this employee is a key employee. example: key_employee gender: anyOf: - type: string enum: - male - female - type: 'null' description: This employee's gender. example: male hiredDate: anyOf: - type: string format: date - type: 'null' description: The date this employee was hired, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01T00:00:00.000Z' originalHireDate: anyOf: - type: string format: date - type: 'null' description: >- The original hire date for this employee, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01T00:00:00.000Z' adjustedServiceDate: anyOf: - type: string format: date - type: 'null' 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-01T00:00:00.000Z' terminationDate: anyOf: - type: string format: date - type: 'null' 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-01T00:00:00.000Z' birthDate: anyOf: - type: string format: date - type: 'null' description: This employee's date of birth, in ISO 8601 format (YYYY-MM-DD). example: '1990-01-01T00:00:00.000Z' usCitizenshipStatus: anyOf: - type: string enum: - citizen - non_citizen - type: 'null' description: Indicates whether this employee is a U.S. citizen. example: citizen ethnicity: anyOf: - type: string enum: - american_indian - asian - black - hawaiian - hispanic - white - two_or_more_races - type: 'null' description: This employee's ethnicity. example: asian disabilityStatus: anyOf: - type: string enum: - disabled - non_disabled - type: 'null' description: Indicates whether this employee is disabled. example: disabled disabilityDescription: anyOf: - type: string - type: 'null' description: A description of this employee's disability. example: Cerebral Palsy i9OnFileStatus: anyOf: - type: string enum: - on_file - not_on_file - type: 'null' description: Indicates whether this employee's I-9 is on file. example: on_file workAuthorizationExpirationDate: anyOf: - type: string format: date - type: 'null' description: >- The date this employee's work authorization expires, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01T00:00:00.000Z' usVeteranStatus: anyOf: - type: string enum: - veteran - non_veteran - type: 'null' description: Indicates whether this employee is a U.S. veteran. example: veteran militaryStatus: anyOf: - type: string enum: - active - reserve - type: 'null' description: This employee's military status if they are a U.S. veteran. example: active accountNumber: anyOf: - type: string - type: '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: anyOf: - type: string - type: '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: anyOf: - type: object properties: id: anyOf: - type: string - type: '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: anyOf: - type: string - type: '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 - type: 'null' description: >- The employee's billing rate, used to override service item rates in time tracking activities. example: id: 80000001-1234567890 fullName: Standard Rate employeePayroll: anyOf: - $ref: '#/components/schemas/qbd_employee_payroll_info' - type: 'null' description: >- The employee's payroll information. **IMPORTANT**: QuickBooks Desktop only returns this field if the connected app has personal data access enabled. If this field is `null` or missing, confirm this setting is enabled in QuickBooks Desktop: sign in as Admin in Single-User Mode and go to `Edit > Preferences > Integrated Applications > Company Preferences`, select the app, click `Properties`, then check "Allow this application to access personal data such as Social Security Numbers and customer credit card information". externalId: anyOf: - type: string 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 - type: 'null' 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: anyOf: - type: string - type: 'null' description: >- The first line of the employee address (e.g., street, PO Box, or company name). example: Conductor Labs Inc. line2: anyOf: - type: string - type: 'null' description: >- The second line of the employee address, if needed (e.g., apartment, suite, unit, or building). example: 540 Market St. line3: anyOf: - type: string - type: 'null' description: The third line of the employee address, if needed. example: Suite 100 line4: anyOf: - type: string - type: 'null' description: The fourth line of the employee address, if needed. example: '' city: anyOf: - type: string - type: 'null' description: >- The city, district, suburb, town, or village name of the employee address. example: San Francisco state: anyOf: - type: string - type: 'null' description: >- 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. example: CA postalCode: anyOf: - type: string - type: 'null' description: The postal code or ZIP code of the employee address. example: '94110' country: anyOf: - type: string - type: '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: anyOf: - type: string - type: '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: anyOf: - $ref: '#/components/schemas/qbd_emergency_contact' - type: 'null' description: The employee's primary emergency contact. secondaryContact: anyOf: - $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: anyOf: - type: string format: date - type: 'null' description: >- The date this note was last updated, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01T00:00:00.000Z' 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: anyOf: - type: string enum: - biweekly - daily - monthly - quarterly - semimonthly - weekly - yearly - type: 'null' description: >- How frequently this employee is paid (e.g., weekly, biweekly, monthly). This determines the schedule for generating paychecks. example: weekly class: anyOf: - type: object properties: id: anyOf: - type: string - type: '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: anyOf: - type: string - type: '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 - type: 'null' 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: anyOf: - type: string enum: - does_not_use_time_data - not_set - uses_time_data - type: 'null' description: >- Indicates whether this employee is using time-tracking data to create paychecks. example: uses_time_data sickHours: anyOf: - $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: anyOf: - $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: anyOf: - type: string - type: 'null' description: The value of the contact field. example: 555-123-4567 relation: anyOf: - type: string enum: - brother - daughter - father - friend - mother - other - partner - sister - son - spouse - type: '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: anyOf: - type: string - type: '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: anyOf: - type: string - type: '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: anyOf: - type: string - type: 'null' description: The hourly rate for this employee, represented as a decimal string. example: '10.00' ratePercent: anyOf: - type: string - type: '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: anyOf: - type: string - type: '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: anyOf: - type: string enum: - accrues_annually - accrues_hourly - accrues_per_paycheck - type: 'null' description: How frequently the employee's sick hours are accrued. example: accrues_per_paycheck hoursAccruedPerPeriod: anyOf: - type: string - type: '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: anyOf: - type: string - type: '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: anyOf: - type: boolean - type: 'null' description: >- Indicates whether the employee's sick hours reset to zero at the beginning of the new year. example: false hoursUsed: anyOf: - type: string - type: '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: anyOf: - type: string format: date - type: 'null' description: >- The date the employee's sick hours began to accrue, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01T00:00:00.000Z' 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: anyOf: - type: string - type: '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: anyOf: - type: string enum: - accrues_annually - accrues_hourly - accrues_per_paycheck - type: 'null' description: How frequently the employee's vacation hours are accrued. example: accrues_per_paycheck hoursAccruedPerPeriod: anyOf: - type: string - type: '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: anyOf: - type: string - type: '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: anyOf: - type: boolean - type: 'null' description: >- Indicates whether the employee's vacation hours reset to zero at the beginning of the new year. example: false hoursUsed: anyOf: - type: string - type: '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: anyOf: - type: string format: date - type: 'null' description: >- The date the employee's vacation hours began to accrue, in ISO 8601 format (YYYY-MM-DD). example: '2024-01-01T00:00:00.000Z' 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}}"`). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.