# 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](https://www.navixy.com/docs/navixy-api/user-api/backend-api/resources/field-service/avatar#assign).
* `avatar_file_name` - string. A name of the updated avatar file. Nullable, can only be updated\
  via [avatar/upload](https://www.navixy.com/docs/navixy-api/user-api/backend-api/resources/field-service/avatar#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](https://www.navixy.com/docs/navixy-api/user-api/errors#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.