Events

The Events API is comprised of Event Definition, Event Actions, and Event Triggers APIs. These APIs are used to access, create, and modify the eventDefinition, eventActions, and event Triggers objects on your business' account. Also covered on this page is a description of how the two APIs interact both with each other and with the event type table below to successfully create an event.

The event type table that follows acts as a key for the Event Definitions and Event Actions you create on your account. I will use the creation of an Automated Messaging Trigger that sends an email to a client to illustrate how the tables interact. You must first create an event definition that dictates which event action should be taken based on which event type from the table below takes place. Say you want to set up a trigger to send an email to staff automatically whenever an appointment that staff is connected to gets created. Looking at the event type table below, we see that "appointment created" is the first type listed. So the eventDefinition object that gets created has an eventType object with an eventTypeId of 1 on it. While creating the Event Definition you will also create an Event Action, which in this case would be the sending of the email.

Event type table

eventTypeId	eventType	objectType	eventCategory
1	APPT_CREATED	CALENDAR	EVENT
2	APPT_CHANGED	CALENDAR	EVENT
3	APPT_REMINDER	CALENDAR	REMINDER
4	CLASS_SCHEDULE_CREATED	CLASS_SCHEDULE	EVENT
5	CLASS_SCHEDULE_CHANGED	CLASS_SCHEDULE	EVENT
6	CLASS_SCHEDULE_REMINDER	CLASS_SCHEDULE	REMINDER
7	INVITE_CREATED	INVITATION	EVENT
8	INVITE_REMINDER	INVITATION	REMINDER
9	INVITE_COMPLETED	INVITATION	EVENT
10	RECALL	RECALL	REMINDER
11	INVITE_CHANGED	INVITATION	EVENT
12	DISCLAIMER_CREATED	DISCLAIMER	EVENT
13	DISCLAIMER_CHANGED	DISCLAIMER	EVENT

On this page

These are the endpoints that are available under the /eventDefinition, /eventTriggers, and /eventAction paths, which are all involved in setting up events. Please note that there is no DELETE call for eventAction objects, instead simply make a POST call to edit it and set the active property to false.

Endpoint	Description
GET /eventDefinition/eventType/{eventTypeId}	Returns all eventDefinition objects that are set to specified eventType in array format.
GET /eventAction/eventDefinition/{eventDefinitionId}	Returns all eventAction objects associated with specified eventDefinition in array format.
GET /eventDefinition/INVITATION_CAMPAIGN/{invitationCampaignId}	Returns all eventDefinition objects associated with specified invitationCampaign in array format.
GET /eventTriggers/invitation/{invitationUUID}	Returns all eventTrigger objects on specified invitation that have either already taken place-such as a status change-or eventTrigger objects that are scheduled to take place-like when you want to send out an automatic reminder.
GET /eventTriggers/CALENDAR/{calendarId}	Returns all eventTrigger objects on associated appointment that have either already taken place - such as a status change - or event trigger objects that are scheduled to take place - like when you want to send an automatic reminder.
GET /eventDefinition/{eventDefinitionId}	Returns a JSON object for specified event definition.
POST /eventDefinition	Creates a new eventDefinition object or updates an existing eventDefinition object. Request body: Must pass an eventDefinition object in request body/payload. For these calls, you need to pass an eventDefinition object with all required fields set in the body of the payload; make sure to include eventType object with eventType set to the proper event type from the table provided at the top of page. If you are updating an object, you must include the eventDefnId in the payload. We have an example of a eventDefinition object in the responses section below.
POST /eventAction	Creates a new eventAction object or updates an existing eventAction object. Request body: Must pass an eventAction object in request body/payload. For these calls, you need to pass an eventAction object with all required fields set in the body of the payload; make sure to fill the eventDefinitionId property with the ID of the event definition that the event action is tied to. If you are updating an object, you must include the eventActionId in the payload. We have an example of a eventAction object in the responses section below.
DELETE /eventDefinition/{eventDefinitionId}	Removes an eventDefinition object from view by setting its active property to false.

There are no parameters included with eventDefinition, eventAction, or eventTriggers calls.

The objects below represent the minimum viable objects to pass that are needed to create or update an eventDefinition or eventAction object. Check whether or not a property can be written to by looking at the Object Values table below to see if the property is writable.

POST /eventDefinition

{
    "active": true,
    "allOrNoneSelect": {
        "disclaimerForms": {
            "value": "all"
        },
        "locations": {
            "label": "All Locations"
        },
        "value": "all"
        },
        "reasons": {
            "label": "All Services & Classes",
            "value": "all"
        },
        "staff": {
            "label": "Select Tutors",
            "value": "select"
    }},
    "businessId": 43111,
    "description": "beebop",
    "disclaimerFormIdList": null,
    "eventType": {
        "eventTypeCode": "APPT",
        "eventTypeDesc": "Appointments",
        "eventTypeId": 3,
        "eventTypeIds": [
            "0": 1,
            "1": 2,
            "2": 3
        ],
    "groupIdList": null,
    "locationIdList": null,
    "newStatus": null,
    "newStatusObject": {
        "label": "Any Status",
        "value": "*"
    },
    "objectType": "CALENDAR",
    "oldStatus": null,
    "oldStatusObject": {
        "label": "Any Status",
        "value": "*"
    },
    "professionalIdList": [
        "0": 81651
    ],
    "reasonIdList": null,
    "templateActions": [{
        "0": {
            "actionType": "SEND_EMAIL",
            "active": true,
            "businessId": 43111,
            "categoryForLookup": 76,
            "emailTemplateId": 211640,
            "msgType": {
                "eventTypeCodes": [
                    "0": "APPT",
                    "1": "CLASS",
                    "2": "DISCLAIMER",
                    "3": "INVOICE"
                ],
                "label": "Email",
                "value": "email"
             },
            "noTemplatesInCategory": false,
            "recipient": {
                "label": "Student",
                "value": "client"
             },
             "template": {
                "active": true,
                "allowOnline": false,
                "attachFileLibraryUUids": [
                    "0": "839fc50deb3e4d4dac4d70c8853bff83"
                ],
                "bccAddress": null,
                "businessId": 43111,
                "ccAddress": null,
                "createdDate": 1671138400789,
                "createdUser": "JoeSchmo",
                "emailBecause": null,
                "emailBody": "(HTML text of email body)",
                "emailBodyText": null,
                "emailCategory": {Email categories object for email category of template - for more info, see Email Categories API page},
                "emailTemplateId": 211640,
                "externalName": null,
                "fromAddress": "noreply@timetap.com",
                "fromName": "%BUSINESS_NAME%",
                "language": null,
                "level": 1,
                "location": null,
                "modifiedDate": 1671138456462,
                "modifiedUser": "JoeSchmo",
                "noHeader": null,
                "reasonIdList": null,
                "reasonNameList": null,
                "replyToAddress": "%PROFESSIONAL_EMAIL%",
                "resellerId": 3,
                "s3FileName": "43111/templates/template-76-211640.html",
                "sortOrder": null,
                "subject": "Appointment Notification",
                "templateName": "Clone of Default Template",
                "toAddress": "%CLIENT_EMAILADDRESS%",
                "toName": "%CLIENT_FULLNAME%"
            },
            "templateOptions": [{
                "0": {
                    "active": true,
                    "allowOnline": false,
                    "attachFileLibraryUUids": [
                        "0": "839fc50deb3e4d4dac4d70c8853bff83"
                    ],
                    "bccAddress": null,
                    "businessId": 43111,
                    "ccAddress": null,
                    "createdDate": 1671138400789,
                    "createdUser": "JoeSchmo",
                    "emailBecause": null,
                    "emailBody": "(HTML text of email body)",
                    "emailBodyText": null,
                    "emailCategory": {Email categories object for email category of template - for more info, see Email Catgories API page},
                    "emailTemplateId": 211640,
                    "externalName": null,
                    "fromAddress": "noreply@timetap.com",
                    "fromName": "%BUSINESS_NAME%",
                    "language": null,
                    "level": 1,
                    "location": null,
                    "modifiedDate": 1671138456462,
                    "modifiedUser": "JoeSchmo",
                    "noHeader": null,
                    "reasonIdList": null,
                    "reasonNameList": null,
                    "replyToAddress": "%PROFESSIONAL_EMAIL%",
                    "resellerId": 3,
                    "s3FileName": "43111/templates/template-76-211640.html",
                    "sortOrder": null,
                    "subject": "Appointment Notification",
                    "templateName": "Clone of Default Template",
                    "toAddress": "%CLIENT_EMAILADDRESS%",
                    "toName": "%CLIENT_FULLNAME%",
    }}]}}],
    "triggerDays": null,
    "triggerHours": -24,
    "triggerHoursValue": 24,
    "triggerMinutes": null,
    "triggerMinutesValue": null,
    "triggerMonths": null,
    "triggerWeeks": null,
    "triggerWhen": {
        "label": "Before",
        "value": "before"
    },
    "triggeredBy": {
        "eventTypeCodes": [
            "0": "APPT",
            "1": "CLASS"
        ],
        "label": "Time",
        "value": "time"
}}

POST /eventAction

{
    "actionType": "SEND_EMAIL",
    "active": true,
    "businessId": 43111,
    "categoryForLookup": 76,
    "emailTemplateId": 211640,
    "eventDefnId": 203973,
    "msgType": {
        "eventTypeCodes": [
            "0": "APPT",
            "1": "CLASS",
            "2": "DISCLAIMER",
            "3": "INVOICE"
        ],
        "label": "Email",
        "value": "email"
    },
    "noTemplatesInCategory": false
    "recipient": {
        "label": "Student",
        "value": "client"
    },
    "template": {Template object for email template of event action - for more info, see Email Templates API page},
    "templateOptions": {Template object for email templates that appear as options here - for more info, see Email Templates API page}
}

GET /eventDefinition/eventType/{eventTypeId}

[{
    "active": true,
    "businessId": 43111,
    "createdDate": 1540497914072,
    "createdUser": "JoeSchmo",
    "description": "Trigger for appointment changing from Open to Completed",
    "disclaimerFormIdList": null,
    "eventActions": null,
    "eventDefnId": 77882,
    "eventType": {
        "eventCategory": "EVENT",
        "eventType": "APPT_CHANGED",
        "eventTypeId": 2,
        "objectType": "CALENDAR"
    },
    "groupIdList": null,
    "locationIdList": null,
    "modifiedDate": null,
    "modifiedUser": null,
    "newStatus": "COMPLETED",
    "objectId": null,
    "objectType": "CALENDAR",
    "objectUUId": null,
    "oldStatus": "OPEN",
    "professionalIdList": null,
    "reasonIdList": null,
    "triggerHours": -24,
    "triggerMinutes": 0
}]

GET /eventAction/eventDefinition/{eventDefinitionId}

[{
    "actionType": "SEND_EMAIL",
    "active": true,
    "businessId": 43111,
    "createdDate": 1540497762572,
    "createdUser": "JoeSchmo",
    "emailCategoryId": null,
    "emailTemplateId": 12685,
    "eventActionId": 77979,
    "eventDefnId": 40258,
    "modifiedDate": null,
    "modifiedUser": null
}]

GET /eventDefinition/INVITATION_CAMPAIGN/{invitationCampaignId}

[{
    "active": true,
    "businessId": 43111,
    "createdDate": 1540498382090,
    "createdUser": "JoeSchmo",
    "description": null,
    "disclaimerFormIdList": null,
    "eventActions": null,
    "eventDefnId": 77883,
    "eventType": {
        "eventCategory": "REMINDER",
        "eventType": "INVITE_REMINDER",
        "eventTypeId": 8,
        "objectType": "INVITATION",
    },
    "groupIdList": null,
    "locationIdList": null,
    "modifiedDate": null,
    "modifiedUser": null,
    "newStatus": null,
    "objectId": 126506,
    "objectType": "INVITATION_CAMPAIGN",
    "objectUUId": null,
    "oldStatus": null,
    "professionalIdList": null,
    "reasonIdList": null,
    "triggerHours": 24,
    "triggerMinutes": 0
}]

GET /eventTriggers/invitation/{invitationUUId}

[{
    "businessId": 43111,
    "completedTime": 1540588201725,
    "createdDate": 1540498382645,
    "createdUser": "JoeSchmo",
    "eventDefnId": 77883,
    "eventTriggerId": 230330,
    "modifiedDate": null,
    "modifiedUser": null,
    "objectId": null,
    "objectType": "INVITATION",
    "objectUUId": "ivt8de5eade77dd4c47b3c2322726848e88",
    "scheduledTime": 1540584782077,
    "status": "COMPLETED"
}]

GET /eventTriggers/CALENDAR/{calendarId}

[{
    "businessId": 43111,
    "completedTime": 1540825802267,
    "createdDate": 1540744427301,
    "createdUser": "event_trigger",
    "eventDefnId": 77911,
    "eventTriggerId": 235312,
    "modifiedDate": 1540744533717,
    "modifiedUser": "event_trigger",
    "objectId": 18445056,
    "objectType": "CALENDAR",
    "objectUUId": null,
    "scheduledTime": 1540024900000,
    "status": "COMPLETED"
}]

GET /eventDefinition/{eventDefinitionId}

[{
    "active": true,
    "businessId": 43111,
    "createdDate": 1540498382090,
    "createdUser": "JoeSchmo",
    "description": null,
    "disclaimerFormIdList": null,
    "eventActions": null,
    "eventDefnId": 77883,
    "eventType": {
        "eventCategory": "REMINDER",
        "eventType": "INVITE_REMINDER",
        "eventTypeId": 8,
        "objectType": "INVITATION",
    },
    "groupIdList": null,
    "locationIdList": null,
    "modifiedDate": null,
    "modifiedUser": null,
    "newStatus": null,
    "objectId": 126506,
    "objectType": "INVITATION_CAMPAIGN",
    "objectUUId": null,
    "oldStatus": null,
    "professionalIdList": null,
    "reasonIdList": null,
    "triggerHours": 24,
    "triggerMinutes": 0
}]

POST /eventDefinition

{
    "active": true,
    "businessId": 43111,
    "createdDate": 1540998926569,
    "createdUser": "JoeSchmo",
    "description": "Test Time trigger",
    "disclaimerFormIdList": null,
    "eventActions": null,
    "eventDefnId": 80551,
    "eventType": {
        "eventCategory": null,
        "eventType": null,
        "eventTypeId": 1,
        "objectType": null,
    },
    "filterTagMapJson": null,
    "groupIdList": null,
    "locationIdList": null,
    "modifiedDate": null,
    "modifiedUser": null,
    "newStatus": null,
    "objectId": null,
    "objectType": "CALENDAR",
    "objectUUId": null,
    "oldStatus": null,
    "professionalIdList": [
        "0": 80891,
        "1": 81651
    ],
    "reasonIdList": null,
    "triggerHours": 24,
    "triggerMinutes": 0
}

POST /eventAction

{
    "actionType": "SEND_EMAIL",
    "active": true,
    "businessId": 43111,
    "createdDate": 1540998926675,
    "createdUser": "JoeSchmo",
    "emailCategoryId": null,
    "emailTemplateId": 13789,
    "eventActionId": 80617,
    "eventDefnId": 80551,
    "modifiedDate": null,
    "modifiedUser": null
}

eventDefinition

Property name	Type	Required	Description
active	boolean	Yes	Indicates whether or not the specified event definition should return on GET calls.
businessId	integer	Yes	Provides unique numeric ID of the business to which the specified event definition belongs.
createdDate	integer		Displays as date the specified event definition was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
createdUser	string		Displays as username of the user who created the specified event definition.
description	string		Displays as the internal description set for the specified event definition.
disclaimerFormIdList	array		Displays as an array of disclaimerFormIds of disclaimer forms selected for the specified event definition.
eventActions	array	Yes	Displays as an array of eventActions objects for the event actions connected to the specified event definition.
eventDefnId	integer	Yes, for updates	Provides unique numeric ID for the specified event definition.
eventType	object		Displays as eventType object associated with the specified event definition.
filterTagMapJson	string		Displays as a JSON of all filter tags associated with the specified event definition.
groupIdList	array		This property is not being used by the back end database to route events at this time.
locationIdList	array		Displays as an array of locationIds of locations selected for the specified event definition.
modifiedDate	integer		Displays as date the specified event definition was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
modifiedUser	string		Displays as username of the user who last modified the specified event definition.
newStatus	string		Displays as what the status changes to if trigger is status change. * indicates that it could be any status, and any other statuses are the values that returned after GET /status calls.
objectId	integer		Provides unique numeric ID for the object connected to the specified event definition.
objectType	string	Yes	Displays as type of object connected to the specified event definition. Has available options "CALENDAR", "INVITATION_CAMPAIGN", "RECALL", and "CLASS_SCHEDULE".
objectUUId	string		Provides unique alphanumeric ID for the object connected to the specified event definition.
oldStatus	string		Displays as what the status changes from if trigger is status change. * indicates that it could be any status, and any other statuses are the values that returned after GET /status calls.
professionalIdList	array		Displays as an array of professionalIds of staff selected for the specified event definition.
reasonIdList	array		Displays as an array of reasonIds of services selected for the specified event definition.
triggerHours	integer	Yes	Provides the number of hours before or after an event that the event action will be triggered.
triggerMinutes	integer	Yes	Provides the number of hours before or after an event that the event action will be triggered.

eventAction

Property name	Type	Required	Description
actionType	string	Yes	Displays as the type of action to be taken when the event type is triggered. Has available options "SEND_EMAIL".
active	boolean	Yes	Indicates whether or not the specified event action should return on GET calls.
businessId	integer	Yes	Provides unique numeric ID of the business to which the specified event action belongs.
createdDate	integer		Displays as date specified event action was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
createdUser	string		Displays as username of the user who created the specified event action.
emailCategoryId	integer		Provides unique numeric ID for any email category connected to the specified event action.
emailTemplateId	integer	Yes	Provides unique numeric ID for email template connected to the specified event action.
eventActionId	integer	Yes, for updates	Provides unique numeric ID for the specified event action.
eventDefnId	integer	Yes	Provides unique numeric ID for the event definition connected to the specified event action.
modifiedDate	integer		Displays as date the specified event action was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
modifiedUser	string		Displays as username of the user who last modified the specified event action.

TimeTap API

Events

Event type table

Events API Endpoints

Events Parameters

Events API Request Body/Payloads

Events API Responses

Events Object Values

eventDefinition

eventAction