--- title: "Update Employee" method: POST path: "/api/v1/employees/{id}" tags: ["Employees", "Public API"] --- # Update Employee `POST /api/v1/employees/{id}` 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 ## Path parameters - `id` string, required ## Request body - Employee — A dictionary of employee field names and their new values. The properties listed below are commonly used fields, but any valid writable employee field name can be used as a key. To discover all available field names, call the List Fields endpoint (operationId: list-fields, GET /api/v1/meta/fields). Only the fields you include will be updated; omitted fields are left unchanged. Some string-valued fields are backed by lists or lookups, so callers should use valid option values from BambooHR metadata rather than assuming any free-text string will persist as entered. **Important for AI agents:** Unknown or misspelled field names are silently ignored — the endpoint returns 200 but the field is not updated. Always use the exact alias from the schema properties below or from the list-fields endpoint; do not invent aliases by adding prefixes such as `home` (e.g., `homeCity` is wrong — the correct alias is `city`). Photo data is not writable through this schema: photo-related keys are silently ignored. 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. - `firstName` string — Legal first name. - `lastName` string — Legal last name. - `workEmail` string — Work email address. - `jobTitle` string — Job title. - `department` string — Department name. - `division` string — Division name. - `location` string — Location name. - `hireDate` string, date — Hire date in YYYY-MM-DD format. - `mobilePhone` string — Mobile phone number. - `homePhone` string — Home phone number. - `workPhone` string — Work phone number. - `address1` string — Home street address line 1. The correct alias is `address1` — do not use `homeAddress1`, `homeStreet1`, or `street1`. - `address2` string — Home street address line 2 (apartment, suite, etc.). The correct alias is `address2` — do not use `homeAddress2` or `homeStreet2`. - `city` string — Home city. The correct alias is `city` — do not use `homeCity`. - `state` string — Home state or province. The correct alias is `state` — do not use `homeState`. Values are normalized to standard abbreviations (e.g., "Pennsylvania" becomes "PA"). - `zipcode` string — Home ZIP or postal code. The correct alias is `zipcode` — do not use `homeZipcode` or `homeZip`. - `country` string — Home country name. The correct alias is `country` — do not use `homeCountry`. ## Response `200` Employee updated successfully. - GetEmployeeResponse — Employee data returned by the Get Employee endpoint. The `id` field is always present; all other named properties are included only when explicitly requested via the `fields` query parameter. Additional custom or company-configured fields may also appear. - `id` string, 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]`. - `employeeNumber` string, 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. - `firstName` string, nullable — Employee's first name - `lastName` string, nullable — Employee's last name - `preferredName` string, nullable — Employee's preferred name - `middleName` string, nullable — Employee's middle name - `photoUrl` string, nullable — URL to the employee's profile photo - `jobTitleName` string, nullable — Employee's current job title - `jobTitleId` string, nullable — Employee's job title ID - `status` 'Active' | 'Inactive', nullable — Employee's current status - `workEmail` string, nullable — Employee's work email address - `homeEmail` string, nullable — Employee's home email address - `bestEmail` string, nullable — Employee's best email address - `workPhone` string, nullable — Employee's work phone number - `workPhoneExtension` string, nullable — Employee's work phone extension - `mobilePhone` string, nullable — Employee's mobile phone number - `homePhone` string, nullable — Employee's home phone number - `skypeUsername` string, nullable — Employee's Skype username - `linkedinUrl` string, nullable — Employee's LinkedIn profile URL - `facebookUrl` string, nullable — Employee's Facebook profile URL - `instagramUrl` string, nullable — Employee's Instagram profile URL - `twitterUrl` string, nullable — Employee's Twitter/X profile URL - `pinterestUrl` string, nullable — Employee's Pinterest profile URL - `birthDate` string, nullable — Employee's birth date - `hireDate` string, nullable — Employee's hire date - `originalHireDate` string, nullable — Employee's original hire date - `terminationDate` string, nullable — Employee's termination date - `address1` string, nullable — Employee's street address - `city` string, nullable — Employee's city - `state` string, nullable — Employee's state or province - `country` string, nullable — Employee's country - `gender` string, nullable — Employee's gender - `marital` string, nullable — Employee's marital status - `payRate` string, nullable — Employee's pay rate - `payType` string, nullable — Employee's pay type - `payPeriod` string, nullable — Employee's pay period - `exempt` string, nullable — Whether the employee is FLSA exempt - `canUploadPhoto` boolean, nullable — Whether the requesting user can upload a photo for this employee - `division` string, nullable — Employee's division name - `divisionId` string, nullable — Employee's division ID - `department` string, nullable — Employee's department name - `departmentId` string, nullable — Employee's department ID - `location` string, nullable — Employee's location name - `locationId` string, nullable — Employee's location ID - `employmentStatus` string, nullable — Employee's current employment status name - `employmentStatusId` string, nullable — Employee's current employment status ID - `reportsToName` string, nullable — Name of the employee's manager - `reportsToId` string, nullable — Internal employee ID of the employee's manager ## Other responses - `400` — Provided JSON is malformed, or required fields are missing. - `403` — The API user does not have permission to see the employee or to update any of the requested fields. - `404` — The employee does not exist. - `409` — A field was given an invalid value (e.g., duplicate email, invalid state/country, incompatible pay type). --- [API](https://skmtc.net/bamboohr/apis/bamboohr-api.md) · [All operations](https://skmtc.net/bamboohr/apis/bamboohr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bamboohr/bamboohr-api/revisions/19ebf391a399/schema)