Mertrack API docs
/

#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

{
    "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.
  • avatar_file_name - string. A name of the updated avatar file. Nullable, can only be updated
    via 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

Optional. Set of sort options. Each option is a pair of property name and sorting direction, e.g. ["first_name=desc","object_label=asc"]. Maximum 2 options in request. Available 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
- driver_license_valid_till
- ssn

 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

curl -X POST 'https://api.mergroup.be/employee/list' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b"}'
https://api.mergroup.be/employee/list?hash=a6aa75587e5c59c32d347da438505fc3

#Response

{
    "success": true,
    "list": [<employee>],
    "count": 12
}
  • list - a list of employees.
  • count - int. Total number of employees (ignoring offset and limit).

#Errors

General types only.

#create

Creates a new employee/driver.

required sub-user rights: employee_update.

#Parameters

name description type
employee An employee object without id field. Non-null. JSON object

#Example

cURL

curl -X POST 'https://api.mergroup.be/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]}'

#Response

{
    "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

curl -X POST 'https://api.mergroup.be/employee/read' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "employee_id": 111}'
https://api.mergroup.be/employee/read?hash=a6aa75587e5c59c32d347da438505fc3&employee_id=111

#Response

{
    "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 with id field. Non-null. JSON object

#Example

cURL

curl -X POST 'https://api.mergroup.be/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]}'

#Response

{ "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

curl -X POST 'https://api.mergroup.be/employee/delete' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "employee_id": 111}'
https://api.mergroup.be/employee/delete?hash=a6aa75587e5c59c32d347da438505fc3&employee_id=111

#Response

{ "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

{
    "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.