# Working with employees and drivers

Employees and drivers used to represent people working at one's organization. They can be linked with other entities such as trackers, vehicles, places, etc.

## Employee object

```json
{
    "id": 222,
    "tracker_id": null,
    "first_name": "John",
    "middle_name": "Jane",
    "last_name": "Smith",
    "email": "smith@example.com",
    "phone": "442071111111",
    "driver_license_number": "SKIMP407952HJ9GK 06",
    "driver_license_cats": "C",
    "driver_license_issue_date": "2008-01-01",
    "driver_license_valid_till": "2018-01-01",
    "hardware_key": null,
    "icon_id" : 55,
    "avatar_file_name": null,
    "department_id": null,
    "location": {
        "lat": 52.5,
        "lng": 13.4,
        "address": "Engeldamm 18"
    },
    "personnel_number": "1059236",
    "ssn": "123-45-6789",
    "tags": [1,2]
}
```

* `id` - int. Internal ID. Can be passed as null only for "create" action.
* `tracker_id` - int. An ID of the tracker currently assigned to this employee or driver. `null` means no tracker assigned.
* `first_name` - string. First name. Cannot be empty. Max 100 characters.
* `middle_name` - string. Middle name. Can be empty, cannot be null. Max 100 characters.
* `last_name` - string. Last name. Can be empty, cannot be null. Max 100 characters.
* `email` - string. Employee's email. Must be valid email address. Can be empty, cannot be null. Max 100 characters.
* `phone` - string. Employee's phone without "+" sign. Can be empty, cannot be null. Max 32 characters.
* `driver_license_number` - string. Driver license number. Can be empty, cannot be null. Max 32 characters.
* `driver_license_cats` - string. Driver license categories. Max 32 characters.
* `driver_license_issue_date` - string date (yyyy-MM-dd). Issue date of a driver license. Can be null.
* `driver_license_valid_till` - string date (yyyy-MM-dd). Date till a driver license valid. Can be null.
* `hardware_key` - string. A hardware key. Can be null. Max 64 characters.
* `icon_id` - int. An icon ID. Can be null, can only be updated via [avatar/assign](/docs/navixy-api/user-api/backend-api/resources/field-service/employee/avatar.md#assign).
* `avatar_file_name` - string. A name of the updated avatar file. Nullable, can only be updated\
  via [avatar/upload](/docs/navixy-api/user-api/backend-api/resources/field-service/employee/avatar.md#upload).
* `department_id` - int. An ID of the department to which employee assigned. Can be null.
* `location` - optional object. Location associated with this employee, should be valid or null.
  * `address` - string. Address of the location.
* `personnel_number` - optional string. Max length is 15.
* `ssn` - optional string. Social Security number. Max length is 32.
* `tags` - int array. List of tag IDs.

## API actions

API base path: `/employee`.

### list

Gets all employees and drivers belonging to user.

#### Parameters

| name   | description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | type         |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| limit  | Pagination. Maximum number of employee records to return.                                                                                                                                                                                                                                                                                                                                                                                                                                                     | int          |
| offset | Pagination. Get employee records starting from.                                                                                                                                                                                                                                                                                                                                                                                                                                                               | int          |
| sort   | <p>Optional. Set of sort options. Each option is a pair of property name and sorting direction, e.g. <code>\["first\_name=desc","object\_label=asc"]</code>. Maximum 2 options in request. Available properties:<br>- ID<br>- first\_name<br>- object\_label<br>- department\_label<br>- personnel\_number<br>- hardware\_key<br>- phone<br>- email<br>- address<br>- driver\_license\_number<br>- driver\_license\_cats<br>- driver\_license\_valid\_till<br>- driver\_license\_valid\_till<br>- ssn<br></p> | string array |
| filter | Get a list of employees filtered by properties, at least one property must contain the desired string. All properties from the sorting list are used in filtering. Maximum 100 characters or null.                                                                                                                                                                                                                                                                                                            | string       |

#### Examples

{% tabs %}
{% tab title="cURL" %}

```sh
curl -X POST 'https://api.eu.navixy.com/v2/employee/list' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b"}'
```

{% endtab %}

{% tab title="HTTP GET" %}

```http
https://api.eu.navixy.com/v2/employee/list?hash=a6aa75587e5c59c32d347da438505fc3
```

{% endtab %}
{% endtabs %}

#### Response

```json
{
    "success": true,
    "list": [<employee>],
    "count": 12
}
```

* `list` - a list of employees.
* `count` - int. Total number of employees (ignoring offset and limit).

#### Errors

[General](/docs/navixy-api/user-api/backend-api/errors.md#error-codes) types only.

### create

Creates a new employee/driver.

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

#### Parameters

| name     | description                                                          | type        |
| -------- | -------------------------------------------------------------------- | ----------- |
| employee | An [employee object](#employee-object) without `id` field. Non-null. | JSON object |

#### Example

cURL

{% code overflow="wrap" %}

```sh
curl -X POST 'https://api.eu.navixy.com/v2/employee/create' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "employee": {"tracker_id": 625987, "first_name": "John", "middle_name": "Jane", "last_name": "Smith", "email": "smith@example.com", "phone": "442071111111", "driver_license_number": "SKIMP407952HJ9GK 06", "driver_license_cats": "C", "driver_license_valid_till": "2018-01-01", "hardware_key": null, "icon_id" : 55, "avatar_file_name": null, "department_id": null, "location": {"lat": 52.5, "lng": 13.4, "address": "Engeldamm 18"}, "personnel_number": "1059236", "tags": [1,2]}'
```

{% endcode %}

#### Response

```json
{
    "success": true,
    "id": 111
}
```

* `id` - int. An ID of the created employee (driver).

#### Errors

* 247 – Entity already exists, if `tracker_id`!=null and exists an employee that already bound to this `tracker_id`.

### read

Gets employee/driver by his ID.

#### Parameters

| name         | description        | type |
| ------------ | ------------------ | ---- |
| employee\_id | ID of an employee. | int  |

#### Examples

{% tabs %}
{% tab title="cURL" %}

```sh
curl -X POST 'https://api.eu.navixy.com/v2/employee/read' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "employee_id": 111}'
```

{% endtab %}

{% tab title="HTTP GET" %}
{% code overflow="wrap" %}

```http
https://api.eu.navixy.com/v2/employee/read?hash=a6aa75587e5c59c32d347da438505fc3&employee_id=111
```

{% endcode %}
{% endtab %}
{% endtabs %}

#### Response

```json
{
    "success": true,
    "value": {
     "id": 222,
     "tracker_id": null,
     "first_name": "John",
     "middle_name": "Jane",
     "last_name": "Smith",
     "email": "smith@example.com",
     "phone": "442071111111",
     "driver_license_number": "SKIMP407952HJ9GK 06",
     "driver_license_cats": "C",
     "driver_license_issue_date": "2008-01-01",
     "driver_license_valid_till": "2018-01-01",
     "hardware_key": null,
     "icon_id" : 55,
     "avatar_file_name": null,
     "department_id": null,
     "location": {
         "lat": 52.5,
         "lng": 13.4,
         "address": "Engeldamm 18"
     },
     "personnel_number": "1059236",
     "ssn": "123-45-6789",
     "tags": [1,2]
 }
}
```

* `value` - an employee object.

#### Errors

* 201 – Not found in the database - if there is no employee/driver with such an ID.

### update

Updates existing employee/driver.

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

#### Parameters

| name     | description                                                       | type        |
| -------- | ----------------------------------------------------------------- | ----------- |
| employee | An [employee object](#employee-object) with `id` field. Non-null. | JSON object |

#### Example

cURL

{% code overflow="wrap" %}

```sh
curl -X POST 'https://api.eu.navixy.com/v2/employee/update' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "employee": {"id": 111, "tracker_id": 625987, "first_name": "John", "middle_name": "Jane", "last_name": "Smith", "email": "smith@example.com", "phone": "442071111111", "driver_license_number": "SKIMP407952HJ9GK 06", "driver_license_cats": "C", "driver_license_valid_till": "2018-01-01", "hardware_key": null, "icon_id" : 55, "avatar_file_name": null, "department_id": null, "location": {"lat": 52.5, "lng": 13.4, "address": "Engeldamm 18"}, "personnel_number": "1059236", "tags": [1,2]}'
```

{% endcode %}

#### Response

```json
{ "success": true }
```

#### Errors

* 201 – Not found in the database - if there is no employee/driver with such an ID.
* 247 – Entity already exists, if `tracker_id`!=null and exists an employee that already bound to this `tracker_id`.

### delete

Deletes an employee/driver with the specified ID.

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

#### Parameters

| name         | description                           | type |
| ------------ | ------------------------------------- | ---- |
| employee\_id | ID of an employee (driver) to delete. | int  |

#### Examples

{% tabs %}
{% tab title="cURL" %}

```sh
curl -X POST 'https://api.eu.navixy.com/v2/employee/delete' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "employee_id": 111}'
```

{% endtab %}

{% tab title="HTTP GET" %}
{% code overflow="wrap" %}

```http
https://api.eu.navixy.com/v2/employee/delete?hash=a6aa75587e5c59c32d347da438505fc3&employee_id=111
```

{% endcode %}
{% endtab %}
{% endtabs %}

#### Response

```json
{ "success": true }
```

#### Errors

* 201 – Not found in the database - if there is no employee/driver with such an ID.

### batch\_convert

Converts batch of tab-delimited employees/drivers and returns list of checked employees/drivers with errors.

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

#### Parameters

| name            | description                                                                                                | type         |
| --------------- | ---------------------------------------------------------------------------------------------------------- | ------------ |
| batch           | Batch of tab-delimited employees/drivers.                                                                  | string       |
| file\_id        | Preloaded file ID.                                                                                         | string       |
| fields          | Optional. Array of field names. Default is `["first_name", "middle_name", "last_name", "email", "phone"]`. | string array |
| geocoder        | Geocoder type.                                                                                             | string       |
| default\_radius | Optional. Radius for point in meters. Default is 100.                                                      | int          |

* If `file_id` is set – `batch` parameter will be ignored.

#### Response

```json
{
    "success": true,
    "list": [{
      "success": true,
      "value": {
        "id": 222,
        "tracker_id": null,
        "first_name": "John",
        "middle_name": "Jane",
        "last_name": "Smith",
        "email": "smith@example.com",
        "phone": "442071111111",
        "driver_license_number": "SKIMP407952HJ9GK 06",
        "driver_license_cats": "C",
        "driver_license_issue_date": "2008-01-01",
        "driver_license_valid_till": "2018-01-01",
        "hardware_key": null,
        "icon_id": 55,
        "avatar_file_name": null,
        "department_id": null,
        "location": {
          "lat": 52.5,
          "lng": 13.4,
          "address": "Engeldamm 18"
        },
        "personnel_number": "1059236",
        "ssn": "123-45-6789",
        "tags": [
          1,
          2
        ],
        "errors": <array_of_objects>
      }
    }],
    "limit_exceeded": false    
}
```

* `list` - list of checked employees/drivers.
  * `errors` - optional array of errors.
* `limit_exceeded` - boolean. `true` if given batch constrained by a limit.

#### Errors

* 234 - Invalid data format.


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.