ServiceNow Table Records API

openapi: 3.1.0
info:
  title: ServiceNow Contact Aggregate Statistics Table Records API
  description: 'The Contact API provides endpoints that enable you to retrieve and update Customer Service Management (CSM) contact records.


    In addition, you can generate new social media profile records when creating a contact.


    The Contact API requires the Customer Service plugin (com.sn_customerservice) and is provided within the now namespace.


    **Authentication**: Users need the `csm_ws_integration` role for full API access.

    '
  version: Zurich
  contact:
    name: ServiceNow
    url: https://docs.servicenow.com
  x-namespace: now
servers:
- url: https://{instance}.servicenow.com/api/now
  description: ServiceNow instance
  variables:
    instance:
      default: instance
      description: Your ServiceNow instance name
security:
- basicAuth: []
tags:
- name: Table Records
  description: Operations for creating, reading, updating, and deleting records in ServiceNow tables.
paths:
  /table/{tableName}:
    get:
      operationId: listRecords
      summary: Servicenow List Records From a Table
      description: Retrieves multiple records from the specified ServiceNow table. Supports encoded query filtering, field selection, pagination via limit and offset, and control over display values and link formatting.
      tags:
      - Table Records
      parameters:
      - $ref: '#/components/parameters/tableName'
      - $ref: '#/components/parameters/sysparmQuery'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmLimit'
      - $ref: '#/components/parameters/sysparmOffset'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      - $ref: '#/components/parameters/sysparmExcludeReferenceLink'
      - $ref: '#/components/parameters/sysparmSuppressPaginationHeader'
      - $ref: '#/components/parameters/sysparmView'
      - $ref: '#/components/parameters/sysparmQueryCategory'
      - $ref: '#/components/parameters/sysparmQueryNoDomain'
      - $ref: '#/components/parameters/sysparmNoCount'
      responses:
        '200':
          description: Successful response returning an array of records matching the query criteria.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Record'
              examples:
                Listrecords200Example:
                  summary: Default listRecords 200 response
                  x-microcks-default: true
                  value:
                    result:
                    - sys_id: '500123'
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_created_by: example_value
                      sys_updated_on: '2026-01-15T10:30:00Z'
                      sys_updated_by: example_value
                      sys_mod_count: 42
                      sys_tags: example_value
                      sys_class_name: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listrecords401Example:
                  summary: Default listRecords 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '403':
          description: Forbidden. The authenticated user does not have access to the specified table.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listrecords403Example:
                  summary: Default listRecords 403 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createRecord
      summary: Servicenow Create a Record in a Table
      description: Creates a new record in the specified ServiceNow table. The request body should contain field name-value pairs for the new record. Fields not included in the request body use their default values.
      tags:
      - Table Records
      parameters:
      - $ref: '#/components/parameters/tableName'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      - $ref: '#/components/parameters/sysparmExcludeReferenceLink'
      - $ref: '#/components/parameters/sysparmView'
      - $ref: '#/components/parameters/sysparmInputDisplayValue'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordInput'
            examples:
              CreaterecordRequestExample:
                summary: Default createRecord request
                x-microcks-default: true
                value: {}
      responses:
        '201':
          description: Record successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Record'
              examples:
                Createrecord201Example:
                  summary: Default createRecord 201 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_created_by: example_value
                      sys_updated_on: '2026-01-15T10:30:00Z'
                      sys_updated_by: example_value
                      sys_mod_count: 42
                      sys_tags: example_value
                      sys_class_name: example_value
        '400':
          description: Bad request. The request body contains invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createrecord400Example:
                  summary: Default createRecord 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createrecord401Example:
                  summary: Default createRecord 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /table/{tableName}/{sys_id}:
    get:
      operationId: getRecord
      summary: Servicenow Retrieve a Single Record
      description: Retrieves a single record from the specified table by its unique sys_id identifier. Supports field selection and display value formatting.
      tags:
      - Table Records
      parameters:
      - $ref: '#/components/parameters/tableName'
      - $ref: '#/components/parameters/sysId'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      - $ref: '#/components/parameters/sysparmExcludeReferenceLink'
      - $ref: '#/components/parameters/sysparmView'
      responses:
        '200':
          description: Successful response returning the requested record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Record'
              examples:
                Getrecord200Example:
                  summary: Default getRecord 200 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_created_by: example_value
                      sys_updated_on: '2026-01-15T10:30:00Z'
                      sys_updated_by: example_value
                      sys_mod_count: 42
                      sys_tags: example_value
                      sys_class_name: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getrecord401Example:
                  summary: Default getRecord 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Not found. The specified record does not exist or the user does not have access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getrecord404Example:
                  summary: Default getRecord 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateRecord
      summary: Servicenow Update a Record
      description: Updates an existing record in the specified table. The request body should contain the fields to be updated. Fields not included in the request body are not modified.
      tags:
      - Table Records
      parameters:
      - $ref: '#/components/parameters/tableName'
      - $ref: '#/components/parameters/sysId'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      - $ref: '#/components/parameters/sysparmExcludeReferenceLink'
      - $ref: '#/components/parameters/sysparmView'
      - $ref: '#/components/parameters/sysparmInputDisplayValue'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordInput'
            examples:
              UpdaterecordRequestExample:
                summary: Default updateRecord request
                x-microcks-default: true
                value: {}
      responses:
        '200':
          description: Record successfully updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Record'
              examples:
                Updaterecord200Example:
                  summary: Default updateRecord 200 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_created_by: example_value
                      sys_updated_on: '2026-01-15T10:30:00Z'
                      sys_updated_by: example_value
                      sys_mod_count: 42
                      sys_tags: example_value
                      sys_class_name: example_value
        '400':
          description: Bad request. The request body contains invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updaterecord400Example:
                  summary: Default updateRecord 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updaterecord401Example:
                  summary: Default updateRecord 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Not found. The specified record does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updaterecord404Example:
                  summary: Default updateRecord 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: patchRecord
      summary: Servicenow Patch a Record
      description: Partially updates an existing record in the specified table. Only the fields included in the request body are modified. This is functionally similar to PUT but follows the PATCH semantics for partial updates.
      tags:
      - Table Records
      parameters:
      - $ref: '#/components/parameters/tableName'
      - $ref: '#/components/parameters/sysId'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      - $ref: '#/components/parameters/sysparmExcludeReferenceLink'
      - $ref: '#/components/parameters/sysparmView'
      - $ref: '#/components/parameters/sysparmInputDisplayValue'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordInput'
            examples:
              PatchrecordRequestExample:
                summary: Default patchRecord request
                x-microcks-default: true
                value: {}
      responses:
        '200':
          description: Record successfully patched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Record'
              examples:
                Patchrecord200Example:
                  summary: Default patchRecord 200 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_created_by: example_value
                      sys_updated_on: '2026-01-15T10:30:00Z'
                      sys_updated_by: example_value
                      sys_mod_count: 42
                      sys_tags: example_value
                      sys_class_name: example_value
        '400':
          description: Bad request. The request body contains invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Patchrecord400Example:
                  summary: Default patchRecord 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Patchrecord401Example:
                  summary: Default patchRecord 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Not found. The specified record does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Patchrecord404Example:
                  summary: Default patchRecord 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteRecord
      summary: Servicenow Delete a Record
      description: Deletes a record from the specified table by its sys_id. This operation is permanent and cannot be undone through the API.
      tags:
      - Table Records
      parameters:
      - $ref: '#/components/parameters/tableName'
      - $ref: '#/components/parameters/sysId'
      responses:
        '204':
          description: Record successfully deleted. No content returned.
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Deleterecord401Example:
                  summary: Default deleteRecord 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Not found. The specified record does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Deleterecord404Example:
                  summary: Default deleteRecord 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    sysparmFields:
      name: sysparm_fields
      in: query
      required: false
      description: A comma-separated list of field names to include in the response. When specified, only these fields are returned, improving response performance.
      schema:
        type: string
      example: sys_id,number,short_description,state,priority
    sysparmQueryNoDomain:
      name: sysparm_query_no_domain
      in: query
      required: false
      description: When set to true, the query ignores domain separation and returns records from all domains.
      schema:
        type: boolean
        default: false
    sysparmSuppressPaginationHeader:
      name: sysparm_suppress_pagination_header
      in: query
      required: false
      description: When set to true, the Link header for pagination is not included in the response.
      schema:
        type: boolean
        default: false
    sysparmOffset:
      name: sysparm_offset
      in: query
      required: false
      description: The starting record index for pagination. Use with sysparm_limit to page through large result sets.
      schema:
        type: integer
        minimum: 0
        default: 0
    sysparmView:
      name: sysparm_view
      in: query
      required: false
      description: The UI view to use for determining which fields to return. When specified, only fields visible in the named view are included.
      schema:
        type: string
    tableName:
      name: tableName
      in: path
      required: true
      description: The name of the ServiceNow table to operate on, such as incident, change_request, cmdb_ci, or any custom table.
      schema:
        type: string
      example: incident
    sysparmQuery:
      name: sysparm_query
      in: query
      required: false
      description: An encoded query string used to filter the result set. Supports operators like =, !=, LIKE, STARTSWITH, ENDSWITH, IN, and boolean operators ^, ^OR. Use ORDERBY and ORDERBYDESC for sorting.
      schema:
        type: string
      example: active=true^priority=1^ORDERBYDESCsys_created_on
    sysparmInputDisplayValue:
      name: sysparm_input_display_value
      in: query
      required: false
      description: When set to true, input values are treated as display values rather than actual values. This allows setting fields using their display labels instead of internal values.
      schema:
        type: boolean
        default: false
    sysparmDisplayValue:
      name: sysparm_display_value
      in: query
      required: false
      description: Controls the format of field values in the response. Set to true to return display values, false to return actual values, or all to return both in a display_value and value object.
      schema:
        type: string
        enum:
        - 'true'
        - 'false'
        - all
        default: 'false'
    sysparmExcludeReferenceLink:
      name: sysparm_exclude_reference_link
      in: query
      required: false
      description: When set to true, reference fields do not include a link attribute in the response, reducing payload size.
      schema:
        type: boolean
        default: false
    sysparmQueryCategory:
      name: sysparm_query_category
      in: query
      required: false
      description: The name of the query category used to filter the query.
      schema:
        type: string
    sysparmLimit:
      name: sysparm_limit
      in: query
      required: false
      description: The maximum number of records to return in a single request. The default is determined by the instance configuration, typically 10000.
      schema:
        type: integer
        minimum: 1
        default: 10000
    sysId:
      name: sys_id
      in: path
      required: true
      description: The unique 32-character system identifier for a record in ServiceNow.
      schema:
        type: string
        pattern: ^[a-f0-9]{32}$
    sysparmNoCount:
      name: sysparm_no_count
      in: query
      required: false
      description: When set to true, the response does not include the X-Total-Count header, which can improve performance for large tables.
      schema:
        type: boolean
        default: false
  schemas:
    Record:
      type: object
      description: A generic ServiceNow record. The actual fields depend on the table being queried. Common system fields are included in every record.
      properties:
        sys_id:
          type: string
          description: The unique 32-character system identifier for the record.
          example: '500123'
        sys_created_on:
          type: string
          format: date-time
          description: The date and time when the record was created.
          example: '2026-01-15T10:30:00Z'
        sys_created_by:
          type: string
          description: The user who created the record.
          example: example_value
        sys_updated_on:
          type: string
          format: date-time
          description: The date and time when the record was last updated.
          example: '2026-01-15T10:30:00Z'
        sys_updated_by:
          type: string
          description: The user who last updated the record.
          example: example_value
        sys_mod_count:
          type: integer
          description: The number of times the record has been modified.
          example: 42
        sys_tags:
          type: string
          description: System tags associated with the record.
          example: example_value
        sys_class_name:
          type: string
          description: The table class name for the record.
          example: example_value
      additionalProperties: true
    RecordInput:
      type: object
      description: A set of field name-value pairs to create or update a record. The accepted fields depend on the target table and the user's ACL permissions.
      additionalProperties: true
    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
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication with ServiceNow credentials. User must have the csm_ws_integration role.