Versions Compared

Old Version 52

changes.mady.by.user Kyle Simmons

Saved on

compared with

New Version Current

changes.mady.by.user Kyle Simmons

Saved on

Key

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

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

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:

Table of Contents
maxLevel2

Webserver Requirements

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: 


Appointment Object Relational Structure 

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:

Appointment JSON Object
Anchor
Appointment-JSON-Object
Appointment-JSON-Object
Code Block
languagexml
	{
		"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

Reason Object 
Anchor
reason-object
reason-object

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"
    }


Client Object 
Anchor
client-object
client-object

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
    }

Staff Object 
Anchor
staff-object
staff-object

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
    }

Location Object 
Anchor
location-object
location-object

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" : ""
    }

Custom Fields Object 
Anchor
custom-fields
custom-fields

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%"
      },