ServiceNow Change Management API

openapi: 3.1.0
info:
  title: ServiceNow Change Management API
  description: >-
    The ServiceNow Change Management API provides REST endpoints for creating,
    retrieving, updating, and managing change requests and their associated
    tasks and approvals. It supports the full change lifecycle including
    normal, standard, and emergency change types within the ITSM Change
    Management application.
  version: 'Yokohama'
  contact:
    name: ServiceNow Support
    url: https://support.servicenow.com
  termsOfService: https://www.servicenow.com/terms-of-use.html
externalDocs:
  description: ServiceNow Change Management API Documentation
  url: https://www.servicenow.com/docs/bundle/yokohama-api-reference/page/integrate/inbound-rest/concept/change-management-api.html
servers:
- url: https://{instance}.service-now.com/api/sn_chg_rest/v1
  description: ServiceNow Instance
  variables:
    instance:
      default: instance
      description: Your ServiceNow instance name
tags:
- name: Change Tasks
  description: >-
    Operations for managing tasks associated with change requests.
- name: Emergency Changes
  description: >-
    Operations for managing emergency change requests that require expedited
    processing.
- name: Normal Changes
  description: >-
    Operations for managing normal change requests that require full review
    and approval before implementation.
- name: Standard Changes
  description: >-
    Operations for managing standard change requests based on pre-approved
    templates.
security:
- basicAuth: []
- oauth2: []
paths:
  /change/normal:
    get:
      operationId: listNormalChanges
      summary: Servicenow List Normal Change Requests
      description: >-
        Retrieves a list of normal change requests. Supports query filtering,
        field selection, and pagination.
      tags:
      - Normal Changes
      parameters:
      - $ref: '#/components/parameters/sysparmQuery'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmLimit'
      - $ref: '#/components/parameters/sysparmOffset'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      responses:
        '200':
          description: Successful response returning normal change requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChangeRequest'
              examples:
                Listnormalchanges200Example:
                  summary: Default listNormalChanges 200 response
                  x-microcks-default: true
                  value:
                    result:
                    - sys_id: '500123'
                      number: example_value
                      short_description: example_value
                      description: A sample description.
                      type: normal
                      state: example_value
                      priority: '1'
                      risk: example_value
                      impact: example_value
                      category: example_value
                      assigned_to: example_value
                      assignment_group: example_value
                      requested_by: example_value
                      start_date: '2026-01-15T10:30:00Z'
                      end_date: '2026-01-15T10:30:00Z'
                      cmdb_ci: example_value
                      close_code: example_value
                      close_notes: example_value
                      approval: example_value
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_updated_on: '2026-01-15T10:30:00Z'
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listnormalchanges401Example:
                  summary: Default listNormalChanges 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createNormalChange
      summary: Servicenow Create a Normal Change Request
      description: >-
        Creates a new normal change request. Normal changes require full
        assessment and approval before implementation.
      tags:
      - Normal Changes
      parameters:
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeRequestInput'
            examples:
              CreatenormalchangeRequestExample:
                summary: Default createNormalChange request
                x-microcks-default: true
                value:
                  short_description: example_value
                  description: A sample description.
                  priority: '1'
                  risk: example_value
                  impact: example_value
                  category: example_value
                  assigned_to: example_value
                  assignment_group: example_value
                  requested_by: example_value
                  start_date: '2026-01-15T10:30:00Z'
                  end_date: '2026-01-15T10:30:00Z'
                  cmdb_ci: example_value
                  justification: example_value
                  implementation_plan: example_value
                  backout_plan: example_value
                  test_plan: example_value
      responses:
        '201':
          description: Normal change request successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ChangeRequest'
              examples:
                Createnormalchange201Example:
                  summary: Default createNormalChange 201 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      number: example_value
                      short_description: example_value
                      description: A sample description.
                      type: normal
                      state: example_value
                      priority: '1'
                      risk: example_value
                      impact: example_value
                      category: example_value
                      assigned_to: example_value
                      assignment_group: example_value
                      requested_by: example_value
                      start_date: '2026-01-15T10:30:00Z'
                      end_date: '2026-01-15T10:30:00Z'
                      cmdb_ci: example_value
                      close_code: example_value
                      close_notes: example_value
                      approval: example_value
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_updated_on: '2026-01-15T10:30:00Z'
        '400':
          description: Bad request. The request body contains invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createnormalchange400Example:
                  summary: Default createNormalChange 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createnormalchange401Example:
                  summary: Default createNormalChange 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /change/normal/{sys_id}:
    get:
      operationId: getNormalChange
      summary: Servicenow Retrieve a Normal Change Request
      description: >-
        Retrieves a specific normal change request by its sys_id.
      tags:
      - Normal Changes
      parameters:
      - $ref: '#/components/parameters/sysId'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      responses:
        '200':
          description: Successful response returning the change request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ChangeRequest'
              examples:
                Getnormalchange200Example:
                  summary: Default getNormalChange 200 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      number: example_value
                      short_description: example_value
                      description: A sample description.
                      type: normal
                      state: example_value
                      priority: '1'
                      risk: example_value
                      impact: example_value
                      category: example_value
                      assigned_to: example_value
                      assignment_group: example_value
                      requested_by: example_value
                      start_date: '2026-01-15T10:30:00Z'
                      end_date: '2026-01-15T10:30:00Z'
                      cmdb_ci: example_value
                      close_code: example_value
                      close_notes: example_value
                      approval: example_value
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_updated_on: '2026-01-15T10:30:00Z'
        '404':
          description: Change request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getnormalchange404Example:
                  summary: Default getNormalChange 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateNormalChange
      summary: Servicenow Update a Normal Change Request
      description: >-
        Updates fields on an existing normal change request.
      tags:
      - Normal Changes
      parameters:
      - $ref: '#/components/parameters/sysId'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeRequestInput'
            examples:
              UpdatenormalchangeRequestExample:
                summary: Default updateNormalChange request
                x-microcks-default: true
                value:
                  short_description: example_value
                  description: A sample description.
                  priority: '1'
                  risk: example_value
                  impact: example_value
                  category: example_value
                  assigned_to: example_value
                  assignment_group: example_value
                  requested_by: example_value
                  start_date: '2026-01-15T10:30:00Z'
                  end_date: '2026-01-15T10:30:00Z'
                  cmdb_ci: example_value
                  justification: example_value
                  implementation_plan: example_value
                  backout_plan: example_value
                  test_plan: example_value
      responses:
        '200':
          description: Change request successfully updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ChangeRequest'
              examples:
                Updatenormalchange200Example:
                  summary: Default updateNormalChange 200 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      number: example_value
                      short_description: example_value
                      description: A sample description.
                      type: normal
                      state: example_value
                      priority: '1'
                      risk: example_value
                      impact: example_value
                      category: example_value
                      assigned_to: example_value
                      assignment_group: example_value
                      requested_by: example_value
                      start_date: '2026-01-15T10:30:00Z'
                      end_date: '2026-01-15T10:30:00Z'
                      cmdb_ci: example_value
                      close_code: example_value
                      close_notes: example_value
                      approval: example_value
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_updated_on: '2026-01-15T10:30:00Z'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updatenormalchange400Example:
                  summary: Default updateNormalChange 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Change request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updatenormalchange404Example:
                  summary: Default updateNormalChange 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /change/standard:
    get:
      operationId: listStandardChanges
      summary: Servicenow List Standard Change Requests
      description: >-
        Retrieves a list of standard change requests. Standard changes are
        created from pre-approved templates.
      tags:
      - Standard Changes
      parameters:
      - $ref: '#/components/parameters/sysparmQuery'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmLimit'
      - $ref: '#/components/parameters/sysparmOffset'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      responses:
        '200':
          description: Successful response returning standard change requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChangeRequest'
              examples:
                Liststandardchanges200Example:
                  summary: Default listStandardChanges 200 response
                  x-microcks-default: true
                  value:
                    result:
                    - sys_id: '500123'
                      number: example_value
                      short_description: example_value
                      description: A sample description.
                      type: normal
                      state: example_value
                      priority: '1'
                      risk: example_value
                      impact: example_value
                      category: example_value
                      assigned_to: example_value
                      assignment_group: example_value
                      requested_by: example_value
                      start_date: '2026-01-15T10:30:00Z'
                      end_date: '2026-01-15T10:30:00Z'
                      cmdb_ci: example_value
                      close_code: example_value
                      close_notes: example_value
                      approval: example_value
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_updated_on: '2026-01-15T10:30:00Z'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Liststandardchanges401Example:
                  summary: Default listStandardChanges 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /change/standard/{standard_change_template_id}:
    post:
      operationId: createStandardChange
      summary: Servicenow Create a Standard Change From a Template
      description: >-
        Creates a new standard change request based on a pre-approved standard
        change template. The template sys_id determines the default values
        and pre-configured approvals.
      tags:
      - Standard Changes
      parameters:
      - name: standard_change_template_id
        in: path
        required: true
        description: >-
          The sys_id of the standard change template to use for creating the
          change request.
        schema:
          type: string
        example: '500123'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeRequestInput'
            examples:
              CreatestandardchangeRequestExample:
                summary: Default createStandardChange request
                x-microcks-default: true
                value:
                  short_description: example_value
                  description: A sample description.
                  priority: '1'
                  risk: example_value
                  impact: example_value
                  category: example_value
                  assigned_to: example_value
                  assignment_group: example_value
                  requested_by: example_value
                  start_date: '2026-01-15T10:30:00Z'
                  end_date: '2026-01-15T10:30:00Z'
                  cmdb_ci: example_value
                  justification: example_value
                  implementation_plan: example_value
                  backout_plan: example_value
                  test_plan: example_value
      responses:
        '201':
          description: Standard change request successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ChangeRequest'
              examples:
                Createstandardchange201Example:
                  summary: Default createStandardChange 201 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      number: example_value
                      short_description: example_value
                      description: A sample description.
                      type: normal
                      state: example_value
                      priority: '1'
                      risk: example_value
                      impact: example_value
                      category: example_value
                      assigned_to: example_value
                      assignment_group: example_value
                      requested_by: example_value
                      start_date: '2026-01-15T10:30:00Z'
                      end_date: '2026-01-15T10:30:00Z'
                      cmdb_ci: example_value
                      close_code: example_value
                      close_notes: example_value
                      approval: example_value
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_updated_on: '2026-01-15T10:30:00Z'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createstandardchange400Example:
                  summary: Default createStandardChange 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /change/emergency:
    get:
      operationId: listEmergencyChanges
      summary: Servicenow List Emergency Change Requests
      description: >-
        Retrieves a list of emergency change requests. Emergency changes
        bypass normal approval processes for urgent situations.
      tags:
      - Emergency Changes
      parameters:
      - $ref: '#/components/parameters/sysparmQuery'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmLimit'
      - $ref: '#/components/parameters/sysparmOffset'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      responses:
        '200':
          description: Successful response returning emergency change requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChangeRequest'
              examples:
                Listemergencychanges200Example:
                  summary: Default listEmergencyChanges 200 response
                  x-microcks-default: true
                  value:
                    result:
                    - sys_id: '500123'
                      number: example_value
                      short_description: example_value
                      description: A sample description.
                      type: normal
                      state: example_value
                      priority: '1'
                      risk: example_value
                      impact: example_value
                      category: example_value
                      assigned_to: example_value
                      assignment_group: example_value
                      requested_by: example_value
                      start_date: '2026-01-15T10:30:00Z'
                      end_date: '2026-01-15T10:30:00Z'
                      cmdb_ci: example_value
                      close_code: example_value
                      close_notes: example_value
                      approval: example_value
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_updated_on: '2026-01-15T10:30:00Z'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listemergencychanges401Example:
                  summary: Default listEmergencyChanges 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createEmergencyChange
      summary: Servicenow Create an Emergency Change Request
      description: >-
        Creates a new emergency change request for urgent changes that cannot
        wait for standard approval processes.
      tags:
      - Emergency Changes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeRequestInput'
            examples:
              CreateemergencychangeRequestExample:
                summary: Default createEmergencyChange request
                x-microcks-default: true
                value:
                  short_description: example_value
                  description: A sample description.
                  priority: '1'
                  risk: example_value
                  impact: example_value
                  category: example_value
                  assigned_to: example_value
                  assignment_group: example_value
                  requested_by: example_value
                  start_date: '2026-01-15T10:30:00Z'
                  end_date: '2026-01-15T10:30:00Z'
                  cmdb_ci: example_value
                  justification: example_value
                  implementation_plan: example_value
                  backout_plan: example_value
                  test_plan: example_value
      responses:
        '201':
          description: Emergency change request successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ChangeRequest'
              examples:
                Createemergencychange201Example:
                  summary: Default createEmergencyChange 201 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      number: example_value
                      short_description: example_value
                      description: A sample description.
                      type: normal
                      state: example_value
                      priority: '1'
                      risk: example_value
                      impact: example_value
                      category: example_value
                      assigned_to: example_value
                      assignment_group: example_value
                      requested_by: example_value
                      start_date: '2026-01-15T10:30:00Z'
                      end_date: '2026-01-15T10:30:00Z'
                      cmdb_ci: example_value
                      close_code: example_value
                      close_notes: example_value
                      approval: example_value
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_updated_on: '2026-01-15T10:30:00Z'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createemergencychange400Example:
                  summary: Default createEmergencyChange 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /change/{sys_id}/task:
    get:
      operationId: listChangeTasks
      summary: Servicenow List Tasks for a Change Request
      description: >-
        Retrieves all tasks associated with the specified change request.
      tags:
      - Change Tasks
      parameters:
      - $ref: '#/components/parameters/sysId'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmLimit'
      - $ref: '#/components/parameters/sysparmOffset'
      responses:
        '200':
          description: Successful response returning change tasks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChangeTask'
              examples:
                Listchangetasks200Example:
                  summary: Default listChangeTasks 200 response
                  x-microcks-default: true
                  value:
                    result:
                    - sys_id: '500123'
                      number: example_value
                      short_description: example_value
                      state: example_value
                      assigned_to: example_value
                      change_request: example_value
                      planned_start_date: '2026-01-15T10:30:00Z'
                      planned_end_date: '2026-01-15T10:30:00Z'
        '404':
          description: Change request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listchangetasks404Example:
                  summary: Default listChangeTasks 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createChangeTask
      summary: Servicenow Create a Task for a Change Request
      description: >-
        Creates a new task associated with the specified change request.
      tags:
      - Change Tasks
      parameters:
      - $ref: '#/components/parameters/sysId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeTaskInput'
            examples:
              CreatechangetaskRequestExample:
                summary: Default createChangeTask request
                x-microcks-default: true
                value:
                  short_description: example_value
                  description: A sample description.
                  assigned_to: example_value
                  assignment_group: example_value
                  planned_start_date: '2026-01-15T10:30:00Z'
                  planned_end_date: '2026-01-15T10:30:00Z'
      responses:
        '201':
          description: Change task successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ChangeTask'
              examples:
                Createchangetask201Example:
                  summary: Default createChangeTask 201 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      number: example_value
                      short_description: example_value
                      state: example_value
                      assigned_to: example_value
                      change_request: example_value
                      planned_start_date: '2026-01-15T10:30:00Z'
                      planned_end_date: '2026-01-15T10:30:00Z'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createchangetask400Example:
                  summary: Default createChangeTask 400 response
                  x-microcks-default: true
        

# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/servicenow/refs/heads/main/openapi/servicenow-change-management-api-openapi.yml