ServiceNow Trouble Ticket API

openapi: 3.1.0
info:
  title: ServiceNow Contact Aggregate Statistics Trouble Ticket 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: Trouble Ticket
  description: Operations for managing trouble tickets (Cases, Incidents, and Service Problem Cases)
paths:
  /troubleTicket:
    get:
      tags:
      - Trouble Ticket
      summary: Servicenow Retrieve All Trouble Tickets
      description: Retrieves a list of all trouble ticket records from the Case, Incident, and Service Problem Case tables.
      operationId: getTroubleTickets
      parameters:
      - name: fields
        in: query
        description: List of fields to return in the response. Invalid fields are ignored.
        required: false
        schema:
          type: string
        example: id,name,description,status,severity,ticketType
      - name: id
        in: query
        description: Filter trouble tickets by sys_id
        required: false
        schema:
          type: string
        example: abc123
      - name: limit
        in: query
        description: Maximum number of records to return
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        example: 10
      - name: offset
        in: query
        description: Starting index at which to begin retrieving records
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        example: 10
      - name: severity
        in: query
        description: Filter trouble tickets by severity
        required: false
        schema:
          type: string
        example: example_value
      - name: status
        in: query
        description: Filter trouble tickets by status
        required: false
        schema:
          type: string
        example: example_value
      - name: ticketType
        in: query
        description: Filter trouble tickets by ticket type
        required: false
        schema:
          type: string
          enum:
          - Case
          - Incident
          - Service Problem Case
        example: Case
      responses:
        '200':
          description: Request successfully processed. Full resource returned in response (no pagination).
          headers:
            Content-Type:
              schema:
                type: string
                default: application/json
            X-Total-Count:
              description: Total number of records available on the server
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TroubleTicket'
              examples:
                Gettroubletickets200Example:
                  summary: Default getTroubleTickets 200 response
                  x-microcks-default: true
                  value:
                  - '@type': example_value
                    id: abc123
                    href: example_value
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdate: '2026-01-15T10:30:00Z'
                    name: Example Title
                    description: A sample description.
                    severity: example_value
                    status: example_value
                    ticketType: Case
                    channel:
                      name: Example Title
                    note:
                    - {}
                    relatedEntity:
                    - {}
                    relatedParty:
                    - {}
        '206':
          description: Partial resource returned in response (with pagination).
          headers:
            Content-Range:
              description: Range of content returned in a paginated call
              schema:
                type: string
              example: items 3-5
            Content-Type:
              schema:
                type: string
                default: application/json
            Link:
              description: Links to navigate through query results (first, last, next, previous)
              schema:
                type: string
            X-Total-Count:
              description: Total number of records available on the server
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TroubleTicket'
              examples:
                Gettroubletickets206Example:
                  summary: Default getTroubleTickets 206 response
                  x-microcks-default: true
                  value:
                  - '@type': example_value
                    id: abc123
                    href: example_value
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdate: '2026-01-15T10:30:00Z'
                    name: Example Title
                    description: A sample description.
                    severity: example_value
                    status: example_value
                    ticketType: Case
                    channel:
                      name: Example Title
                    note:
                    - {}
                    relatedEntity:
                    - {}
                    relatedParty:
                    - {}
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Gettroubletickets400Example:
                  summary: Default getTroubleTickets 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Record not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Gettroubletickets404Example:
                  summary: Default getTroubleTickets 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Trouble Ticket
      summary: Servicenow Create a Trouble Ticket
      description: Creates a record in the Case, Incident, or Service Problem Case table.
      operationId: createTroubleTicket
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TroubleTicketCreate'
            examples:
              CreatetroubleticketRequestExample:
                summary: Default createTroubleTicket request
                x-microcks-default: true
                value:
                  name: Example Title
                  description: A sample description.
                  severity: '1'
                  status: example_value
                  ticketType: Case
                  channel:
                    name: Example Title
                  note:
                  - text: example_value
                    '@type': comments
                  relatedEntity:
                  - id: abc123
                    '@referredType': asset
                  relatedParty:
                  - id: abc123
                    '@referredType': customer
      responses:
        '201':
          description: Successful. The request was successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TroubleTicket'
              examples:
                Createtroubleticket201Example:
                  summary: Default createTroubleTicket 201 response
                  x-microcks-default: true
                  value:
                    '@type': example_value
                    id: abc123
                    href: example_value
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdate: '2026-01-15T10:30:00Z'
                    name: Example Title
                    description: A sample description.
                    severity: example_value
                    status: example_value
                    ticketType: Case
                    channel:
                      name: Example Title
                    note:
                    - '@type': example_value
                      text: example_value
                      date: '2026-01-15T10:30:00Z'
                      author: example_value
                    relatedEntity:
                    - '@type': example_value
                      id: abc123
                      href: example_value
                      name: Example Title
                      role: example_value
                      '@referredType': asset
                    relatedParty:
                    - id: abc123
                      name: Example Title
                      '@referredType': assigned_to
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createtroubleticket400Example:
                  summary: Default createTroubleTicket 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /troubleTicket/{id}:
    get:
      tags:
      - Trouble Ticket
      summary: Servicenow Retrieve a Specific Trouble Ticket
      description: Retrieves a specified record from the Case, Incident, or Service Problem Case table.
      operationId: getTroubleTicketById
      parameters:
      - name: id
        in: path
        description: Sys_id of the case or incident record to retrieve
        required: true
        schema:
          type: string
        example: abc123
      - name: fields
        in: query
        description: List of fields to return in the response. Invalid fields are ignored.
        required: false
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successful. The request was successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TroubleTicket'
              examples:
                Gettroubleticketbyid200Example:
                  summary: Default getTroubleTicketById 200 response
                  x-microcks-default: true
                  value:
                    '@type': example_value
                    id: abc123
                    href: example_value
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdate: '2026-01-15T10:30:00Z'
                    name: Example Title
                    description: A sample description.
                    severity: example_value
                    status: example_value
                    ticketType: Case
                    channel:
                      name: Example Title
                    note:
                    - '@type': example_value
                      text: example_value
                      date: '2026-01-15T10:30:00Z'
                      author: example_value
                    relatedEntity:
                    - '@type': example_value
                      id: abc123
                      href: example_value
                      name: Example Title
                      role: example_value
                      '@referredType': asset
                    relatedParty:
                    - id: abc123
                      name: Example Title
                      '@referredType': assigned_to
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Gettroubleticketbyid400Example:
                  summary: Default getTroubleTicketById 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Record not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Gettroubleticketbyid404Example:
                  summary: Default getTroubleTicketById 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      tags:
      - Trouble Ticket
      summary: Servicenow Update a Trouble Ticket
      description: Updates a specified record in the Case, Incident, or Service Problem Case table.
      operationId: updateTroubleTicket
      parameters:
      - name: id
        in: path
        description: Sys_id of the case or incident record to update
        required: true
        schema:
          type: string
        example: abc123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TroubleTicketUpdate'
            examples:
              UpdatetroubleticketRequestExample:
                summary: Default updateTroubleTicket request
                x-microcks-default: true
                value:
                  name: Example Title
                  description: A sample description.
                  severity: '1'
                  status: example_value
                  channel:
                    name: Example Title
                  note:
                  - text: example_value
                    '@type': comments
                  relatedEntity:
                  - id: abc123
                    '@referredType': asset
                  relatedParty:
                  - id: abc123
                    '@referredType': customer
      responses:
        '200':
          description: Successful. The request was successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TroubleTicket'
              examples:
                Updatetroubleticket200Example:
                  summary: Default updateTroubleTicket 200 response
                  x-microcks-default: true
                  value:
                    '@type': example_value
                    id: abc123
                    href: example_value
                    creationDate: '2026-01-15T10:30:00Z'
                    lastUpdate: '2026-01-15T10:30:00Z'
                    name: Example Title
                    description: A sample description.
                    severity: example_value
                    status: example_value
                    ticketType: Case
                    channel:
                      name: Example Title
                    note:
                    - '@type': example_value
                      text: example_value
                      date: '2026-01-15T10:30:00Z'
                      author: example_value
                    relatedEntity:
                    - '@type': example_value
                      id: abc123
                      href: example_value
                      name: Example Title
                      role: example_value
                      '@referredType': asset
                    relatedParty:
                    - id: abc123
                      name: Example Title
                      '@referredType': assigned_to
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updatetroubleticket400Example:
                  summary: Default updateTroubleTicket 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Record not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updatetroubleticket404Example:
                  summary: Default updateTroubleTicket 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Note:
      type: object
      properties:
        '@type':
          type: string
          default: comments
          description: The type of note (always 'comments' in responses)
          example: example_value
        text:
          type: string
          description: The comment text
          example: example_value
        date:
          type: string
          format: date-time
          description: The date the comment was created
          example: '2026-01-15T10:30:00Z'
        author:
          type: string
          description: The name of the user who wrote the comment
          example: example_value
    RelatedPartyInput:
      type: object
      required:
      - id
      - '@referredType'
      properties:
        id:
          type: string
          description: Sys_id of the related party
          example: abc123
        '@referredType':
          type: string
          enum:
          - customer
          - customer_contact
          description: 'Type of related party:

            - customer: Company or account for the ticket

            - customer_contact: Caller or contact for the ticket

            '
          example: customer
    NoteInput:
      type: object
      required:
      - text
      - '@type'
      properties:
        text:
          type: string
          description: Note text
          example: example_value
        '@type':
          type: string
          enum:
          - comments
          - work_notes
          description: Type of note (determines whether recorded in Work notes or Additional comments field)
          example: comments
    RelatedParty:
      type: object
      properties:
        id:
          type: string
          description: Sys_id of the related party
          example: abc123
        name:
          type: string
          description: Name of the related party
          example: Example Title
        '@referredType':
          type: string
          enum:
          - assigned_to
          - assignment_group
          - customer
          - customer_contact
          description: 'Type of related party:

            - assigned_to: User assigned to work on the ticket

            - assignment_group: Group assigned to work on the ticket

            - customer: Company or account for the ticket

            - customer_contact: Caller or contact for the ticket

            '
          example: assigned_to
    TroubleTicketCreate:
      type: object
      required:
      - description
      - severity
      - status
      properties:
        name:
          type: string
          description: Name of the trouble ticket, typically a short description of the issue
          example: Example Title
        description:
          type: string
          description: A description of the issue
          example: A sample description.
        severity:
          type: string
          enum:
          - '1'
          - '2'
          - '3'
          - '4'
          - '5'
          description: 'The severity of the issue (must provide choice value only):

            - 1: Critical

            - 2: High

            - 3: Moderate

            - 4: Low

            - 5: Planning (Incident only)

            '
          example: '1'
        status:
          type: string
          description: The current status of the trouble ticket (can provide choice label or value)
          example: example_value
        ticketType:
          type: string
          enum:
          - Case
          - Incident
          - Service Problem Case
          default: Incident
          description: The type of ticket to create
          example: Case
        channel:
          $ref: '#/components/schemas/ChannelInput'
        note:
          type: array
          description: List of work notes and comments to add to the ticket
          items:
            $ref: '#/components/schemas/NoteInput'
          example: []
        relatedEntity:
          type: array
          description: List of impacted assets, products, sold products, configuration items, or services
          items:
            $ref: '#/components/schemas/RelatedEntityInput'
          example: []
        relatedParty:
          type: array
          description: Details about contacts for the ticket
          items:
            $ref: '#/components/schemas/RelatedPartyInput'
          example: []
    ChannelInput:
      type: object
      properties:
        name:
          type: string
          description: Name of the contact method (can provide choice label or value, e.g., 'Virtual Agent' or 'virtual_agent')
          example: Example Title
    TroubleTicketUpdate:
      type: object
      properties:
        name:
          type: string
          description: Name of the trouble ticket, typically a short description of the issue
          example: Example Title
        description:
          type: string
          description: Description of the issue
          example: A sample description.
        severity:
          type: string
          enum:
          - '1'
          - '2'
          - '3'
          - '4'
          - '5'
          description: 'The severity of the issue (must provide choice value only):

            - 1: Critical

            - 2: High

            - 3: Moderate

            - 4: Low

            - 5: Planning (Incident only)

            '
          example: '1'
        status:
          type: string
          description: The current status of the trouble ticket (can provide choice label or value)
          example: example_value
        channel:
          $ref: '#/components/schemas/ChannelInput'
        note:
          type: array
          description: List of work notes and comments to add to the ticket
          items:
            $ref: '#/components/schemas/NoteInput'
          example: []
        relatedEntity:
          type: array
          description: List of impacted assets, products, sold products, configuration items, or services
          items:
            $ref: '#/components/schemas/RelatedEntityInput'
          example: []
        relatedParty:
          type: array
          description: Details about contacts for the ticket
          items:
            $ref: '#/components/schemas/RelatedPartyInput'
          example: []
    RelatedEntity:
      type: object
      properties:
        '@type':
          type: string
          default: relatedEntity
          description: This value is always relatedEntity
          example: example_value
        id:
          type: string
          description: Sys_id of the impacted item or service
          example: abc123
        href:
          type: string
          description: Returns an empty string
          example: example_value
        name:
          type: string
          description: Name of the impacted item or service
          example: Example Title
        role:
          type: string
          description: Description of the impacted item or service
          example: example_value
        '@referredType':
          type: string
          enum:
          - asset
          - product
          - product_inventory
          - cmdb_ci
          - cmdb_ci_service
          description: Type of item or service
          example: asset
    TroubleTicket:
      type: object
      properties:
        '@type':
          type: string
          default: TroubleTicket
          description: This value is always TroubleTicket
          example: example_value
        id:
          type: string
          description: The sys_id of the case or incident record
          example: abc123
        href:
          type: string
          description: Relative link to the case or incident record
          example: example_value
        creationDate:
          type: string
          format: date-time
          description: The date that the case or incident record was created
          example: '2026-01-15T10:30:00Z'
        lastUpdate:
          type: string
          format: date-time
          description: The date the record was last updated
          example: '2026-01-15T10:30:00Z'
        name:
          type: string
          description: The name of the trouble ticket, typically a short description of the issue
          example: Example Title
        description:
          type: string
          description: The description of the issue from the ticket
          example: A sample description.
        severity:
          type: string
          description: The severity of the issue described by the trouble ticket
          example: 2 - High
        status:
          type: string
          description: The current status of the trouble ticket
          example: example_value
        ticketType:
          type: string
          enum:
          - Case
          - Incident
          - Service Problem Case
          description: The type of ticket
          example: Case
        channel:
          $ref: '#/components/schemas/Channel'
        note:
          type: array
          description: A list of all comments on the ticket (excludes work notes)
          items:
            $ref: '#/components/schemas/Note'
          example: []
        relatedEntity:
          type: array
          description: List of impacted assets, products, sold products, configuration items, or services
          items:
            $ref: '#/components/schemas/RelatedEntity'
          example: []
        relatedParty:
          type: array
          description: Details about contacts for the ticket
          items:
            $ref: '#/components/schemas/RelatedParty'
          example: []
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Error message
            detail:
              type: string
              description: Detailed error information
          example: example_value
    Channel:
      type: object
      properties:
        name:
          type: string
          description: The name of the contact method
          example: Example Title
    RelatedEntityInput:
      type: object
      required:
      - id
      - '@referredType'
      properties:
        id:
          type: string
          description: Sys_id of the impacted item or service
          example: abc123
        '@referredType':
          type: string
          enum:
          - asset
          - product
          - product_inventory
          - cmdb_ci
          - cmdb_ci_service
          description: Type of item or service
          example: asset
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication with ServiceNow credentials. User must have the csm_ws_integration role.