Introduction
Context
We operate in the exhibitions and live events industry.
Our focus is registration data. This is various types of visitors and exhibitors attending trade exhibitions, conferences, and other live events.
We wish to understand what events people go to, whether they attended, and what are their interests or demographics.
We also provide for events where people pay for entry or additional options such as conferences places and seminars.
The exhibitors at events may be offered a lead recording solution. This allows the exhibitors to record visitors to the event as potential sales leads. This can be done using our mobile app, or a handheld scanner.
Scope & Support
License: We license our APIs for specific use cases to enable us to ensure we provide the right solution and support for your specific scenario.
Discovery Call: If your use case is not covered by this document, we will setup a discovery call to ensure that we have a mutual understanding of the requirements and license our solution according to your needs.
Kick Off: Even in the most basic integrations, it is often easier and quicker to have a quick discovery call to ensure that we can support you and integration proceeds smoothly.
Build a Team: Use this guide or give it to your technical integration team to support you in connecting with our systems.
We aim to provide the essential information on our APIs in this guide to enables you to succeed with the most typical usage scenarios. If you are unclear or have a different use case, please contact us for a discovery call. We will be happy to help understand your needs and strive to provide a solution.
You will not find technical documentation on how JSON and SOAP APIs work in general, this knowledge is assumed.
Overview
Basics
We setup logins to our online systems for you. You will receive a welcome e-mail with your username and password.
The login will have security access to events and systems appropriate to your role. It should not be shared with other users.
A specific login will usually be created for the API calls. This is to ensure that password changes for a user do not interrupt the integration.
Events
Our APIs are specific to an event/show.
You will need to supply an EventRef to determine which event you are accessing. This will be advised to you by your project manager.
Each event on our system has a unique event reference.
Demographics
Each event has a unique profile setup for visitors.
This demographic profile is a series of questions and answers which are decided by you, the customer.
They can be checkbox, drop-down, multi-choice and free typing fields when they appear on our forms.
The demographic data is available in our system as reports, exports, and included in the API responses.
Our APIs are self-describing – although we include the coding used within our system, we also return the textual meaning of the codes.
Each question has a unique identifier in our system and each answer has a unique code.
Here is an example:
| Question: | Identified in our system: |
| How did you hear about this event? | Analysis.HowHeard |
| Answers: | Code in our system: |
| Word of mouth | 1A |
| E-mail newsletter | 1B |
| Facebook ad | 1C |
| Trade journal flyer | 1D |
| Other | 1Z |
To understand the data, you can log in to JET Reporting and JET Data to visualise and export the records.
To Retrieve Records
The basic operation of our API is a follows:
- We set up the event in our system and advise you of the EventRef
- We send you an account with a login and password to access the system
- We setup a QueueIdentifier and advise you which create a unique feed
- Every time a record is added (someone registers) or is updated in our system, it will be added to the queue
- Your integration will call the LookupQueue API to retrieve the next set of records available (we recommend 20 at a time)
- You will receive the records and add or update them in your database
- The LookupQueue will also send a timestamp to identify the set of records returned.
- Your program will confirm the successful receipt of the records by calling the MarkQueue API with the timestamp.
- Your program can then immediately request the next set of records.
- If no records are available when calling the API, we recommend your program waits for a couple of minutes and then tries again.
For each event we will advise you of the correct queue identifier to use.
We will initialise each queue with all the records available. As records are updated or added, they will add to the queue ready for you to download. We recommend polling our systems every couple of minutes to see if new records are available and then retrieving up to 20 records at a time.
We can reset the queue for you when required if records must be re-sent or you have completed testing.
Demo Program
We have a sample program written in VB.Net to help you understand better how to make the API calls. Most platforms PHP, Node, .Net and Python have built in or easily accessible components to access SOAP APIs. The sample app uses the SOAP interface to download records 20 at a time:
https://eventdata.uk/Downloads/SOAPDemo-eventdata.co.uk.zip
Our sample program just logs names to a text file. The intention is for you to take the data the is needed and write it to a database.
To successfully retrieve records requires the use of 2 methods:
SOAPRecords.Records.LookupQueue:-
To load the next X records in the queue
SOAPRecords.Records.MarkQueue:-
To tell system you have received them safely, or you will get them again
To use the demo program, you need to enter some settings:
- Please enter your own username and password. Click ‘Save’ and then (to follow)
- Click ‘Select’ to choose an event (you can’t choose an event until you have entered username/password)
- We issue an event ref. and queue identifier to select the correct records, select and enter these.
- Then enter a filename to dump to and click ‘Save’ again and click ‘Start’.
Sending Us Records
You would use the Records API Submit method:
https://eventdata.uk/SOAP/Records.asmx?op=Submit
RecordNumber should be set to -1 and BadgeRef should be left blank. This will then automatically assign a new record number.
Most of fields in the system are self-explanatory however as mentioned above, demographic fields vary by event.
It is important to ensure the reply is received from our system to acknowledge receipt which will include the assigned record number.
If you do not receive a valid response, you should understand if this is an integration error to be fixed or a transient error which can be retried.
If you successfully receive a reply, it means the record has been successfully stored in our database.
If the event is live, the record will be automatically downloaded to the on-site systems at the venue, ready for the end-user to be found on the system and potentially collect their badge.
API End Points
APIs are stable and we also use them internally to send and receive data, so you can be assured that they are working correctly.
The endpoints can be accessed either as:
SOAP using XML
or
JSON
Events
https://eventdata.uk/SOAP/Events.asmx
Obtain information about the event, and demographic setup.
