---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference
Release :
- xanadu
ft:locale :
- en-US
ft:publication_title :
- Xanadu API Reference
ft:clusterId :
- crapiref
bundleId :
- crapiref
workflow :
- Creator
---
# Appointment API
# Appointment API {#ariaid-title1}
* Release version: Xanadu
*
* Updated August 1, 2024
*
*  25 minutes to read
The Appointment API provides endpoints for interacting with the appointment booking application. Use this API to book and reschedule appointments, check available appointment slots, and fetch appointment
booking configuration details.
Before using this API, the Appointment Booking Configuration and Service Configuration must be setup. In addition, a task for which the appointment is being booked must already exist. For additional information, see [Configuring Appointment Booking](https://www.servicenow.com/docs/access?context=appointment-booking-administer&version=xanadu&pubname=xanadu-field-service-management&ft:locale=en-US).
The Appointment API requires the Appointment Booking plugin (com.snc.appointment_booking) and is provided within the `sn_apptmnt_booking` namespace. To access this API you must have the snc_internal
role.
## Appointment - GET /sn_apptmnt_booking/appointment/calendar {#ariaid-title2}
Returns the time range for which you can book appointments. The return results honor the lead time and maximum future bookable dates configured in the appointment booking service configuration.
For additional information on lead time and maximum future bookable dates configuration, see [Create or modify an appointment booking application configuration](https://www.servicenow.com/docs/access?context=appt-booking-create-app-config&version=xanadu&pubname=xanadu-field-service-management&ft:locale=en-US).
You must have either the snc_internal or snc_external role to access this endpoint.
### URL format
Versioned URL: /api/sn_apptmnt_booking/{api_version}/appointment/calendar
Default URL: /api/sn_apptmnt_booking/appointment/calendar
### Supported request parameters
{#appt-GET-calendar__entry__2}{#appt-GET-calendar__version-not_optional-RESTAPI}
| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String |
[Table 1. Path parameters]
{#appt-GET-calendar__entry__6}
| Name | Description |
|-|-|
| catalog_id | Required. Sys_id of the record producer configured with an appointment booking service configuration. Located in the Record Producer \[sc_cat_item_producer\] table. Data type: String |
| location | Required. Sys_id of the location (cmn_location) of the appointment. Located in the Location \[cmn_location\] table. Data type: String |
| opened_for | Required. Sys_id of the user for whom the appointment is being booked. Located in the User \[sys_user\] table. Data type: String |
[Table 2. Query parameters]
{#appt-GET-calendar__entry__14}
| Name | Description |
|-|-|
| None | |
[Table 3. Request body parameters]
### Headers
The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#appt-GET-calendar__entry__18}{#appt-GET-calendar__accept-JSON-only-entry-RESTAPI}
| Header | Description |
|-|-|
| Accept | Data format of the response body. Only supports application/json. |
[Table 4. Request headers]
{#appt-GET-calendar__entry__22}
| Header | Description |
|-|-|
| None | |
[Table 5. Response headers]
### Status codes
The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#appt-GET-calendar__entry__26}{#appt-GET-calendar__entry-200-status-code}{#appt-GET-calendar__entry-400-status-code}{#appt-GET-calendar__entry-500-status-code}
| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 6. Status codes]
### Response body parameters
{#appt-GET-calendar__entry__34}
| Name | Description |
|-|-|
| result | Information about the results of the endpoint request. Data type: Object "result": { "range_end": "String", "range_start": "String" } |
| result.range_end | End of the range in which the appointments can be booked. `Range End = Today + Maximum future bookable days` Data type: String Format: Appointment's time zone in internal date time format. |
| result.range_start | Start of the range in which the appointments can be booked. `Range Start = Today + Lead time` Data type: String Format: Appointment's time zone in internal date time format. |
[ ]
### cURL request
The following code example shows how to call this endpoint.
curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/calendar?catalog_id=e4c1116b3b810300ce8a4d72f3efc40f&location=32e8499cdb2d2200d75270f5bf9619d6&opened_for=6816f79cc0a8016401c5a33be04be441" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'
Result:
{
"result": {
"range_start": "2023-02-08 03:52:27",
"range_end": "2023-02-21 23:52:27"
}
}
## Appointment - GET /sn_apptmnt_booking/appointment/configuration {#ariaid-title3}
Returns the configuration defined in a specified Appointment Booking Service Configuration.
In addition, it returns the translations and user date and time preferences required to render the slots on the appointment booking widgets.
You must have either the snc_internal or snc_external role to access this endpoint.
### URL format
Versioned URL: /api/sn_apptmnt_booking/{api_version}/appointment/configuration
Default URL: /api/sn_apptmnt_booking/appointment/configuration
### Supported request parameters
{#appt-GET-configuration__entry__2}{#appt-GET-configuration__version-not_optional-RESTAPI}
| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String |
[Table 7. Path parameters]
{#appt-GET-configuration__entry__6}
| Name | Description |
|-|-|
| catalog_id | Required. Sys_id of the record producer configured with the appointment booking service configuration. Located in the Record Producer \[sc_cat_item_producer\] table. Data type: String |
[Table 8. Query parameters]
{#appt-GET-configuration__entry__10}
| Name | Description |
|-|-|
| None | |
[Table 9. Request body parameters]
### Headers
The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#appt-GET-configuration__entry__14}{#appt-GET-configuration__accept-JSON-only-entry-RESTAPI}
| Header | Description |
|-|-|
| Accept | Data format of the response body. Only supports application/json. |
[Table 10. Request headers]
{#appt-GET-configuration__entry__18}
| Header | Description |
|-|-|
| None | |
[Table 11. Response headers]
### Status codes
The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#appt-GET-configuration__entry__22}{#appt-GET-configuration__entry-200-status-code}{#appt-GET-configuration__entry-400-status-code}{#appt-GET-configuration__entry-500-status-code}
| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 12. Status codes]
### Response body parameters
{#appt-GET-configuration__entry__30}
| Name | Description |
|-|-|
| result | Results of the endpoint request. Data type: Object "result": { "active": Boolean, "active_string": "String", "advanced_calendar_view_portal": Boolean, "auto_acceptance": Boolean, "locale_language": "String", "service_config": {Object}, "task_table": "String", "translations": {Object}, "userDateFormatOptions": {Object}, "useRR": Boolean, "userTimeFormat": {Object}, "userTimeFormatOptions": {Object}, "view_scale": "String" } |
| result.active | Flag that indicates whether the service configuration setup for the associated catalog ID is active. Possible values: * true: Service configuration setup for the catalog ID is active. * false: Service configuration setup for the catalog ID isn't active. Data type: Boolean |
| result.active_string | Text representation of the status of the service configuration setup for the associated catalog ID. Data type: String |
| result.advanced_calendar_view_portal | Flag that indicates whether the advanced calendar view displays on the portal or displays the base view. For additional information on the advanced calendar view, see [Create or modify an appointment booking application configuration](https://www.servicenow.com/docs/access?context=appt-booking-create-app-config&version=xanadu&pubname=xanadu-field-service-management&ft:locale=en-US). Possible values: * true: Advanced calendar view displays on the portal. * false: Basic view displays on the portal. Data type: Boolean |
| result.auto_acceptance | Flag that indicates whether the appointment automatically transitions to the accepted state. Possible values: * true: Appointment automatically transitions to the accepted state. * false: Agent must manually accept the appointment. Data type: Boolean |
| result.locale_language | User's language setting. Data type: String Format: ISO 639.1 language code |
| result.service_config | Details about the service configuration. Data type: Object "service_config": { "active": Boolean, "active_string": "String", "appointment_booking_config": "String", "appointment_duration": "String", "appointments_per_bookable_slot": "String", "bookable_days": "String", "cancel_by_time": "String", "default_timezone": "String", "enable_advanced_config": Boolean, "field_mapping": {Object}, "future_bookable_max_days": "String", "lead_time": "String", "mandatory": "String", "use_slot_end_time_as": "String", "work_duration": "String" } |
| result.service_config.active | Flag that indicates the active status of the appointment booking service configuration. Possible values: * true: Active * false: Inactive Data type: Boolean |
| result.service_config.active_string | Text representation of the status of the appointment booking service configuration. Data type: String |
| result.service_config.appointment_booking_config | Sys_id of the appointment booking service configuration setup for the associated catalog ID. Located in the Appointment Booking Service Configuration \[sn_apptmnt_booking_service_config\] table. Data type: String |
| result.service_config.appointment_duration | Length of the appointment. Data type: String Unit: Minutes |
| result.service_config.appointments_per_bookable_slot | Number of appointments that can be booked for the associated slot. Data type: String |
| result.service_config.bookable_days | Comma-separated values representing the days on which appointments can be booked. Days are represented as integers where, Monday = 1 and Sunday = 7. Data type: String |
| result.service_config.cancel_by_time | Minimum amount of time prior to the start of an appointment that a user can cancel the appointment. For example, if you have an appointment booked for 1:00pm and there's a 2 hour cancel by time, you must cancel the appointment no later than 10:59 am. Format: This value is the date and time difference from "1970-01-01 00:00:00". So if the returned value is "1970-01-01 04:00:00, it means that the room must be canceled four hours before the meeting starts. Data type: String |
| result.service_config.default_timezone | Time zone configuration that appointments are booked in. Possible values: * location: Use the time zone of the location of the appointment. * user: Use the time zone of the person for whom the appointment is being booked. Data type: String |
| result.service_config.enable_advanced_config | Flag that indicates whether appointment booking configurations and appointment booking rules are considered when booking appointments. For additional information, see [Create appointment booking advanced configuration](https://www.servicenow.com/docs/access?context=appintment-booking-day-level-config&version=xanadu&pubname=xanadu-field-service-management&ft:locale=en-US). Possible values: * true: Appointment booking configurations and appointment booking rules are considered when booking appointments. * false: Appointment booking configurations and appointment booking rules aren't considered when booking appointments. Data type: Boolean |
| result.service_config.field_mapping | Details about the catalog variables mapped to the location and contact values used to book the appointment. Data type: Object "field_mapping": { "contact": "String", "contactRPVariable": {Object}, "location": "String", "locationRPVariable": {Object} } |
| result.service_config.field_mapping.contact | Name of the catalog variable that contains the contact value. Data type: String |
| result.service_config.field_mapping.contactRPVariable | Details about the location catalog variables data. Data type: Object "contactRPVariable": { "displayName": "String", "label": "String", "name": "String" } |
| result.service_config.field_mapping.contactRPVariable.displayName | Display name of the contact catalog variable. Data type: String |
| result.service_config.field_mapping.contactRPVariable.label | Label of the contact catalog variable. Data type: String |
| result.service_config.field_mapping.contactRPVariable.name | Name of the contact catalog variable. Data type: String |
| result.service_config.field_mapping.location | Name of the catalog variable that contains the location value. Data type: String |
| result.service_config.field_mapping.locationRPVariable | Details about the location catalog variables data. Data type: Object "locationRPVariable": { "displayName": "String", "label": "String", "name": "String" } |
| result.service_config.field_mapping.locationRPVariable.displayName | Display name of the location catalog variable. Data type: String |
| result.service_config.field_mapping.locationRPVariable.label | Label of the location catalog variable. Data type: String |
| result.service_config.field_mapping.locationRPVariable.name | Name of the location catalog variable. Data type: String |
| result.service_config. future_bookable_max_days | Maximum number of days in the future that an appointment can be booked. Data type: String |
| result.service_config.lead_time | Minimum amount of time prior to the start of an appointment that a user can book the appointment. For example, if you want to book an appointment at 1:00pm and there's a 2-hour lead time, you must book the appointment no later than 10:59 am. Format: This value is the date and time difference from "1970-01-01 00:00:00". So if the returned value is "1970-01-01 04:00:00, it means that the room must be booked four hours before the meeting starts. Data type: String |
| result.service_config.mandatory | Indicator for whether the appointment is mandatory. Possible values: * 0: Appointment isn't mandatory. * 1: Appointment is mandatory. Data type: String |
| result.service_config.use_slot_end_time_as | Indicator as to when an agent will arrive or complete the work scheduled for the associated appointment. Possible values: * arrive_by: Agent will arrive at the location for the appointment within the specified time slot. * complete_by: Agent will complete the work for the appointment within the specified time slot. * empty: Same as completed_by. Data type: String |
| result.service_config.work_duration | Amount of time it takes to work on the appointment. Work duration is configured in the appointment booking service configuration. For additional information, see [Create or modify an appointment booking service configuration](https://www.servicenow.com/docs/access?context=appt-booking-create-service-config&version=xanadu&pubname=xanadu-field-service-management&ft:locale=en-US). Data type: String Unit: Minutes |
| result.task_table | Name of the table for which the appointment can be booked. Configured in the appointment booking service configuration. Data type: String |
| result.translations | Name-value pairs of text translations used by the appointment booking widget. Contains translated values for actions, messages, days, and months. Data type: Object |
| result.userDateFormatOptions | Describes the date format options that are needed to render JS date objects. These values are set in appointment booking constants which are not modifiable. Data type: Object "userDateFormatOptions": { "day": "String", "month": "String", "week": "String", "weekday": "String" } |
| result.userDateFormatOptions.day | Day date format. Data type: String Format: Numeric (Values or 1-31) |
| result.userDateFormatOptions.month | Month date format. Data type: String Format: Short (Values on Jan, Feb, Mar, and so on) |
| result.userDateFormatOptions.week | Week date format. Data type: String Format: Numeric (Values of 1-5) |
| result.userDateFormatOptions.weekday | Weekday date format. Data type: String Format: Short (Values of Mon, Tue, Wed, and so on) |
| result.useRR | Value of the sn_apptmnt_booking.use_read_replica_from_ui property. This value defines whether to use the read replica database to fetch appointment slots when the query is performed from the UI. Possible values: * true: Use the read replica database to fetch the slots. * false: Don't use the read replica database to fetch the slots. Data type: Boolean |
| result.userTimeFormat | Describes the user's time format. The user is the person making the endpoint request. If made through the platform, it is an agent. If made through the portal, it is a customer. Data type: Object "userTimeFormat": { "type": "String", "value": "String" } |
| result.userTimeFormat.type | Type of time format. Possible values: * 12hr * 24hr Data type: String |
| result.userTimeFormat.value | Preferred time format, such as "HH:mm:ss". Data type: String |
| result.userTimeFormatOptions | Describes the time format options that are needed to render JS time objects. These values are set in the appointment booking constants which can't be modified. Data type: Object "userTimeFormatOptions": { "hour": "String", "hourCycle": "String", "minute": "String" } |
| result.userTimeFormatOptions.hour | Format for hours. Format: numeric (Values 1-12) |
| result.userTimeFormatOptions.hourCycle | Format for hour cycle. Only possible value is h23. |
| result.userTimeFormatOptions.minute | Format for minutes. Format: numeric (Values of 1-60) |
| result.view_scale | View configured in the service configuration. Possible values: * day * week Data type: String |
[ ]
### cURL request
The following code example shows how to call this endpoint.
curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/configuration?catalog_id=e4c1116b3b810300ce8a4d72f3efc40f" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'
Response:
{
"result": {
"active": true,
"activeString": "true"
"view_scale": "day",
"auto_acceptance": true,
"task_table": "wm_order",
"advanced_calendar_view_portal": false,
"service_config": {
"appointment_booking_config": "deb1d2fd3b033200ce8a4d72f3efc4c2",
"future_bookable_max_days": "14",
"appointments_per_bookable_slot": "20",
"bookable_days": "1,2,3,4,5",
"active": true,
"activeString": "true",
"mandatory": "1",
"lead_time": "1970-01-01 04:00:00",
"cancel_by_time": "1970-01-01 04:00:00",
"appointment_duration": "120",
"default_timezone": "location",
"work_duration": "60",
"enable_advanced_config": true,
"field_mapping": {
"location": "location"
"opened_for": "contact",
"locationRPVariable": {
"name": "location",
"label": "Location",
"displayName": "location"
},
"contactRPVariable": {
"name": "contact",
"label": "Contact",
"displayName": "contact"
}
},
"use_slot_end_time_as": ""
},
"translations": {
"submit_btn_text": "Select",
"cancel_btn_text": "Cancel",
"calendar_prev_text": "Previous",
"select_appointment_calendar_text": "Select Appointment Calendar",
"calendar_next_text": "Next",
"previous_btn_text": "Previous day",
"next_btn_text": "Next day",
"date_input_placeholder_text": "Pick a date",
"show_calendar_btn_text": "Show Calendar",
"app_window_btn_text_start_time": "Start time",
"app_window_btn_text_end_time": "End time",
"appointment_window_aria_label_start_text": "Available appointment window ",
"no_appointment": "No appointments",
"time_zone": "Time zone",
"selected_window": "The window which has been selected is ",
"day_names": {
"1": "Monday",
"2": "Tuesday",
"3": "Wednesday",
"4": "Thursday",
"5": "Friday",
"6": "Saturday",
"7": "Sunday"
},
"days": [
"Sunday",
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday",
"Saturday"
],
"daysShort": [
"Sun",
"Mon",
"Tue",
"Wed",
"Thu",
"Fri",
"Sat"
],
"daysMin": [
"Su",
"Mo",
"Tu",
"We",
"Th",
"Fr",
"Sa"
],
"months": [
"January",
"February",
"March",
"April",
"May",
"June",
"July",
"August",
"September",
"October",
"November",
"December"
],
"monthsShort": [
"Jan",
"Feb",
"Mar",
"Apr",
"May",
"Jun",
"Jul",
"Aug",
"Sep",
"Oct",
"Nov",
"Dec"
],
"today": "Today",
"clear": "Clear",
"language": "en",
"arrive_by_msg": "The agent will arrive within the selected slot."
},
"useRR": true,
"locale_language": "en",
"userTimeFormat": {
"value": "HH:mm:ss",
"type": "24hr"
},
"userDateFormatOptions": {
"weekday": "short",
"year": "numeric",
"month": "short",
"day": "numeric"
},
"userTimeFormatOptions": {
"hour": "numeric",
"minute": "numeric",
"hourCycle": "h23"
}
}
}
## Appointment - GET /sn_apptmnt_booking/appointment/execute_rule_conditions {#ariaid-title4}
Returns the sys_id of the appointment booking service configuration rule that matches a specified task sys_id or a set of specified catalog item data.
The passed task ID or catalog item data is evaluated against the rules defined for a service configuration. The sys_id for the first rule for which these conditions match is returned. You must then pass this rule sys_id to
subsequent availability requests to fetch the correct slots, which are defined in the rule.
You must have either the snc_internal or snc_external role to access this endpoint.
### URL format {#appt-GET-exec_rule_conditions__section_uzx_w3p_mwb}
Versioned URL: /api/sn_apptmnt_booking/{api_version}/appointment/execute_rule_conditions
Default URL: /api/sn_apptmnt_booking/appointment/execute_rule_conditions
### Supported request parameters
{#appt-GET-exec_rule_conditions__entry__2}{#appt-GET-exec_rule_conditions__version-not_optional-RESTAPI}
| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String |
[Table 13. Path parameters]
{#appt-GET-exec_rule_conditions__entry__6}
| Name | Description |
|-|-|
| None | |
[Table 14. Query parameters]
{#appt-GET-exec_rule_conditions__entry__10}
| Name | Description |
|-|-|
| catalogId | Required. Sys_id of the record producer configured with the appointment booking service configuration. Located in the Record Producer \[sc_cat_item_producer\] table. Data type: String |
| otherInputs | Required if the taskId parameter isn't specified. Name-value pairs of catalog item variables to compare against the rules defined for a service configuration. For example: "otherInputs": { "u_sn_point_of_sale_variable_set": "true", "short_description": "Point-of-Sale Installation", "contact": "6816f79cc0a8016401c5a33be04be441", "description": "Install new point-of-sale system with cash tray", "location": "32e8499cdb2d2200d75270f5bf9619d6" } Data type: Object |
| taskId | Required if the otherInputs parameter isn't specified. Sys_id of the task record for which the appointment is being booked. Located in the task table for which the appointment is being booked. The catalogId corresponds to a particular appointment booking configuration and every config has a task table on which the appointment is booked. Data type: String |
[Table 15. Request body parameters]
### Headers
The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#appt-GET-exec_rule_conditions__entry__18}{#appt-GET-exec_rule_conditions__accept-JSON-only-entry-RESTAPI}{#appt-GET-exec_rule_conditions__content_type-JSON-only-entry-RESTAPI}
| Header | Description |
|-|-|
| Accept | Data format of the response body. Only supports application/json. |
| Content-Type | Data format of the request body. Only supports application/json. |
[Table 16. Request headers]
{#appt-GET-exec_rule_conditions__entry__24}
| Header | Description |
|-|-|
| None | |
[Table 17. Response headers]
### Status codes
The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#appt-GET-exec_rule_conditions__entry__28}{#appt-GET-exec_rule_conditions__entry-200-status-code}{#appt-GET-exec_rule_conditions__entry-400-status-code}{#appt-GET-exec_rule_conditions__entry-500-status-code}
| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 18. Status codes]
### Response body parameters
{#appt-GET-exec_rule_conditions__entry__36}
| Name | Description |
|-|-|
| result | Description of the information returned by the endpoint. Data type: Object "result": { "dedicatedCapacity": Boolean, "futureMaxBookableDays": "String", "ruleId": "String", "ruleName": "String" } |
| result.dedicatedCapacity | Flag that indicates whether the associated rule has dedicated capacity. For additional information on dedicated capacity, see [Create appointment booking service configuration rules](https://www.servicenow.com/docs/access?context=create-appt-booking-service-config-rules&version=xanadu&pubname=xanadu-field-service-management&ft:locale=en-US). Possible values: * true: Rule has dedicated capacity. * false: Capacity is shared between the associated rule and the base configuration. It's also shared with other rules that don't have dedicated capacity. Data type: Boolean |
| result.futureMaxBookableDays | Maximum number of days in the future for which an appointment with the matching rule can be booked. Data type: String |
| result.ruleId | Sys_id of the appointment booking service configuration rule that matches the taskId or otherInputs parameters passed in the request. Located in the Service Configuration Rule \[sn_apptmnt_booking_config_rule\] table. Data type: String |
| result.ruleName | Name of the rule that matched the passed parameters. Data type: String |
[ ]
### cURL request
The following code example shows how to use the taskId parameter to make the rule comparison request.
curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/execute_rule_conditions" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
\"catalogId\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
\"taskId\": \"ce1f397c43b861105e0dbcba6ab8f298\"}" \
--user 'username':'password'
Response:
{
"result": {
"ruleId": "f7d5d98f437c21105e0dbcba6ab8f2fc",
"ruleName": "Priority 1 rule",
"dedicatedCapacity": true,
"futureMaxBookableDays": "14"
}
}
### cURL request {#appt-GET-exec_rule_conditions__example_gcb_j1w_mwb}
The following code example shows how to use the otherInputs parameter to make the rule comparison request.
curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/execute_rule_conditions" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
\"catalogId\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
\"otherInputs\": {
\"u_sn_point_of_sale_variable_set\": \"true\",
\"short_description\": \"Point-of-Sale Installation\",
\"contact\": \"6816f79cc0a8016401c5a33be04be441\",
\"description\": \"Install new point-of-sale system with cash tray\",
\"location\": \"32e8499cdb2d2200d75270f5bf9619d6\"
}
}" \
--user 'username':'password'
Response:
{
"result": {
"ruleId": " 1d1bb72b4334a1105e0dbcba6ab8f275",
"ruleName": "Lake View SC rule",
"dedicatedCapacity": false,
"futureMaxBookableDays": "21"
}
}
## Appointment - POST /sn_apptmnt_booking/appointment/appointment {#ariaid-title5}
Enables you to book and reschedule appointments for a Field Service Management task.
Note:
This endpoint only enables you to book and schedule appointments that have start and end times defined in the associated appointment booking service configuration and have available slots.
For additional information on Field Service Management tasks, see [Configuring Appointment Booking](https://www.servicenow.com/docs/access?context=appointment-booking-administer&version=xanadu&pubname=xanadu-field-service-management&ft:locale=en-US).
### URL format
Versioned URL: /api/sn_apptmnt_booking/{api_version}/appointment/appointment
Default URL: /api/sn_apptmnt_booking/appointment/appointment
### Supported request parameters
{#appt-POST-appointment__entry__2}{#appt-POST-appointment__version-not_optional-RESTAPI}
| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String |
[Table 19. Path parameters]
{#appt-POST-appointment__entry__6}
| Name | Description |
|-|-|
| None | |
[Table 20. Query parameters]
{#appt-POST-appointment__entry__10}
| Name | Description |
|-|-|
| actualEndDate | Required. End date and time for the appointment slot in the appointment's time zone. Date type: String Format: YYYY-MM-dd HH:mm:ss |
| actualStartDate | Required. Start date and time for the appointment slot in the appointment's time zone. Date type: String Format: YYYY-MM-dd HH:mm:ss |
| catalogId | Required. Sys_id of the record producer configured for the appointment booking service configuration. The record producer is defined in the Catalog Item field in the related appointment booking service configuration record - Appointment Booking Service Configuration \[sn_apptmnt_booking_service_config\] table. Date type: String |
| endDateUTC | Required. End date and time for the appointment slot in UTC time zone. Date type: String Format: YYYY-MM-dd HH:mm:ss |
| location | Required. Sys_id of the location record related to the appointment. Located in the Location \[cmn_location\] table. Date type: String |
| openedFor | Required. Sys_id of the user for which the appointment is being booked. Located in the User \[sys_user\] table. Date type: String |
| reschedule | Required. Flag that indicates whether the appointment is being rescheduled. Valid values: * true: Appointment currently exists and is being rescheduled. * false: New appointment. Data type: Boolean |
| service_cofig_rule | If the appointment is being booked under a rule, the sys_id of the service configuration rule. Located in the Service Configuration Rule \[sn_apptmnt_booking_config_rule\] table. Date type: String |
| startDateUTC | Required. Start date and time for the appointment slot in UTC time zone. Date type: String Format: YYYY-MM-dd HH:mm:ss in UTC time zone |
| taskId | Required. Sys_id of the task record for which the appointment is being booked. The table containing this sys_id is defined in the taskTable parameter. Date type: String |
| taskTable | Required. Name of the table containing the task record for which the appointment is being booked. Date type: String |
| timezone | Required. Time zone to use when booking or updating the specified appointment slot. Format: Country/City or Area format, such as US/Eastern Date type: String |
[Table 21. Request body parameters]
### Headers
The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#appt-POST-appointment__entry__36}{#appt-POST-appointment__accept-JSON-only-entry-RESTAPI}{#appt-POST-appointment__content_type-JSON-only-entry-RESTAPI}
| Header | Description |
|-|-|
| Accept | Data format of the response body. Only supports application/json. |
| Content-Type | Data format of the request body. Only supports application/json. |
[Table 22. Request headers]
{#appt-POST-appointment__entry__42}
| Header | Description |
|-|-|
| None | |
[Table 23. Response headers]
### Status codes
The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#appt-POST-appointment__entry__46}{#appt-POST-appointment__entry-200-status-code}{#appt-POST-appointment__entry-500-status-code}
| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 24. Status codes]
### Response body parameters
{#appt-POST-appointment__entry__52}
| Name | Description |
|-|-|
| result | Information about the results of the endpoint request. Data type: Object "result": { "data": "String", "message": "String", "reason": "String", "success": Boolean } |
| result.data | Sys_id of the appointment record that has been created or rescheduled. Data type: String |
| result.message | Message that explains whether the appointment request was scheduled or failed. For example, error responses might include: * Your appointment cannot be scheduled. * Your appointment cannot be rescheduled. If the operation is successful, a message similar to the following is returned: Your appointment has been scheduled successfully. Data type: String |
| result.reason | Additional information about the results of the appointment request. Data type: String |
| result.success | Flag that indicates whether the request was successful. Possible values: * true: Request succeeded * false: Request failed Data type: Boolean |
[ ]
### cURL request
The following example shows how to create a new appointment booking for a task in the Work Order \[wm_order\] table.
curl "https://instance.servicenow.com/api/sn_apptmnt_booking/appointment/appointment" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
\"startDateUTC\": \"2023-02-01 20:00:00\",
\"endDateUTC\": \"2023-02-01 22:00:00\",
\"actualStartDate\": \"2023-02-01 15:00:00\",
\"actualEndDate\": \"2023-02-01 17:00:00\",
\"taskTable\": \"wm_order\",
\"location\": \"32e8499cdb2d2200d75270f5bf9619d6\",
\"catalogId\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
\"openedFor\": \"ddce70866f9331003b3c498f5d3ee417\"
\"taskId\": \"ce1f397c43b861105e0dbcba6ab8f298\",
\"reschedule\": false,
\"service_configuration_rule\": \"\",
\"timezone\": \"US/Eastern\"
}" \
--user 'username':'password'
Response:
{
"result": {
"success": true,
"message": "Your appointment has been scheduled successfully.",
"reason": "Appointment created!",
"data": "7a5f393c43b861105e0dbcba6ab8f29f"
}
}
## Appointment - POST /sn_apptmnt_booking/appointment/availability {#ariaid-title6}
Returns the slots that have been configured in the appointment booking service configuration along with their availability.
If advanced configurations are enabled for the service configuration, the endpoint honors these configurations, and returns the data according to the rules and advanced configuration. You can also use this endpoint to find the
first available slot by passing the get_next_available_slot parameter or get_next_available_day_data parameter in the request body as `true`.
You must have either the snc_internal or snc_external role to access this endpoint.
### URL format {#appt-POST-availability__section_yyz_lgd_nwb}
Versioned URL: /api/sn_apptmnt_booking/{api_version}/appointment/availability
Default URL: /api/sn_apptmnt_booking/appointment/availability
### Supported request parameters
{#appt-POST-availability__entry__2}{#appt-POST-availability__version-not_optional-RESTAPI}
| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String |
[Table 25. Path parameters]
{#appt-POST-availability__entry__6}
| Name | Description |
|-|-|
| None | |
[Table 26. Query parameters]
{#appt-POST-availability__entry__10}
| Name | Description |
|-|-|
| catalog_id | Required. Sys_id of the record producer configured for the appointment booking service configuration. The record producer is defined in the Catalog Item field in the related appointment booking service configuration record - Appointment Booking Service Configuration \[sn_apptmnt_booking_service_config\] table. Data type: String |
| end_date | Required. End date and time for which to fetch appointments. Data type: String Format: UTC time zone and in the internal date and time format YYYY-MM-dd HH:mm:ss |
| full_day | Required. Flag that indicates whether to return all appointments for the specified date range passed regardless of the time values in start and end date. Possible values: * true: Return all appointments regardless of specified times. * false: Only return appointments that correspond to the specified dates and times. Data type: Boolean |
| get_next_available_slot | Flag that indicates whether to return the first available appointment slot with the response even if it isn't part of the passed-in start_date and end_date parameters. Possible values: * true: Return the first available appointment slot. * false: Don't return the first available appointment slot. Data type: Boolean Default: false |
| limit | Maximum number of appointments to return. Data type: Number Default: Value specified in the sn_apptmnt_booking .max_appointments_ returned property or 1000 if the property is empty. |
| location | Required. Sys_id of the location record associated with the appointment. Located in the Location \[cmn_location\] table. Data type: String |
| opened_for | Required. Sys_id of the user for which the appointment is being booked. Located in the User \[sys_user\] table. Data type: String |
| otherInputs | Name-value pairs of any other values needed to calculate the availability in the scripted method. Typically these values are catalog item variables, however, if you customize your booking application you can pass any values needed by your implementation. For example: "otherInputs": { "u_sn_point_of_sale_variable_set": "true", "short_description": "Point-of-Sale Installation", "contact": "6816f79cc0a8016401c5a33be04be441", "description": "Install new point-of-sale system with cash tray", "location": "32e8499cdb2d2200d75270f5bf9619d6" } Data type: Object |
| service_config_rule | Sys_id of the service configuration rule to use to calculate the appointment slots and availability. Located in the Service Configuration Rule \[sn_apptmnt_booking_config_rule\] table. Data type: String |
| start_date | Required. Start date and time for which to fetch appointments. Data type: String Format: UTC time zone and in the internal date and time format YYYY-MM-dd HH:mm:ss |
| task_table | Required. Name of the table containing the task record for which the appointment is being booked. Data type: String |
| use_read_replica | Flag that indicates whether to use the read replica of the database when fetching the appointment slots and their availability. Valid values: * true: Use the read replica of the database. * false: Don't use the read replica of the database. Default: false |
| view | Required. Origination point of the request. Valid values: (case-sensitive) * platform * portal Data type: String |
[Table 27. Request body parameters]
### Headers
The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#appt-POST-availability__entry__38}{#appt-POST-availability__accept-JSON-only-entry-RESTAPI}{#appt-POST-availability__content_type-JSON-only-entry-RESTAPI}
| Header | Description |
|-|-|
| Accept | Data format of the response body. Only supports application/json. |
| Content-Type | Data format of the request body. Only supports application/json. |
[Table 28. Request headers]
{#appt-POST-availability__entry__44}
| Header | Description |
|-|-|
| None | |
[Table 29. Response headers]
### Status codes
The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#appt-POST-availability__entry__48}{#appt-POST-availability__entry-200-status-code}{#appt-POST-availability__entry-400-status-code}{#appt-POST-availability__entry-500-status-code}
| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 30. Status codes]
### Response body parameters
{#appt-POST-availability__entry__56}
| Name | Description |
|-|-|
| result | Details about the appointments that match the request. Data type: Object "result": { "availability": [Array], "has_more": Boolean, "next_available_slot": {Object}, "no_appt_available": Boolean, "success": Boolean, "time_zone": "String", "time_zone_display_value": "String" } |
| result.availability | List of appointment slots that meet the specified request. Data type: Object "availability": { "available": Boolean, "end_date": "String", "end_date_display": "String", "end_dateUTC": "String", "start_date": "String", "start_date_display": "String", "start_dateUTC": "String" } |
| result.availability.available | Flag that indicates whether the associated time slot is available. Possible values: * true: Time slot is available. * false: Times slot isn't available. Data type: Boolean |
| result.availability.end_date | End date and time of the associated appointment. The time zone is based on the value in the time_zone parameter. Data type: String Format: YYYY-MM-DD hh:mm:ss |
| result.availability.end_date_display | Display end date and time of the associated appointment. The time zone is based on the value in the time_zone_display_value parameter. Data type: String Format: Requesting user's date time format. |
| result.availability.end_dateUTC | End date and time of the associated appointment in UTC time. Data type: String Format: YYYY-MM-DD hh:mm:ss |
| result.availability.start_date | Start date and time of the associated appointment. The time zone is based on the value in the time_zone parameter. Data type: String Format: YYYY-MM-DD hh:mm:ss |
| result.availability.start_date_display | Display start date and time of the associated appointment. The time zone is based on the value in the time_zone_display_value parameter. Data type: String Format: Requesting user's date time format. |
| result.availability.start_dateUTC | Start date and time of the associated appointment in UTC time. Data type: String Format: YYYY-MM-DD hh:mm:ss |
| result.has_more | Flag that indicates whether there are more appointment slots to fetch after returning the limit. Possible values: * true: More appointment slots are available. * false: No more slots are available. Data type: Boolean |
| result.next_available_slot | If the get_next_available_slot parameter was passed as true, details about the first available slot irrespective of the passed start and end date. Data type: Object "next_available_slot": { "available": Boolean, "end_date": "String", "end_date_display": "String", "end_dateUTC": "String", "start_date": "String", "start_date_display": "String", "start_dateUTC": "String" } |
| result.next_available_slot.available | Flag that indicates whether the associated time slot is available. Possible values: * true: Time slot is available. * false: Times slot isn't available. Data type: Boolean |
| result.next_available_slot.end_date | End date and time of the associated appointment. The time zone is based on the value in the time_zone parameter. Data type: String Format: YYYY-MM-DD hh:mm:ss |
| result.next_available_slot.end_date_display | Display end date and time of the associated appointment. The time zone is based on the value in the time_zone_display_value parameter. Data type: String Format: |
| result.next_available_slot.end_dateUTC | End date and time of the associated appointment in UTC time. Data type: String Format: YYYY-MM-DD hh:mm:ss |
| result.next_available_slot.start_date | Start date and time of the associated appointment. The time zone is based on the value in the time_zone parameter. Data type: String Format: YYYY-MM-DD hh:mm:ss |
| result.next_available_slot.start_date_display | Display start date and time of the associated appointment. The time zone is based on the value in the time_zone_display_value parameter. Data type: String Format: |
| result.next_available_slot.start_dateUTC | Start date and time of the associated appointment in UTC time. Data type: String Format: YYYY-MM-DD hh:mm:ss |
| result.no_appt_available | Flag that indicates whether there are more appointment slots available for the specified date and time. Possible values: * true: More appointment time slots are available. * false: No more appointment time slots are available. Data type: Boolean |
| result.success | Flag that indicates whether the endpoint call was successful. Possible values: * true: Endpoint call was successful. * false: Endpoint call failed. Data type: Boolean |
| result.time_zone | Time zone in which the appointment slots were rendered. Based on the values in the appointment booking service configuration. Data type: String |
| result.time_zone_display_value | Display time zone in which the appointment slots were rendered. Based on the values in the appointment booking service configuration. Data type: String |
[ ]
### cURL request
The following code example shows how to call this endpoint.
curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/availability" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
\"start_date\": \"2023-02-05 05:00:00\",
\"end_date\": \"2023-02-07 04:59:59\",
\"location\": \"32e8499cdb2d2200d75270f5bf9619d6\",
\"catalog_id\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
\"opened_for\": \"6816f79cc0a8016401c5a33be04be441\",
\"full_day\": false,
\"task_table\": \"wm_order\",
\"view\": \"portal\",
\"get_next_available_slot\": true,
\"use_read_replica\": true,
\"service_config_rule\": \"f7d5d98f437c21105e0dbcba6ab8f2fc\"
}" \
--user 'username':'password
Response:
{
"result": {
"success": true,
"availability": [
{
"start_date": "2023-02-06 09:00:00",
"end_date": "2023-02-06 11:00:00",
"start_date_display": "09:00",
"end_date_display": "11:00",
"start_dateUTC": "2023-02-06 14:00:00",
"end_dateUTC": "2023-02-06 16:00:00",
"available": false
},
{
"start_date": "2023-02-06 13:00:00",
"end_date": "2023-02-06 15:00:00",
"start_date_display": "13:00",
"end_date_display": "15:00",
"start_dateUTC": "2023-02-06 18:00:00",
"end_dateUTC": "2023-02-06 20:00:00",
"available": false
},
{
"start_date": "2023-02-06 15:00:00",
"end_date": "2023-02-06 17:00:00",
"start_date_display": "15:00",
"end_date_display": "17:00",
"start_dateUTC": "2023-02-06 20:00:00",
"end_dateUTC": "2023-02-06 22:00:00",
"available": false
}
],
"has_more": false,
"no_appt_available": true,
"time_zone": "US/Eastern",
"time_zone_display_value": "US/Eastern",
"next_available_slot": {
"start_date": "2023-02-10 13:00:00",
"end_date": "2023-02-10 15:00:00",
"start_date_display": "13:00",
"end_date_display": "15:00",
"start_dateUTC": "2023-02-10 18:00:00",
"end_dateUTC": "2023-02-10 20:00:00",
"available": true
}