Event

In this Article:

View in Postman collection

GET /apiv2/event/

Get a list of events

Parameter Required Description
apiKey YES The apiKey provided by ECAL and is found in Publisher Admin Portal
apiSign YES MD5 string of all parameters signed by the SECRET
showDraft NO Set this parameter to show draft calendars
tz NO The name of the timezone to convert the events date to. Check valid timezones here
calendarIds NO List of calendar ids comma separated to filter the events
page NO The page number of the event list
limit NO Defaults to 100 and Maximum 100. Work in conjunction with page to create pagination
type NO Type of events to fetch. For e.g. fixture or private. By default, all events are fetched
startDate NO Set this parameter to limit the results shown. Lower limit for the start date of the event (inclusive). For e.g. 2022-10-10
endDate NO Set this parameter to limit the results shown. Upper limit for the start date of the event (inclusive). For e.g. 2022-11-11
showPastEvents NO By defualt, past events are not shown. Use this parameter to show past events. Valid values: true or false

GET /apiv2/event/{id}

Get a single event and its full details. If id is not set, the request will be recognized as GET /apiv2/event/

Parameter Required Description
apiKey YES The apiKey provided by ECAL and is found in Publisher Admin Portal
apiSign YES MD5 string of all parameters signed by the SECRET
tz NO The name of the timezone to convert the events date to. Check valid timezones here

POST /apiv2/event/

Creates a new event in a calendar.

Parameter Required Description
apiKey YES The apiKey provided by ECAL and is found in Publisher Admin Portal
apiSign YES MD5 string of all parameters signed by the SECRET

Parameters

The event data must be posted as a RAW JSON string.

The list below shows the fields available:

Field Type Required Description
name string YES The name of the event
location string YES string
startDate date YES The start date of the event. Must be in YYYY-MM-DD format
startTime time CONDITIONAL The start time of the event. Must be in HH:MM 24hr format. Required unless ‘allDay’ field is set to ‘yes’.
endDate date YES The end date of the event. Must be in YYYY-MM-DD format
endTime time CONDITIONAL The end time of the event. Must be in HH:MM 24hr format. Required unless ‘allDay’ field is set to ‘yes’.
allDay string NO Set it to ‘yes’ if the event runs all day
timezone string/enum NO The timezone of the event. Defaults to the publisher timezone. Check valid timezones here.
alert string/enum NO The initial reminder alert for the event before its due. The valid values are
alert2 string/enum NO The secondary reminder alert for the event before its due. The valid values are
details string NO Description / comments about the event
objective* string NO Provides ECAL context to personalise event reminder times and content.
It can be one of the following:
● payment_reminder
● payment_success
● ticket_sale
● merchandise_sale
● tune_in
smartAlert* bit NO Set it to 1 if you want ECAL to apply User provided preference for reminder times when available. Else, ECAL will apply ML based techniques to determine the optimal time to remind. Works in conjunction with objective parameter.
smartDetails* bit NO Set it to 1 if you want ECAL to apply ML determined reminder content for reminder. Works in conjunction with objective parameter.

* These features are currently in preview and need to be specifically activated for an account. Contact support@ecal.com to request access.

It’s highly recommended that you use quicklinks and social fields for any external links in your events so they can be shortened, tracked and reported in dashboard.

Field Type Required Description
calendarId string YES The id of the calendar the event belongs to
quickLink[n][name] string NO The name of the quicklink where n constitute the number of facts starting from 1 and a maximum of 6
quickLink[n][url] string NO The url of the quicklink where n constitute the number of facts starting from 1 and a maximum of 6
social array NO The social links to your organisation. Valid keys for the array are
  • facebook
  • twitter
  • instagram
  • google
  • ipad
  • iphone
  • android
  • podcast
  • blog
  • foursquare
  • youtube
  • tikTok
  • snapchat
  • twitch
  • discord
  • linktree
reference string YES Unique reference of the event, provided by you
draft bit NO Set this to 0 to push the event live. Defaults to 1
sponsored_message string NO This field can be used to add event specific sponsor message, or text adverts
referenceType string NO Assigning the same reference type string to a set of events, allows you to bulk update the content of that set of events using that reference type string - using PUT apiv2/events/{referenceType}

Example POST Event Data

Request
{
    "name"       : "Test Fixture Event",
    "reference"  : "TFE01",
    "location"   : "ECAL HQ 4 Bank Place Melbourne",
    "calendarId" : "5215bef8b499921657000000",
    "startDate"   : "2013-08-29",
    "startTime"  : "18:00",
    "endDate"     : "2013-08-30",
    "endTime"    : "19:00",
    "timezone"   : "Australia/Melbourne",
    "alert"      : "15M",
    "details"    : "This is a test fixture event",
    "social"     : {
         "facebook" : "https://www.facebook.com/ECALworld/",
         "twitter"  : "https://twitter.com/ECALworld"
    },
    "quickLink[1][name]" : "ECAL",
    "quickLink[1][url]"  : "https://ecal.com/",
    "quickLink[2][name]" : "ECAL About",
    "quickLink[2][url]"  : "https://ecal.com/about-us/",
    "draft"              : 0
}
Response
{
   "status":"200",
   "statusLong":"OK",
   "eventId":"521d865ab49992f33f000001"
}

PUT /apiv2/event/{id}

Updates event based on id or reference

Parameter Required Description
apiKey YES The apiKey provided by ECAL and is found in Publisher Admin Portal
apiSign YES MD5 string of all parameters signed by the SECRET

Request Data

The event data must be posted as a RAW JSON string. Refer to POST /apiv2/event for field reference.

Example Request
{
    "name"       : "Test Fixture Event - CONFIRMED",
    "startDate"  : "2013-08-29",
    "startTime"  : "18:30",
    "endDate"    : "2013-08-30",
    "endTime"    : "19:30",
    "alert"      : "5M"
}
Response
{
    "status":"200",
    "statusLong":"OK",
    "eventId":"521d865ab49992f33f000001"
}

PUT /apiv2/events/{referenceType}

Updates event based on reference type

Parameter Required Description
apiKey YES The apiKey provided by ECAL and is found in Publisher Admin Portal
apiSign YES MD5 string of all parameters signed by the SECRET

Parameters

The event data must be posted as a RAW JSON string.

The list below shows the fields available:

Field Type Required Description
referenceType string NO Assigning the same reference type string to a set of events, allows you to bulk update the content of that set of events using that reference type string - using PUT apiv2/events/{referenceType}
social array NO The social links to your organisation. Valid keys for the array are
  • facebook
  • twitter
  • instagram
  • google
  • ipad
  • iphone
  • android
  • podcast
  • blog
  • foursquare
  • youtube
  • tikTok
  • snapchat
  • twitch
  • discord
  • linktree
sponsored_message string NO This field can be used to add event specific sponsor message, or text adverts
details string NO Description / comments about the event
objective string NO Provides ECAL context to personalise event reminder times and content.
It can be one of the following:
● payment_reminder
● payment_success
● ticket_sale
● merchandise_sale
● tune_in
smartAlert bit NO Set it to 1 if you want ECAL to apply User provided preference for reminder times when available. Else, ECAL will apply ML based techniques to determine the optimal time to remind. Works in conjunction with objective parameter.
smartDetails bit NO Set it to 1 if you want ECAL to apply ML determined reminder content for reminder. Works in conjunction with objective parameter.
Example Request
{
    "alert": "15M",
    "alert2": "-",
    "details": "This is a test event",
    "social": {
        "facebook": "https://www.facebook.com/ECALworld/",
        "twitter": "https://twitter.com/ECALworld",
        "google": "",
        "linkedin": "",
        "podcast": "",
        "blog": "",
        "foursquare": "",
        "youtube": "",
        "instagram": "",
        "flickr": "",
        "iphone": "",
        "ipad": "",
        "android": "",
        "blackberry": "",
        "vimeo": "",
        "tikTok": "",
        "snapchat": "",
        "twitch": "",
        "discord": "",
        "linktree": ""
    },
    "sponsored_message": "",
    "referenceType": ""
}
Response
{
    "affected_rows":2,
    "status":"200",
    "statusLong":"OK"
}

DELETE /apiv2/event/{id}

Delete a single event and event_history details based on id or reference.

Parameter Required Description
apiKey YES The apiKey provided by ECAL and is found in Publisher Admin Portal
apiSign YES MD5 string of all parameters signed by the SECRET
Response
{
  "status": 200,
  "statusLong": "OK"
}