Get Appointment Candidates

Syntax

URI

/services/data/vXX.X/scheduling/getAppointmentCandidates

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
workTypeGroupId	Required if workType is not given.	String	The ID of the work type group containing the work types that are being performed.
workType	Required if workTypeGroupId is not given.	Work Type	The type of the work to be performed.
territoryIds	Yes	String[]	List of service territory IDs, where the work that is being requested is performed.
schedulingPolicyId	No	String	The ID of the AppointmentSchedulingPolicy object. If no scheduling policy is passed in the request body, the default configurations are used. All Scheduling Policy Configurations are considered when using this API.
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).
accountId	No	String	The ID of the associated account.

To determine the required fields in your request body, consider the following points:

• Provide either workTypeGroupId or workType in your request body, but not both
• If workType is given, then you must provide either id or durationInMinutes, but not both.
• If id of the workType is given, the rest of workType fields are optional.

Note

Response Body

Execution of a successful request returns the response body containing a list of available appointment resources.

Parameter	Required	Type	Description
candidates	Yes	Candidates[]	List of available appointment candidates.

Examples

Request Body Example

Using workTypeGroupId:

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    "schedulingPolicyId" : "0VrB0000000KyjB"
8}

Using workType:

1{
2"startTime" : "2019-01-23T00:00:00.000Z",
3"endTime" : "2019-02-30T00:00:00.000Z",
4"workType" : {
5    "id" : "08qRM00000003fkYAA"
6    },
7"territoryIds" : ["0HhRM00000003OZ0AY"],
8"accountId" : "001B000000qAUAWIA4",
9"schedulingPolicyId" : "0VrB0000000KyjB"
10}

Using durationInMinutes and without workTypeGroupId or workType id fields:

1{
2"workType" : {
3    "durationInMinutes" : 60,
4    "blockTimeBeforeAppointmentInMinutes" : 5,
5    "blockTimeAfterAppointmentInMinutes" : 5,
6    "timeFrameStartInMinutes" : 10080,
7    "timeFrameEndInMinutes" : 40320,
8    "operatingHoursId" : "0OHR00000004EEjOAM",
9    "skillRequirements" : [
10        {"skillId" : "0C5R000000000cf", "skillLevel" : 90}
11    ]
12  },
13"territoryIds" : ["0HhRM00000003OZ0AY"]
14}

Response Body Example

1{
2  "candidates" : [ {
3    "endTime" : "2019-01-23T19:15:00.000+0000",
4    "resources" : [ "0HnB0000000D2DsKAK" ],
5    "startTime" : "2019-01-23T16:15:00.000+0000",
6    "territoryId" : "0HhB0000000TO9WKAW"
7  }, {
8    "endTime" : "2019-01-23T19:30:00.000+0000",
9    "resources" : [ "0HnB0000000D2DsKAK" ],
10    "startTime" : "2019-01-23T16:30:00.000+0000",
11    "territoryId" : "0HhB0000000TO9WKAW"
12  }, {
13    "endTime" : "2019-01-23T19:45:00.000+0000",
14    "resources" : [ "0HnB0000000D2DsKAK" ],
15    "startTime" : "2019-01-23T16:45:00.000+0000",
16    "territoryId" : "0HhB0000000TO9WKAW"
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 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.
• The territory type of the Service Territory Member must be either Primary, Secondary, or Relocation. The Primary and Relocation territory types are considered the same.
• The territory type of the Service Territory Member must be either Primary, Secondary, or Relocation. The Primary and Relocation territory types are considered the same.

Rules and Guidelines

The following factors are considered for returning start time and end time of resources.

Resource Availability

Determined using service territory member, service territory, work type, and account operating hours fields.

Resource Unavailability

Determined by resource absences, existing appointments that the resource is assigned to. The resource must be marked as a required resource for the appointment with a status that is not in closed, canceled, or completed.

Appointment Start Time Interval in the Scheduling Policy

Appointment start time interval field in the Scheduling Policy is used to determine when the appointment can start. This interval can be 5, 10, 15, 20, 30, or 60. By default, it is set to 15.

Work Type Duration

The end time is calculated as start time + duration of the work type.