--- title: Xmatters slug: connectors/xmatters docTags: createdAt: 2026-06-09T16:29:59.202Z --- XMatters is a digital service availability platform that automates incident management and communication processes. xMatters is a leading incident management and communication platform that helps organizations automate and streamline their incident response processes. The xMatters connector for Swimlane Turbine enables seamless integration with xMatters, allowing users to automate incident retrieval, event management, and device management. By integrating xMatters with Swimlane Turbine, users can enhance their security operations with real-time incident insights, efficient communication, and automated workflows, ultimately reducing response times and improving incident resolution. ### Limitations None to date. ### Supported Versions This xMatters connector uses the Version 1 API. ## Configuration ### Prerequisites Before you can use the xMatters connector for Turbine, you'll need access to the xMatters API. This requires the following: - HTTP Basic authentication using the following parameters: - URL: The endpoint for accessing xMatters services. - Username: Your xMatters account username. - Password: The password associated with your xMatters account. - OAuth2 authorization using the following parameters: - URL: The endpoint for accessing xMatters services. - Username: Your xMatters account username. - Password: The password associated with your xMatters account. - Client ID: The client identifier for OAuth2 authentication. ## Authentication Methods ### HTTP Basic Authentication: - URL: The endpoint URL for the xMatters API. - Username: Your xMatters username with sufficient permissions. - Password: The password associated with your xMatters account. ### OAuth2 Password Credentials with the following parameters: - URL: The endpoint URL for the xMatters API. - Username: Your xMatters username with sufficient permissions. - Password: The password associated with your xMatters account. - Client ID: The client identifier as registered in xMatters for OAuth authentication. ## Capabilities This xMatters connector provides the following capabilities: - Get a Device - Get an Event - Get an Incident by Incident ID - Get an Incident by Incident Identifier - Get Devices - Get Events - Get Incidents - Modify an Incident - Trigger an Event ### Get a Device Returns information about a device in a Device object. xMatters's documentation for this action can be found [here](https://help.xmatters.com/xmapi/#get-a-device). ### Get an Event Returns information about an event. xMatters's documentation for this action can be found [here](https://help.xmatters.com/xmapi/#get-an-event). ### Get an Incident by Incident ID Returns a specific incident in your xMatters instance by UUID. You must have sufficient permissions to view the incident if you did not create it. xMatters's documentation for this action can be found [here](https://help.xmatters.com/xmapi/#get-an-incident). ### Get an Incident by Incident Identifier Returns a specific incident in your xMatters instance by incident identifier. You must have sufficient permissions to view the incident if you did not create it. xMatters's documentation for this action can be found [here](https://help.xmatters.com/xmapi/#get-an-incident). ### Get Devices Returns all devices in a system. Users must have roles that give sufficient permission to view or edit data. If devices are marked as "privileged" by a company supervisor, and you don't have the appropriate permissions, you will see asterisks in of phone numbers, email addresses, and country information. xMatters's documentation for this action can be found [here](https://help.xmatters.com/xmapi/#get-devices). ### Get Events Returns a list of events. xMatters's documentation for this action can be found [here](https://help.xmatters.com/xmapi/#get-events). ### Get Incidents Returns a list of incidents in your xMatters instance. You can use the query parameters to limit your search by the requestID, status, or severity of an incident, or search for a particular keyword in the summary, description, or incident identifier. The incidents returned in the results are based on your permission level. xMatters's documentation for this action can be found [here](https://help.xmatters.com/xmapi/#get-incidents). ### Modify an Incident Updates an existing incident in xMatters. To find the ID of an incident, use Get incidents. xMatters's documentation for this action can be found [here](https://help.xmatters.com/xmapi/#modify-an-incident). ### Trigger an Event To trigger a form from a shell script, create an inbound integration and trigger it by sending a POST request to the inbound integration URL. xMatters's documentation for this action can be found [here](https://help.xmatters.com/xmapi/#trigger-an-event). ## Additional Documentation - [Xmatters Connector Documentation](https://docs.swimlane.com/connectors/xmatters) - [Xmatters Authentication Guide](https://docs.swimlane.com/authentication-guides/xmatters) - [xMatters Authentication (Vendor)](https://help.xmatters.com/xmapi/#authentication) - [xMatters Roles and Permissions (Vendor)](https://help.xmatters.com/xmapi/#roles-and-permissions) - [xMatters REST API Documentation (Vendor)](https://help.xmatters.com/xmapi/#xmatters-rest-api) # Configurations ## xMatters HTTP Basic Authentication Authenticates using username and password. ### Configuration Parameters | **Parameter** | **Description** | **Type** | **Required** | | ------------- | ---------------------------------- | -------- | ------------ | | url | A URL to the target host. | string | Required | | username | Username | string | Required | | password | Password | string | Required | | verify\_ssl | Verify SSL certificate | boolean | Optional | | http\_proxy | A proxy to route requests through. | string | Optional | ## xMatters Oauth 2.0 Password Grant Authenticates using oauth 2.0 client credentials ### Configuration Parameters | **Parameter** | **Description** | **Type** | **Required** | | ---------------- | ------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | | url | A URL to the target host. | string | Required | | oauth2\_username | The name of the user that is used to authenticate requests. | string | Required | | oauth2\_password | The password of the user that is used to authenticate requests. | string | Required | | client\_id | The client ID. You can locate your client ID in the Web user interface by opening the Workflows menu and selecting OAuth. | string | Required | | verify\_ssl | Verify SSL certificate | boolean | Optional | | http\_proxy | A proxy to route requests through. | string | Optional | # Actions ## Get a Device Retrieve details for a specific device in xMatters by providing the required deviceID. ### Endpoint - **URL:** `/api/xm/1/devices/{{deviceID}}` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | | -------------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | `path_parameters.deviceID` | string | Required | The unique identifier or target name of the device to retrieve. The target name of a device is the user name, followed by the | (pipe) character, followed by the device name. | | `parameters.embed` | string | Optional | Use ?embed=timeframes to include the timeframes that each device is scheduled to receive notifications. | | ### Input Example `{"parameters":{"embed":"timeframes"},"path_parameters":{"deviceID":"254c95ee-4abe-47ea-ae7c-ae84fb4bee4f"}}` ### Output | **Parameter** | **Type** | **Description** | | ----------------------------------- | -------- | -------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `id` | string | Unique identifier | | `name` | string | Name of the resource | | `emailAddress` | string | Output field: emailAddress | | `targetName` | string | Name of the resource | | `deviceType` | string | Type of the resource | | `description` | string | Output field: description | | `testStatus` | string | Status value | | `externallyOwned` | boolean | Output field: externallyOwned | | `defaultDevice` | boolean | Output field: defaultDevice | | `priorityThreshold` | string | Output field: priorityThreshold | | `sequence` | number | Output field: sequence | | `delay` | number | Output field: delay | | `timeframes` | object | Output field: timeframes | | `timeframes.count` | number | Count value | | `timeframes.total` | number | Output field: timeframes.total | | `timeframes.data` | array | Response data | | `timeframes.data.name` | string | Response data | | `timeframes.data.startTime` | string | Response data | | `timeframes.data.timezone` | string | Response data | | `timeframes.data.durationInMinutes` | number | Response data | | `timeframes.data.excludeHolidays` | boolean | Response data | | `timeframes.data.days` | array | Response data | | `timeframes.links` | object | Output field: timeframes.links | ### Output Example `{"status_code":200,"response_headers":{"date":"Tue, 15 Oct 2024 09:21:33 GMT","x-trace":"1e325123-5b06-449c-ce5c-e4ab8c69c69d,d3fd9363-433e-4234-8c30-58b4ab817b2a","vary":"Origin,Access-Control-Request-Method,Access-Control-Request-Headers","content-type":"application/json","x-xss-protection":"1; mode=block","cache-control":"no-cache, no-store, max-age=0, must-revalidate","pragma":"no-cache","expires":"0","x-envoy-upstream-service-time":"402","server":"envoy","strict-transport-security":"max-age...` ## Get an Event Retrieve detailed information about a specific event in xMatters using the unique eventId provided. ### Endpoint - **URL:** `/api/xm/1/events/{{eventId}}` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path_parameters.eventId` | string | Required | The unique identifier or ID of the event. We recommend using the UUID, since the event ID number might not always return results. To find the ID or UUID for an event, use GET /events or locate the Event UUID entry on the event’s Properties screen in the web interface. | | `parameters.embed` | string | Optional | A comma-separated list of the properties to embed in the response. | | `parameters.targeted` | boolean | Optional | Used with ?embed=recipients. If set to true, the response returns the directly-targeted recipients. If set to false (or omitted) the response returns the resolved recipients. | | `parameters.at` | string | Optional | A date and time in UTC format that represents the time in the past at which you want to view the state of the data in the system. Using the at query parameter tells the request to search historical data. | ### Input Example `{"parameters":{"embed":"properties,recipients,responseOptions,annotations,messages","targeted":true,"at":"2018-11-02T08:00:00.000Z"},"path_parameters":{"eventId":"ced9fac9-1065-4659-82ab-1c9664a777b2"}}` ### Output | **Parameter** | **Type** | **Description** | | ---------------------------- | -------- | ------------------------------------ | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `id` | string | Unique identifier | | `plan` | object | Output field: plan | | `plan.id` | string | Unique identifier | | `plan.name` | string | Name of the resource | | `form` | object | Output field: form | | `form.id` | string | Unique identifier | | `form.name` | string | Name of the resource | | `eventId` | string | Unique identifier | | `created` | string | Output field: created | | `terminated` | string | Output field: terminated | | `status` | string | Status value | | `priority` | string | Output field: priority | | `incident` | string | Unique identifier | | `expirationInMinutes` | number | Output field: expirationInMinutes | | `overrideDeviceRestrictions` | boolean | Unique identifier | | `bypassPhoneIntro` | boolean | Output field: bypassPhoneIntro | | `requirePhonePassword` | boolean | Output field: requirePhonePassword | | `attachments` | array | Output field: attachments | | `voicemailOptions` | object | Output field: voicemailOptions | | `voicemailOptions.retry` | number | Output field: voicemailOptions.retry | | `voicemailOptions.every` | number | Output field: voicemailOptions.every | | `voicemailOptions.leave` | string | Output field: voicemailOptions.leave | | `floodControl` | boolean | Output field: floodControl | ### Output Example `{"id":"12345678-1234-1234-1234-123456789abc","plan":{"id":"12345678-1234-1234-1234-123456789abc","name":"Example Name"},"form":{"id":"12345678-1234-1234-1234-123456789abc","name":"Example Name"},"eventId":"string","created":"2024-01-01T00:00:00Z","terminated":"string","status":"active","priority":"string","incident":"string","expirationInMinutes":123,"overrideDeviceRestrictions":true,"bypassPhoneIntro":true,"requirePhonePassword":true,"attachments":["string"],"voicemailOptions":{"retry":123,"eve...` ## Get an Incident by Incident ID Retrieve a specific incident by its UUID in your xMatters instance, ensuring access aligns with user permissions. Requires the incidentID as a path parameter. ### Endpoint - **URL:** `/api/xm/1/incidents/{{incidentID}}` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ---------------------------- | -------- | ------------ | ----------------------------------------------------------- | | `path_parameters.incidentID` | string | Required | The unique identifier (or UUID) of an incident in xMatters. | ### Input Example `{"path_parameters":{"incidentID":"ab1d6091-7d58-41e2-af72-49c69b3d9b65"}}` ### Output | **Parameter** | **Type** | **Description** | | --------------------------- | -------- | ------------------------------------ | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `id` | string | Unique identifier | | `incidentIdentifier` | string | Unique identifier | | `summary` | string | Output field: summary | | `description` | string | Output field: description | | `severity` | object | Output field: severity | | `severity.name` | string | Name of the resource | | `status` | object | Status value | | `status.name` | string | Name of the resource | | `initiatedBy` | object | Output field: initiatedBy | | `initiatedBy.id` | string | Unique identifier | | `initiatedBy.targetName` | string | Name of the resource | | `initiatedBy.firstName` | string | Name of the resource | | `initiatedBy.lastName` | string | Name of the resource | | `initiatedBy.licenseType` | string | Type of the resource | | `initiatedBy.recipientType` | string | Type of the resource | | `initiatedBy.links` | object | Output field: initiatedBy.links | | `initiatedBy.links.self` | string | Output field: initiatedBy.links.self | | `commander` | object | Output field: commander | | `commander.id` | string | Unique identifier | | `commander.targetName` | string | Name of the resource | | `commander.firstName` | string | Name of the resource | | `commander.lastName` | string | Name of the resource | | `commander.licenseType` | string | Type of the resource | ### Output Example `{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 10 Jul 2023 20:37:23 GMT"},"reason":"OK","json_body":{"id":"ab1d6091-7d58-41e2-af72-49c69b3d9b65s","incidentIdentifier":"INC-14","summary":"We are experiencing an issue with Google Compute Engine in us-east1-c and us-eas...","description":"Existing VMs may be unavailable or unreachable, and new VM creation may fail beg...","severity":{"name":"Critical"},"status":{"name":"In Progress"},"in...` ## Get an Incident by Incident Identifier Retrieve a specific incident in xMatters using the unique identifier, subject to user permissions. Requires incidentIdentifier as a path parameter. ### Endpoint - **URL:** `/api/xm/1/incidents/{{incidentIdentifier}}` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ------------------------------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- | | `path_parameters.incidentIdentifier` | string | Required | The unique alpha-numeric incident number. The default identifier for incidents created by xMatters is INC. For example INC-145. | ### Input Example `{"path_parameters":{"incidentIdentifier":"INC-145"}}` ### Output | **Parameter** | **Type** | **Description** | | --------------------------- | -------- | ------------------------------------ | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `id` | string | Unique identifier | | `incidentIdentifier` | string | Unique identifier | | `summary` | string | Output field: summary | | `description` | string | Output field: description | | `severity` | object | Output field: severity | | `severity.name` | string | Name of the resource | | `status` | object | Status value | | `status.name` | string | Name of the resource | | `initiatedBy` | object | Output field: initiatedBy | | `initiatedBy.id` | string | Unique identifier | | `initiatedBy.targetName` | string | Name of the resource | | `initiatedBy.firstName` | string | Name of the resource | | `initiatedBy.lastName` | string | Name of the resource | | `initiatedBy.licenseType` | string | Type of the resource | | `initiatedBy.recipientType` | string | Type of the resource | | `initiatedBy.links` | object | Output field: initiatedBy.links | | `initiatedBy.links.self` | string | Output field: initiatedBy.links.self | | `commander` | object | Output field: commander | | `commander.id` | string | Unique identifier | | `commander.targetName` | string | Name of the resource | | `commander.firstName` | string | Name of the resource | | `commander.lastName` | string | Name of the resource | | `commander.licenseType` | string | Type of the resource | ### Output Example `{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 10 Jul 2023 20:37:23 GMT"},"reason":"OK","json_body":{"id":"ab1d6091-7d58-41e2-af72-49c69b3d9b65s","incidentIdentifier":"INC-14","summary":"We are experiencing an issue with Google Compute Engine in us-east1-c and us-eas...","description":"Existing VMs may be unavailable or unreachable, and new VM creation may fail beg...","severity":{"name":"Critical"},"status":{"name":"In Progress"},"in...` ## Get Devices Retrieve all devices within the xMatters system, respecting user permissions for data access. ### Endpoint - **URL:** `/api/xm/1/devices` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ------------------------------ | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `parameters.embed` | string | Optional | Use ?embed=timeframes to include the timeframes that the devices are scheduled to receive notifications. | | `parameters.deviceStatus` | string | Optional | The status of the devices at the time of the request. Valid values are ACTIVE, INACTIVE. | | `parameters.deviceType` | string | Optional | The type of device. Use one of the following values ANDROID\_PUSH, APPLE\_PUSH, EMAIL, FAX, GENERIC, TEXT\_PAGER, TEXT\_PHONE, VOICE, VOICE\_IVR. | | `parameters.deviceNames` | string | Optional | A comma-separated list of device names. Returns a list of all devices with that device name. | | `parameters.phoneNumberFormat` | string | Optional | Return phone numbers in the specified format. If this value is not included, phone numbers are returned in E.164 format. Valid values are E164 - E.164 standard format. COUNTRY\_CODE - Formatted with spaces. | | `parameters.offset` | number | Optional | The number of items to skip before returning results. | | `parameters.limit` | number | Optional | The number of items to return. | ### Input Example `{"parameters":{"embed":"timeframes","deviceStatus":"ACTIVE","deviceType":"EMAIL","deviceNames":"Work Phone, Home Email","phoneNumberFormat":"E164","offset":1,"limit":1}}` ### Output | **Parameter** | **Type** | **Description** | | -------------------------- | -------- | -------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `count` | number | Count value | | `total` | number | Output field: total | | `data` | array | Response data | | `data.id` | string | Response data | | `data.name` | string | Response data | | `data.phoneNumber` | string | Response data | | `data.targetName` | string | Response data | | `data.deviceType` | string | Response data | | `data.description` | string | Response data | | `data.testStatus` | string | Response data | | `data.externallyOwned` | boolean | Response data | | `data.defaultDevice` | boolean | Response data | | `data.priorityThreshold` | string | Response data | | `data.sequence` | number | Response data | | `data.delay` | number | Response data | | `data.owner` | object | Response data | | `data.owner.id` | string | Response data | | `data.owner.targetName` | string | Response data | | `data.owner.firstName` | string | Response data | | `data.owner.lastName` | string | Response data | | `data.owner.recipientType` | string | Response data | | `data.owner.links` | object | Response data | | `data.owner.links.self` | string | Response data | ### Output Example `{"status_code":200,"response_headers":{"date":"Tue, 15 Oct 2024 09:21:33 GMT","x-trace":"1e325123-5b06-449c-ce5c-e4ab8c69c69d,d3fd9363-433e-4234-8c30-58b4ab817b2a","vary":"Origin,Access-Control-Request-Method,Access-Control-Request-Headers","content-type":"application/json","x-xss-protection":"1; mode=block","cache-control":"no-cache, no-store, max-age=0, must-revalidate","pragma":"no-cache","expires":"0","x-envoy-upstream-service-time":"402","server":"envoy","strict-transport-security":"max-age...` ## Get Events Retrieve a comprehensive list of events from xMatters, offering insights into incidents and alerts. ### Endpoint - **URL:** `/api/xm/1/events` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ---------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `parameters.at` | string | Optional | A date and time in UTC format. Using the at query parameter tells the request to search historical data. Can be used with either a timestamp, to and from, or after and before parameters. | | `parameters.embed` | string | Optional | A comma-separated list of the objects to embed in the response. | | `parameters.eventType` | string | Optional | The type of event to return in the results. Valid values are either USER or SYSTEM. | | `parameters.fields` | string | Optional | Defines the fields to search when a search term is specified. The only valid value is NAME, which limits the search results to the content of the event's "name" property, which are email subjects (for user events) or system event type (for system events). | | `parameters.form` | string | Optional | The unique identifier (ID) or name of the form that created the events you want to view. When searching for multiple forms, use a comma-separated list. | | `parameters.from` | string | Optional | A date in UTC format that represents the start of the time range you want to search. All events created at or after the specified time range are displayed in the query results. Use with the to query parameter to return current system data. To return historical data, you must also set the at parameter as described below. | | `parameters.incidentId` | string | Optional | The unique identifier (INC-1234) or UUID (ID) of a single incident in xMatters. The response returns all events associated with the incident. | | `parameters.limit` | number | Optional | The number of items to return. | | `parameters.offset` | number | Optional | The number of items to skip before returning results. | | `parameters.plan` | string | Optional | The unique identifier (ID) or name of the communication plan or built-in integration that created the events you want to view. When searching for multiple plans, use a comma-separated list. | | `parameters.priority` | string | Optional | The priorities of events that you want to return in the search results. Searching by priority is an exact match search, however you can specify multiple values in a comma-separated list priority=HIGH,MEDIUM. Valid values are HIGH, MEDIUM, LOW. | | `parameters.propertyName` | string | Optional | The name of a form property. This value is not case-sensitive. You can have multiple property names in a comma-separated list. | | `parameters.propertyValue` | string | Optional | The value of a form property. This value is not case-sensitive. You can have multiple property values in a comma-separated list. | | `parameters.propertyValueOperator` | string | Optional | The operator used when performing exact searches for unique properties. The propertyValueOperator must be used in conjunction with propertyName and propertyValue. You must have a propertyValueOperator for each propertyName and propertyValue in a comma-separated list. Valid values are CONTAINS, EQUALS. CONTAINS - the search results must contain the value of the propertyValue. EQUALS - the search results must exactly match the value of the propertyValue. | | `parameters.requestId` | string | Optional | The unique identifier returned from a request to trigger an Inbound Integration. Searching by request ID returns the event or events that were initiated when the Inbound Integration was triggered. | | `parameters.resolvedUsers` | string | Optional | The targetName or ID of a user, or users who were notified of an event. Multiple target names or IDs must be comma-separated. Returns a Pagination of events for all specified recipients. | | `parameters.search` | string | Optional | A list of search terms separated by the + sign or a space character. Searches are case-insensitive ("data" finds "data", "Data", as well as "database") and must contain at least two characters. When two or more search terms are present an "AND" search is performed and the result includes events that match all search terms. Use the fields parameter to expand or limit search results. | | `parameters.sortBy` | string | Optional | The criteria for sorting the returned results. Use with the sortOrder query parameter to specify whether the results should be sorted in ascending or descending order. Valid values are EVENT\_ID, START\_TIME, STATUS, SUBMITTER, NAME, PRIORITY. | | `parameters.sortOrder` | string | Optional | Specifies whether events are sorted in ascending or descending order. This parameter must be used in conjunction with the sortBy query parameter. Valid values are ASCENDING, DESCENDING. | | `parameters.status` | string | Optional | The status of events that you want to return in the search results. Valid values are ACTIVE, SUSPENDED, TERMINATED. | | `parameters.submitter` | string | Optional | The unique identifier (ID) or name (targetName) of the submitter. | | `parameters.targetedRecipients` | string | Optional | The targetName or ID of users, groups, devices, or dynamic teams that were targeted as part of the event. Multiple target names or IDs must be comma-separated. Based on your system's settings, targeted users may or may not receive notifications at the time of the event. | | `parameters.to` | string | Optional | A date in UTC format that represents the end of the time range you want to search. All events created at or before the specified time range are displayed in the query results. Use this with the from query parameter. | ### Input Example `{"parameters":{"at":"2018-11-02T08:00:00.000Z","embed":"properties","eventType":"USER","fields":"NAME","form":"c56730a9-1435-4ae2-8c7e-b2539e635ac6","from":"2017-05-01T14:00:00.000Z","incidentId":"INC-1234","limit":1,"offset":0,"plan":"c56730a9-1435-4ae2-8c7e-b2539e635ac6,d0019da1-7cc3-432c-a97d-136515986980","priority":"HIGH","propertyName":"customerAffected","propertyValue":"dogs,fiction","propertyValueOperator":"CONTAINS","requestId":"5588db90-6b87-4662-9a2f-107d3bb233bf","resolvedUsers":"mmcbride,tsmith","search":"Database","sortBy":"SUBMITTER","sortOrder":"ASCENDING","status":"ACTIVE","submitter":"mmcbride","targetedRecipients":"c56730a9-1435-4ae2-8c7e-b2539e635ac6","to":"2017-05-01T19:00:00.000Z"}}` ### Output | **Parameter** | **Type** | **Description** | | ------------------------------ | -------- | -------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `count` | number | Count value | | `total` | number | Output field: total | | `data` | array | Response data | | `data.id` | string | Response data | | `data.name` | string | Response data | | `data.eventType` | string | Response data | | `data.plan` | object | Response data | | `data.plan.id` | string | Response data | | `data.plan.name` | string | Response data | | `data.form` | object | Response data | | `data.form.id` | string | Response data | | `data.form.name` | string | Response data | | `data.floodControl` | boolean | Response data | | `data.submitter` | object | Response data | | `data.submitter.id` | string | Response data | | `data.submitter.targetName` | string | Response data | | `data.submitter.firstName` | string | Response data | | `data.submitter.lastName` | string | Response data | | `data.submitter.recipientType` | string | Response data | | `data.submitter.links` | object | Response data | | `data.submitter.links.self` | string | Response data | | `data.priority` | string | Response data | | `data.incident` | string | Response data | ### Output Example `{"status_code":200,"response_headers":{"date":"Mon, 14 Oct 2024 13:14:03 GMT","x-trace":"ef474a4f-3534-6766-cda0-f17c7110ec80,193e957b-790c-43ea-9402-d41d5e749cec","vary":"Origin,Access-Control-Request-Method,Access-Control-Request-Headers","content-type":"application/json","x-xss-protection":"1; mode=block","cache-control":"no-cache, no-store, max-age=0, must-revalidate","pragma":"no-cache","expires":"0","x-envoy-upstream-service-time":"101","server":"envoy","strict-transport-security":"max-age...` ## Get Incidents Retrieve a filtered list of incidents from xMatters based on requestID, status, severity, or keywords in summary and description. ### Endpoint - **URL:** `/api/xm/1/incidents` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ----------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `parameters.impactedServices` | string | Optional | A comma-separated list of services. You can specify the service either by its target name, or unique identifier. Any spaces or special characters in the service name must be URL-encoded. When impactedServices is included in a request, the response returns incidents that contain any of the services as impacted services. | | `parameters.requestId` | string | Optional | The unique identifier returned from a request to trigger an incident. Searching by requestId returns the incident that was initiated when the trigger fired. | | `parameters.resolver.group` | string | Optional | The target name or unique identifier of a single group in your xMatters instance. Any spaces or special characters in the group name must be URL-encoded. When resolver.group is included in the request, the response returns only incidents where the specified group is a resolver. | | `parameters.search` | string | Optional | A list of search terms separated by the + sign or a space character. The search looks for the term anywhere in the incident summary, description, or incident identifier. Searches are case-insensitive ("alert" finds "alert", "Alert", as well as "alerting") and must contain at least two characters. When two or more search terms are present, the result includes incidents that match either search term. Use the operand and fields query parameters to expand or limit search results. | | `parameters.operand` | string | Optional | The operand to use to limit or expand the search query parameter AND or OR. AND only returns incidents that have all search terms in the summary or description. OR returns incidents that have any of the search terms in the summary or description; this is the default if you don’t specify an operand. The operand is case-sensitive; for example, lowercase ‘and’ returns an error. | | `parameters.fields` | string | Optional | Defines the field to search when a search term is specified. Valid values are SUMMARY - The title of the incident, DESCRIPTION - The description of the incident, INCIDENT\_IDENTIFIER - The unique alpha-numeric incident number. The default identifier for incidents created by xMatters is INC. For example INC-145. | | `parameters.status` | string | Optional | The status of the incident at the time of the request. To search for multiple values, use a comma-separated list. Valid values are OPEN, IN\_PROGRESS, MITIGATED, RESOLVED, REJECTED. | | `parameters.severity` | string | Optional | The severity of the incident at the time of the request. To search for multiple values, use a comma-separated list. Valid values are CRITICAL, HIGH, MEDIUM, LOW, MINIMAL. | ### Input Example `{"parameters":{"impactedServices":"API,47eb2567-38d0-40e5-8fbd-fa1f9e1454fd","requestId":"92eb2567-38d0-40e5-8fbd-fa1f9e1454bd","resolver.group":"Database%20Admins","search":"telecommunication outage","operand":"AND","fields":"SUMMARY","status":"OPEN","severity":"CRITICAL"}}` ### Output | **Parameter** | **Type** | **Description** | | -------------------------------- | -------- | -------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `count` | number | Count value | | `total` | number | Output field: total | | `data` | array | Response data | | `data.id` | string | Response data | | `data.incidentIdentifier` | string | Response data | | `data.summary` | string | Response data | | `data.description` | string | Response data | | `data.severity` | object | Response data | | `data.severity.name` | string | Response data | | `data.status` | object | Response data | | `data.status.name` | string | Response data | | `data.initiatedBy` | object | Response data | | `data.initiatedBy.id` | string | Response data | | `data.initiatedBy.targetName` | string | Response data | | `data.initiatedBy.firstName` | string | Response data | | `data.initiatedBy.lastName` | string | Response data | | `data.initiatedBy.licenseType` | string | Response data | | `data.initiatedBy.recipientType` | string | Response data | | `data.initiatedBy.links` | object | Response data | | `data.initiatedBy.links.self` | string | Response data | | `data.commander` | object | Response data | | `data.commander.id` | string | Response data | | `data.commander.targetName` | string | Response data | ### Output Example `{"status_code":200,"response_headers":{"date":"Mon, 14 Oct 2024 06:22:34 GMT","x-trace":"d7161258-0099-ec38-26e5-6e9d7a520fd6,f286580b-40b8-493c-9739-6828d6d8c5d0","vary":"Origin,Access-Control-Request-Method,Access-Control-Request-Headers","content-type":"application/json","x-xss-protection":"1; mode=block","cache-control":"no-cache, no-store, max-age=0, must-revalidate","pragma":"no-cache","expires":"0","x-envoy-upstream-service-time":"127","server":"envoy","strict-transport-security":"max-age...` ## Modify an Incident Update an existing incident in xMatters using specified details in the JSON body. Retrieve incident IDs using 'Get Incidents'. ### Endpoint - **URL:** `/api/xm/1/incidents` - **Method:** `POST` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | -------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | string | Optional | The unique identifier (ID) of the incident. | | `incidentIdentifier` | string | Optional | The unique alpha-numeric incident number used to look up the incident. | | `summary` | string | Optional | The high-level summary of the incident. | | `description` | string | Optional | The concise description of the incident that provides users with additional information. | | `severity` | string | Optional | The initial severity of the incident. If one is not provided during incident creation, the default severity of Medium is used. The available options are not case-sensitive CRITICAL, HIGH, MEDIUM, LOW, MINIMAL. | | `status` | string | Optional | The initial status of the incident. If one is not provided during incident creation, the default status of OPEN is used. The available options are not case-sensitive OPEN, IN\_PROGRESS, MITIGATED, RESOLVED, REJECTED. | ### Input Example `{"json_body":{"id":"ab1d6091-7d58-41e2-af72-49c69b3d9b65s","incidentIdentifier":"","summary":"","description":"","severity":"Medium","status":"Mitigated"}}` ### Output | **Parameter** | **Type** | **Description** | | --------------------------- | -------- | ------------------------------------ | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `id` | string | Unique identifier | | `incidentIdentifier` | string | Unique identifier | | `summary` | string | Output field: summary | | `description` | string | Output field: description | | `severity` | object | Output field: severity | | `severity.name` | string | Name of the resource | | `status` | object | Status value | | `status.name` | string | Name of the resource | | `initiatedBy` | object | Output field: initiatedBy | | `initiatedBy.id` | string | Unique identifier | | `initiatedBy.targetName` | string | Name of the resource | | `initiatedBy.firstName` | string | Name of the resource | | `initiatedBy.lastName` | string | Name of the resource | | `initiatedBy.licenseType` | string | Type of the resource | | `initiatedBy.recipientType` | string | Type of the resource | | `initiatedBy.links` | object | Output field: initiatedBy.links | | `initiatedBy.links.self` | string | Output field: initiatedBy.links.self | | `commander` | object | Output field: commander | | `commander.id` | string | Unique identifier | | `commander.targetName` | string | Name of the resource | | `commander.firstName` | string | Name of the resource | | `commander.lastName` | string | Name of the resource | | `commander.licenseType` | string | Type of the resource | ### Output Example `{"status_code":200,"response_headers":{"date":"Tue, 15 Oct 2024 10:07:01 GMT","x-trace":"aa83eafb-424c-e3ed-a252-bf11c5887313,3aa12321-9fdc-4fe9-badd-05c6367a82b1","vary":"Origin,Access-Control-Request-Method,Access-Control-Request-Headers","content-type":"application/json","x-xss-protection":"1; mode=block","cache-control":"no-cache, no-store, max-age=0, must-revalidate","pragma":"no-cache","expires":"0","x-envoy-upstream-service-time":"310","server":"envoy","strict-transport-security":"max-age...` ## Trigger an Event Initiate an xMatters event via a POST request to the inbound integration URL, requiring an 'id' as a path parameter. ### Endpoint - **URL:** `/api/integration/1/functions/{{id}}/triggers` - **Method:** `POST` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ----------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------ | | `path_parameters.id` | string | Required | Parameters for the Trigger an Event action | | `recipients` | array | Optional | Parameter for Trigger an Event | | `recipients.id` | string | Optional | Unique identifier | | `recipients.recipientType` | string | Optional | Type of the resource | | `recipients.responseCountThreshold` | number | Optional | Parameter for Trigger an Event | | `otherResponseCountThreshold` | number | Optional | Number of responses required from the "other recipients" group if response counts are used. | | | | | | | `priority` | string | Optional | The priority of the event. Valid values: LOW, MEDIUM, HIGH. | | | | | | | `expirationInMinutes` | number | Optional | Duration of the event in minutes. | | | | | | | `overrideDeviceRestrictions` | boolean | Optional | If true, notifies users on any device at any time, ignoring device timeframes and delays. | | | | | | | `escalationOverride` | boolean | Optional | If true, ignores shift escalation delays and broadcasts to all recipients immediately. | | | | | | | `bypassPhoneIntro` | boolean | Optional | If true, omits the standard voice greeting and plays the message immediately. | | | | | | | `requirePhonePassword` | boolean | Optional | If true, recipients must enter their phone password before a voice notification is played. | | | | | | | `attachments` | array | Optional | List of file paths to attachments uploaded to xMatters temporary storage. | | | | | | | `attachments.path` | string | Optional | Parameter for Trigger an Event | | `voicemailOptions` | object | Optional | Options for retrying calls or leaving a voicemail for voice notifications. | | | | | | | `voicemailOptions.retry` | number | Optional | Parameter for Trigger an Event | | `voicemailOptions.every` | number | Optional | Parameter for Trigger an Event | | `voicemailOptions.leave` | string | Optional | Parameter for Trigger an Event | | `conference` | object | Optional | Conference bridge details. Specify type and bridgeId for hosted or external bridges. | | | | | | | `conference.bridgeId` | string | Optional | Unique identifier | | `conference.type` | string | Optional | Type of the resource | | `responseOptions` | array | Optional | Overrides the form's response options. Use id to select or modify existing options, or omit id to create new ones. | | | | | | | `responseOptions.id` | string | Optional | Unique identifier | | `responseOptions.redirectUrl` | string | Optional | URL endpoint for the request | | `responseOptions.number` | number | Optional | Parameter for Trigger an Event | ### Input Example `{"path_parameters":{"id":"ba601cb1-3513-4320-b48a-05cb501bb5af"}}` ### Output | **Parameter** | **Type** | **Description** | | ---------------------------- | -------- | ------------------------------------ | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `id` | string | Unique identifier | | `plan` | object | Output field: plan | | `plan.id` | string | Unique identifier | | `plan.name` | string | Name of the resource | | `form` | object | Output field: form | | `form.id` | string | Unique identifier | | `form.name` | string | Name of the resource | | `eventId` | string | Unique identifier | | `created` | string | Output field: created | | `terminated` | string | Output field: terminated | | `status` | string | Status value | | `priority` | string | Output field: priority | | `incident` | string | Unique identifier | | `expirationInMinutes` | number | Output field: expirationInMinutes | | `overrideDeviceRestrictions` | boolean | Unique identifier | | `bypassPhoneIntro` | boolean | Output field: bypassPhoneIntro | | `requirePhonePassword` | boolean | Output field: requirePhonePassword | | `attachments` | array | Output field: attachments | | `voicemailOptions` | object | Output field: voicemailOptions | | `voicemailOptions.retry` | number | Output field: voicemailOptions.retry | | `voicemailOptions.every` | number | Output field: voicemailOptions.every | | `voicemailOptions.leave` | string | Output field: voicemailOptions.leave | | `floodControl` | boolean | Output field: floodControl | ### Output Example `{"id":"12345678-1234-1234-1234-123456789abc","plan":{"id":"12345678-1234-1234-1234-123456789abc","name":"Example Name"},"form":{"id":"12345678-1234-1234-1234-123456789abc","name":"Example Name"},"eventId":"string","created":"2024-01-01T00:00:00Z","terminated":"string","status":"active","priority":"string","incident":"string","expirationInMinutes":123,"overrideDeviceRestrictions":true,"bypassPhoneIntro":true,"requirePhonePassword":true,"attachments":["string"],"voicemailOptions":{"retry":123,"eve...` # Response Headers | **Header** | **Description** | **Example** | | ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------- | | Alt-Svc | HTTP response header: Alt-Svc | h3=":443"; ma=2592000,h3-29=":443"; ma=2592000 | | cache-control | Directives for caching mechanisms | no-cache, no-store, max-age=0, must-revalidate | | content-length | The length of the response body in bytes | 140 | | content-type | The media type of the resource | application/json | | date | The date and time at which the message was originated | Mon, 14 Oct 2024 13:14:03 GMT | | expires | The date/time after which the response is considered stale | 0 | | pragma | HTTP response header: pragma | no-cache | | server | Information about the software used by the origin server | envoy | | strict-transport-security | HTTP response header: strict-transport-security | max-age=31536000; includeSubDomains; preload | | Transfer-Encoding | HTTP response header: Transfer-Encoding | chunked | | vary | HTTP response header: vary | Origin,Access-Control-Request-Method,Access-Control-Request-Headers | | Via | HTTP response header: Via | 1.1 google | | x-content-type-options | HTTP response header: x-content-type-options | nosniff | | x-envoy-upstream-service-time | HTTP response header: x-envoy-upstream-service-time | 310 | | x-frame-options | HTTP response header: x-frame-options | SAMEORIGIN | | x-robots-tag | HTTP response header: x-robots-tag | noindex | | x-trace | HTTP response header: x-trace | 1e325123-5b06-449c-ce5c-e4ab8c69c69d,d3fd9363-433e-4234-8c30-58b4ab817b2a | | x-xss-protection | HTTP response header: x-xss-protection | 1; mode=block |