EventStream Game API (Version 2.0)

Last Modified on 04/29/2024 5:41 am EDT

< Want to jump to a particular section? Use the contents tab to the right of this article

The API provides methods to retrieve from and send data to EventsAir.

Request and return values are in json format.

API base URL: “API Base URL from App Store in EventsAir”

All requests must contain the following headers:

Key	Value	Source
ApiKey	{api key}	To be provided by Centium Software.
AppUserName	{portal user username}	Provided by the customer from the Portal User configured in the App Store in EventsAir, by adding the EventStream Game API App and configuring the settings and creating a user.
AppPassword	{portal user password}	Provided by the customer from the Portal User configured in the App Store in EventsAir, by adding the EventStream Game API App and configuring the settings and creating a user.

METHOD

GetConfiguration

GET
/GetConfiguration
Retrieves a collection of Prizes and Goals from the EventsAir setup.

Return:
Collection of Prizes and Goals objects.

Prizes:

Field	Type	Nullable	Description
Id	String	No	Id of Prize
Name	String	No	Name of Prize
Description	String	Yes	Description of Prize
PrizeOrder	Int	No	Order number for ordering the list of Prizes
AdditionalInformation	String	No	Additional Information HTML of Prize
CoinsRequired	Int	No	Number of Coins required for Prize
ImageUri	String	Yes	Uri for Image for Prize

Goals:

Field	Type	Nullable	Description
Id	String	No	Id of Goal
Name	String	No	Name of Goal
Description	String	Yes	Description of Goal
IconUnicode	String	Yes	Unicode value for Icon of Goal
IconColor	String	Yes	Hex color value for Icon of Goal
Points	Int	No	Number of Points of Goal
DisplayAsMysteryPoints	Bool	No	Value of Display as Mystery Points of Goal
Instructions	String	No	Instructions HTML of Goal
GoalOrder	Int	No	Order number for ordering the list of Goals
CustomIconUri	String	Yes	Uri for Custom Icon Image for Goal

JSON data example:

The following example shows a Prize and a Goal.

{
     "Prizes": [
        {
            "Id": "891c4453-6aed-4dfa-a300-9c8c940510e5",
             "Name": "Food: Donuts",
             "Description": null,
             "PrizeOrder": 1,
             "AdditionalInformation": ",
            "CoinsRequired": 10,
             "ImageUri": null
        } ],
     "Goals": [
       {
             "Id": "7cbb01d8-989a-4892-92ac-681292464001",
             "Name": "Attend Chalk-Talk #2",
            "Description": null,
            "IconUnicode": null,
            "IconColor": "#000000",
             "Points": 200,
             "DisplayAsMysteryPoints": false,
             "Instructions": "",
             "GoalOrder": 0,
             "CustomIconUri": null
        }  ]
}

METHOD

UpdateExternalId

POST
/UpdateExternalId

Form Data Parameters

Parameter	Type	Optional	Description
ExternalId	String	No	Id of tag to be saved against contact records in EventsAir
QrCode	String	Yes	Value from scan of QRCode for Contact
Barcode	String	Yes	Value of scan of Barcode for Contact
InternalId	String	Yes	Guid for Contact from EventsAir
ContactIdentifier	Int	Yes	ID number as displayed on the Contact from EventsAir

Sends an ExternalID to be associated with a Contact in EventsAir, must contain the externalId parameter and at least one of the other parameters to be a valid call.

Return:

Response object.

Field	Type	Nullable	Description
Success	Bool	No	Value for success of call
ContactName	String	Yes	Name of Contact that was updated from EventsAir when call is successful
ErrorMessage	String	Yes	Description of Error if call was not successful

JSON data example:

The following example shows response from a successful call.

{
    "Success": true,
    "ContactName": "Archie Barker",
    "ErrorMessage": null
}

METHOD

AddPoints

POST
/AddPoints

Form Data Parameters

Parameter	Type	Optional	Description
GoalId	String	No	Id of Goal to add points for as returned in the GetConfiguration method
ExternalId	String	Yes	Id of tag already saved against contact record in EventsAir
QrCode	String	Yes	Value from scan of QRCode for Contact
Barcode	String	Yes	Value of scan of Barcode for Contact
InternalId	String	Yes	Guid for Contact from EventsAir
ContactIdentifier	Int	Yes	ID number as displayed on the Contact from EventsAir
SendPushNotification	Bool	Yes	If set to true will push a notification to the user in the EventsAir Attendee App to confirm the points assigned.

Sends a goalId and one of the optional parameters to add points for the goal to the contact in EventsAir, must contain the goalId parameter and at least one of the following optional parameters of externalId, qrCode, barcode, internalId, contactIdentifier to be a valid call.

Return:

Response object.

Field	Type	Nullable	Description
Points	Int	Yes	Number of points added if points are successfully allocated.
ErrorCode	String	No	Error Code if not able to process the points successfully but the call is valid. The text for the error is retuned in Error message. Codes returned are: 001 = Invalid Goal 002 = Not active at this time 003 = No longer available (max inventory reached) 004 = No longer available for this person (max inventory reached) Or if successful call an empty string is returned.
Success	Bool	No	Value for success of call, will return false is call is invalid or an error code is returned.
ContactName	String	Yes	Name of Contact that was updated from EventsAir when call is successful
ErrorMessage	String	Yes	Description of Error if call was not successful.

JSON data successful response example:

The following example shows response from a successful call.

{
     "Points": 10,
     "ErrorCode": "",
     "Success": true,
     "ContactName": "Archie Barker",
     "ErrorMessage": null
}

JSON data unsuccessful response example:

The following example shows response from a unsuccessful call.

{
    "Points": 0,
    "ErrorCode": "004",
    "Success": false,
    "ContactName": "Archie Barker",
    "ErrorMessage": "No longer available for this person (max inventory reached)"
}

METHOD

AddPointsBatch

POST
/AddPointsBatch

Form Data parameter of PointsBatch that has a value of the json formatted collection of PointsBatch

PointsBatch:

Field	Type	Nullable	Description
GoalId	String	No	Id of Goal to add points for as returned in the GetConfiguration method
ExternalId	String	Yes	Id of tag already saved against contact record in EventsAir
QrCode	String	Yes	Value from scan of QRCode for Contact
Barcode	String	Yes	Value of scan of Barcode for Contact
InternalId	String	Yes	Guid for Contact from EventsAir
ContactIdentifier	Int	Yes	ID number as displayed on the Contact from EventsAir
SendPushNotification	Bool	Yes	If set to true will push a notification to the user in the EventsAir Attendee App to confirm the points assigned.

JSON data example:

{ "PointsBatch": [ {
"GoalId": "29bcc754-fabe-4ff8-bb79-1e4edab37f77",
"ExternalId": null,
"QrCode": null, 
"Barcode": null,
"InternalId": null,
"ContactIdentifier": 17,
"SendPushNotification": false
} ]
}

Return:

Response object.

Field	Type	Nullable	Description
Success	Bool	No	Value for success of call
ContactName	String	Yes	Will always be null
ErrorMessage	String	Yes	Description of Error if call was not successful.

JSON data successful response example:

The following example shows response from a successful call.

{
    "Success": true,
    "ContactName": null,
    "ErrorMessage": null
}

METHOD

CheckCoins

POST
/CheckCoins

Form Data Parameters

Parameter	Type	Optional	Description
ExternalId	String	Yes	Id of tag already saved against contact record in EventsAir
QrCode	String	Yes	Value from scan of QRCode for Contact
Barcode	String	Yes	Value of scan of Barcode for Contact
InternalId	String	Yes	Guid for Contact from EventsAir
ContactIdentifier	Int	Yes	ID number as displayed on the Contact from EventsAir

Sends at least one of the following optional parameters of ExternalId, QrCode, Barcode, InternalId, ContactIdentifier to be a valid call.

Return:

Response object.

Field	Type	Nullable	Description
Coins	Int	No	Always 0
CoinsBalance	Int	No	Current Balance of Coins if call is successful.
ErrorCode	String	No	Always returned as empty String
Success	Bool	No	Value for success of call
ContactName	String	Yes	Name of Contact from EventsAir when call is successful
ErrorMessage	String	Yes	Description of Error if call was not successful.

JSON data response example:

The following example shows response from a successful call.

{
    "Coins": 0,
    "CoinsBalance": 70,
    "ErrorCode": "",
    "Success": true,
    "ContactName": "Archie Barker",
    "ErrorMessage": null
}

METHOD

RedeemCoins

POST
/RedeemPoints

Form Data Parameters

Parameter	Type	Optional	Description
RedemptionId	String	No	Id of Prize to redeem as returned in the GetConfiguration method
ExternalId	String	Yes	Id of tag already saved against contact record in EventsAir
QrCode	String	Yes	Value from scan of QRCode for Contact
Barcode	String	Yes	Value of scan of Barcode for Contact
InternalId	String	Yes	Guid for Contact from EventsAir
ContactIdentifier	Int	Yes	ID number as displayed on the Contact from EventsAir
LocationCode	String	Yes	Location Code of point where Prize is redeemed
SendPushNotification	Bool	Yes	If set to true will push a notification to the user in the EventsAir Attendee App to confirm a prize has been redeemed.

RedemptionId and at least one of the following optional parameters of ExternalId, QrCode, Barcode, InternalId, ContactIdentifier must be passed for the call to be valid.

Return:

Response object.

Field	Type	Nullable	Description
Coins	Int	No	Number of Coins redeemed for Prize or needed if Insufficient Coins error returned, or 0 if redemption was not successful for another reason.
CoinsBalance	Int	No	Current Balance of Coins (after Prize is redeemed if prize was able to be redeemed) if call is successful or Insufficient Coins error is returned.
ErrorCode	String	No	Error Code if not able to process the points successfully but the call is valid. The text for the error is retuned in Error message. Codes returned are: 001 = Invalid Prize 002 = Not active at this time 003 = No longer available (max inventory reached) 004 = No longer available for this person (max inventory reached) 005 = Insufficient Coins Or if successful call an empty string is returned.
Success	Bool	No	Value for success of call, will return false is call is invalid or an error code is returned.
ContactName	String	Yes	Name of Contact from EventsAir when call is successful
ErrorMessage	String	Yes	Description of Error if call was not successful.

JSON data successful response example:

The following example shows response from a successful call.

{
    "Coins": 10,
    "CoinsBalance": 20,
    "ErrorCode": "",
    "Success": true,
    "ContactName": "Archie Barker",
    "ErrorMessage": null
}

JSON data unsuccessful response example:

The following example shows response from unsuccessful call.

{
    "Coins": 0,
    "CoinsBalance": 0,
    "ErrorCode": "004",
    "Success": false,
    "ContactName": "Archie Barker",
    "ErrorMessage": "No longer available for this person (max inventory reached)"
}

Was this article helpful?

EventStream Game API (Version 2.0)

METHOD

GetConfiguration

Prizes:

Goals:

JSON data example:

METHOD

UpdateExternalId

Form Data Parameters

Return:

JSON data example:

METHOD

AddPoints

Form Data Parameters

Return:

JSON data successful response example:

JSON data unsuccessful response example:

METHOD

AddPointsBatch

PointsBatch:

JSON data example:

Return:

JSON data successful response example:

METHOD

CheckCoins

Form Data Parameters

Return:

JSON data response example:

METHOD

RedeemCoins

Form Data Parameters

Return:

JSON data successful response example:

JSON data unsuccessful response example:

Related Articles