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.