> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-api/user-api/resources/field-service/employee.md).

# Employee

The people working for an account, linked to the trackers, vehicles, and places they work with.

An employee represents a person working for the account. Employees are what make tracking data about people rather than only about hardware: an employee linked to a [tracker](/docs/navixy-api/user-api/resources/tracking/tracker/employee.md) is the driver of whatever that tracker is fitted to, and reports can then attribute trips and behaviour to them.

Employees also link to vehicles and [places](/docs/navixy-api/user-api/resources/field-service/place/work-with-poi.md), belong to [departments](/docs/navixy-api/user-api/resources/field-service/department.md), and carry the [avatar](/docs/navixy-api/user-api/resources/field-service/employee/avatar.md) shown for them in the interface.

## Employee object

## The Employee object

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"Employee":{"type":"object","description":"A person working at the organization: an employee or a driver. Employees can be linked to trackers, vehicles and places.","properties":{"id":{"type":["integer","null"],"description":"Internal ID. May be null or absent when creating."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker currently assigned to this employee. Null means none."},"first_name":{"type":"string","description":"First name. **Cannot be empty.** Up to 100 characters.","minLength":1,"maxLength":100},"middle_name":{"type":"string","description":"Middle name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"last_name":{"type":"string","description":"Last name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"email":{"type":"string","description":"Email address, which must be valid when given. May be empty but **not null**. Up to 100 characters.","maxLength":100},"phone":{"type":"string","description":"Phone number **without the leading `+`**. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_number":{"type":"string","description":"Driver licence number. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_cats":{"type":"string","description":"Driver licence categories. Up to 32 characters.","maxLength":32},"driver_license_issue_date":{"type":["string","null"],"description":"Issue date of the driver licence, as `yyyy-MM-dd`."},"driver_license_valid_till":{"type":["string","null"],"description":"Date the driver licence is valid until, as `yyyy-MM-dd`."},"hardware_key":{"type":["string","null"],"description":"Hardware key, such as an iButton or RFID identifier. Up to 64 characters.","maxLength":64},"icon_id":{"type":["integer","null"],"description":"ID of the assigned icon. **Cannot be set here**: use `employee/avatar/assign`."},"avatar_file_name":{"type":["string","null"],"description":"Name of the uploaded avatar file. **Cannot be set here**: use `employee/avatar/upload`."},"department_id":{"type":["integer","null"],"description":"ID of the department this employee belongs to."},"location":{"type":["object","null"],"description":"Optional. Location associated with this employee. Must be a valid location or null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."},"radius":{"type":"integer","description":"Radius in metres around that point."}}},"personnel_number":{"type":"string","description":"Optional. Personnel number. Up to 15 characters.","maxLength":15},"ssn":{"type":"string","description":"Optional. Social security number. Up to 32 characters.","maxLength":32},"tags":{"type":"array","description":"IDs of tags applied to the employee.","items":{"type":"integer"}}}}}}}
```

The avatar fields are set elsewhere: `icon_id` through [avatar/assign](/docs/navixy-api/user-api/resources/field-service/employee/avatar.md#post-employee-avatar-assign), and `avatar_file_name` through [avatar/upload](/docs/navixy-api/user-api/resources/field-service/employee/avatar.md#post-employee-avatar-upload).

## API actions

API base path: `/employee`.

Operations that list no errors of their own return only the [general error codes](/docs/navixy-api/general/errors.md#error-codes).

***

## List employees

> List the employees and drivers of the current user, with pagination, sorting and a text filter.\
> \
> Callable with an empty body. Also accepts GET with the same parameters as query-string values.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Employees","description":"Employees and drivers, their avatars, spreadsheet import, and the departments they belong to. All resources under the /employee/ and /department/ paths."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"Employee":{"type":"object","description":"A person working at the organization: an employee or a driver. Employees can be linked to trackers, vehicles and places.","properties":{"id":{"type":["integer","null"],"description":"Internal ID. May be null or absent when creating."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker currently assigned to this employee. Null means none."},"first_name":{"type":"string","description":"First name. **Cannot be empty.** Up to 100 characters.","minLength":1,"maxLength":100},"middle_name":{"type":"string","description":"Middle name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"last_name":{"type":"string","description":"Last name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"email":{"type":"string","description":"Email address, which must be valid when given. May be empty but **not null**. Up to 100 characters.","maxLength":100},"phone":{"type":"string","description":"Phone number **without the leading `+`**. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_number":{"type":"string","description":"Driver licence number. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_cats":{"type":"string","description":"Driver licence categories. Up to 32 characters.","maxLength":32},"driver_license_issue_date":{"type":["string","null"],"description":"Issue date of the driver licence, as `yyyy-MM-dd`."},"driver_license_valid_till":{"type":["string","null"],"description":"Date the driver licence is valid until, as `yyyy-MM-dd`."},"hardware_key":{"type":["string","null"],"description":"Hardware key, such as an iButton or RFID identifier. Up to 64 characters.","maxLength":64},"icon_id":{"type":["integer","null"],"description":"ID of the assigned icon. **Cannot be set here**: use `employee/avatar/assign`."},"avatar_file_name":{"type":["string","null"],"description":"Name of the uploaded avatar file. **Cannot be set here**: use `employee/avatar/upload`."},"department_id":{"type":["integer","null"],"description":"ID of the department this employee belongs to."},"location":{"type":["object","null"],"description":"Optional. Location associated with this employee. Must be a valid location or null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."},"radius":{"type":"integer","description":"Radius in metres around that point."}}},"personnel_number":{"type":"string","description":"Optional. Personnel number. Up to 15 characters.","maxLength":15},"ssn":{"type":"string","description":"Optional. Social security number. Up to 32 characters.","maxLength":32},"tags":{"type":"array","description":"IDs of tags applied to the employee.","items":{"type":"integer"}}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/employee/list":{"post":{"tags":["Employees"],"summary":"List employees","description":"List the employees and drivers of the current user, with pagination, sorting and a text filter.\n\nCallable with an empty body. Also accepts GET with the same parameters as query-string values.","operationId":"employeeList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","description":"Pagination. Maximum number of employee records to return."},"offset":{"type":"integer","description":"Pagination. Return employees starting from this offset."},"sort":{"type":"array","description":"Optional. Sort options, each a property and direction such as `first_name=desc`. **At most 2 options per request.** Sortable properties: `id`, `first_name`, `object_label`, `department_label`, `personnel_number`, `hardware_key`, `phone`, `email`, `address`, `driver_license_number`, `driver_license_cats`, `driver_license_valid_till`, and `ssn`.","items":{"type":"string"},"maxItems":2},"filter":{"type":"string","description":"Optional. Text filter. An employee matches when at least one of the sortable properties above contains the string. Up to 100 characters, or null.","maxLength":100}}}}}},"responses":{"200":{"description":"Matching employees","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/Employee"}},"count":{"type":"integer","description":"Total number of employees, ignoring pagination."}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

***

*Required sub-user rights:* `employee_update`.

## Create employee

> Create an employee or driver, and return the ID.\
> \
> \`icon\_id\` and \`avatar\_file\_name\` cannot be set here: they are changed through \`employee/avatar/assign\` and \`employee/avatar/upload\`.\
> \
> Requires the \`employee\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Employees","description":"Employees and drivers, their avatars, spreadsheet import, and the departments they belong to. All resources under the /employee/ and /department/ paths."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"Employee":{"type":"object","description":"A person working at the organization: an employee or a driver. Employees can be linked to trackers, vehicles and places.","properties":{"id":{"type":["integer","null"],"description":"Internal ID. May be null or absent when creating."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker currently assigned to this employee. Null means none."},"first_name":{"type":"string","description":"First name. **Cannot be empty.** Up to 100 characters.","minLength":1,"maxLength":100},"middle_name":{"type":"string","description":"Middle name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"last_name":{"type":"string","description":"Last name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"email":{"type":"string","description":"Email address, which must be valid when given. May be empty but **not null**. Up to 100 characters.","maxLength":100},"phone":{"type":"string","description":"Phone number **without the leading `+`**. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_number":{"type":"string","description":"Driver licence number. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_cats":{"type":"string","description":"Driver licence categories. Up to 32 characters.","maxLength":32},"driver_license_issue_date":{"type":["string","null"],"description":"Issue date of the driver licence, as `yyyy-MM-dd`."},"driver_license_valid_till":{"type":["string","null"],"description":"Date the driver licence is valid until, as `yyyy-MM-dd`."},"hardware_key":{"type":["string","null"],"description":"Hardware key, such as an iButton or RFID identifier. Up to 64 characters.","maxLength":64},"icon_id":{"type":["integer","null"],"description":"ID of the assigned icon. **Cannot be set here**: use `employee/avatar/assign`."},"avatar_file_name":{"type":["string","null"],"description":"Name of the uploaded avatar file. **Cannot be set here**: use `employee/avatar/upload`."},"department_id":{"type":["integer","null"],"description":"ID of the department this employee belongs to."},"location":{"type":["object","null"],"description":"Optional. Location associated with this employee. Must be a valid location or null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."},"radius":{"type":"integer","description":"Radius in metres around that point."}}},"personnel_number":{"type":"string","description":"Optional. Personnel number. Up to 15 characters.","maxLength":15},"ssn":{"type":"string","description":"Optional. Social security number. Up to 32 characters.","maxLength":32},"tags":{"type":"array","description":"IDs of tags applied to the employee.","items":{"type":"integer"}}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/employee/create":{"post":{"tags":["Employees"],"summary":"Create employee","description":"Create an employee or driver, and return the ID.\n\n`icon_id` and `avatar_file_name` cannot be set here: they are changed through `employee/avatar/assign` and `employee/avatar/upload`.\n\nRequires the `employee_update` right.","operationId":"employeeCreate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employee":{"allOf":[{"$ref":"#/components/schemas/Employee"}],"description":"The employee to create. `id` may be null or absent."}},"required":["employee"]}}}},"responses":{"200":{"description":"The created employee","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"id":{"type":"integer","description":"ID of the new employee."}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"409":{"description":"Error 247: an employee with this `hardware_key` or another unique value already exists.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* 247 - Entity already exists.

***

## Read employee

> Return one employee or driver by ID.\
> \
> Also accepts GET with the same parameters as query-string values.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Employees","description":"Employees and drivers, their avatars, spreadsheet import, and the departments they belong to. All resources under the /employee/ and /department/ paths."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"Employee":{"type":"object","description":"A person working at the organization: an employee or a driver. Employees can be linked to trackers, vehicles and places.","properties":{"id":{"type":["integer","null"],"description":"Internal ID. May be null or absent when creating."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker currently assigned to this employee. Null means none."},"first_name":{"type":"string","description":"First name. **Cannot be empty.** Up to 100 characters.","minLength":1,"maxLength":100},"middle_name":{"type":"string","description":"Middle name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"last_name":{"type":"string","description":"Last name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"email":{"type":"string","description":"Email address, which must be valid when given. May be empty but **not null**. Up to 100 characters.","maxLength":100},"phone":{"type":"string","description":"Phone number **without the leading `+`**. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_number":{"type":"string","description":"Driver licence number. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_cats":{"type":"string","description":"Driver licence categories. Up to 32 characters.","maxLength":32},"driver_license_issue_date":{"type":["string","null"],"description":"Issue date of the driver licence, as `yyyy-MM-dd`."},"driver_license_valid_till":{"type":["string","null"],"description":"Date the driver licence is valid until, as `yyyy-MM-dd`."},"hardware_key":{"type":["string","null"],"description":"Hardware key, such as an iButton or RFID identifier. Up to 64 characters.","maxLength":64},"icon_id":{"type":["integer","null"],"description":"ID of the assigned icon. **Cannot be set here**: use `employee/avatar/assign`."},"avatar_file_name":{"type":["string","null"],"description":"Name of the uploaded avatar file. **Cannot be set here**: use `employee/avatar/upload`."},"department_id":{"type":["integer","null"],"description":"ID of the department this employee belongs to."},"location":{"type":["object","null"],"description":"Optional. Location associated with this employee. Must be a valid location or null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."},"radius":{"type":"integer","description":"Radius in metres around that point."}}},"personnel_number":{"type":"string","description":"Optional. Personnel number. Up to 15 characters.","maxLength":15},"ssn":{"type":"string","description":"Optional. Social security number. Up to 32 characters.","maxLength":32},"tags":{"type":"array","description":"IDs of tags applied to the employee.","items":{"type":"integer"}}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/employee/read":{"post":{"tags":["Employees"],"summary":"Read employee","description":"Return one employee or driver by ID.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"employeeRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"integer","description":"ID of the employee.","minimum":1}},"required":["employee_id"]}}}},"responses":{"200":{"description":"The employee","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"value":{"$ref":"#/components/schemas/Employee"}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* 201 - Not found in the database.

***

*Required sub-user rights:* `employee_update`.

## Update employee

> Update an employee or driver. Pass a full employee object including its \`id\`.\
> \
> \`icon\_id\` and \`avatar\_file\_name\` cannot be set here: they are changed through \`employee/avatar/assign\` and \`employee/avatar/upload\`.\
> \
> Requires the \`employee\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Employees","description":"Employees and drivers, their avatars, spreadsheet import, and the departments they belong to. All resources under the /employee/ and /department/ paths."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"Employee":{"type":"object","description":"A person working at the organization: an employee or a driver. Employees can be linked to trackers, vehicles and places.","properties":{"id":{"type":["integer","null"],"description":"Internal ID. May be null or absent when creating."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker currently assigned to this employee. Null means none."},"first_name":{"type":"string","description":"First name. **Cannot be empty.** Up to 100 characters.","minLength":1,"maxLength":100},"middle_name":{"type":"string","description":"Middle name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"last_name":{"type":"string","description":"Last name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"email":{"type":"string","description":"Email address, which must be valid when given. May be empty but **not null**. Up to 100 characters.","maxLength":100},"phone":{"type":"string","description":"Phone number **without the leading `+`**. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_number":{"type":"string","description":"Driver licence number. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_cats":{"type":"string","description":"Driver licence categories. Up to 32 characters.","maxLength":32},"driver_license_issue_date":{"type":["string","null"],"description":"Issue date of the driver licence, as `yyyy-MM-dd`."},"driver_license_valid_till":{"type":["string","null"],"description":"Date the driver licence is valid until, as `yyyy-MM-dd`."},"hardware_key":{"type":["string","null"],"description":"Hardware key, such as an iButton or RFID identifier. Up to 64 characters.","maxLength":64},"icon_id":{"type":["integer","null"],"description":"ID of the assigned icon. **Cannot be set here**: use `employee/avatar/assign`."},"avatar_file_name":{"type":["string","null"],"description":"Name of the uploaded avatar file. **Cannot be set here**: use `employee/avatar/upload`."},"department_id":{"type":["integer","null"],"description":"ID of the department this employee belongs to."},"location":{"type":["object","null"],"description":"Optional. Location associated with this employee. Must be a valid location or null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."},"radius":{"type":"integer","description":"Radius in metres around that point."}}},"personnel_number":{"type":"string","description":"Optional. Personnel number. Up to 15 characters.","maxLength":15},"ssn":{"type":"string","description":"Optional. Social security number. Up to 32 characters.","maxLength":32},"tags":{"type":"array","description":"IDs of tags applied to the employee.","items":{"type":"integer"}}}}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/employee/update":{"post":{"tags":["Employees"],"summary":"Update employee","description":"Update an employee or driver. Pass a full employee object including its `id`.\n\n`icon_id` and `avatar_file_name` cannot be set here: they are changed through `employee/avatar/assign` and `employee/avatar/upload`.\n\nRequires the `employee_update` right.","operationId":"employeeUpdate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employee":{"allOf":[{"$ref":"#/components/schemas/Employee"}],"description":"The employee to update, including its `id`."}},"required":["employee"]}}}},"responses":{"200":{"description":"Employee updated","$ref":"#/components/responses/OK"},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"409":{"description":"Error 247: an employee with this `hardware_key` or another unique value already exists.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* 201 - Not found in the database.
* 247 - Entity already exists.

***

*Required sub-user rights:* `employee_update`.

## Delete employee

> Delete an employee or driver by ID.\
> \
> Also accepts GET with the same parameters as query-string values.\
> \
> Requires the \`employee\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Employees","description":"Employees and drivers, their avatars, spreadsheet import, and the departments they belong to. All resources under the /employee/ and /department/ paths."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/employee/delete":{"post":{"tags":["Employees"],"summary":"Delete employee","description":"Delete an employee or driver by ID.\n\nAlso accepts GET with the same parameters as query-string values.\n\nRequires the `employee_update` right.","operationId":"employeeDelete","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"integer","description":"ID of the employee to delete.","minimum":1}},"required":["employee_id"]}}}},"responses":{"200":{"description":"Employee deleted","$ref":"#/components/responses/OK"},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* 201 - Not found in the database.

***

*Required sub-user rights:* `employee_update`.

## Convert employee batch

> Parse a tab-delimited batch of employees and return them checked, with per-row errors. \*\*Creates nothing.\*\*\
> \
> Give either \`batch\` or \`file\_id\`. \*\*If \`file\_id\` is set, \`batch\` is ignored.\*\* A request with neither returns error 7 with the message "The 'batch' or 'file\_id' parameter must be specified".\
> \
> Requires the \`employee\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Employees","description":"Employees and drivers, their avatars, spreadsheet import, and the departments they belong to. All resources under the /employee/ and /department/ paths."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"CheckedEmployee":{"type":"object","description":"An employee parsed from a batch, with the same fields as an employee plus any per-row problems found while checking it.","properties":{"id":{"type":["integer","null"],"description":"Internal ID. May be null or absent when creating."},"tracker_id":{"type":["integer","null"],"description":"ID of the tracker currently assigned to this employee. Null means none."},"first_name":{"type":"string","description":"First name. **Cannot be empty.** Up to 100 characters.","minLength":1,"maxLength":100},"middle_name":{"type":"string","description":"Middle name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"last_name":{"type":"string","description":"Last name. May be empty but **not null**. Up to 100 characters.","maxLength":100},"email":{"type":"string","description":"Email address, which must be valid when given. May be empty but **not null**. Up to 100 characters.","maxLength":100},"phone":{"type":"string","description":"Phone number **without the leading `+`**. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_number":{"type":"string","description":"Driver licence number. May be empty but not null. Up to 32 characters.","maxLength":32},"driver_license_cats":{"type":"string","description":"Driver licence categories. Up to 32 characters.","maxLength":32},"driver_license_issue_date":{"type":["string","null"],"description":"Issue date of the driver licence, as `yyyy-MM-dd`."},"driver_license_valid_till":{"type":["string","null"],"description":"Date the driver licence is valid until, as `yyyy-MM-dd`."},"hardware_key":{"type":["string","null"],"description":"Hardware key, such as an iButton or RFID identifier. Up to 64 characters.","maxLength":64},"icon_id":{"type":["integer","null"],"description":"ID of the assigned icon. **Cannot be set here**: use `employee/avatar/assign`."},"avatar_file_name":{"type":["string","null"],"description":"Name of the uploaded avatar file. **Cannot be set here**: use `employee/avatar/upload`."},"department_id":{"type":["integer","null"],"description":"ID of the department this employee belongs to."},"location":{"type":["object","null"],"description":"Optional. Location associated with this employee. Must be a valid location or null.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point."},"radius":{"type":"integer","description":"Radius in metres around that point."}}},"personnel_number":{"type":"string","description":"Optional. Personnel number. Up to 15 characters.","maxLength":15},"ssn":{"type":"string","description":"Optional. Social security number. Up to 32 characters.","maxLength":32},"tags":{"type":"array","description":"IDs of tags applied to the employee.","items":{"type":"integer"}},"errors":{"type":"array","description":"Optional. Problems found in this row.","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/employee/batch_convert":{"post":{"tags":["Employees"],"summary":"Convert employee batch","description":"Parse a tab-delimited batch of employees and return them checked, with per-row errors. **Creates nothing.**\n\nGive either `batch` or `file_id`. **If `file_id` is set, `batch` is ignored.** A request with neither returns error 7 with the message \"The 'batch' or 'file_id' parameter must be specified\".\n\nRequires the `employee_update` right.","operationId":"employeeBatchConvert","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"string","description":"Batch of tab-delimited employees."},"file_id":{"type":"string","description":"Preloaded file ID. Takes precedence over `batch`."},"fields":{"type":"array","description":"Optional. Column names, in order. Defaults to `[\"first_name\", \"middle_name\", \"last_name\", \"email\", \"phone\"]`.","items":{"type":"string"}},"geocoder":{"type":"string","description":"Geocoder type to use for resolving addresses."},"default_radius":{"type":"integer","description":"Optional. Default 100. Radius in metres for a row that gives no radius."}}}}}},"responses":{"200":{"description":"The checked batch","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/CheckedEmployee"}},"limit_exceeded":{"type":"boolean","description":"`true` if the given batch was constrained by a limit."}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"402":{"description":"Error 234: the batch or file could not be parsed.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* 234 - Invalid data format.

## More in this section

#### Employee avatar

| Endpoint                                                                                                                      | Method | What it does           |
| ----------------------------------------------------------------------------------------------------------------------------- | ------ | ---------------------- |
| [`/employee/avatar/assign`](/docs/navixy-api/user-api/resources/field-service/employee/avatar.md#post-employee-avatar-assign) | POST   | Assign employee icon   |
| [`/employee/avatar/upload`](/docs/navixy-api/user-api/resources/field-service/employee/avatar.md#post-employee-avatar-upload) | POST   | Upload employee avatar |

#### Employee import

| Endpoint                                                                                                                                        | Method | What it does                  |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------- |
| [`/employee/import/start`](/docs/navixy-api/user-api/resources/field-service/employee/import.md#post-employee-import-start)                     | POST   | Start employee import         |
| [`/employee/import/read`](/docs/navixy-api/user-api/resources/field-service/employee/import.md#post-employee-import-read)                       | POST   | Read employee import          |
| [`/employee/import/list`](/docs/navixy-api/user-api/resources/field-service/employee/import.md#post-employee-import-list)                       | POST   | List employee imports         |
| [`/employee/import/download_failed`](/docs/navixy-api/user-api/resources/field-service/employee/import.md#post-employee-import-download_failed) | POST   | Download failed employee rows |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://navixy.com/docs/navixy-api/user-api/resources/field-service/employee.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.