This is the process for creating a custom integration between Schedule Engine products and the FSM of your choice. We recommend you source a software engineer and use the instructions below to build out your own custom integration.
Instructions
When the Custom Integration mode is enabled within Schedule Engine there are 3 REST endpoints that will be called as appointments are being scheduled and created:
- Customer Lookup
- Availability Lookup
- New Appointment
Below are the technical requirements for these endpoints.
Auth
When the Schedule Engine system calls a REST endpoint it will always add a request header called X-SE-Signature
. In order to ensure that your endpoint is being called by Schedule Engine and not someone else, you MUST verify that the value of the X-SE-Signature
header matches the value present in your Schedule Engine Dashboard.
If the X-SE-Signature
header value does not match we recommend returning a HTTP 403. If the value does match, please process the request as documented below.
Errors and Retries
Schedule Engine expects HTTP 200 responses from your endpoints. When a non-200 is received, Schedule Engine will retry the request a few times before giving up and logging an error. Both errors and success logs can be viewed in your Schedule Engine Dashboard.
Endpoints
Customer Lookup Endpoint
Example Request
GET https://api.your-site.com/customer-lookup?phoneNumber=XX
Request Query Parameters
phoneNumber
- Customer phone number in international format (ex. +12223334444)
Example Response Body
{
customer: { // Can also be null if no customer found
id, // Customer ID from your system
firstName,
lastName,
locations: [
{
id, // Location ID from your system
line1,
line2, // Optional
locality, // ex. Miami
region, // ex. FL
postalCode,
countryCode, // ex. US
isBookingAllowed, // true/false
},
// ...
],
},
}
Availability Lookup Endpoint
Example Request
GET https://api.your-site.com/availability-lookup?serviceCodeKey=XX&postalCode=XX&startDateTime=XX&endDateTime=XX&timezone=XX&isEmergency=XX
Request Query Parameters
serviceCodeKey
- ID from your system identifying the type of work requestedpostalCode
- Customer postal codestartDateTime
- Start getting availability at this date/timeendDateTime
- Stop getting availability at this date/timetimezone
- Timezone of start/end date times (ex. America/New_York)isEmergency
- Customer classified this as an emergency (true/false)
Example Response Body
{
timeslots: [
{
label,
hasAvailability, // true/false
startDateTime, // ex. 2022-02-07T17:00:00.000Z
endDateTime,
},
],
}
New Appointment Endpoint
Example Request
POST https://api.your-site.com/new-appointment
{
customerId, // Customer ID from your system
locationId, // Location ID from your system
serviceCodeKey, // ID from your system identifying the type of work requested
startDateTime, // Appointment date/time (ex. 2022-02-07T17:00:00.000Z)
isEmergency,
notes,
}
Example Response Body
{
id, // Appointment or job ID from your system
}