The Change Management API provides endpoints that enable third-party application integration with the ServiceNow Change Management process.

By integrating your application with the ServiceNow Change Management process, all change requests, regardless of where they are initiated, have a single source of truth, providing a single audit source.

Use this REST API to integrate your change management process with external applications and when developing ServiceNow client-side applications.

This REST API enables integrators to:

  • Initiate a standard change request from a published standard change request template.
  • Create a change request of type emergency or normal.
  • Update any field that exists in the change request table for any change request.
  • Update any field that exists in the change task table and work tasks from creation through closure/cancellation.
  • Retrieve a specific change request, standard template, change request task, or change model.
  • Retrieve multiple change requests, standard templates, change request tasks using pagination.
  • Perform risk evaluation.
  • Refresh impacted services.
  • Generate and process any related approval activity associated with a change request.
  • Identify potential scheduling conflicts and identify periods where conflicts do not exist.
  • Delete change requests, change request tasks, and conflict checking processes.
  • Create a change request record based on a change model record.
  • Retrieves a list of available states for the specified change request, including the current state.
The Change Management API supports ITIL types and change models using Workflow Studio and Workflow. Change models deliver fit-for-purpose change. Types and models define transition criteria that must be met before the change request can progress to the next state. You can define this criteria using states, workflows, tools, and business rules.
  • Traditional ITIL types: Standard, Emergency, and Normal.
  • Change model states: New, Scheduled, Implement, Review, and Closed.

You can configure additional change models within your ServiceNow instance and then create change requests based on those change models using endpoints in this API. Use the Change Management - GET /sn_chg_rest/change/model/{sys_id} and Change Management - GET /sn_chg_rest/change/model endpoints to obtain the available change models in an instance. Then use the Change Management - POST /sn_chg_rest/change to create a change request based on a specified change model.

For information on configuring change models, see Configure Change Management.

The following roles are required to access the Change Management endpoints:
  • DELETE: change_manager or admin
  • GET: change_manager, itil, sn_change_read, or admin
  • PATCH/POST: change_manager, itil, or admin

In addition, administrators can set change properties to configure Change Management behavior. For a list of these properties and a description of their available functionality, see Change Management properties.

Change Management - DELETE /sn_chg_rest/change/{change_sys_id}/task/{task_sys_id}

Deletes the change request task identified by the specified sys_ids.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{change_sys_id}/task/{task_sys_id}

Default URL: /api/sn_chg_rest/change/{change_sys_id}/task/{task_sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 1. Path parameters
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
change_sys_id Sys_id of the change request to which the task is associated. Verifies that the task is actually associated to the specified change request.

Data type: String

Table: Change Request [change_request]
task_sys_id Sys_id of the change request task to delete.

Data type: String

Table: Change Tasks [change_task]
Table 2. Query parameters
Name Description
None
Table 3. Request body parameters (XML or JSON)
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.

Table 4. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 5. Response headers
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.

Table 6. Status codes
Status code Description
200 Successful. The request was successfully processed.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs All fields (key) with their associated values for the identified change request task prior to the delete.

Data type: Object
parent Information for the change request to which this task was associated.

Data type: Object

parent: {
  display_value: "String", 
  value: "String"
}
parent.display_value Sys_id of the parent task to display in a UI.

Data type: String
parent.value Sys_id of the parent task.

Data type: String
sys_id Sys_id information for the deleted change request.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request to display in a UI.

Data type: String
sys_id.value Sys_id of the change request.

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/0f4ac6c4b750230096c3e4f6ee11a9fe/task/12629ec4b750230096c3e4f6ee11a9d5" \
--request DELETE \
--header "Accept:application/json" \ 
--user "username":"password"
{
  result: [
    {
      sys_id: {
        value: "12629ec4b750230096c3e4f6ee11a9d5",
        display_value: "12629ec4b750230096c3e4f6ee11a9d5"
      },
      parent: {
        value: "0f4ac6c4b750230096c3e4f6ee11a9fe", 
        display_value: "CHG0033046 "
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Retire both nodes",
        display_value: "Retire both nodes"
      }
    }
  ]
}

Change Management - DELETE /sn_chg_rest/change/{sys_id}

Deletes the change request associated with the specified sys_id.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{sys_id}

Default URL: /api/sn_chg_rest/change/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 7. Path parameters
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
sys_id Sys_id of the change request record to delete.

Data type: String

Table: Change Request [change_request]
Table 8. Query parameters
Name Description
None
Table 9. Request body parameters (XML or JSON)
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.

Table 10. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 11. Response headers
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.

Table 12. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
result Change request record that was deleted. Each element in this object corresponds to a field in the record of the Change Request [change_request] table.

Data type: Object

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/b0dbda5347c12200e0ef563dbb9a718f" \
--request DELETE \
--header "Accept:application/json" \
--user "username":"password"

{
  "result":
    {
      "reason": {
        "display_value": "",
        "value": ""
      },
      "parent": {
        "display_value": "",
        "value": ""
      },
      "watch_list": {
        "display_value": "",
        "value": ""
       },
       "proposed_change": {
         "display_value": "",
         "value": ""
       },
       "upon_reject": {
         "display_value": "Cancel all future Tasks",
         "value": "cancel"
       },
       "sys_updated_on": {
         "display_value": "2015-07-06 11:59:27",
         "value": "2015-07-06 18:59:27",
         "display_value_internal": "2015-07-06 11:59:27"
      },
      "type": {
        "display_value": "Standard",
        "value": "standard"
      },
      "approval_history": {
        "display_value": "",
        "value": ""
      },
      "skills": {
        "display_value": "",
        "value": ""
      },
      "test_plan": {
        "display_value": "--Confirm that there are no monitoring alerts for the router",
        "value": "--Confirm that there are no monitoring alerts for the router"
      },
      "number": {
        "display_value": "CHG0000024",
        "value": "CHG0000024"
      },
      "is_bulk": {
        "display_value": "false",
        "value": false
      },
      "cab_delegate": {
        "display_value": "",
        "value": ""
      },
      "requested_by_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "ci_class": {
        "display_value": "cmdb_ci",
        "value": "cmdb_ci"
      },
      "state": {
        "display_value": "Closed",
        "value": 3.0
      },
      "sys_created_by": {
        "display_value": "admin",
        "value": "admin"
      },
      "knowledge": {
        "display_value": "false",
        "value": false
      },
      "order": {
        "display_value": "",
        "value": ""
      },
      "phase": {
        "display_value": "Requested",
        "value": "requested"
      },
      "cmdb_ci": {
        "display_value": "",
        "value": ""
      },
      "delivery_plan": {
        "display_value": "",
        "value": ""
      },
      "impact": {
        "display_value": "3 - Low",
        "value": 3.0
      },
      "contract": {
        "display_value": "",
        "value": ""
      },
      "active": {
        "display_value": "false",
        "value": false
      },
      "work_notes_list": {
        "display_value": "",
        "value": ""
      },
      "priority": {
        "display_value": "4 - Low",
        "value": 4.0
      },
      "sys_domain_path": {
        "display_value": "/",
        "value": "/"
      },
      "cab_recommendation": {
        "display_value": "",
        "value": ""
      },
      "production_system": {
        "display_value": "false",
        "value": false
      },
      "rejection_goto": {
        "display_value": "",
        "value": ""
      },
      "review_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "requested_by": {
        "display_value": "System Administrator",
        "value": "6816f79cc0a8016401c5a33be04be441"
      },
      "business_duration": {
        "display_value": "",
        "value": ""
      },
      "group_list": {
        "display_value": "",
        "value": ""
      },
      "change_plan": {
        "display_value": "",
        "value": ""
      },
      "approval_set": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "wf_activity": {
        "display_value": "",
        "value": ""
      },
      "implementation_plan": {
        "display_value": "-- Place router into maintenance mode in the monitoring platform\r\n-- Logon to router through SSH\r\n-- Run the following command\r\n\r\nrouter(config-router)#router bgp 12345\r\nrouter(config-router)#neighbor {neighbor ip} soft-reconfig [inbound]\r\nrouter#clear ip bgp {neighbor ip} soft in\r\n\r\n-- Confirm the sessions have been cleared\r\n-- Place router back into operational mode in the monitoring platform",
        "value": "-- Place router into maintenance mode in the monitoring platform\r\n-- Logon to router through SSH\r\n-- Run the following command\r\n\r\nrouter(config-router)#router bgp 12345\r\nrouter(config-router)#neighbor {neighbor ip} soft-reconfig [inbound]\r\nrouter#clear ip bgp {neighbor ip} soft in\r\n\r\n-- Confirm the sessions have been cleared\r\n-- Place router back into operational mode in the monitoring platform"
      },
      "universal_request": {
        "display_value": "",
        "value": ""
      },
      "end_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "short_description": {
        "display_value": "Reboot the server at 6 am",
        "value": "Reboot the server at 6 am"
      },
      "correlation_display": {
        "display_value": "",
        "value": ""
      },
      "work_start": {
        "display_value": "2015-07-06 11:56:04",
        "value": "2015-07-06 18:56:04",
        "display_value_internal": "2015-07-06 11:56:04"
      },
      "delivery_task": {
        "display_value": "",
        "value": ""
      },
      "outside_maintenance_schedule": {
        "display_value": "false",
        "value": false
      },
      "additional_assignee_list": {
        "display_value": "",
        "value": ""
      },
      "std_change_producer_version": {
        "display_value": "Clear BGP sessions on a Cisco router - 1",
        "value": "16c2273c47010200e90d87e8dee49006"
      },
      "sys_class_name": {
        "display_value": "Change Request",
        "value": "change_request"
      },
      "service_offering": {
        "display_value": "",
        "value": ""
      },
      "closed_by": {
        "display_value": "System Administrator",
        "value": "6816f79cc0a8016401c5a33be04be441"
      },
      "follow_up": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "review_status": {
        "display_value": "",
        "value": ""
      },
      "reassignment_count": {
        "display_value": "2",
        "value": 2.0
      },
      "start_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "assigned_to": {
        "display_value": "",
        "value": ""
      },
      "variables": {
        "display_value": "variable_pool",
        "value": "variable_pool"
      },
      "sla_due": {
        "display_value": "UNKNOWN",
        "value": "",
        "display_value_internal": ""
      },
      "comments_and_work_notes": {
        "display_value": "",
        "value": ""
      },
      "escalation": {
        "display_value": "Normal",
        "value": 0.0
      },
      "upon_approval": {
        "display_value": "Proceed to Next Task",
        "value": "proceed"
      },
      "correlation_id": {
        "display_value": "",
        "value": ""
      },
      "made_sla": {
        "display_value": "true",
        "value": true
      },
      "backout_plan": {
        "display_value": "Due to the limited number of commands in the implementation plan it is not possible to backout the change.\r\n\r\nIf required you are authorized to reboot the router if BGP fails to work",
        "value": "Due to the limited number of commands in the implementation plan it is not possible to backout the change.\r\n\r\nIf required you are authorized to reboot the router if BGP fails to work"
      },
      "conflict_status": {
        "display_value": "Not Run",
        "value": "Not Run"
      },
      "task_effective_number": {
        "display_value": "CHG0000024",
        "value": "CHG0000024"
      },
      "sys_updated_by": {
        "display_value": "admin",
        "value": "admin"
      },
      "opened_by": {
        "display_value": "System Administrator",
        "value": "6816f79cc0a8016401c5a33be04be441"
      },
      "user_input": {
        "display_value": "",
        "value": ""
      },
      "sys_created_on": {
        "display_value": "2015-07-06 11:55:46",
        "value": "2015-07-06 18:55:46",
        "display_value_internal": "2015-07-06 11:55:46"
      },
      "on_hold_task": {
        "display_value": "",
        "value": ""
      },
      "sys_domain": {
        "display_value": "global",
        "value": "global"
      },
      "route_reason": {
        "display_value": "",
        "value": ""
      },
      "closed_at": {
        "display_value": "2015-07-06 11:56:23",
        "value": "2015-07-06 18:56:23",
        "display_value_internal": "2015-07-06 11:56:23"
      },
      "review_comments": {
        "display_value": "",
        "value": ""
      },
      "business_service": {
        "display_value": "",
        "value": ""
      },
      "time_worked": {
        "display_value": "",
        "value": ""
      },
      "chg_model": {
        "display_value": "",
        "value": ""
      },
      "expected_start": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "opened_at": {
        "display_value": "2015-06-09 11:55:46",
        "value": "2015-06-09 18:55:46",
        "display_value_internal": "2015-06-09 11:55:46"
      },
      "work_end": {
        "display_value": "2015-07-06 11:56:10",
        "value": "2015-07-06 18:56:10",
        "display_value_internal": "2015-07-06 11:56:10"
      },
      "phase_state": {
        "display_value": "Open",
        "value": "open"
      },
      "cab_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "work_notes": {
        "display_value": "",
        "value": ""
      },
      "close_code": {
        "display_value": "Successful",
        "value": "successful"
      },
      "assignment_group": {
        "display_value": "Network",
        "value": "287ebd7da9fe198100f92cc8d1d2154e"
      },
      "description": {
        "display_value": "Resend the complete BGP table to neighboring routers\r\n\r\n--Both neighbors need to support soft reset route refresh capability.\r\n--Stores complete BGP table of you neighbor in router memory.\r\n--Not a good idea on a peering router with full feed, due to the memory requirements.\r\n",
        "value": "Resend the complete BGP table to neighboring routers\r\n\r\n--Both neighbors need to support soft reset route refresh capability.\r\n--Stores complete BGP table of you neighbor in router memory.\r\n--Not a good idea on a peering router with full feed, due to the memory requirements.\r\n"
      },
      "on_hold_reason": {
        "display_value": "",
        "value": ""
      },
      "calendar_duration": {
        "display_value": "",
        "value": ""
      },
      "close_notes": {
        "display_value": "Completed without issues",
        "value": "Completed without issues"
      },
      "sys_id": {
        "display_value": "b0dbda5347c12200e0ef563dbb9a718f",
        "value": "b0dbda5347c12200e0ef563dbb9a718f"
      },
      "contact_type": {
        "display_value": "Phone",
        "value": "phone"
      },
      "cab_required": {
        "display_value": "false",
        "value": false
      },
      "urgency": {
        "display_value": "3 - Low",
        "value": 3.0
      },
      "scope": {
        "display_value": "Medium",
        "value": 3.0
      },
      "company": {
        "display_value": "",
        "value": ""
      },
      "justification": {
        "display_value": "",
        "value": ""
      },
      "activity_due": {
        "display_value": "UNKNOWN",
        "value": "",
        "display_value_internal": ""
      },
      "comments": {
        "display_value": "",
        "value": ""
      },
      "approval": {
        "display_value": "Approved",
        "value": "approved"
      },
      "due_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "sys_mod_count": {
        "display_value": "10",
        "value": 10.0
      },
      "on_hold": {
        "display_value": "false",
        "value": false
      },
      "sys_tags": {
        "display_value": "",
        "value": ""
      },
      "conflict_last_run": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "risk_value": {
        "display_value": "",
        "value": ""
      },
      "unauthorized": {
        "display_value": "false",
        "value": false
      },
      "risk": {
        "display_value": "Moderate",
        "value": 3.0
      },
      "location": {
        "display_value": "",
        "value": ""
      },
      "category": {
        "display_value": "Other",
        "value": "Other"
      },
      "risk_impact_analysis": {
        "display_value": "",
        "value": ""
      }
    }
}

Change Management - DELETE /sn_chg_rest/change/{sys_id}/conflict

Cancels the running conflict checking process for the specified change request (sys_id).

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{sys_id}/conflict

Default URL: /api/sn_chg_rest/change/{sys_id}/conflict

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 13. Path parameters
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
sys_id Sys_id of the change request record for which to cancel the running conflict checking process.

Data type: String

Table: Change Request [change_request]
Table 14. Query parameters
Name Description
None
Table 15. Request body parameters (XML or JSON)
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.

Table 16. Request headers
Header Description
None
Table 17. Response headers
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.

Table 18. Status codes
Status code Description
200 Successful. The request was successfully processed.
400 Bad request. Cancel request failed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Name Description
None

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/0f4ac6c4b750230096c3e4f6ee11a9fe/conflict" \
--request DELETE \
--user "username":"password"

None

Change Management - DELETE /sn_chg_rest/change/emergency/{sys_id}

Deletes the emergency change request identified by the specified sys_id.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/emergency/{sys_id}

Default URL: /api/sn_chg_rest/change/emergency/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 19. Path parameters
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
sys_id Sys_id of the emergency change request to delete.

Data type: String

Table: Change Request [ change_request]
Table 20. Query parameters
Name Description
None
Table 21. Request body parameters (XML or JSON)
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.

Table 22. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 23. Response headers
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.

Table 24. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs Values for all fields in the associated change request.

Data type: Object
state State of the change request prior to the delete.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in the UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Sys_id information for the change request.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request to display in a UI.

Data type: String
sys_id.value Sys_id of the change request.

Data type: String
type Type of change request.

Data type: Object

type: {
  display_value: "String",
  value: "String"
}
type.display_value Change type to display in a UI.

Value is always "Emergency".

Data type: String
type.value Internal type value.

Value is always "emergency".

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/emergency/b0dbda5347c12200e0ef563dbb9a718f" \
--request DELETE \
--header "Accept:application/json" \
--user "username":"password"

{
  result: [
    {
      sys_id: {
        value: "b0dbda5347c12200e0ef563dbb9a718f", 
        display_value: "b0dbda5347c12200e0ef563dbb9a718f"
      },
      state: {
        value: "-5", 
        display_value: "New"
      },
      type: {
        value: "emergency",
        display_value: "Emergency"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Remove server",
        display_value: "Remove server"
      },
    }, 
  ]
}

Change Management - DELETE /sn_chg_rest/change/normal/{sys_id}

Deletes the normal change request identified by the specified sys_id.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/normal/{sys_id}

Default URL: /api/sn_chg_rest/change/normal/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 25. Path parameters
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
sys_id Sys_id of the normal change request to delete.

Data type: String

Table: Change Request [change_request]
Table 26. Query parameters
Name Description
None
Table 27. Request body parameters (XML or JSON)
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.

Table 28. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 29. Response headers
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.

Table 30. Status codes
Status code Description
200 Successful. The request was successfully processed.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs Values for all fields in the associated change request.

Data type: Object
state State of the change request prior to the delete.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in the UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Sys_id of the change request.

Data type: String
type Type of change request.

Data type: Object

type: {
  display_value: "String",
  value: "String"
}
type.display_value Change type to display in the UI.

Value is always "Normal".

Data type: String
type.value Internal type value.

Value is always "normal".

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/normal/b0dbda5347c12200e0ef563dbb9a718f" \
--request DELETE \
--header "Accept:application/json" \
--user "username":"password"

{
  result: [
    {
      sys_id: "b0dbda5347c12200e0ef563dbb9a718f",
      state: {
        value: "-5", 
        display_value: "New"
      },
      type: {
        value: "normal",
        display_value: "Normal"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Remove server",
        display_value: "Remove server"
      },
    }, 
  ]
}

Change Management - DELETE /sn_chg_rest/change/standard/{sys_id}

Deletes the standard change request identified by the specified sys_id.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/standard/{sys_id}

Default URL: /api/sn_chg_rest/change/standard/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 31. Path parameters
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
sys_id Sys_id of the standard change request to delete.

Data type: String

Table: Change Request [change_request]
Table 32. Query parameters
Name Description
None
Table 33. Request body parameters (XML or JSON)
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.

Table 34. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 35. Response headers
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.

Table 36. Status codes
Status code Description
200 Request completed successfully.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs All fields (key) with their associated values for the identified change request.
state State of the change request prior to the delete.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in the UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Unique identifier of the change request.

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/standard/1c87925347c12200e0ef563dbb9a7177" \
--request DELETE \
--header "Accept:application/json" \
--user "username":"password"

{
  result: [
    {
      sys_id: "1c87925347c12200e0ef563dbb9a7177",
      state: {
        value: "-5", 
        display_value: "New"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Add network switch to cabinet",
        display_value: "Add network switch to cabinet"
      },
    }, 
  ]
}

Change Management - GET /sn_chg_rest/change/ci/{cmdb_ci_sys_id}/schedule

Enables retrieving available time slots by configuration item ID and duration, with an option to include planned start time.

Role required: sn_change_writer.

Note: Running this endpoint doesn't list the available start and end times. Use the link provided in the response body worker.link property to get the schedule data.
See also:

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/ci/{cmdb_ci_sys_id}/schedule

Default URL: /api/sn_chg_rest/change/ci/{cmdb_ci_sys_id}/schedule

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 37. Path parameters
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
cmdb_ci_sys_id Sys_id of the configuration item record. This endpoint doesn't require a change request.

Data type: String

Table: Configuration Items [cmdb_ci]
Table 38. Query parameters
Name Description
duration_in_seconds Duration of change in seconds, that is, how much time is required to complete the change request task.

Data type: Integer
planned_start_time Optional. Date and time that the change request is planned to start implementation in UTC.

Retrieve the available time slot start at or later than this time. If not provided, the system uses the current time as the start time.

Format: yyyy-mm-dd hh:mm:ss

Data type: String
Table 39. Request body parameters (XML or JSON)
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.

Table 40. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 41. Response headers
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.

Table 42. Status codes
Status code Description
202 System accepted the request.
400 Bad Request. A bad request type or malformed request was detected.
Possible issues:
  • Can't find the cmdb_ci with the provided sys_id. The record either doesn't exist the or the user doesn't have read access to it.
  • The duration_in_seconds query parameter value wasn't provided.
  • Invalid duration_in_seconds or planned_start_time query parameter value provided.

Response body parameters (JSON or XML)

Name Description
error Information on any errors encountered while processing the endpoint request.

Data type: Object

"error": {
  "detail": "String",
  "message": "String",
  "status": "String"
}
error.detail Additional information about the error.

Data type: String
error.message Message that identifies the error.

Data type: String
messages Message information.
Data type: Object
"messages": {
  "errorMessages": [Array],
  "infoMessages": [Array],
  "warningMessages": [Array]
}
messages.errorMessages Error messages encountered while processing the request.

Data type: Array
messages.infoMessages Information messages encountered while processing the request.

Data type: Array
messages.warningMessages Warning messages encountered while processing the request.

Data type: Array
request Original endpoint request.

Data type: String
state Information on the current state of the worker.

Data type: Object

state: {
  display_value: "String", 
  value: Number
}
state.display_value Display value of the state of the worker. These values directly correlate to the state.value parameter.

Possible values:

  • Complete
  • Error
  • In-Progress
  • Waiting

Data type: String
state.value Numeric value of the state of the worker.

Possible values:

  • 1
  • 2
  • 3
  • 4

Data type: Number
type Type of request.

Valid value: schedule

Data type: String
worker Information about the associated worker.

Data type: Object

"worker": {
  "link": "String",
  "sysId": "String"
}
worker.link Link for retrieving time slot data. Use the sys_id in GET /sn_chg_rest/change/worker/{sys_id} to view results.

Data type: String
worker.sysId Sys_id of the worker associated with the change request.

Data type: String
status Only appears if an error is encountered. Status of the endpoint processing.

Possible value: failure

Data type: String

Get available time slots

Use the value provided in the worker.link to get schedule window details. The value is in the following format:

https://instance.service-now.com/api/sn_chg_rest/change/worker/<worker_sys_id>

Use the worker_sys_id in GET /sn_chg_rest/change/worker/{sys_id} to view results.

The response body contains the status and provides results when processing is complete.

Worker response body parameter results vary depending on time slot availability.
  • If the provided time slot is available for the change request within the schedule time slot, the worker API lists the available time slots in the payload.spans property. The payload.spans property isn't listed in the results otherwise.
  • If there are no time slots available for change request duration provided within the defined scheduling time slot, the messages.infoMessages states the following: D
    Note: The change request scheduling time slot default value is 90 days. To change this value, modify the change.conflict.next_available.schedule_window property. For more information, see Configure conflict analysis properties.

The following GET /sn_chg_rest/change/worker/{sys_id} example shows output provided using the ID provided in the worker.link detail. The results list open time spans available for the task duration.

{
  "result": {
    "worker": {
      "sysId": "d7d1f2b4a444b010f87712198fe9caae",
      "link": "https://instance.service-now.com/api/sn_chg_rest/change/worker/d7d1f2b4a444b010f87712198fe9caae"
    },
    "request": "{\"cmdb_ci_sys_id\":\"82967cdd0ad3370236092104ce988d76\",\"planned_start_time\":\"\",\"duration_in_seconds\":10800,\"timezone\":\"America/Los_Angeles\"}",
    "state": {
      "value": 3,
      "display_value": "Complete"
    },
    "type": "schedule",
    "messages": {
      "errorMessages": [],
      "warningMessages": [],
      "infoMessages": []
    },
    "payload": {
      "spans": [
        {
          "start": {
            "value": "2021-05-15 08:00:00",
            "display_value": "2021-05-15 01:00:00"
          },
          "end": {
            "value": "2021-05-15 11:00:00",
            "display_value": "2021-05-15 04:00:00"
          }
        },
        {
          "start": {
            "value": "2021-05-22 08:00:00",
            "display_value": "2021-05-22 01:00:00"
          },
          "end": {
            "value": "2021-05-22 11:00:00",
            "display_value": "2021-05-22 04:00:00"
          }
        },
        ...
      ]
    }
  }
}

Example: cURL request

curl "https://instance.service-now.com/api/sn_chg_rest/change/ci/<cmdb_ci_sys_id>/schedule?duration_in_seconds=10800" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

Results include worker.link details you can use to run the provided sys_id in the GET /sn_chg_rest/change/worker/ endpoint.

{
  "result": {
    "worker": {
      "sysId": "1049419c1b4c3010f58a6572604bcb7a",
      "link": "https://instance.service-now.com/api/sn_chg_rest/change/worker/1049419c1b4c3010f58a6572604bcb7a"
    },
    "request": "{\"cmdb_ci_sys_id\":\"<cmdb_ci_sys_id>\",\"planned_start_time\":\"\",\"duration_in_seconds\":10800,\"timezone\":\"America/Los_Angeles\"}",
    "state": {
      "value": 1,
      "display_value": "Waiting"
    },
    "type": "schedule",
    "messages": {
      "errorMessages": [],
      "warningMessages": [],
      "infoMessages": []
    }
  }
}

Change Management - GET /sn_chg_rest/change

Retrieves one or more change requests based on the specified criteria.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change

Default URL: /api/sn_chg_rest/change

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 43. Path parameters
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 44. Query parameters
Name Description
name-value pairs Name-value pairs to use to filter the result set. The name is the field on which the specified value is filtered. This parameter is mutually exclusive with sysparm_query. For example, instead of using &sysparm_query=active=true, you can simplify the calling statement by using &active=true. You can also use the display value when the field is a choice or reference type field, such as &state=closed instead of &state=7. To specify multiple key-value pairs, separate each with an ampersand, such as &active=true&assigned_to=john.smith.

Data type: String
order Field by which to sort the returned change requests.

Data type: String

Default: name
sysparm_offset Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks.

For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use sysparm_offset=sysparm_offset+sysparm_limit, until you reach the end of all records.

Don't pass a negative number in the sysparm_offset parameter.

Data type: Number

Default: 0
sysparm_query Encoded query used to filter the result set. You can use a UI filter to obtain a properly encoded query.
Syntax: sysparm_query=<col_name><operator><value>.
  • <col_name>: Name of the table column to filter against.
  • <operator>: Supports the following values:
    • =: Exactly matches <value>.
    • !=: Does not match <value>.
    • ^: Logically AND multiple query statements.
    • ^OR: Logically OR multiple query statements.
    • LIKE: <col_name> contains the specified string. Only works for <col_name> fields whose data type is string.
    • STARTSWITH: <col_name> starts with the specified string. Only works for <col_name> fields whose data type is string.
    • ENDSWITH: <col_name> ends with the specified string. Only works for <col_name> fields whose data type is string.
    <value>: Value to match against.
For more operators, see Operators available for filters and queries.

All parameters are case-sensitive. Queries can contain more than one entry, such as sysparm_query=<col_name><operator><value>[<operator><col_name><operator><value>].

For example:

(sysparm_query=caller_id=javascript:gs.getUserID()^active=true)

Encoded queries also support order by functionality. To sort responses based on certain fields, use the ORDERBY and ORDERBYDESC clauses in sysparm_query.

Syntax:
  • ORDERBY<col_name>
  • ORDERBYDESC<col_name>

For example: sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory

This query filters all active records and orders the results in ascending order by number, and then in descending order by category.

If part of the query is invalid, such as by specifying an invalid field name, the instance ignores the invalid part. It then returns rows using only the valid portion of the query. You can control this behavior using the property glide.invalid_query.returns_no_rows. Set this property to true to return no rows on an invalid query.
Note: The glide.invalid_query.returns_no_rows property controls the behavior of all queries across the instance, such as in lists, scripts (GlideRecord.query()), and web service APIs.

Data type: String
textSearch String to use to search all normal change request record fields. This search uses ServiceNow full text search platform functionality. For more information on ServiceNow search capabilities, see Search administration.

Default: IR_AND_OR_QUERY
Table 45. Request body parameters (XML or JSON)
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.

Table 46. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 47. Response headers
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.

Table 48. Status codes
Status code Description
200 Request completed successfully.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Element Description
result List containing one or more change request record objects. Each object describes a change request. Each element in the change request object corresponds to a field in its associated record in the Change Request [change_request] table.

All elements contain value and display_value name-value pairs. Date fields also contain display_value_internal name-value pairs.

Data type: Array
action_status Current action status of the associated change request.

Possible values:

  • 1: Blocked internally
  • 2: Blocked by customer
  • 3: Blocked internally and by customer
  • 4: Needs attention

Data type: Number
active Flag that indicates whether the change request is active.

Possible values:

  • true: Change request is active
  • false: Change request isn't active

Data type: Boolean

Default: true
activity_due Date and time for which the associated case is expected to be completed.

Data type: String
additional_assignee_list List of sys_ids of additional persons assigned to work on the change request.

Data type: Array
approval Type of approval process required.

Data type: String

Default: not requested
approval_history Most recent approval history journal entry.

Data type: String
approval_set Date and time that the associated action was approved.

Data type: String
assigned_to Sys_id of the user assigned to the change request.

Data type: String
assignment_group Sys_id of the group assigned to the change request.

Data type: String
backout_plan Description of the plan to execute if the change must be reversed.

Data type: String
business_duration Length in scheduled work hours, work days, and work weeks that it took to complete the change.

Data type: String
business_service Sys_id of the business service associated with the change request. Located in the Service [cmdb_ci_service] table.

Data type: String
cab_date Date on which the Change Advisory Board (CAB) meets.

Data type: String
cab_delegate Sys_id of the user that can substitute for the CAB manager during a CAB meeting. Located in the User [sys_user] table

Data type: String
cab_recommendation Description of the CAB recommendations for the change request.

Data type: String

Maximum length: 4,000
cab_required Flag that indicates whether the CAB is required.
Possible values:
  • true: Change Advisory Board is required.
  • false: Change Advisory Board isn't required.

Data type: Boolean

Default: false
calendar_duration Not currently used by Change Management.

Data type: String
category Category of the change, for example hardware, network, or software.

Data type: String

Default: Other
change_plan Activities and roles for managing and controlling the change request.

Data type: String
chg_model Sys_id of the change model that the associated change request was based on. The Change Model defines the state flow, transitions, and process activities that must be completed for the change request.

Data type: String

Table: Change Model [chg_model]
closed_at Date and time that the associated change request was closed.

Data type: String
closed_by Sys_id of the person that closed the change request.

Data type: String

Table: User [sys_user]
close_code Code assigned to the change request when it was closed. For example, Successful, Successful with issues, and Unsuccessful.

Data type: String
close_notes Notes that the person entered when closing the change request.

Data type: String
cmdb_ci Sys_id of the configuration item associated with the change request.

Data type: String

Table: Configuration Item [cmdb_ci]
comments List of customer-facing work notes entered in the associated change request.

Data type: Array
comments_and_work_notes List of both internal and customer-facing work notes entered for the associated change request.

Data type: Array

Maximum length: 4,000
company Sys_id of the company associated with the change request.

Data type: String

Table: Company [core_company]
conflict_last_run Date and time that the conflict detection script was last run on the change request.

Data type: String
conflict_status Current conflict status as detected by the conflict detection script, such as Conflict and Not Run.

Data type: String

Maximum length: 40

Default: Not Run
contact_type Method in which the change request was initially requested.
Possible values:
  • chat
  • email
  • phone
  • social
  • web

Data type: String
contract Sys_id of the contract associated with the change request.

Data type: String

Table: Contract [ast_contract]
correlation_display User-friendly name for the correlation_id.

Data type: String

Maximum length: 100
correlation_id Globally unique ID (GUID) of a matching change request record in a third-party system.

Data type: String

Maximum length: 100
delivery_plan No longer in use. Sys_id of the delivery plan associated with the change request.

Data type: String

Table: Execution Plan [sc_cat_item_delivery_plan]
delivery_task No longer in use. Sys_id of the delivery task associated with the change request.

Data type: String

Table: Execution Plan Task [sc_cat_item_delivery_task]
description Detailed description of the change request.

Data type: String

Maximum length: 4,000
due_date Task due date. Not used by change request process.

Data type: String
end_date Date and time when the change request is to be completed.

Data type: String
escalation Current escalation level.

Possible values:

  • 0: Normal
  • 1: Moderate
  • 2: High
  • 3: Overdue

Data type: Number (Integer)

Default: 0
expected_start Date and time when the task is to start. Not used by the change request process.

Data type: String
follow_up Date and time when a user followed-up with the person requesting the change request.

Data type: String
group_list List of sys_ids and names of the groups associated with the change request.

Data type: Array

Maximum length: 4,000
impact Impact on the change request will have on the customer.

Possible values:

  • 1: High
  • 2: Medium
  • 3: Low

Data type: Number (Integer)

Default: 3
implementation_plan Sequential steps to execute to implement this change. It also contains any dependencies between steps and assignee details for each step.

Data type: String

Maximum length: 4,000
justification Benefits of implementing this change and the impact if this change is not implemented.

Data type: String

Maximum length: 4,000
knowledge Flag that indicates whether there are any knowledge base ()KB) articles associated with the change request.
Possible values:
  • true: Associated KB articles
  • false: No associated KB articles

Data type: Boolean
location Sys_id and name of the location of the equipment referenced in the change request.

Data type: String

Table: Location [cmn_location]
made_sla No longer used. Flag that indicates whether the change request was implemented in alignment with the associated service level agreement.

Data type: Boolean
needs_attention Flag that indicates whether the change request needs attention.

Possible values:

  • true: Change request needs additional attention.
  • false: Change request doesn't need additional attention.

Data type: Boolean

Default: false
number Change number assigned to the change request by the system, such as CHG0040007.

Data type: String
on_hold Flag that indicates whether the change request is currently on hold.
Possible values:
  • true: On hold
  • false: Not on hold

Data type: Boolean

Default: false
on_hold_reason If the on_hold parameter is "true", description of the reason why the change request is being held up.

Data type: String

Maximum length: 4,000
on_hold_task If the on_hold parameter is "true", list of the sys_ids of the tasks that must be completed before the hold is released.

Data type: String

Maximum length: 4,000
opened_at Date and time that the change release was created.

Data type: String
opened_by Sys_id and name of the user that created the change release.

Data type: String

Table: User [sys_user]
order Not used by Change Management. Optional numeric field by which to order records, such as when retrieving them from a database.

Data type: Number (Integer)
outside_maintenance_schedule Flag that indicates whether maintenance by an outside company has been schedule for the change request.
Possible values:
  • true: Outside maintenance scheduled
  • false: No outside maintenance scheduled

Data type: Boolean

Default: false
parent Sys_id and name of the parent task to this change request, if any.

Data type: String

Table: Task [task]
phase Current phase of the change request. This defines what the change is doing in greater detail.
Possible values:
  • accept
  • build
  • plan
  • requested

Data type: String
phase_state Change_phase records that should be created for a change. They are dependent on the category, such that each type of change may have different change_phase records. The change_phase records provide an opportunity to control the approval process as each change_phase can have a schedule and a set of approvers.
Possible values:
  • complete
  • on hold
  • open
  • rejected
  • requested
  • work in progress

Data type: String
priority Priority of the change request.
Possible values:
  • 1: Critical
  • 2: High
  • 3: Moderate
  • 4: Low

Data type: Number (Integer)

Default: 4
production_system Flag that indicates whether the change request is for a ServiceNow instance that is in a production environment.
Possible values:
  • true: Production environment
  • false: Non-production environment

Data type: Boolean
reason Description of why the change request was initiated.
Possible values:
  • Business requirements
  • Hardware upgrade
  • Legislation
  • Location change
  • Network requirements
  • New or removed CI
  • Other
  • Problem resolved
  • Product or service changed
  • Software upgrade
  • User requested

Data type: String

Maximum length: 40
reassignment_count Number of times that the change request has been reassigned to a new owner.

Data type: Number (Integer)

Default: 0
rejection_goto Sys_id of the task to perform if the change request is rejected.

Data type: String

Table: Task [task]
requested_by Sys_id of the user that requested the change.

Data type: String

Table: User [sys_user]
requested_by_date Date and time when the change is requested to be implemented by.

Data type: String
review_comments Comments entered when the change request was reviewed.

Data type: String

Maximum length: 4,000
review_date Date that the change request was reviewed.

Data type: String
review_status Current status of the requested change request review.

Data type: String
risk Level of risk associated with the change request.
Valid values:
  • 1: High
  • 2: Moderate
  • 3: Low

Data type: Number

Default: 3
risk_impact_analysis Description of the risk and analysis of implementing the change request.

Data type: String

Maximum length: 4,000
route_reason Not currently used by Change Management. Reason that the change request was transferred.
Possible values:
  • 1: Transfer with Resolution
  • 9: Transfer without Resolutions

Data type: Number
scope Size of the change request.
Possible values:
  • 1: Massive
  • 2: Large
  • 3: Medium
  • 4: Small
  • 5: Tiny

Data type: Number

Default: 3
service_offering Sys_id of the service offering associated with the change request. Service offerings uniquely define the level of service in terms of availability, scope, pricing, and packaging options.

Data type: String

Table: Offering [service_offering]
short_description Description of the change request.

Data type: String

Maximum length: 40
skills List of the sys_ids of all of the skills required to implement the change request.

Data type: Array

Table: Skill [cmn_skill]
sla_due No longer in use. Date and time that the change request must be completed based on the associated service level agreement.

Data type: String
sn_esign_document Sys_id of any E-signed document attached to the change request.

Data type: String

Table: Attachment [sys_attachment]
sn_esign_esignature_configuration Sys_id of the E-signed signature template used for the associated document.

Data type: String

Table: E-signature Template [sn_esign_configuration]
start_date Date and time that the change request is planned to start implementation.

Data type: String
state Current state of the change request. Possible values are defined in the change model.

Data type: Number (Integer)

Default: 1
std_change_producer_version Sys_id of the record producer and change proposal associated with the change request. It also includes the number and percentage of successful and unsuccessful change requests created from the proposal.

Data type: String

Table: Standard Change Template Version [std_change_producer_version]
sys_class_name Name of the table in which the change request is located.

Data type: String
sys_created_by Name of the user that initially created the change request.

Data type: String

Maximum length: 40
sys_created_on Date and time that the associated change request record was originally created.

Data type: String
sys_domain If using domains in the instance, the name of the domain to which the change module record is associated.

Data type: String
sys_domain_path If using domains in the instance, the domain path in which the associated change module record resides.

Data type: String
sys_id Unique identifier of the associated change request record.

Data type: String
sys_mod_count Number of updates to the case since it was initially created.

Data type: Number (Integer)
sys_updated_by Person that last updated the case.

Data type: String

Maximum length: 40
sys_updated_on Date and time when the case was last updated.

Data type: String
task_effective_number Universal request number.

Data type: String

Maximum length: 40
task_for Not used by Change Management. Sys_id of the user that the task was created for.

Data type: String

Table: User [sys_user]
test_plan Description of the associated test plan for the change.

Data type: String

Maximum length: 4,000
time_worked Total amount of time worked on the change request.

Data type: String
type Change request type.
Possible values:
  • emergency
  • normal
  • standard

Data type: String

Maximum length: 40
unauthorized Flag that indicates whether the change request is unauthorized
Possible values:
  • true: Unauthorized
  • false: Authorized

Data type: Boolean
universal_request Sys_id of the Parent Universal request to which this change request is a part of.

Data type: String

Table: Task [task]
upon_approval Action to take if the change request is approved.

Possible values:

  • do_nothing
  • proceed

Data type: String

Maximum length: 40

Default: proceed
upon_reject Action to take if the change request is rejected.

Possible values:

  • cancel
  • goto

Data type: String

Maximum length: 40

Default: cancel
urgency Urgency of the change request.

Possible values:

  • 1: High
  • 2: Medium
  • 3: Low

Data type: Number (Integer)

Default: 3
user_input Additional user input.

Data type: String

Maximum length: 4,000
variables Name-value pairs of variables associated with the change request.

Data type: String

Maximum length: 40
watch_list List of sys_ids of the users who receive notifications about this change request when additional comments are added or if the state of a change request is changed to Resolved or Closed.

Data type: Array

Table: User [sys_user]
wf_activity Sys_id of the workflow activity record associated with the change request.

Data type: String

Table: Workflow Activity [wf_activity]
work_end Date and time work ended on the change request.

Data type: String
work_notes Information about how to resolve the change request, or steps taken to resolve it.

Data type: String

Maximum length: 4,000
work_notes_list List of sys_ids of the internal users who receive notifications about this change request when work notes are added.

Data type: Array

Table: User [sys_user]
work_start Date and time that work started on the change request.

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change?sysparm_query=active=true^ORDERBYnumber" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

For brevity, the results only contain a single change request record.

{
  "result": [
    {
      "reason": {
        "display_value": "",
        "value": ""
      },
      "parent": {
        "display_value": "",
        "value": ""
      },
      "watch_list": {
        "display_value": "",
        "value": ""
       },
       "proposed_change": {
         "display_value": "",
         "value": ""
       },
       "upon_reject": {
         "display_value": "Cancel all future Tasks",
         "value": "cancel"
       },
       "sys_updated_on": {
         "display_value": "2015-07-06 11:59:27",
         "value": "2015-07-06 18:59:27",
         "display_value_internal": "2015-07-06 11:59:27"
      },
      "type": {
        "display_value": "Standard",
        "value": "standard"
      },
      "approval_history": {
        "display_value": "",
        "value": ""
      },
      "skills": {
        "display_value": "",
        "value": ""
      },
      "test_plan": {
        "display_value": "--Confirm that there are no monitoring alerts for the router",
        "value": "--Confirm that there are no monitoring alerts for the router"
      },
      "number": {
        "display_value": "CHG0000024",
        "value": "CHG0000024"
      },
      "is_bulk": {
        "display_value": "false",
        "value": false
      },
      "cab_delegate": {
        "display_value": "",
        "value": ""
      },
      "requested_by_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "ci_class": {
        "display_value": "cmdb_ci",
        "value": "cmdb_ci"
      },
      "state": {
        "display_value": "Closed",
        "value": 3.0
      },
      "sys_created_by": {
        "display_value": "admin",
        "value": "admin"
      },
      "knowledge": {
        "display_value": "false",
        "value": false
      },
      "order": {
        "display_value": "",
        "value": ""
      },
      "phase": {
        "display_value": "Requested",
        "value": "requested"
      },
      "cmdb_ci": {
        "display_value": "",
        "value": ""
      },
      "delivery_plan": {
        "display_value": "",
        "value": ""
      },
      "impact": {
        "display_value": "3 - Low",
        "value": 3.0
      },
      "contract": {
        "display_value": "",
        "value": ""
      },
      "active": {
        "display_value": "false",
        "value": false
      },
      "work_notes_list": {
        "display_value": "",
        "value": ""
      },
      "priority": {
        "display_value": "4 - Low",
        "value": 4.0
      },
      "sys_domain_path": {
        "display_value": "/",
        "value": "/"
      },
      "cab_recommendation": {
        "display_value": "",
        "value": ""
      },
      "production_system": {
        "display_value": "false",
        "value": false
      },
      "rejection_goto": {
        "display_value": "",
        "value": ""
      },
      "review_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "requested_by": {
        "display_value": "System Administrator",
        "value": "6816f79cc0a8016401c5a33be04be441"
      },
      "business_duration": {
        "display_value": "",
        "value": ""
      },
      "group_list": {
        "display_value": "",
        "value": ""
      },
      "change_plan": {
        "display_value": "",
        "value": ""
      },
      "approval_set": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "wf_activity": {
        "display_value": "",
        "value": ""
      },
      "implementation_plan": {
        "display_value": "-- Place router into maintenance mode in the monitoring platform\r\n-- Logon to router through SSH\r\n-- Run the following command\r\n\r\nrouter(config-router)#router bgp 12345\r\nrouter(config-router)#neighbor {neighbor ip} soft-reconfig [inbound]\r\nrouter#clear ip bgp {neighbor ip} soft in\r\n\r\n-- Confirm the sessions have been cleared\r\n-- Place router back into operational mode in the monitoring platform",
        "value": "-- Place router into maintenance mode in the monitoring platform\r\n-- Logon to router through SSH\r\n-- Run the following command\r\n\r\nrouter(config-router)#router bgp 12345\r\nrouter(config-router)#neighbor {neighbor ip} soft-reconfig [inbound]\r\nrouter#clear ip bgp {neighbor ip} soft in\r\n\r\n-- Confirm the sessions have been cleared\r\n-- Place router back into operational mode in the monitoring platform"
      },
      "universal_request": {
        "display_value": "",
        "value": ""
      },
      "end_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "short_description": {
        "display_value": "Clear BGP sessions on a Cisco router",
        "value": "Clear BGP sessions on a Cisco router"
      },
      "correlation_display": {
        "display_value": "",
        "value": ""
      },
      "work_start": {
        "display_value": "2015-07-06 11:56:04",
        "value": "2015-07-06 18:56:04",
        "display_value_internal": "2015-07-06 11:56:04"
      },
      "delivery_task": {
        "display_value": "",
        "value": ""
      },
      "outside_maintenance_schedule": {
        "display_value": "false",
        "value": false
      },
      "additional_assignee_list": {
        "display_value": "",
        "value": ""
      },
      "std_change_producer_version": {
        "display_value": "Clear BGP sessions on a Cisco router - 1",
        "value": "16c2273c47010200e90d87e8dee49006"
      },
      "sys_class_name": {
        "display_value": "Change Request",
        "value": "change_request"
      },
      "service_offering": {
        "display_value": "",
        "value": ""
      },
      "closed_by": {
        "display_value": "System Administrator",
        "value": "6816f79cc0a8016401c5a33be04be441"
      },
      "follow_up": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "review_status": {
        "display_value": "",
        "value": ""
      },
      "reassignment_count": {
        "display_value": "2",
        "value": 2.0
      },
      "start_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "assigned_to": {
        "display_value": "",
        "value": ""
      },
      "variables": {
        "display_value": "variable_pool",
        "value": "variable_pool"
      },
      "sla_due": {
        "display_value": "UNKNOWN",
        "value": "",
        "display_value_internal": ""
      },
      "comments_and_work_notes": {
        "display_value": "",
        "value": ""
      },
      "escalation": {
        "display_value": "Normal",
        "value": 0.0
      },
      "upon_approval": {
        "display_value": "Proceed to Next Task",
        "value": "proceed"
      },
      "correlation_id": {
        "display_value": "",
        "value": ""
      },
      "made_sla": {
        "display_value": "true",
        "value": true
      },
      "backout_plan": {
        "display_value": "Due to the limited number of commands in the implementation plan it is not possible to backout the change.\r\n\r\nIf required you are authorized to reboot the router if BGP fails to work",
        "value": "Due to the limited number of commands in the implementation plan it is not possible to backout the change.\r\n\r\nIf required you are authorized to reboot the router if BGP fails to work"
      },
      "conflict_status": {
        "display_value": "Not Run",
        "value": "Not Run"
      },
      "task_effective_number": {
        "display_value": "CHG0000024",
        "value": "CHG0000024"
      },
      "sys_updated_by": {
        "display_value": "admin",
        "value": "admin"
      },
      "opened_by": {
        "display_value": "System Administrator",
        "value": "6816f79cc0a8016401c5a33be04be441"
      },
      "user_input": {
        "display_value": "",
        "value": ""
      },
      "sys_created_on": {
        "display_value": "2015-07-06 11:55:46",
        "value": "2015-07-06 18:55:46",
        "display_value_internal": "2015-07-06 11:55:46"
      },
      "on_hold_task": {
        "display_value": "",
        "value": ""
      },
      "sys_domain": {
        "display_value": "global",
        "value": "global"
      },
      "route_reason": {
        "display_value": "",
        "value": ""
      },
      "closed_at": {
        "display_value": "2015-07-06 11:56:23",
        "value": "2015-07-06 18:56:23",
        "display_value_internal": "2015-07-06 11:56:23"
      },
      "review_comments": {
        "display_value": "",
        "value": ""
      },
      "business_service": {
        "display_value": "",
        "value": ""
      },
      "time_worked": {
        "display_value": "",
        "value": ""
      },
      "chg_model": {
        "display_value": "",
        "value": ""
      },
      "expected_start": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "opened_at": {
        "display_value": "2015-06-09 11:55:46",
        "value": "2015-06-09 18:55:46",
        "display_value_internal": "2015-06-09 11:55:46"
      },
      "work_end": {
        "display_value": "2015-07-06 11:56:10",
        "value": "2015-07-06 18:56:10",
        "display_value_internal": "2015-07-06 11:56:10"
      },
      "phase_state": {
        "display_value": "Open",
        "value": "open"
      },
      "cab_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "work_notes": {
        "display_value": "",
        "value": ""
      },
      "close_code": {
        "display_value": "Successful",
        "value": "successful"
      },
      "assignment_group": {
        "display_value": "Network",
        "value": "287ebd7da9fe198100f92cc8d1d2154e"
      },
      "description": {
        "display_value": "Resend the complete BGP table to neighboring routers\r\n\r\n--Both neighbors need to support soft reset route refresh capability.\r\n--Stores complete BGP table of you neighbor in router memory.\r\n--Not a good idea on a peering router with full feed, due to the memory requirements.\r\n",
        "value": "Resend the complete BGP table to neighboring routers\r\n\r\n--Both neighbors need to support soft reset route refresh capability.\r\n--Stores complete BGP table of you neighbor in router memory.\r\n--Not a good idea on a peering router with full feed, due to the memory requirements.\r\n"
      },
      "on_hold_reason": {
        "display_value": "",
        "value": ""
      },
      "calendar_duration": {
        "display_value": "",
        "value": ""
      },
      "close_notes": {
        "display_value": "Completed without issues",
        "value": "Completed without issues"
      },
      "sys_id": {
        "display_value": "1766f1de47410200e90d87e8dee490f6",
        "value": "1766f1de47410200e90d87e8dee490f6"
      },
      "contact_type": {
        "display_value": "Phone",
        "value": "phone"
      },
      "cab_required": {
        "display_value": "false",
        "value": false
      },
      "urgency": {
        "display_value": "3 - Low",
        "value": 3.0
      },
      "scope": {
        "display_value": "Medium",
        "value": 3.0
      },
      "company": {
        "display_value": "",
        "value": ""
      },
      "justification": {
        "display_value": "",
        "value": ""
      },
      "activity_due": {
        "display_value": "UNKNOWN",
        "value": "",
        "display_value_internal": ""
      },
      "comments": {
        "display_value": "",
        "value": ""
      },
      "approval": {
        "display_value": "Approved",
        "value": "approved"
      },
      "due_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "sys_mod_count": {
        "display_value": "10",
        "value": 10.0
      },
      "on_hold": {
        "display_value": "false",
        "value": false
      },
      "sys_tags": {
        "display_value": "",
        "value": ""
      },
      "conflict_last_run": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "risk_value": {
        "display_value": "",
        "value": ""
      },
      "unauthorized": {
        "display_value": "false",
        "value": false
      },
      "risk": {
        "display_value": "Moderate",
        "value": 3.0
      },
      "location": {
        "display_value": "",
        "value": ""
      },
      "category": {
        "display_value": "Other",
        "value": "Other"
      },
      "risk_impact_analysis": {
        "display_value": "",
        "value": ""
      }
    }
  ]
}

Change Management - GET /sn_chg_rest/change/{change_sys_id}/nextstates

Retrieves a list of available states for the specified change request, including the current state.

If available, it also provides how to transition to the next state based on the version of the implemented Change Management. If the changes are change model driven, the endpoint returns conditions which have passed or not. It also provides information on whether all conditions have passed for a given transition. This information is not available for type driven and legacy change requests.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{change_sys_id}/nextstates

Default URL: /api/sn_chg_rest/change/{change_sys_id}/nextstates

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 49. Path parameters
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
change_sys_id Sys_id of the change request.

Data type: String

Table: Change Request [change_request]
Table 50. Query parameters
Name Description
None
Table 51. Request body parameters (XML or JSON)
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.

Table 52. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 53. Response headers
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.

Table 54. Status codes
Status code Description
200 Successful. The request was successfully processed.
404 Not found. The requested item wasn't found.

Response body parameters (JSON or XML)

Name Description
available_states Values for the states that are available for the specified change request, including the current state.

Data type: Array
state_label Key-value pairs that associate labels with the available states.

Data type: Object
state_transitions Information on what is required to transition to each available state. Each distinct available "to state" is in its own Array with each differing set of conditions for that to state being in its own Object.

Data type: Array

"state_transitions": [
  {
    "automatic_transition": Boolean,
    "conditions": [Array],
    "display_value": "String",
    "from_state": "String",
    "sys_id": "String",
    "to_state": "String",
    "transition_available": Boolean
  }
]
state_transitions.automatic_transition

Flag that indicates whether to automatically transition to this state.

Valid values:
  • true: Change request automatically transitions to this state.
  • false: Change request does not automatically transition to this state.

Data type: Boolean
state_transitions.conditions List of the conditions associated with the state.

Data type: Array of Objects

"conditions": [
  {
    "condition": {Object},
    "passed": Boolean
  }
]
state_transitions.conditions.condition Values of a specific condition.

Data type: Object

"condition": {
  "description": "String",
  "name": "String",
  "sys_id": "String"
}
state_transitions.conditions.condition.description Description of the condition.

Data type: String
state_transitions.conditions.condition.name Name of the condition.

Data type: String
state_transitions.conditions.condition.sys_id Sys_id of the condition.

Data type: String
state_transitions.conditions.passed

Flag that indicates whether the change request met the associated condition.

Valid values:
  • true: Met the condition.
  • false: Did not meet the condition.
state_transitions.display_value Displayed description of the state.

Data type: String
state_transitions.from_state Value of the state that the change request is transitioning from.

Data type: String
state_transitions.sys_id Sys_id of the transition state.

Data type: String
state_transitions.to_state Value of the state that the change request is transitioning to.

Data type: String
state_transitions.transition_available

Flag that indicates whether the change request can transition from its current state to this state.

Valid values:
  • true: Can transition to this state.
  • false: Cannot transition to this state.

Example: cURL request

The following code example shows how to call this endpoint.

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/b0dbda5347c12200e0ef563dbb9a718f"/nextstates \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

Return results:

{
  "result": {
    "available_states": [ "0", "4", "-1" ], // State values
    "state_transitions": [
      [
        {
          "sys_id": "7a0d2ccdc343101035ae3f52c1d3ae2e", // sttrm_state_transition sys id
          "display_value": "Implement to Review",
          "from_state": "-1",
          "to_state": "0",
          "transition_available": false, // If true, can move to this state
          "automatic_transition": true, // If true, automatically moves to this state
          "conditions": [
            {
              "passed": false, // If true, change request met this condition
              "condition": {
                "name": "No active Change Tasks",
                "description": null,
                "sys_id": "3c1d2ccdc343101035ae3f52c1d3aea4"
              }
            }
          ]
        },
        {
          "sys_id": "db401481c343101035ae3f52c1d3aedd",
          "display_value": "Implement to Review",
          "from_state": "-1",
          "to_state": "0",
          "transition_available": true,
          "automatic_transition": false,
          "conditions": [
            {
              "passed": true,
              "condition": {
                "name": "Not On hold",
                "description": null,
                "sys_id": "2132deb6c303101035ae3f52c1d3ae8c"
              }
            }
          ]
        }
      ],
      [
        {
          "sys_id": "5327c551c343101035ae3f52c1d3aeec",
          "display_value": "Implement to Canceled",
          "from_state": "-1",
          "to_state": "4",
          "transition_available": true,
          "automatic_transition": false,
          "conditions": []
        }
      ]
    ],
    "state_label": { // state value to label pairs
      "0": "Review",
      "4": "Canceled",
      "-1": "Implement"
    }
  }
}

Change Management - GET /sn_chg_rest/change/{change_sys_id}/schedule

Enables retrieving the available time slots for a change request.

Role required: sn_change_writer.

Note: Running this endpoint doesn't list the available start and end times. Use the link provided in the response body worker.link property to get the schedule data.
See also:

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{change_sys_id}/schedule

Default URL: /api/sn_chg_rest/change/{change_sys_id}/schedule

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 55. Path parameters
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
change_sys_id Sys_id of the change request on which to find the next available time slot.

The selected change request must have a configuration item (cmdb_ci) with planned start and planned end times.

Table: Change Request [change_request]
Table 56. Query parameters
Name Description
None
Table 57. Request body parameters (XML or JSON)
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.

Table 58. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 59. Response headers
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.

Table 60. Status codes
Status code Description
202 System accepted the request.
400 Bad Request. A bad request type or malformed request was detected.
Possible issues:
  • The specified change request is missing the planned start and end times.
  • The specified change request doesn't have an associated configuration item (cmdb_ci).
  • User doesn't have read access to the fields of the change request.
404 Not Found. The specified record couldn't be found.
Possible issues:
  • System can't find the change request based on information provided.
  • User doesn't have read access to the record.

Response body parameters (JSON or XML)

Name Description
error Information on any errors encountered while processing the endpoint request.

Data type: Object

"error": {
  "detail": "String",
  "message": "String",
  "status": "String"
}
error.detail Additional information about the error.

Data type: String
error.message Message that identifies the error.

Data type: String
messages Message information.
Data type: Object
"messages": {
  "errorMessages": [Array],
  "infoMessages": [Array],
  "warningMessages": [Array]
}
messages.errorMessages Error messages encountered while processing the request.

Data type: Array
messages.infoMessages Information messages encountered while processing the request.

Data type: Array
messages.warningMessages Warning messages encountered while processing the request.

Data type: Array
request Original endpoint request.

Data type: String
state Information on the current state of the worker.

Data type: Object

state: {
  display_value: "String", 
  value: Number
}
state.display_value Display value of the state of the worker. These values directly correlate to the state.value parameter.

Possible values:

  • Complete
  • Error
  • In-Progress
  • Waiting

Data type: String
state.value Numeric value of the state of the worker.

Possible values:

  • 1
  • 2
  • 3
  • 4

Data type: Number
type Type of request.

Valid value: schedule

Data type: String
worker Information about the associated worker.

Data type: Object

"worker": {
  "link": "String",
  "sysId": "String"
}
worker.link Link for retrieving time slot data. Use the sys_id in GET /sn_chg_rest/change/worker/{sys_id} to view results.

Data type: String
worker.sysId Sys_id of the worker associated with the change request.

Data type: String
status Only appears if an error is encountered. Status of the endpoint processing.

Possible value: failure

Data type: String

Get available time slots

Use the value provided in the worker.link to get schedule window details. The value is in the following format:

https://instance.service-now.com/api/sn_chg_rest/change/worker/<worker_sys_id>

Use the worker_sys_id in GET /sn_chg_rest/change/worker/{worker_sys_id} to view results.

The response body contains the status and provides results when processing is complete.

Worker response body parameter results vary depending on time slot availability.
  • If the provided time slot is available for the change request within the schedule time slot, the worker API lists the available time slots in the payload.spans property. The payload.spans property isn't listed in the results otherwise.
  • If there are no time slots available for change request duration provided within the defined scheduling time slot, the messages.infoMessages states the following: D
    Note: The change request scheduling time slot default value is 90 days. To change this value, modify the change.conflict.next_available.schedule_window property. For more information, see Configure conflict analysis properties.

The following GET /sn_chg_rest/change/worker/{sys_id} example shows output provided using the ID provided in the worker.link detail. The results list open time spans available for the task duration.

{
  "result": {
    "worker": {
      "sysId": "9b3f62e0a4c87010f87712198fe9cad1",
      "link": "https://instance.service-now.com/api/sn_chg_rest/change/worker/9b3f62e0a4c87010f87712198fe9cad1"
    },
    "request": "{\"change_sys_id\":\"87ae5e900a0a2c3e263e8304e727c646\",\"timezone\":\"America/Los_Angeles\"}",
    "state": {
      "value": 3,
      "display_value": "Complete"
    },
    "type": "schedule",
    "messages": {
      "errorMessages": [],
      "warningMessages": [],
      "infoMessages": []
    },
    "payload": {
      "spans": [
        {
          "start": {
            "value": "2021-05-08 08:00:00",
            "display_value": "2021-05-08 01:00:00"
          },
          "end": {
            "value": "2021-05-08 11:00:00",
            "display_value": "2021-05-08 04:00:00"
          }
        },
        {
          "start": {
            "value": "2021-05-15 08:00:00",
            "display_value": "2021-05-15 01:00:00"
          },
          "end": {
            "value": "2021-05-15 11:00:00",
            "display_value": "2021-05-15 04:00:00"
          }
        },
        ...
      ]
    }
  }
}

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/change/{change_sys_id}/schedule" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

Results include worker.link details you can use to run the provided sys_id in the GET /sn_chg_rest/change/worker/ endpoint.

{
  "result": {
    "worker": {
      "sysId": "9b3f62e0a4c87010f87712198fe9cad1",
      "link": "https://instance.service-now.com/api/sn_chg_rest/change/worker/9b3f62e0a4c87010f87712198fe9cad1"
    },
    "request": "{\"change_sys_id\":\"87ae5e900a0a2c3e263e8304e727c646\",\"timezone\":\"America/Los_Angeles\"}",
    "state": {
      "value": 1,
      "display_value": "Waiting"
    },
    "type": "schedule",
    "messages": {
      "errorMessages": [],
      "warningMessages": [],
      "infoMessages": []
    }
  }
}

Change Management - GET /sn_chg_rest/change/{change_sys_id}/task

Retrieves one or more tasks associated with a specified change request based on the specified criteria.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{change_sys_id}/task

Default URL: /api/sn_chg_rest/change/{change_sys_id}/task

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 61. Path parameters
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
change_sys_id Sys_id of the change request whose tasks are to be retrieved.

Data type: String

Table: Change Request [change_request]
Table 62. Query parameters
Name Description
key-value pairs Fields to modify when creating the request. The key is the field name within the template and the value is the information to populate in the field.
Fields that cannot be modified and are ignored if passed in:
  • Business rules
  • Read-only fields as defined in ACLs
  • Fields that do not exist

Data type: String
order Field by which to sort the returned change requests.

Data type: String
sysparm_limit Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval.

Data type: Number

Default: 500
sysparm_offset Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks.

For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use sysparm_offset=sysparm_offset+sysparm_limit, until you reach the end of all records.

Don't pass a negative number in the sysparm_offset parameter.

Data type: Number

Default: 0
sysparm_query Encoded query used to filter the result set. You can use a UI filter to obtain a properly encoded query.
Syntax: sysparm_query=<col_name><operator><value>.
  • <col_name>: Name of the table column to filter against.
  • <operator>: Supports the following values:
    • =: Exactly matches <value>.
    • !=: Does not match <value>.
    • ^: Logically AND multiple query statements.
    • ^OR: Logically OR multiple query statements.
    • LIKE: <col_name> contains the specified string. Only works for <col_name> fields whose data type is string.
    • STARTSWITH: <col_name> starts with the specified string. Only works for <col_name> fields whose data type is string.
    • ENDSWITH: <col_name> ends with the specified string. Only works for <col_name> fields whose data type is string.
    <value>: Value to match against.
For more operators, see Operators available for filters and queries.

All parameters are case-sensitive. Queries can contain more than one entry, such as sysparm_query=<col_name><operator><value>[<operator><col_name><operator><value>].

For example:

(sysparm_query=caller_id=javascript:gs.getUserID()^active=true)

Encoded queries also support order by functionality. To sort responses based on certain fields, use the ORDERBY and ORDERBYDESC clauses in sysparm_query.

Syntax:
  • ORDERBY<col_name>
  • ORDERBYDESC<col_name>

For example: sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory

This query filters all active records and orders the results in ascending order by number, and then in descending order by category.

If part of the query is invalid, such as by specifying an invalid field name, the instance ignores the invalid part. It then returns rows using only the valid portion of the query. You can control this behavior using the property glide.invalid_query.returns_no_rows. Set this property to true to return no rows on an invalid query.
Note: The glide.invalid_query.returns_no_rows property controls the behavior of all queries across the instance, such as in lists, scripts (GlideRecord.query()), and web service APIs.

Data type: String
textSearch String to use to search all change task record fields. This search uses ServiceNow full text search platform functionality and defaults to IR_AND_OR_QUERY.

Data type: String
Table 63. Request body parameters (XML or JSON)
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.

Table 64. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 65. Response headers
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.

Table 66. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs All fields (key) with their associated values for the identified change request task prior to the delete.

Data type: Object
parent Information for the change request associated to the task.

Data type: Object

parent: {
  display_value: "String", 
  value: "String"
}
parent.display_value Change request information to display in a UI.

Data type: String
parent.value Sys_id of the change request associated to the task.

Data type: String
sys_id Sys_id information for the change request task.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request task to display in a UI.

Data type: String
sys_id.value Sys_id of the change request task.

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/0f4ac6c4b750230096c3e4f6ee11a9fe/task?sysparm_query=active=true^ORDERBYnumber" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

{
    result: [
        {
            sys_id: {
                value: "12629ec4b750230096c3e4f6ee11a9d5",
                display_value: "12629ec4b750230096c3e4f6ee11a9d5"
            },
            parent: {
                value: "0f4ac6c4b750230096c3e4f6ee11a9fe ", 
                display_value: "CHG0033046 "
            },
            ..., // all valid fields in record, example below
            short_description: {
                value: "Retire node",
                display_value: "Retire node"
            }
        }, 
        { // next record found }, ... // and so on
    ]
}

Change Management - GET /sn_chg_rest/change/{sys_id}

Retrieves the change request identified by the specified sys_id.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{sys_id}

Default URL: /api/sn_chg_rest/change/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 67. Path parameters
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
sys_id Sys_id of the change request record.

Data type: String

Table: Change Request [change_request]
Table 68. Query parameters
Name Description
None
Table 69. Request body parameters (XML or JSON)
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.

Table 70. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 71. Response headers
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.

Table 72. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Element Description
result List containing one or more change request record objects. Each object describes a change request. Each element in the change request object corresponds to a field in its associated record in the Change Request [change_request] table.

All elements contain value and display_value name-value pairs. Date fields also contain display_value_internal name-value pairs.

Data type: Array
action_status Current action status of the associated change request.

Possible values:

  • 1: Blocked internally
  • 2: Blocked by customer
  • 3: Blocked internally and by customer
  • 4: Needs attention

Data type: Number
active Flag that indicates whether the change request is active.

Possible values:

  • true: Change request is active
  • false: Change request isn't active

Data type: Boolean

Default: true
activity_due Date and time for which the associated case is expected to be completed.

Data type: String
additional_assignee_list List of sys_ids of additional persons assigned to work on the change request.

Data type: Array
approval Type of approval process required.

Data type: String

Default: not requested
approval_history Most recent approval history journal entry.

Data type: String
approval_set Date and time that the associated action was approved.

Data type: String
assigned_to Sys_id of the user assigned to the change request.

Data type: String
assignment_group Sys_id of the group assigned to the change request.

Data type: String
backout_plan Description of the plan to execute if the change must be reversed.

Data type: String
business_duration Length in scheduled work hours, work days, and work weeks that it took to complete the change.

Data type: String
business_service Sys_id of the business service associated with the change request. Located in the Service [cmdb_ci_service] table.

Data type: String
cab_date Date on which the Change Advisory Board (CAB) meets.

Data type: String
cab_delegate Sys_id of the user that can substitute for the CAB manager during a CAB meeting. Located in the User [sys_user] table

Data type: String
cab_recommendation Description of the CAB recommendations for the change request.

Data type: String

Maximum length: 4,000
cab_required Flag that indicates whether the CAB is required.
Possible values:
  • true: Change Advisory Board is required.
  • false: Change Advisory Board isn't required.

Data type: Boolean

Default: false
calendar_duration Not currently used by Change Management.

Data type: String
category Category of the change, for example hardware, network, or software.

Data type: String

Default: Other
change_plan Activities and roles for managing and controlling the change request.

Data type: String
chg_model Sys_id of the change model that the associated change request was based on. The Change Model defines the state flow, transitions, and process activities that must be completed for the change request.

Data type: String

Table: Change Model [chg_model]
closed_at Date and time that the associated change request was closed.

Data type: String
closed_by Sys_id of the person that closed the change request.

Data type: String

Table: User [sys_user]
close_code Code assigned to the change request when it was closed. For example, Successful, Successful with issues, and Unsuccessful.

Data type: String
close_notes Notes that the person entered when closing the change request.

Data type: String
cmdb_ci Sys_id of the configuration item associated with the change request.

Data type: String

Table: Configuration Item [cmdb_ci]
comments List of customer-facing work notes entered in the associated change request.

Data type: Array
comments_and_work_notes List of both internal and customer-facing work notes entered for the associated change request.

Data type: Array

Maximum length: 4,000
company Sys_id of the company associated with the change request.

Data type: String

Table: Company [core_company]
conflict_last_run Date and time that the conflict detection script was last run on the change request.

Data type: String
conflict_status Current conflict status as detected by the conflict detection script, such as Conflict and Not Run.

Data type: String

Maximum length: 40

Default: Not Run
contact_type Method in which the change request was initially requested.
Possible values:
  • chat
  • email
  • phone
  • social
  • web

Data type: String
contract Sys_id of the contract associated with the change request.

Data type: String

Table: Contract [ast_contract]
correlation_display User-friendly name for the correlation_id.

Data type: String

Maximum length: 100
correlation_id Globally unique ID (GUID) of a matching change request record in a third-party system.

Data type: String

Maximum length: 100
delivery_plan No longer in use. Sys_id of the delivery plan associated with the change request.

Data type: String

Table: Execution Plan [sc_cat_item_delivery_plan]
delivery_task No longer in use. Sys_id of the delivery task associated with the change request.

Data type: String

Table: Execution Plan Task [sc_cat_item_delivery_task]
description Detailed description of the change request.

Data type: String

Maximum length: 4,000
due_date Task due date. Not used by change request process.

Data type: String
end_date Date and time when the change request is to be completed.

Data type: String
escalation Current escalation level.

Possible values:

  • 0: Normal
  • 1: Moderate
  • 2: High
  • 3: Overdue

Data type: Number (Integer)

Default: 0
expected_start Date and time when the task is to start. Not used by the change request process.

Data type: String
follow_up Date and time when a user followed-up with the person requesting the change request.

Data type: String
group_list List of sys_ids and names of the groups associated with the change request.

Data type: Array

Maximum length: 4,000
impact Impact on the change request will have on the customer.

Possible values:

  • 1: High
  • 2: Medium
  • 3: Low

Data type: Number (Integer)

Default: 3
implementation_plan Sequential steps to execute to implement this change. It also contains any dependencies between steps and assignee details for each step.

Data type: String

Maximum length: 4,000
justification Benefits of implementing this change and the impact if this change is not implemented.

Data type: String

Maximum length: 4,000
knowledge Flag that indicates whether there are any knowledge base ()KB) articles associated with the change request.
Possible values:
  • true: Associated KB articles
  • false: No associated KB articles

Data type: Boolean
location Sys_id and name of the location of the equipment referenced in the change request.

Data type: String

Table: Location [cmn_location]
made_sla No longer used. Flag that indicates whether the change request was implemented in alignment with the associated service level agreement.

Data type: Boolean
needs_attention Flag that indicates whether the change request needs attention.

Possible values:

  • true: Change request needs additional attention.
  • false: Change request doesn't need additional attention.

Data type: Boolean

Default: false
number Change number assigned to the change request by the system, such as CHG0040007.

Data type: String
on_hold Flag that indicates whether the change request is currently on hold.
Possible values:
  • true: On hold
  • false: Not on hold

Data type: Boolean

Default: false
on_hold_reason If the on_hold parameter is "true", description of the reason why the change request is being held up.

Data type: String

Maximum length: 4,000
on_hold_task If the on_hold parameter is "true", list of the sys_ids of the tasks that must be completed before the hold is released.

Data type: String

Maximum length: 4,000
opened_at Date and time that the change release was created.

Data type: String
opened_by Sys_id and name of the user that created the change release.

Data type: String

Table: User [sys_user]
order Not used by Change Management. Optional numeric field by which to order records, such as when retrieving them from a database.

Data type: Number (Integer)
outside_maintenance_schedule Flag that indicates whether maintenance by an outside company has been schedule for the change request.
Possible values:
  • true: Outside maintenance scheduled
  • false: No outside maintenance scheduled

Data type: Boolean

Default: false
parent Sys_id and name of the parent task to this change request, if any.

Data type: String

Table: Task [task]
phase Current phase of the change request. This defines what the change is doing in greater detail.
Possible values:
  • accept
  • build
  • plan
  • requested

Data type: String
phase_state Change_phase records that should be created for a change. They are dependent on the category, such that each type of change may have different change_phase records. The change_phase records provide an opportunity to control the approval process as each change_phase can have a schedule and a set of approvers.
Possible values:
  • complete
  • on hold
  • open
  • rejected
  • requested
  • work in progress

Data type: String
priority Priority of the change request.
Possible values:
  • 1: Critical
  • 2: High
  • 3: Moderate
  • 4: Low

Data type: Number (Integer)

Default: 4
production_system Flag that indicates whether the change request is for a ServiceNow instance that is in a production environment.
Possible values:
  • true: Production environment
  • false: Non-production environment

Data type: Boolean
reason Description of why the change request was initiated.
Possible values:
  • Business requirements
  • Hardware upgrade
  • Legislation
  • Location change
  • Network requirements
  • New or removed CI
  • Other
  • Problem resolved
  • Product or service changed
  • Software upgrade
  • User requested

Data type: String

Maximum length: 40
reassignment_count Number of times that the change request has been reassigned to a new owner.

Data type: Number (Integer)

Default: 0
rejection_goto Sys_id of the task to perform if the change request is rejected.

Data type: String

Table: Task [task]
requested_by Sys_id of the user that requested the change.

Data type: String

Table: User [sys_user]
requested_by_date Date and time when the change is requested to be implemented by.

Data type: String
review_comments Comments entered when the change request was reviewed.

Data type: String

Maximum length: 4,000
review_date Date that the change request was reviewed.

Data type: String
review_status Current status of the requested change request review.

Data type: String
risk Level of risk associated with the change request.
Valid values:
  • 1: High
  • 2: Moderate
  • 3: Low

Data type: Number

Default: 3
risk_impact_analysis Description of the risk and analysis of implementing the change request.

Data type: String

Maximum length: 4,000
route_reason Not currently used by Change Management. Reason that the change request was transferred.
Possible values:
  • 1: Transfer with Resolution
  • 9: Transfer without Resolutions

Data type: Number
scope Size of the change request.
Possible values:
  • 1: Massive
  • 2: Large
  • 3: Medium
  • 4: Small
  • 5: Tiny

Data type: Number

Default: 3
service_offering Sys_id of the service offering associated with the change request. Service offerings uniquely define the level of service in terms of availability, scope, pricing, and packaging options.

Data type: String

Table: Offering [service_offering]
short_description Description of the change request.

Data type: String

Maximum length: 40
skills List of the sys_ids of all of the skills required to implement the change request.

Data type: Array

Table: Skill [cmn_skill]
sla_due No longer in use. Date and time that the change request must be completed based on the associated service level agreement.

Data type: String
sn_esign_document Sys_id of any E-signed document attached to the change request.

Data type: String

Table: Attachment [sys_attachment]
sn_esign_esignature_configuration Sys_id of the E-signed signature template used for the associated document.

Data type: String

Table: E-signature Template [sn_esign_configuration]
start_date Date and time that the change request is planned to start implementation.

Data type: String
state Current state of the change request. Possible values are defined in the change model.

Data type: Number (Integer)

Default: 1
std_change_producer_version Sys_id of the record producer and change proposal associated with the change request. It also includes the number and percentage of successful and unsuccessful change requests created from the proposal.

Data type: String

Table: Standard Change Template Version [std_change_producer_version]
sys_class_name Name of the table in which the change request is located.

Data type: String
sys_created_by Name of the user that initially created the change request.

Data type: String

Maximum length: 40
sys_created_on Date and time that the associated change request record was originally created.

Data type: String
sys_domain If using domains in the instance, the name of the domain to which the change module record is associated.

Data type: String
sys_domain_path If using domains in the instance, the domain path in which the associated change module record resides.

Data type: String
sys_id Unique identifier of the associated change request record.

Data type: String
sys_mod_count Number of updates to the case since it was initially created.

Data type: Number (Integer)
sys_updated_by Person that last updated the case.

Data type: String

Maximum length: 40
sys_updated_on Date and time when the case was last updated.

Data type: String
task_effective_number Universal request number.

Data type: String

Maximum length: 40
task_for Not used by Change Management. Sys_id of the user that the task was created for.

Data type: String

Table: User [sys_user]
test_plan Description of the associated test plan for the change.

Data type: String

Maximum length: 4,000
time_worked Total amount of time worked on the change request.

Data type: String
type Change request type.
Possible values:
  • emergency
  • normal
  • standard

Data type: String

Maximum length: 40
unauthorized Flag that indicates whether the change request is unauthorized
Possible values:
  • true: Unauthorized
  • false: Authorized

Data type: Boolean
universal_request Sys_id of the Parent Universal request to which this change request is a part of.

Data type: String

Table: Task [task]
upon_approval Action to take if the change request is approved.

Possible values:

  • do_nothing
  • proceed

Data type: String

Maximum length: 40

Default: proceed
upon_reject Action to take if the change request is rejected.

Possible values:

  • cancel
  • goto

Data type: String

Maximum length: 40

Default: cancel
urgency Urgency of the change request.

Possible values:

  • 1: High
  • 2: Medium
  • 3: Low

Data type: Number (Integer)

Default: 3
user_input Additional user input.

Data type: String

Maximum length: 4,000
variables Name-value pairs of variables associated with the change request.

Data type: String

Maximum length: 40
watch_list List of sys_ids of the users who receive notifications about this change request when additional comments are added or if the state of a change request is changed to Resolved or Closed.

Data type: Array

Table: User [sys_user]
wf_activity Sys_id of the workflow activity record associated with the change request.

Data type: String

Table: Workflow Activity [wf_activity]
work_end Date and time work ended on the change request.

Data type: String
work_notes Information about how to resolve the change request, or steps taken to resolve it.

Data type: String

Maximum length: 4,000
work_notes_list List of sys_ids of the internal users who receive notifications about this change request when work notes are added.

Data type: Array

Table: User [sys_user]
work_start Date and time that work started on the change request.

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/b0dbda5347c12200e0ef563dbb9a718f" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result":
    {
      "reason": {
        "display_value": "",
        "value": ""
      },
      "parent": {
        "display_value": "",
        "value": ""
      },
      "watch_list": {
        "display_value": "",
        "value": ""
       },
       "proposed_change": {
         "display_value": "",
         "value": ""
       },
       "upon_reject": {
         "display_value": "Cancel all future Tasks",
         "value": "cancel"
       },
       "sys_updated_on": {
         "display_value": "2015-07-06 11:59:27",
         "value": "2015-07-06 18:59:27",
         "display_value_internal": "2015-07-06 11:59:27"
      },
      "type": {
        "display_value": "Standard",
        "value": "standard"
      },
      "approval_history": {
        "display_value": "",
        "value": ""
      },
      "skills": {
        "display_value": "",
        "value": ""
      },
      "test_plan": {
        "display_value": "--Confirm that there are no monitoring alerts for the router",
        "value": "--Confirm that there are no monitoring alerts for the router"
      },
      "number": {
        "display_value": "CHG0000024",
        "value": "CHG0000024"
      },
      "is_bulk": {
        "display_value": "false",
        "value": false
      },
      "cab_delegate": {
        "display_value": "",
        "value": ""
      },
      "requested_by_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "ci_class": {
        "display_value": "cmdb_ci",
        "value": "cmdb_ci"
      },
      "state": {
        "display_value": "Closed",
        "value": 3.0
      },
      "sys_created_by": {
        "display_value": "admin",
        "value": "admin"
      },
      "knowledge": {
        "display_value": "false",
        "value": false
      },
      "order": {
        "display_value": "",
        "value": ""
      },
      "phase": {
        "display_value": "Requested",
        "value": "requested"
      },
      "cmdb_ci": {
        "display_value": "",
        "value": ""
      },
      "delivery_plan": {
        "display_value": "",
        "value": ""
      },
      "impact": {
        "display_value": "3 - Low",
        "value": 3.0
      },
      "contract": {
        "display_value": "",
        "value": ""
      },
      "active": {
        "display_value": "false",
        "value": false
      },
      "work_notes_list": {
        "display_value": "",
        "value": ""
      },
      "priority": {
        "display_value": "4 - Low",
        "value": 4.0
      },
      "sys_domain_path": {
        "display_value": "/",
        "value": "/"
      },
      "cab_recommendation": {
        "display_value": "",
        "value": ""
      },
      "production_system": {
        "display_value": "false",
        "value": false
      },
      "rejection_goto": {
        "display_value": "",
        "value": ""
      },
      "review_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "requested_by": {
        "display_value": "System Administrator",
        "value": "6816f79cc0a8016401c5a33be04be441"
      },
      "business_duration": {
        "display_value": "",
        "value": ""
      },
      "group_list": {
        "display_value": "",
        "value": ""
      },
      "change_plan": {
        "display_value": "",
        "value": ""
      },
      "approval_set": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "wf_activity": {
        "display_value": "",
        "value": ""
      },
      "implementation_plan": {
        "display_value": "-- Place router into maintenance mode in the monitoring platform\r\n-- Logon to router through SSH\r\n-- Run the following command\r\n\r\nrouter(config-router)#router bgp 12345\r\nrouter(config-router)#neighbor {neighbor ip} soft-reconfig [inbound]\r\nrouter#clear ip bgp {neighbor ip} soft in\r\n\r\n-- Confirm the sessions have been cleared\r\n-- Place router back into operational mode in the monitoring platform",
        "value": "-- Place router into maintenance mode in the monitoring platform\r\n-- Logon to router through SSH\r\n-- Run the following command\r\n\r\nrouter(config-router)#router bgp 12345\r\nrouter(config-router)#neighbor {neighbor ip} soft-reconfig [inbound]\r\nrouter#clear ip bgp {neighbor ip} soft in\r\n\r\n-- Confirm the sessions have been cleared\r\n-- Place router back into operational mode in the monitoring platform"
      },
      "universal_request": {
        "display_value": "",
        "value": ""
      },
      "end_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "short_description": {
        "display_value": "Clear BGP sessions on a Cisco router",
        "value": "Clear BGP sessions on a Cisco router"
      },
      "correlation_display": {
        "display_value": "",
        "value": ""
      },
      "work_start": {
        "display_value": "2015-07-06 11:56:04",
        "value": "2015-07-06 18:56:04",
        "display_value_internal": "2015-07-06 11:56:04"
      },
      "delivery_task": {
        "display_value": "",
        "value": ""
      },
      "outside_maintenance_schedule": {
        "display_value": "false",
        "value": false
      },
      "additional_assignee_list": {
        "display_value": "",
        "value": ""
      },
      "std_change_producer_version": {
        "display_value": "Clear BGP sessions on a Cisco router - 1",
        "value": "16c2273c47010200e90d87e8dee49006"
      },
      "sys_class_name": {
        "display_value": "Change Request",
        "value": "change_request"
      },
      "service_offering": {
        "display_value": "",
        "value": ""
      },
      "closed_by": {
        "display_value": "System Administrator",
        "value": "6816f79cc0a8016401c5a33be04be441"
      },
      "follow_up": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "review_status": {
        "display_value": "",
        "value": ""
      },
      "reassignment_count": {
        "display_value": "2",
        "value": 2.0
      },
      "start_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "assigned_to": {
        "display_value": "",
        "value": ""
      },
      "variables": {
        "display_value": "variable_pool",
        "value": "variable_pool"
      },
      "sla_due": {
        "display_value": "UNKNOWN",
        "value": "",
        "display_value_internal": ""
      },
      "comments_and_work_notes": {
        "display_value": "",
        "value": ""
      },
      "escalation": {
        "display_value": "Normal",
        "value": 0.0
      },
      "upon_approval": {
        "display_value": "Proceed to Next Task",
        "value": "proceed"
      },
      "correlation_id": {
        "display_value": "",
        "value": ""
      },
      "made_sla": {
        "display_value": "true",
        "value": true
      },
      "backout_plan": {
        "display_value": "Due to the limited number of commands in the implementation plan it is not possible to backout the change.\r\n\r\nIf required you are authorized to reboot the router if BGP fails to work",
        "value": "Due to the limited number of commands in the implementation plan it is not possible to backout the change.\r\n\r\nIf required you are authorized to reboot the router if BGP fails to work"
      },
      "conflict_status": {
        "display_value": "Not Run",
        "value": "Not Run"
      },
      "task_effective_number": {
        "display_value": "CHG0000024",
        "value": "CHG0000024"
      },
      "sys_updated_by": {
        "display_value": "admin",
        "value": "admin"
      },
      "opened_by": {
        "display_value": "System Administrator",
        "value": "6816f79cc0a8016401c5a33be04be441"
      },
      "user_input": {
        "display_value": "",
        "value": ""
      },
      "sys_created_on": {
        "display_value": "2015-07-06 11:55:46",
        "value": "2015-07-06 18:55:46",
        "display_value_internal": "2015-07-06 11:55:46"
      },
      "on_hold_task": {
        "display_value": "",
        "value": ""
      },
      "sys_domain": {
        "display_value": "global",
        "value": "global"
      },
      "route_reason": {
        "display_value": "",
        "value": ""
      },
      "closed_at": {
        "display_value": "2015-07-06 11:56:23",
        "value": "2015-07-06 18:56:23",
        "display_value_internal": "2015-07-06 11:56:23"
      },
      "review_comments": {
        "display_value": "",
        "value": ""
      },
      "business_service": {
        "display_value": "",
        "value": ""
      },
      "time_worked": {
        "display_value": "",
        "value": ""
      },
      "chg_model": {
        "display_value": "",
        "value": ""
      },
      "expected_start": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "opened_at": {
        "display_value": "2015-06-09 11:55:46",
        "value": "2015-06-09 18:55:46",
        "display_value_internal": "2015-06-09 11:55:46"
      },
      "work_end": {
        "display_value": "2015-07-06 11:56:10",
        "value": "2015-07-06 18:56:10",
        "display_value_internal": "2015-07-06 11:56:10"
      },
      "phase_state": {
        "display_value": "Open",
        "value": "open"
      },
      "cab_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "work_notes": {
        "display_value": "",
        "value": ""
      },
      "close_code": {
        "display_value": "Successful",
        "value": "successful"
      },
      "assignment_group": {
        "display_value": "Network",
        "value": "287ebd7da9fe198100f92cc8d1d2154e"
      },
      "description": {
        "display_value": "Resend the complete BGP table to neighboring routers\r\n\r\n--Both neighbors need to support soft reset route refresh capability.\r\n--Stores complete BGP table of you neighbor in router memory.\r\n--Not a good idea on a peering router with full feed, due to the memory requirements.\r\n",
        "value": "Resend the complete BGP table to neighboring routers\r\n\r\n--Both neighbors need to support soft reset route refresh capability.\r\n--Stores complete BGP table of you neighbor in router memory.\r\n--Not a good idea on a peering router with full feed, due to the memory requirements.\r\n"
      },
      "on_hold_reason": {
        "display_value": "",
        "value": ""
      },
      "calendar_duration": {
        "display_value": "",
        "value": ""
      },
      "close_notes": {
        "display_value": "Completed without issues",
        "value": "Completed without issues"
      },
      "sys_id": {
        "display_value": "1766f1de47410200e90d87e8dee490f6",
        "value": "1766f1de47410200e90d87e8dee490f6"
      },
      "contact_type": {
        "display_value": "Phone",
        "value": "phone"
      },
      "cab_required": {
        "display_value": "false",
        "value": false
      },
      "urgency": {
        "display_value": "3 - Low",
        "value": 3.0
      },
      "scope": {
        "display_value": "Medium",
        "value": 3.0
      },
      "company": {
        "display_value": "",
        "value": ""
      },
      "justification": {
        "display_value": "",
        "value": ""
      },
      "activity_due": {
        "display_value": "UNKNOWN",
        "value": "",
        "display_value_internal": ""
      },
      "comments": {
        "display_value": "",
        "value": ""
      },
      "approval": {
        "display_value": "Approved",
        "value": "approved"
      },
      "due_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "sys_mod_count": {
        "display_value": "10",
        "value": 10.0
      },
      "on_hold": {
        "display_value": "false",
        "value": false
      },
      "sys_tags": {
        "display_value": "",
        "value": ""
      },
      "conflict_last_run": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "risk_value": {
        "display_value": "",
        "value": ""
      },
      "unauthorized": {
        "display_value": "false",
        "value": false
      },
      "risk": {
        "display_value": "Moderate",
        "value": 3.0
      },
      "location": {
        "display_value": "",
        "value": ""
      },
      "category": {
        "display_value": "Other",
        "value": "Other"
      },
      "risk_impact_analysis": {
        "display_value": "",
        "value": ""
      }
    }
}

Change Management - GET /sn_chg_rest/change/{sys_id}/ci

Retrieves multiple configuration items (CIs) associated to a specified change request based on the specified association type.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{sys_id}/ci

Default URL: /api/sn_chg_rest/change/{sys_id}/ci

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 73. Path parameters
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
sys_id Sys_id of the change request for which to return the associated CMDB CIs.

Data type: String
Table 74. Query parameters
Name Description
association_type Required. Type of association between the CMDB CI and the change request.

Valid values:

  • affected: CIs that are affected by the change request
  • impacted: Services impacted by the change request
  • offering: Impacted service offerings

Data type: String
name-value pairs Name-value pairs to use to filter the result set. The name is the field on which the specified value is filtered. This parameter is mutually exclusive with sysparm_query. For example, instead of using &sysparm_query=active=true, you can simplify the calling statement by using &active=true. You can also use the display value when the field is a choice or reference type field, such as &state=closed instead of &state=7. To specify multiple key-value pairs, separate each with an ampersand, such as &active=true&assigned_to=john.smith.

Data type: String
sysparm_limit Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval.

Data type: Number

Default: 500
sysparm_offset Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks.

For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use sysparm_offset=sysparm_offset+sysparm_limit, until you reach the end of all records.

Don't pass a negative number in the sysparm_offset parameter.

Data type: Number

Default: 0
sysparm_query Encoded query used to filter the result set. You can use a UI filter to obtain a properly encoded query.
Syntax: sysparm_query=<col_name><operator><value>.
  • <col_name>: Name of the table column to filter against.
  • <operator>: Supports the following values:
    • =: Exactly matches <value>.
    • !=: Does not match <value>.
    • ^: Logically AND multiple query statements.
    • ^OR: Logically OR multiple query statements.
    • LIKE: <col_name> contains the specified string. Only works for <col_name> fields whose data type is string.
    • STARTSWITH: <col_name> starts with the specified string. Only works for <col_name> fields whose data type is string.
    • ENDSWITH: <col_name> ends with the specified string. Only works for <col_name> fields whose data type is string.
    <value>: Value to match against.
For more operators, see Operators available for filters and queries.

All parameters are case-sensitive. Queries can contain more than one entry, such as sysparm_query=<col_name><operator><value>[<operator><col_name><operator><value>].

For example:

(sysparm_query=caller_id=javascript:gs.getUserID()^active=true)

Encoded queries also support order by functionality. To sort responses based on certain fields, use the ORDERBY and ORDERBYDESC clauses in sysparm_query.

Syntax:
  • ORDERBY<col_name>
  • ORDERBYDESC<col_name>

For example: sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory

This query filters all active records and orders the results in ascending order by number, and then in descending order by category.

If part of the query is invalid, such as by specifying an invalid field name, the instance ignores the invalid part. It then returns rows using only the valid portion of the query. You can control this behavior using the property glide.invalid_query.returns_no_rows. Set this property to true to return no rows on an invalid query.
Note: The glide.invalid_query.returns_no_rows property controls the behavior of all queries across the instance, such as in lists, scripts (GlideRecord.query()), and web service APIs.

Data type: String
Table 75. Request body parameters (XML or JSON)
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.

Table 76. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 77. Response headers
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.

Table 78. Status codes
Status code Description
200 Successful. The request was successfully processed.
400 Bad Request. A bad request type or malformed request was detected.

The error response contains pertinent messages to help troubleshoot the problem.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Name Description
ci_item|cmdb_ci_service Either the ci_item or cmdb_ci_service variables, depending upon the association type.

Data type: Array

ci_item|cmdb_ci_service : {
  display_value: "String", 
  value: "String"
}
ci_item|cmdb_ci_service.value Sys_id of the ci_item or cmdb_ci_service.

Data type: String
ci_item|cmdb_ci_service.display_value Display value of the ci_item or cmdb_ci_service.

Data type: String
sys_id Change request sys_id information.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.value Sys_id of the change request.

Data type: String
sys_id.display_value Sys_id of the change request to display in a UI.

Data type: String
<record_fields> All valid fields in the ci_item or cmdb_ci_service record; table based on association type.

Data type: Object

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/c286d61347c12200e0ef563dbb9a71df/ci?association_type=affected" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

{
  result: [
    {
      sys_id: {
        value: "92b8544047810200e90d87e8dee490b0",
        display_value: "92b8544047810200e90d87e8dee490b0"
      },
      ci_item|cmdb_ci_service : {
        value: "3a27d4370a0a0bb4006316812bf45439", 
        display_value: "PS Apache01"
      },
      ..., // all valid fields in record, table based on association type
    }, 
    { // next record found }, ... // and so on
  ]
}

Change Management - GET /sn_chg_rest/change/{sys_id}/conflict

Retrieves the status of the currently running change request conflict checking process or the results of the last completed conflict checking process for the specified change request.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{sys_id}/conflict

Default URL: /api/sn_chg_rest/change/{sys_id}/conflict

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 79. Path parameters
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
sys_id Sys_id of the change request for which to return the status of the running/completed conflict checking process.

Data type: String

Table: Change Request [change_request]
Table 80. Query parameters
Name Description
None
Table 81. Request body parameters (XML or JSON)
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.

Table 82. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 83. Response headers
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.

Table 84. Status codes
Status code Description
200 Current status of the conflict checking process; including conflicts if any are detected.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
conflicts List of conflicts found for the change request. An empty object indicates that no conflicts were detected.

Data type: Array
job_status Status of the actual conflict checking job.

Data type: String
last_run Date and time the last conflict checking process started.

Data type: String
record_count Number of records checked.

Data type: String
status Outcome of the conflict checking process, such as "Conflict" or "Not run".
Note: Even if the change request does not have any conflicts, this field is set to "Conflict." However, the conflicts object is empty.

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/0f4ac6c4b750230096c3e4f6ee11a9fe/conflict" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

Successful response - no conflicts

{
  result: {
    status: "Conflict",
    last_run": "2018-08-30 12:58:05",
    record_count: "1",
    job_status: "2",
    conflicts: []
  }
}

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/0f4ac6c4b750230096c3e4f6ee11a9fe/conflict" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

Successful response - with conflicts

{
  result: {
    status: "Conflict",
    last_run": "2018-08-30 12:58:05",
    record_count: "1",
    job_status: "2",
    conflicts: [
      {
        change: {
          display_value: "CHG0030001",
          value: "afbffb24b758230096c3e4f6ee11a972"
        },
        type: {
          display_value: "Not In Maintenance Window",
          value: "not_in_maintenance_window"
        }
        ..., // all valid fields in record, example below
      }
    ]
  }
}

Change Management - GET /sn_chg_rest/change/emergency

Retrieves one or more emergency change requests based on the specified criteria.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/emergency

Default URL: /api/sn_chg_rest/change/emergency

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 85. Path parameters
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 86. Query parameters
Name Description
order Field by which to sort the returned change requests.

Data type: String

Default: number
sysparm_limit Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval.

Data type: Number

Default: 500
sysparm_offset Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks.

For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use sysparm_offset=sysparm_offset+sysparm_limit, until you reach the end of all records.

Don't pass a negative number in the sysparm_offset parameter.

Data type: Number

Default: 0
sysparm_query Encoded query used to filter the result set. You can use a UI filter to obtain a properly encoded query.
Syntax: sysparm_query=<col_name><operator><value>.
  • <col_name>: Name of the table column to filter against.
  • <operator>: Supports the following values:
    • =: Exactly matches <value>.
    • !=: Does not match <value>.
    • ^: Logically AND multiple query statements.
    • ^OR: Logically OR multiple query statements.
    • LIKE: <col_name> contains the specified string. Only works for <col_name> fields whose data type is string.
    • STARTSWITH: <col_name> starts with the specified string. Only works for <col_name> fields whose data type is string.
    • ENDSWITH: <col_name> ends with the specified string. Only works for <col_name> fields whose data type is string.
    <value>: Value to match against.
For more operators, see Operators available for filters and queries.

All parameters are case-sensitive. Queries can contain more than one entry, such as sysparm_query=<col_name><operator><value>[<operator><col_name><operator><value>].

For example:

(sysparm_query=caller_id=javascript:gs.getUserID()^active=true)

Encoded queries also support order by functionality. To sort responses based on certain fields, use the ORDERBY and ORDERBYDESC clauses in sysparm_query.

Syntax:
  • ORDERBY<col_name>
  • ORDERBYDESC<col_name>

For example: sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory

This query filters all active records and orders the results in ascending order by number, and then in descending order by category.

If part of the query is invalid, such as by specifying an invalid field name, the instance ignores the invalid part. It then returns rows using only the valid portion of the query. You can control this behavior using the property glide.invalid_query.returns_no_rows. Set this property to true to return no rows on an invalid query.
Note: The glide.invalid_query.returns_no_rows property controls the behavior of all queries across the instance, such as in lists, scripts (GlideRecord.query()), and web service APIs.

Data type: String
key-value pairs Name-value pairs to use to filter the result set. The name is the field on which the specified value is filtered. This parameter is mutually exclusive with sysparm_query. For example, instead of using &sysparm_query=active=true, you can simplify the calling statement by using &active=true. You can also use the display value when the field is a choice or reference type field, such as &state=closed instead of &state=7. To specify multiple key-value pairs, separate each with an ampersand, such as &active=true&assigned_to=john.smith.

Data type: String
textSearch String to use to search all emergency change request record fields. This search uses ServiceNow full text search platform functionality and defaults to IR_AND_OR_QUERY.

Data type: String
Table 87. Request body parameters (XML or JSON)
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.

Table 88. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 89. Response headers
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.

Table 90. Status codes
Status code Description
200 Request completed successfully.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs Values for all fields in the associated change request.

Data type: Object
state State of the change request.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in a UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Sys_id information for the change request.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request to display in a UI.

Data type: String
sys_id.value Sys_id of the change request.

Data type: String
type Type of change request.

Data type: Object

type: {
  display_value: "String",
  value: "String"
}
type.display_value Change type to display in a UI.

Value is always "Emergency".

Data type: String
type.value Internal type value.

Value is always "emergency".

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/emergency?sysparm_query=active=true^ORDERBYnumber" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  result: [
    {
      sys_id: {
        value: "1c87925347c12200e0ef563dbb9a7177",
        display_value: "1c87925347c12200e0ef563dbb9a7177"
      },
      state: {
        value: "-5", 
        display_value: "New"
      },
      type: {
        value: "emergency",
        display_value: "Emergency"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Reboot server",
        display_value: "Reboot server"
      },
    }, 
    { // next record found }, ... // and so on
  ]
}

Change Management - GET /sn_chg_rest/change/emergency/{sys_id}

Retrieves the emergency change request identified by the specified sys_id.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/emergency/{sys_id}

Default URL: /api/sn_chg_rest/change/emergency/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 91. Path parameters
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
sys_id Sys_id of the emergency change request to retrieve.

Data type: String

Table: Change Request [change_request]
Table 92. Query parameters
Name Description
None
Table 93. Request body parameters (XML or JSON)
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.

Table 94. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 95. Response headers
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.

Table 96. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs Values for all fields in the associated change request.

Data type: Object
state State of the change request.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in a UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Sys_id information for the change request.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request to display in a UI.

Data type: String
sys_id.value Sys_id of the change request.

Data type: String
type Type of change request.

Data type: Object

type: {
  display_value: "String",
  value: "String"
}
type.display_value Change type to display in a UI.

Value is always "Emergency".

Data type: String
type.value Internal type value.

Value is always "emergency".

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/emergency/b0dbda5347c12200e0ef563dbb9a718f" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  result: [
    {
      sys_id: {
        value: "b0dbda5347c12200e0ef563dbb9a718f", 
        display_value: "b0dbda5347c12200e0ef563dbb9a718f"
      },
      state: {
        value: "-5", 
        display_value: "New"
      },
      type: {
        value: "emergency",
        display_value: "Emergency"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Reboot server",
        display_value: "Reboot server"
      },
    },
  ]
}

Change Management - GET /sn_chg_rest/change/model

Retrieves one or more change models based on the specified criteria.

Use this endpoint to find a change model that best fits the change request that you are trying to create. For additional information, see Change Models.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/model

Default URL: /api/sn_chg_rest/change/model

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 97. Path parameters
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 98. Query parameters
Name Description
name-value pairs Name-value pairs to use to filter the result set. The name is the field on which the specified value is filtered. This parameter is mutually exclusive with sysparm_query. For example, instead of using &sysparm_query=active=true, you can simplify the calling statement by using &active=true. You can also use the display value when the field is a choice or reference type field, such as &state=closed instead of &state=7. To specify multiple key-value pairs, separate each with an ampersand, such as &active=true&assigned_to=john.smith.

Data type: String
order Field by which to sort the returned change models.

Data type: String

Default: name
sysparm_offset Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks.

For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use sysparm_offset=sysparm_offset+sysparm_limit, until you reach the end of all records.

Don't pass a negative number in the sysparm_offset parameter.

Data type: Number

Default: 0
sysparm_query Encoded query used to filter the result set. You can use a UI filter to obtain a properly encoded query.
Syntax: sysparm_query=<col_name><operator><value>.
  • <col_name>: Name of the table column to filter against.
  • <operator>: Supports the following values:
    • =: Exactly matches <value>.
    • !=: Does not match <value>.
    • ^: Logically AND multiple query statements.
    • ^OR: Logically OR multiple query statements.
    • LIKE: <col_name> contains the specified string. Only works for <col_name> fields whose data type is string.
    • STARTSWITH: <col_name> starts with the specified string. Only works for <col_name> fields whose data type is string.
    • ENDSWITH: <col_name> ends with the specified string. Only works for <col_name> fields whose data type is string.
    <value>: Value to match against.
For more operators, see Operators available for filters and queries.

All parameters are case-sensitive. Queries can contain more than one entry, such as sysparm_query=<col_name><operator><value>[<operator><col_name><operator><value>].

For example:

(sysparm_query=caller_id=javascript:gs.getUserID()^active=true)

Encoded queries also support order by functionality. To sort responses based on certain fields, use the ORDERBY and ORDERBYDESC clauses in sysparm_query.

Syntax:
  • ORDERBY<col_name>
  • ORDERBYDESC<col_name>

For example: sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory

This query filters all active records and orders the results in ascending order by number, and then in descending order by category.

If part of the query is invalid, such as by specifying an invalid field name, the instance ignores the invalid part. It then returns rows using only the valid portion of the query. You can control this behavior using the property glide.invalid_query.returns_no_rows. Set this property to true to return no rows on an invalid query.
Note: The glide.invalid_query.returns_no_rows property controls the behavior of all queries across the instance, such as in lists, scripts (GlideRecord.query()), and web service APIs.

Data type: String
textSearch String to use to search all change model record fields. This search uses ServiceNow full text search platform functionality. For more information on ServiceNow search capabilities, see Search administration.

Data type: String

Default: IR_AND_OR_QUERY
Table 99. Request body parameters (XML or JSON)
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.

Table 100. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 101. Response headers
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.

Table 102. Status codes
Status code Description
200 Request completed successfully.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
result List containing one or more change model record objects. Each object describes a change model. Each element in the change model object corresponds to a field in its associated record in the Change Model [chg_model] table.

All elements contain value and display_value name-value pairs. Some contain display_value_internal name-value pairs.

Data type: Array
result.active Flag that indicates whether the associated change model record is active and available within the instance.
Valid values:
  • true: Change model is active.
  • false: Change model isn't active.

Data type: Boolean

Default: true
result.available_in_ui Flag that indicates whether the associated change model record is available within the user interface.
Valid values:
  • true: Change model is available in the user interface.
  • false: Change model isn't available in the user interface.

Data type: Boolean

Default: true
result.color Color of the associated change model on the change request landing page.

Data type: String

Default: #cbcbcb
result.default_change_model Flag that indicates whether the associated change model record is the default change model.
Valid values:
  • true: Default
  • false: Not the default

Data type: Boolean

Default: false
result.description Short description of the purpose of the change model.

Data type: String

Maximum length: 4,000
result.name Name of the change model.

Data type: String

Maximum length: 200
result.record_preset Name-value pairs of the fields that should automatically be populated, with their associated values, when a new change request record is created. Values are separated by caret symbols.

For example:

"type=normal^assignment_group=a715cd759f2002002920bde8132e7018^short_description=Automated : Change^EQ"

Data type: String
result.state_field Choice list field from which to collect choices, based on the provided in table_name. For change models, this is always set to "state".

Data type: String
result.sys_class_name Change module table name. Always Change Model/chg_model.

Data type: String
result.sys_created_by Name of the user that initially created the associated change module record.

Data type: String
result.sys_created_on Date and time that the change module record was originally created.

Data type: String
result.sys_domain If using domains in the instance, the name of the domain to which the change module record is associated.

Data type: String
result.sys_domain_path If using domains in the instance, the domain path in which the associated change module record resides.

Data type: String
result.sys_id Unique identifier of the associated change model record.

Data type: String
result.sys_mod_count Number of times that the associated change model record has been modified.

Data type: Number
result.sys_name Name of the change model. Always the same as the name parameter.

Data type: String
result.sys_tags System tags associated with the change model record.

Data type: String
result.sys_updated_by Name of the user that last updated the associated change model record.

Data type: String

Maximum length: 40
result.sys_updated_on Date and time the associated change model record was last updated.

Data type: String
result.table_name Table that defines the Choice list field from which to collect choices. For change models this is always set to "change_request".

Data type: String

Maximum length: 80

Example: cURL request

This example shows a request for obtaining all change model records.

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/model \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

For brevity, this response only shows a single change model object.

{
  "result": [
    {
      "record_preset": {
        "display_value": "type=normal^assignment_group=a715cd759f2002002920bde8132e7018^short_description=Automated : Change^EQ",
        "value": "type=normal^assignment_group=a715cd759f2002002920bde8132e7018^short_description=Automated : Change^EQ"
      },
      "color": {
        "display_value": "#488df4",
        "value": "#488df4"
      },
      "default_change_model": {
        "display_value": "false",
        "value": false
      },
      "sys_mod_count": {
        "display_value": "6",
        "value": 6.0
      },
      "description": {
        "display_value": "This model is intended to capture  a record of an automated change.  There are no approvals associated with this change model.\r\n",
        "value": "This model is intended to capture  a record of an automated change.  There are no approvals associated with this change model.\r\n"
      },
      "active": {
        "display_value": "true",
        "value": true
      },
      "sys_updated_on": {
        "display_value": "2020-10-02 06:24:24",
        "value": "2020-10-02 13:24:24",
        "display_value_internal": "2020-10-02 06:24:24"
      },
      "sys_tags": {
        "display_value": "",
        "value": ""
      },
        "table_name": {
        "display_value": "change_request",
        "value": "change_request"
      },
      "sys_class_name": {
        "display_value": "Change Model",
        "value": "chg_model"
      },
      "sys_id": {
        "display_value": "7840d2515323101034d1ddeeff7b12a6",
        "value": "7840d2515323101034d1ddeeff7b12a6"
      },
      "sys_updated_by": {
        "display_value": "admin",
        "value": "admin"
      },
      "available_in_ui": {
        "display_value": "false",
        "value": false
      },
      "state_field": {
        "display_value": "state",
        "value": "state"
      },
      "sys_created_on": {
        "display_value": "2020-09-28 07:33:25",
        "value": "2020-09-28 14:33:25",
        "display_value_internal": "2020-09-28 07:33:25"
      },
      "name": {
        "display_value": "Change Registration",
        "value": "Change Registration"
      },
      "sys_name": {
        "display_value": "Change Registration",
        "value": "Change Registration"
      },
      "sys_created_by": {
        "display_value": "admin",
        "value": "admin"
      }
    }
  ]
}

Change Management - GET /sn_chg_rest/change/model/{sys_id}

Retrieves the change model identified by the specified sys_id.

You can then use this change model to create the desired change request. For additional information on change models, see Change Models.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/model/{sys_id}

Default URL: /api/sn_chg_rest/change/model/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 103. Path parameters
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
sys_id Sys_id of the change model record to retrieve from the Change Model [chg_model] table.

Data type: String
Table 104. Query parameters
Name Description
None
Table 105. Request body parameters (XML or JSON)
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.

Table 106. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 107. Response headers
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.

Table 108. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
result Requested change model record object. Each element in this object corresponds to a field in the record in the Change Model [chg_model] table.

All elements contain value and display_value name-value pairs. Some contain display_value_internal name-value pairs.

Data type: Object
result.active Flag that indicates whether the associated change model record is active and available within the instance.
Valid values:
  • true: Change model is active.
  • false: Change model isn't active.

Data type: Boolean

Default: true
result.available_in_ui Flag that indicates whether the associated change model record is available within the user interface.
Valid values:
  • true: Change model is available in the user interface.
  • false: Change model isn't available in the user interface.

Data type: Boolean

Default: true
result.color Color of the associated change model on the change request landing page.

Data type: String

Default: #cbcbcb
result.default_change_model Flag that indicates whether the associated change model record is the default change model.
Valid values:
  • true: Default
  • false: Not the default

Data type: Boolean

Default: false
result.description Short description of the purpose of the change model.

Data type: String

Maximum length: 4,000
result.name Name of the change model.

Data type: String

Maximum length: 200
result.record_preset Name-value pairs of the fields that should automatically be populated, with their associated values, when a new change request record is created. Values are separated by caret symbols.

For example:

"type=normal^assignment_group=a715cd759f2002002920bde8132e7018^short_description=Automated : Change^EQ"

Data type: String
result.state_field Choice list field from which to collect choices, based on the provided in table_name. For change models, this is always set to "state".

Data type: String
result.sys_class_name Change module table name. Always Change Model/chg_model.

Data type: String
result.sys_created_by Name of the user that initially created the associated change module record.

Data type: String
result.sys_created_on Date and time that the change module record was originally created.

Data type: String
result.sys_domain If using domains in the instance, the name of the domain to which the change module record is associated.

Data type: String
result.sys_domain_path If using domains in the instance, the domain path in which the associated change module record resides.

Data type: String
result.sys_id Unique identifier of the associated change model record.

Data type: String
result.sys_mod_count Number of times that the associated change model record has been modified.

Data type: Number
result.sys_name Name of the change model. Always the same as the name parameter.

Data type: String
result.sys_tags System tags associated with the change model record.

Data type: String
result.sys_updated_by Name of the user that last updated the associated change model record.

Data type: String

Maximum length: 40
result.sys_updated_on Date and time the associated change model record was last updated.

Data type: String
result.table_name Table that defines the Choice list field from which to collect choices. For change models this is always set to "change_request".

Data type: String

Maximum length: 80

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/model/c0efda5347c12200e0ef563dbb9a81e3" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": {
    "record_preset": {
      "display_value": "type=emergency^EQ",
      "value": "type=emergency^EQ"
    },
    "color": {
      "display_value": "#ea3423",
      "value": "#ea3423"
    },
    "default_change_model": {
      "display_value": "false",
      "value": false
    },
    "sys_mod_count": {
      "display_value": "2",
      "value": 2.0
    },
    "description": {
      "display_value": "ITIL Mode 1 Emergency Change",
      "value": "ITIL Mode 1 Emergency Change"
    },
    "active": {
      "display_value": "true",
      "value": true
    },
    "sys_updated_on": {
      "display_value": "2020-09-28 08:53:12",
      "value": "2020-09-28 15:53:12",
      "display_value_internal": "2020-09-28 08:53:12"
    },
    "sys_tags": {
      "display_value": "",
      "value": ""
    },
    "table_name": {
      "display_value": "change_request",
      "value": "change_request"
    },
    "sys_class_name": {
      "display_value": "Change Model",
      "value": "chg_model"
    },
    "sys_id": {
      "display_value": "c0efda5347c12200e0ef563dbb9a81e3",
      "value": "c0efda5347c12200e0ef563dbb9a81e3"
    },
    "sys_updated_by": {
      "display_value": "admin",
      "value": "admin"
    },
    "available_in_ui": {
      "display_value": "true",
      "value": true
    },
    "state_field": {
      "display_value": "state",
      "value": "state"
    },
    "sys_created_on": {
      "display_value": "2020-09-04 09:16:03",
      "value": "2020-09-04 16:16:03",
      "display_value_internal": "2020-09-04 09:16:03"
    },
    "name": {
      "display_value": "Emergency",
      "value": "Emergency"
    },
    "sys_name": {
      "display_value": "Emergency",
      "value": "Emergency"
    },
    "sys_created_by": {
      "display_value": "admin",
      "value": "admin"
    }
  }
}

Change Management - GET /sn_chg_rest/change/normal

Retrieves one or more normal change requests based on the specified criteria.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/normal

Default URL: /api/sn_chg_rest/change/normal

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 109. Path parameters
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 110. Query parameters
Name Description
name-value pairs Name-value pairs to use to filter the result set. The name is the field on which the specified value is filtered. This parameter is mutually exclusive with sysparm_query. For example, instead of using &sysparm_query=active=true, you can simplify the calling statement by using &active=true. You can also use the display value when the field is a choice or reference type field, such as &state=closed instead of &state=7. To specify multiple key-value pairs, separate each with an ampersand, such as &active=true&assigned_to=john.smith.

Data type: String
order Field by which to sort the returned change requests.

Data type: String
sysparm_limit Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval.

Data type: Number

Default: 500
sysparm_offset Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks.

For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use sysparm_offset=sysparm_offset+sysparm_limit, until you reach the end of all records.

Don't pass a negative number in the sysparm_offset parameter.

Data type: Number

Default: 0
sysparm_query Encoded query used to filter the result set. You can use a UI filter to obtain a properly encoded query.
Syntax: sysparm_query=<col_name><operator><value>.
  • <col_name>: Name of the table column to filter against.
  • <operator>: Supports the following values:
    • =: Exactly matches <value>.
    • !=: Does not match <value>.
    • ^: Logically AND multiple query statements.
    • ^OR: Logically OR multiple query statements.
    • LIKE: <col_name> contains the specified string. Only works for <col_name> fields whose data type is string.
    • STARTSWITH: <col_name> starts with the specified string. Only works for <col_name> fields whose data type is string.
    • ENDSWITH: <col_name> ends with the specified string. Only works for <col_name> fields whose data type is string.
    <value>: Value to match against.
For more operators, see Operators available for filters and queries.

All parameters are case-sensitive. Queries can contain more than one entry, such as sysparm_query=<col_name><operator><value>[<operator><col_name><operator><value>].

For example:

(sysparm_query=caller_id=javascript:gs.getUserID()^active=true)

Encoded queries also support order by functionality. To sort responses based on certain fields, use the ORDERBY and ORDERBYDESC clauses in sysparm_query.

Syntax:
  • ORDERBY<col_name>
  • ORDERBYDESC<col_name>

For example: sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory

This query filters all active records and orders the results in ascending order by number, and then in descending order by category.

If part of the query is invalid, such as by specifying an invalid field name, the instance ignores the invalid part. It then returns rows using only the valid portion of the query. You can control this behavior using the property glide.invalid_query.returns_no_rows. Set this property to true to return no rows on an invalid query.
Note: The glide.invalid_query.returns_no_rows property controls the behavior of all queries across the instance, such as in lists, scripts (GlideRecord.query()), and web service APIs.

Data type: String
textSearch String to use to search all normal change request record fields. This search uses ServiceNow full text search platform functionality and defaults to IR_AND_OR_QUERY.

Data type: String
Table 111. Request body parameters (XML or JSON)
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.

Table 112. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 113. Response headers
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.

Table 114. Status codes
Status code Description
200 Request completed successfully.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs Values for all fields in the associated change request.

Data type: Object
state State of the change request prior to the delete.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in a UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Sys_id information for the change request.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request to display in a UI.

Data type: String
sys_id.value Sys_id of the change request.

Data type: String
type Type of change request.

Data type: Object

type: {
  display_value: "String",
  value: "String"
}
type.display_value Change type to display in a UI.

Value is always "Normal".

Data type: String
type.value Internal type value.

Value is always "normal".

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/normal?sysparm_query=active=true^ORDERBYnumber" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
  result: [
    {
      sys_id: {
        value: "1c87925347c12200e0ef563dbb9a7177",
        display_value: "1c87925347c12200e0ef563dbb9a7177"
      },
      state: {
        value: "-5", 
        display_value: "New"
      },
      type: {
        value: "normal",
        display_value: "Normal"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Add network switch to cabinet",
        display_value: "Add network switch to cabinet"
      },
    },
    { // next record found }, ... // and so on
  ]
}

Change Management - GET /sn_chg_rest/change/normal/{sys_id}

Retrieves the normal change request identified by the specified sys_id.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/normal/{sys_id}

Default URL: /api/sn_chg_rest/change/normal/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 115. Path parameters
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
sys_id Sys_id of the normal change request to retrieve.

Data type: String

Table: Change Request [change_request]
Table 116. Query parameters
Name Description
None
Table 117. Request body parameters (XML or JSON)
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.

Table 118. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 119. Response headers
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.

Table 120. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs Values for all fields in the associated change request.

Data type: Object
state State of the change request prior to the delete.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in a UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Sys_id of the change request.

Data type: String
type Type of change request.

Data type: Object

type: {
  display_value: "String",
  value: "String"
}
type.display_value Change type to display in a UI.

Value is always "Normal".

Data type: String
type.value Internal type value.

Value is always "normal".

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/normal/b0dbda5347c12200e0ef563dbb9a718f" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  result: [
    {
      sys_id: "b0dbda5347c12200e0ef563dbb9a718f",
      state: {
        value: "-5", 
        display_value: "New"
      },
      type: {
        value: "normal",
        display_value: "Normal"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Add network switch to cabinet",
        display_value: "Add network switch to cabinet"
      },
    },
  ]
}

Change Management - GET /sn_chg_rest/change/standard

Retrieves one or more standard change requests based on the specified criteria.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/standard

Default URL: /api/sn_chg_rest/change/standard

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 121. Path parameters
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 122. Query parameters
Name Description
name-value pairs Name-value pairs to use to filter the result set. The name is the field on which the specified value is filtered. This parameter is mutually exclusive with sysparm_query. For example, instead of using &sysparm_query=active=true, you can simplify the calling statement by using &active=true. You can also use the display value when the field is a choice or reference type field, such as &state=closed instead of &state=7. To specify multiple key-value pairs, separate each with an ampersand, such as &active=true&assigned_to=john.smith.

Data type: String
order Field by which to sort the returned change requests.

Data type: String
sysparm_limit Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval.

Data type: String

Default: 500
sysparm_offset Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks.

For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use sysparm_offset=sysparm_offset+sysparm_limit, until you reach the end of all records.

Don't pass a negative number in the sysparm_offset parameter.

Data type: Number

Default: 0
sysparm_query Encoded query used to filter the result set. You can use a UI filter to obtain a properly encoded query.
Syntax: sysparm_query=<col_name><operator><value>.
  • <col_name>: Name of the table column to filter against.
  • <operator>: Supports the following values:
    • =: Exactly matches <value>.
    • !=: Does not match <value>.
    • ^: Logically AND multiple query statements.
    • ^OR: Logically OR multiple query statements.
    • LIKE: <col_name> contains the specified string. Only works for <col_name> fields whose data type is string.
    • STARTSWITH: <col_name> starts with the specified string. Only works for <col_name> fields whose data type is string.
    • ENDSWITH: <col_name> ends with the specified string. Only works for <col_name> fields whose data type is string.
    <value>: Value to match against.
For more operators, see Operators available for filters and queries.

All parameters are case-sensitive. Queries can contain more than one entry, such as sysparm_query=<col_name><operator><value>[<operator><col_name><operator><value>].

For example:

(sysparm_query=caller_id=javascript:gs.getUserID()^active=true)

Encoded queries also support order by functionality. To sort responses based on certain fields, use the ORDERBY and ORDERBYDESC clauses in sysparm_query.

Syntax:
  • ORDERBY<col_name>
  • ORDERBYDESC<col_name>

For example: sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory

This query filters all active records and orders the results in ascending order by number, and then in descending order by category.

If part of the query is invalid, such as by specifying an invalid field name, the instance ignores the invalid part. It then returns rows using only the valid portion of the query. You can control this behavior using the property glide.invalid_query.returns_no_rows. Set this property to true to return no rows on an invalid query.
Note: The glide.invalid_query.returns_no_rows property controls the behavior of all queries across the instance, such as in lists, scripts (GlideRecord.query()), and web service APIs.

Data type: String
textSearch String to use to search all standard change request record fields. This search uses ServiceNow full text search platform functionality and defaults to IR_AND_OR_QUERY.

Data type: String
Table 123. Request body parameters (XML or JSON)
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.

Table 124. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 125. Response headers
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.

Table 126. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs All fields (key) with their associated values for the identified change request.

Data type: Object
state State of the change request prior to the delete.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in a UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Sys_id information for the change request.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request to display in a UI.

Data type: String
sys_id.value Sys_id of the change request.

Data type: String
type Type of change request.

Data type: Object

type: {
  display_value: "String",
  value: "String"
}
type.display_value Change type to display in a UI.

Value is always "Standard".

Data type: String
type.value Internal type value.

Value is always "standard".

Data type: String

Example: Sample cURL request

curl "https://instance.service-now.com/api/sn_chg_rest/v1/change/standard?sysparm_query=active=true^ORDERBYnumber" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
  result: [
    {
      sys_id: {
        value: "1c87925347c12200e0ef563dbb9a7177",
        display_value: "1c87925347c12200e0ef563dbb9a7177"
      },
      state: {
        value: "-5", 
        display_value: "New"
      },
      type: {
        value: "standard",
        display_value: "Standard"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Add network switch to cabinet",
        display_value: "Add network switch to cabinet"
      },
    }, 
    { // next record found }, ... // and so on
  ]
}

Change Management - GET /sn_chg_rest/change/standard/{sys_id}

Retrieves the standard change request identified by the specified sys_id.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/standard/{sys_id}

Default URL: /api/sn_chg_rest/change/standard/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 127. Path parameters
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
sys_id Sys_id of the standard change request to retrieve.

Data type: String

Table: Change Request [change_request]
Table 128. Query parameters
Name Description
None
Table 129. Request body parameters (XML or JSON)
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.

Table 130. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 131. Response headers
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.

Table 132. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs All fields (key) with their associated values for the identified change request.

Data type: Object
state State of the change request prior to the delete.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in a UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Sys_id information for the change request.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request to display in a UI.

Data type: String
sys_id.value Sys_id of the change request.

Data type: String

Example: cURL request

curl "https://https://instance.servicenow.com/api/sn_chg_rest/v1/change/standard/b0dbda5347c12200e0ef563dbb9a718f" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
  result: [
    {
      sys_id: {
        value: "1c87925347c12200e0ef563dbb9a7177",
        display_value: "1c87925347c12200e0ef563dbb9a7177"
      },
      state: {
        value: "-5", 
        display_value: "New"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Add network switch to cabinet",
        display_value: "Add network switch to cabinet"
      },
    }, 
  ]
}

Change Management - GET /sn_chg_rest/change/standard/template

Retrieves one or more standard change templates based on the specified criteria.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/standard/template

Default URL: /api/sn_chg_rest/change/standard/template

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 133. Path parameters
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 134. Query parameters
Name Description
name-value pairs Name-value pairs to use to filter the result set. The name is the field on which the specified value is filtered. This parameter is mutually exclusive with sysparm_query. For example, instead of using &sysparm_query=active=true, you can simplify the calling statement by using &active=true. You can also use the display value when the field is a choice or reference type field, such as &state=closed instead of &state=7. To specify multiple key-value pairs, separate each with an ampersand, such as &active=true&assigned_to=john.smith.

Data type: String
order Field by which to sort the returned standard change templates.

Data type: String

Default: Number
sysparm_limit Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval.

Data type: Number

Default: 500
sysparm_offset Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks.

For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use sysparm_offset=sysparm_offset+sysparm_limit, until you reach the end of all records.

Don't pass a negative number in the sysparm_offset parameter.

Data type: Number

Default: 0
sysparm_query Encoded query used to filter the result set. You can use a UI filter to obtain a properly encoded query.
Syntax: sysparm_query=<col_name><operator><value>.
  • <col_name>: Name of the table column to filter against.
  • <operator>: Supports the following values:
    • =: Exactly matches <value>.
    • !=: Does not match <value>.
    • ^: Logically AND multiple query statements.
    • ^OR: Logically OR multiple query statements.
    • LIKE: <col_name> contains the specified string. Only works for <col_name> fields whose data type is string.
    • STARTSWITH: <col_name> starts with the specified string. Only works for <col_name> fields whose data type is string.
    • ENDSWITH: <col_name> ends with the specified string. Only works for <col_name> fields whose data type is string.
    <value>: Value to match against.
For more operators, see Operators available for filters and queries.

All parameters are case-sensitive. Queries can contain more than one entry, such as sysparm_query=<col_name><operator><value>[<operator><col_name><operator><value>].

For example:

(sysparm_query=caller_id=javascript:gs.getUserID()^active=true)

Encoded queries also support order by functionality. To sort responses based on certain fields, use the ORDERBY and ORDERBYDESC clauses in sysparm_query.

Syntax:
  • ORDERBY<col_name>
  • ORDERBYDESC<col_name>

For example: sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory

This query filters all active records and orders the results in ascending order by number, and then in descending order by category.

If part of the query is invalid, such as by specifying an invalid field name, the instance ignores the invalid part. It then returns rows using only the valid portion of the query. You can control this behavior using the property glide.invalid_query.returns_no_rows. Set this property to true to return no rows on an invalid query.
Note: The glide.invalid_query.returns_no_rows property controls the behavior of all queries across the instance, such as in lists, scripts (GlideRecord.query()), and web service APIs.

Data type: String
textSearch String to use to search all standard change request record fields. This search uses ServiceNow full text search platform functionality and defaults to IR_AND_OR_QUERY.

Data type: String
Table 135. Request body parameters (XML or JSON)
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.

Table 136. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 137. Response headers
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.

Table 138. Status codes
Status code Description
200 Request completed successfully.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs All fields with their associated values for the identified standard change template.

Data type: Object
sys_id Sys_id information for the change request.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request to display in a UI.

Data type: String
sys_id.value Sys_id of the change request.

Data type: String
template Information about the standard change template.

Data type: Object

template: {
  display_value: "String", 
  value: "String"
}
template.display_value Template information to display in the UI.

Data type: String
template.value Template sys_id.

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/standard/template?sysparm_query=active=true^ORDERBYnumber" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  result: [
    {
      sys_id: {
        value: "92b8544047810200e90d87e8dee490b0",
        display_value: "92b8544047810200e90d87e8dee490b0"
      },
      template : {
        value: "1c8e02ec47410200e90d87e8dee49057", 
        display_value: "Add network switch to datacenter cabinet"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Standard change template to add network switch to cabinet",
        display_value: "Standard change template to add network switch to cabinet"
      },
    }, 
    { // next record found }, ... // and so on
  ]
}

Change Management - GET /sn_chg_rest/change/standard/template/{sys_id}

Retrieves the standard change template identified by the specified sys_id.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/standard/template/{sys_id}

Default URL: /api/sn_chg_rest/change/standard/template/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 139. Path parameters
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
sys_id Sys_id of the standard change template to retrieve.

Data type: String

Table: Standard Change Template [std_change_record_producer]
Table 140. Query parameters
Name Description
None
Table 141. Request body parameters (XML or JSON)
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.

Table 142. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 143. Response headers
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.

Table 144. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs All fields with their associated values for the identified standard change template.

Data type: Object
sys_id Sys_id of the change request.

Data type: String
template Information about the standard change template.

Data type: Object

template: {
  display_value: "String", 
  value: "String"
}
template.display_value Template information to display in a UI.

Data type: String
template.value Template sys_id.

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/standard/template/92b8544047810200e90d87e8dee490b0" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
  result: [
    {
      sys_id: "92b8544047810200e90d87e8dee490b0",
      template : {
        value: "1c8e02ec47410200e90d87e8dee49057", 
        display_value: "Add network switch to datacenter cabinet"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Standard change template to add network switch to cabinet",
        display_value: "Standard change template to add network switch to cabinet"
      },
    }, 
  ]
}

Change Management - GET /sn_chg_rest/change/worker/{sys_id}

Retrieves the current status, information, and errors for the specified asynchronous worker.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/worker/{sys_id}

Default URL: /api/sn_chg_rest/{change/worker/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 145. Path parameters
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
sys_id Sys_id of the change management asynchronous worker.

Data type: String

Table: Change Management Worker [chg_mgt_worker]
Table 146. Query parameters
Name Description
None
Table 147. Request body parameters (XML or JSON)
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.

Table 148. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 149. Response headers
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.

Table 150. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Name Description
messages Message information.
Data type: Object
"messages": {
  "errorMessages": [Array],
  "infoMessages": [Array],
  "warningMessages": [Array]
}
messages.errorMessages Error messages encountered while processing the request. For example: 
Invalid CMDB_CI sys_id provided

Data type: Array
messages.infoMessages Information messages encountered while processing the request. For example: 
CMDB_CI sys_id already associated to provided.

Data type: Array
messages.warningMessages Warning messages encountered while processing the request. For example: 
Invalid CMDB_CI sys_id provided.

Data type: Array
payload Unique payload provided when using a worker sys_id from the successful response body of a scheduling endpoint.
"payload": {
  "spans": [Array]
}

Data type: Object
payload.spans If a timespan is available within the duration provided in the schedule endpoint, the worker API lists the available time spans.
"payload": {
  "spans": [
   {
    "end": {Object}, 
    "start": {Object}
   }
  ]
}

Data type: Array
payload.spans.start 
"start": {
  "display_value": "String",
  "value": "String"
}

Data type: Object
payload.spans.start.value Date and time that the change request is planned to start implementation.

Data type: String
payload.spans.start.display_value Displays the value of the change request start time.

Time format: yyyy-mm-dd hh:mm:ss

Data type: String
payload.spans.end 
"end": {
  "display_value": "String",
  "value": "String"
}

Data type: Object
payload.spans.end.value Date and time that the change request is planned for completion.

Time format: yyyy-mm-dd hh:mm:ss

Data type: String
payload.spans.end.display_value Displays the value of the change request completion time.

Data type: String
request Original endpoint request.

Data type: String
state Information on the current state of the worker.

Data type: Object

state: {
  display_value: "String", 
  value: Number
}
state.display_value Display value of the state of the worker. These values directly correlate to the state.value parameter.

Possible values:

  • Complete
  • Error
  • In-Progress
  • Waiting

Data type: String
state.value Numeric value of the state of the worker.

Possible values:

  • 1
  • 2
  • 3
  • 4

Data type: Number
type Type of association between the CMDB CI and the change request.

Data type: String
worker Information about the associated worker.

Data type: Object

"worker": {
  "link": "String",
  "sysId": "String"
}
worker.link URL to retrieve the status of the associated worker and other worker pertinent information.

Data type: String
worker.sysId Sys_id of the worker associated with the change request.

Data type: String
<other_params> Other parameters that are process-specific, such as ignored_cmdb_ci_sys_ids.

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/worker/0644cd02dbec330084f07ffdbf9619c1" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
  "result": {
    "worker": {
      "sysId": "0644cd02dbec330084f07ffdbf9619c1",
      "link": "https://instance.service-now.com/api/sn_chg_rest/change/worker/0644cd02dbec330084f07ffdbf9619c1"
    },
    "request": "{\"task\":\"c286d61347c12200e0ef563dbb9a71df\"}",
    "state": {
      "value": 3,
      "display_value": "Complete"
    },
    "type": "impacted",
    "messages": {
      "errorMessages": [],
      "warningMessages": [],
      "infoMessages": []
    }
  }
}

Change Management - PATCH /sn_chg_rest/change/{sys_id}

Updates the change request identified by the specified sys_id with the key-value pairs in the request body or URL.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{sys_id}

Default URL: /api/sn_chg_rest/change/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 151. Path parameters
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
sys_id Sys_id of the change request to modify.

Data type: String

Table: Change Request [change_request]
Table 152. Query parameters
Name Description
name-value pairs Name-value pairs representing the fields to update. Request body parameters override URL parameters. However, required parameters must be specified in the URL.

Data type: String
encrypted_fields List of comma-separated fields to encrypt. These fields are encrypted before they are stored in the associated record. When specified, the endpoint calls the GlideRecord setDisplayValue() method, instead of calling the setValue() method.

Because of this, you can also use this parameter to pass display values for non-encrypted fields, such as reference or choice fields, instead of passing sys_ids or values.

Data type: String
Table 153. Request body parameters (XML or JSON)
Name Description
data Name-value pairs representing the field(s) to update in the associated change request. For example, to update the short description file, enter a name-value pair similar to the following: --data "{\"short_description\": \"my short desc\" }" \.

Data type: String
encrypted_fields List of comma-separated fields to encrypt. These fields are encrypted before they are stored in the associated record. When specified, the endpoint calls the GlideRecord setDisplayValue() method, instead of calling the setValue() method.

Because of this, you can also use this parameter to pass display values for non-encrypted fields, such as reference or choice fields, instead of passing sys_ids or values.

Data type: String

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.

Table 154. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 155. Response headers
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.

Table 156. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
result Updated change request record. Each element in this object corresponds to a field in the record in the Change Request [change_request] table.

All elements contain value and display_value name-value pairs. Some contain display_value_internal name-value pairs.

Data type: Object

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/b0dbda5347c12200e0ef563dbb9a718f" \
--request PATCH \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data "{\"short_desription\": \"Reboot the server at 6 am\" }" \
--user "username":"password"
{
  "result":
    {
      "reason": {
        "display_value": "",
        "value": ""
      },
      "parent": {
        "display_value": "",
        "value": ""
      },
      "watch_list": {
        "display_value": "",
        "value": ""
       },
       "proposed_change": {
         "display_value": "",
         "value": ""
       },
       "upon_reject": {
         "display_value": "Cancel all future Tasks",
         "value": "cancel"
       },
       "sys_updated_on": {
         "display_value": "2015-07-06 11:59:27",
         "value": "2015-07-06 18:59:27",
         "display_value_internal": "2015-07-06 11:59:27"
      },
      "type": {
        "display_value": "Standard",
        "value": "standard"
      },
      "approval_history": {
        "display_value": "",
        "value": ""
      },
      "skills": {
        "display_value": "",
        "value": ""
      },
      "test_plan": {
        "display_value": "--Confirm that there are no monitoring alerts for the router",
        "value": "--Confirm that there are no monitoring alerts for the router"
      },
      "number": {
        "display_value": "CHG0000024",
        "value": "CHG0000024"
      },
      "is_bulk": {
        "display_value": "false",
        "value": false
      },
      "cab_delegate": {
        "display_value": "",
        "value": ""
      },
      "requested_by_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "ci_class": {
        "display_value": "cmdb_ci",
        "value": "cmdb_ci"
      },
      "state": {
        "display_value": "Closed",
        "value": 3.0
      },
      "sys_created_by": {
        "display_value": "admin",
        "value": "admin"
      },
      "knowledge": {
        "display_value": "false",
        "value": false
      },
      "order": {
        "display_value": "",
        "value": ""
      },
      "phase": {
        "display_value": "Requested",
        "value": "requested"
      },
      "cmdb_ci": {
        "display_value": "",
        "value": ""
      },
      "delivery_plan": {
        "display_value": "",
        "value": ""
      },
      "impact": {
        "display_value": "3 - Low",
        "value": 3.0
      },
      "contract": {
        "display_value": "",
        "value": ""
      },
      "active": {
        "display_value": "false",
        "value": false
      },
      "work_notes_list": {
        "display_value": "",
        "value": ""
      },
      "priority": {
        "display_value": "4 - Low",
        "value": 4.0
      },
      "sys_domain_path": {
        "display_value": "/",
        "value": "/"
      },
      "cab_recommendation": {
        "display_value": "",
        "value": ""
      },
      "production_system": {
        "display_value": "false",
        "value": false
      },
      "rejection_goto": {
        "display_value": "",
        "value": ""
      },
      "review_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "requested_by": {
        "display_value": "System Administrator",
        "value": "6816f79cc0a8016401c5a33be04be441"
      },
      "business_duration": {
        "display_value": "",
        "value": ""
      },
      "group_list": {
        "display_value": "",
        "value": ""
      },
      "change_plan": {
        "display_value": "",
        "value": ""
      },
      "approval_set": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "wf_activity": {
        "display_value": "",
        "value": ""
      },
      "implementation_plan": {
        "display_value": "-- Place router into maintenance mode in the monitoring platform\r\n-- Logon to router through SSH\r\n-- Run the following command\r\n\r\nrouter(config-router)#router bgp 12345\r\nrouter(config-router)#neighbor {neighbor ip} soft-reconfig [inbound]\r\nrouter#clear ip bgp {neighbor ip} soft in\r\n\r\n-- Confirm the sessions have been cleared\r\n-- Place router back into operational mode in the monitoring platform",
        "value": "-- Place router into maintenance mode in the monitoring platform\r\n-- Logon to router through SSH\r\n-- Run the following command\r\n\r\nrouter(config-router)#router bgp 12345\r\nrouter(config-router)#neighbor {neighbor ip} soft-reconfig [inbound]\r\nrouter#clear ip bgp {neighbor ip} soft in\r\n\r\n-- Confirm the sessions have been cleared\r\n-- Place router back into operational mode in the monitoring platform"
      },
      "universal_request": {
        "display_value": "",
        "value": ""
      },
      "end_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "short_description": {
        "display_value": "Reboot the server at 6 am",
        "value": "Reboot the server at 6 am"
      },
      "correlation_display": {
        "display_value": "",
        "value": ""
      },
      "work_start": {
        "display_value": "2015-07-06 11:56:04",
        "value": "2015-07-06 18:56:04",
        "display_value_internal": "2015-07-06 11:56:04"
      },
      "delivery_task": {
        "display_value": "",
        "value": ""
      },
      "outside_maintenance_schedule": {
        "display_value": "false",
        "value": false
      },
      "additional_assignee_list": {
        "display_value": "",
        "value": ""
      },
      "std_change_producer_version": {
        "display_value": "Clear BGP sessions on a Cisco router - 1",
        "value": "16c2273c47010200e90d87e8dee49006"
      },
      "sys_class_name": {
        "display_value": "Change Request",
        "value": "change_request"
      },
      "service_offering": {
        "display_value": "",
        "value": ""
      },
      "closed_by": {
        "display_value": "System Administrator",
        "value": "6816f79cc0a8016401c5a33be04be441"
      },
      "follow_up": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "review_status": {
        "display_value": "",
        "value": ""
      },
      "reassignment_count": {
        "display_value": "2",
        "value": 2.0
      },
      "start_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "assigned_to": {
        "display_value": "",
        "value": ""
      },
      "variables": {
        "display_value": "variable_pool",
        "value": "variable_pool"
      },
      "sla_due": {
        "display_value": "UNKNOWN",
        "value": "",
        "display_value_internal": ""
      },
      "comments_and_work_notes": {
        "display_value": "",
        "value": ""
      },
      "escalation": {
        "display_value": "Normal",
        "value": 0.0
      },
      "upon_approval": {
        "display_value": "Proceed to Next Task",
        "value": "proceed"
      },
      "correlation_id": {
        "display_value": "",
        "value": ""
      },
      "made_sla": {
        "display_value": "true",
        "value": true
      },
      "backout_plan": {
        "display_value": "Due to the limited number of commands in the implementation plan it is not possible to backout the change.\r\n\r\nIf required you are authorized to reboot the router if BGP fails to work",
        "value": "Due to the limited number of commands in the implementation plan it is not possible to backout the change.\r\n\r\nIf required you are authorized to reboot the router if BGP fails to work"
      },
      "conflict_status": {
        "display_value": "Not Run",
        "value": "Not Run"
      },
      "task_effective_number": {
        "display_value": "CHG0000024",
        "value": "CHG0000024"
      },
      "sys_updated_by": {
        "display_value": "admin",
        "value": "admin"
      },
      "opened_by": {
        "display_value": "System Administrator",
        "value": "6816f79cc0a8016401c5a33be04be441"
      },
      "user_input": {
        "display_value": "",
        "value": ""
      },
      "sys_created_on": {
        "display_value": "2015-07-06 11:55:46",
        "value": "2015-07-06 18:55:46",
        "display_value_internal": "2015-07-06 11:55:46"
      },
      "on_hold_task": {
        "display_value": "",
        "value": ""
      },
      "sys_domain": {
        "display_value": "global",
        "value": "global"
      },
      "route_reason": {
        "display_value": "",
        "value": ""
      },
      "closed_at": {
        "display_value": "2015-07-06 11:56:23",
        "value": "2015-07-06 18:56:23",
        "display_value_internal": "2015-07-06 11:56:23"
      },
      "review_comments": {
        "display_value": "",
        "value": ""
      },
      "business_service": {
        "display_value": "",
        "value": ""
      },
      "time_worked": {
        "display_value": "",
        "value": ""
      },
      "chg_model": {
        "display_value": "",
        "value": ""
      },
      "expected_start": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "opened_at": {
        "display_value": "2015-06-09 11:55:46",
        "value": "2015-06-09 18:55:46",
        "display_value_internal": "2015-06-09 11:55:46"
      },
      "work_end": {
        "display_value": "2015-07-06 11:56:10",
        "value": "2015-07-06 18:56:10",
        "display_value_internal": "2015-07-06 11:56:10"
      },
      "phase_state": {
        "display_value": "Open",
        "value": "open"
      },
      "cab_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "work_notes": {
        "display_value": "",
        "value": ""
      },
      "close_code": {
        "display_value": "Successful",
        "value": "successful"
      },
      "assignment_group": {
        "display_value": "Network",
        "value": "287ebd7da9fe198100f92cc8d1d2154e"
      },
      "description": {
        "display_value": "Resend the complete BGP table to neighboring routers\r\n\r\n--Both neighbors need to support soft reset route refresh capability.\r\n--Stores complete BGP table of you neighbor in router memory.\r\n--Not a good idea on a peering router with full feed, due to the memory requirements.\r\n",
        "value": "Resend the complete BGP table to neighboring routers\r\n\r\n--Both neighbors need to support soft reset route refresh capability.\r\n--Stores complete BGP table of you neighbor in router memory.\r\n--Not a good idea on a peering router with full feed, due to the memory requirements.\r\n"
      },
      "on_hold_reason": {
        "display_value": "",
        "value": ""
      },
      "calendar_duration": {
        "display_value": "",
        "value": ""
      },
      "close_notes": {
        "display_value": "Completed without issues",
        "value": "Completed without issues"
      },
      "sys_id": {
        "display_value": "b0dbda5347c12200e0ef563dbb9a718f",
        "value": "b0dbda5347c12200e0ef563dbb9a718f"
      },
      "contact_type": {
        "display_value": "Phone",
        "value": "phone"
      },
      "cab_required": {
        "display_value": "false",
        "value": false
      },
      "urgency": {
        "display_value": "3 - Low",
        "value": 3.0
      },
      "scope": {
        "display_value": "Medium",
        "value": 3.0
      },
      "company": {
        "display_value": "",
        "value": ""
      },
      "justification": {
        "display_value": "",
        "value": ""
      },
      "activity_due": {
        "display_value": "UNKNOWN",
        "value": "",
        "display_value_internal": ""
      },
      "comments": {
        "display_value": "",
        "value": ""
      },
      "approval": {
        "display_value": "Approved",
        "value": "approved"
      },
      "due_date": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "sys_mod_count": {
        "display_value": "10",
        "value": 10.0
      },
      "on_hold": {
        "display_value": "false",
        "value": false
      },
      "sys_tags": {
        "display_value": "",
        "value": ""
      },
      "conflict_last_run": {
        "display_value": "",
        "value": "",
        "display_value_internal": ""
      },
      "risk_value": {
        "display_value": "",
        "value": ""
      },
      "unauthorized": {
        "display_value": "false",
        "value": false
      },
      "risk": {
        "display_value": "Moderate",
        "value": 3.0
      },
      "location": {
        "display_value": "",
        "value": ""
      },
      "category": {
        "display_value": "Other",
        "value": "Other"
      },
      "risk_impact_analysis": {
        "display_value": "",
        "value": ""
      }
    }
}

Example: cURL request

The following example shows how to pass encrypted fields in the request body.

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/b0dbda5347c12200e0ef563dbb9a718f" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"encrypted_fields\":\"short_description,description\",
    \"short_description\":\"my short desc\",
    \"description\":\"my desc\"
}" \
--user "username":"password"

Example: cURL request

The following example shows how to pass encrypted fields as query parameters.

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/b0dbda5347c12200e0ef563dbb9a718f?encrypted_fields=short_description%2Cdescription&short_description=my%20short%20desc&description=my%20desc" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{}" \
--user "username":"password"

Change Management - PATCH /sn_chg_rest/change/{sys_id}/approvals

Allows the current user to approve or reject a change request approval record for the specified change request.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{sys_id}/approvals

Default URL: /api/sn_chg_rest/change/{sys_id}/approvals

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 157. Path parameters
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
sys_id Sys_id of the change request for which the approval/rejection applies.

Data type: String

Table: Change Request [change_request]
Table 158. Query parameters
Name Description
None
Table 159. Request body parameters (XML or JSON)
Name Description
comments Required if state is rejected. Reason that the change was rejected.

Data type: String
state Required. Approval state.

For example: --data "{\"state\": \"approved\"}"

Valid values:
  • approved
  • rejected

Data type: String

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.

Table 160. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 161. Response headers
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.

Table 162. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
400 Bad request. Indicates a bad request type such as the user not having the authority to approve or reject the change request.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Name Description
name-value pairs Values for all fields in the associated change request.

Data type: Object
state Current state of the change request.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in a UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Sys_id of the change request being approved/rejected.

Data type: String
type Type of change request.

Data type: Object

type: {
  display_value: "String",
  value: "String"
}
type.display_value Change type to display in a UI.
Possible values:
  • Emergency
  • Normal
  • Standard

Data type: String
type.value Internal type value.
Possible values:
  • emergency
  • normal
  • standard

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/0f4ac6c4b750230096c3e4f6ee11a9fe/approvals" \
--request POST \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data "{\"state\": \"approved\"}" \
--user "username":"password"

{
  result: [
    {
      sys_id: "0f4ac6c4b750230096c3e4f6ee11a9fe",
      state: {
        value: "-2", 
        display_value: "Scheduled"
      },
      type: {
        value: "normal",
        display_value: "Normal"
      },
      ..., // all valid fields in record, single parameter example below
      short_description: {
        value: "Remove server",
        display_value: "Remove server"
      }
    }
  ]
}

Change Management - PATCH /sn_chg_rest/change/{change_sys_id}/schedule/first_available

Updates the planned start and end times of a change request using the first available time slot found.

Role required: sn_change_writer.

Note: Use the link provided in the response body worker.link property to view the schedule status.
See also:

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{change_sys_id}/schedule/first_available

Default URL: /api/sn_chg_rest/change/{change_sys_id}/schedule/first_available

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 163. Path parameters
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
change_sys_id Sys_id of the change request on which to update with the next available time slot. The selected change request must have a configuration item (cmdb_ci).

Data type: String

Table: Change Requests [change_request]
Table 164. Query parameters
Name Description
None
Table 165. Request body parameters (XML or JSON)
Name Description
duration_in_seconds Duration of change in seconds, that is, how much time is required to complete the change request task.

Data type: Integer
planned_start_time Optional. Date and time that the change request is planned to start implementation in UTC.

Retrieve the available time slot start at or later than this time. If not provided, the system uses the current time as the start time.

Format: yyyy-mm-dd hh:mm:ss

Data type: String

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.

Table 166. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 167. Response headers
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.

Table 168. Status codes
Status code Description
202 System accepted the request.
400 Bad Request. A bad request type or malformed request was detected.
Possible issues:
  • The duration_in_seconds body parameter value is invalid or was not provided.
  • Invalid planned_start_time body parameter value provided.
  • The specified change request doesn't have an associated configuration item (cmdb_ci).
  • User doesn't have read access to the fields of the change request.
403 Forbidden. User does not have write access to the planned start and end date values of the change request.
404 Not Found. The specified record couldn't be found.
Possible issues:
  • System can't find the change request based on information provided.
  • User doesn't have read access to the record.

Response body parameters (JSON or XML)

Name Description
error Information on any errors encountered while processing the endpoint request.

Data type: Object

"error": {
  "detail": "String",
  "message": "String",
  "status": "String"
}
error.detail Additional information about the error.

Data type: String
error.message Message that identifies the error.

Data type: String
messages Message information.
Data type: Object
"messages": {
  "errorMessages": [Array],
  "infoMessages": [Array],
  "warningMessages": [Array]
}
messages.errorMessages Error messages encountered while processing the request.

Data type: Array
messages.infoMessages Information messages encountered while processing the request.

Data type: Array
messages.warningMessages Warning messages encountered while processing the request.

Data type: Array
request Original endpoint request.

Data type: String
state Information on the current state of the worker.

Data type: Object

state: {
  display_value: "String", 
  value: Number
}
state.display_value Display value of the state of the worker. These values directly correlate to the state.value parameter.

Possible values:

  • Complete
  • Error
  • In-Progress
  • Waiting

Data type: String
state.value Numeric value of the state of the worker.

Possible values:

  • 1
  • 2
  • 3
  • 4

Data type: Number
type Type of request.

Valid value: schedule

Data type: String
worker Information about the associated worker.

Data type: Object

"worker": {
  "link": "String",
  "sysId": "String"
}
worker.link Link for retrieving change request schedule status. Use the sys_id in GET /sn_chg_rest/change/worker/{sys_id} to view results.

Data type: String
worker.sysId Sys_id of the worker associated with the change request.

Data type: String
status Only appears if an error is encountered. Status of the endpoint processing.

Possible value: failure

Data type: String

Get change request schedule status

Use the value provided in the worker.link to determine if the change record has been successfully scheduled for the first available time slot. The value is in the following format:

https://instance.service-now.com/api/sn_chg_rest/change/worker/<worker_sys_id>

Use the worker.link details to run the provided sys_id in GET /sn_chg_rest/change/worker/{sys_id} to view results.

The response body contains the status and provides results when processing is complete.

If an available time slot is found, the system updates the change request with the first available slot. When the state is complete, the messages.infoMessages reveals that the first available time slot has been set.

One of the following scheduling response values for messages.infoMessages are provided in the response body:
  • Change has been updated – Change requested has been updated for time slot.
  • No slots found for <number> days from now – No time slots available for change request duration provided within the number of days defined in the schedule window.
    Note: The change request scheduling time slot default value is 90 days. To change this value, modify the change.conflict.next_available.schedule_window property. For more information, see Configure conflict analysis properties.

The following GET /sn_chg_rest/change/worker/{sys_id} example shows output provided using the ID provided in the worker.link detail. The results indicate that processing is complete and the change request has been updated with the first available time slot.

{
  "result": {
    "worker": {
      "sysId": "355c62e0a4c87010f87712198fe9cacf",
      "link": "https://instance.service-now.com/api/sn_chg_rest/change/worker/355c62e0a4c87010f87712198fe9cacf"
    },
    "request": "{\"change_sys_id\":\"87ae5e900a0a2c3e263e8304e727c646\",\"duration_in_seconds\":10800,\"timezone\":\"America/Los_Angeles\"}",
    "state": {
      "value": 3,
      "display_value": "Complete"
    },
    "type": "schedule",
    "messages": {
      "errorMessages": [],
      "warningMessages": [],
      "infoMessages": [
        "Change has been updated"
      ]
    }
  }
}

Example: cURL request

curl "https://instance.service-now.com/api/sn_chg_rest/change/87ae5e900a0a2c3e263e8304e727c646/schedule/first_available" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{\"duration_in_seconds\":\"10800\"}" \
--user "username":"password"

Results include worker.link details you can use to run the provided sys_id in the GET /sn_chg_rest/change/worker/ endpoint.

{
  "result": {
    "worker": {
      "sysId": "355c62e0a4c87010f87712198fe9cacf",
      "link": "https://instance.service-now.com/api/sn_chg_rest/change/worker/355c62e0a4c87010f87712198fe9cacf"
    },
    "request": "{\"change_sys_id\":\"87ae5e900a0a2c3e263e8304e727c646\",\"duration_in_seconds\":10800,\"timezone\":\"America/Los_Angeles\"}",
    "state": {
      "value": 1,
      "display_value": "Waiting"
    },
    "type": "schedule",
    "messages": {
      "errorMessages": [],
      "warningMessages": [],
      "infoMessages": []
    }
  }
}

Change Management - PATCH /sn_chg_rest/change/{change_sys_id}/task/{task_sys_id}

Updates the change request task identified by the specified sys_ids with the key-value pairs in the request body or the URL.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{change_sys_id}/task/{task_sys_id}

Default URL: /api/sn_chg_rest/change/{change_sys_id}/task/{task_sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 169. Path parameters
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
change_sys_id Sys_id of the change request to which the task is associated. Verifies whether the specified task is associated with the specified change request.

Data type: String

Table: Change Request [change_request]
task_sys_id Sys_id of the task to modify.

Data type: String

Table: Change Task [change_task]
Table 170. Query parameters
Name Description
key-value pairs Name-value pairs representing the fields to update. Request body parameters override URL parameters. However, required parameters must be specified in the URL.

Data type: String
Table 171. Request body parameters (XML or JSON)
Name Description
data Name-value pairs representing the field(s) to update in the associated change request. For example, to update the short description file, enter a name-value pair similar to the following: --data "{\"short_description\": \"my short desc\" }" \.

Data type: String

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.

Table 172. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 173. Response headers
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.

Table 174. Status codes
Status code Description
200 Successful. The request was successfully processed.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs All fields (key) with their associated values for the identified change request task prior to the delete.

Data type: Object
sys_id Sys_id information for the change request task.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request task to display in a UI.

Data type: String
sys_id.value Sys_id of the change request task.

Data type: String
parent Unique identifier information for the change request associated to this task.

Data type: Object

parent: {
  display_value: "String", 
  value: "String"
}
parent.display_value Task information to display in a UI.

Data type: String
parent.value Sys_id of the parent task.

Data type: String
__meta.ignoredFields Key-value pairs that were passed in the call, but weren't applied to the change request as they either don't exist in the base record or the fields are read-only.

Data type: Array

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/0f4ac6c4b750230096c3e4f6ee11a9fe/task/12629ec4b750230096c3e4f6ee11a9d5?short_description=Retire both nodes" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type: application/json" \
--data "{\"state\": \"assess\", \"no_such_field\": \"this will be ignored\" }" \
--user "username":"password"
{
  result: [
    {
      sys_id: {
        value: "12629ec4b750230096c3e4f6ee11a9d5",
        display_value: "12629ec4b750230096c3e4f6ee11a9d5"
      },
      parent: {
        value: "0f4ac6c4b750230096c3e4f6ee11a9fe", 
        display_value: "CHG0033046 "
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Retire both nodes",
        display_value: "Retire both nodes"
      }
      __meta: {
        ignoredFields: ["no_such_field"]
      }
    }
  ]
}

Change Management - PATCH /sn_chg_rest/change/emergency/{sys_id}

Updates the emergency change request identified by the specified sys_id with the key-value pairs in the request body or the URL.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/emergency/{sys_id}

Default URL: /api/sn_chg_rest/change/emergency/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 175. Path parameters
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
sys_id Sys_id of the change request to modify.

Data type: String

Table: Change Request [change_request]
Table 176. Query parameters
Name Description
name-value pairs Name-value pairs representing the fields to update. Request body parameters override URL parameters. However, required parameters must be specified in the URL.

Data type: String
Table 177. Request body parameters (XML or JSON)
Name Description
data Name-value pairs representing the field(s) to update in the associated change request. For example, to update the short description file, enter a name-value pair similar to the following: --data "{\"short_description\": \"my short desc\" }" \.

Data type: String

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.

Table 178. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 179. Response headers
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.

Table 180. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs Values for all fields in the associated change request.

Data type: String
state Current state of the change request.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in a UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Sys_id of the change request.

Data type: String
type Type of change request.

Data type: Object

type: {
  display_value: "String",
  value: "String"
}
type.display_value Change type to display in a UI.

Value is always "Emergency".

Data type: String
type.value Internal type value.

Value is always "emergency".

Data type: String
__meta.ignoredFields Name-value pairs that were passed in the call, but were not applied to the change request as they either do not exist in the base record or the fields are read-only.

Data type: Array

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/emergency/b0dbda5347c12200e0ef563dbb9a718f" \
--request PATCH \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data "{\"no_such_field\": \"this will be ignored\", }" \
--user "username":"password"
{
  result: [
    {
      sys_id: "b0dbda5347c12200e0ef563dbb9a718f",    },
      state: {
        value: "-4", 
        display_value: "Assess"
      },
      type: {
        value: "emergency",
        display_value: "Emergency"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Reboot server",
        display_value: "Reboot server"
      }
      __meta: {
        ignoredFields: ["no_such_field"]
      }
    }
  ]
}

Change Management - PATCH /sn_chg_rest/change/normal/{sys_id}

Updates the normal change request identified by the specified sys_id with the parameters in the request body or the URL.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/normal/{sys_id}

Default URL: /api/sn_chg_rest/change/normal/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 181. Path parameters
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
sys_id Sys_id of the change request to modify.

Data type: String

Table: Change Request [change_request]
Table 182. Query parameters
Name Description
name-value pairs Name-value pairs representing the fields to update. Request body parameters override URL parameters. However, required parameters must be specified in the URL.

Data type: String
Table 183. Request body parameters (XML or JSON)
Name Description
data Name-value pairs representing the field(s) to update in the associated change request. For example, to update the short description file, enter a name-value pair similar to the following: --data "{\"short_description\": \"my short desc\" }" \.

Data type: String

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.

Table 184. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 185. Response headers
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.

Table 186. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs Values for all fields in the associated change request.

Data type: Object
state Current state of the change request.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in a UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Sys_id of the change request.

Data type: String
type Type of change request.

Data type: Object

type: {
  display_value: "String",
  value: "String"
}
type.display_value Change type to display in a UI.

Value is always "Normal".

Data type: String
type.value Internal type value.

Value is always "normal".

Data type: String
__meta.ignoredFields Name-value pairs that were passed in the call, but were not applied to the change request as they either do not exist in the base record or the fields are read-only.

Data type: Array

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/normal/b0dbda5347c12200e0ef563dbb9a718f?state=assess" \
--request PATCH \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data "{\"state\": \"assess\", \"no_such_field\": \"this will be ignored\" }" \
--user "username":"password"

{
  result: [
    {
      sys_id: "b0dbda5347c12200e0ef563dbb9a718f",
      state: {
        value: "-4", 
        display_value: "Assess"
      },
      type: {
        value: "normal",
        display_value: "Normal"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Remove server",
        display_value: "Remove server"
      }
      __meta: {
        ignoredFields: ["no_such_field"]
      }
    }
  ]
}

Change Management - PATCH /sn_chg_rest/change/standard/{sys_id}

Updates the standard change request identified by the specified sys_id with the parameters in the request body or in the URL.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/standard/{sys_id}

Default URL: /api/sn_chg_rest/change/standard/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 187. Path parameters
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
sys_id Sys_id of the change request to modify.

Data type: String

Table: Change Request [change_request]
Table 188. Query parameters
Name Description
name-value pairs Name-value pairs representing the fields to update. Request body parameters override URL parameters. However, required parameters must be specified in the URL.

Data type: String
Table 189. Request body parameters (XML or JSON)
Name Description
data Name-value pairs representing the field(s) to update in the associated change request. For example, to update the short description file, enter a name-value pair similar to the following: --data "{\"short_description\": \"my short desc\" }" \.

Data type: String

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.

Table 190. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 191. Response headers
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.

Table 192. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs All fields (key) with their associated values for the identified change request.

Data type: Object
state State of the change request.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in a UI.

Data type: String
state.value Internal state value.

Data type: String
sys_id Sys_id information for the change request.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request to disply in a UI.

Data type: String
sys_id.value Sys_id of the change request.

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/standard/1c87925347c12200e0ef563dbb9a7177?description=Reboot my email server" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{\"short_description\": \"my short desc\" }" \
--user "username":"password"

{
  result: [
    {
      sys_id: {
        value: "1c87925347c12200e0ef563dbb9a7177",
        display_value: "1c87925347c12200e0ef563dbb9a7177"
      },
      state: {
        value: "-5", 
        display_value: "New"
      },

      ..., // all valid fields in record, example below
      short_description: {
        value: "Reboot my email server",
        display_value: "Reboot my email server"
      },
    } 
  ]
}

Change Management - PATCH /sn_chg_rest/change/standard/{sys_id}/risk

Calculates the risk and impact of the specified standard change based on an evaluation of the risk conditions.

If the Change Risk Assessment plugin is installed, it also calculates the cumulative highest risk once the risk assessment is complete.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{sys_id}/risk

Default URL: /api/sn_chg_rest/change/{sys_id}/risk

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 193. Path parameters
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
sys_id Sys_id of the standard change to evaluate.

Data type: String

Table: Change Request [change_request]
Table 194. Query parameters
Name Description
None
Table 195. Request body parameters (XML or JSON)
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.

Table 196. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 197. Response headers
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.

Table 198. Status codes
Status code Description
200 Risk assessment completed successfully.
400 Risk assessment failed. Details of the type of failure are included in the error data.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not found. The requested item wasn't found.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Name Description
impact Impact associated with the specified standard change.

Data type: Object

impact: {
  display_value: "String", 
  value: "String"
}
impact.display_value Impact information to display in a UI.

Data type: String
impact.value Internal impact value.

Data type: String
name-value pairs All valid fields within the standard change record.

Data type: Object
risk Risk calculated for the specified standard change.

Data type: Object

risk: {
  display_value: "String", 
  value: "String"
}
risk.display_value Risk information to display in a UI.

Data type: String
risk.value Internal risk value.

Data type: String
sys_id Sys_id information for the standard change request.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request to display in a UI.

Data type: String
sys_id.value Sys_id of the change request.

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/1c87925347c12200e0ef563dbb9a7177/risk" \
--request PATCH \
--header "Accept:application/json" \
--user "username":"password"
{
  sys_id: {
    value: "1c87925347c12200e0ef563dbb9a7177",
    display_value: "1c87925347c12200e0ef563dbb9a7177"
  },
  risk: {
    value: "4", 
    display_value: "Low"
  },
  impact: {
    value: "3",
    display_value: "3 - Low"
  }
  ..., // all valid fields in record
}

Change Management - POST /sn_chg_rest/change

Creates a change request record based on the change request. Creating multiple change requests within a single call isn’t supported.

You can obtain the list of available change models using the Change Management - GET /sn_chg_rest/change/model or Change Management - GET /sn_chg_rest/change/model/{sys_id} endpoints.

When creating a change request, set the change model (chg_model) or type. If both chg_modeland type are set, the type is simply a categorization of the change. Not providing at least one of these values results in a default setting that is subject to change by release. It is strongly advised to set at least one of these values.

Values can be set either as a query parameter or request body parameter.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change

Default URL: /api/sn_chg_rest/change

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 199. Path parameters
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 200. Query parameters
Name Description
name-value pairs Name-value pairs representing the fields to update. Request body parameters override URL parameters. However, required parameters must be specified in the URL. The same values can be set as request body parameters instead.
Note: When creating a change request, set the change model (chg_model) or type. If both chg_modeland type are set, the type is simply a categorization of the change. Not providing at least one of these values results in a default setting that is subject to change by release. It is strongly advised to set at least one of these values.

Data type: String
chg_model Name of a change model listed in the Change Model [chg_model] table.

Provided in the following format: chg_model=Normal.

For more information, see Change models.

Note: Not providing either the change model (chg_model) or type value results in a default setting that is subject to change by release. It is strongly advised to set at least one of these values.

Data type: String
encrypted_fields List of comma-separated fields to encrypt. These fields are encrypted before they are stored in the associated record. When specified, the endpoint calls the GlideRecord setDisplayValue() method, instead of calling the setValue() method.

Because of this, you can also use this parameter to pass display values for non-encrypted fields, such as reference or choice fields, instead of passing sys_ids or values.

Data type: String
type Name of the change request type listed in the Choices [sys_choice] table. If the chg_model is also populated, this field is only used as a change categorization.

Provided in the following format: type=Normal.

For more information, see Add a new change request type.

Note: Not providing either the change model (chg_model) or type value results in a default setting that is subject to change by release. It is strongly advised to set at least one of these values.

Data type: String
Table 201. Request body parameters (JSON)
Name Description
Object Name-value pairs representing the field(s) to update in the associated change request. For example, to update the short description file, enter a name-value pair similar to the following: --data "{\"short_description\": \"my short desc\" }" \. The same properties can be set as query parameters instead.

Data type: String
Object.chg_model Name of a change model listed in the Change Model [chg_model] table.

Provided as a name-value pair in the following format: {"chg_model" : "Cloud Infrastructure"}

For more information, see Change models.

Note: Not providing either the change model (chg_model) or type value results in a default setting that is subject to change by release. It is strongly advised to set at least one of these values.

Data type: String
Object.encrypted_fields List of comma-separated fields to encrypt. These fields are encrypted before they are stored in the associated record. When specified, the endpoint calls the GlideRecord setDisplayValue() method, instead of calling the setValue() method.

Because of this, you can also use this parameter to pass display values for non-encrypted fields, such as reference or choice fields, instead of passing sys_ids or values.

Data type: String
Object.type Name of the change request type listed in the Choices [sys_choice] table. If the chg_model is also populated, this field is only used as a change categorization.

Provided as a name-value pair in the following format: {"type" : "emergency"}

For more information, see Add a new change request type.

Note: Not providing either the change model (chg_model) or type value results in a default setting that is subject to change by release. It is strongly advised to set at least one of these values.

Data type: String

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.

Table 202. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 203. Response headers
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.

Table 204. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
result New change request record. The elements of this object correspond to the record format in the Change Request [change_request] table. All values that are not specified in the request are set to their defaults or are empty/null.

Data type: Object

Example: cURL request

The following example shows how to create a change request record based on the Standard change model and Standard type. In this example, the Change Request is driven by the model and the type field is only used as a categorization.

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"chg_model\" : \"Standard\",
    \"description\" : \"Describes the change request.\",
    \"short_description\" : \"My change request\",
    \"type\" : \"Standard\"
}" \
--user "username":"password"

Results show that the record was successfully added to the Change Request [change_request] table with the value CHG0030022.

{
  "result": 
    "upon_reject": {
      "display_value": "Cancel all future Tasks",
      "value": "cancel"
    },
    "sys_updated_on": {
      "display_value": "2022-12-08 17:18:57",
      "value": "2022-12-09 01:18:57",
      "display_value_internal": "2022-12-08 17:18:57"
    },
    "type": {
      "display_value": "Standard",
      "value": "standard"
    }
    "number": {
      "display_value": "CHG0030022",
      "value": "CHG0030022"
    },
    "is_bulk": {
      "display_value": "false",
      "value": false
    }
    "ci_class": {
      "display_value": "cmdb_ci",
      "value": "cmdb_ci"
    },
    "state": {
      "display_value": "New",
      "value": -5
    },
    "sys_created_by": {
      "display_value": "admin",
      "value": "admin"
    },
    "knowledge": {
      "display_value": "false",
      "value": false
    },
    "phase": {
      "display_value": "Requested",
      "value": "requested"
    }
    "impact": {
      "display_value": "3 - Low",
      "value": 3
    },
    "active": {
      "display_value": "true",
      "value": true
    },
    "priority": {
      "display_value": "4 - Low",
      "value": 4
    },
    "sys_domain_path": {
      "display_value": "/",
      "value": "/"
    },
    "production_system": {
      "display_value": "false",
      "value": false
    },
    "requested_by": {
      "display_value": "System Administrator",
      "value": "6816f79cc0a8016401c5a33be04be441"
    }
    "short_description": {
      "display_value": "My change request",
      "value": "My change request"
    },
    "sys_class_name": {
      "display_value": "Change Request",
      "value": "change_request"
    },
    "reassignment_count": {
      "display_value": "0",
      "value": 0
    },
    "variables": {
      "display_value": "variable_pool",
      "value": "variable_pool"
    },
    "sla_due": {
      "display_value": "UNKNOWN",
      "value": "",
      "display_value_internal": ""
    },
    "escalation": {
      "display_value": "Normal",
      "value": 0
    },
    "upon_approval": {
      "display_value": "Proceed to Next Task",
      "value": "proceed"
    },
    "conflict_status": {
      "display_value": "Not Run",
      "value": "Not Run"
    },
    "task_effective_number": {
      "display_value": "CHG0030022",
      "value": "CHG0030022"
    },
    "sys_updated_by": {
      "display_value": "admin",
      "value": "admin"
    },
    "opened_by": {
      "display_value": "System Administrator",
      "value": "6816f79cc0a8016401c5a33be04be441"
    },
    "sys_created_on": {
      "display_value": "2022-12-08 17:18:57",
      "value": "2022-12-09 01:18:57",
      "display_value_internal": "2022-12-08 17:18:57"
    },
    "sys_domain": {
      "display_value": "global",
      "value": "global"
    },
    "chg_model": {
      "display_value": "Standard",
      "value": "e55d0bfec343101035ae3f52c1d3ae49"
    },
    "opened_at": {
      "display_value": "2022-12-08 17:18:57",
      "value": "2022-12-09 01:18:57",
      "display_value_internal": "2022-12-08 17:18:57"
    },
    "description": {
      "display_value": "Describes the change request.",
      "value": "Describes the change request."
    },
    "sys_id": {
      "display_value": "2ac52dd77c6b1510f877be3b096e64fe",
      "value": "2ac52dd77c6b1510f877be3b096e64fe"
    },
    "cab_required": {
      "display_value": "false",
      "value": false
    },
    "urgency": {
      "display_value": "3 - Low",
      "value": 3
    },
    "scope": {
      "display_value": "Medium",
      "value": 3
    },
    "activity_due": {
      "display_value": "UNKNOWN",
      "value": "",
      "display_value_internal": ""
    },
    "approval": {
      "display_value": "Not Yet Requested",
      "value": "not requested"
    },
  }
}

Example: cURL request

The following example shows how to pass encrypted fields in the request body.

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"encrypted_fields\":\"short_description,description\",
    \"short_description\":\"my short desc\",
    \"description\":\"my desc\"
}" \
--user "username":"password"

Example: cURL request

The following example shows how to pass encrypted fields as query parameters.

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change?encrypted_fields=short_description%2Cdescription&short_description=my%20short%20desc&description=my%20desc" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{}" \
--user "username":"password"

Change Management - POST /sn_chg_rest/change/{sys_id}/ci

Creates the association between a change request and Configuration Management Database (CMDB) configuration items (CI).

The creation of the association is done asynchronously, which means that a response is provided immediately and contains details for the worker. The worker does the actual work after the response.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{sys_id}/ci

Default URL: /api/sn_chg_rest/change/{sys_id}/ci

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 205. Path parameters
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
sys_id Sys_id of the change request to associate with the CMDB CI.

Data type: String
Table 206. Query parameters
Name Description
None
Table 207. Request body parameters (XML or JSON)
Name Description
association_type Required. Type of association between the CMDB CI and the change request.

Valid values:

  • affected: CIs that are affected by the change request
  • impacted: Services impacted by the change request
  • offering: Impacted service offerings

Data type: String
cmdb_ci_sys_ids Required. List of CMDB CI sys_ids to associate to the change request.

Data type: Array or comma-separated string
refresh_impacted_services Flag used when association_type=affected to populate impacted services based on the list of affected CIs.

Valid values:

  • true: Populate impacted services based on the list of affected CIs
  • false: Do not automatically populate impacted services

Data type: Boolean

Default: false

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.

Table 208. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 209. Response headers
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.

Table 210. Status codes
Status code Description
202 Accepted. The request was accepted for processing.
400 Bad Request. A bad request type or malformed request was detected.

The error response contains pertinent messages to help troubleshoot the problem.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not found. The requested item wasn't found.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Name Description
messages Message information.
Data type: Object
"messages": {
  "errorMessages": [Array],
  "infoMessages": [Array],
  "warningMessages": [Array]
}
messages.errorMessages Error messages encountered while processing the request. For example: 
Invalid CMDB_CI sys_id provided

Data type: Array
messages.infoMessages Information messages encountered while processing the request. For example: 
CMDB_CI sys_id already associated to provided.

Data type: Array
messages.warningMessages Warning messages encountered while processing the request. For example: 
Invalid CMDB_CI sys_id provided.

Data type: Array
request Original endpoint request.

Data type: String
state Information on the current state of the worker.
state: {
  display_value: "String", 
  value: "String"
}
state.display_value Display value of the state of the worker. These values directly correlate to the state.value element.

Possible values:

  • Complete
  • Error
  • In-Progress
  • Waiting

Data type: String
state.value Numeric value of the state of the worker.

Possible values:

  • 1
  • 2
  • 3
  • 4

Data type: Number
type Type of association between the CMDB CI and the change request.

Data type: String
worker Information about the associated worker.

Data type: Object

"worker": {
  "link": "String",
  "sysId": "String"
}
worker.link URL to retrieve the status of the associated worker and other worker pertinent information.

Data type: String
worker.sysId Sys_id of the worker associated with the change request.

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/c286d61347c12200e0ef563dbb9a71df/ci" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{cmdb_ci_sys_ids:'caf043a3b7fb23000999e4f6ee11a9c0,06f043a3b7fb23000999e4f6ee11a9c1', association_type:'affected'}" \
--user "username":"password"

{
  "result": {
    "worker": {
      "sysId": "f490f4c6dbac330084f07ffdbf961952",
      "link": "instance.service-now.com/api/sn_chg_rest/change/worker/f490f4c6dbac330084f07ffdbf961952"
    },
    "request": "{\"cmdb_ci_sys_ids\":[\"caf043a3b7fb23000999e4f6ee11a9c0\",\"06f043a3b7fb23000999e4f6ee11a9c1\"],\"association_type\":\"affected\",\"task\":\"c286d61347c12200e0ef563dbb9a71df\"}",
    "state": {
      "value": 1,
      "display_value": "Waiting"
    },
    "type": "affected",
    "messages": {
      "errorMessages": [],
      "warningMessages": [],
      "infoMessages": []
    }
  }
}

Change Management - POST /sn_chg_rest/change/{sys_id}/conflict

Starts a change request conflict checking process for the specified change request (sys_id).

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{sys_id}/conflict

Default URL: /api/sn_chg_rest/change/{sys_id}/conflict

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 211. Path parameters
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
sys_id Sys_id of the change management request for which to start the conflict checking process. For additional information on the conflict checking process, see Conflict detection.

Data type: String

Table: Change Request [change_request]
Table 212. Query parameters
Name Description
None
Table 213. Request body parameters (XML or JSON)
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.

Table 214. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 215. Response headers
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.

Table 216. Status codes
Status code Description
200 Successful. The request was successfully processed.
400 Bad Request. Request was unable to start due to unresolvable errors. The returned message may provide additional details.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not found. The requested item wasn't found.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Name Description
result Sys_id of the change request conflict checking process.

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/0f4ac6c4b750230096c3e4f6ee11a9fe/conflict" \
--request POST \
--header "Accept:application/json" \
--user "username":"password"

{
    result: "c0b5afe4b710230096c3e4f6ee11a93f"
}

Change Management - POST /sn_chg_rest/change/emergency

Creates one emergency change request based on the default emergency change request record. Multiple emergency change request creations within a single call is not supported.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/emergency

Default URL: /api/sn_chg_rest/change/emergency

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 217. Path parameters
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 218. Query parameters
Name Description
key-value pairs Key-value pairs of fields to modify when creating the request. The key is the field name within the template and the value is the information to populate in the field.
Fields that cannot be modified and are ignored if passed in:
  • Business rules
  • Read-only fields as defined in ACLs
  • Fields that do not exist

Data type: String
Table 219. Request body parameters (XML or JSON)
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.

Table 220. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 221. Response headers
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.

Table 222. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs Name-value pairs of the fields that were created in the emergency change request.

Data type: Object
state State of the change request prior to the delete.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in a UI.

Value is always "New".

Data type: String
state.value Internal state value.

Value is always "-5".

Data type: String
sys_id Sys_id of the newly created emergency change request.

Data type: String
type Type of change request.

Data type: Object

type: {
  display_value: "String",
  value: "String"
}
type.display_value Change type to display in a UI.

Value is always "Emergency".

Data type: String
type.value Internal type value.

Value is always "emergency".

Data type: String
__meta.ignoredFields Key-value pairs that were passed in the call, but weren't applied to the change request as they either don't exist in the base record or the fields are read-only.

Data type: Array

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/emergency?no_such_field=something&description=test&short_description=Reboot server" \
--request POST \
--header "Accept:application/json" \
--user "username":"password"
{
  result: [
    {
      sys_id: "b0dbda5347c12200e0ef563dbb9a718f",
      state: {
        value: "-5", 
        display_value: "New"
      },
      type: {
        value: "emergency",
        display_value: "Emergency"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Reboot server",
        display_value: "Reboot server"
      }
      __meta: {
        ignoredFields: ["no_such_field"]
      }
    }
  ]
}

Change Management - POST /sn_chg_rest/change/normal

Creates one normal change request based on the default normal change request record. Multiple normal change request creations within a single call is not supported.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/normal

Default URL: /api/sn_chg_rest/change/normal

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 223. Path parameters
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 224. Query parameters
Name Description
key-value pairs Fields to modify when creating the request. The key is the field name within the template and the value is the information to populate in the field.
Fields that cannot be modified and are ignored if passed in:
  • Business rules
  • Read-only fields as defined in ACLs
  • Fields that do not exist

Data type: String
Table 225. Request body parameters (XML or JSON)
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.

Table 226. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 227. Response headers
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.

Table 228. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs Values for all fields in the associated change request.

Data type: Object
state State of the newly created change request.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value State to display in a UI.

Value is always "New".

Data type: String
state.value Internal state value.

Value is always "-5".

Data type: String
sys_id Sys_id of the newly created normal change request.

Data type: String
type Type of change request.

Data type: Object

type: {
  display_value: "String",
  value: "String"
}
type.display_value Change type to display in a UI.

Value is always "Normal".

Data type: String
type.value Internal type value.

Value is always "normal".

Data type: String
__meta.ignoredFields Key-value pairs that were passed in the call, but weren't applied to the change request as they either don't exist in the base record or the fields are read-only.

Data type: Array

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/normal?no_such_field=something&description=test&short_description=Remove server" \
--request POST \
--header "Accept:application/json" \
--user "username":"password"

{
  result: [
    {
      sys_id: "b0dbda5347c12200e0ef563dbb9a718f",
      state: {
        value: "-5", 
        display_value: "New"
      },
      type: {
        value: "normal",
        display_value: "Normal"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Remove server",
        display_value: "Remove server"
      }
      __meta: {
        ignoredFields: ["no_such_field"]
      }
    }
  ]
}

Change Management - POST /sn_chg_rest/change/{sys_id}/refresh_impacted_services

Populates the impacted services/configuration items (CIs) related list based on the primary CI.

The primary CI appears on the change request form and affected CI related list.

Note: All work items for this endpoint are performed asynchronously.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{sys_id}/refresh_impacted_services

Default URL: /api/sn_chg_rest/change/{sys_id}/refresh_impacted_services

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 229. Path parameters
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
sys_id Sys_id of the change request to use to refresh the impacted services.

Data type: String
Table 230. Query parameters
Name Description
None
Table 231. Request body parameters (XML or JSON)
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.

Table 232. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 233. Response headers
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.

Table 234. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Name Description
messages Message information.
Data type: Object
"messages": {
  "errorMessages": [Array],
  "infoMessages": [Array],
  "warningMessages": [Array]
}
messages.errorMessages Error messages encountered while processing the request. For example: 
Invalid CMDB_CI sys_id provided

Data type: Array
messages.infoMessages Information messages encountered while processing the request. For example: 
CMDB_CI sys_id already associated to provided.

Data type: Array
messages.warningMessages Warning messages encountered while processing the request. For example: 
Invalid CMDB_CI sys_id provided.

Data type: Array
request Original endpoint request.

Data type: String
state Information on the current state of the worker.

Data type: Object

state: {
  display_value: "String", 
  value: "String"
}
state.display_value Display value of the state of the worker. These values directly correlate to the state.value element.

Possible values:

  • Complete
  • Error
  • In-Progress
  • Waiting

Data type: String
state.value Numeric value of the state of the worker.

Possible values:

  • 1
  • 2
  • 3
  • 4

Data type: Number
type Type of association between the CMDB CI and the change request.

Data type: String
worker Information about the associated worker.

Data type: Object

"worker": {
  "link": "String",
  "sysId": "String"
}
worker.link URL to retrieve the status of the associated worker and other worker pertinent information.

Data type: String
worker.sysId Sys_id of the worker associated with the change request.

Data type: String

Example: cURL request

curl "https://instance.servicenow.com/api/sn_chg_rest/v1/change/c286d61347c12200e0ef563dbb9a71df/refresh_impacted_services" \ 
--request POST \ 
--header "Accept:application/json" \
--header "Content-Type:application/json" \ 
--user "username":"password"
{ 
  result: { 
    worker: { 
      sysId: "aa31c308b75033000999e4f6ee11a9c2", 
      link: "http://instance.service-now.com/api/sn_chg_rest/change/worker/aa31c308b75033000999e4f6ee11a9c2" 
    }, 
    request: "", 
    state: { 
      value: 1, 
      display_value: "Waiting" 
    }, 
    type: "impacted", 
    messages: { 
      errorMessages: [], 
      warningMessages: [], 
      infoMessages: [] 
    } 
  } 
}

Change Management - POST /sn_chg_rest/change/standard/{standard_change_template_id}

Creates one standard change request based on an existing standard change template as specified by the passed-in template sys_id. Multiple standard change request creations within a single call is not supported.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/standard/{standard_change_template_id}

Default URL: /api/sn_chg_rest/change/standard/{standard_change_template_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 235. Path parameters
Parameter 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
standard_change_template_id Sys_id of the standard change template on which to base the new standard change request.

Data type: String

Table: Standard Change Template [std_change_record_producer]
Table 236. Query parameters
Parameter Description
name-value pairs Fields within the specified standard change template to modify when creating the request. The key is the field name within the template and the value is the information to populate in the field.
Fields that cannot be modified and are ignored if passed in:
  • Description
  • Backout plan
  • Test plan
  • Implementation plan
  • Read-only fields as defined in ACLs
  • Fields that do not exist in the specified standard change template

Data type: String
Table 237. Request body parameters (XML or JSON)
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.

Table 238. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 239. Response headers
Header Description
None

Status codes

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.

Table 240. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body

The API returns these JSON or XML elements in the response body.

Table 241. Elements returned in the response body
Element Description
name-value pairs Name-value pairs of the fields that were created in the standard change request.

Data type: Object
sys_id Sys_id information of the newly created standard change request.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the standard change request to display in a UI.

Data type: String
sys_id.value Sys_id of the standard change request.

Data type: String
__meta.ignoredFields Key-value pairs that were passed in the call, but weren't applied to the change request as they either don't exist in the base record or the fields are read-only.

Data type: Array

Example: Sample cURL request

curl "https://instance.servicenow.com" \
--request POST \
--header "Accept:application/json" \
--user "username":"password"

{
  result: [
    {
      sys_id: {
        value: "1c87925347c12200e0ef563dbb9a7177",
        display_value: "1c87925347c12200e0ef563dbb9a7177"
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Add network switch to cabinet",
        display_value: "Add network switch to cabinet"
      }
      __meta: {
        ignoredFields: ["no_such_field"]
      }
    }
  ]
}

Change Management - POST /sn_chg_rest/change/{change_sys_id}/task

Creates one change request task based on the default change request task record and associates it with the specified change request. Multiple change request task creations within a single call is not supported.

URL format

Versioned URL: /api/sn_chg_rest/{api_version}/change/{change_sys_id}/task

Default URL: /api/sn_chg_rest/change/{change_sys_id}/task

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 242. Path parameters
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
change_sys_id Sys_id of the change request to which to associate this task.

Data type: String

Table: Change Request [change_request]
Table 243. Query parameters
Name Description
key-value pairs Fields to modify when creating the request. The key is the field name within the template and the value is the information to populate in the field.
Fields that cannot be modified and are ignored if passed in:
  • Business rules
  • Read-only fields as defined in ACLs
  • Fields that do not exist

Data type: String
Table 244. Request body parameters (XML or JSON)
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.

Table 245. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 246. Response headers
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.

Table 247. Status codes
Status code Description
200 Request completed successfully.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.
404 Not Found. The specified record couldn't be found.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name Description
name-value pairs Name-value pairs of the fields that were created in the change request task.

Data type: Object
parent Information for the change request associated to the task.

Data type: Object

parent: {
  display_value: "String", 
  value: "String"
}
parent.display_value Information to display in the UI for the change request associated to the task.

Data type: String
parent.value Sys_id of the change request associated to the task.

Data type: String
sys_id Sys_id information of the newly created change request task.

Data type: Object

sys_id: {
  display_value: "String", 
  value: "String"
}
sys_id.display_value Sys_id of the change request task to display in a UI.

Data type: String
sys_id.value Sys_id of the change request task.

Data type: String
__meta.ignoredFields Key-value pairs that were passed in the call, but weren't applied to the change request as they either don't exist in the base record or the fields are read-only.

Data type: Array

Example: cURL request

curl "https://instance.servicenow.com/api/now/change/0f4ac6c4b750230096c3e4f6ee11a9fe/task?short_description=Retire node&no_such_field=test" \
--request POST \
--header "Accept:application/json" \
--user "username":"password"

{
  result: [
    {
      sys_id: {
        value: "12629ec4b750230096c3e4f6ee11a9d5",
        display_value: "12629ec4b750230096c3e4f6ee11a9d5"
      },
      parent: {
        value: "0f4ac6c4b750230096c3e4f6ee11a9fe ", 
        display_value: "CHG0033046 "
      },
      ..., // all valid fields in record, example below
      short_description: {
        value: "Retire node",
        display_value: "Retire node"
      }
      __meta.ignoredFields": ["no_such_field"]
    }
  ]
}