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 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, belong to departments, and carry the avatar shown for them in the interface.
Employee object
The avatar fields are set elsewhere: icon_id through avatar/assign, and avatar_file_name through avatar/upload.
API actions
API base path: /employee.
Operations that list no errors of their own return only the general error codes.
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.
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.
Pagination. Maximum number of employee records to return.
Pagination. Return employees starting from this offset.
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.
Optional. Text filter. An employee matches when at least one of the sortable properties above contains the string. Up to 100 characters, or null.
Matching employees
true if request finished successfully.
trueTotal number of employees, ignoring pagination.
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.
Error response object
POST /v2/employee/list HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 54
{
"limit": 1,
"offset": 1,
"sort": [
"text"
],
"filter": "text"
}{
"success": true,
"list": [
{
"id": null,
"tracker_id": null,
"first_name": "text",
"middle_name": "text",
"last_name": "text",
"email": "text",
"phone": "text",
"driver_license_number": "text",
"driver_license_cats": "text",
"driver_license_issue_date": null,
"driver_license_valid_till": null,
"hardware_key": null,
"icon_id": null,
"avatar_file_name": null,
"department_id": null,
"location": {
"lat": 1,
"lng": 1,
"address": "text",
"radius": 1
},
"personnel_number": "text",
"ssn": "text",
"tags": [
1
]
}
],
"count": 1
}Required sub-user rights: employee_update.
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.
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.
The created employee
true if request finished successfully.
trueID of the new employee.
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.
Error 247: an employee with this hardware_key or another unique value already exists.
Error response object
POST /v2/employee/create HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 445
{
"employee": {
"id": null,
"tracker_id": null,
"first_name": "text",
"middle_name": "text",
"last_name": "text",
"email": "text",
"phone": "text",
"driver_license_number": "text",
"driver_license_cats": "text",
"driver_license_issue_date": null,
"driver_license_valid_till": null,
"hardware_key": null,
"icon_id": null,
"avatar_file_name": null,
"department_id": null,
"location": {
"lat": 1,
"lng": 1,
"address": "text",
"radius": 1
},
"personnel_number": "text",
"ssn": "text",
"tags": [
1
]
}
}{
"success": true,
"id": 1
}Errors
These errors come in addition to the general error codes:
247 - Entity already exists.
Return one employee or driver by ID.
Also accepts GET with the same parameters as query-string values.
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.
ID of the employee.
The employee
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error response object
POST /v2/employee/read HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"employee_id": 1
}{
"success": true,
"value": {
"id": null,
"tracker_id": null,
"first_name": "text",
"middle_name": "text",
"last_name": "text",
"email": "text",
"phone": "text",
"driver_license_number": "text",
"driver_license_cats": "text",
"driver_license_issue_date": null,
"driver_license_valid_till": null,
"hardware_key": null,
"icon_id": null,
"avatar_file_name": null,
"department_id": null,
"location": {
"lat": 1,
"lng": 1,
"address": "text",
"radius": 1
},
"personnel_number": "text",
"ssn": "text",
"tags": [
1
]
}
}Errors
These errors come in addition to the general error codes:
201 - Not found in the database.
Required sub-user rights: employee_update.
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.
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.
Employee updated
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error 247: an employee with this hardware_key or another unique value already exists.
Error response object
POST /v2/employee/update HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 445
{
"employee": {
"id": null,
"tracker_id": null,
"first_name": "text",
"middle_name": "text",
"last_name": "text",
"email": "text",
"phone": "text",
"driver_license_number": "text",
"driver_license_cats": "text",
"driver_license_issue_date": null,
"driver_license_valid_till": null,
"hardware_key": null,
"icon_id": null,
"avatar_file_name": null,
"department_id": null,
"location": {
"lat": 1,
"lng": 1,
"address": "text",
"radius": 1
},
"personnel_number": "text",
"ssn": "text",
"tags": [
1
]
}
}{
"success": true
}Errors
These errors come in addition to the general error codes:
201 - Not found in the database.
247 - Entity already exists.
Required sub-user rights: employee_update.
Delete an employee or driver by ID.
Also accepts GET with the same parameters as query-string values.
Requires the employee_update right.
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.
ID of the employee to delete.
Employee deleted
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error response object
POST /v2/employee/delete HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"employee_id": 1
}{
"success": true
}Errors
These errors come in addition to the general error codes:
201 - Not found in the database.
Required sub-user rights: employee_update.
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.
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.
Batch of tab-delimited employees.
Preloaded file ID. Takes precedence over batch.
Optional. Column names, in order. Defaults to ["first_name", "middle_name", "last_name", "email", "phone"].
Geocoder type to use for resolving addresses.
Optional. Default 100. Radius in metres for a row that gives no radius.
The checked batch
true if request finished successfully.
truetrue if the given batch was constrained by a limit.
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.
Error 234: the batch or file could not be parsed.
Error response object
POST /v2/employee/batch_convert HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 88
{
"batch": "text",
"file_id": "text",
"fields": [
"text"
],
"geocoder": "text",
"default_radius": 1
}{
"success": true,
"list": [
{
"id": null,
"tracker_id": null,
"first_name": "text",
"middle_name": "text",
"last_name": "text",
"email": "text",
"phone": "text",
"driver_license_number": "text",
"driver_license_cats": "text",
"driver_license_issue_date": null,
"driver_license_valid_till": null,
"hardware_key": null,
"icon_id": null,
"avatar_file_name": null,
"department_id": null,
"location": {
"lat": 1,
"lng": 1,
"address": "text",
"radius": 1
},
"personnel_number": "text",
"ssn": "text",
"tags": [
1
],
"errors": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"limit_exceeded": true
}Errors
These errors come in addition to the general error codes:
234 - Invalid data format.
More in this section
Employee avatar
Employee import
Last updated
Was this helpful?