v1

latestOpenAPI 3.1.02026-07-26294215839.4 KB

Employees

Public API

Create Employee

Create a new employee. At minimum, provide a first name and last name in a JSON object or XML document. The request body schema lists commonly used fields, but any valid writable employee field name may be included 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, set, or remove the employee profile photo. Photo-related keys (e.g. photo, photoUrl) included in the body are silently ignored: the request still creates the employee and returns 201, but no photo is attached. After creation, use the Upload Employee Photo endpoint (upload-employee-photo) to attach a profile photo. AI connectors cannot use that endpoint reliably and should redirect the user to the BambooHR web UI.

Trax Payroll note: Employees added to a pay schedule synced with Trax Payroll 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

Request body

firstNamestring required

Legal first name (required).

lastNamestring required

Legal last name (required).

workEmailstring

Work email address.

jobTitlestring

Job title.

departmentstring

Department name.

hireDatestring date

Hire date in YYYY-MM-DD format.

Example request

{
  "firstName": "Panda",
  "lastName": "Bear",
  "jobTitle": "Software Engineer",
  "department": "Engineering"
}

Response

Employee created 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