v1

latestOpenAPI 3.1.02026-07-26294215839.4 KB

Employees

Public API

Get Employee

Returns a single employee record as a JSON object (or XML when Accept: application/xml). The id field is always present and is returned as a string; it is the internal employee ID — see the id and employeeNumber field documentation in the response schema for the distinction between the internal ID and the editable Employee # value. Every other field is included only when explicitly named in the fields query parameter. With no fields parameter, the response contains only id — there is no implicit default field set. Field names come from List Fields (list-fields), which also exposes custom-field aliases usable here. Note that the field-name vocabulary differs from the employee dataset (queried via Get Data from Dataset (v2) (get-data-from-dataset-v2)): this endpoint uses short names (workEmail, jobTitle, department, supervisor) where the dataset uses qualified names (email, jobInformationJobTitle, jobInformationDepartment, jobInformationReportsTo). By default only currently effective values from historical tables (job title, compensation, employment status, etc.) are returned; pass onlyCurrent=false to include future-dated values. Field-level permissions are applied silently: any requested field the authenticated caller cannot view is omitted from the response with no marker — an absent field may indicate either that it was not requested or that the caller lacks permission to view it. This differs from get-data-from-dataset-v2 for the employee dataset, which always returns every requested field but represents inaccessible values as empty and lists the withheld field names in a per-record _restrictedFields array. The maximum number of fields per request is 400. Use this for fetching arbitrary fields on a single known employee. For multiple employees, use list-employees. For complex filtering or tabular reports, use get-data-from-dataset-v2.

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

get/api/v1/employees/{id}

Path parameters

idstring required

The internal employee ID of the employee to retrieve. Use id from this endpoint, employeeId from list-employees, or eeid from the employee dataset. Do not pass employeeNumber (the editable Employee # value); it may fail with 404 or resolve to a different employee if its value matches another employee's internal employee ID. The sentinel value 0 resolves to the employee record bound to the authenticated user, when one exists; if the credentials are not bound to an employee (for example an integration-style account), 0 returns only {"id": "0"} with no other fields. list-employees does not accept this sentinel.

Query parameters

fieldsstring

Comma-separated list of fields to include in the response. Three reference forms are accepted and may be mixed in a single request: standard field names (e.g. firstName, workEmail), numeric field IDs (e.g. 1349), and custom-field aliases (e.g. customStartDate). Discover all three via List Fields (list-fields) — its response includes id, name, and alias for every available field. Example mixing all three: firstName,1349,customStartDate. When omitted, the response includes only id. Bracket-array (fields[]=...) and repeated-key (fields=a&fields=b) forms are not supported on this endpoint — use the comma-separated form. Unknown or unauthorized fields are silently dropped from the response.

onlyCurrentboolean

When true (the default), returns only currently effective values from historical tables (job, compensation, employment status, etc.). When false, future-dated history rows are also returned.

Headers

AcceptHeaderParameter'application/xml' | 'application/json'

This endpoint can produce either JSON or XML.

Response

An object keyed by field name with the requested employee's values. id is always present and is a string. Fields the authenticated caller cannot view are silently omitted. When Accept: application/xml, the body is an <employee id="..."> element with one <field id="..."> child per returned field.

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