ServiceNow Standard Changes API

openapi: 3.2.0
info:
  title: ServiceNow Change Management Standard Changes 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
servers:
- url: https://{instance}.service-now.com/api/sn_chg_rest/v1
  description: ServiceNow Instance
  variables:
    instance:
      default: instance
      description: Your ServiceNow instance name
security:
- basicAuth: []
- oauth2: []
tags:
- name: Standard Changes
  description: Operations for managing standard change requests based on pre-approved templates.
paths:
  /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
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: A human-readable error message.
            detail:
              type: string
              description: Detailed information about the error.
          example: example_value
    ChangeRequest:
      type: object
      description: A ServiceNow change request record.
      properties:
        sys_id:
          type: string
          description: Unique identifier for the change request.
          example: '500123'
        number:
          type: string
          description: The human-readable change request number.
          example: example_value
        short_description:
          type: string
          description: A brief summary of the change.
          example: example_value
        description:
          type: string
          description: A detailed description of the change and its purpose.
          example: A sample description.
        type:
          type: string
          description: 'The change type: normal, standard, or emergency.'
          enum:
          - normal
          - standard
          - emergency
          example: normal
        state:
          type: string
          description: The current state of the change request in its lifecycle.
          example: example_value
        priority:
          type: string
          description: The priority level of the change request.
          enum:
          - '1'
          - '2'
          - '3'
          - '4'
          example: '1'
        risk:
          type: string
          description: The risk level assessed for this change.
          example: example_value
        impact:
          type: string
          description: The impact level of this change.
          example: example_value
        category:
          type: string
          description: The category of the change.
          example: example_value
        assigned_to:
          type: string
          description: The sys_id of the user assigned to implement the change.
          example: example_value
        assignment_group:
          type: string
          description: The sys_id of the group responsible for the change.
          example: example_value
        requested_by:
          type: string
          description: The sys_id of the user who requested the change.
          example: example_value
        start_date:
          type: string
          format: date-time
          description: The planned start date and time for the change.
          example: '2026-01-15T10:30:00Z'
        end_date:
          type: string
          format: date-time
          description: The planned end date and time for the change.
          example: '2026-01-15T10:30:00Z'
        cmdb_ci:
          type: string
          description: The sys_id of the configuration item affected by this change.
          example: example_value
        close_code:
          type: string
          description: The close code indicating how the change was resolved.
          example: example_value
        close_notes:
          type: string
          description: Notes recorded when closing the change request.
          example: example_value
        approval:
          type: string
          description: The current approval status.
          example: example_value
        sys_created_on:
          type: string
          format: date-time
          description: The date and time the change request was created.
          example: '2026-01-15T10:30:00Z'
        sys_updated_on:
          type: string
          format: date-time
          description: The date and time the change request was last updated.
          example: '2026-01-15T10:30:00Z'
    ChangeRequestInput:
      type: object
      description: Fields for creating or updating a change request.
      properties:
        short_description:
          type: string
          description: A brief summary of the change.
          example: example_value
        description:
          type: string
          description: A detailed description of the change.
          example: A sample description.
        priority:
          type: string
          description: The priority level.
          enum:
          - '1'
          - '2'
          - '3'
          - '4'
          example: '1'
        risk:
          type: string
          description: The risk level.
          example: example_value
        impact:
          type: string
          description: The impact level.
          example: example_value
        category:
          type: string
          description: The category of the change.
          example: example_value
        assigned_to:
          type: string
          description: The sys_id of the assigned user.
          example: example_value
        assignment_group:
          type: string
          description: The sys_id of the assignment group.
          example: example_value
        requested_by:
          type: string
          description: The sys_id of the requesting user.
          example: example_value
        start_date:
          type: string
          format: date-time
          description: The planned start date and time.
          example: '2026-01-15T10:30:00Z'
        end_date:
          type: string
          format: date-time
          description: The planned end date and time.
          example: '2026-01-15T10:30:00Z'
        cmdb_ci:
          type: string
          description: The sys_id of the affected configuration item.
          example: example_value
        justification:
          type: string
          description: The business justification for the change.
          example: example_value
        implementation_plan:
          type: string
          description: The plan for implementing the change.
          example: example_value
        backout_plan:
          type: string
          description: The plan for reverting the change if needed.
          example: example_value
        test_plan:
          type: string
          description: The plan for testing the change.
          example: example_value
  parameters:
    sysparmDisplayValue:
      name: sysparm_display_value
      in: query
      required: false
      description: Controls the format of field values in the response.
      schema:
        type: string
        enum:
        - 'true'
        - 'false'
        - all
        default: 'false'
    sysparmFields:
      name: sysparm_fields
      in: query
      required: false
      description: A comma-separated list of field names to include in the response.
      schema:
        type: string
    sysparmOffset:
      name: sysparm_offset
      in: query
      required: false
      description: Starting record index for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    sysparmQuery:
      name: sysparm_query
      in: query
      required: false
      description: An encoded query string to filter results.
      schema:
        type: string
    sysparmLimit:
      name: sysparm_limit
      in: query
      required: false
      description: Maximum number of records to return.
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication with ServiceNow credentials. The user must have the change_manager, change_admin, or itil role.
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication using ServiceNow's OAuth provider.
      flows:
        password:
          tokenUrl: https://{instance}.service-now.com/oauth_token.do
          scopes: {}
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