Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


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:

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

Requirements:

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

In this guide, we'll cover:




Webserver Requirements
Anchor
#webserver
#webserver

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

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
languagexml
titleAppointment JSON Object
linenumberstrue
	{
		"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%"
      	}
    	],
	}


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 NameTypeDescription
requiredbooleanSignifies if the field is required when booking an appointment
serviceIdsinteger arrayIdentifies which services this field is attached to
userDefinedFieldbooleanSignifies if the field is user-generated or TimeTap system field
dataTypestringSignifies the type of field, ex. "TXT" = text field
activebooleanSignifies if the field is active
codestringSignifies if the field is user-generated or TimeTap system field
visibleOnSchedulerbooleanSignifies if the field is visible on the client-facing scheduler
validationRegexstringSignifies a regular expression used to validate the field's value
sortOrderintegerSignifies the field's display order in relation to other fields
businessIdintegerThe account business id
hintstringThe "field hint" value
filterByServicebooleanFilters custom field by service
createdUserstringThe username of the user that created the field
labelTagstringA special tag used to identify the field
modifiedDateintegerThe last date the field was modified
tagNamestringA special tag used to identify the field
modifiedUserstringThe username of the user who last modified the field
labelstring

The field's label

createdDateintegerThe date on which the field was created
valuestringThe field's value, entered by the user or user's client when booking an appointment
extendedValuestringThe field's value, entered by the user or user's client when booking an appointment
fieldValuesstringValues for LIST-type custom fields
visiblebooleanSignifies if the field is visible on the client scheduler
modestringSignifies if the field belongs to client record or appointment record. Ex, "CLIENT", "APPT"
valueTagstringA 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%"
      },

Return To Top