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:

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
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 Basic Concepts for more details)
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:

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

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

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

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:

GET /delegate/barcode:299281713529

Example response:

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

PATCH /delegate/barcode:299281713529

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

Example response:

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

POST /delegate/new

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

Example response:

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

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

Example response:

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