BAbamboohr
Employees
Public API

Update Employee

Changed on

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 List Fields (list-fields).

employmentType and terminationDate cannot be changed here: they belong to the employment status record. Sent alongside other fields they are ignored and the other fields save; a request whose only changes are to these fields is rejected with 400. Change them through the employmentStatus table on the REST API.

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.

Employment status note: it is recommended to use the employmentStatus table endpoint. Writing a different employmentHistoryStatus appends a new employment status record rather than amending the current one; resending the current status appends nothing. employeeStatusDate is ignored unless the status changes, and a request whose only change is employeeStatusDate is rejected with 400. The new record will be dated using employeeStatusDate when supplied in the same request, otherwise the new hire date if hireDate changes, otherwise today in the company's time zone. A date earlier than the current record inserts the new record into history rather than making it current. On accounts with employment types enabled, the new record takes its employment type from the record in effect on its date, so the request is rejected with 400 when that record has no employment type or the date is earlier than the employee's first record. The response reflects the employee's current record, so a backdated record does not appear in it; read the full history through the employmentStatus table. This endpoint cannot amend an existing record; that is done through the employmentStatus table endpoints of the REST API.

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}

Request

  • Base URL
    https://companySubDomain.bamboohr.com
  • Auth
    • HTTP basic
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:assets.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:contact.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:compensation.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:custom_fields_encrypted.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:custom_fields.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:demographic.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:dependent.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:dependent:ssn.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:education.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:emergency_contacts.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:identification.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:job.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:management.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:name.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:photo.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:vaccination.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopessensitive_employee:protected_info.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopessensitive_employee:address.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopessensitive_employee:creditcards.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:payroll.write
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee
    • or OAuth 2
      Authorization code/authorize.php
      Token URL/token.php
      Scopesemployee:job
  • TypeScript
    A function with typed inputs. Its response is checked against the schema.

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

Changes

  • 922fc15f43a7Revision changes
    • info

      the security scope employee.write was added to the endpoint's security scheme oauth

    • info

      the security scope employee:job was removed from the endpoint's security scheme oauth