Delegate
========

A delegate is a user that interacts with Satellite Tag devices, usually through a NFC chip or a barcode. Examples of
interactions can be:

- the delegate registers at a registration desk by showing their barcode and/or providing some personal details;
- the delegate scans their wristband or lanyard against a mobile phone when entering a room to attend a session;
- the delegate scans their wristband or lanyard against a mobile phone after taking a picture to receive their
  personalised content in their mobile site companion;
- two delegates scan their wristband or lanyard against a tablet to connect with each other and exchange their
  virtual business card.

All these interactions involve:

1. a **unique code** that identifies the delegate, it's either a NFC chip or a barcode/QR code, but it can be the raw ID
   of the delegate
2. a **device**, usually a session, a sponsor or a UHF reader, but can be literally any registered *device* (the
   word device is used here as a generic term that encompass all different objects the delegate can interact with,
   see :doc:`/basic_concepts` for more details)
3. a **recording device** (or **app**), it can be a mobile phone, a registration station or any other digital device
   consuming our REST API.

Some simple interactions are *check-ins* and *joins* and complex interactions are for example *leads* and *connections*
because they involve extra steps.

Delegate Flags
--------------

Flags are a simple way of tracking some specific choices or interactions made or triggered by the delegate. Flags should
always be stored lowercase. The following list includes only the core flags:

+---------+------------------------------------------------------------------------------------------------------------+
| Flags   | Meaning                                                                                                    |
+=========+============================================================================================================+
| a,b,c,d | Reserved for instance specific purposes                                                                    |
+---------+------------------------------------------------------------------------------------------------------------+
| e       | The delegate has opened an email sent by Tag                                                               |
+---------+------------------------------------------------------------------------------------------------------------+
| f       | The delegate has sent their feedback                                                                       |
+---------+------------------------------------------------------------------------------------------------------------+
| k       | The delegate is a Spark customer                                                                           |
+---------+------------------------------------------------------------------------------------------------------------+
| p       | The delegate has made their profile public for other delegate to see                                       |
+---------+------------------------------------------------------------------------------------------------------------+
| s       | The delegate has seen the splash screen page/pop-up and answered any questions in it                       |
+---------+------------------------------------------------------------------------------------------------------------+
| v       | The delegate has visited their mobile site                                                                 |
+---------+------------------------------------------------------------------------------------------------------------+

Flags from ``a`` to ``d`` are reserved for instance specific purposes.

Object Shape
------------

A delegate object will always have this shape when not embedded into another object:

.. code-block:: json

  {
    "id": "integer",
    "_type": "string",
    "parent": "object:delegate",
    "children": "array:delegate",
    "barcode": "string",
    "publicId": "string",
    "rfid": "string",
    "externalId": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "phone": "string",
    "jobTitle": "string",
    "company": "string",
    "sources": "array:string",
    "data": "object",
    "firstInteractions": "array:interaction",
    "secondInteractions": "array:interaction",
    "thirdInteractions": "array:interaction",
    "createdAt": "string",
    "updatedAt": "string"
  }

The ``data`` property inside the delegate object will have this shape:

.. code-block:: json

  {
    "Section1": "object",
    "Section2": "object",
    "Section3": "object"
  }

Where the sections are defined in the system configuration and are available for inspection in the Control Room.

The ``interactions`` property inside the delegate object is a list of interaction. Refer to the shape of interaction
objects to understand how the list will look like.

GET /delegate/list
------------------

Gets all delegates.

All properties available for the authenticated client will be returned.

.. note::

  This method supports pagination.

  Use limit and offset to paginate returned results. The defaults if no limit or offset are provided are limit=5000 and
  offset=0.

  GET /delegate/list?offset=0&limit=5000

  The total result set count is returned in all responses in the ``meta`` property. Links to the next or previous page
  are also provided in the same property.

Response
........

The response is a collection of delegates. The collection can be empty (``[]`` in JSON).

.. code-block:: json

  {
    "data": [
      {
        "id": 1,
        "_type": "delegate",
        "firstName": "Someone",
        "lastName": "Gioffreda",
        "sources": [
          "admin",
          "api"
        ],
        "createdAt": "2017-09-28T12:35:38+13:00",
        "updatedAt": "2017-09-28T13:23:02+13:00"
      },
      {
        "id": 8,
        "_type": "delegate",
        "rfid": "7894561230",
        "firstName": "Someone",
        "sources": [
          "admin",
          "api"
        ],
        "createdAt": "2017-09-28T13:18:56+13:00",
        "updatedAt": "2017-09-28T13:22:43+13:00"
      }
    ],
    "meta": {
      "pagination": {
        "totalItems": 1056,
        "totalPages": 528,
        "offset": 0,
        "limit": 2,
        "next": "/api/5/delegate/list.json?q=firstName%3Dsomeone"
      }
    }
  }

Errors and Exceptions
.....................

General rule is that this method should not return an exception because it's read only. Although general failures or
service unavailability may occur, in that case a `5xx` error will be returned.

See the list of `Error Responses`_ for more information.

GET /delegate/{idType}:{id}
---------------------------

Gets a specific delegate.

All properties available for the authenticated client will be returned.

Available identifier types are: ``id``, ``rfid``, ``barcode``, ``externalId``, ``publicId``.

.. code-block:: text

  GET /delegate/id:820
  GET /delegate/rfid:1234567890
  GET /delegate/barcode:9876543210
  GET /delegate/publicId:337cb1d6-ec42-417b-b9b6-596458c679bc

See the list of `Error Responses`_ for more information, in particular error 1301.

Example request:

.. code-block:: text

  GET /delegate/barcode:299281713529

Example response:

.. code-block:: json

  {
    "data": {
      "id": 29,
      "_type": "delegate",
      "barcode": "299281713529",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+123456789",
      "jobTitle": "Dev",
      "company": "Acme Ltd",
      "sources": [
        "api"
      ],
      "createdAt": "2018-03-13T23:31:32+00:00",
      "updatedAt": "2018-03-13T23:31:32+00:00"
    },
    "meta": {}
  }

PATCH /delegate/{idType}:{id}
-----------------------------

Patches a delegate.

All properties provided in the request will be updated to the given value.

**When calling this you must only provide the properties that you want to change, and nothing else.**

See the list of `Error Responses`_ for more information, in particular error 1301.

Example request:

.. code-block:: text

  PATCH /delegate/barcode:299281713529

.. code-block:: json

  {
    "firstName": "Jane",
    "company": "Acme Ltd",
  }

Example response:

.. code-block:: json

  {
    "data": {
      "id": 29,
      "_type": "delegate",
      "barcode": "299281713529",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+123456789",
      "jobTitle": "Dev",
      "company": "Acme Ltd",
      "sources": [
        "api"
      ],
      "createdAt": "2018-03-13T23:31:32+00:00",
      "updatedAt": "2018-03-13T23:31:32+00:00"
    },
    "meta": {}
  }

POST /delegate/new
------------------

Creates a new delegate.

Example request:

.. code-block:: text

  POST /delegate/new

.. code-block:: json

  {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+123456789",
    "jobTitle": "Dev",
    "company": "Acme Ltd",
    "barcode": "299281713529"
  }

Example response:

.. code-block:: json

  {
    "data": {
      "id": 29,
      "_type": "delegate",
      "barcode": "299281713529",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+123456789",
      "jobTitle": "Dev",
      "company": "Acme Ltd",
      "sources": [
        "api"
      ],
      "createdAt": "2018-03-13T23:31:32+00:00",
      "updatedAt": "2018-03-13T23:31:32+00:00"
    },
    "meta": {}
  }

DELETE /delegate/{idType}:{id}
------------------------------

Deletes a delegate.

This will soft-delete a delegate from the system, hard deletion is available only from the Control Room.

See the list of `Error Responses`_ for more information, in particular error 1301.

GET /delegate/myself
--------------------

Gets the logged in delegate.

For this endpoint to work, the client must use a "user access token" obtained through the "password" grant type. The
output of this API is identical to the output of the `GET /delegate/{idType}:{id}`_ endpoint.

If the client uses a "client credentials" access token, a 401 error will be returned.

DELETE /delegate/myself
-----------------------

Deletes the logged in user and attached delegate. **This operation cannot be undone.**

All interactions belonging to the logged in user will also be deleted, and their details erased from the
denormalisation tables. Any token issued will also be cancelled and invalid.

For this endpoint to work, the client must use a "user access token" obtained through the "password" grant type.

If the client uses a "client credentials" access token, a 401 error will be returned.

POST /delegate/send-comm
------------------------

Sends an SMS and/or email to a delegate. The response is an object with ``sms_sent`` and ``email_sent`` properties that
tell if the communication was sent successfully or not. Common reasons for a comm not to be send are:

- backend settings: communications to delegates can be turned off
- invalid recipient: the email or phone number don't match the requirements
- gateway is down: ie EziTxt or SendGrid are unavailable or the credentials are wrong

See the list of `Error Responses`_ for more information, in particular error 1301.

Example request:

.. code-block:: json

  {
    "sms_code": "WELCOME",
    "email_id": 8,
    "delegate_id": 4
  }

Example response:

.. code-block:: json

  {
    "data": {
      "sms_sent": true,
      "email_sent": false
    },
    "meta": {}
  }

.. _Error Responses: /rest_api/index.html#error-responses