Book an appointment

Use Case Description

To book an appointment the API client need to perform multiple interactions with the API. These interactions are depicted in the diagram below.

In short, the following actions need to be performed to make a booking:

Retrieve the list of available services/service groups and branches (locations) related
Get time slots for the service selected and branch-specified
Reserve a time slot
Confirm a booking

Note! If the service combinations feature was turned on in System Settings and service combinations were configured the stack of separate API calls should be used /external/v1/serviceCombination/

Please refer to detailed guides to get more info about how to interact with new endpoints:

Book an appointment with multiple services

Reschedule appointment with multiple services

The following endpoints are not changed and can be used for both appointment types:

Cancel an appointment

Update customer details on Appointment

For a full reference please go to API Reference.

API endpoints

Services

Allows to receive the list of active services and their characteristics.

The endpoint can be used when the “service combinations“ feature is turned on. However, to get the information about the service combinations its recommended to use a separate endpoint which is GET /external/v1/serviceCombination/branch . See Book an appointment with multiple services for more details.

Attributes

Name	Type	Required	Description
Accept-Language	string	yes	Requested language for service names. The system will support languages depending on Tenant Localization settings (possible values are: en_US, en_UK, fr_FR, nl_NL, de_DE, it_IT, ES_es )
X-TENANT-ID	string	yes	The tenant id to use for this operation. The tenant id must be the same as an existing system Id.

Listing

GET /services will return the list of active services.

Response

[
  {
    "branch": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "address": {
        "streetName": "string",
        "zipCode": "string",
        "city": "string",
        "country": "string"
      },
      "location": {
        "longitude": 180,
        "latitude": 180
      }
    },
    "service": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "config": {
        "maxNumberOfReservations": 0,
        "onlineBookable": false
      }
    },
    "resourceSelection": {
      "required": true,
      "availableResources": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "string"
        }
      ]
    },
    "informationQuestions": [
      {
        "required": true,
        "questionText": "string",
        "clarificationText": "string"
      }
    ],
    "screeningQuestions": [
      {
        "yesRequiredAnswer": true,
        "questionText": "string",
        "clarificationText": "string",
        "answerDeniedMessage": "string"
      }
    ]
  }
]

Please note,

"resourceSelection" will be returned in the response only if specific resources were configured for the service, and resource selection: true is checked. In case resource pools are virtual, and there are no particular resources configured - no data will be returned:

"resourceSelection": {
"required": false,
"availableResources": []

"onlineBookable" parameter will allow to define whether the service is enabled for bookings by end customers or not (and can be used only for internal bookings) according to configurations on general/branch level.

Service Groups

Allows returning the list of services organized in service groups (for instance, building permits and building consultation can be grouped in Building services). The endpoint is valid only in case if service groups are configured in Appointment Configurations.

The endpoint can be used when the “service combinations“ feature is turned on.

Attributes

Name	Type	Required	Description
Accept-Language	string	yes	Requested language for service names. The system will support languages depending on Tenant Localization settings (possible values are: en_US, en_UK, fr_FR, nl_NL, de_DE, it_IT, ES_es )
X-TENANT-ID	string	yes	The tenant id to use for this operation. The tenant id must be the same as an existing system Id.

Listing

GET /services/groups

Response schema

{
  "services": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "index": 0
    }
  ],
  "serviceGroups": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "index": 0,
      "services": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "string",
          "index": 0
        }
      ]
    }
  ]
}

Branches

Allows to retrieve the list of branches (locations) that are associated with the specific service

Note, the endpoint can be used when the “service combinations“ feature is turned on.

Attributes

Name	Type	Required	Description
service ID	string (GUID)	yes	The service id (GUID)
Accept-Language	string	yes	Requested language for service names, The system will support languages depending on Tenant Localization settings (possible values are: en_US, en_UK, fr_FR, nl_NL, de_DE, it_IT, ES_es )
X-TENANT-ID	string	yes	The tenant id to use for this operation. The tenant id must be the same as an existing systemId.

Listing

GET /services/serviceId

Response schema

[
  {
    "branch": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "address": {
        "streetName": "string",
        "zipCode": "string",
        "city": "string",
        "country": "string"
      },
      "location": {
        "longitude": 180,
        "latitude": 180
      }
    },
    "resourceSelection": {
      "required": true,
      "availableResources": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "string"
        }
      ]
    }
  }
]

Timeslots

It is a virtual representation of available times based on attributes from resources/resource pools and services as well as various settings. So if service is open from 8am to 4pm and it has a duration of 60 minutes, resources associated with the available slots will return an array of all time intervals (8am-9am, 9am-10am etc.). Slots are meant for listing available times on the booking page.

To get the list of timeslots for combined services its recommended to use the endpoint /external/v1/serviceCombination/branch/{serviceId}/timeslots where several selected services can be specified and the total number of reservations. See Book an appointment with multiple services for the details.

Attributes

Name	Type	Required	Description
service ID	string (GUID)	yes	The service id (GUID)
branch ID	string	yes	The branch Id for the service specified
requestedResourceId	string		Resource ID
numberOfReservations	integer	yes	equals to number of people, number of times to serve (depending on business context) 1 by default, but more than 1 can be processed
X-TENANT-ID	string	yes	The tenant id to use for this operation. The tenant id must be the same as an existing systemId.

Listing

GET /services/serviceId/timeslots

Response schema

{
  "serviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timeSlots": [
    {
      "startTime": "2022-03-03T09:00:00+01:00",
      "endTime": "2022-03-03T09:00:00+01:00"
    }
  ]
}

Create a new Reservation

Please follow the instructions specified in Book an appointment with multiple services for making an appointment with several services inside.

Allows to create and place a new reservation. Please note, a temporary reservation will be made by this request, and it should be confirmed via a separate API call. If the reservation is not confirmed the timeslot will become available in 15 minutes.

POST /reservations

{
  "serviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "requestedResource": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timeSlot": {
    "startTime": "2022-03-03T09:00:00+01:00",
    "endTime": "2022-03-03T09:00:00+01:00"
  },
  "numberOfReservations": 1
}

Attributes

Name	Type	Required	Description
service ID	string (guid)	yes	The service id (GUID)
branch ID	string	yes	The branch Id for the service specified
requestedResourceId	string		Resource ID
Timeslot: “StartTime“	date & timestamp	yes	start time for the timeslot to reserve
Timeslot: “EndTime“	date & timestamp	yes	end time for the timeslot to reserve
Notes	string	no	the notes added for the appointment details
Numberofreservations	integer	yes	number of reservations, 1 by default

Response schema

Code 201 - Reservation is created

{
  "appointmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "serviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "requestedResource": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timeSlot": {
    "startTime": "2022-03-03T09:00:00+01:00",
    "endTime": "2022-03-03T09:00:00+01:00"
  },
  "expiration": "2023-03-08T13:42:41.035Z",
  "numberOfReservations": 1,
  "reservationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Confirm a reservation

POST /reservations/reservationId

Allows to confirm a reservation and place a booking for the customer. The booking should be confirmed by sending customer details in the following format:

{
  "customerInfo": {
    "personalIdentifier": "5TH5MY86p0MlkVz9W4ce2QVQ",
    "firstName": "eDCw''CesDnCay'pg gs{aLgLiDIHpnDCp",
    "lastName": ".'wa}{awwybCg'.pitCynntrt{t'Dycp 'IIp sHneIiwClrrt",
    "phoneNumber": "+p+pp--}p }}t}{D{gptD-i{{ g{{ {{}gti} ",
    "email": "string",
    "dateOfBirth": "2000-01-01"
  },
  "informationQuestions": [
    {
      "question": "string",
      "answer": "string"
    }
  ]
}

Attributes

Name	Type	Required	Description
personalIdentifier	string (GUID)	yes	The external customer’s identifier. Must contain 10-48 char and must match `A-Za-z0-9`
firstName	string	yes	The customer’s first name
lastName	string	yes	The customer’s last name
phoneNumber	integer	no	The customer’s phone number
email	string	yes	The customer’s email
dateofBirth	string	yes/no (depends on configs)	The customer’s date of birth
informationQuestions	string	yes/no (depends on configs)	The customer’s answers on informational questions

Response schema

Code 201 -Appointment confirmed

{
  "appointmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timeSlot": {
    "startTime": "2022-03-03T09:00:00+01:00",
    "endTime": "2022-03-03T09:00:00+01:00"
  },
  "customer": {
    "firstName": "rsecgyD'DpbIbswCcwc{-.{CnLca- siiebLrarl",
    "lastName": ".wLDaD}}cDr}L'ceri ntyg-DHlgLsir-Dsws  .s",
    "phoneNumber": "tp{ttitpD{ii-t{ +ii-p+Dtgpg}-it}-g{-+i +",
    "email": "string",
    "dateOfBirth": "2000-01-01"
  },
  "service": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "config": {
      "maxNumberOfReservations": 0
    }
  },
  "branch": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "address": {
      "streetName": "string",
      "zipCode": "string",
      "city": "string",
      "country": "string"
    },
    "location": {
      "longitude": 180,
      "latitude": 180
    }
  },
  "numberOfReservations": 0,
  "supportNotes": "string"
}