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 requested
  • postalCode - Customer postal code
  • startDateTime - Start getting availability at this date/time
  • endDateTime - Stop getting availability at this date/time
  • timezone - 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
}