``POST /device/handshake``
==========================

Synopsis
--------

Establish the connection between a mobile device and the platform before normal communication begins.

The service registers the device with the information about the client application that initiates this request.

The registration of the device is pending until an individual user or an administrator of an organization responsible for this device reviews the information provided.  The device cannot access all the services supported by the platform until the device has been activated.


Request Header Fields
---------------------

.. include:: /_include/anonymous_session_header_fields.inc


Request URL Bits
----------------

None.


Request Query Parameters
------------------------

None.


Request Message Body
--------------------

The HTTP request must provide the following JSON data::

    {
      "location": {
        "accuracy": decimal,
        "altitude": decimal,
        "bearing": decimal,
        "fix_time": timestamp,
        "latitude": decimal,
        "longitude": decimal,
        "provider": string,
        "speed": decimal
      },
      "mac_address": string,
      "serial_number": string
    }

where:

* ``battery_level`` (required): The current level in percentage of the battery of the mobile device.

* ``is_battery_plugged`` (required): Indicate if the internal battery of the mobile device is plugged to a power source.

* ``is_battery_present`` (required): Indicate whether the mobile device is equipped with an internal battery.  A device not equipped with an internal battery is less secure as it is not able to send any notification when it is disconnected from the power source of the vehicle this device is mounted on; the device is immediately shutdown.

* ``location`` (optional): The last known location of the mobile device:

  * ``accuracy`` (required): The accuracy in meters of the location.

  * ``altitude`` (required): The altitude in meters of the location.

  * ``bearing`` (optional): The bearing in degrees of the mobile device.  Bearing is the horizontal direction of travel of the device, and is not related to the device orientation.  The value is guaranteed to be in the range ``[0.0, 360.0]``.

  * ``fix_time`` (required): The time when the device determined the information of this fix.

  * ``latitude`` (required): The latitude-angular distance, expressed in decimal degrees (WGS84 datum), measured from the center of the Earth, of a point north or south of the Equator corresponding to the location.

  * ``longitude`` (required): The longitude-angular distance, expressed in decimal degrees (WGS84 datum), measured from the center of the Earth, of a point east or west of the Prime Meridian corresponding to the location.

  * ``provider`` (required): The type of the location provider that reported this geographical location:

    * ``fused``: The location API in Google Play services that combines different signals to provide the location information.

    * ``gps``: This provider determines location using satellites (Global Positioning System (GPS).

    * ``network``: This provider determines location based on availability of cell towers and Wi-Fi access points.  Results are retrieved by means of a network lookup.

    * ``passive``: A special location provider for receiving locations without actually initiating a location fix.  This provider can be used to passively receive location updates when other applications or services request them without actually requesting the locations yourself.  This provider will return locations generated by other providers.

  * ``speed`` (optional): Speed in meters/second over the ground.

* ``mac_address`` (required): Media Access Control (MAC) address of the device.  A MAC address is a unique identifier assigned to a network interface for communications at the data link layer of a network segment.

* ``serial_number`` (required): The hardware serial number of the mobile device.  It corresponds to a unique number assigned by the manufacturer to help identify an individual device.

  .. note:: Because the operating system of the mobile device may restrict access to persistent device identifiers, the serial number of the mobile device may not be provided.

  .. note::  Serial number is case-sensitive.


---------------------
Response Message Body
---------------------

The platform returns the following JSON form::

    {
      "account_id": "string",
      "device_id": "string",
      "object_status": string,
      "team": {
        "name": string,
        "picture_id": string,
        "picture_url": string,
        "team_id": string
      }
    }



where:

- `account_id` (optional): The identification of the account of the user who has activated the device.  This is either an individual user (the owner of the device), either an administrator of the organization that manages this device.

- ``device_id`` (required): The identification of the mobile device.

- ``object_status`` (required): The current status of the device:

  - ``deleted``:  The device has been banned by an administrator of the platform.  All services for this device are currently inaccessible.

  - ``disabled``: The device has been suspended by the individual user who has activated this device or an administrator of the organization that manages this device.

  - ``enabled``: The device is activated and is expected to operate properly. device is activated.

  - ``pending``: The device has not been activated yet.

- ``team`` (optional): The organization that has activated this mobile device.

  - ``name`` (required): The name of the organization.

  - ``picture_id`` (required): The identification of the picture representing the organization's logo.

  - ``picture_url`` (required): The Uniform Resource Locator (URL) of picture representing the organization's logo.

  - ``team_id`` (required): The identification of the organization on behalf of which an administrator has activated the device.


Exceptions
----------

* ``DeletedObjectException``: If the team that is managing the device has been deleted, or if the account of the individual user who has activated this device has been deleted.

* ``DisabledObjectException``: If the team that is managing the device has been disabled, or if the account of the individual user who has activated this device has been disabled.
