SafeFleet User API
version 2.2
Contents
  1. Base Concepts
  2. Authentication
  3. SafeFleet Objects
  4. Available Endpoints
  5. Tables Of Constants
  6. Example
  1. Base Concepts
  2. This API is a RESTful API implemented using Django/Python technologies, everything being based on HTTP. A client for this service would perform a couple of simple HTTP requests to the server. The default SafeFleet API server address is api.safefleet.eu, on TCP port 443 (HTTPS).
    Requests
    The base path that the requests are made to has the following format:
    /safefleet/api/{version}/{endpoint}
    where version is an optional part of the path indicating a specific API version to be used and endpoint is one of the available endpoints.

    For details on available API versions and how to use them see API Versions.

    Values are transmitted in the request body and must be in JSON format. Don't forget to set the request content type to application/json.
    Responses
    The actual response is given by the server in the body section. The format used is JSON, encoded using UTF-8 text and with a content type of application/json. In case of an error, the server returns a corresponding message. For example, when an object cannot be found the response body looks like this:
    {"message": "object not found: vehicle_id=128"},
    having a status code of 404 Not Found (see status codes for more details).
    Conventions
    All dates are UTC and are transmitted (from and to the server) in ISO 8601 format:

    All countries are transmitted as ISO 3166-1 alpha-2 capital two-letter country codes (e.g. FR for France).
    Phone numbers are always preceded by a + sign and must include the country prefix.

    These are the conventional units used for the various values throughout the API:

    Constraints
    The number of requests per second is limited on a per company basis. The following constraints are imposed: When any of these limits is exceeded, a 503 Service Unavailable status will be returned.
    Status Codes
    HTTP status codes are used to inform the client about the way the request was processed. Any errors that have been encountered while processing the request are signaled using these codes, as follows:
    API Versions
    In order to be able to improve the API while preserving backwards compatibility with existing clients, the SafeFleet API interface allows specifying a desired version in the URI.

    A complete version string has the following format: vX.Y (e.g. v1.1), where X is the major version and Y is the minor version. The current major version is 2. We only plan to change the major version when we redesign major parts of the API.

    Minor versions, however, change more often. Whenever we update the parameters or the response format of an endpoint, or whenever we rename or remove an endpoint, we'll update the minor version.

    This being said, if you want to always use the latest version and you're prepared to quickly adapt your code to our changes, just don't specify any version at all, e.g.:
    /safefleet/api/{endpoint}
    If you want to use the latest minor version of a specific major version, specify only the major version, e.g.:
    /safefleet/api/v2/{endpoint}
    If you want to use a precise version because you don't plan to update your API client code too often, specify it entirely, e.g.:
    /safefleet/api/v2.0/{endpoint}
  3. Authentication
  4. Two different authentication methods are accepted by the API. Choosing one or another depends strictly on the purpose of the API client.

    It is important to note that both of these authentication methods require an existent user in the system, and that the user can be configured to work with only one method, not with both.
    Session-based Authentication
    This is the most commonly used method and requires a pair of username and password values to be sent to the server once, at the beginning of the session. The user is identified by its unique username.

    The mechanism is based on a session id transmitted through an HTTP cookie named sessionid. More precisely, the server maintains a session for an authenticated user for a couple of days. If this session has expired, or just doesn't exist yet, the server will respond with a 403 Forbidden to any regular request, with an error message saying {"message": "authentication required"}.

    To open a new session, a call to a special authenticate endpoint must be requested. This endpoint takes the username and the password as parameters. The request must use the POST method.
    In case of successful authentication, the server responds with 200 OK and the content {"message": "ok"}. In case of unsuccessful authentication, 403 Forbidden is returned and the error message is {"message": "authentication failed"}.

    Upon successful authentication, the server normally responds directly with the content {"message": "ok"}, and offers the client the session id in a cookie. This session id must be included as a cookie with any further requests.
    If however, the user resides on a different server, the URL of this server is returned, and the client is required to change its base URL accordingly. This "soft" redirect actually indicates that the user, together with the whole customer data reside on a different server (also called instance), and points the API client to that instance's URL. Here's an example of such an answer:
    {"url": "http://instance13.safefleet.eu/safefleet/api"}
    The redirect was implemented to allow starting with a single common URL as an entry point for anyone using the SafeFleet API, regardless of the server on which the user is stored. The API client should be written in such a way that it is aware of this case.

    For users with 2FA enabled, an additional authentication step is necessary to send the 2FA code. After the first authentication call on the final instance, 403 Forbidden is returned with the content set to {"message": "2fa code required"}. In this case, the client must re-issue the authentication request, including the 2FA code (along with username and password).

    Client ID-based Authentication
    This authentication mechanism should be used when there is only one user that the API client works with, and this user never changes. The user is in fact associated to the API client and thus uniquely identifies the client on the server. Hence the parameter called client_id which is used instead of a username or a sessionid.

    Moreover, there is no session and the authentication information has to be transmitted with every request. This is not a security issue thanks to the use of a signature which is based on a shared secret and the timestamp of the request. The secret is never transmitted between the server and the client. The signature is computed using the following formula:
    signature = sha1(secret + timestamp),
    where the secret and the timestamp (in seconds since Epoch) are concatenated as strings, and the signature itself is expressed as string, in lowercase hex digits.

    Now the following three parameters have to be sent with each request, in addition to the parameters that are normally required by the endpoint: A time skew of at most ±5 minutes is accepted between the client and the server's timestamps.

  5. SafeFleet Objects
  6. The information maintained by the SafeFleet system is structured in a hierarchy of objects, as shown in the following figure:

    The SafeFleet objects and their relations

    The system manages a number of companies, each company having one or more fleets. These fleets may have other subfleets of their own, thus creating a tree structure of fleets with as many levels as necessary. At any level (i.e. under any fleet), different types of objects can be found. As depicted in the diagram, these objects may be users, vehicles, drivers, points of interest (POIs), regions of interest (ROIs), tracks or navigation jobs.
    Instances
    An instance represents in fact a server that runs our SafeFleet application stack. The architecture of the system is divided into multiple instances to facilitate scaling and to accommodate the different types and sizes of customers.

    Customer's data is stored entirely on one single instance (that is, not scattered across multiple servers). The developer using this API must take this into account and not hardcode the base URL (or IP address for that matter) of a certain instance, but rather use the authenticate method on the single common entry point https://api.safefleet.eu and follow the "soft" redirects, as described in authentication.

    Companies
    Companies are objects that group all the information of a SafeFleet customer. A company has the following fields:
    Fleets
    A fleet represents a subdivision (a department) of a company. Two types of fleets are distinguished:

    A fleet has the following fields:
    Vehicles
    Vehicles are probably the most important pieces of the SafeFleet system. Vehicles make journeys delimited by a start point and a stop point. They send so-called presences to the server. These presences include the position, the speed and the azimuth of the vehicle at specific moments, and are used to reconstruct the trajectory.

    Vehicles generate events that are stored on the server and can be used to tell the behaviour of the driver, to identify problems with the vehicle's device or to simply keep an eye on the vehicle.

    Vehicles can also generate contact records whenever one of their configured digital inputs (such as door contacts) change state.

    Vehicles equipped with temperature sensors generate temperature records.

    Each vehicle has a list of attributes (such as engine displacement or insurance expiry date).

    Fuelings can be imported into our system and associated to their corresponding vehicles.

    Vehicles can have associated documents that usually correspond to a period of activity (such as journeys).

    Tickets are used to keep track of various issues regarding each vehicle.

    All these are shown in the following diagram:

    Objects related to a vehicle

    A vehicle has the following fields:

    Apart from these static fields, each vehicle has the following fields that change often, called the current information:
    Users
    Each user has one of the five defined levels of access:

    Users can receive notifications when vehicles generate events or when attributes of type date expire.

    A user has the following fields: Users have a set of notification preferences that control the various notifications they receive.
    Drivers
    Drivers are authenticated by the system using special keys individually assigned to each driver. A vehicle can be driven by only one driver at a certain moment.

    A driver has the following fields:

    Each driver has a list of attributes used to store additional data.

    Apart from these static fields, a driver may expose details about the tachograph information, in a field called tacho:
    Driver Groups
    Drivers are grouped into driver droups. A driver can belong to zero, one or multiple groups.

    A driver group has the following fields:
    Points Of Interest
    Each fleet has points of interest (POIs). A POI is a pair of (latitude, longitude) with a certain tolerance (delta) around this central point. POIs are in fact small rectangles used to easily identify and name places on map.

    A POI has the following fields:
    Regions Of Interest
    Each fleet has regions of interest (ROIs). A ROI is a collection of pairs of (latitude, longitude). ROIs are in fact polygons which define a geographical area. They are used for area-related reports and geofence notifications.

    A ROI has the following fields:
    Tracks
    Tracks are used to compare the actual trajectory of a vehicle with an imposed one. A track is basically a set of successive points. The points that make up a track can be points of interest as well as way points (arbitrary points).

    A track has the following fields: A navigation job is basically a task given to the driver to be used on the navigation device attached to the vehicle. The destination of a job can be either a random address or a point of interest. Jobs are managed using state machines. For more information on the available states see navigation job states and navigation vehicle states.

    A navigation job has the following fields:
    Carpool Reservations
    A carpool reservation represents the act of booking a certain vehicle by a certain user for a given period of time. Carpool reservations may not overlap but can be cancelled. A log of all the reservations made (or cancelled) for each vehicle is kept by the system.

    A carpool reservation has the following fields:
    Presences
    Presences represent the positions and all the information that is sampled, recorded and transmitted by a vehicle in time. Presences are used to recreate the trajectory of a vehicle in a specified interval of time.

    A presence has the following fields:
    Journeys
    A journey is delimited by the moment when the engine starts and the moment when it stops.

    A journey has the following fields:
    Events
    Events are generated by vehicles and represent important facts that occurred during journeys (or outside journeys, for that matter). Events are used to tell the behaviour of the drivers, to identify problems with the vehicle's device or to simply keep an eye on the vehicle.

    An event has the following fields:
    Contacts
    Contact records are generated by vehicles when the state of one of their configured digital inputs changes. Each input has an identifier that helps associating it with a certain function (such as a door contact). There is a list of predefined input ids, but the actual id of the input may have any other integer value.

    A contact record has the following fields:
    Temperatures
    Temperature records are generated by vehicles equipped with temperature sensors. Up to 4 temperature sensors can be attached to each vehicle.

    A temperature record has the following fields:
    Attributes
    Attributes store additional information about vehicles and other objects, such as technical specifications or insurance expiry dates. Custom attributes can be defined by the user, aside from the common ones that are available by default.

    An attribute has the following fields:
    Fuelings
    A fueling has the following fields:
    Documents
    A document has the following fields:
    Tickets
    A ticket has the following fields: A temporary link has the following fields:
  7. Available Endpoints
  8. Function parameters whose names are written in italics are optional.
    Parameters that are separated by a pipe character "|" are mutually exclusive.

    The returned values are documented for the successful case, when the status is 200 OK. Whenever an error occurs, the response is as documented in status codes.

    POST /authenticate
    This function is used to authenticate the client with the server and obtain the sessionid. The supplied username must exist on the server.
    usernameString
    the login username
    passwordString
    the login password
    codeString
    the 2FA code
    noteadditional fields may be returned in the response
    returns‣ the message "ok", if the user resides on this instance
    {"message": String}
    ‣ the error message "2fa code required" if 2FA is enabled and code is to be sent
    { "message": String, "phone_hint": String }
    ‣ the instance's URL, if the user resides on another instance
    {"url": String}
    POST /authenticate_vehicle
    This function is similar to authenticate but intended for vehicles rather than users. It can be used instead of authenticate if a vehicle's PIN and license plate are known, to perform API requests on vehicle's behalf. Driver PIN can and should be used instead of vehicle PIN, if driver phone is supplied.
    license_plateString
    vehicle's license plate (any format is fine)
    pinString
    vehicle PIN
    driver_phonedriver's phone (may be required, depending on company setting)
    returns‣ the vehicle details, if the vehicle resides on this instance; driver details are also returned if driver_phone is supplied and a corresponding driver is found
    { "vehicle": { "vehicle_id": Number, "name": String, "license_plate": String, "vin": String, "maker": String, "model": String, "year_of_manufacture": Number, "identification_card": String, "type": Number, /* see vehicle types */ "default_driver": String, "default_driver_phone": String, "tracked": Boolean }, "driver": { "driver_id": Number, "name": String, "email": String, "phone": String, "personal_identification": String, "key_code": String, "driver_code": String, "active": Boolean } }
    ‣ the vehicle instance URL, if the vehicle resides on another instance
    {"url": String}
    POST /authenticate_driver
    This function is similar to authenticate but intended for drivers rather than users. It can be used instead of authenticate if a driver's PIN and phone number are known, to perform API requests on driver's behalf.
    phoneString
    driver's phone number
    pinString
    driver's PIN
    returns‣ the driver details, if the driver resides on this instance
    { "driver": { "driver_id": Number, "name": String, "email": String, "phone": String, "personal_identification": String, "key_code": String, "driver_code": String, "active": Boolean } }
    ‣ the driver instance URL, if the driver resides on another instance
    {"url": String}
    GET /companies
    This function returns a list of all the companies present on the current instance.
    seecompanies
    requiresat least SafeFleet administrator user level
    returnsthe list of companies
    [ { "company_id": Number, "name": String, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String }, "vat_number": String, "type": String, "activity_type": String }, ... ]
    POST /companies
    This function adds a new company. It also creates a root fleet for the new company.
    nameString
    latNumber
    lngNumber
    address{ "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String },
    vat_numberString
    typeString
    activity_typeString
    seecompanies, fleets
    requiresat least SafeFleet administrator user level
    returnsthe ids of the new company and root fleet
    {"company_id": Number, "fleet_id": Number}
    GET /companies/{company_id}
    This function returns detailed information about a company.
    company_idthe id of the desired company, or "mine" for the current user's company
    seecompanies
    requiresat least company administrator user level
    returns{ "company_id": Number, "name": String, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String }, "vat_number": String, "type": String, "activity_type": String }
    PATCH /companies/{company_id}
    This function updates the information of a company. Only safefleet administrators are allowed to update other companies.
    company_idthe id of the desired company, or "mine" for the current user's company
    nameString
    address{ "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String }
    vat_numberString
    typeString
    activity_typeString
    seecompanies
    requiresat least company administrator user level
    returnsthe message "ok"
    {"message": String}
    DELETE /companies/{company_id}
    This function deletes a company.
    company_idthe id of the desired company
    seecompanies
    requiresat least SafeFleet administrator user level
    notethis function recursively and permanently deletes all the objects related to this company
    returnsthe message "ok"
    {"message": String}
    GET /companies/{company_id}/functionalities
    This function returns all the functionalities of a company, along with their current status.
    company_idthe id of the desired company
    seecompanies
    requiresat least SafeFleet administrator user level
    returnsthe list of functionalities
    { "flavour": String, "func1": { "title": String, "category": String, "choices": [ { "name": String, "value": any }, ... ], "value": any }, ... }
    PATCH /companies/{company_id}/functionalities
    This function modifies the functionalities of a company.
    company_idthe id of the desired company
    flavourString
    the name of the flavour to use as functionality preset
    func1...any
    the name of a functionality to be changed
    seecompanies
    requiresat least SafeFleet administrator user level
    note‣ more functionalities can be modified with one request, by specifying them as parameters
    ‣ specifying a flavour as well as separate functionalities will result in a set of functionalities defaulting to the flavour but updated with supplied functionalities
    returnsthe message "ok"
    {"message": String}
    GET /companies/{company_id}/structure
    This function returns the hierarchical structure of a company. Optionally, vehicles, users and other related objects can be included in the result.
    company_idthe id of the desired company, or "mine" for the current user's company
    include_vehiclesset this to true to include vehicle ids in the result
    include_usersset this to true to include user ids in the result
    include_driversset this to true to include driver ids in the result
    include_poisset this to true to include point of interest ids in the result
    include_roisset this to true to include region of interest ids in the result
    include_tracksset this to true to include track ids in the result
    seecompanies
    requiresat least company administrator user level
    returnsthe hierarchical structure of the company
    { "company_id": Number, "name": String, "fleets": [ { "fleet_id": Number, "name": String, "fleets": [...], "vehicle_ids": [Number], "user_ids": [Number], "driver_ids": [Number], "poi_ids": [Number], "roi_ids": [Number], "track_ids": [Number] }, ... ] }
    GET /companies/{company_id}/fleets
    This function returns a list of the root fleets corresponding to a given company.
    company_idthe id of the desired company, or "mine" for the current user's company
    seefleets
    requiresat least department administrator user level
    returnsthe list of fleets
    [ { "fleet_id": Number, "name": String, "lat": Number, "lng": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }, ... ]
    POST /companies/{company_id}/fleets
    This function adds a root fleet to a company.
    company_idthe id of the desired company, or "mine" for the current user's company
    nameString
    latNumber
    lngNumber
    address{ "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String }
    seefleets
    requiresat least company administrator user level
    returnsthe id of the new fleet
    {"fleet_id": Number}
    GET /fleets
    This function returns a list of the root fleets accessible to the current user.
    seefleets
    requiresat least department administrator user level
    returnsthe list of fleets
    [ { "fleet_id": Number, "name": String, "lat": Number, "lng": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }, ... ]
    GET /fleets/{fleet_id}/fleets
    This function returns a list of the subfleets corresponding to a fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    seefleets
    requiresat least department administrator user level
    returnsthe list of fleets
    [ { "fleet_id": Number, "name": String, "lat": Number, "lng": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }, ... ]
    POST /fleets/{fleet_id}/fleets
    This function adds a subfleet to a fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    nameString
    latNumber
    lngNumber
    address{ "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String }
    seefleets
    requiresat least company administrator user level
    returnsthe id of the new fleet
    {"fleet_id": Number}
    GET /fleets/{fleet_id}
    This function returns detailed information about a fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    seefleets
    requiresat least department administrator user level
    returns{ "fleet_id": Number, "name": String, "lat": Number, "lng": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }
    PATCH /fleets/{fleet_id}
    This function updates the information of a fleet. Company administrators are allowed to update any fleet belonging to their company.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    nameString
    latNumber
    lngNumber
    address{ "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String }
    seefleets
    requiresat least department administrator user level
    returnsthe message "ok"
    {"message": String}
    DELETE /fleets/{fleet_id}
    This function deletes a fleet.
    fleet_idthe id of the desired fleet
    seefleets
    requiresat least company administrator user level
    notethis function recursively and permanently deletes all the objects related to this fleet
    returnsthe message "ok"
    {"message": String}
    GET /fleets/{fleet_id}/vehicles
    This function returns a list of the vehicles corresponding to a given fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    seevehicles
    returnsthe list of vehicles
    [ { "vehicle_id": Number, "name": String, "license_plate": String, "vin": String, "maker": String, "model": String, "year_of_manufacture": Number, "identification_card": String, "type": Number, /* see vehicle types */ "working_schedule": { "mon": { "from_hour": Number, "from_minute": Number, "to_hour": Number, "to_minute": Number }, ..., "sun": { "from_hour": Number, "from_minute": Number, "to_hour": Number, "to_minute": Number } }, "map_prefs": { "color": String, /* see vehicle colors */, "size": String, /* see vehicle sizes */ }, "default_driver": String, "default_driver_phone": String, "tracked": Boolean, "device_serial_number": String, "current_info": { "lat": Number, "lng": Number, "speed": Number, "moment": String, "last_sync": String, "azimuth": Number, "driver_id": Number, "status": Number, /* see vehicle statuses */ "engine_since": String, "navig_state": Number, /* see navigation vehicle states */ "battery_soc": Number, "fuel_level": Number, "total_fuel_used": Number, "purpose": String, "journey_code": String, "contacts": { input_id: Number, /* see input ids */ ... }, "temperatures": { "1": Number, "2": Number, "3": Number, "4": Number } } }, ... ]
    POST /fleets/{fleet_id}/vehicles
    This function adds a new vehicle to a fleet
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    nameString
    license_plateString
    vinString
    makerString
    modelString
    year_of_manufactureNumber
    identification_cardString
    typeNumber /* see vehicle types */
    map_prefs{ "color": String, /* see vehicle map colors */ "size": String /* see vehicle types */ }
    working_schedule{ "mon": { "from_hour": Number, "from_minute": Number, "to_hour": Number, "to_minute": Number }, ..., "sun": { "from_hour": Number, 'from_minute": Number, 'to_hour": Number, "to_minute": Number } }
    default_driverString
    default_driver_phoneString
    seevehicles
    returnsthe id of the new vehicle
    {"vehicle_id": Number}
    GET /fleets/{fleet_id}/vehicles/journeys
    This function returns the journeys of all the vehicles corresponding to a given fleet that started or ended within a specified period of time. If no start_moment or no stop_moment is given, the function returns the last journey of each vehicle.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    min_distanceNumber
    if given, will filter out journeys with a distance less than this value (in kilometers)
    min_durationNumber
    if given, will filter out journeys with a duration less than this value (in seconds)
    seejourneys
    requirestracked vehicles
    note‣ the interval of time must be less than a month
    ‣ when requesting the last journey, the min_distance and min_duration filters are ignored
    ‣ when requesting the last journey, if the journey is in progress, the fields stop, distance, idle_duration, max_speed and consumption will be null
    returnsthe list of journeys for each vehicle
    [ { "vehicle_id": String, "journeys": [ { "journey_id": String, "start": { "moment": String, "lat": Number, "lng": Number }, "stop": { "moment": String, "lat": Number, "lng": Number }, "distance": Number, "idle_duration": Number, "consumption": { "value": Number, "measured": Boolean }, "max_speed": Number, "driver_id": Number, "purpose": String, "journey_code": String }, ... ] }, ... ]
    GET /fleets/{fleet_id}/vehicles/attributes
    This function returns the attributes of all the vehicles corresponding to a given fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    seeattributes
    returnsthe list of attributes for each vehicle
    [ { "vehicle_id": String, "attributes": [ { "name": String, "slug": String, "type": Number, /* see attribute types */ "value": Number|Boolean|String }, ... ] }, ... ]
    GET /fleets/{fleet_id}/vehicles/fuelings
    This function returns the fuelings of all the vehicles corresponding to a given fleet, within a given period of time.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    seefuelings
    returnsthe list of fuelings for each vehicle
    [ { "vehicle_id": String, "fuelings": [ { "moment": String, "quantity": Number, "price": Number, "type": Number, /* see fuel types */ "provider": String, "odometer": Number, "station": String, "card": String, "remark": String }, ... ] }, ... ]
    GET /fleets/{fleet_id}/vehicles/odometers
    This function returns the odometers of all the vehicles corresponding to a given fleet, at a certain moment. Odometers can be computed using values from two sources: device (FMS) and dashboard reading.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    momentString
    the desired moment (defaults to now if not supplied)
    seevehicles
    returnsthe odometer for each vehicle
    [ { "vehicle_id": String, "odometer": Number, "source": String /* "device", "readings" or null */ }, ... ]
    GET /vehicles
    This function returns a list of all vehicles accessible to the current user.
    seevehicles
    returnsthe list of vehicles
    [ { "vehicle_id": Number, "name": String, "license_plate": String, "vin": String, "maker": String, "model": String, "year_of_manufacture": Number, "identification_card": String, "type": Number, /* see vehicle types */ "working_schedule": { "mon": { "from_hour": Number, "from_minute": Number, "to_hour": Number, "to_minute": Number }, ..., "sun": { "from_hour": Number, "from_minute": Number, "to_hour": Number, "to_minute": Number } }, "map_prefs": { "color": String, /* see vehicle colors */, "size": String, /* see vehicle sizes */ }, "default_driver": String, "default_driver_phone": String, "tracked": Boolean, "device_serial_number": String, "current_info": { "lat": Number, "lng": Number, "speed": Number, "moment": String, "last_sync": String, "azimuth": Number, "driver_id": Number, "status": Number, /* see vehicle statuses */ "engine_since": String, "navig_state": Number, /* see navigation vehicle states */ "battery_soc": Number, "fuel_level": Number, "total_fuel_used": Number, "purpose": String, "journey_code": String, "contacts": { input_id: Number, /* see input ids */ ... }, "temperatures": { "1": Number, "2": Number, "3": Number, "4": Number } } }, ... ]
    GET /vehicles/{vehicle_id}
    This function returns detailed information about a vehicle.
    vehicle_idthe id of the desired vehicle
    seevehicles
    returns{ "vehicle_id": Number, "name": String, "license_plate": String, "vin": String, "maker": String, "model": String, "year_of_manufacture": Number, "identification_card": String, "type": Number, /* see vehicle types */ "working_schedule": { "mon": { "from_hour": Number, "from_minute": Number, "to_hour": Number, "to_minute": Number }, ..., "sun": { "from_hour": Number, "from_minute": Number, "to_hour": Number, "to_minute": Number } }, "map_prefs": { "color": String, /* see vehicle colors */, "size": String, /* see vehicle sizes */ }, "default_driver": String, "default_driver_phone": String, "tracked": Boolean, "device_serial_number": String, "current_info": { "lat": Number, "lng": Number, "speed": Number, "moment": String, "last_sync": String, "azimuth": Number, "driver_id": Number, "status": Number, /* see vehicle statuses */ "engine_since": String, "navig_state": Number, /* see navigation vehicle states */ "battery_soc": Number, "fuel_level": Number, "total_fuel_used": Number, "purpose": String, "journey_code": String, "contacts": { input_id: Number, /* see input ids */ ... }, "temperatures": { "1": Number, "2": Number, "3": Number, "4": Number } } }
    PATCH /vehicles/{vehicle_id}
    This function updates the information of a vehicle.
    fleet_idNumber
    nameString
    license_plateString
    vinString
    makerString
    modelString
    year_of_manufactureNumber
    identification_cardString
    typeNumber /* see vehicle types */
    map_prefs{ "color": String, /* see vehicle map colors */ "size": String /* see vehicle types */ }
    working_schedule{ "mon": { "from_hour": Number, "from_minute": Number, "to_hour": Number, "to_minute": Number }, ..., "sun": { "from_hour": Number, 'from_minute": Number, 'to_hour": Number, "to_minute": Number } }
    default_driverString
    default_driver_phoneString
    seevehicles
    returnsthe message "ok"
    {"message": String}
    DELETE /vehicles/{vehicle_id}
    This function deletes a vehicle.
    seevehicles
    returnsthe message "ok"
    {"message": String}
    GET /vehicles/{vehicle_id}/odometer
    This function returns the odometer of a vehicle at a certain moment. Odometers can be computed using values from two sources: device (FMS) and dashboard reading.
    vehicle_idthe id of the desired vehicle
    momentString
    the desired moment (defaults to now if not supplied)
    seevehicles
    requirestracked vehicles
    noteodometers that are not available will be returned as null
    returns{ "vehicle_id": String, "odometer": Number, "source": String /* "device", "readings" or null */ }
    POST /vehicles/{vehicle_id}/odometers
    This function adds a new odometer reading for a vehicle.
    vehicle_idthe id of the desired vehicle
    odometerNumber
    the value of the odometer
    momentString
    the moment at which the odometer was recorded
    returnsthe message "ok"
    {"message": String}
    GET /vehicles/{vehicle_id}/presences
    This function returns the presences of a vehicle that were received within a specified period of time.
    vehicle_idthe id of the desired vehicle
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    filterString
    set to plot to return a set of filtered presences optimized for plotting on a map
    filter_dist_percentNumber
    min distance between two successive presences, expressed as percent from total distance (defaults to 0.01, i.e. 1%)
    filter_angle_threshNumber
    min angle between two successive presences, expressed as sexagesimal degrees (defaults to 10)
    seepresences
    requirestracked vehicles
    notethe interval of time must be less than a week
    returns[ { "presence_id": String, "vehicle_id": Number, "moment": String, "lat": Number, "lng": Number, "speed": Number, "azimuth": Number, "engine": Boolean }, ... ]
    POST /vehicles/{vehicle_id}/presences
    This function adds a presence (a tracking data record) for a vehicle. Most of the parameters are optional. It is recommended however to supply as many parameters as are available at the moment of the call.
    vehicle_idthe id of the desired vehicle
    momentString
    the moment of the presence
    currentBoolean
    tells whether the information is current or from the past (defaults to true)
    journeyBoolean
    the journey (ignition) status
    latNumber
    the latitude
    lngNumber
    the longitude
    speedNumber
    the speed (in km/h)
    azimuthNumber
    the azimuth (degrees, from 0 to 360)
    driver_keyString
    the authenticated driver key
    rel_odomNumber
    a relative odometer used to determine travelled distance (in meters)
    abs_odomNumber
    the absolute (dashboard) odometer (in meters)
    purposeString
    the journey purpose
    journey_codeString
    optional journey code
    idlingNumber
    the idling time during current journey (in seconds)
    event_typeString
    the type of an event (see event types)
    durationNumber
    the duration of the event (in seconds)
    input_idNumber
    the id of an input (see input ids)
    input_valueNumber
    the value of the input
    fuel_levelNumber
    the current fuel level (the unit and scale depends on the vehicle configuration)
    fuel_usedNumber
    the total fuel used (in liters)
    rpmNumber
    the engine RPM
    tempBoolean
    the value of the first temperature sensor (in degrees Celsius)
    temp2Number
    the value of the second temperature sensor (in degrees Celsius)
    temp3Number
    the value of the third temperature sensor (in degrees Celsius)
    temp4Number
    the value of the fourth temperature sensor (in degrees Celsius)
    auto_posif set to true, position fields (lat, lng and azimuth) will be automatically filled in using last known values, if not supplied
    seepresences
    requirestracked vehicles
    returnsthe message "ok"
    {"message": String}
    GET /vehicles/{vehicle_id}/journeys
    This function returns the journeys of a vehicle that started or ended within a specified period of time. If no start_moment or no stop_moment is given, the function returns the last journey of the vehicle.
    vehicle_idthe id of the desired vehicle
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    min_distanceNumber
    if given, will filter out journeys with a distance less than this value (in kilometers)
    min_durationNumber
    if given, will filter out journeys with a duration less than this value (in seconds)
    seejourneys
    requirestracked vehicles
    note‣ the interval of time must be less than a year
    ‣ when requesting the last journey, the min_distance and min_duration filters are ignored
    ‣ when requesting the last journey, if the journey is in progress, the fields stop, distance, idle_duration, max_speed and consumption will be null
    returns[ { "journey_id": String, "vehicle_id": Number, "start": { "moment": String, "lat": Number, "lng": Number }, "stop": { "moment": String, "lat": Number, "lng": Number }, "distance": Number, "idle_duration": Number, "consumption": { "value": Number, "measured": Boolean }, "max_speed": Number, "driver_id": Number, "purpose": String, "journey_code": String }, ... ]
    GET /vehicles/{vehicle_id}/events
    This function returns the events of a vehicle that occurred within a specified period of time.
    vehicle_idthe id of the desired vehicle
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    typeString
    if given, will return only the events of this type (see event types)
    seeevents
    requirestracked vehicles
    notethe interval of time must be less than a year
    returns[ { "event_id": String, "vehicle_id": Number, "moment": String, "lat": Number, "lng": Number, "type": String, /* see event types */ "driver_id": Number, "track_id": Number, "roi_id": Number }, ... ]
    GET /vehicles/{vehicle_id}/contacts
    This function returns the contact records of a vehicle that occurred within a specified period of time.
    vehicle_idthe id of the desired vehicle
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    input_idif given, will return only the records having this input id (see input ids)
    typeString
    seecontacts
    requirestracked vehicles
    notethe interval of time must be less than a year
    returns[ { "contact_id": String, "vehicle_id": Number, "moment": String, "input_id": Number, /* see input ids */ "input_value": Number, "lat": Number, "lng": Number }, ... ]
    GET /vehicles/{vehicle_id}/attributes
    This function returns the attributes of a vehicle.
    vehicle_idthe id of the desired vehicle
    seeattributes
    returns[ { "vehicle_id": String, "slug": String, "name": String, "type": Number, /* see attribute types */ "value": Number|Boolean|String }, ... ]
    PATCH /vehicles/{vehicle_id}/attributes/{slug}
    This function sets the value of a vehicle attribute.
    vehicle_idthe id of the desired vehicle
    slugString
    the slug (simplified name) of the attribute
    valueany
    the new value of the attribute
    seeattributes
    returnsthe message "ok"
    {"message": String}
    GET /vehicles/{vehicle_id}/fuelings
    This function returns the fuelings of a vehicle that were done within a specified period of time.
    vehicle_idthe id of the desired vehicle
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    seefuelings
    notethe interval of time must be less than a year
    returns[ { "fueling_id": String, "vehicle_id": Number, "moment": String, "quantity": Number, "price": Number, "type": Number, /* see fuel types */ "provider": String, "odometer": Number, "station": String, "card": String, "remark": String }, ... ]
    POST /vehicles/{vehicle_id}/fuelings
    This function adds one or more fuelings of a vehicle to the system.
    vehicle_idthe id of the desired vehicle
    fuelings[ { "moment": String, "quantity": Number, "price": Number, "type": Number, /* see fuel types */ "provider": String, /*optional */ "odometer": Number, /*optional */ "station": String, /*optional */ "card": String, /*optional */ "remark": String /*optional */ }, ... ]
    a list of fuelings
    seefuelings
    returns‣ the message "ok", if everything went well
    {"message": String}
    ‣ the indexes of duplicate fuelings, if any
    {"duplicate_indexes": [Number]}
    GET /vehicles/{vehicle_id}/device_settings/{name}
    This function queries the vehicle's device for a given setting and returns the corresponding value. Not all settings are exposed by all vehicles.
    vehicle_idthe id of the desired vehicle
    nameString
    the name of the device setting
    seedevice settings
    requirestracked vehicles
    returns‣ the current value of the setting, if everything goes well
    {"value": any}
    ‣ a message set to whatever error has occurred, if any
    {"message": String}
    PATCH /vehicles/{vehicle_id}/device_settings/{name}
    This function updates a vehicle's device setting.
    vehicle_idthe id of the desired vehicle
    nameString
    the name of the device setting
    valueany
    the new value for the device setting
    seedevice settings
    requirestracked vehicles
    returns‣ the message "ok", if everything goes well
    {"message": String}
    ‣ a message set to whatever error has occurred, if any
    {"message": String}
    GET /vehicles/{vehicle_id}/temperatures
    This function returns the temperature records of a vehicle that were generated within a specified period of time.
    vehicle_idthe id of the desired vehicle
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    typeString
    seetemperatures
    requirestracked vehicles
    notethe interval of time must be less than a year
    returns[ { "temperature_id": Number, "vehicle_id": Number, "moment": String, "temp": Number, "temp2": Number, "temp3": Number, "temp4": Number, "moment": String, "lat": Number, "lng": Number }, ... ]
    GET /vehicles/{vehicle_id}/tickets
    This function returns the tickets of a vehicle that were opened within a specified period of time.
    vehicle_idthe id of the desired vehicle
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    seetickets
    returns[ { "vehicle_id": Number, "ticket_id": Number, "reporter_id": Number, "responsible_id": Number, "issue": String, "remark": String, "opened_moment": String, "status": Number /* see ticket statuses */ }, ... ]
    POST /vehicles/{vehicle_id}/tickets
    This function creates a ticket for a vehicle.
    vehicle_idthe id of the desired fleet
    reporter_idNumber
    the id of the reporter
    responsible_idNumber
    the id of the responsible
    issueString
    the description of the ticket's issue
    remarkString
    an optional textual remark
    seetickets
    returnsthe id of the new ticket
    {"ticket_id": Number}
    PATCH /tickets/{ticket_id}
    This function updates the information of a ticket.
    ticket_idthe id of the desired ticket
    responsible_idNumber
    issueString
    remarkString
    statusNumber /* see ticket statuses */
    seetickets
    returnsthe message "ok"
    {"message": String}
    GET /fleets/{fleet_id}/users
    This function returns a list of the users corresponding to a given fleet. Company administrators are allowed list all users of their company. Department administrators are allowed to list the users of their department or subdepartments.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    seeusers
    requiresat least department admin user level
    returnsthe list of users
    [ { "user_id": Number, "username": String, "first_name": String, "last_name": String, "email": String, "phone": String, "timezone": String, "timezone_offset": Number, "level": Number /* see user levels */ }, ... ]
    POST /fleets/{fleet_id}/users
    This function adds a new user to a fleet. The level cannot have a value smaller than the current user's level.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    usernameString
    passwordString
    first_nameString
    last_nameString
    emailString
    phoneString
    timezoneString
    levelNumber /* see user levels */
    seeusers
    requiresat least department admin user level
    returnsthe id of the new user
    {"user_id": Number}
    GET /users
    This function returns a list of all users accessible to the current user. Company administrators are allowed list all users of their company. Department administrators are allowed to list the users of their department or subdepartments.
    seeusers
    requiresat least department admin user level
    returnsthe list of users
    [ { "user_id": Number, "username": String, "first_name": String, "last_name": String, "email": String, "phone": String, "timezone": String, "timezone_offset": Number, "level": Number /* see user levels */ }, ... ]
    GET /users/{user_id}
    This function returns detailed information about a user. All users are allowed to obtain information about any of the users of their company, provided they know the id.
    user_idthe id of the desired user, or "me" for the current user
    seeusers
    returns{ "user_id": Number, "username": String, "first_name": String, "last_name": String, "email": String, "phone": String, "timezone": String, "timezone_offset": Number, "level": Number /* see user levels */ }
    PATCH /users/{user_id}
    This function updates the information of a user. Company administrators are allowed to update other users of their company. Department administrators are allowed to update other users of their department or subdepartments. The level cannot have a value smaller than the current user's level.
    user_idthe id of the desired user, or "me" for the current user
    fleet_idNumber
    usernameString
    first_nameString
    last_nameString
    emailString
    phoneString
    timezoneString
    levelNumber /* see user levels */
    seeusers
    returnsthe message "ok"
    {"message": String}
    DELETE /users/{user_id}
    This function deletes a user.
    user_idthe id of the desired user
    seeusers
    requiresat least department admin user level
    returnsthe message "ok"
    {"message": String}
    GET /users/{user_id}/notification_prefs
    This function returns the notification preferences of a user. These notification preferences include the types of notifications, the events for which notifications are sent.
    user_idthe id of the desired user, or "me" for the current user
    seeusers
    notethe number associated to the expiry attributes is the number of days to notify in advance (1, 7 or 30)
    returns{ "user_id": Number, "events": { event type: { /* see event types */ "online": Boolean, "email": Boolean, "sms": Boolean }, ... }, "expiry": { attribute name: Number, /* see common attributes, the Date attributes */ ... } }
    PATCH /users/{user_id}/notification_prefs
    This function updates the notifications preferences of a user. Company administrators are allowed to update other users of their company. Department administrators are allowed to update other users of their department or subdepartments.
    user_idthe id of the desired user, or "me" for the current user
    events{ event type: { /* see event types */ "online": Boolean, "email": Boolean, "sms": Boolean }, ... }
    expiry{ attribute name: Number, /* see common attributes, the Date attributes */ ... }
    seeusers
    notethe number associated to the expiry attributes is the number of days to notify in advance (1, 7 or 30)
    returnsthe message "ok"
    {"message": String}
    GET /users/{user_id}/geofence_prefs
    This function returns the geofence preferences of a user. These geofence preferences are in fact the tracks and regions of interest that the user wishes to use as geofences, in association with one or more vehicles (see geofence events in event types).
    user_idthe id of the desired user, or "me" for the current user
    seeusers, tracks, regions of interest
    note‣ a "vehicle_id": 0 signifies any vehicle, a "roi_id": 0 signifies any region of interest and "track_id": 0 signifies any track
    ‣ one of roi_id and track_id is set and the other one is null, indicating the type of geofence
    returns{ "user_id": Number, "geofences": [ { "vehicle_id": Number, "roi_id": Number, "track_id": Number }, ... ] }
    PATCH /users/{user_id}/geofence_prefs
    This function updates the geofence preferences of a user. Company administrators are allowed to update other users of their company. Department administrators are allowed to update other users of their department or subdepartments.
    user_idthe id of the desired user, or "me" for the current user
    geofences[ { "vehicle_id": Number, "roi_id": Number, "track_id": Number }, ... ]
    seeusers, tracks, regions of interest
    note‣ a "vehicle_id": 0 signifies any vehicle, a "roi_id": 0 signifies any region of interest and "track_id": 0 signifies any track
    ‣ one of roi_id and track_id must be set and the other one must be null, indicating the type of geofence
    returnsthe message "ok"
    {"message": String}
    GET /fleets/{fleet_id}/drivers
    This function returns a list of the drivers corresponding to a given fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    seedrivers
    notetacho field will be null if tachograph information is not available
    returnsthe list of drivers
    [ { "driver_id": Number, "name": String, "email": String, "phone": String, "personal_identification": String, "key_code": String, "driver_code": String, "active": Boolean, "tacho": { "state": Number, /* see tacho states */ "time_driven_since_short_break": Number, "time_driven_since_long_rest": Number, "leave_in": Number, "next_short_break_in": Number, "next_long_rest_in": Number } }, ... ]
    POST /fleets/{fleet_id}/drivers
    This function adds a new driver to a fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    nameString
    emailString
    phoneString
    personal_identificationString
    key_codeString
    driver_codeString
    activeBoolean
    seedrivers
    returnsthe id of the new driver
    {"driver_id": Number}
    GET /fleets/{fleet_id}/drivers/attributes
    This function returns the attributes of all the drivers corresponding to a given fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    seeattributes
    returnsthe list of attributes for each driver
    [ { "driver_id": String, "attributes": [ { "name": String, "slug": String, "type": Number, /* see attribute types */ "value": Number|Boolean|String }, ... ] }, ... ]
    GET /drivers
    This function returns a list of the drivers visible to the current user.
    seedrivers
    notetacho field will be null if tachograph information is not available
    returnsthe list of drivers
    [ { "driver_id": Number, "name": String, "email": String, "phone": String, "personal_identification": String, "key_code": String, "driver_code": String, "active": Boolean, "tacho": { "state": Number, /* see tacho states */ "time_driven_since_short_break": Number, "time_driven_since_long_rest": Number, "leave_in": Number, "next_short_break_in": Number, "next_long_rest_in": Number } }, ... ]
    GET /drivers/{driver_id}
    This function returns detailed information about a driver.
    driver_idthe id of the desired driver
    seedrivers
    notetacho field will be null if tachograph information is not available
    returns{ "driver_id": Number, "name": String, "email": String, "phone": String, "personal_identification": String, "key_code": String, "driver_code": String, "active": Boolean, "tacho": { "state": Number, /* see tacho states */ "time_driven_since_short_break": Number, "time_driven_since_long_rest": Number, "leave_in": Number, "next_short_break_in": Number, "next_long_rest_in": Number } }
    PATCH /drivers/{driver_id}
    This function updates the information of a driver.
    driver_idthe id of the desired driver
    fleet_idNumber
    nameString
    emailString
    phoneString
    personal_identificationString
    key_codeString
    driver_codeString
    activeBoolean
    seedrivers
    returnsthe message "ok"
    {"message": String}
    DELETE /drivers/{driver_id}
    This function deletes a driver.
    driver_idthe id of the desired driver
    seedrivers
    returnsthe message "ok"
    {"message": String}
    PATCH /drivers/{driver_id}/attributes/{slug}
    This function sets the value of a driver attribute.
    driver_idthe id of the desired driver
    slugString
    the slug (simplified name) of the attribute
    valueany
    the new value of the attribute
    seeattributes
    returnsthe message "ok"
    {"message": String}
    GET /drivers/{driver_id}/attributes
    This function returns the attributes a driver.
    driver_idthe id of the desired driver
    seeattributes
    returns[ { "driver_id": String, "slug": String, "name": String, "type": Number, /* see attribute types */ "value": Number|Boolean|String }, ... ]
    GET /companies/{company_id}/driver_groups
    This function returns a list of the driver groups corresponding to a given company.
    company_idthe id of the desired company, or "mine" for the current user's company
    seedriver groups
    requiresat least company administrator user level
    returnsthe list of driver groups
    [ { "driver_group_id": Number, "name": String, "driver_ids": [Number] }, ... ]
    POST /companies/{company_id}/driver_groups
    This function adds a new driver group to a company.
    company_idthe id of the desired company, or "mine" for the current user's company
    nameString
    driver_ids[Number]
    seedriver groups
    requiresat least company administrator user level
    returnsthe id of the new driver group
    {"driver_group_id": Number}
    GET /driver_groups
    This function returns a list of the driver groups accessible to the current user.
    seedriver groups
    requiresat least company administrator user level
    returnsthe list of driver groups
    [ { "driver_group_id": Number, "name": String, "driver_ids": [Number] }, ... ]
    GET /driver_groups/{driver_group_id}
    This function returns detailed information about a driver group.
    driver_group_idthe id of the desired driver group
    seedriver groups
    requiresat least company administrator user level
    returns{ "driver_group_id": Number, "name": String, "driver_ids": [Number] }
    PATCH /driver_groups/{driver_group_id}
    This function updates the information of a driver group.
    driver_group_idthe id of the desired driver group
    nameString
    driver_ids[Number]
    seedriver groups
    requiresat least company administrator user level
    returnsthe message "ok"
    {"message": String}
    DELETE /driver_groups/{driver_group_id}
    This function deletes a driver group.
    driver_group_idthe id of the desired driver group
    seedriver groups
    requiresat least company administrator user level
    returnsthe message "ok"
    {"message": String}
    GET /fleets/{fleet_id}/pois
    This function returns a list of the points of interest corresponding to a given fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    seepoints of interest
    returnsthe list of POIs
    [ { "poi_id": Number, "name": String, "category": String, "comment": String, "business": Boolean, "visible_upwards": Boolean, "visible_downwards": Boolean, "lat": Number, "lng": Number, "delta_lat": Number, "delta_lng": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }, ... ]
    POST /fleets/{fleet_id}/pois
    This function adds a new point of interest to a fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    nameString
    categoryString
    commentString
    businessBoolean
    visible_upwardsBoolean
    visible_downwardsBoolean
    latNumber
    lngNumber
    delta_latNumber
    delta_lngNumber
    address{ "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String }
    seepoints of interest
    returnsthe id of the new point of interest
    {"poi_id": Number}
    GET /pois
    This function returns a list of the points of interest accessible to the current user.
    seepoints of interest
    returnsthe list of POIs
    [ { "poi_id": Number, "name": String, "category": String, "comment": String, "business": Boolean, "visible_upwards": Boolean, "visible_downwards": Boolean, "lat": Number, "lng": Number, "delta_lat": Number, "delta_lng": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }, ... ]
    GET /pois/{poi_id}
    This function returns detailed information about a point of interest.
    poi_idthe id of the desired point of interest
    seepoints of interest
    returns{ "poi_id": Number, "name": String, "category": String, "comment": String, "business": Boolean, "visible_upwards": Boolean, "visible_downwards": Boolean, "lat": Number, "lng": Number, "delta_lat": Number, "delta_lng": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }
    PATCH /pois/{poi_id}
    This function updates the information of a point of interest.
    poi_idthe id of the desired point of interest
    fleet_idNumber
    nameString
    categoryString
    commentString
    businessBoolean
    visible_upwardsBoolean
    visible_downwardsBoolean
    latNumber
    lngNumber
    delta_latNumber
    delta_lngNumber
    address{ "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String }
    seepoints of interest
    returnsthe message "ok"
    {"message": String}
    DELETE /pois/{poi_id}
    This function deletes a point of interest.
    poi_idthe id of the desired point of interest
    seepoints of interest
    returnsthe message "ok"
    {"message": String}
    GET /pois/public
    This function returns a list of the public points of interest.
    seepoints of interest
    returnsthe list of public POIs
    [ { "poi_id": Number, "name": String, "category": String, "comment": String, "business": Boolean, "lat": Number, "lng": Number, "delta_lat": Number, "delta_lng": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }, ... ]
    POST /pois/public
    This function adds a new public point of interest.
    nameString
    categoryString
    commentString
    businessBoolean
    visible_upwardsBoolean
    visible_downwardsBoolean
    latNumber
    lngNumber
    delta_latNumber
    delta_lngNumber
    address{ "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String }
    seepoints of interest
    requiresat least SafeFleet administrator user level
    returnsthe id of the new point of interest
    {"poi_id": Number}
    GET /fleets/{fleet_id}/rois
    This function returns a list of the regions of interest corresponding to a given fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    seeregions of interest
    returnsthe list of ROIs
    [ { "roi_id": Number, "name": String, "category": String, "visible_upwards": Boolean, "visible_downwards": Boolean, "polygon": [ { "lat": Number, "lng": Number }, ... ] }, ... ]
    POST /fleets/{fleet_id}/rois
    This function adds a new region of interest to a fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    nameString
    categoryString
    visible_upwardsBoolean
    visible_downwardsBoolean
    polygon[ { "lat": Number, "lng": Number }, ... ]
    seeregions of interest
    returnsthe id of the new region of interest
    {"roi_id": Number}
    GET /rois
    This function returns a list of the regions of interest accessible to the current user.
    seeregions of interest
    returnsthe list of ROIs
    [ { "roi_id": Number, "name": String, "category": String, "visible_upwards": Boolean, "visible_downwards": Boolean, "polygon": [ { "lat": Number, "lng": Number }, ... ] }, ... ]
    GET /rois/{roi_id}
    This function returns detailed information about a region of interest.
    roi_idthe id of the desired region of interest
    seeregions of interest
    returns{ "roi_id": Number, "name": String, "category": String, "visible_upwards": Boolean, "visible_downwards": Boolean, "polygon": [ { "lat": Number, "lng": Number }, ... ] }
    PATCH /rois/{roi_id}
    This function updates the information of a region of interest.
    roi_idthe id of the desired region of interest
    fleet_idNumber
    nameString
    categoryString
    visible_upwardsBoolean
    visible_downwardsBoolean
    polygon[ { "lat": Number, "lng": Number }, ... ]
    seeregions of interest
    returnsthe message "ok"
    {"message": String}
    DELETE /rois/{roi_id}
    This function deletes a region of interest.
    roi_idthe id of the desired region of interest
    seeregions of interest
    returnsthe message "ok"
    {"message": String}
    GET /rois/public
    This function returns a list of the public regions of interest.
    seeregions of interest
    returnsthe list of public ROIs
    [ { "roi_id": Number, "name": String, "category": String, "polygon": [ { "lat": Number, "lng": Number }, ... ] }, ... ]
    POST /rois/public
    This function adds a new public region of interest to a fleet.
    nameString
    categoryString
    polygon[ { "lat": Number, "lng": Number }, ... ]
    seeregions of interest
    requiresat least SafeFleet administrator user level
    returnsthe id of the new region of interest
    {"roi_id": Number}
    GET /fleets/{fleet_id}/tracks
    This function returns a list of the tracks corresponding to a given fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    include_navigBoolean
    if true, will include tracks used as navigation jobs; defaults to false
    seetracks
    returnsthe list of tracks
    [ { "track_id": Number, "name": String, "geofence": Boolean, "visible_upwards": Boolean, "visible_downwards": Boolean, "pois": [ { "poi_id": Number, "order": Number, "lat": Number, "lng": Number }, ... ], "way_points": [ { "order": Number, "lat": Number, "lng": Number }, ... ] }, ... ]
    POST /fleets/{fleet_id}/tracks
    This function adds a new track to a fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    nameString
    geofenceBoolean
    visible_upwardsBoolean
    visible_downwardsBoolean
    pois[ { "poi_id": Number, "order": Number }, ... ]
    way_points[ { "order": Number, "lat": Number, "lng": Number }, ... ]
    seetracks
    returnsthe id of the new track
    {"track_id": Number}
    GET /tracks
    This function returns a list of the tracks visible to the current user.
    include_navigBoolean
    if true, will include tracks used as navigation jobs; defaults to false
    seetracks
    returnsthe list of tracks
    [ { "track_id": Number, "name": String, "geofence": Boolean, "visible_upwards": Boolean, "visible_downwards": Boolean, "pois": [ { "poi_id": Number, "order": Number, "lat": Number, "lng": Number }, ... ], "way_points": [ { "order": Number, "lat": Number, "lng": Number }, ... ] }, ... ]
    GET /tracks/{track_id}
    This function returns detailed information about a track.
    track_idthe id of the desired track
    seetracks
    returns{ "track_id": Number, "name": String, "geofence": Boolean, "visible_upwards": Boolean, "visible_downwards": Boolean, "pois": [ { "poi_id": Number, "order": Number, "lat": Number, "lng": Number }, ... ], "way_points": [ { "order": Number, "lat": Number, "lng": Number }, ... ] }
    PATCH /tracks/{track_id}
    This function updates the information of a track.
    track_idthe id of the desired track
    fleet_idNumber
    nameString
    geofenceBoolean
    visible_upwardsBoolean
    visible_downwardsBoolean
    pois[ { "poi_id": Number, "order": Number }, ... ]
    way_points[ { "order": Number, "lat": Number, "lng": Number }, ... ]
    seetracks
    returnsthe message "ok"
    {"message": String}
    DELETE /tracks/{track_id}
    This function deletes a track.
    track_idthe id of the desired track
    seetracks
    returnsthe message "ok"
    {"message": String}
    GET /fleets/{fleet_id}/navig_jobs
    This function returns a list of the navigation jobs corresponding to a given fleet, that were created within a given period of time.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    seenavigation jobs
    returnsthe list of navigation jobs
    [ { "navig_job_id": Number, "name": String, "message": String, "remark": String, "lat": Number, "lng": Number, "vehicle_id": Number, "created": String, "start": String, "due": String, "state": Number, /* see navigation job states */ "poi_id": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }, ... ]
    POST /fleets/{fleet_id}/navig_jobs
    This function creates a new navigation job in a fleet.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    nameString
    messageString
    remarkString
    latNumber
    lngNumber
    vehicle_idNumber
    startString
    dueString
    poi_idNumber
    track_idNumber
    address{ "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String }
    seenavigation jobs
    note‣ the state of the new job is always set to New; see navigation job states for the available states
    ‣ if poi_id is given, the job will be associated with that POI and the following fields will be ignored: name, address, lat and lng
    ‣ if track_id is given, the job will be associated with that track and the following fields will be ignored: name, lat and lng
    returnsthe id of the new navigation job
    {"navig_job_id": Number}
    GET /navig_jobs
    This function returns a list of the navigation jobs that are accessible to the current user, that were created within a given period of time.
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    seenavigation jobs
    returnsthe list of navigation jobs
    [ { "navig_job_id": Number, "name": String, "message": String, "remark": String, "lat": Number, "lng": Number, "vehicle_id": Number, "created": String, "start": String, "due": String, "state": Number, /* see navigation job states */ "poi_id": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }, ... ]
    GET /navig_jobs/{navig_job_id}
    This function returns detailed information about a navigation job.
    navig_job_idthe id of the desired navigation job
    seenavigation jobs
    returns{ "navig_job_id": Number, "name": String, "message": String, "remark": String, "lat": Number, "lng": Number, "vehicle_id": Number, "created": String, "start": String, "due": String, "state": Number, /* see navigation job states */ "poi_id": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }
    PATCH /navig_jobs/{navig_job_id}
    This function updates the information of a navigation job.
    navig_job_idthe id of the desired navigation job
    nameString
    messageString
    remarkString
    latNumber
    lngNumber
    vehicle_idNumber
    startString
    dueString
    address{ "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String }
    seenavigation jobs
    note‣ if the job is associated to a point of interest, then its name, address and location will be updated with the supplied values
    ‣ a job cannot be modified unless it is New, Rejected, Cancelled or Completed; see navigation job states for the available states
    returnsthe message "ok"
    {"message": String}
    DELETE /navig_jobs/{navig_job_id}
    This function deletes a navigation job.
    navig_job_idthe id of the desired navigation job
    seenavigation jobs
    returnsthe message "ok"
    {"message": String}
    GET /fleets/{fleet_id}/carpool_reservations
    This function returns a list of the carpool reservations corresponding to a given fleet, that were created within a given period of time.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    seecarpool reservations
    returnsthe list of carpool reservations
    [ { "carpool_reservation_id": Number, "vehicle_id": Number, "user_id": Number, "created": String, "start": String, "stop": String, "cancelled": Boolean, "remark": String }, ... ]
    POST /vehicles/{vehicle_id}/carpool_reservations
    This function creates a new carpool reservation for a given vehicle. If no user_id is supplied, the current user will be assumed.
    vehicle_idthe id of the desired vehicle
    user_idNumber
    startString
    stopString
    remarkString
    seecarpool reservations
    returnsthe id of the new carpool reservation
    {"carpool_reservation_id": Number}
    GET /carpool_reservations
    This function returns a list of the carpool reservations accessible to the current user, that were created within a given period of time.
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    seecarpool reservations
    returnsthe list of carpool reservations
    [ { "carpool_reservation_id": Number, "vehicle_id": Number, "user_id": Number, "created": String, "start": String, "stop": String, "cancelled": Boolean, "remark": String }, ... ]
    GET /carpool_reservations/{carpool_reservation_id}
    This function returns detailed information about a carpool reservation.
    carpool_reservation_idthe id of the desired carpool reservation
    seecarpool reservations
    returns{ "carpool_reservation_id": Number, "vehicle_id": Number, "user_id": Number, "created": String, "start": String, "stop": String, "cancelled": Boolean, "remark": String }
    PATCH /carpool_reservations/{carpool_reservation_id}
    This function updates the information of a carpool reservation.
    carpool_reservation_idthe id of the desired carpool reservation
    user_idNumber
    startString
    stopString
    cancelledBoolean
    remarkString
    seecarpool reservations
    returnsthe message "ok"
    {"message": String}
    GET /fleets/{fleet_id}/vehicles/documents
    This function returns the documents of all the vehicles corresponding to a given fleet, within a given period of time.
    fleet_idthe id of the desired fleet, or "mine" for the current user's fleet
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    seedocuments
    returnsthe list of fuelings for each vehicle
    [ { "vehicle_id": String, "documents": [ { "document_id": String, "moment": String, "content_type": String, "name": String }, ... ] }, ... ]
    GET /vehicles/{vehicle_id}/documents
    This function returns the documents of a vehicle, within a specified period of time.
    vehicle_idthe id of the desired vehicle
    start_momentString
    defines the beginning of the desired period of time
    stop_momentString
    defines the end of the desired period of time
    seedocuments
    notethe interval of time must be less than a year
    returns[ { "document_id": String, "vehicle_id": Number, "moment": String, "content_type": String, "name": String }, ... ]
    POST /vehicles/{vehicle_id}/documents
    This function adds a document to a vehicle.
    vehicle_idthe id of the desired vehicle
    nameString
    the document name
    momentString
    document moment (defaults to now)
    content_typeString
    the document content type (e.g. image/jpeg)
    contentString
    base64-encoded content
    seedocuments
    notemaximum allowed document size is 10MB
    returnsthe message "ok", if everything went well
    {"message": String}
    GET /documents/{document_id}
    This function returns the details of a document.
    document_idthe id of the desired document
    seedocuments
    returns{ "document_id": String, "vehicle_id": Number, "moment": String, "name": String "content_type": String, "content": String /* base64-encoded */ }
    DELETE /documents/{document_id}
    This function deletes a document.
    document_idthe id of the desired document
    seedocuments
    returnsthe message "ok"
    {"message": String}
    GET /flavours
    This function return the available functionality flavours.
    requiresat least SafeFleet administrator user level
    returnsthe list of flavours
    { "flavour1": { "title": String, "func1": any, ... }, ... }
    GET /lookup_position
    This function performs a position lookup for a (lat, lng) pair. First, a search through all the points of interest accessible to the current user is done. Then, if no point of interest matched, a reverse geocoding is performed. If you need to look up more than one position, use lookup_positions instead.
    latNumber
    the latitude of the position
    lngNumber
    the longitude of the position
    force_addressBoolean
    set this to true to force the return of a reverse-geocoded address, ignoring all POIs
    langString
    the language code (e.g. en-us)
    noteeither the point of interest is returned or the found address, never both; however both the point of interest and the address may be null
    returnsthe "resolved" position
    { "display_name": String, "poi": { "poi_id": Number, "name": String, "category": String, "comment": String, "business": Boolean, "visible_upwards": Boolean, "visible_downwards": Boolean, "lat": Number, "lng": Number, "delta_lat": Number, "delta_lng": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }, "address": { "lat": Number, "lng": Number, "country": String, "state": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String } }
    POST /lookup_positions
    This function performs a lookup for multiple positions made of (lat, lng) pairs. First, a search through all the points of interest accessible to the current user is done. Then, if no point of interest matched, a reverse geocoding is performed.
    lat_lngs[ { "lat": Number, "lng": Number }, ... ]
    the list of positions
    force_addressBoolean
    set this to true to force the return of a reverse-geocoded address, ignoring all POIs
    langString
    the language code (e.g. en-us)
    note‣ the list of coordinates must not be larger than 1000 elements
    ‣ either the point of interest is returned or the found address, never both; however both the point of interest and the address may be null
    returnsthe list of "resolved" positions, in respective order
    [ { "display_name": String, "poi": { "poi_id": Number, "name": String, "category": String, "comment": String, "business": Boolean, "visible_upwards": Boolean, "visible_downwards": Boolean, "lat": Number, "lng": Number, "delta_lat": Number, "delta_lng": Number, "address": { "country": String, "county": String, "city": String, "street": String, "number": String, "postal_code": String, "phone": String, "email": String } }, "address": { "lat": Number, "lng": Number, "country": String "state": String,, "county": String, "city": String, "street": String, "number": String, "postal_code": String } }, ... ]
  9. Tables Of Constants
  10. Company Types
    Company TypeDescription
    "enterprise"Enterprise
    "self_employed"Self-employed Individual
    "individual"Individual
    "ngo"Non-governmental Organization
    "other"Other
    Activity Types
    Activity TypeDescription
    "international_transport"International Transport
    "mining_quarrying"Heavy Industry
    "manufacturing"Manufacturing
    "domestic_transport"Domestic Transport
    "distribution"Distribution
    "civil_engineering"Civil Engineering & Constructions
    "banks_insurance"Banks & Insurance
    "telecom"Telecom
    "public_utilities"Public Utilities
    "security"Security
    "agriculture"Agriculture
    "rent_a_car"Leasing & Rent-a-car
    "it"IT
    "retail"Retail
    "wholesale"Wholesale
    "real_estate"Real Estate
    "public_administration_defense"Public Administration & Defense
    "science_education"Science & Education
    "health"Health
    "arts_entertainment"Arts & Entertainment
    "extraterritorial_organizations_bodies"Extraterritorial Organizations & Bodies
    "individual"Individual
    "other"Other
    Vehicle Types
    Vehicle TypeDescription
    1Bike
    2Bus
    3Car
    4Helicopter
    5Motorcycle
    6Personal Tracker
    7Plane
    8Ship
    9Tank
    10Tractor
    11Train
    12Tram
    13Truck
    14Van
    15Excavator
    16Armored
    17Utility
    Vehicle Map Colors
    Vehicle Map ColorDescription
    "w"White
    "g"Gray
    "y"Yellow
    "r"Light Green
    "e"Light Red
    "p"Pink
    "b"Light Blue
    "o"Orange
    "n"Dark Green
    "d"Dark Red
    "m"Magenta
    "l"Dark Blue
    "x"Brown
    "k"Black
    Vehicle Map Sizes
    Vehicle Map SizeDescription
    "s"Small
    "n"Normal
    "b"Big
    Vehicle Statuses
    Vehicle StatusDescription
    -1Offline
    0Engine Off
    1Engine On
    User Levels
    User LevelDescription
    1Site Administrator
    2SafeFleet Administrator
    3Company Administrator
    4Department Administrator
    5Department Member
    Event Types
    Event TypeDescription
    "impact"Impact
    "harsh_acceleration"Harsh Acceleration
    "harsh_brake"Harsh Brake
    "harsh_cornering"Harsh Cornering
    "panic"Panic
    "overspeeding"Overspeeding
    "idle"Idling
    "no_gps_signal"No GPS Signal
    "no_gsm_signal"No GSM Signal
    "geofence_entered"Geofence Entered
    "geofence_left"Geofence Left
    "driver_id_enable"Driver Authentication Enabled
    "driver_id_disable"Driver Authentication Disabled
    "no_driver_id"No Driver Key
    "imob_off"Immobilizer Off
    "imob_on"Immobilizer On
    "no_external_power"No External Power
    "external_power_reconnected"External Power Reconnected
    "low_external_battery"Low External Battery
    "external_battery_charging"External Battery Charging
    "device_sabotage"Device Sabotage
    "unauthorized_door_opening"Unauthorized Door Opening
    "unauthorized_tractor_unit_detachment"Unauthorized Tractor Unit Detachment
    "unauthorized_tractor_unit_attachment"Unauthorized Tractor Unit Attachment
    "authorized_tractor_unit_detachment"Authorized Tractor Unit Detachment
    "authorized_tractor_unit_attachment"Authorized Tractor Unit Attachment
    "gprs_traffic_enable"GPRS Traffic Enabled
    "gprs_traffic_disable"GPRS Traffic Disabled
    "overtemperature"Overtemperature
    "undertemperature"Undertemperature
    "emergency_mode"Emergency Mode
    "tow"Tow
    Input IDs
    Input IDDescription
    1Door
    2Dumpster
    3Tipper
    4Pressure Pump
    5Vacuum Pump
    6Tractor Unit
    7Device Sabotage
    8Fuel Pump
    9Tank Cap
    Attribute Types
    Attribute TypeDescription
    1Number
    2Boolean
    3Text
    4Date
    5Formula
    6File
    7Link
    Common Vehicle Attributes
    Attribute NameType
    "Mandatory Insurance Agency"Text
    "Mandatory Insurance Agency Branch"Text
    "Mandatory Insurance Expiry Date"Date
    "Full Insurance Agency"Text
    "Full Insurance Agency Branch"Text
    "Full Insurance Expiry Date"Date
    "Vignette Expiry Date"Date
    "Leasing Expiry Date"Date
    "Technical Inspection Expiry Date"Date
    "Service At"Number
    "Last Service Date"Date
    "Oil Replacement At"Number
    "Last Oil Replacement Date"Date
    "Winter Tires Replacement At"Number
    "Last Winter Tires Replacement Date"Date
    "Summer Tires Replacement At"Number
    "Last Summer Tires Replacement Date"Date
    "Stationary Consumption"Number
    "Average Consumption"Number
    "Engine Displacement"Number
    "Power"Number
    "Tank Capacity"Number
    "Fuel Type"Text
    "Maximum Allowed Weight"Number
    "Passenger Places"Number
    "Category"Text
    Fuel Types
    Fuel TypeDescription
    1Gasoline
    2Diesel
    3LPG
    4Electric
    5Other
    StateDescription
    1New
    2Waiting For Execution
    3Rejected
    4Heading To
    5Executing
    6Cancelled
    7Completed
    StateDescription
    1Offline
    2Unavailable
    3Available
    4Idle
    5Busy
    6Paused
    Device Settings
    Setting NameDescriptionType
    "abs_odom_factor"the correction factor constant for the dashboard odometerNumber
    "abs_odom_offs"the offset constant for the dashboard odometerNumber
    "abs_odom_prefer"true when the distance is computed from dashboard odometer,
    false when GPS odometer is used
    Boolean
    "driver_auth"empty string or null when driver authentication is disabled,
    "*" when any supplied driver key is accepted,
    driver group id when only a specific group of drivers are accepted
    String
    "idling_threshold"the interval after which an idling event is generated, in secondsNumber
    "immobilizer"the state of the immobilizer relayBoolean
    "overspeeding_threshold"the speed above which an overspeeding event is generated, in km/hNumber
    "temp1_hyst" ... "temp4_hyst"the temperature hysteresis threshold, in ° CNumber
    "temp1_max" ... "temp4_max"the upper limit of the valid temperature interval, in ° CNumber
    "temp1_min" ... "temp4_min"the lower limit of the valid temperature interval, in ° CNumber
    "tracking"the tracking stateBoolean
    Ticket Statuses
    StatusDescription
    0Open
    1Closed
    2Invalid
    3Accepted
    Tacho States
    StateDescription
    -1Absent
    0Rest
    1Available
    2Work
    3Drive
    4Unknown
  11. Example
  12. The example described here fetches the list of all the vehicles accessible to the current user. It picks one of the vehicles and obtains detailed information about it. Then, the name and the working schedule of this vehicle are updated.
    HTTP Messages
    (a) The (unauthenticated) client tries to get list of vehicles. The API asks for authentication:
    Client
    GET /vehicles
    Server
    GET /safefleet/api/vehicles HTTP/1.1
    Host: api.safefleet.eu
    Client
    403 Forbidden
    Server
    HTTP/1.1 403 Forbidden
    Content-Type: application/json
    {"message": "authentication required"}
    (b) The client authenticates. The server sends a cookie with the session id:
    Client
    POST /authenticate
    Server
    POST /safefleet/api/authenticate HTTP/1.1
    Host: api.safefleet.eu
    Content-Type: application/json
    {"username": "test", "password": "1234"}
    Client
    200 OK
    Server
    HTTP/1.1 200 OK
    Content-Type: application/json
    Set-Cookie: sessionid=4ce508d20832d12a64fd49ecb336a7b6
    {"message": "ok"}
    (c) The client reissues the GET /vehicles request, this time with the session id cookie. The server replies with the vehicles:
    Client
    GET /vehicles
    Server
    GET /safefleet/api/vehicles HTTP/1.1
    Host: api.safefleet.eu
    Cookie: sessionid=4ce508d20832d12a64fd49ecb336a7b6
    Client
    200 OK
    Server
    HTTP/1.1 200 OK
    Content-Type: application/json
    [ {"vehicle_id": 1234, "name": "Vehicle A", ...}, {"vehicle_id": 2345, "name": "Vehicle B", ...} ... ]
    (d) The client updates the name and the working schedule of the vehicle. The server simply answers with an "ok":
    Client
    PATCH /vehicles/{id}
    Server
    PATCH /safefleet/api/vehicles/1234 HTTP/1.1
    Host: api.safefleet.eu
    Content-Type: application/json
    Cookie: sessionid=4ce508d20832d12a64fd49ecb336a7b6
    { "name": "My Vehicle", "working_schedule": { "mon": { "from_minute": 0, "to_minute": 0, "from_hour": 8, "to_hour": 18 }, ..., "fri": { "from_minute": 0, "to_minute": 0, "from_hour": 8, "to_hour": 18 } } }
    Client
    200 OK
    Server
    HTTP/1.1 200 OK
    Content-Type: application/json