/employees

Returns a collection of your account employees. Required scope: r_employees.

🚧

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:

JSON

{
    "totalCount": 72,
    "employees": [
        {
            "id": "2fbc",
            "firstname": "Rex",
            "lastname": "Abernathy",
            "email": "[email protected]",
            "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": "[phone]",
            "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": "[email protected]"
        },
        {
            "id": "2fb6",
            "firstname": "Okey",
            "lastname": "Adams",
            "email": "[email protected]",
            "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": "[email protected]"
        },
    ...  // 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:

1. Profile Creation: HR administrator creates a new employee profile -> Profile is in the draft state.
2. Onboarding: HR administrator uses the draft profile to handle onboarding tasks and prepare the profile.
3. Profile Publishing: Once onboarding is completed, the HR administrator publishes the profile -> Profile state changes to published.
4. 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.