Anchor

	top
	top

By setting up a web hook, TimeTap can send you notifications anytime your clients or staff members book an appointment for your business.

Our Notification service consists of a 3-step process:

A client or staff member books an appointment
TimeTap posts the notification with the appointment information as a JSON object to your webserver endpoint
Your webserver application processes the JSON object

Requirements:

A webserver running an endpoint application capable of receiving a POST request

Notes:

Any update made to an appointment will cause a webhook to get fired - not just appointment booking but also appointment editing and appointment deletion
Webhooks are specific to appointments. Any changes made to staff or client objects not involved with an appointment will not generate a webhook.

In this guide, we'll cover:

To receive a notification from TimeTap, you'll need to set up an endpoint to handle a POST request from our system. The post request will contain a JSON object (example shown below) with appointment data.

Once your endpoint is setup, provide the URL by going to Settings → Integrations in the backoffice, then scroll down to the Other Integrations section and click on the Webhook icon to expand:

With the Webhook area expanded, click the Activate Webhook button:

Enter the endpoint URL and click the "Update Webhook URL" button:

Anchor

	connect
	connect

Appointment Object Relational Structure
Anchor
relationalDrawing
relationalDrawing

Return To Top

Appointment JSON Object Structure and Example

Appointment objects have several top-level properties, whose types can be viewed here: Appointment Object Values

In addition, appointment objects also have child objects for Reasons (Service or Class), Client, Staff, Location, and an Array of Custom Fields.

Here's the basic structure of an Appointment object:

Code Block
{ "top-level properties" : "...", "reason" { Object }, "client" { Object }, "staff" { Object }, "location" { Object }, "fields" { Array } }

Here's an abbreviated example of what the Appointment JSON object looks like:

Code Block

language	xml
title	Appointment JSON Object
linenumbers	true

	{
		"calendarid":10390617,
		"businessId":20398,
		"startTime":800,
		"endTime":845,
		"clientStartTime":800,
		"clientEndTime":845,
		"reason":{
				"reasonId":96439,
				"businessId":20398,
				"visitMinutes":45,
				"reasonDesc":"Service3"
		},
		"client":{
				"clientId":2530974,
				"firstName":"Jon",
				"lastName":"Snow",
				"emailAddress":"jsnow@castleblack.mil",
				"city":"Victoria",
				"notes":"Jon would like a notification before his appointment.",
		},
		"staff":{
			"professionalId" : 42441,
			"businessId":20398,
			"userName":"DrJones2",
			"email": "djones2@marshallcollege.edu"
			"timeZoneCode":{
				"timeZoneId":78,
				"timeZoneCode":"America/New_York",
				"timeZoneDesc":"America/New_York",
		},
		"location":{
				"locationId":29945,
				"locationName":"MyOffice",
				"businessId":20398,
				"locationType":"Office"
		},
		"fields": [
      	{
        	"required" : false,
        	"serviceIds" : [
          		107292
        	],
        	"userDefinedField" : false,
        	"dataType" : "AREA",
        	"active" : true,
        	"code" : "UDF",
        	"visibleOnScheduler" : true,
        	"validationRegex" : null,
        	"sortOrder" : 21,
        	"businessId" : 23144,
        	"hint" : null,
        	"filterByService" : true,
        	"oldFieldIds" : null,
        	"createdUser" : "mpbtest138",
        	"labelTag" : "%CUSTOM_FIELD_107740_LABEL%",
        	"modifiedDate" : 1488575155000,
        	"tagName" : null,
        	"modifiedUser" : "MPBTEST138",
        	"label" : "Comments",
        	"createdDate" : 1488394066000,
        	"value" : "These are comments ",
        	"extendedValue" : "These are comments ",
        	"validationError" : null,
        	"fieldValues" : null,
        	"visible" : true,
        	"schedulerPreferenceFieldDefnId" : 107740,
        	"mode" : "APPT",
        	"valueTag" : "%CUSTOM_FIELD_107740%"
      	},
      	{
        	"required" : null,
        	"serviceIds" : null,
        	"userDefinedField" : true,
        	"dataType" : "TXT",
        	"active" : true,
        	"code" : "UDF",
        	"visibleOnScheduler" : true,
        	"validationRegex" : null,
        	"sortOrder" : 22,
        	"businessId" : 23144,
        	"hint" : null,
        	"filterByService" : false,
        	"oldFieldIds" : null,
        	"createdUser" : "MPBTEST138",
        	"labelTag" : "%CUSTOM_FIELD_108594_LABEL%",
        	"modifiedDate" : 1488575322000,
        	"tagName" : null,
        	"modifiedUser" : "MPBTEST138",
        	"label" : "My Custom Field",
        	"createdDate" : 1488575322000,
        	"value" : "Custom field value",
        	"extendedValue" : "Custom field value",
        	"validationError" : null,
        	"fieldValues" : null,
        	"visible" : true,
        	"schedulerPreferenceFieldDefnId" : 108594,
        	"mode" : "APPT",
        	"valueTag" : "%CUSTOM_FIELD_108594%"
      	}
    	],
	}

Return To Top

Object Values
Anchor
objectValues
objectValues

Reason Object
Anchor
reasonObject
reasonObject

Reason object value types can be found here: Reason Object Value Types

Code Block

"reason" : {
      "modifiedUser" : "MPBTEST138",
      "internalDisplayName" : "Service 1",
      "serviceLocations" : null,
      "reasonId" : 107292,
      "apptHrMin" : null,
      "emailInstructions2" : null,
      "taxable" : false,
      "professionalServiceList" : null,
      "businessId" : 23144,
      "rescheduleType" : null,
      "maxWaitListPerClass" : null,
      "visitMinutes" : 60,
      "customWorkSchedule" : 0,
      "reasonType" : "SERVICE",
      "numberSessions" : null,
      "bufferBefore" : null,
      "personal" : false,
      "privateUrl" : null,
      "embedCode" : null,
      "screeningQuestion" : null,
      "emailInstructions" : null,
      "currencySymbol" : null,
      "apptDayMax" : null,
      "professionalId" : null,
      "durationList" : null,
      "quotaType" : null,
      "allowOnline" : true,
      "allowWaitList" : false,
      "active" : true,
      "price" : null,
      "color" : null,
      "discountedPrice" : null,
      "sortWeight" : 0,
      "customFieldForm" : null,
      "bufferAfter" : null,
      "internalName" : null,
      "quotaFilled" : null,
      "depositAmount" : null,
      "allowPrePay" : false,
      "reasonDetail" : null,
      "quota" : null,
      "reasonDesc" : "Service 1"
    }

Return To Top

Client Object
Anchor
clientObject
clientObject

Client objects contain top-level properties, as well as a nested array of Custom Fields.

Client object value types can be found here: Client Object Value Types

Code Block

"client" : {
      "excludeEmailCategoryIdList" : null,
      "viewClientAccountIds" : null,
      "lastName" : "Smith",
      "clientAccountId" : null,
      "createdDate" : null,
      "country" : null,
      "modifiedUser" : "MPBTEST138",
      "state" : null,
      "locale" : null,
      "firstName" : "Josh ",
      "cellPhone" : "9802221111",
      "ssn" : null,
      "timeZone" : {
        "visible" : null,
        "timeZoneCode" : "America\/New_York",
        "timeZoneDesc" : "America\/New_York",
        "sortOrder" : 10,
        "timeZoneId" : 78
      },
      "allowWaitListText" : null,
      "salesforceContactId" : null,
      "createdUser" : "MPBTEST138",
      "sex" : null,
      "modifiedDate" : 1488575701889,
      "address2" : null,
      "fullName" : "Josh  Smith",
      "status" : "Active",
      "city" : null,
      "zip" : null,
      "fields" : [
        {
          "required" : true,
          "serviceIds" : null,
          "userDefinedField" : false,
          "dataType" : "TXT",
          "active" : true,
          "code" : "firstName",
          "visibleOnScheduler" : true,
          "validationRegex" : null,
          "sortOrder" : 0,
          "businessId" : 23144,
          "hint" : null,
          "filterByService" : false,
          "oldFieldIds" : null,
          "createdUser" : "mpbtest138",
          "labelTag" : "%CLIENT_FIRSTNAME_LABEL%",
          "modifiedDate" : 1488394066000,
          "tagName" : "CLIENT_FIRSTNAME",
          "modifiedUser" : "mpbtest138",
          "label" : "First Name",
          "createdDate" : 1488394066000,
          "value" : "Josh ",
          "extendedValue" : "Josh ",
          "validationError" : null,
          "fieldValues" : null,
          "visible" : true,
          "schedulerPreferenceFieldDefnId" : 107719,
          "mode" : "CLIENT",
          "valueTag" : "%CLIENT_FIRSTNAME%"
        },
        {
          "required" : true,
          "serviceIds" : null,
          "userDefinedField" : false,
          "dataType" : "TXT",
          "active" : true,
          "code" : "lastName",
          "visibleOnScheduler" : true,
          "validationRegex" : null,
          "sortOrder" : 1,
          "businessId" : 23144,
          "hint" : null,
          "filterByService" : false,
          "oldFieldIds" : null,
          "createdUser" : "mpbtest138",
          "labelTag" : "%CLIENT_LASTNAME_LABEL%",
          "modifiedDate" : 1488394066000,
          "tagName" : "CLIENT_LASTNAME",
          "modifiedUser" : "mpbtest138",
          "label" : "Last Name",
          "createdDate" : 1488394066000,
          "value" : "Smith",
          "extendedValue" : "Smith",
          "validationError" : null,
          "fieldValues" : null,
          "visible" : true,
          "schedulerPreferenceFieldDefnId" : 107720,
          "mode" : "CLIENT",
          "valueTag" : "%CLIENT_LASTNAME%"
        },
        {
          "required" : true,
          "serviceIds" : null,
          "userDefinedField" : false,
          "dataType" : "TXT",
          "active" : true,
          "code" : "fullName",
          "visibleOnScheduler" : false,
          "validationRegex" : null,
          "sortOrder" : 2,
          "businessId" : 23144,
          "hint" : null,
          "filterByService" : false,
          "oldFieldIds" : null,
          "createdUser" : "mpbtest138",
          "labelTag" : "%CLIENT_FULLNAME_LABEL%",
          "modifiedDate" : 1488394066000,
          "tagName" : "CLIENT_FULLNAME",
          "modifiedUser" : "mpbtest138",
          "label" : "Full Name",
          "createdDate" : 1488394066000,
          "value" : "Josh  Smith",
          "extendedValue" : "Josh  Smith",
          "validationError" : null,
          "fieldValues" : null,
          "visible" : false,
          "schedulerPreferenceFieldDefnId" : 107721,
          "mode" : "CLIENT",
          "valueTag" : "%CLIENT_FULLNAME%"
        },
      ],
      "homePhone" : "7048882233",
      "clientId" : 3042662,
      "stripeCustomerId" : null,
      "squareCustomerId" : null,
      "address1" : null,
      "notes" : null,
      "password" : null,
      "emailAddress" : "timetaptest@gmail.com",
      "language" : null,
      "companyName" : null,
      "county" : null,
      "dateOfBirth" : null
    }

Return To Top

Staff Object
Anchor
staffObject
staffObject

Staff object value types can be found here: Staff Object Value Types

Code Block

"staff" : {
      "emailInstructions" : null,
      "locationAccessList" : null,
      "active" : true,
      "embedCode" : null,
      "emailFooter" : "<strong>You can contact us at:<\/strong><br\/>%STAFF_FULLNAME%<br\/>%BUSINESS_NAME%<br\/>%STAFF_EMAIL%<br\/>%STAFF_MOBILE%",
      "acceptAppointments" : true,
      "internalName" : null,
      "professionalId" : 42441,
      "googleSyncPeriod" : "",
      "businessId" : 23144,
      "mobilePhone" : "",
      "locationsWithSchedule" : null,
      "locale" : "en-US",
      "sortWeight" : 0,
      "excludeEmailCategoryIdList" : null,
      "imageUrl" : null,
      "timeZone" : null,
      "privateUrl" : null,
      "email" : "timetaptest@gmail.com",
      "firstDayOfWeek" : 0,
      "phone" : null,
      "newApptSms" : false,
      "staffProfile" : null,
      "internalDisplayName" : "mpbtest138",
      "userName" : "MPBTEST138",
      "googleSyncActive" : false,
      "skypeId" : null,
      "changePasswordNextLogin" : false,
      "fullName" : "mpbtest138",
      "securityRoleId" : 1
    }

Return To Top

Location Object
Anchor
locationObject
locationObject

Location object value types can be found here: Location Object Value Types

Code Block

"location" : {
      "officePhone" : null,
      "zip" : null,
      "active" : true,
      "embedCode" : null,
      "country" : null,
      "internalName" : null,
      "businessId" : 23144,
      "address1" : null,
      "city" : null,
      "locationId" : 35186,
      "emailAddress" : null,
      "logoUrl" : null,
      "sortWeight" : null,
      "state" : null,
      "hasWorkScheduleOrClass" : null,
      "timeZone" : null,
      "privateUrl" : null,
      "address2" : null,
      "locationType" : "Office",
      "internalDisplayName" : "My Office",
      "directions" : null,
      "locationName" : "My Office",
      "description" : ""
    }

Return To Top

Custom Fields Object
Anchor
customFields
customFields

Custom Field Value Types:

Property Name	Type	Description
required	boolean	Signifies if the field is required when booking an appointment
serviceIds	integer array	Identifies which services this field is attached to
userDefinedField	boolean	Signifies if the field is user-generated or TimeTap system field
dataType	string	Signifies the type of field, ex. "TXT" = text field
active	boolean	Signifies if the field is active
code	string	Signifies if the field is user-generated or TimeTap system field
visibleOnScheduler	boolean	Signifies if the field is visible on the client-facing scheduler
validationRegex	string	Signifies a regular expression used to validate the field's value
sortOrder	integer	Signifies the field's display order in relation to other fields
businessId	integer	The account business id
hint	string	The "field hint" value
filterByService	boolean	Filters custom field by service
createdUser	string	The username of the user that created the field
labelTag	string	A special tag used to identify the field
modifiedDate	integer	The last date the field was modified
tagName	string	A special tag used to identify the field
modifiedUser	string	The username of the user who last modified the field
label	string	The field's label
createdDate	integer	The date on which the field was created
value	string	The field's value, entered by the user or user's client when booking an appointment
extendedValue	string	The field's value, entered by the user or user's client when booking an appointment
fieldValues	string	Values for LIST-type custom fields
visible	boolean	Signifies if the field is visible on the client scheduler
mode	string	Signifies if the field belongs to client record or appointment record. Ex, "CLIENT", "APPT"
valueTag	string	A special tag used to identify the field

Code Block

{
        "required" : false,
        "serviceIds" : [
          107292
        ],
        "userDefinedField" : false,
        "dataType" : "AREA",
        "active" : true,
        "code" : "UDF",
        "visibleOnScheduler" : true,
        "validationRegex" : null,
        "sortOrder" : 21,
        "businessId" : 23144,
        "hint" : null,
        "filterByService" : true,
        "oldFieldIds" : null,
        "createdUser" : "mpbtest138",
        "labelTag" : "%CUSTOM_FIELD_107740_LABEL%",
        "modifiedDate" : 1488575155000,
        "tagName" : null,
        "modifiedUser" : "MPBTEST138",
        "label" : "Comments",
        "createdDate" : 1488394066000,
        "value" : "These are comments ",
        "extendedValue" : "These are comments ",
        "validationError" : null,
        "fieldValues" : null,
        "visible" : true,
        "schedulerPreferenceFieldDefnId" : 107740,
        "mode" : "APPT",
        "valueTag" : "%CUSTOM_FIELD_107740%"
      },

Versions Compared

Old Version 3

New Version Current

Key

Webserver Requirements
Anchor
#webserver
#webserver

Return To Top

Appointment Object Relational Structure
Anchor
relationalDrawing
relationalDrawing

Return To Top

Appointment JSON Object Structure and Example

Return To Top

Object Values
Anchor
objectValues
objectValues

Reason Object
Anchor
reasonObject
reasonObject

Return To Top

Client Object
Anchor
clientObject
clientObject

Return To Top

Staff Object
Anchor
staffObject
staffObject

Return To Top

Location Object
Anchor
locationObject
locationObject

Return To Top

Custom Fields Object
Anchor
customFields
customFields

Custom Field Value Types:

Return To Top

Page Comparison

Versions Compared

Key

Webserver Requirements Anchor#webserver#webserver

Appointment Object Relational Structure AnchorrelationalDrawingrelationalDrawing

Appointment JSON Object Structure and Example

Object Values AnchorobjectValuesobjectValues

Reason Object AnchorreasonObjectreasonObject

Client Object AnchorclientObjectclientObject

Staff Object AnchorstaffObjectstaffObject

Location Object AnchorlocationObjectlocationObject

Custom Fields Object AnchorcustomFieldscustomFields

Custom Field Value Types:

Webserver Requirements
Anchor
#webserver
#webserver

Appointment Object Relational Structure
Anchor
relationalDrawing
relationalDrawing

Object Values
Anchor
objectValues
objectValues

Reason Object
Anchor
reasonObject
reasonObject

Client Object
Anchor
clientObject
clientObject

Staff Object
Anchor
staffObject
staffObject

Location Object
Anchor
locationObject
locationObject

Custom Fields Object
Anchor
customFields
customFields