Get Appointment Slots

Syntax

URI

/services/data/vXX.X/scheduling/getAppointmentSlots

Available since release

45.0

Formats

JSON, XML

HTTP methods

POST

Authentication

Authorization: Bearer token

The Lightning Platform REST API supports OAuth 2.0 (an open protocol to allow secure API authorization). See Understanding Authentication for more details.

Note

Request body

Parameter	Required	Type	Description
startTime	No	String	The earliest time that a time slot can begin (inclusive). Defaults to the current time of the request, if empty.
endTime	No	String	The latest time that a time slot can end (inclusive).
workTypeGroupId	Yes	String	The ID of the work type group containing the work types that are being performed.
accountId	No	String	The ID of the associated account.
territoryIds	Yes	String[]	List of IDs of service territories, where the work that is being requested is performed.
requiredResourceIds	Yes	String[]	List of resource IDs that must be available during the time slot. At present, only one resource is allowed on this list.
schedulingPolicyId	No	String	The ID of the AppointmentSchedulingPolicy object. If no scheduling policy is passed in the request body, the default configurations are used. The only scheduling policy configuration that is used in determining time slots is the enforcement of account visiting hours.

Response Body

Execution of a successful request returns the response body containing a list of available time slots.

Parameter	Required	Type	Description
timeSlots	Yes	Time Slots[]	List of time slots included in each territory.

Examples

Request Body Example

1{
2    "startTime" : "2019-01-23T00:00:00.000Z",
3    "endTime" : "2019-02-30T00:00:00.000Z",
4    "workTypeGroupId" : "0VSB0000000KyjBOAS",
5    "accountId" : "001B000000qAUAWIA4",
6    "territoryIds" : ["0HhB0000000TO9WKAW"],
7    "requiredResourceIds" : ["0HnB0000000TO8gKAK"],
8    "schedulingPolicyId" : "0VrB0000000KudK"
9}

Response Body Example

1{
2"timeSlots" :
3[ 
4  {
5    "endTime" : "2019-01-21T19:15:00.000+0000",
6    "startTime" : "2019-01-21T16:15:00.000+0000",
7    "territoryId" : "0HhB0000000TO9WKAW"
8  }, {
9    "endTime" : "2019-01-21T19:30:00.000+0000",
10    "startTime" : "2019-01-21T16:30:00.000+0000",
11    "territoryId" : "0HhB0000000TO9WKAW"
12  }, {
13    "endTime" : "2019-01-21T19:45:00.000+0000",
14    "startTime" : "2019-01-21T16:45:00.000+0000",
15    "territoryId" : "0HhB0000000TO9WKAW"
16  }
17]
18}

Prerequisites

The appointment time slots are determined based on your Lightning Scheduler data model configurations. Here are some prerequisites that you can consider while setting up data.

• Set up Lightning Scheduler before making your requests. This setup includes creating or configuring Service Resources, Service Territory Members, Work Type Groups, Work Types, Work Type Group Members, and Service Territory Work Types. See Set Up Lightning Scheduler for more information.
• Configure a work type mapped for each territory in the request body via Service Territory Work Type. Map the same work type to the work type group, via work type group member.

Rules and Guidelines

The following factors affect how time slots are calculated and returned.

• Timezones that differ across operating hours are handled and results are always returned in UTC.
• The resource must be marked as a required resource on the assigned resource object.
• The resource is considered unavailable If the status categories of the resource assigned to service appointments are other than Canceled, Cannot Complete, and Completed.
• Resource Absences of all types are considered unavailable from start to end.
• The following fields of Work Type records, if configured, are used to fine-tune time slot requirements. For more information, see Create Work Types in Lightning Scheduler.

  Parameter	Description
  Timeframe Start	Time slots sooner than current time + Timeframe Start are not returned.
  Timeframe End	Time slots later than current time + Timeframe End are not returned.
  Block Time Before Appointment	This time period before the appointment is considered as unavailable.
  Block Time After Appointment	This time period after the appointment is considered as unavailable.
  Operating Hours	The overlap of all operating hours from the account, work type, service territory, and service territory member are considered while determining time slots. For more information, see Operating Hours Considerations in Lightning Scheduler.

• Only the time slots within the period of 28 days are returned.
• The earliest and latest appointment slots are calculated using the following guidelines:
  • The earliest appointment slot = maximum of
    • Service Territory Member Start Date
    • current time + Time frame Start
    • Start Time passed in the request body
  • The latest appointment slot = minimum of
    • Service Territory Member End Date
    • the earliest appointment slot date + 28 days
    • current time + Timeframe End