REST API reference › API reference › API implementation and reference

Release: Australia · Updated: 2026-03-12 · Official documentation · View source

Appointment Open API

The Appointment Open API is a telecommunication API that allows you to interact with the appointment booking application. Use this API to book appointments and search available time slots.

The Appointment Open API is a ServiceNow® implementation of the Open API TMForum TMF646 Appointment REST API specification and is conformance certified by TM Forum. This implementation is based on TMF646 Appointment API REST Specification R16.0.1.

Image omitted: tmf-conformance.png
TMF conformance logo

This API requires the following plugins available on the ServiceNow Store.

Appointment Booking (com.snc.appointment_booking)
Field Service Management (com.snc.work_management)
Field Service Management for Telecommunications (com.sn_fsmt)
Telecommunication Open APIs (com.sn_tmf_api)

Before using this API, Appointment Booking Configuration and Service Configuration must be set up. In addition, a task for which the appointment is being booked must exist.

This API is provided within the sn_tmf_api namespace. The calling user must have the sn_tmf_api.appointment_integrator role.

Parent Topic:REST API reference

Appointment Open - DELETE /api/sn_tmf_api/appointment/appointment/{id}

Deletes an appointment record with a given ID.

URL format

Default URL: /api/sn_tmf_api/appointment/appointment/{id}

Supported request parameters

Name	Description
id	Sys\_id of the appointment record to delete. Data type: String Table: Appointment booking \[sn\_apptmnt\_booking\_appointment\_booking\]

Name	Description
None

Name	Description
None

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.

Header	Description
Accept	Data format of the response body. Only supports application/json.

Header	Description
Content-Type	Data format of the request body. Only supports application/json.

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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
404	Not found. The requested item wasn't found.

Response body parameters (JSON)

Name

Description

message

Response message acknowledging successful deletion.Success: "The appointment \(<id>\) is successfully cancelled." Errors: - "Appointment cancellation failed.": The ID can't be found in the system and returns a 404 status code. - "Appointment cancellation failed.": The appointment is already in a cancelled or completed state or can't be deleted, and returns a 404 status code. - "The appointment \(<id>\) can't be cancelled as it is beyond the Cancel by time.": The appointment is already beyond the ‘cancel by time’, which is configured in the appointment booking service configuration. Returns a 400 status code. Data type: String

cURL request

The following example deletes an appointment with a specific ID.

curl "http://instance.servicenow.com/api/sn_tmf_api/appointment/appointment/68cc0a5a9314521060320dd548373" \ 
--request GET\ 
--user 'username':'password'

Response body:

"The appointment (68cc0a5a9314521060320dd548373cbd) is successfully cancelled."

Appointment Open - GET /api/sn_tmf_api/appointment/searchTimeSlot

Returns time slots that were configured in the appointment booking service configuration along with their availability.

URL format

/api/sn_tmf_api/appointment/searchTimeSlot

Supported request parameters

Name	Description
None

Name	Description
catalog\_id	Required. Sys\_id of the record producer configured with an appointment booking service configuration. Data type: String Table: Record Producer \[sc\_cat\_item\_producer\]
end\_date	Required. End date and time of the time period in which you want to search for the appointment.Data type: String Format: YYYY-MM-DD 00:00:00. For example, `2025-01-31 12:00:00`.
location	Sys\_id of the appointment's location.Table: Location \[cmn\_location\] Data type: String Default: Returns all locations if not specified.
opened\_for	Required. Sys\_id of the user for whom the appointment is being booked.Table: Contact \[customer\_contact\] Data type: String
start\_date	Required. Start date and time of the time period in which you want to search for the appointment.Data type: String Format: YYYY-MM-DD 00:00:00. For example, `2025-01-31 09:00:00`.

Name	Description
None

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.

Header	Description
Accept	Data format of the response body. Only supports application/json.

Header	Description
None

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.

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.

Response body parameters

Name	Description
availableTimeSlot	List of appointment slots within the specified block of time requested.Data type: Array of Objects `'availableTimeSlot': [ { "available": Boolean, "end_date": "String", "end_date_display": "String", "end_dateUTC": "String", "start_date": "String", "start_date_display": "String", "start_dateUTC": "String" } ]`
availableTimeSlot.available	Flag that indicates whether the associated time slot is available.Possible values: - true: Time slot is available. - false: Time slot is unavailable. Data type: Boolean
availableTimeSlot.end\_date	End date and time of the associated appointment. The time zone is based on the value in the timeZone parameter.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
availableTimeSlot.end\_date\_display	Display end date and time of the associated appointment. The time zone is based on the value in the timeZone parameter.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
availableTimeSlot.end\_dateUTC	End date and time of the associated appointment.Data type: String Format: UTC
availableTimeSlot.start\_date	Start date and time of the associated appointment. Reflects the value of the timeZone parameter.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
availableTimeSlot.start\_date\_display	Display start date and time of the associated appointment. Reflects the value of the timeZone parameter.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
availableTimeSlot.start\_dateUTC	Start date and time of the associated appointment.Data type: String Format: UTC
hasMore	Flag that indicates whether there are more appointment slots to fetch after returning the limit. The limit is specified in the Appointment Booking property, sn\_apptmnt\_booking.max\_appointments\_returned \(Default: 100\). See Appointment booking components for more details about this property.Possible values: - true: More appointment slots can be fetched. - false: No more appointment slots are available. Data type: Boolean
noApptAvailable	Flag that indicates whether there are more appointment slots available for the specified date and time.Valid values: - true: More appointment slots are available for the specified date and time. - false: No more appointment slots are available for the specified date and time. Data type: Boolean
searchResult	Results for appointment availability within the designated search time slot.Possible values: - success - fail Data type: String
status	Completion status of the search for available time slots. For example, done.Data type: String
timeZone	Time zone used when booking or updating the specified appointment slot.Date type: String Format: Country/city or area format, such as US/Eastern

cURL request

The following code example shows how to call this endpoint.

curl --location --request GET 'https://instance.service-now.com/api/sn_tmf_api/appointment/searchTimeSlot?
start_date=2024-07-10 09:00:00&end_date=2024-07-20 23:00:00&catalog_id=ada50a93f0220210f8776517d8c8e776&
opened_for=51670151c35420105252716b7d40ddfe&location=f48b21850a0a0ba7004182b18099696d ' \
--user 'username':'password'

Result:

{
  "searchResult": "success",
  "status": "done",
  "availableTimeSlot": [
    {
      "start_date": "2024-07-10 09:00:00",
      "end_date": "2024-07-10 12:00:00",
      "start_date_display": "09:00",
      "end_date_display": "12:00",
      "start_dateUTC": "2024-07-10 16:00:00",
      "end_dateUTC": "2024-07-10 19:00:00",
      "available": false
    },
    {
      "start_date": "2024-07-11 13:00:00",
      "end_date": "2024-07-11 16:00:00",
      "start_date_display": "13:00",
      "end_date_display": "16:00",
      "start_dateUTC": "2024-07-11 20:00:00",
      "end_dateUTC": "2024-07-11 23:00:00",
      "available": true
    },
    {
      "start_date": "2024-07-12 09:00:00",
      "end_date": "2024-07-12 12:00:00",
      "start_date_display": "09:00",
      "end_date_display": "12:00",
      "start_dateUTC": "2024-07-12 16:00:00",
      "end_dateUTC": "2024-07-12 19:00:00",
      "available": true
    },
    {
      "start_date": "2024-07-12 13:00:00",
      "end_date": "2024-07-12 16:00:00",
      "start_date_display": "13:00",
      "end_date_display": "16:00",
      "start_dateUTC": "2024-07-12 20:00:00",
      "end_dateUTC": "2024-07-12 23:00:00",
      "available": true
    },
    {
      "start_date": "2024-07-19 13:00:00",
      "end_date": "2024-07-19 16:00:00",
      "start_date_display": "13:00",
      "end_date_display": "16:00",
      "start_dateUTC": "2024-07-19 20:00:00",
      "end_dateUTC": "2024-07-19 23:00:00",
      "available": true
    }
  ],
  "hasMore": false,
  "noApptAvailable": false,
  "timeZone": "US/Arizona"
}

Appointment Open - GET /api/sn_tmf_api/appointment/appointment/{id}

Retrieves an appointment record associated with a specified ID.

URL format

Default URL: /api/sn_tmf_api/appointment/appointment/{id}

Supported request parameters

Name	Description
id	Sys\_id of the appointment to retrieve.Data type: String Table: Appointment booking \[sn\_apptmnt\_booking\_appointment\_booking\]

Name	Description
category	Filter the appointment by category sys\_id.Data type: String Table: Location \[cmn\_location\] Default: Returns all appointments if category sys\_id is not provided.
relatedEntity	Details about the related entity associated with the work order.Data type: Object `"relatedEntity": { "id": "String" }`
relatedEntity.id	Required. Sys\_id of the related entity.Data type: String Table: workOrder \[wm\_order\] Default: Returns all if sys\_id is not provided.
relatedParty	Filter the appointment by the sys_id of the related party associated with the appointment.Data type: Object `"relatedParty": { "id": "String", "name": "String" }` Default: Returns all appointments if relatedParty is not provided.
relatedParty.id	Sys\_id of the related party.Data type: String Table: User \[sys\_user\]
relatedParty.name	Name of the related party.Data type: String
relatedPlace	Filter the appointment by the place where the service or repair is scheduled to happen.Data type: Object `"relatedPlace": { "id": "String" }` Default: Returns all appointments if relatedPlace is not provided.
relatedPlace.id	Sys\_id of the related place.Data type: String Table: Location \[cmn\_location\]
validFor	Filter the appointment by a date range that the appointment is valid for.Data type: Object `"validFor": { "endDateTime": "String", "startDateTime": "String" }` Default: Returns all appointments if validFor is not provided.
validFor.endDateTime	End date and time of the appointment. Only appointments with the specified end date and time are returned in the response.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43. Table: Location \[cmn\_location\]
validFor.startDateTime	Start date and time of the appointment. Only appointments with the specified start date and time are returned in the response. Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43. Table: Location \[cmn\_location\]

Name	Description
None

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.

Header	Description
Accept	Data format of the response body. Only supports application/json.

Header	Description
Content-Type	Data format of the request body. Only supports application/json.

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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
404	Not found. The requested item wasn't found.

Response body parameters

Name	Description
category	Sys\_id of the record producer configured for the appointment booking service configuration.Data type: String Stored in: Catalog Item  field of the Appointment Booking Service Configuration \[sn\_apptmnt\_booking\_service\_config\] table.
creationDate	Date and time that the appointment was created.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
href	Hyperlink to the appointment record. Use this link in another Appointment Open API request to reschedule or delete the appointment.Data type: String
id	Sys\_id of the appointment.Data type: String Stored in: Appointment Booking Service Configuration \[sn\_apptmnt\_booking\_service\_config\] table
lastUpdate	Date and time the appointment was last updated.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
relatedEntity	Details about the related entity of the appointment.Data type: Array of Objects `"relatedEntity": [ { "@referredType": "String", "id": "String", "role": "String" } ]`
relatedEntity.@referredType	Type of item or service.Data type: String Stored in: workOrder \[wm\_order\] table
relatedEntity.id	Sys\_id of the related entity.Data type: String Stored in: workOrder \[wm\_order\] table
relatedEntity.role	Role description of the related entity. Possible value: work order Data type: String Stored in: workOrder \[wm\_order\] table
relatedParty	List of contacts for the appointment. Each contact is an object in the array.Data type: Array of Objects `"relatedParty": [ { "@referredType": "String", "id": "String", "name": " String", "role": "String" } ]`
relatedParty.@referredType	Type of customer.Data type: String Stored in: Contact \[customer\_contact\] table
relatedParty.id	Sys\_id of the customer contact associated with the work order.Data type: String Stored in: Contact \[customer\_contact\] table
relatedParty.name	Name of the customer contact.Data type: String Stored in: Contact \[customer\_contact\] table
relatedParty.role	Role of the customer contact.Possible values: - customer: The contact has a customer role. - technician: The contact has a technician role. Data type: String Stored in: Contact \[customer\_contact\] table
relatedPlace	Location details of the associated appointment.Data type: Object `"relatedPlace": { "@referredType": "String", "id": "String", "name": "String", "role": "String" }`
relatedPlace.@referredType	Geographic address of the appointment. Possible value: GeographicLocation. Data type: String Stored in: Location \[cmn\_location\] table
relatedPlace.id	Sys\_id of the location. Data type: String Stored in: Location \[cmn\_location\] table
relatedPlace.name	Name of the location related to the contact. For example, 100 South Charles Street, Baltimore, MD.Data type: String Stored in: Location \[cmn\_location\] table
relatedPlace.role	Role of the appointment location as an intervention address.Possible value: InterventionAddress Data type: String Stored in: Location \[cmn\_location\] table
validFor	Date range that the appointment is valid for.Data type: Object `"validFor": { "endDateTime": "String" "startDateTime": "String" }`
validFor.endDateTime	End date and time of the appointment.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
validFor.startDateTime	Start date and time of the appointment.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.

cURL request

The following example returns appointment details according to the given appointment record ID.

curl "http://instance.servicenow.com/api/sn_tmf_api/appointment/appointment/201071ad4f80d210f8992fec52ce0ba9" \ 
--request GET\ 
--user 'username':'password'

Response body:

[
  {
    "id": "201071ad4f80d210f8992fec52ce0ba9",
    "href": "api/sn_tmf_api/appointment/appointment/201071ad4f80d210f8992fec52ce0ba9",
    "validFor": {
      "startDateTime": "2024-08-16 17:00:00",
      "endDateTime": "2024-08-16 19:00:00"
    },
    "category": "4a34a64d4f4c1210f8992fec52ce0b63",
    "relatedParty": [
      {
        "id": "eaf68911c35420105252716b7d40ddde",
        "name": " null",
        "role": "customer",
        "@referredType": "Individual"
      }
    ],
    "relatedPlace": {
      "id": "25ab9c4d0a0a0bb300f7dabdc0ca7c1c",
      "name": "100 South Charles Street, Baltimore,MD",
      "role": "interventionAddress",
      "@referredType": "Individual"
    },
    "relatedEntity": [
      {
        "id": "b440a5694f40d210f8992fec52ce0ba3",
        "role": "work order",
        "@referredType": "WorkOrder"
      }
    ],
    "creationDate": "2024-08-16 00:39:22",
    "lastUpdate": "2024-08-16 00:39:22"
  }
]

Appointment Open - GET /api/sn_tmf_api/appointment/appointment

Retrieves a list of appointment records.

URL format

Default URL: /api/sn_tmf_api/appointment/appointment

Supported request parameters

Name	Description
None

Name	Description
category	Filter the appointment by category sys\_id.Data type: String Table: Location \[cmn\_location\] Default: Returns all appointments if category sys\_id is not provided.
relatedEntity	Details about the related entity associated with the work order.Data type: Object `"relatedEntity": { "id": "String" }`
relatedEntity.id	Required. Sys\_id of the related entity.Data type: String Table: workOrder \[wm\_order\] Default: Returns all if sys\_id is not provided.
relatedParty	Filter the appointment by the sys_id of the related party associated with the appointment.Data type: Object `"relatedParty": { "id": "String", "name": "String" }` Default: Returns all appointments if relatedParty is not provided.
relatedParty.id	Sys\_id of the related party.Data type: String Table: User \[sys\_user\]
relatedParty.name	Name of the related party.Data type: String
relatedPlace	Filter the appointment by the place where the service or repair is scheduled to happen.Data type: Object `"relatedPlace": { "id": "String" }` Default: Returns all appointments if relatedPlace is not provided.
relatedPlace.id	Sys\_id of the related place.Data type: String Table: Location \[cmn\_location\]
validFor	Filter the appointment by a date range that the appointment is valid for.Data type: Object `"validFor": { "endDateTime": "String", "startDateTime": "String" }` Default: Returns all appointments if validFor is not provided.
validFor.endDateTime	End date and time of the appointment. Only appointments with the specified end date and time are returned in the response.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43. Table: Location \[cmn\_location\]
validFor.startDateTime	Start date and time of the appointment. Only appointments with the specified start date and time are returned in the response. Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43. Table: Location \[cmn\_location\]

Name	Description
None

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.

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

Header	Description
Content-Type	Data format of the request body. Only supports application/json.

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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
404	Not found. The requested item wasn't found.

Response body parameters (JSON or XML)

Name	Description
category	Sys\_id of the record producer configured for the appointment booking service configuration.Data type: String Stored in: Catalog Item  field of the Appointment Booking Service Configuration \[sn\_apptmnt\_booking\_service\_config\] table.
creationDate	Date and time that the appointment was created.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
href	Hyperlink to the appointment record. Use this link in another Appointment Open API request to reschedule or delete the appointment.Data type: String
id	Sys\_id of the appointment.Data type: String Stored in: Appointment Booking Service Configuration \[sn\_apptmnt\_booking\_service\_config\] table
lastUpdate	Date and time the appointment was last updated.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
relatedEntity	Details about the related entity of the appointment.Data type: Array of Objects `"relatedEntity": [ { "@referredType": "String", "id": "String", "role": "String" } ]`
relatedEntity.@referredType	Type of item or service.Data type: String Stored in: workOrder \[wm\_order\] table
relatedEntity.id	Sys\_id of the related entity.Data type: String Stored in: workOrder \[wm\_order\] table
relatedEntity.role	Role description of the related entity. Possible value: work order Data type: String Stored in: workOrder \[wm\_order\] table
relatedParty	List of contacts for the appointment. Each contact is an object in the array.Data type: Array of Objects `"relatedParty": [ { "@referredType": "String", "id": "String", "name": " String", "role": "String" } ]`
relatedParty.@referredType	Type of customer.Data type: String Stored in: Contact \[customer\_contact\] table
relatedParty.id	Sys\_id of the customer contact associated with the work order.Data type: String Stored in: Contact \[customer\_contact\] table
relatedParty.name	Name of the customer contact.Data type: String Stored in: Contact \[customer\_contact\] table
relatedParty.role	Role of the customer contact.Possible values: - customer: The contact has a customer role. - technician: The contact has a technician role. Data type: String Stored in: Contact \[customer\_contact\] table
relatedPlace	Location details of the associated appointment.Data type: Object `"relatedPlace": { "@referredType": "String", "id": "String", "name": "String", "role": "String" }`
relatedPlace.@referredType	Geographic address of the appointment. Possible value: GeographicLocation. Data type: String Stored in: Location \[cmn\_location\] table
relatedPlace.id	Sys\_id of the location. Data type: String Stored in: Location \[cmn\_location\] table
relatedPlace.name	Name of the location related to the contact. For example, 100 South Charles Street, Baltimore, MD.Data type: String Stored in: Location \[cmn\_location\] table
relatedPlace.role	Role of the appointment location as an intervention address.Possible value: InterventionAddress Data type: String Stored in: Location \[cmn\_location\] table
validFor	Date range that the appointment is valid for.Data type: Object `"validFor": { "endDateTime": "String" "startDateTime": "String" }`
validFor.endDateTime	End date and time of the appointment.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
validFor.startDateTime	Start date and time of the appointment.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.

cURL request

The following example shows how to return a list of appointments using the GET appointment method.

curl "http://instance.servicenow.com/api/sn_tmf_api/appointment/appointment" \ 
--request GET\ 
--user 'username':'password'

The response body contains the details of two different appointments configured in the appointment booking service configuration:

[
  {
    "id": "201071ad4f80d210f8992fec52ce0ba9",
    "href": "api/sn_tmf_api/appointment/appointment/201071ad4f80d210f8992fec52ce0ba9",
    "validFor": {
      "startDateTime": "2024-08-16 17:00:00",
      "endDateTime": "2024-08-16 19:00:00"
    },
    "category": "4a34a64d4f4c1210f8992fec52ce0b63",
    "relatedParty": [
      {
        "id": "eaf68911c35420105252716b7d40ddde",
        "name": " null",
        "role": "customer",
        "@referredType": "Individual"
      }
    ],
    "relatedPlace": {
      "id": "25ab9c4d0a0a0bb300f7dabdc0ca7c1c",
      "name": "100 South Charles Street, Baltimore,MD",
      "role": "interventionAddress",
      "@referredType": "Individual"
    },
    "relatedEntity": [
      {
        "id": "b440a5694f40d210f8992fec52ce0ba3",
        "role": "work order",
        "@referredType": "WorkOrder"
      }
    ],
    "creationDate": "2024-08-16 00:39:22",
    "lastUpdate": "2024-08-16 00:39:22"
  },
  {
    "id": "25c012c07f5c5610f8994fa63c866523",
    "href": "api/sn_tmf_api/appointment/appointment/25c012c07f5c5610f8994fa63c866523",
    "validFor": {
      "startDateTime": "2024-08-26 17:00:00",
      "endDateTime": "2024-08-26 19:00:00"
    },
    "category": "4a34a64d4f4c1210f8992fec52ce0b63",
    "relatedParty": [
      {
        "id": "eaf68911c35420105252716b7d40ddde",
        "name": " null",
        "role": "customer",
        "@referredType": "Individual"
      }
    ],
    "relatedPlace": {
      "id": "f48b21850a0a0ba7004182b18099696d",
      "name": "11251 Rancho Carmel Drive, San Diego,CA",
      "role": "interventionAddress",
      "@referredType": "Individual"
    },
    "relatedEntity": [
      {
        "id": "c0b09a047f109610f8994fa63c8665b4",
        "role": "work order",
        "@referredType": "WorkOrder"
      }
    ],
    "creationDate": "2024-08-23 22:18:43",
    "lastUpdate": "2024-08-23 22:18:43"
  }
]

Appointment Open - PATCH /api/sn_tmf_api/appointment/appointment/{id}

Reschedule appointments with a given ID for a  work order.

URL format

Default URL: PATCH /api/sn_tmf_api/appointment/appointment/{id}

Supported request parameters

Name	Description
id	Sys\_id of the appointment to reschedule. Data type: String Table: Appointment booking \[sn\_apptmnt\_booking\_appointment\_booking\]

Name	Description
None

Name	Description
note	If canceling the appointment, you can add work notes here. Updates the work notes of the work order and the message of the appointment.Data type: Array of Objects `"note": [ { "author": "String", "date": "String", "text": "String" } ]` Stored in: Appointment Booking \[sn\_apptmnt\_booking\_appointment\_booking\] table
note.author	Name of the person who writing the note.Data type: String
note.date	Date and time that the note was published. Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2018-02-04T11:00:18.071Z.
note.text	Descriptive text about the work order that is attached to the appointment. For example, updates on the work order's progress.Data type: String
status	Status of the appointment.Valid values: - cancelled: The appointment reschedule is cancelled. - completed: The rescheduled appointment is completed. - confirmed: The appointment reschedule is accepted and booked. - new: The appointment rescheduling request was recently created. - pending: The appointment reschedule is pending. - ready: The appointment reschedule is requested. Data type: String
validFor	Filter the appointment by a date range that the appointment is valid for.Data type: Object `"validFor": { "endDateTime": "String", "startDateTime": "String" }` Default: Returns all appointments if validFor is not provided.
validFor.endDateTime	End date and time of the appointment. Only appointments with the specified end date and time are returned in the response.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43. Table: Location \[cmn\_location\]
validFor.startDateTime	Start date and time of the appointment. Only appointments with the specified start date and time are returned in the response. Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43. Table: Location \[cmn\_location\]

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.

Header	Description
Accept	Data format of the response body. Only supports application/json.

Header	Description
Content-Type	Data format of the request body. Only supports application/json.

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.

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.

Response body parameters (JSON)

Name	Description
creationDate	Date and time that the appointment was created.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
href	Unique reference link of the appointment. You can use this link in another request to get an appointment.Data type: String
id	Sys\_id of the appointment that was rescheduled.Data type: String Stored in: Appointment booking \[sn\_apptmnt\_booking\_appointment\_booking\] table
lastUpdate	Date and time the appointment was last updated.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
reason	Purpose for updating the appointment.Possible values: - "Appointment rescheduled.": The PATCH method was used to reschedule the appointment. - "The appointment \(id\) is successfully cancelled.": The PATCH method was used to cancel the appointment. Data type: String
relatedParty	Customer details of the associated appointment.Data type: Array of Objects `"relatedParty": [ { "@referredType": "String", "id": "String", "name": "String", "role": "String" } ]`
relatedParty.id	Sys\_id of the customer contact.Data type: String Stored in: Contact \[customer\_contact\] table
relatedParty.name	Name of the customer contact.Data type: String
relatedPlace.@referredType	Type of customer.Data type: String Only possible value: Individual
relatedParty.role	Role of the contact.Data type: String Only possible value: Contact
success	Flag that indicates whether the request was successful.Possible values: - true: The appointment was successfully rescheduled. - false: The appointment couldn't be rescheduled. Data type: Boolean

cURL request

The following example demonstrates how to use a PATCH method to reschedule an appointment with a given ID.

curl -X POST 'https://instance.service-now.com/api/sn_tmf_api/appointment/appointment/68cc0a5a9314521060320dd548373cbd ' \ 
-H "Accept: application/json" \ 
-H "Content-Type: application/json" \ 
-u "username":"password" \ 
-data {
  "validFor": { 
      "startDateTime": "2024-07-30 00:0:00", 
      "endDateTime": "2024-08-30 00:00:00" 
              }
  "note": {
      "date": "85388c25b71011104eed4643ae11a993",
      "author": "Sarah Johnson",
      "text": "customer"
    }
  "state": "active"
   }
  ]
}

The response body shows a success message that the appointment was rescheduled.

{
  "relatedParty": [
    {
      "id": "85388c25b71011104eed4643ae11a993",
      "name": "Sarah Johnson",
      "role": "customer",
      "@referredType": "Individual"
    }
  ],
  "success": true,
  "reason": "Appointment rescheduled!",
  "id": "68cc0a5a9314521060320dd548373cbd",
  "href": "api/sn_tmf_api/appointment/appointment/68cc0a5a9314521060320dd548373cbd",
  "creationDate": "2024-08-30 20:56:54",
  "lastUpdate": "2024-08-30 20:56:54"
}

Appointment Open - POST /api/sn_tmf_api/appointment/appointment

Enables you to book appointments for a work order.

URL format

/api/sn_tmf_api/appointment/appointment

Supported request parameters

Name	Description
None

Name	Description
None

Name	Description
category	Required. Sys\_id of the record producer configured for the appointment booking service configuration. Data type: String Table: In the Catalog Item field of the Appointment Booking Service Configuration \[sn\_apptmnt\_booking\_service\_config\] table.
relatedEntity	Required. List of impacted work orders to associate with the appointment.Data type: Array of Objects `"relatedEntity": [ { "@referredType": "String" "id": "String", } ]`
relatedEntity.@referredType	Required. Type of item or service. Only valid value: WorkOrder Data type: String Table: Work Order \[wm\_order\]
relatedEntity.id	Required. Sys\_id of the related entity.Data type: String Table: workOrder \[wm\_order\] Default: Returns all if sys\_id is not provided.
relatedEntity.role	Required. Role description of the related entity. Only valid value: work order Data type: String Table: Work Order \[wm\_order\]
relatedParty	Required. List of contacts for the appointment. Each contact is an object in the array. The request must list at least one item which contains customer account information.Data type: Array of Objects `"relatedParty": [ { "@referredType": "String", "id": "String", "name": "String", "role": "String" } ]`
relatedParty.@referredType	Type of customer. Only valid value: Individual Data type: String
relatedParty.id	Required. Sys\_id or external\_id of the contact associated with the work order. Data type: String Table: Contact \[customer\_contact\]
relatedParty.name	Name of the contact.Data type: String Table: Contact \[customer\_contact\]
relatedParty.role	Required. Role of the contact.Possible values: - customer: The contact has a customer role. - technician: The contact has a technician role. Data type: String Table: Contact \[customer\_contact\]
relatedPlace	Required. List of the locations related to the appointment.Data type: Array of Objects `"relatedPlace": [ { "@referredType": "String", "id": "String", "name": "String", "role": "String" } ]`
relatedPlace.@referredType	Required. Type of location. For example, City.Data type: String Table: Locations \[cmn\_location\]
relatedPlace.id	Required. Sys\_id of the related location.Data type: String Table: Locations \[cmn\_location\]
relatedPlace.name	Name of the location related to the contact. For example, 251 Reddy St, Darwin, CA 93522.Data type: String Table: Locations \[cmn\_location\]
relatedPlace.role	Required. Description of the location role. For example, work order.Data type: String
timeZone	Required. Time zone to use when booking the specified appointment slot.Date type: String Format: Country/city or area format, such as US/Eastern
validFor	Required. Date range the appointment is valid for.Data type: Object `"validFor": { "endDateTime": "String", "startDateTime": "String" }`
validFor.endDateTime	Required. End date and time of the time slot. Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
validFor.startDateTime	Required. Start date and time of the time slot. Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.

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.

Header	Description
Accept	Data format of the response body. Only supports application/json.

Header	Description
Content-Type	Data format of the request body. Only supports application/json.

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.

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.

Response body parameters

Name	Description
category	Sys\_id of the record producer configured for the appointment booking service configuration. Data type: String Stored in: Catalog Item field of the Appointment Booking Service Configuration \[sn\_apptmnt\_booking\_service\_config\] table.
creationDate	Date and time that the appointment was created.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
href	Hyperlink to the appointment record. Use this link in another Appointment Open API request to reschedule or delete the appointment.Data type: String
id	Sys\_id of the appointment.Data type: String Stored in: Appointment Booking Service Configuration \[sn\_apptmnt\_booking\_service\_config\] table
lastUpdate	Date and time the appointment was last updated.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
relatedEntity	Details about the related entity of the appointment.Data type: Array of Objects `"relatedEntity": [ { "@referredType": "String", "id": "String", "role": "String" } ]`
relatedEntity.@referredType	Type of item or service.Data type: String Stored in: workOrder \[wm\_order\] table
relatedEntity.id	Sys\_id of the related entity.Data type: String Stored in: workOrder \[wm\_order\] table
relatedEntity.role	Role description of the related entity. Possible value: work order Data type: String Stored in: workOrder \[wm\_order\] table
relatedParty	List of contacts for the appointment. Each contact is an object in the array.Data type: Array of Objects `"relatedParty": [ { "@referredType": "String", "id": "String", "name": " String", "role": "String" } ]`
relatedParty.@referredType	Type of customer.Data type: String Stored in: Contact \[customer\_contact\] table
relatedParty.id	Sys\_id of the customer contact associated with the work order.Data type: String Stored in: Contact \[customer\_contact\] table
relatedParty.name	Name of the customer contact.Data type: String Stored in: Contact \[customer\_contact\] table
relatedParty.role	Role of the customer contact.Possible values: - customer: The contact has a customer role. - technician: The contact has a technician role. Data type: String Stored in: Contact \[customer\_contact\] table
relatedPlace	Location details of the associated appointment.Data type: Object `"relatedPlace": { "@referredType": "String", "id": "String", "name": "String", "role": "String" }`
relatedPlace.@referredType	Geographic address of the appointment. Possible value: GeographicLocation. Data type: String Stored in: Location \[cmn\_location\] table
relatedPlace.id	Sys\_id of the location. Data type: String Stored in: Location \[cmn\_location\] table
relatedPlace.name	Name of the location related to the contact. For example, 100 South Charles Street, Baltimore, MD.Data type: String Stored in: Location \[cmn\_location\] table
relatedPlace.role	Role of the appointment location as an intervention address.Possible value: InterventionAddress Data type: String Stored in: Location \[cmn\_location\] table
success	Flag that indicates whether the request was successful.Possible values: - true: Request succeeded. - false: Request failed. Data type: Boolean
timeZone	Time zone used when booking or updating the specified appointment slot.Date type: String Format: Country/city or area format, such as US/Eastern
validFor	Date range that the appointment is valid for.Data type: Object `"validFor": { "endDateTime": "String" "startDateTime": "String" }`
validFor.endDateTime	End date and time of the appointment.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.
validFor.startDateTime	Start date and time of the appointment.Data type: String Format: YYYY-MM-DD 00:00:00. For example, 2025-01-31 09:35:43.

cURL request

The following example shows how to create a new appointment booking.

curl "https://instance.servicenow.com/api/sn_tmf_api/appointment/appointment" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"validFor\": {
    \"startDateTime\": \"2024-08-19 09:00:00\",
    \"endDateTime\": \"2024-08-19 11:00:00\"
  },
  \"category\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
  \"relatedParty\": [
    {
      \"id\": \"eaf68911c35420105252716b7d40ddde\",
      \"name\": \"Sally Thomas\",
      \"role\": \"customer\",
      \"@referredType\": \"Individual\"
    }
  ],
  \"relatedPlace\": {
    \"id\": \"25ab9c4d0a0a0bb300f7dabdc0ca7c1c\",
    \"name\": \"100 South Charles Street, Baltimore,MD\",
    \"role\": \"interventionAddress\",
    \"@referredType\": \"GeographicAddress\"
  },
  \"relatedEntity\": [
    {
      \"id\": \"48dbfbf9201f0250f877303e8a020dcd\",
      \"role\": \"work order\",
      \"@referredType\": \"WorkOrder\"
    }
  ],
  \"timeZone\": \"US/Arizona\"
}" \
--user 'username':'password'

Response:

{
  "validFor": {
    "startDateTime": "2024-07-19 09:00:00",
    "endDateTime": "2024-07-19 11:00:00"
  },
  "category": "e4c1116b3b810300ce8a4d72f3efc40f",
  "relatedParty": [
    {
      "id": "eaf68911c35420105252716b7d40ddde",
      "name": "Sally Thomas",
      "role": "customer",
      "@referredType": "Individual"
    }
  ],
  "relatedPlace": {
    "id": "25ab9c4d0a0a0bb300f7dabdc0ca7c1c",
    "name": "100 South Charles Street, Baltimore,MD",
    "role": "interventionAddress",
    "@referredType": "GeographicAddress"
  },
  "relatedEntity": [
    {
      "id": "48dbfbf9201f0250f877303e8a020dcd",
      "role": "work order",
      "@referredType": "WorkOrder"
    }
  ],
  "timeZone": "US/Arizona",
  "success": true,
  "id": "feacb7f9201f0250f877303e8a020d38",
  "href": "api/sn_tmf_api/appointment/appointment/feacb7f9201f0250f877303e8a020d38",
  "creationDate": "2024-07-10 22:45:01",
  "lastUpdate": "2024-07-10 22:45:01"
}