v1

latestOpenAPI 3.1.02026-07-26294215839.4 KB

Employees

Public API

Update Employee

Update an employee's fields by submitting a JSON object or XML document containing field name/value pairs. The request body schema lists commonly used fields, but any valid writable employee field name may be used as a key. To discover available field names, call the List Fields endpoint (operationId: list-fields, GET /api/v1/meta/fields).

This endpoint does not upload, replace, or remove the employee profile photo, and does not accept any binary or file uploads in general. Photo-related keys (e.g. photo, photoUrl) included in the body are silently ignored: the request still returns 200, but no photo change is made. To change a profile photo, use the Upload Employee Photo endpoint (upload-employee-photo). AI connectors cannot use that endpoint reliably and should redirect the user to the BambooHR web UI.

Trax Payroll note: If the employee is currently on a pay schedule syncing with Trax Payroll, or is being added to one, the request must include the required payroll-related employee fields: employeeNumber (unless the company has automatic employee numbers enabled), firstName, lastName, dateOfBirth, ssn or ein, gender, maritalStatus, hireDate, address1, city, state, zipcode, country, employmentHistoryStatus, exempt, payType, payRate, payPer, overtimeRate, and location.

OAuth Scopes: employee, employee.write, employee:assets.write, employee:compensation.write, employee:contact.write, employee:custom_fields.write, employee:custom_fields_encrypted.write, employee:demographic.write, employee:dependent.write, employee:dependent:ssn.write, employee:education.write, employee:emergency_contacts.write, employee:identification.write, employee:job, employee:job.write, employee:management.write, employee:name.write, employee:payroll.write, employee:photo.write, employee:vaccination.write, sensitive_employee:address.write, sensitive_employee:creditcards.write, sensitive_employee:protected_info.write

post/api/v1/employees/{id}

Path parameters

idstring required

The employee ID.

Request body

firstNamestring

Legal first name.

lastNamestring

Legal last name.

workEmailstring

Work email address.

jobTitlestring

Job title.

departmentstring

Department name.

divisionstring

Division name.

locationstring

Location name.

hireDatestring date

Hire date in YYYY-MM-DD format.

mobilePhonestring

Mobile phone number.

homePhonestring

Home phone number.

workPhonestring

Work phone number.

address1string

Home street address line 1. The correct alias is address1 — do not use homeAddress1, homeStreet1, or street1.

address2string

Home street address line 2 (apartment, suite, etc.). The correct alias is address2 — do not use homeAddress2 or homeStreet2.

citystring

Home city. The correct alias is city — do not use homeCity.

statestring

Home state or province. The correct alias is state — do not use homeState. Values are normalized to standard abbreviations (e.g., "Pennsylvania" becomes "PA").

zipcodestring

Home ZIP or postal code. The correct alias is zipcode — do not use homeZipcode or homeZip.

countrystring

Home country name. The correct alias is country — do not use homeCountry.

Example request

{
  "firstName": "Panda",
  "lastName": "Bear",
  "workEmail": "panda.bear@example.com",
  "jobTitle": "Software Engineer",
  "department": "Engineering"
}

Response

Employee updated successfully.

idstring required

The internal employee ID — the canonical, immutable identifier for this employee across all employee endpoints. Equivalent to employeeId on list-employees and eeid on the employee dataset. Use this value (not employeeNumber) for employee ID inputs such as {id} path parameters or filter[ids].

employeeNumberstring nullable

The employee's editable Employee # value (the HR-visible display field on the employee profile). This is not the internal employee ID used by API inputs such as filter[ids] and {id} path parameters; those inputs expect id on this endpoint, employeeId on list-employees, or eeid on the employee dataset. Passing employeeNumber there may fail with 404 or resolve to a different employee if its value matches another employee's internal employee ID. Only included when requested via the fields parameter.

firstNamestring nullable

Employee's first name

lastNamestring nullable

Employee's last name

preferredNamestring nullable

Employee's preferred name

middleNamestring nullable

Employee's middle name

photoUrlstring nullable

URL to the employee's profile photo

jobTitleNamestring nullable

Employee's current job title

jobTitleIdstring nullable

Employee's job title ID

status'Active' | 'Inactive' nullable

Employee's current status

workEmailstring nullable

Employee's work email address

homeEmailstring nullable

Employee's home email address

bestEmailstring nullable

Employee's best email address

workPhonestring nullable

Employee's work phone number

workPhoneExtensionstring nullable

Employee's work phone extension

mobilePhonestring nullable

Employee's mobile phone number

homePhonestring nullable

Employee's home phone number

skypeUsernamestring nullable

Employee's Skype username

linkedinUrlstring nullable

Employee's LinkedIn profile URL

facebookUrlstring nullable

Employee's Facebook profile URL

instagramUrlstring nullable

Employee's Instagram profile URL

twitterUrlstring nullable

Employee's Twitter/X profile URL

pinterestUrlstring nullable

Employee's Pinterest profile URL

birthDatestring nullable

Employee's birth date

hireDatestring nullable

Employee's hire date

originalHireDatestring nullable

Employee's original hire date

terminationDatestring nullable

Employee's termination date

address1string nullable

Employee's street address

citystring nullable

Employee's city

statestring nullable

Employee's state or province

countrystring nullable

Employee's country

genderstring nullable

Employee's gender

maritalstring nullable

Employee's marital status

payRatestring nullable

Employee's pay rate

payTypestring nullable

Employee's pay type

payPeriodstring nullable

Employee's pay period

exemptstring nullable

Whether the employee is FLSA exempt

canUploadPhotoboolean nullable

Whether the requesting user can upload a photo for this employee

divisionstring nullable

Employee's division name

divisionIdstring nullable

Employee's division ID

departmentstring nullable

Employee's department name

departmentIdstring nullable

Employee's department ID

locationstring nullable

Employee's location name

locationIdstring nullable

Employee's location ID

employmentStatusstring nullable

Employee's current employment status name

employmentStatusIdstring nullable

Employee's current employment status ID

reportsToNamestring nullable

Name of the employee's manager

reportsToIdstring nullable

Internal employee ID of the employee's manager