🚧
This particular endpoint uses r_employees scope, which can be enabled through the Integrations section found within the Settings menu.

Results

Calling the /employees endpoint will return a collection of the available employees for the account. If you are using an account level token you will get only published employees with publicly available info. To get all types of employees there is a need to add member_id of an hr admin. There are some query parameters that can be used to paginate through the results. By using the offset one can control the starting point of the list and by using the limit one can control the returned size of the list. By using the order_by one can control the ordering by department or division. Finally, there is a query parameter that can be used to search through the firstname, lastname and email fields. An example of the response follows:

{
    "totalCount": 72,
    "employees": [
        {
            "id": "2fbc",
            "firstname": "Rex",
            "lastname": "Abernathy",
            "email": "rex_abernathy@sampleemployee.com",
            "start_date": "2021-10-08T00:00:00.000Z",
            "state": "published",
            "employee_number": "5",
            "avatar": "https://officedroid-hris.s3.amazonaws.com/demo/avatars/men/2.jpeg?AWSAccessKeyId=AKIAZ2DSJVUU35ZD65CF&Expires=1693593051&Signature=y%2BLxX2muLIYU1u2GTSmJfigCi%2F8%3D",
            "phone": "+18579909723",
            "address": "London Road, Highfield, Sheffield, UK",
            "job_title": "Account Manager ",
            "manager_id": "2fce",
            "department_id": "3ff4d641",
            "template_id": null,
            "division_id": null,
            "candidate_id": null,
            "roles": null,
            "legal_entity_id": "e697173f-5853-48c0-8eb4-b9c67ca11a93",
            "work_schedule_id": "5c6",
            "work_email": "rex_abernathy@sampleemployee.com"
        },
        {
            "id": "2fb6",
            "firstname": "Okey",
            "lastname": "Adams",
            "email": "okey_adams@sampleemployee.com",
            "start_date": "2022-06-17T00:00:00.000Z",
            "state": "published",
            "employee_number": "41",
            "avatar": "https://officedroid-hris.s3.amazonaws.com/demo/avatars/men/20.jpeg?AWSAccessKeyId=AKIAZ2DSJVUU35ZD65CF&Expires=1693593051&Signature=RqeRPkykyiKcTVorfkOXEA7I5PQ%3D",
            "phone": "857-990-9703",
            "address": "95737 Dessie Place",
            "job_title": "Senior Account Executive ",
            "manager_id": "2fb5",
            "department_id": "3ff4d647",
            "template_id": null,
            "division_id": null,
            "candidate_id": null,
            "roles": null,
            "legal_entity_id": null,
            "work_schedule_id": null,
            "work_email": "okey_adams@sampleemployee.com"
        },
    ...  // The pattern continues for other objects in the list
  ]
}

Each employee will have the following keys:

key	type	description
id	`string`	The employee identifier
firstname	`string`	The first name of the employee
lastname	`string`	The last name of the employee
email	`string`	The email that has been assigned to the employee
start_date	`string`	Indicates the start data of the employee profile
state	`string`	The state of the employee. Available values are `draft`, `published` and `inactive`. More information can be found here
employee_number	`string`	The unique identifier for each employee, often used for payroll or HR tracking purposes
avatar	`string`	A url to the image representing the employee, used for profile pictures or directory listings. The image has an expiry time of 1 hour
phone	`string`	The direct contact number for the employee, used for communication or emergency contact purposes
job_title	`string`	The designated role or position that the employee holds within the company, such as 'Software Engineer' or 'Product Manager'
manager_id	`string`	A reference to the unique identifier of the employee's direct supervisor or manager, allowing for hierarchy representation
department_id	`string`	A reference to the unique identifier of the department or team the employee is part of, aiding in organizational structuring. Refers to the id that can be retrieved from calling the `/departments` endpoint
template_id	`string`	A reference to the unique identifier of the employee profile template that was used to depict information for this employee
division_id	`string`	A reference to the unique identifier of a specific division or business unit within the company. Helps in grouping employees based on business segments or specialized teams
candidate_id	`string`	The unique identifier of the candidate that was hired for a requisition that was filled in by the Applicant Tracking System
legal_entity_id	`string`	Refers to the unique identifier of the legal entity that the employee is associated with. Especially useful in conglomerates or multinational corporations with multiple legal entities. Refers to the id that can be retrieved from calling the `legal_entities` endpoint
work_schedule_id	`string`	A reference to the unique identifier for an employee's assigned work schedule. This links to details like working hours, shifts, or special arrangements. Refers to the id that can be retrieved from calling the `/work_schedules` endpoint
work_email	`string`	The official company email address assigned to the employee. Used for professional communication and work-related correspondence

Employee State

1. Draft

Initial State: When an HR administrator creates a new employee profile, it starts in the "draft" state. Same applies when the employee profile is rehired (applicable for inactive). Remains in this status until an HR Admin publishes the profile to the rest employees
Visibility: Profiles in the draft state are not visible to anyone except users with the hr_admin role and the management line of the profile
Usage: The draft state is typically used to initiate the onboarding process. This allows HR administrators to prepare an employee's profile and complete any relevant tasks before making the profile publicly visible within the company.

2. Published

Transition: Once the onboarding tasks are completed, the HR administrator can change the employee's profile state from "draft" to "published". Remains in this status until Offboarding is complete or there is no active "Empoyment"
Visibility: Once published, the employee's public information becomes visible in the employee directory. Additionally, the employee's profile will appear in the organization chart of the account
Implication: This indicates that the employee is now officially a part of the company, with their details accessible to other employees (as allowed by the organization's visibility settings). This status is eligible for off boarding

3. Inactive

Meaning: This state suggests that the employee is no longer active within the company. This could be due to various reasons like resignation, retirement, or any other form of separation. This state is enabled when off boarding is complete or when an end date exists in all employment entries and is in the past
Visibility: Depending on the organization's policy, inactive profiles might be hidden from the general directory to avoid confusion. Is visible to HR Admins and the management line of the profile when they update the filter in employee directory. Can be moved to draft for cases of re-hiring

Workflow Overview:

Profile Creation: HR administrator creates a new employee profile -> Profile is in the draft state.
Onboarding: HR administrator uses the draft profile to handle onboarding tasks and prepare the profile.
Profile Publishing: Once onboarding is completed, the HR administrator publishes the profile -> Profile state changes to published.
Profile Deactivation (If Applicable): If an employee leaves or separates from the company for any reason, their profile might be marked as inactive.

This system allows for a seamless transition of an employee's journey in a company, from their onboarding process to their eventual departure, while ensuring that the right people have access to the right information at the right time.