Private Events

In this Article:

Private Events are Events that only appear in the individual Subscriber’s calendar. If a single Event is to be shared with many Subscribers, use Publisher Admin Portal or ECAL’s Event API to publish them.

Pre-requisites

A subscriber’s ecalId is required to retrieve Private Events. To ensure you have captured this:

  1. Configure the ECAL Widget for Private Schedules
  2. Configure Webhook to recieve User’s ecalId
  3. Authenticate with ECAL API

Retrieving Private Events

An individual Subscriber’s Events can be retrieved by performing a HTTP GET /event request, providing the Subscriber’s ecalId as a parameter.

By default, the /Event endpoint returns all Events that a Subscriber has subscribed to within your ECAL, both Public & Private. To retrieve a Subscriber’s Private Events only, you must also specify the type=private. This will return one or more Event Objects as described in the /Event endpoint documentation.

Example Request

GET /apiv2/event?ecal_id=5924fd21608e3beb118b4567&type=private

Example Response

 [
     {
         "eventId"    : "521d865ab43952f33f000001",
         "type"       : "private",
         "name"       : "Your payment is due tomorrow!",
         "location"   : "ACME Corp Payment Reminders",
         "startDate"  : "2018-01-22",
         "startTime"  : "09:00",
         "endDate"    : "2018-01-22",
         "endTime"    : "09:00",
         "allDay"     : "no",
         "timezone"   : "Australia/Melbourne",
         "alert"      : "15M",
         "details"    : "Payment for Invoice #(45009) from ACME Corp is due tomorrow. Avoid late fees and interest by paying the full amount of $350.98 on time. You can pay now via the link below.",
         "quickLink[1][name]" : "Pay Now",
         "quickLink[1][url]"  : "https://payments.acme.com",
         "quickLink[2][name]" : "Contact us",
         "quickLink[2][url]"  : "http://www.acme.com/contact",
         "social"     : {
             "facebook" : "http://www.facebook.com/ACMECorp",
             "twitter"  : "@ACME"
         },
         "reference"  : "ACME_INV_45009_Payment-Due-tomorrow",
         "draft"      : 0,
         "sponsored_message" : ""
     },
     {
         "type"       : "private",
         "name"       : "Your payment is due!",
         "location"   : "ACME Corp Payment Reminders",
         "startDate"  : "2018-01-23",
         "startTime"  : "09:00",
         "endDate"    : "2018-01-23",
         "endTime"    : "09:00",
         "allDay"     : "no",
         "timezone"   : "Australia/Melbourne",
         "alert"      : "15M",
         "alert2"     : "1D",
         "details"    : "Payment for Invoice #(45009) from ACME Corp is due. Avoid late fees and interest by paying the full amount of $350.98 on time. You can pay now via the link below.",
         "quickLink[1][name]" : "Pay Now",
         "quickLink[1][url]"  : "https://payments.acme.com",
         "quickLink[2][name]" : "Contact us",
         "quickLink[2][url]"  : "http://www.acme.com/contact",
         "social"     : {
             "facebook" : "http://www.facebook.com/ACMECorp",
             "twitter"  : "@ACME"
         },
         "reference"  : "ACME_INV_45009_Payment-Due",
         "draft"      : 0,
         "sponsored_message" : ""
     }
 ]

Adding Private Event

Similarly, to add a new Private Event to a Subscriber’s calendar, by simply making HTTP POST /event request, providing the Subscriber’s ecalId as a parameter.

When you POST to the /Event endpoint with a Subscriber’s ecalId, setting the type value in your JSON payload as private.

Make sure to include draft: 0 in the payload of your event to ensure your event is Live and synced to the user’s calendar. If no draft parameter is provided, our API will assume this event is not ready to sync to a user’s calendar and will default to draft:1.

Example Request

POST /apiv2/event?ecal_id=5924fd21608e3beb118b4567

{
    "type"       : "private",
    "name"       : "Your Payment is now overdue!",
    "location"   : "ACME Corp Payment Reminders",
    "startDate"  : "2018-01-22",
    "startTime"  : "09:00",
    "endDate"    : "2018-01-22",
    "endTime"    : "09:00",
    "allDay"     : "no",
    "timezone"   : "Australia/Melbourne",
    "alert"      : "15M",
    "details"    : "We haven't received payment for Invoice #(45009) from ACME Corp. If you have paid in the last 24hrs, thankyou and please ignore this message. You can pay now via the link below.",
    "quickLink[1][name]" : "Pay Now",
    "quickLink[1][url]"  : "https://payments.acme.com",
    "quickLink[2][name]" : "Contact us",
    "quickLink[2][url]"  : "http://www.acme.com/contact",
    "social"     : {
         "facebook" : "http://www.facebook.com/ACMECorp",
         "twitter"  : "@ACME"
    },
    "reference"  : "ACME_INV_45009_Payment-Overdue",
    "draft"      : 0,
    "sponsored_message" : ""
}

When your request has been successful, you will receive a response including the eventID of the Event you have just created. This can be stored and used to retrieve/update/delete this Event in the future.

Example Response

{
    "status":"200",
    "statusLong":"OK",
    "eventId":"521d865ab49992f33f000001"
}

Updating a Private Event

To update a Private Event in a Subscriber’s calendar, simply make a HTTP PUT /event request, providing the EventID or Event Reference.

The Event type cannot be updated via the API. When updating an Event you only need to include the Event properties that you would like to change.

Example Request

PUT (Event ID) /apiv2/event/521d865ab49992f33f000001 or
PUT (Event Reference) /apiv2/event/ACME_INV_45009_Payment-Overdue

{
    "name"       : "✅ Your Payment has been received.",
    "location"   : "ACME Corp Payment Reminders",
    "startDate"  : "2018-01-23",
    "startTime"  : "09:00",
    "details"    : "Thanks for you payment of Invoice #(45009) from ACME Corp.",
    "quickLink[1][name]" : "",
    "quickLink[1][url]"  : ""
}

Example Response

{
    "status": "200",
    "statusLong": "OK",
    "eventId": "521d865ab49992f33f000001"
}

Deleting a Private Event

To delete a Private Event in a Subscriber’s calendar, simply make a HTTP DELETE /event request, providing the EventID or Event Reference.

Example Request

DELETE (Event ID) /apiv2/event/521d865ab49992f33f000001 or
DELETE (Event Reference) /apiv2/event/ACME_INV_45009_Payment-Overdue

Example Response

{
  "status": 200,
  "statusLong": "OK"
}