Standard Incident API

Overview

The Standard Incident API is a REST integration layer that enables client systems to create, update, query, and manage ServiceNow incidents through a unified interface. It supports the full incident lifecycle, including attachments, incident tasks, and system health monitoring.

Key Capabilities

📝 Create & Update

POST and PUT operations with comprehensive payload validation and ServiceNow field mapping

🔍 Powerful Query

GET with 20+ filter parameters including state, date ranges, users, CI, and RPA/Moogsoft identifiers

📎 Attachments

Upload (async) and download attachments with Base64 encoding, up to ~3 MB per file

🩺 Health Monitoring

Stats and healthcheck endpoints for load balancers and observability tooling

Use Cases

Monitoring Integration: Auto-create incidents from Nagios, Moogsoft, or other alerting systems
Service Desk Automation: Programmatic ticket creation and updates from client portals
Reporting Dashboards: Query active incidents with rich filtering for real-time dashboards
Bi-Directional Sync: Keep external ticketing systems in sync with ServiceNow

Architecture

The API follows the MuleSoft API-Led Connectivity pattern, sitting between client systems and ServiceNow with routing, validation, and transformation logic.

graph LR A["🖥️ Client Systems"] B["📡 Standard Incident API"] C["🔐 Auth Layer"] D["🔀 Routing"] E["🔄 Transform"] F["⚙️ ServiceNow"] A -->|HTTPS| B B --> C C --> D D --> E E --> F F -->|Response| B B -->|Response| A style A fill:#f0f9ff,stroke:#000099,stroke-width:2px style B fill:#fce7f3,stroke:#c12e6b,stroke-width:2px style C fill:#fce7f3,stroke:#c12e6b,stroke-width:2px style D fill:#fce7f3,stroke:#c12e6b,stroke-width:2px style E fill:#fce7f3,stroke:#c12e6b,stroke-width:2px style F fill:#fed7aa,stroke:#f98b1c,stroke-width:2px

Environment URLs

Environment	Base URL
QC (Quality Control)	`https://muleqc.diam.compucom.com/api/standard`
Production	`https://muleprod.diam.compucom.com/api/standard`

Available Versions

v1 — /api/standard/incident (Basic Auth; no interfaceType required on GET)
v2 — /api/standard/v2/incident (OAuth 2.0 Bearer; interfaceType required on GET; supports GET by incident number)

Authentication

The API supports two authentication methods depending on the API version selected.

Basic Authentication (v1)

Username and password base64-encoded in the Authorization header.

Use Case: Server-to-server integrations and legacy systems with secure credential storage.

Authorization: Basic <base64-encoded-credentials>

OAuth 2.0 (v2)

Token-based authentication with automatic refresh. Provides enhanced security with time-limited access tokens.

Use Case: Recommended for new integrations, client applications, and scenarios requiring strong security.

Authorization: Bearer <oauth-access-token>

📋 Credentials: To obtain username, password, client_id, and client_secret, contact the Compucom MuleSoft Team.

Request Envelope

Every POST and PUT request requires the following envelope fields, with the incident data nested inside payload:

Field	Type	Required	Description
`transmitId`	string	Yes	Unique transaction identifier (not the client ticket number)
`interfaceType`	string	Yes	Interface type (e.g., "ESB Client", "Twilio")
`senderId`	string	Yes	Sender system identifier
`transmitDt`	string	Yes	Transaction timestamp in GMT (YYYY-MM-DDTHH:MM:SSZ)
`openedDt`	string	Yes	Incident open timestamp in GMT
`sourceRefNumber`	string	No	External reference number, useful for idempotent updates
`payload`	object	Yes	Incident data (must include `longDescription` and `caller.company`)

API Endpoints

The API exposes the following operations. All endpoints are prefixed with /api/standard.

📝 POST /incident

POST Basic / Bearer

Create a new incident in ServiceNow.

Response: 201 Created

curl -X POST \
  https://muleqc.diam.compucom.com/api/standard/incident \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '{
    "transmitId": "unique-txn-id-12345",
    "interfaceType": "ESB Client",
    "senderId": "IntegrationApp",
    "transmitDt": "2024-01-15T10:30:00Z",
    "openedDt": "2024-01-15T10:30:00Z",
    "payload": {
      "shortDescription": "Application downtime",
      "longDescription": "Application not responding to user requests",
      "caller": { "company": "Compucom Systems, Inc." }
    }
  }'

✓ Success Response (201 Created)

{
  "transactionId": "testing-ref-num-mule--24",
  "timeStamp": "2019-09-16T17:00:52.768Z",
  "caseNumber": "INC30000198",
  "status": "inserted",
  "statusCode": "201",
  "message": "WARNING: Caller ID not found or Invalid, Default Used"
}

🔄 PUT /incident

PUT Basic / Bearer

Update an existing incident. The incidentNumber field is required inside payload.

Response: 200 OK

curl -X PUT \
  https://muleqc.diam.compucom.com/api/standard/incident \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '{
    "transmitId": "unique-update-id-67890",
    "interfaceType": "ESB Client",
    "senderId": "IntegrationApp",
    "transmitDt": "2024-01-15T11:00:00Z",
    "openedDt": "2024-01-15T10:30:00Z",
    "payload": {
      "incidentNumber": "INC30025407",
      "state": "2",
      "assignmentGroup": "Level 2 Support",
      "workNotes": "Issue escalated to Level 2",
      "caller": { "company": "Compucom Systems, Inc." }
    }
  }'

🔍 GET /incident

GET v1 v2 Basic / Bearer

Query incidents with 20+ filter parameters (state, date ranges, users, CI, include options, and more).

Response: 200 OK — v2 requires interfaceType; supports GET by {incidentNumber}.

curl -X GET \
  "https://muleqc.diam.compucom.com/api/standard/v2/incident?interfaceType=ESB%20Client&state=New,Active&updatedInLastHours=24&ticketLimit=50&include=contact,attachment" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

📋 Full parameter list: See the API Specification.

📎 POST /incident/attachments

POST Basic / Bearer

Upload attachments to an existing incident. Operation is asynchronous — a 202 response means accepted, not completed.

Response: 202 Accepted | Limits: max 5 attachments per request, ~3 MB per file

curl -X POST \
  https://muleqc.diam.compucom.com/api/standard/incident/attachments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '{
    "incidentNumber": "INC35808432",
    "interfaceType": "ESB Client",
    "callerCompany": "Compucom Systems, Inc.",
    "attachments": [
      { "name": "issue.png", "type": "image/png", "content": "iVBORw0KGgo..." }
    ]
  }'

⬇️ GET /incident/attachments

GET Basic / Bearer

Download an attachment from ServiceNow by sysId and fileName.

Supported types: PDF, PNG, JPEG, CSV, plain text, Office documents, ZIP, and more.

🗂️ POST /incidentTask

POST Basic / Bearer

Create a task associated with an existing incident.

Response: 201 Created — returns generated TASK number.

🩺 GET /stats & GET /healthcheck

GET

Observability endpoints. /stats returns detailed API and dependency health; /healthcheck is a lightweight liveness probe for load balancers.

Response Codes & Error Handling

Code	Meaning	Usage
200	OK	Successful GET or PUT
201	Created	Successful POST
202	Accepted	Async attachment upload accepted
400	Bad Request	Invalid input or missing required fields
404	Not Found	Incident or resource not found
500	Internal Server Error	Retry with exponential backoff

Error Response Example:

{
  "httpStatus": "400",
  "errorCode": "M_01_BAD_REQUEST",
  "timestamp": "2018-06-12T10:47:07+0530",
  "errorMessage": "Bad Request"
}
            

Support & Resources

Interactive API Spec: Try requests and view examples in the API Specification
Support Email: CompucomMuleSoftSupport@compucom.com
MuleSoft Portal: Anypoint Exchange

View API Specification

Standard Incident API v1 / v2

Overview

Key Capabilities

Use Cases

Architecture

Environment URLs

Available Versions

Authentication

Basic Authentication (v1)

OAuth 2.0 (v2)

Request Envelope

API Endpoints

📝 POST /incident

🔄 PUT /incident

🔍 GET /incident

📎 POST /incident/attachments

⬇️ GET /incident/attachments

🗂️ POST /incidentTask

🩺 GET /stats & GET /healthcheck

Response Codes & Error Handling

Support & Resources