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 target 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.
GET /delegate/list¶
Gets all delegates.
All available properties will be shown. You should not be using this to download the full list of delegates, use the delegate cache method instead. This method should be used
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 or /delegate/cache?offset=0&limit=5000
The total result set count is returned in all responses with the HTTP header: X-Total-Count.
Links to the next or previous page are provided in the HTTP header links block as well
Link: <https://demo.satellitetag.co.nz/delegate/list?offset=15&limit=5>; rel="next",
<https://demo.satellitetag.co.nz/delegate/list?offset=50&limit=3>; rel="last",
<https://demo.satellitetag.co.nz/delegate/list?offset=0&limit=5>; rel="first",
<https://demo.satellitetag.co.nz/delegate/lists?offset=5&limit=5>; rel="prev",
Parameters¶
| Method | GET |
| Query | |
| HTTP Status Code |
|
- exactMatch
type array required false
Find the delegates matching the given filters. Requires an exact match (case insensitive).
exactMatch[barcode]=1234567890 exactMatch[barcode]=1234567890&exactMatch[rfid]=ABCDEFGHIL
Response¶
The response is a collection of delegates. The collection can be empty ([] in JSON).
[
{
"id": 1,
"firstName": "Someone",
"lastName": "Gioffreda",
"sources": [
"admin",
"api"
],
"createdAt": "2017-09-28T12:35:38+13:00",
"updatedAt": "2017-09-28T13:23:02+13:00"
},
{
"rfid": "7894561230",
"id": 8,
"firstName": "Someone",
"sources": [
"admin",
"api"
],
"createdAt": "2017-09-28T13:18:56+13:00",
"updatedAt": "2017-09-28T13:22:43+13:00"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<result>
<entry>
<id>1</id>
<firstName><![CDATA[Someone]]></firstName>
<lastName><![CDATA[Gioffreda]]></lastName>
<sources>
<entry><![CDATA[admin]]></entry>
<entry><![CDATA[api]]></entry>
</sources>
<createdAt><![CDATA[2017-09-28T12:35:38+13:00]]></createdAt>
<updatedAt><![CDATA[2017-09-28T13:23:02+13:00]]></updatedAt>
</entry>
<entry>
<rfid><![CDATA[7894561230]]></rfid>
<id>8</id>
<firstName><![CDATA[Someone]]></firstName>
<sources>
<entry><![CDATA[admin]]></entry>
<entry><![CDATA[api]]></entry>
</sources>
<createdAt><![CDATA[2017-09-28T13:18:56+13:00]]></createdAt>
<updatedAt><![CDATA[2017-09-28T13:22:43+13:00]]></updatedAt>
</entry>
</result>
GET /delegate/{idType}:{id}¶
Gets a specific delegate.
All available properties will be shown. Available identifier types are: id, rfid, barcode, externalId,
uhfId.
GET /delegate/id:820.json
GET /delegate/rfid:1234567890.json
GET /delegate/barcode:9876543210.json
GET /delegate/externalId:337cb1d6-ec42-417b-b9b6-596458c679bc.json
GET /delegate/uhfId:E2000017571701072790046D.json
PATCH /delegate/{idType}:{id}¶
Patches a delegate.
All properties provided in the request will be updated to the given value.
Note
There is a notable exception: a unique code cannot be unset.
That is if you try and set the rfid property to null for example, nothing will happen. Unique codes can only
be replaced through this API.
Unique codes are: rfid, barcode and externalId. The id of a delegate can never change.
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:
{
"barcode": "299281713529",
"id": 29,
"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"
}
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. Trying and getting or patching a deleted delegate will result in a
404 Not Found error.
GET /delegate/cache¶
Gets a list of all delegates for client side caching. You can specify a set of fields you want to cache and only those
will be returned. The delegate’s id will always be returned, even if you don’t ask for it.
If you add the If-Modified-Since header to your request, only delegates created or updated after the given date and
time will be returned. The format of If-Modified-Since header can be any format currently accepted by PHP.
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 or /delegate/cache?offset=0&limit=5000
The total result set count is returned in all responses with the HTTP header: X-Total-Count.
Links to the next or previous page are provided in the HTTP header links block as well
Link: <https://demo.satellitetag.co.nz/delegate/cache?offset=15&limit=5>; rel="next",
<https://demo.satellitetag.co.nz/delegate/cache?offset=50&limit=3>; rel="last",
<https://demo.satellitetag.co.nz/delegate/cache?offset=0&limit=5>; rel="first",
<https://demo.satellitetag.co.nz/delegate/cache?offset=5&limit=5>; rel="prev",
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 Modica or SendGrid are unavailable or the credentials are wrong
Example request:
{
"sms_name": "Welcome",
"email_id": 8,
"delegate_id": 4
}
Example response:
{
"sms_sent": true,
"email_sent": false
}