# Employees

Employees are the people working in your organisation. Use these
endpoints to list employees; to map a Dyflexis employee to an external
personnel number; and to create or update an external employee
record from your own HR or payroll system.

Three list endpoints are exposed under different token scopes so
each consumer sees only the data its scope is allowed to read:
`business`, `clock`, and `payroll`.


## List employees

 - [GET /api/business/v3/employees](https://beta-developer.dyflexis.com/openapi/employees/listbusinessemployees.md): Requires scope: business.

Fetches all active employees, their labels, and their card numbers.

## List personnel numbers

 - [GET /api2/employee-mappings](https://beta-developer.dyflexis.com/openapi/employees/listpersonnelnumbers.md): Requires scope: employee_mappings.

> Legacy, Kept for existing integrations. New integrations should use GET /api/business/v3/employees, which returns the same mapping (employeeId and personnelNumber) along with the full employee record.

Returns a list of personnel numbers and their corresponding Dyflexis employee ids. Employees that do not have a personnel number will be omitted.

## Create or update an employee

 - [POST /api2/external-employees/{employeeReference}](https://beta-developer.dyflexis.com/openapi/employees/createorupdateemployee.md): Requires scope: external_employees.

You can use this endpoint to send employee data to Dyflexis. This will create an external employee in Dyflexis, or update an existing external employee if one with the same unique reference already exists.

An external employee will need to be connected to either an existing or a new Dyflexis employee within the Dyflexis application. An administrator can do this by using the widget in the employee overview page, or by using the external employee connection settings screen.

Once connected, the Dyflexis employee will be kept in sync with the external employee whenever data is sent to this endpoint.