xMatters REST API
The xMatters REST API allows you to interact with xMatters using RESTful requests over the HTTP protocol.
As new methods are added, they replace endpoints from the previous version of our API (which will then be deprecated). Until this transition is complete, you can use endpoints from either API.
For convenience, this document includes links to supported methods from the previous API.
Workflows and communication plans
We’ve renamed “communication plans” to “workflows” and are working to update the xMatters REST API guide to reflect those changes. For the time being, xMatters REST API items such as plans
, forms
, constants
, endpoints
, subscriptions
, and integrations
still contain references to plans and communication plans both in their text and code samples..
Roles and permissions
The xMatters REST API controls access to features using the same roles and permissions as the xMatters web user interface. If the authenticating user has permission to perform an action or access a particular resource in the web user interface they can use the corresponding endpoints and see the same information in this API.
The REST Web Service User role provides the required permissions for accessing some of the most commonly-used xMatters endpoints and provides permission to create and update all users and groups. Assigning this role to the authenticating xMatters REST API user grants permissions required to support most integrations. This role is not designed to provide access to the web user interface.
When the authenticating user does not have permission to access an endpoint, they receive a “403: Forbidden” response.
When the authenticating user has permission to access an endpoint, it returns the data that they have permission view. For example, the GET /people endpoint returns only those users that the authenticating user has permission to view (not necessarily all users in the system).
For more information about the standard roles available with xMatters, see Roles in the online help.
Historical Data
Currently, access to historical data is controlled by a single permission that is enabled or disabled by Client Services for specific user roles. Users with the permission enabled have access to all historical data, regardless of their runtime data permissions. This access is temporary; as we continue to expand the data retention capabilities of xMatters, we’ll also update endpoints to respect runtime data permissions when accessing historical data.
For more information, see Accessing Data.
Versions
The version of xMatters REST API is included as part of the base URL. This API is currently on version 1.
As the xM API is built out and new features are added to xMatters, endpoints may be enhanced to accept more parameters or return more fields in response options. These changes are not considered to be breaking changes and do not result in a version increment of this API.
The following changes are not considered to be breaking changes:
- Returning additional fields in a response.
- Changing the text of an error message.
- Enhancing an endpoint to accept more query or body parameters.
Changes to field names or the structures of the JSON request body or response body are considered breaking changes and are only made when the version of the API is incremented.
Authentication
The xMatters REST API supports HTTP Basic authentication and OAuth authentication.
HTTP Basic authentication authorizes requests by passing the username and password of an xMatters account in the header of each request. For more information about using HTTP Basic authentication, see HTTP Basic Authentication.
OAuth authentication authorizes requests by passing a token in the header of each request. This enables you to avoid storing a user name and password in your application. Tokens can be revoked at any time. For more information about obtaining and working with OAuth access tokens, see OAuth Authentication.
Regardless of which authentication method you use, ensure that you use HTTPS when making RESTful requests so that sensitive information such as passwords and tokens are secured during transmission. Also, ensure that strings are appropriately URL encoded.
HTTP Basic authentication
curl --user username "https://acmeco.xmatters.com/api/xm/1/myendpoint"
import requests
from requests.auth import HTTPBasicAuth
auth = HTTPBasicAuth("username", "password")
response = requests.post(url, auth=auth)
/**
* Authentication in the xMatters Integration Builder is done through the 'xMatters' endpoint.
* This endpoint contains the host name of the system. Configure it with the user ID and
* password of the account that you want to use to access the xMatters REST API.
*
* You can then authenticate your requests by passing the 'xMatters' endpoint to the http.request method.
*/
"endpoint": "xMatters",
xMatters uses HTTP basic authentication to authenticate endpoints in the REST API.
To authenticate with HTTP basic authentication, include an Authorization header with each request. This header contains an encoded version of a username and password. Although this information is encoded, it is not encrypted, so ensure that you use HTTPS protocol to transmit your request. This ensures that the request is encrypted and transmitted securely.
You can authenticate requests with the same web login ID and password that you use to log on natively to the xMatters web user interface, or use an API key and secret to authenticate. To use an API key as your username, it must be prepended with x-api-key-
. The secret is used as the password. For more information on generating API keys in the web user interface, see the online help.
Most tools and programming languages that support REST provide built-in support for HTTP basic authentication and
automatically create the Authorization header for you. If you need to add the Authorization
header to your request manually, you can construct it by using the string ‘Basic’ and appending a base-64 encoding
of your username and password in the format username:password
to the end of the string.
EXAMPLE AUTHENTICATION HEADER
This example uses username
and password as the credentials
, which are then base-64 encoded into dXNlcm5hbWU6cGFzc3dvcmQ=
:
--header Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Base URL
https://acmeco.xmatters.com/api/xm/1/
The base URL identifies your xMatters company and the version of the API you are using. It forms the base of each request to the xMatters REST API.
FORMAT
https://<company>.<deployment>.xmatters.com/api/xm/<version>/
/**
* In the Integration Builder, the host name is stored in the 'xmatters' endpoint.
* The rest of the base URL is passed to the request as part of the path attribute.
*/
"endpoint": "xMatters",
"path": "/api/xm/1/",
Accessing data
To provide you with improved access to your data, we’ve expanded our data retention capabilities. We’re also adding more reporting features, and giving you access to historical on-call, event, and notification history.
When you retrieve information using the xMatters REST API, you can either request runtime data or historical data. While runtime data is available for 30 days, historical data is available to the point in time supported by your pricing plan. When you query runtime data, you see the current state of your system; when you query historical data, you see what the state of your system was at a specific point in time.
As we are implementing extended data retention, some historical endpoints might return incomplete data. For example, the Sites
endpoint does not yet support historical data access. If a query is run for a user that references a Site (For example, GET /people?at={timestamp}?sites={siteID}
), the response will not contain the site data since it doesn’t exist yet.
We are building our endpoints so that once the data is supported it automatically appears in the responses that need it.
Historical data permission
To query historical data, the authenticating REST API user must have the ability.act.HistoricalDataAccess
permission added to a function within their roles. (Contact xMatters Customer Support for help with adding this permission to your user roles.) Also, because permission-level access is not yet available for all endpoints, the user may have access to all available historical data.
Static object queries
For static object queries such as People and Group (by groupID), use the at
parameter to search for information on an object at a specified point in time. For example, GET /people
brings back all users who were in the system at your specified date and time.
Currently, the at
parameter is available on the following endpoints:
- GET /devices/{deviceId}
- GET /events/{eventId}
- GET /groups/{groupId}
- GET /groups/{groupId}/shifts
- GET /groups/{groupId}/shifts/{shiftId}
- GET /people
- GET /people/{personId}
- GET /people/{personId}/devices
- GET /plans
- GET /plans/{planId}
(Bold indicates that the endpoint will respect runtime data permissions and return only the historical data that the authenticating user has permission to view; the ability.act.HistoricalDataAccess
permission is not required.)
Timeframe-based queries
For timeframe-based queries such as Audits and Events, use the at
parameter with to
and from
to provide the state of your system within a timeframe in the past.
- When setting the
from
parameter, the length of time you can set is limited by your pricing plan. Also theat
timestamp cannot be earlier than thefrom
timestamp.
Example: If your pricing plan allows you to access 90 days of historical data, you will receive an error message if you set thefrom
parameter to be greater than 90 days in the past. - When setting the
to
parameter, the time cannot be further in the future than the time of theat
parameter.
Example: If theat
is set for 2018-12-01T13:00:00.000Z, theto
parameter cannot be set for 2018-12-01T14:30:00.000Z.
To allow for unknown factors such as clock drift and network lag, there is a 15-minute synchronization window between data collected by the current system and the contents of the extended data retention facility. This means that when searching timeframe-based historical data, the “to” parameter cannot be within 15 minutes of the current time. The exception to the 15-minute synchronization window is the On-Call endpoint, which has a 24-hr synchronization window. For more information, see Get who’s on call.
Currently, the at
parameter is available on the following endpoints:
- GET /audits
- GET /events
- GET /on-call
As it becomes more widely implemented, we will add the at
parameter to even more endpoints.
HTTP methods
The xMatters REST API supports the following HTTP methods:
GET | Returns a description of a resource. |
POST | Creates or updates a resource. |
DELETE | Deletes a resource. |
Identifying resources
{
"targetName" : "mmcbride",
"id" : "031313cc-42d3-4703-a90e-36cc5f5f6209"
}
This API provides two ways of identifying resources:
- by unique identifier (stored in the
id
field) - by name (stored in the
targetName
field)
The name of a resource is the common name of a resource such as the user ID or group name.
The unique identifier of a resource is a UUID that is automatically assigned to a resource when it is created. The UUID, if available, is usually a better method to identify a resource, since it is unique, less likely to change, and doesn’t run into character encoding issues. (Some methods may allow you to provide a unique identifier when you create a resource. This allows you to synchronize the identifier with an external system.) To locate the unique identifier of a resource in the xMatters user interface, see the xMatters online help.
Request body format
xMatters accepts request data in JSON and form-data formats.
For requests that include data in the request body, add the Content-Type
attribute to the request header and set its value to application/json
.
EXAMPLE
Content-Type: application/json
curl --header "Content-Type: application/json" https://acmeco.xmatters.com/api/xm/1/myendpoint
headers = {"Content-Type": "application/json"}
"headers": {"Content-Type": "application/json"},
To upload files of user data, the supported content type is multipart/form-data
.
EXAMPLE
Content-Type: multipart/form-data
curl --header "Content-Type: multipart/form-data" https://acmeco.xmatters.com/api/xm/1/uploads/users-v1
headers = {"Content-Type": "multipart/form-data"}
Character encoding in requests
To avoid errors in parsing request data, always use UTF-8 character encoding. Requests with other character encoding formats may result in errors and unprocessed requests.
Note: Parameter names are case-sensitive. For example, appending “?requestid=…” to a query does not produce the same result as “?requestId=…”. In general, an unrecognized parameter name (eg, “requestid”) is ignored and has no effect on the number of event records in the response.
Encoding URI parameters and request URLs
xMatters sometimes uses URI parameters to represent system resources, for example, to get a group you can call GET /groups/{groupId}
and replace {groupId}
with name of the group.
If the resource name contains special characters, you must encode it so that it can be included as part of the URI without being mistaken for URI control characters. For example, to search for the group “System+ Administrators”, you need to encode the plus sign and the space: “System%2B%20Administrators”. Depending on the tool you use to make the request, some or all of the URI characters may be automatically encoded for you.
Alternatively, you may be able to access the resource by providing its UUID instead of its name, for example,
you could call GET /groups/{groupId}
and replace {groupId}
with unique identifier of the group.
The exception to this rule is searching for phone numbers as xMatters stores phone numbers with spaces for some device types, and without spaces for others. If you use GET /people
to search for a phone number, enter the number without the country code or spaces. For example: to search for 1 250 555 1234, enter GET /people?search=2505551234
.
Manual URI Encoding
var groupName = ‘IT%20%2F%20Ops’; //group is named ‘IT / Ops'
var request = http.request({
'endpoint': 'xMatters',
'path': '/api/xm/1/groups/' + groupName,
'autoEncodeURI' : false,
'method': 'GET'
});
var request = getGroupsRequest.write();
By default, JavaScript automatically encodes some characters in the URI (for example, spaces and slashes). This helps us standardize the URLs and create default configurations for our built-in and packaged integrations that have the best chance of succeeding wherever they find themselves.
However, it is possible to override this behavior and manually encode special characters. That way, you can make sure you’re sending exactly the request you intend – and not leaving it up to a machine to interpret.
To turn off URI encoding, add 'autoEncodeURI' : false
to the request parameters, and manually encode any special characters in the URI.
Click the JavaScript tab to see an example of how to retrieve a group that includes special characters.
Response format
Responses from the xMatters REST API are in JSON format.
We recommended that you use a JSON parser to process responses. This allows you to easily access the properties of the response and enables your scripts to process any new fields that may be added to the response in the future. (The addition of a new field to the response is not considered a breaking change. For more information on what is considered to be a breaking change, see Versions.)
HTTP response codes
Responses use standard HTTP response codes to describe whether the operation was completed successfully. The following table describes common response codes returned by this API
200 OK | Resource was retrieved or deleted successfully. |
201 Created | Resource was created successfully. |
204 No Content | A resource was not found in response to a DELETE request. |
400 Bad Request | Request is malformed. This often occurs when there is an error in the request such as referring to an object that does not exist. |
401 Unauthorized | User authentication failed. |
403 Forbidden | Authenticated user does not have permission to perform the action. When this occurs you may need to authenticate with a user that has more permissions in xMatters. |
404 Not found | The resource does not exist. This is caused by attempting to access an endpoint that does not exist, for example, this error can occur when there is a typo in the endpoint name. |
406 Not acceptable | The requested media type is not supported. This API supports application/JSON only. |
409 Conflict | The action cannot be performed in the system. This can occur when you attempt to create an object that already exists or perform another unauthorized action such as adding a group to itself. |
415 Unsupported Media Type | The media type in the request body is not supported. This API supports application/JSON only. |
429 Too many requests | The request cannot be processed because the request rate limit has been exceeded. |
Error responses
When the xMatters REST API could not complete an action as requested, it returns an error object in the response. The following table describes the fields that may be present in an error response.
code | integer |
The HTTP response code for the request. | |
reason | string |
An English description of the HTTP response code. | |
message | string |
An English string that describes the error. The text in this string is subject to change at any time. If your application needs more specific information about the error, refer to the subcode field. Example: “Could not find a person with the id mmcbride.” |
|
subcode | string |
A code that represents the root cause of the error. Your application can use this value to determine the root cause of an error and take action accordingly. Example: validation.person.person_not_exists |
Results pagination
Retrieve the first 100 results (0 to 99)
https://acmeco.xmatters.com/api/xm/1/myendpoint?offset=0&limit=100
Retrieve the next 100 results (100 to 199)
https://acmeco.xmatters.com/api/xm/1/myendpoint?offset=100&limit=100
When a request retrieves a large number of results, the results may be split into pages that can be retrieved by using a series of HTTP requests. This prevents the size of any single response from becoming too large.
When results are paginated, the original request returns the first page of results and a URL that links to access the next page of results. The next page of results may contain another link if there are still more results to retrieve. You can keep following these links until you have retrieved all of the results.
Additionally, you can retrieve any subset of the result set by specifying values for the offset
and limit
query parameters.
The maximum value of the limit parameter is 1000. This prevents the returned result set from becoming too large.
For more information about pagination, see the Pagination object and PaginationLinks object.
Special Characters in Responses
The responses from this API may contain names of xMatters objects that contain special characters such as /
and "
.
Because these characters could be interpreted as control characters of the response, they are escaped using the backslash character to represent they are part of a text string.
Some graphical tools may automatically convert escaped characters back to their original format when they display the string. If you want to view the exact characters that are returned in the response, use a programming language or a command-line tool such as cURL to make the request.
The following table shows some examples of how the response returns group names that contain the backslash or double-quote characters.
Name in xMatters | Returned Result |
---|---|
“Corporate Executives” | \“Corporate Executives\” |
Sales \ Marketing | Sales \\ Marketing |
Common query parameters
This section describes query parameters used throughout the API. The maximum number of returned results per request is 1000.
Pagination query parameters
offset and limit
Retrieve the first 100 results (0 to 99)
https://acmeco.xmatters.com/api/xm/1/myendpoint?offset=0&limit=100
Retrieve the next 100 results (100 to 199)
https://acmeco.xmatters.com/api/xm/1/myendpoint?offset=100&limit=100
These query parameters are used to control what appears in a list of paginated results.
offset | integer |
The number of items to skip before returning results. Use with the limit parameter to return a single page of results. |
|
limit | integer |
The number of items to return. Use with the offset parameter to return a single page of results. |
Common fields
This section describes fields that are used throughout the API.
externallyOwned
externallyOwned
{
"externallyOwned" : false
}
A field is externally owned when it is managed by an external system. Externally-owned objects cannot be deleted in the xMatters user interface by most users.
For more information about external ownership, see External ownership and locking.
externallyOwned | Boolean |
True if the object is managed by an external system. False by default. |
externalKey
externalKey
{
"externalKey" : "20160112MCK-FLY"
}
This field identifies a resource in an external system.
externalKey | string |
This field identifies a resource in an external system. |
Common objects
This section describes common objects used throughout the API.
Error object
Error object
{
"code" : 404,
"reason" : "Not Found",
"message" : "Could not find a person with id 0313142d3-4703-a90e-36cc5f5f6209"
}
Describes an error. For a complete list of error response codes, see HTTP response codes.
code | integer |
The HTTP error code. | |
reason | string |
A description of the error code. | |
message | string |
A description of the specific error that occurred. |
Pagination object
Pagination object
EXAMPLE (data truncated)
{
"count": 100,
"total": 235,
"data":
[
{
"id" : "8f2d98ed-eaa9-4b0b-b366-c1db06b27e1f"
...
}
...
],
"links":
{
"self": "/api/xm/1/people?offset=0&limit=100",
"next": "/api/xm/1/people?offset=100&limit=100"
}
}
A page of results. Use the links in the links field to retrieve the rest of the result set. See also Results pagination.
count | integer |
The number of items in this page of results. | |
data | array [object] |
An array of the paginated objects. | |
links | PaginationLinks object |
Links to the current, previous, and next pages of results. | |
total | integer |
The total number of items in the result set. |
PaginationLinks object
PaginationLinks object
{
"links":
{
"self": "/api/xm/1/people?offset=100&limit=100",
"previous": "/api/xm/1/people?offset=0&limit=100",
"next": "/api/xm/1/people?offset=200&limit=100"
}
}
Provides links to the current, previous, and next pages of a paginated result set. See also Results pagination.
next | string |
A link to the next page of results. | |
previous | string |
A link to the previous page of results. | |
self | string |
A link to this page of results. |
Recipient object
See Group object, Device object, Person object, or Dynamic team object.
A recipient is a user, group, device or dynamic team in xMatters that can receive notifications. The recipient object provides a base for Group object, Device object, Person object, and Dynamic team object.
id | string |
A unique identifier that represents the recipient. | |
targetName | string |
The common name of the recipient. | |
recipientType | string |
The type of this object. Values include:
|
|
externalKey | string |
See externalKey. | |
externallyOwned | Boolean |
See externallyOwned. | |
locked | array [string] |
A list of fields that cannot be modified in the xMatters user interface. | |
status | string |
Whether the recipient is active. Inactive recipients do not receive notifications. Use one of the following values:
|
|
links | SelfLink object |
A link that can be used to access the object from within the API. |
Dynamic team object
{
"targetName": "DynamicTeam",
"useEmergencyDevice": false,
"externallyOwned": false,
"recipientType": "DYNAMIC_TEAM",
"id": "88ba7243-a4bc-477e-9b76-c49200a54b35",
"responseCount" : 2,
"responseCountThreshold" : 1
}
A dynamic team is a set of users (based on the Recipient object) that are automatically generated based on a common attribute such as their skills, location, or other attributes. When returned by your system, dynamic teams do not include the status field because dynamic teams are always active. When a dynamic team is a member of a group it is included in the returned list of group members.
id | string |
A unique identifier that represents the dynamic team. | |
targetName | string |
The name of the dynamic team. | |
recipientType | string |
For dynamic teams, this value is “DYNAMIC_TEAM”. | |
responseCount | integer |
When an event is configured to count responses for this dynamic team, this field indicates the number of dynamic team members that have responded positively to the event. If this number is greater than the responseCountThreshold then the response or “fill” counts for this team have been met. | |
responseCountThreshold | integer |
When an event is configured to count responses for this dynamic team, this field indicates the number of dynamic team members required to respond to the event. Once this threshold is met, additional dynamic team members are no longer notified. | |
externallyOwned | Boolean |
See externallyOwned. | |
useEmergencyDevice | Boolean |
True if the dynamic team is configured to contact failsafe devices when no other devices are configured to receive notifications. |
SelfLink object
SelfLink object
{
"self": "/api/xm/1/people/84a6dde7-82ad-4e64-9f4d-3b9001ad60de"
}
A link that can be used to reference this object in the xMatters API.
self | string |
A link that can be used to access this resource with a GET request. |
ReferenceById object
ReferenceById object
{
"id" : "84a6dde7-82ad-4e64-9f4d-3b9001ad60de"
}
The identifier of a resource.
id | string |
The identifier of the resource. |
ReferenceByName object
ReferenceByName object
{
"name" : "Incident Manager"
}
Identifies a resource by name.
name | string |
The name of the resource. |
ReferenceByIdAndSelfLink object
ReferenceByIdAndSelfLink object
{
"id":"f0c572a8-45ec-fe23-289c-df749cf19a5e",
"links":
{
"self":"/api/xm/1/sites/f0c572a8-45ec-fe23-289c-df749cf19a5e"
}
}
The identifier of a resource and a SelfLink object that contains a URL to the resource.
id | string |
The identifier of the resource. | |
links | SelfLink object |
A link that can be used to access the resource with this API. |
RecipientPointer object
RecipientPointer object
{
"id": "438e9245-b32d-445f-916bd3e07932c892",
"recipientType": "GROUP"
}
A reference to a recipient.
id | string |
The unique identifier or target name of the group member. Examples:
|
|
recipientType | string |
optional | The type of the group member. Providing this optional field allows xMatters to process your request more efficiently and improves performance. Use one of the following values:
|
AUDITS
xMatters stores information about actions that occur in the system in a series of audit records. Audit records include information about how events have progressed, how recipients have responded to notifications, and many other system actions.
You can use the /audits
endpoint to access audit records. As we build out this endpoint
we will add the ability to retrieve a wide variety of audit records. For information about the audit records that are
currently supported, see the Audit types table, which contains a list of the available record types
that you can request.
Audit types
The following table shows a list of audit types that can be used with the ?auditType
query parameter to retrieve the corresponding audit records.
QueryParam | Returned Audit | Description |
---|---|---|
EVENT_ANNOTATED | Audit annotation | Comments (annotations) entered for the event. |
EVENT_CREATED | Audit object | Audit information about when the event was created. |
EVENT_SUSPENDED | Audit object | Audit information about when the event was suspended. |
EVENT_RESUMED | Audit object | Audit information about when a suspended event was resumed. |
EVENT_COMPLETED | Audit object | Audit information about when the event was completed. |
EVENT_TERMINATED | Audit object | Audit information about when the event was terminated. |
RESPONSE_RECEIVED | Response | The response a user gave to a notification (also includes any comments made when responding using the mobile app). |
Get event audit information
Get event comments and responses by querying current system data
REQUEST get all the comments on an event and the responses to it, using the EVENT_ANNOTATED and RESPONSE_RECEIVED query parameters
curl --user username "https://acmeco.xmatters.com/api/xm/1/audits?eventId=a7ab8012-0583-4e5b-a5dd-36f67ec016f3&auditType=EVENT_ANNOTATED,RESPONSE_RECEIVED""
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/audits?eventId=a7ab8012-0583-4e5b-a5dd-36f67ec016f3&auditType=EVENT_ANNOTATED,RESPONSE_RECEIVED",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved: " + json.count + " of " + json.total);
for (var i in json.data)
{
if (json.data[i].type == "EVENT_ANNOTATED")
console.log ("Comment added. \t\t User: " + json.data[i].annotation.author.targetName + "\tComment: " + json.data[i].annotation.comment);
else if (json.data[i].type == "RESPONSE_RECEIVED")
console.log ("User: " + json.data[i].response.notification.recipient.targetName + "\t\tResponse: " + json.data[i].response.response);
}
}
# This example shows how to retrieve event comments (annotations)
# by retrieving audit records for comments made when responding to a
# notification and for comments added directly to the tracking report.
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/audits"
url = (
base_URL
+ endpoint_URL
+ "?eventId=a7ab8012-0583-4e5b-a5dd-36f67ec016f3&"
+ "auditType=EVENT_ANNOTATED,RESPONSE_RECEIVED"
)
username = "myuser"
password = "pa55w0rd"
response = requests.get(url, auth=HTTPBasicAuth(username, password))
if response.status_code == 200:
json = response.json()
print(
"Retrieved " + str(json["count"]) + " of " + str(json["total"]) + " comments."
)
for d in json["data"]:
if d["type"] == "EVENT_ANNOTATED":
print(
"Comment added. \t\t User: "
+ d["annotation"]["author"]["targetName"]
+ "\tComment: "
+ d["annotation"]["comment"]
)
elif d["type"] == "RESPONSE_RECEIVED":
print(
"User: "
+ d["response"]["notification"]["recipient"]["targetName"]
+ "\tResponse: "
+ d["response"]["response"]
)
Get responses by querying current system data
REQUEST Get the response option selected by recipients, along with comments added using the mobile app, using the RESPONSE_RECEIVED query parameter
curl --user username "https://acmeco.xmatters.com/api/xm/1/audits?eventId=e3f5b01f-40f3-4273-94bb-fce10d0f2d10&auditType=RESPONSE_RECEIVED"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/audits?eventId=e3f5b01f-40f3-4273-94bb-fce10d0f2d10&auditType=RESPONSE_RECEIVED",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved: " + json.count + " of " + json.total + " responses");
for (var i in json.data)
{
if (json.data[i].type == "RESPONSE_RECEIVED")
console.log ("User: " + json.data[i].response.notification.recipient.targetName + "\t\tResponse: " + json.data[i].response.response);
}
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/audits"
url = (
base_URL
+ endpoint_URL
+ "?eventId=e3f5b01f-40f3-4273-94bb-fce10d0f2d10"
+ "&auditType=RESPONSE_RECEIVED"
)
username = "myuser"
password = "pa55w0rd"
response = requests.get(url, auth=HTTPBasicAuth(username, password))
if response.status_code == 200:
json = response.json()
print(
"Retrieved " + str(json["count"]) + " of " + str(json["total"]) + " responses."
)
for d in json["data"]:
if d["type"] == "RESPONSE_RECEIVED":
print(
"User: "
+ d["response"]["notification"]["recipient"]["targetName"]
+ "\t\t Response: "
+ d["response"]["response"]
)
Get responses by querying historical system data
REQUEST Get the response option selected by recipients.
curl --user username "https://acmeco.xmatters.com/api/xm/1/audits?at=2018-11-02T08:00:00.000Z&from=2018-01-27T08:00:00.000Z&to=2018-06-30T08:00:00.000Z"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/audits?at=2018-11-02T08:00:00.000Z&from=2018-01-27T08:00:00.000Z&to=2018-06-30T08:00:00.000Z",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved: " + json.count + " of " + json.total + " responses");
for (var i in json.data)
{
if (json.data[i].type == "RESPONSE_RECEIVED")
console.log ("User: " + json.data[i].response.notification.recipient.targetName + "\t\tResponse: " + json.data[i].response.response);
}
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/audits"
url = (
base_URL
+ endpoint_URL
+ "?at=2018-11-02T08:00:00.000Z"
+ "&from=2018-01-27T08:00:00.000Z"
+ "&to=2018-06-30T08:00:00.000Z"
)
username = "myUser"
password = "pa55w0rd"
response = requests.get(url, auth=HTTPBasicAuth(username, password))
if response.status_code == 200:
json = response.json()
print(
"Retrieved " + str(json["count"]) + " of " + str(json["total"]) + " responses."
)
for d in json["data"]:
if d["type"] == "RESPONSE_RECEIVED":
print(
"User: "
+ d["response"]["notification"]["recipient"]["targetName"]
+ "\t\t Response: "
+ d["response"]["response"]
)
RESPONSE This response contains a paginated list of EVENT_ANNOTATED and RESPONSE_RECEIVED audit records.
{
"count": 3,
"total": 3,
"data": [
{
"id": "870db826-fc91-47de-ad11-f4c0ec910e93",
"orderId": "336920",
"type": "EVENT_ANNOTATED",
"at": "2018-03-12T20:28:10.868Z",
"annotation": {
"event": {
"id": "6c46e298-6466-4808-a679-e23da39a38aa",
"eventId": "303000",
"links": {
"self": "/api/xm/1/events/6c46e298-6466-4808-a679-e23da39a38aa"
}
},
"author": {
"id": "3bde07b6-22cd-42f7-ba58-40dbb6bbdf16",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/3bde07b6-22cd-42f7-ba58-40dbb6bbdf16"
}
},
"comment": "Ali expects to have a resolution in a half hour."
}
},
{
"id": "8b728c01-e363-4c93-9cd3-d8ccbf990dcd",
"orderId": "336928",
"type": "RESPONSE_RECEIVED",
"at": "2018-03-12T20:28:50.550Z",
"response": {
"comment": "I know what the cause is. Working on the solution.",
"notification": {
"id": "3266b948-39c0-42eb-8a92-74bbede61fd6",
"category": "PERSON",
"recipient": {
"id": "49a99bdd-74b1-496f-9fb5-87f3ca375351",
"targetName": "asamara",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/devices/49a99bdd-74b1-496f-9fb5-87f3ca375351"
}
},
"deliveryStatus": "RESPONDED",
"created": "2018-03-12T20:28:19.831Z",
"event": {
"id": "6c46e298-6466-4808-a679-e23da39a38aa",
"eventId": "303000",
"links": {
"self": "/api/xm/1/events/6c46e298-6466-4808-a679-e23da39a38aa"
}
}
},
"option": {
"id": "920d171b-c7f5-4499-95da-09daaa43c8bd",
"number": 1,
"text": "I got this",
"description": "Assign the issue to me",
"prompt": "I got this",
"action": "STOP_NOTIFYING_USER",
"contribution": "POSITIVE",
"joinConference": false,
"redirectUrl": ""
},
"source": "ANDROID",
"received": "2018-03-12T20:28:19.831Z",
"response": "I got this"
}
},
{
"id": "1c1a9caf-c587-4a3f-8a47-0ab2b41e0ace",
"orderId": "336934",
"type": "EVENT_ANNOTATED",
"at": "2018-03-12T20:29:00.927Z",
"annotation": {
"event": {
"id": "6c46e298-6466-4808-a679-e23da39a38aa",
"eventId": "303000",
"links": {
"self": "/api/xm/1/events/6c46e298-6466-4808-a679-e23da39a38aa"
}
},
"author": {
"id": "bbf8ae6e-96ee-4cf7-83b2-2b88401444b1",
"targetName": "asamara",
"firstName": "Ali",
"lastName": "Samara",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/bbf8ae6e-96ee-4cf7-83b2-2b88401444b1"
}
},
"comment": "I know what the cause is. Working on the solution."
}
}
],
"links": {
"self": "/api/xm/1/audits?eventId=6c46e298-6466-4808-a679-e23da39a38aa&auditType=EVENT_ANNOTATED%2CRESPONSE_RECEIVED&limit=100"
}
}
Returns responses to an event and any comments added, depending on the query parameters entered.
Note that the response object is a separate object from the comment (annotation) on the response. For example, if two responses were selected and three comments added to an event, adding both the EVENT_ANNOTATED and RESPONSE_RECEIVED query parameters returns 5 objects.
DEFINITION
GET /audits?eventId={eventId}&auditType=EVENT_ANNOTATED,RESPONSE_RECEIVED GET /audits?at=2018-11-02T08:00:00.000Z&from=2018-01-27T08:00:00.000Z&to=2018-06-30T08:00:00.000Z GET /audits?eventId={eventId}&sortOrder=ascending
QUERY PARAMETERS
eventId | string |
The unique identifier or event ID of the event that you want to retrieve comments for. Examples:
Note: 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 user interface. |
|
auditType | string |
A comma-separated list of the type of audit events to retrieve.
|
|
sortOrder | string |
Sets whether audits are sorted in ascending or descending order by their creation timestamp. Valid values include:
|
|
at | string |
A date and time in UTC format. Using the at query parameter tells the request to search historical data. Must be used with the to and from , or after and before parameters.
|
RESPONSES
Success | Response code 200 OK and a Pagination of Audit objects of type Response and Audit annotation. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Audit objects
Audit object
Audit object
{
"orderId": "384915",
"type": "EVENT_ANNOTATED",
"at": "2017-03-27T18:45:21.718Z",
"event": {...},
...
}
Audit objects contain basic information about an audit record, and additional
information specific to the type of audit record that is being returned. The at
parameter is supported for these audit types to provide the most current historical data available.
type | string |
The type of audit. Available options are: Available audit types include:
|
|
event | EventReference object |
The event that is associated with the audit. | |
orderId | integer |
deprecated | This field has been deprecated and will be removed from the API in a future release. An identifier for this audit entry. |
at |
string |
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.Example: 2017-05-01T19:00:00.000Z |
Audit annotation object
Audit annotation object
"annotation":
{
"event": {...},
"author":
{
"id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
"targetName": "poravets",
"firstName": "Pauline",
"lastName": "Oravets",
"links":
{
"self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
},
"recipientType": "PERSON"
},
"comment": "This is a comment Pauline Oravets entered directly on the tracking report."
}
Audit annotation objects are Audit objects that represent a comment that was added to an event. To retrieve annotations,
call the /audits
endpoint with the ?auditType=EVENT_ANNOTATED
query parameter.
Annotations can be made by any user who has permission to view the event, regardless of whether they received a notification.
For information about responses to a notification, see Response object.
Annotation objects contain the fields in Audit objects as well as the fields in the following table.
event | EventReference object |
The event that is associated with the comment. | |
author | PersonReference object |
The user who made the comment. Any user who can view the event can make a comment on it, even if they are not a recipient of the event. | |
comment | string |
The comment that was made on the event. |
Response object
Response object
"response":
{
"comment": "This comment was made by mmcbride when she responded on her iPhone.",
"notification":
{
"id": "1d204d66-32d7-41af-aeb1-fb18cbb43b66",
"category": "PERSON",
"recipient":
{
"id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"links":
{
"self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
},
"recipientType": "PERSON"
},
"deliveryStatus": "RESPONDED",
"created": "2017-03-27T18:45:47.111Z",
"deliveryAttempted": "2017-03-27T18:48:19.216Z",
"event":
{
"id": "a7ab8012-0583-4e5b-a5dd-36f67ec016f3",
"eventId": "1562001",
"links":
{
"self": "/api/xm/1/events/a7ab8012-0583-4e5b-a5dd-36f67ec016f3"
}
}
},
"option":
{
"number": 1,
"text": "Accept",
"description": "I can take care of this.",
"prompt": "Assign this task to me.",
"action": "RECORD_RESPONSE",
"contribution": "NONE",
"joinConference": false
},
"source": "IOS",
"received": "2017-03-27T18:45:47.111Z",
"response": "Accept"
}
Event response objects contain information about how a user responded to an event. To retrieve responses, call the /audits
endpoint with the ?auditType=RESPONSE_RECEIVED
query parameter.
For information about comments that were added to the event, see Audit annotation object.
Response objects contain the fields in Audit objects as well as the fields in the following table.
comment | string |
optional | Contains the comment text if a comment was made when responding using the mobile app. |
notification | Notification object |
The notification that the user responded to. | |
option | ResponseOptions object |
A description of the available response choices for the notification. | |
source | string |
optional | The source of the response if it was not made in response to a device notification. This includes responses made from the xMatters user interface or mobile devices. Valid values include:
|
received | string |
The date and time the response occurred. | |
response | string |
The response that the user chose when responding to the notification. |
Notification object
Notification object
"response":
{
"notification":
{
"id": "1d204d66-32d7-41af-aeb1-fb18cbb43b66",
"category": "PERSON",
"recipient":
{
"id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"links":
{
"self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
},
"recipientType": "PERSON"
},
"deliveryStatus": "RESPONDED",
"created": "2017-03-27T18:45:47.111Z",
"deliveryAttempted": "2017-03-27T18:48:19.216Z",
"event":
{
"id": "a7ab8012-0583-4e5b-a5dd-36f67ec016f3",
"eventId": "1562001",
"links":
{
"self": "/api/xm/1/events/a7ab8012-0583-4e5b-a5dd-36f67ec016f3"
}
}
}
}
A notification object describes a notification.
When a response is made from a device, the "category"
field is "DEVICE"
and the "recipient"
field contains information about the device, such as the device type, for example, "EMAIL"
, and the device name, for example, "Work Email"
.
When a response is made in the web user interface, the "category"
field is "PERSON"
and the "recipient"
field does not contain device information.
id | string |
The unique identifier of the notification. | |
category | string |
The type of recipient that received the notification. Valid values include:
|
|
recipient | Recipient object |
The recipient of the notification. | |
deliveryStatus | string |
Whether the response was delivered to the recipient. Valid values include:
|
|
created | string |
The date and time the notification was received. | |
deliveryAttempted | string |
The date and time the delivery was attempted. | |
event | EventReference object |
A link to the event that generated the notification. |
DEVICES
Get a device
Get a device
REQUEST (get a device by id, including timeframes, by querying current system data)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/devices/254c95ee-4abe-47ea-ae7c-ae84fb4bee4f?embed=timeframes"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/devices/254c95ee-4abe-47ea-ae7c-ae84fb4bee4f?embed=timeframes",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved device " + json.id + " owned by " + json.targetName);
}
else if (response.statusCode ==404)
console.log ("The device could not be found.");
import requests
from requests.auth import HTTPBasicAuth
import json
deviceId = "a4d69579-f436-4e85-9d93-703714d85d72"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/devices/" + deviceId
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
print("Received response: " + str(responseCode))
if responseCode == 200:
rjson = response.json()
print(
"Retrieved device with name: "
+ rjson["name"]
+ "\tand device type: "
+ rjson["deviceType"]
)
REQUEST (get a device by id, including timeframes, by querying historical data)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/devices/254c95ee-4abe-47ea-ae7c-ae84fb4bee4f?embed=timeframes?at=2018-11-02T08:00:00.000Z"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/devices/254c95ee-4abe-47ea-ae7c-ae84fb4bee4f?embed=timeframes?at=2018-11-02T08:00:00.000Z",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved device " + json.id + " owned by " + json.targetName + " at" + json.timeFrame);
}
else if (response.statusCode ==404)
console.log ("The device could not be found.");
import requests
from requests.auth import HTTPBasicAuth
import json
deviceId = "a4d69579-f436-4e85-9d93-703714d85d72"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/devices/" + deviceId + "?at=2019-11-02T08:00:00.000Z"
url = base_URL + endpoint_URL + "&embed=timeframes"
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
print("Received response: " + str(responseCode))
if responseCode == 200:
rjson = response.json()
print(
"Retrieved device with device type: "
+ rjson["deviceType"]
+ "\tand owner: "
+ rjson["owner"]["targetName"]
)
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"id":"254c95ee-4abe-47ea-ae7c-ae84fb4bee4f",
"name":"Work Email",
"emailAddress":"m.mcbride@xmatters.com",
"targetName":"mmcbride|Work Email",
"deviceType":"EMAIL",
"description":"m.mcbride@xmatters.com",
"testStatus":"TESTED",
"externallyOwned":false,
"defaultDevice":true,
"priorityThreshold":"LOW",
"sequence":2,
"delay":5,
"timeframes":
{
"count": 1,
"total": 1,
"data":
[
{
"name": "Work Email",
"startTime": "08:00",
"timezone": "US/Pacific",
"durationInMinutes": 540,
"excludeHolidays": true,
"days":
[
"MO",
"TU",
"WE",
"TH",
"FR"
]
}
],
"links":
{
"self": "/api/xm/1/devices/254c95ee-4abe-47ea-ae7c-ae84fb4bee4f/timeframes?offset=0&limit=100"
}
},
"owner":
{
"id":"481086d8-357a-4279-b7d5-d7dce48fcd12",
"targetName": "mmcbride",
"links":
{
"self":"/api/xm/1/people/481086d8-357a-4279-b7d5-d7dce48fcd12"
}
},
"links":
{
"self":"/api/xm/1/devices/254c95ee-4abe-47ea-ae7c-ae84fb4bee4f"
},
"recipientType":"DEVICE",
"status":"ACTIVE"
}
Returns information about a device in a Device object.
To use this method, you must know the unique identifier of the device. You can obtain this identifier from the response of Create a device or Get a person’s devices.
If devices are marked as privileged, and you don’t have the appropriate permissions, you will see asterisks in place of phone numbers, email addresses, and country information.
DEFINITION
GET /devices/{deviceID}
GET /devices/{deviceID}?at=2018-11-02T08:00:00.000Z
URL PARAMETERS
deviceID | string |
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. Examples:
|
QUERY PARAMETERS
embed | string |
Use ?embed=timeframes to include the timeframes that each device is scheduled to receive notifications.Example: /devices/254c95ee-4abe-47ea-ae7c-ae84fb4bee4f?embed=timeframes |
|
at |
string |
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.Example: 2017-05-01T19:00:00.000Z |
RESPONSES
Success | Response code 200 OK and a Device object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get devices
Get devices
REQUEST (get all devices on the system, including timeframes)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/devices?embed=timeframes"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/devices?embed=timeframes",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved devices");
}
else if (response.statusCode ==404)
console.log ("The devices could not be found.");
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/devices?embed=timeframes"
url = base_URL + endpoint_URL
response = requests.get(url, auth=("username", "password"))
if response.status_code == 200:
print("Retrieved devices: " + response.json())
elif response.status_code == 404:
print("Devices list could not be retrieved.")
RESPONSE
{
"count": 100,
"total": 4526,
"data": [
{
"id": "a0cd9227-889c-4332-8e58-b3202e2a0220",
"name": "Mobile Phone",
"phoneNumber": "+25055550260",
"targetName": "1008|Mobile Phone",
"deviceType": "VOICE",
"description": "(205)755 263",
"testStatus": "UNTESTED",
"externallyOwned": false,
"defaultDevice": true,
"priorityThreshold": "LOW",
"sequence": 2,
"delay": 0,
"owner": {
"id": "703d01ad-452f-40eb-bea7-c9379f2bcc72",
"targetName": "1008",
"firstName": "Mary",
"lastName": "MCBRIDE",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/703d01ad-452f-40eb-bea7-c9379f2bcc72"
}
},
"links": {
"self": "/api/xm/1/devices/a0cd9227-889c-4332-8e58-b3202e2a0220"
},
"country": "CA",
"recipientType": "DEVICE",
"status": "ACTIVE",
"provider": {
"id": "acme mobile"
}
},
{
"id": "cbf0e4f1-3b9e-4ab5-91e4-dfb5ed879dd6",
"name": "SMS Phone",
"phoneNumber": "+25055550260",
"country": "CA",
"targetName": "1008|SMS Phone",
"deviceType": "TEXT_PHONE",
"description": "205755263",
"testStatus": "UNTESTED",
"externallyOwned": false,
"defaultDevice": true,
"priorityThreshold": "LOW",
"sequence": 3,
"delay": 0,
"owner": {
"id": "703d01ad-452f-40eb-bea7-c9379f2bcc72",
"targetName": "1008",
"firstName": "Mary",
"lastName": "MCBRIDE",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/703d01ad-452f-40eb-bea7-c9379f2bcc72"
}
},
"links": {
"self": "/api/xm/1/devices/cbf0e4f1-3b9e-4ab5-91e4-dfb5ed879dd6"
},
"recipientType": "DEVICE",
"status": "ACTIVE",
"provider": {
"id": "(x)matters HTTP SMS Gateway"
}
},
{
...a truncated list of devices...
},
],
"links": {
"self": "/api/xm/1/devices?offset=0&limit=100",
"next": "/api/xm/1/devices?offset=100&limit=100"
}
}
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 place of phone numbers, email addresses, and country information.
To return information about a single device, use Get a device.
DEFINITION
GET /devices
GET /devices?deviceStatus=ACTIVE
GET /devices?deviceType=EMAIL
GET /devices?deviceNames=Work Phone, Home Email
GET /devices?embed=timeframes
QUERY PARAMETERS
embed | string |
Use ?embed=timeframes to include the timeframes that the devices are scheduled to receive notifications.Example: /devices?embed=timeframes |
|
deviceStatus | string |
The status of the devices at the time of the request. Valid values include:
|
|
deviceType | string |
The type of device. Use one of the following values:
|
|
deviceNames | string |
A comma-separated list of device names. Returns a list of all devices with that device name. | |
phoneNumberFormat | string |
Return phone numbers in the specified format. If this value is not included, phone numbers are returned in E.164 format. Valid values include:
|
|
offset | integer |
The number of items to skip before returning results. See Pagination query parameters. | |
limit | integer |
The number of items to return. See Pagination query parameters. |
RESPONSES
Success | Response code 200 OK and a Device object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a device
Create a device
REQUEST (create a device)
The following example shows how to create a mobile phone device for Mary McBride that is active on weekdays from 8 AM to 10 PM and weekends from 9 AM to 5 PM. This device is only contacted for medium and high-priority events. After this device is contacted there is a five-minute delay before xMatters contacts the next device.
curl -H "Content-Type: application/json" --user username -X POST -d
'{
"recipientType": "DEVICE",
"defaultDevice" : true,
"deviceType" : "VOICE",
"owner": "ceb08e86-2674-4812-9145-d157b0e24c17",
"phoneNumber": "+16045551212",
"name": "Mobile Phone",
"delay" : 5,
"priorityThreshold": "MEDIUM",
"sequence" : 2,
"testStatus" : "UNTESTED",
"timeframes":[
{
"name":"Weekdays",
"startTime":"08:00",
"durationInMinutes":840,
"days": ["MO", "TU", "WE", "TH", "FR"],
"excludeHolidays": true
},
{
"name":"Weekends",
"startTime":"09:00",
"durationInMinutes":480,
"days": ["SU", "SA"],
"excludeHolidays": false
}
]
}
'
"https://acmeco.xmatters.com/api/xm/1/devices"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/devices",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.recipientType = 'DEVICE';
data.deviceType = 'VOICE';
data.owner ='ceb08e86-2674-4812-9145-d157b0e24c17';
data.name = 'Mobile Phone';
data.phoneNumber = '+16045551212';
data.delay = 5;
data.priorityThreshold = 'MEDIUM';
data.sequence = 2;
data.testStatus = 'UNTESTED';
var timeframe1 = {};
timeframe1.name = 'Weekdays';
timeframe1.startTime = '08:00';
timeframe1.durationInMinutes = 840,
timeframe1.excludeHolidays = true;
timeframe1.days = ['MO' ,'TU', 'WE', 'TH', 'FR'];
var timeframe2 = {};
timeframe2.name = 'Weekends';
timeframe2.startTime = '09:00';
timeframe2.durationInMinutes = 480,
timeframe2.excludeHolidays = true;
timeframe2.days = ['SA' ,'SU'];
var timeframes = [timeframe1, timeframe2];
data.timeframes = timeframes;
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created device: " + json.targetName);
}
# The following code is formatted to work with Python v.3.6 and later.
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/devices"
url = base_URL + endpoint_URL
data = {
"defaultDevice": True,
"deviceType": "VOICE",
"owner": "ceb08e86-2674-4812-9145-d157b0e24c17",
"phoneNumber": "+16045551212",
"name": "Mobile Phone",
"delay": 5,
"priorityThreshold": "MEDIUM",
"sequence": 2,
"testStatus": "UNTESTED",
"timeframes": [
{
"name": "Weekdays",
"startTime": "08:00",
"durationInMinutes": 840,
"days": ["MO", "TU", "WE", "TH", "FR"],
"excludeHolidays": True,
},
{
"name": "Weekends",
"startTime": "09:00",
"durationInMinutes": 480,
"days": ["SU", "SA"],
"excludeHolidays": False,
},
],
}
response = requests.post(url, json=data, auth=("username, password"))
if response.status_code == 201:
rjson = response.json()
print("Created device " + rjson.get("targetName"))
else:
print("There was a problem. Response had status code: " + str(response.status_code))
REQUEST (create a device and set id)
The following request shows how to create the mobile phone from the above example but this time provides a unique identifier in theid
field.
curl -H "Content-Type: application/json" --user username -X POST -d
'{
"id" : "42469eb6-c58c-4c0e-8c4b1838bdf853d2",
"recipientType": "DEVICE",
"defaultDevice" : true,
"deviceType" : "VOICE",
"owner": "ceb08e86-2674-4812-9145-d157b0e24c17",
"phoneNumber": "+16045551212",
"name": "Mobile Phone",
"delay" : 5,
"priorityThreshold": "MEDIUM",
"sequence" : 2,
"testStatus" : "UNTESTED",
"timeframes":[
{
"name":"Weekdays",
"startTime":"08:00",
"durationInMinutes":840,
"days": ["MO", "TU", "WE", "TH", "FR"],
"excludeHolidays": true
},
{
"name":"Weekends",
"startTime":"09:00",
"durationInMinutes":480,
"days": ["SU", "SA"],
"excludeHolidays": false
}
]
}
'
"https://acmeco.xmatters.com/api/xm/1/devices"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/devices",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '42469eb6-c58c-4c0e-8c4b1838bdf853d2';
data.recipientType = 'DEVICE';
data.deviceType = 'VOICE';
data.owner ='ceb08e86-2674-4812-9145-d157b0e24c17';
data.name = 'Mobile Phone';
data.phoneNumber = '+16045551212';
data.delay = 5;
data.priorityThreshold = 'MEDIUM';
data.sequence = 2;
data.testStatus = 'UNTESTED';
var timeframe1 = {};
timeframe1.name = 'Weekdays';
timeframe1.startTime = '08:00';
timeframe1.durationInMinutes = 840,
timeframe1.excludeHolidays = true;
timeframe1.days = ['MO' ,'TU', 'WE', 'TH', 'FR'];
var timeframe2 = {};
timeframe2.name = 'Weekends';
timeframe2.startTime = '09:00';
timeframe2.durationInMinutes = 480,
timeframe2.excludeHolidays = true;
timeframe2.days = ['SA' ,'SU'];
var timeframes = [timeframe1, timeframe2];
data.timeframes = timeframes;
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created device: " + json.targetName);
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/devices"
url = base_URL + endpoint_URL
data = {
"id": "42469eb6-c58c-4c0e-8c4b1838bdf853d2",
"deviceType": "VOICE",
"defaultDevice": True,
"owner": "ceb08e86-2674-4812-9145-d157b0e24c17",
"name": "Mobile Phone",
"phoneNumber": "+16045551212",
"delay": 5,
"priorityThreshold": "MEDIUM",
"sequence": 2,
"testStatus": "UNTESTED",
"timeframes": [
{
"name": "Weekdays",
"startTime": "08:00",
"durationInMinutes": 840,
"excludeHolidays": True,
"days": ["MO", "TU", "WE", "TH", "FR"],
},
{
"name": "Weekends",
"startTime": "09:00",
"durationInMinutes": 480,
"excludeHolidays": True,
"days": ["SU", "SA"],
},
],
}
response = requests.post(url, json=data, auth=("username", "password"))
if response.status_code == 201:
rjson = response.json()
print("Created device " + rjson.get("targetName"))
RESPONSE
{
"id":"42469eb6-c58c-4c0e-8c4b1838bdf853d2",
"name":"Mobile Phone",
"phoneNumber":"+16045551212",
"targetName":"mmcbride",
"deviceType":"VOICE",
"description":"(604)5551212",
"testStatus":"UNTESTED",
"externallyOwned":false,
"defaultDevice":true,
"priorityThreshold":"MEDIUM",
"sequence":2,
"delay":5,
"timeframes":
{
"count":2,
"total":1,
"data":
[{
"name":"Weekdays",
"startTime":"08:00",
"timezone": "US/Pacific",
"durationInMinutes":840,
"excludeHolidays":true,
"days":["TU","MO","TH","FR","WE"]
},
{
"name":"Weekends",
"startTime":"09:00",
"timezone": "US/Pacific",
"durationInMinutes":480,
"excludeHolidays":false,
"days":["SU","SA"]
}],
"links":
{
"self": "/api/xm/1/devices/f5f76ffe-5fa3-4a1e-a43a-059d8046f9e4/timeframes?offset=0&limit=100"
}
},
"owner":
{
"id":"ceb08e86-2674-4812-9145-d157b0e24c17",
"targetName": "mmcbride",
"links":
{
"self":"/api/xm/1/people/ceb08e86-2674-4812-9145-d157b0e24c17"}
},
"links":{
"self":"/api/xm/1/devices/42469eb6-c58c-4c0e-8c4b-1838bdf853d2"
},
"recipientType":"DEVICE",
"status":"ACTIVE",
"privileged": false,
"provider":
{
"id":"(x)matters Voice Gateway"
}
}
Adds a device to xMatters and returns a Device object that represents the newly-created device.
Provide fields in the request body that are common to all devices as well as fields that are specific
to the type of device you want to create, for example, include the emailAddress
field when creating
email devices and include the phoneNumber
field for phone, text (SMS), or public address devices.
Privileged devices redact specific information, such as phone numbers, email addresses, or country location from users without the appropriate permission settings. This is useful to keep certain information, such as a group supervisor’s home phone number from being visible to everyone in the group. Only company supervisors currently have permission to create, edit, and delete priviledged devices. To have this permission setting applied to other roles in your company, contact xMatters Support.
Mobile app devices such as iPhone, iPad, and Android app devices cannot be created using the xMatters REST API. These devices are added to a user’s profile automatically after they install the mobile app on their device and use it to log on to xMatters for the first time. However, once a mobile app device has been added to a user’s profile it may be modified with Modify a device.
DEFINITION
POST /devices
BODY PARAMETERS
Include the parameters in the All Devices table in the body of each request to create a device.
You must also include the parameters specific to the type of device you are creating as defined in the
deviceType
field. Refer to the remaining tables in this section to see the fields to include
for each type of device:
All devices
defaultDevice | Boolean |
optional | True if the device is a failsafe device. |
delay | integer |
optional | The number of minutes to wait for a response before contacting the next device. |
deviceType | string |
The type of device to be created. Valid values include the following:
|
|
id | string |
optional | If provided, xMatters attempts to use this value as a device’s unique identifier. This value must be a valid UUID and cannot be used to identify any other objects within xMatters. If this value is not provided, xMatters generates a UUID and uses it as the device’s unique identifier. Set a value in this optional field when you want a device’s identifier to match a UUID stored in an external system.Note: The UUID can only contain letters a-f, numbers 0-9, and dashes, and cannot match the UUID of any other objects within xMatters. For example: ceb08e86-2674-4812-9145-d157b0e24c17. |
externalKey | string |
optional | See externalKey. |
externallyOwned | Boolean |
optional | See externallyOwned. |
name | string |
The name of the device. Device names are configured uniquely for each company, but typical values include the following:
|
|
owner | string |
The unique identifier of the user who owns this device. This corresponds to a user’s id field. |
|
priorityThreshold | string |
optional | The minimum priority of an event for it to be delivered to this device. Valid values include the following:
|
provider | string |
optional | The name of the provider to use when sending notifications to this device. You do not need to include this value if there is only one provider configured for this type of device. |
recipientType | string |
optional | For devices, the recipient type is “DEVICE”. Providing this optional field allows xMatters to process your request more efficiently and improves performance. |
sequence | integer |
optional | The order in which the device will be contacted, where 1 represents the first device contacted. If the provided sequence number is higher than the number of existing devices, the device is added to the end of the device order. |
status | string |
optional | The status of the devices. Valid values include:
|
testStatus | string |
optional | A code indicating whether the device has been tested or if testing is in progress. Valid values include the following:
|
timeframes | array [DeviceTimeframes object] |
optional | A list of timeframes when xMatters may contact this device. (If the device is a failsafe device, it may be contacted outside these times in certain situations.) |
privileged | Boolean |
When false device information is visible to all users regardless of permission level. When true the email address, phone number, and country are redacted for all users except company administrators and company supervisors. |
EMAIL Devices
emailAddress | string |
The email address of the device. Example: someone@example.com |
VOICE, TEXT_PHONE, and VOICE_IVR devices
phoneNumber | string |
Phone numbers must begin with the + sign and include the country code (E.164 format). Examples:
|
TEXT_PAGER devices
twoWayDevice | Boolean |
True if the device is able to send and receive messages. False if the device is only able to receive messages. | |
pin | string |
The PIN code of the pager. |
FAX devices
country | string |
The country code of the fax device. Valid country codes include the following:
|
|
phoneNumber | string |
The phone number of the fax device, not including the country code. The phone number must be between 5 and 20 characters long. Examples for USA ( country = “US”):
"^d{5, 20}$" |
ANDROID_PUSH and APPLE_PUSH devices
Mobile app devices cannot be added to xMatters with the REST API. These devices are added automatically when a user downloads and installs the mobile app and logs in to xMatters from their device.
RESPONSES
Success | Response code 201 Created and a Device object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a device
Modify a device
REQUEST (modify a device)
curl -H "Content-Type: application/json" --user username -X POST -d
'{
"id" : "42469eb6-c58c-4c0e-8c4b-1838bdf853d2",
"deviceType" : "VOICE",
"phoneNumber": "+13105556672"
}'
"https://acmeco.xmatters.com/api/xm/1/devices"
var parameters = request.parameters;
var deviceID = parameters.deviceID;
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/devices",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '42469eb6-c58c-4c0e-8c4b-1838bdf853d2';
data.deviceType = 'VOICE';
data.phoneNumber = '+13105556672';
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Modified device: " + json.targetName);
}
#The following code is formatted to work with Python v.3.6 and later.
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/devices"
url = base_URL + endpoint_URL
data = {
"id": "42469eb6-c58c-4c0e-8c4b-1838bdf853d2",
"deviceType": "VOICE",
"phoneNumber": "+13105556672",
}
response = requests.post(url, json=data, auth=("username", "password"))
if response.status_code == 200:
print("Success: Modified device " + response.json()["targetName"])
else:
print("Failure: Response code is: " + response.status_code)
RESPONSE
{
"id":"42469eb6-c58c-4c0e-8c4b-1838bdf853d2",
"name":"Mobile Phone",
"phoneNumber":"+13105556672",
"targetName":"mmcbride|Mobile Phone",
"deviceType":"VOICE",
"description":"(310)5556672",
"testStatus":"UNTESTED",
"externallyOwned":false,
"defaultDevice":true,
"priorityThreshold":"MEDIUM",
"sequence":2,
"delay":5,
"owner":
{
"id":"ceb08e86-2674-4812-9145-d157b0e24c17",
"targetName" : "mmcbride",
"links":
{
"self":"/api/xm/1/people/ceb08e86-2674-4812-9145-d157b0e24c17"
}
},
"links":
{
"self":"/api/xm/1/devices/42469eb6-c58c-4c0e-8c4b-1838bdf853d2"
},
"recipientType":"DEVICE",
"status":"ACTIVE",
"provider":
{
"id":"(x)matters Voice Gateway"
}
}
Changes the properties of an existing device.
To modify a device and include the id
and deviceType
properties of the device, and the properties you want to modify. For a description of the available properties for each device, see Device object. You cannot modify the owner or type of a device.
If a call does not include the id
field, it is treated as a request to create a device (see Create a device).
Note: You can use this API to modify properties of mobile app devices but you cannot use this API to create mobile app devices.
Privileged devices redact specific information, such as phone numbers, email addresses, or country location from users without the appropriate permission settings. This is useful to keep certain information, such as a group supervisor’s home phone number from being visible to everyone in the group. Only company supervisors currently have permission to create, edit, and delete priviledged devices. To have this permission setting applied to other roles in your company, contact xMatters Support.
DEFINITION
POST /devices
BODY PARAMETERS
id | string |
The unique identifier (id ) of the device you want to modify. You can get this value from the response of Create a device or Get a person’s devices. |
|
deviceType | string |
The type of the device. Use one of the following values:
|
|
privileged | Boolean |
When false device information is visible to all users regardless of permission level. When true the email address, phone number, and country are redacted for all users except company administrators and company supervisors. |
In addition to the above required fields, include the properties you want to modify. For more information about specifying these properties, see Create a device.
RESPONSES
Success | Response code 200 OK and a Device object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a device
Delete a device
REQUEST (delete a device using the UUID)
curl --user username -X DELETE
"https://acmeco.xmatters.com/api/xm/1/devices/b6a3d8fe-6e8d-415a-81c3-3b970d83b092
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/devices/b6a3d8fe-6e8d-415a-81c3-3b970d83b092",
"method": "DELETE",
});
response = request.write();
console.log (response.statusCode);
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the device: " + json.name + " owned by " + json.targetName);
}
else if (response.statusCode == 204){
console.log("The device could not be found.")
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/devices/b6a3d8fe-6e8d-415a-81c3-3b970d83b092"
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.delete(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Deleted device: " + rjson["id"] + "\twith targetName: " + rjson["targetName"]
)
elif responsecode == 204:
print("The device could not be found.")
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"id": "b6a3d8fe-6e8d-415a-81c3-3b970d83b092",
"name": "Mobile Phone",
"phoneNumber": "+15555551212",
"targetName": "mmcbride",
"deviceType": "VOICE",
"description": "(555)5551212",
"testStatus": "TESTED",
"externallyOwned": false,
"defaultDevice": false,
"priorityThreshold": "LOW",
"sequence": 1,
"delay": 3,
"owner":
{
"id": "481086d8-357a-4279-b7d5-d7dce48fcd12",
"targetName" : "mmcbride",
"links":
{
"self": "/api/xm/1/people/481086d8-357a-4279-b7d5-d7dce48fcd12"
}
},
"links":
{
"self": "/api/xm/1/devices/b6a3d8fe-6e8d-415a-81c3-3b970d83b092"
},
"recipientType": "DEVICE",
"status": "ACTIVE"
}
Deletes a device.
To use this method, you must know the unique identifier (id
) or targetName
of the device. You can obtain the id or targetName from the response of Create a device or Get a person’s devices.
Privileged devices redact specific information, such as phone numbers, email addresses, or country location from users without the appropriate permission settings. This is useful to keep certain information, such as a group supervisor’s home phone number from being visible to everyone in the group. Only company administrators and company supervisors currently have permission to create, edit, and delete priviledged devices. To have this permission setting applied to other roles in your company, contact xMatters Support.
DEFINITION
DELETE /devices/{deviceID}
URL PARAMETERS
{deviceID} | string |
The unique identifier (id ) or targetName of the device to delete. The targetName of a device is the user name, followed by the | (pipe) character, followed by the device name. Examples:
|
RESPONSES
Success | Response code 200 OK and a Device object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Device objects
Device objects represent devices in xMatters.
Device objects include the fields defined in Recipient object in addition to fields specific to device recipients.
The Device object is a base for specific types of devices such as email and voice devices. When you retrieve a device, it contains the fields included in Recipient object, Device object, and the specific type of device. See also:
- Recipient object
- Email device object
- Voice device object
- SMS device object
- Text Pager device object
- Apple Push device object
- Android Push device object
- Fax device object
- Public Address device object
- Generic device object
Device object
Device Object
This example shows an email device object that includes timeframes. Device objects for other device types omit the
emailAddress
field and include fields specific to the type of device.
"id": "77c7ec54-8609-47da-9b6b-80d4b24bead1",
"name": "Home Email",
"emailAddress": "akaur@example.com",
"targetName": "akaur|Home Email",
"deviceType": "EMAIL",
"description": "akaur@example.com",
"testStatus": "UNTESTED",
"externallyOwned": false,
"defaultDevice": true,
"priorityThreshold": "LOW",
"sequence": 1,
"delay": 0,
"owner":
{
"id": "031313cc-42d3-4703-a90e-36cc5f5f6209",
"targetName": "akaur",
"links":
{
"self": "/api/xm/1/people/031313cc-42d3-4703-a90e-36cc5f5f6209"
}
},
"links":
{
"self": "/api/xm/1/devices/77e7ec54-8609-47da-9b6b-80d4b24bead1"
},
"recipientType": "DEVICE",
"status": "ACTIVE",
"provider":
{
"id": "(x)matters Email Gateway"
}
"timeframes":
[
{
"name":"Weekdays",
"startTime":"08:00",
"durationInMinutes":840,
"days": ["MO", "TU", "WE", "TH", "FR"],
"excludeHolidays": true
},
{
"name":"Weekends",
"startTime":"09:00",
"durationInMinutes":480,
"days": ["SU", "SA"],
"excludeHolidays": false
}
]
Contains fields common to recipients and all types of devices.
See also Recipient object.
defaultDevice | Boolean |
True if this device can receive notifications when the person has no active devices. | |
delay | integer |
The number of minutes to wait for a response on this device before contacting the next device. | |
description | string |
A system-generated description of the device. | |
deviceType | string |
The type of device. Use one of the following values:
|
|
name | string |
The name of the device. Example: “Work Email” or “Home Phone” |
|
owner | PersonReference object |
A link to the person who owns the device. | |
priorityThreshold | string |
The minimum priority that an event must have for it to be delivered to this device. Use one of the following values:
|
|
provider | ReferenceById object |
The name of the provider used to send notifications to this device. | |
recipientType | string |
The type of this object. For devices, this value is “DEVICE”. | |
sequence | string |
The order in which the device will be contacted, where 1 represents the first device contacted. | |
targetName | string |
For devices, the target name is the user name, followed by the | (pipe) character, followed by the device name.Example: “mmcbride|Work Phone” |
|
testStatus | string |
Whether the device has been tested. Use one of the following values:
|
|
timeframes | array [DeviceTimeframes object] |
optional | The timeframes the device is active and able to receive notifications. This field is included when the query parameter ?embed=timeframes is included in supported requests. |
Email device object
Email device object
"deviceType": "EMAIL",
"emailAddress": "akaur@example.com",
Email device objects include the fields of Recipient object and Device object, as well as the following fields:
deviceType | string |
For email devices, the device type is “EMAIL”. | |
emailAddress | string |
The email address associated with the device. Your system administrator may restrict the domains that are allowed to be associated with an email device. |
Voice device object
Voice device object
"deviceType": "VOICE",
"phoneNumber": "604 555 1234;ext=83",
Voice device objects include the fields of Recipient object and Device object, as well as the following fields:
deviceType | string |
For phone devices, the device type is “VOICE”. | |
phoneNumber | string |
The phone number associated with this voice device. The phone number uses E.164 international format including country code and extension. Example: +16045551234 |
SMS device object
SMS device object
"deviceType": "TEXT_PHONE",
"phoneNumber": "+12505551212",
SMS devices receive text messages. SMS device objects include the fields of Recipient object and Device object, as well as the following fields:
deviceType | string |
For SMS (text message) devices, the device type is “TEXT_PHONE”. | |
phoneNumber | string |
The phone numbers associated with this device. Phone numbers for SMS devices are stored with no spaces between the numbers. The phone number uses E.164 international format including country code and extension. Example: +12505551212 |
Text pager device object
Text pager device object
"deviceType": "TEXT_PAGER",
"pin": "1234",
"twoWayDevice": true,
Text pager device objects include the fields of Recipient object and Device object, as well as the following fields:
deviceType | string |
For text pager devices, the device type is “TEXT_PAGER”. | |
pin | string |
The PIN code for the pager. | |
twoWayDevice | Boolean |
True if the pager is capable of sending a return message in response to a notification. False if the pager can only receive notifications. |
Apple push device object
Apple push device object
"deviceType": "APPLE_PUSH",
"accountid": "",
"apnToken" : "",
"alertSound" : "",
"soundStatus" : "",
"soundThreshold" : "",
Apple push devices are Apple devices such as iPhones and iPads that use the xMatters mobile app. Push devices are added to xMatters automatically the first time they are used to log on to the system. They can be retrieved but not created with this API.
Apple push device objects include the fields of Recipient object and Device object, as well as the following fields:
deviceType | string |
For Apple push devices, the device type is “APPLE_PUSH”. | |
accountId | string |
The email address associated with the device. | |
apnToken | string |
The APN token associated with the device. | |
alertSound | string |
The alert sound associated with the device. | |
soundStatus | string |
The sound status of the device. | |
soundThreshold | string |
The sound threshold of the device. |
Android push device object
Android push device object
"deviceType": "ANDROID_PUSH",
"accountId": "",
"registrationId": "",
Android push devices are devices such as Android phones that use the xMatters mobile app. Push devices are added to xMatters automatically the first time they are used to log on to the system. They can be retrieved but not created with this API.
Android push device objects include the fields of Recipient object and Device object, as well as the following fields:
deviceType | string |
For Android push devices, the device type is “ANDROID_PUSH”. | |
accountId | string |
The account ID of the device. | |
registrationId | string |
The registration ID associated with the device. |
Fax device object
Fax device object
"deviceType": "FAX",
"phoneNumber": "4035551919",
"country": "US",
Fax device objects include the fields of Recipient object and Device object, as well as the following fields:
deviceType | string |
For fax devices, the device type is “FAX”. | |
phoneNumber | string |
The phone number, not including country code, for the fax. The phone number follows the regular expression pattern ^d{5, 20}$ Example: 4035551919 (when country code is US) Note: This phone number format differs from the phone number format used for voice, public address, and SMS devices. |
|
country | string |
The country code of the fax device. |
Public address device object
Public address device object
"deviceType": "VOICE_IVR",
"phoneNumber": "+177855556782;ext=120",
Public address devices are one-way broadcast devices that play voice notifications but do not include response options. Public address device objects include the fields of Recipient object and Device object, as well as the following fields:
deviceType | string |
For public address devices, the device type is “VOICE_IVR”. | |
phoneNumber | string |
The phone numbers associated with this device. The phone number uses E.164 international format including country code and extension. Example: +15555551212;ext=838 |
Generic device object
Generic device object
"deviceType": "GENERIC",
"pin": "",
Generic device objects include the fields of Recipient object and Device object, as well as the following fields:
deviceType | string |
For generic devices, the device type is “GENERIC”. | |
pin | string |
The PIN of the device. |
Device timeframes object
Device timeframes object
[
{
"name":"Weekdays",
"startTime":"08:00",
"durationInMinutes":840,
"days": ["MO", "TU", "WE", "TH", "FR"],
"excludeHolidays": true
},
{
"name":"Weekends",
"startTime":"09:00",
"durationInMinutes":480,
"days": ["SU", "SA"],
"excludeHolidays": false
}
]
Device timeframes objects list the timeframes that the device is active and able to receive notifications.
days | string |
List of the days of the week this timeframe is active. Valid values include the following:
|
|
durationInMinutes | integer |
The length of the timeframe in minutes. | |
excludeHolidays | Boolean |
True if the timeframe is not active on holidays. | |
name | string |
The name of the timeframe. | |
startTime | string |
The time of day that the timeframe begins. Example: “08:00” |
|
timezone | string |
The time zone of the startTime value.Example: “US/Pacific” |
DEVICE NAMES
Device names are the devices such as email addresses, phone numbers, pagers, and mobile apps that users can add to the Devices tab of their user profile.
Device names are customized for your system but typically include values such as “Work Email”, “Home Email”, “Mobile Phone”, “iPhone”, and so on.
Get device names
GET device names
REQUEST (get all device names)
curl --user username "https://acmeco.xmatters.com/api/xm/1/device-names"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/device-names",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
for (var i in json.data ) {
console.log(json.data[i].name + ": " + json.data[i].description);
}
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/device-names"
url = base_URL + endpoint_URL
response = requests.get(url, auth=HTTPBasicAuth("username", "password"))
if response.status_code == 200:
json = response.json()
print (
"Retrieved "
+ str(json["count"])
+ " of "
+ str(json["total"])
+ " device names."
)
for d in json["data"]:
print (d["name"] + ": " + d["description"])
REQUEST (get email device names)
curl --user username "https://acmeco.xmatters.com/api/xm/1/device-names?deviceType=EMAIL"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/device-names?deviceType=EMAIL",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
for (var i in json.data ) {
console.log(json.data[i].name + ": " + json.data[i].description);
}
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/device-names?deviceType=EMAIL"
url = base_URL + endpoint_URL
response = requests.get(url, auth=HTTPBasicAuth("username", "password"))
if response.status_code == 200:
json = response.json()
print (
"Retrieved "
+ str(json["count"])
+ " of "
+ str(json["total"])
+ " device names."
)
for d in json["data"]:
print (d["name"] + ": " + d["description"])
RESPONSE
{
"count":9,
"total":9,
"data":[
{
"id": "a6edd52d-e192-43cf-86ad-7c3ac629f1b2",
"deviceType":"EMAIL",
"name":"Home Email",
"description":"Home Email Address",
"privileged": false
},
{
"id": "b9edd41d-e192-43cf-32bf-7c3ac896f1h6",
"deviceType":"EMAIL",
"name":"Work Email",
"description":"Work Email Address",
"privileged": false,
"domains":
[
"xmatters.com",
"example.com"
]
},
{
"id": "2a830f29-5b35-4259-9ffb-ae41cf1a9300",
"deviceType":"FAX",
"name":"Fax",
"description":"Fax",
"privileged": false
},
{
"id": "a7ea51bf-7400-42ee-bb86-5d9c89d03347",
"deviceType":"TEXT_PAGER",
"name":"Pager",
"description":"Text Pager",
"privileged": false
},
{
"id": "fe6b1c8e-772e-4dee-906a-ad39e0f57614",
"deviceType":"TEXT_PHONE",
"name":"SMS Phone",
"description":"Phone with SMS",
"privileged": false
},
{
"id": "d8d68eb5-3014-49f1-adc0-209f3f98bc73",
"deviceType":"VOICE",
"name":"Home Phone",
"description":"Phone Number at Home",
"privileged": true
},
{
"id": "d8d68eb5-49f1-adc0-3014-209f3f31bc95",
"deviceType":"VOICE",
"name":"Mobile Phone",
"description":"Cell Phone",
"privileged": false
},
{
"id": "a6edd52d-e192-43cf-86ad-7c3ac629f1b2",
"deviceType":"VOICE",
"name":"Work Phone",
"description":"Phone Number at Work",
"privileged": true
}
],
"links": {
"self": "/api/xm/1/device-names?limit=100&offset=0"
}
}
Returns a paginated list of the DeviceName objects that represent the devices users can add to their profile. Any device where the “privileged” field is set to true
displays redacted information for users without appropriate permission settings. Redacted items include email address, phone number, and country for the following device types: EMAIL, VOICE, VOICE_IVR, FAX, and TEXT_PHONE.
You can request devices of a specific type by including the ?deviceTypes
query parameter, for example, use /device-names?deviceTypes=EMAIL
to retrieve a list of email devices. You can also use the at
parameter to see a list of devices at a specific point in time, however the search parameters and privileged device information are not supported for historical data searches at this time.
DEFINITION
GET /device-names GET /device-names?search=Phone Pager GET /device-names?deviceTypes=FAX,ANDROID_PUSH,VOICE GET /device-names?sortBy=NAME&sortOrder=ASCENDING GET /device-names?at={timestamp}
QUERY PARAMETERS
deviceTypes | string |
Returns all devices of the specified type. You can request multiple device types with a comma-separated list. Available values are:
|
|
search | string |
A space-delimited list of terms that searches both the name and description fields. The search is case-insensitive, and returns both full and partial matches for all specified terms. | |
sortBy | string |
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 include:
|
|
sortOrder | string |
Specifies whether groups are sorted in ascending or descending order. This parameter must be used in conjunction with the sortBy query parameter. Valid values include:
|
|
offset | integer |
The number of items to skip before returning results. See Pagination query parameters. | |
limit | integer |
The number of items to return. See Pagination query parameters. | |
at |
string |
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.Example: 2017-05-01T19:00:00.000Z |
RESPONSES
Success | Response code 200 OK and a Pagination of DeviceName object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a device name
Create a device name
REQUEST (create a device name)
curl -H "Content-Type: application/json" --user username -X POST -d
'{
"deviceType" : "VOICE",
"name": "Mobile Phone",
"description":"Cell Phone",
"privileged": false
}
'
"https://acmeco.xmatters.com/api/xm/1/deviceName"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/device-names",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.deviceType = 'VOICE';
data.name = 'Mobile Phone';
data.description = 'Cell Phone';
data.privileged = false
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created device name: " + json.targetName);
}
# The following code is formatted to work with Python v.3.6 and later.
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/device-names"
url = base_URL + endpoint_URL
data = {
"deviceType": "VOICE",
"name": "Mobile Phone",
"description": "Cell Phone",
"privileged": false
],
}
response = requests.post(url, json=data, auth=("username, password"))
if response.status_code == 201:
rjson = response.json()
print("Created device name " + rjson.get("targetName"))
else:
print("There was a problem. Response had status code: " + str(response.status_code))
RESPONSE
{
"id":"42469eb6-c58c-4c0e-8c4b1838bdf853d2",
"deviceType":"VOICE",
"name":"Mobile Phone",
"description":"Cell Phone",
"privileged": false,
"links":
{
"self": "/api/xm/1/deviceName/42469eb6-c58c-4c0e-8c4b1838bdf853d2"
}
},
Adds a device name to xMatters and returns a Device object that represents the newly-created device. If the submitted device type does not exist in the user’s system at the time of the request, it is added.
If a device name is marked as a privileged device, specific information, such as phone numbers, email addresses, or country location is withheld from users without the appropriate permission settings. This is useful to keep certain information, such as a group supervisor’s home phone number from being visible to everyone in the group. Only company administrators and company supervisors have permission to create, edit, and delete priviledged devices.
DEFINITION
POST /device-names
BODY PARAMETERS
deviceType | string |
The type of device to be created. Valid values include the following:
|
|
name | string |
required | The name of the device. Device names are configured uniquely for each company, but typical values include the following:
|
description | string |
The description of the device, up to 1000 characters. | |
privileged | Boolean |
When false device information is visible to all users regardless of permission level. When true the email address, phone number, and country are redacted for all users except company administrators and company supervisors. |
RESPONSES
Success | Response code 201 Created and a Device name object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a device name
Modify a device name
REQUEST (modify a device name)
curl -H "Content-Type: application/json" --user username -X POST -d
'{
"id" : "42469eb6-c58c-4c0e-8c4b-1838bdf853d2",
"deviceType" : "VOICE",
"phoneNumber": "+13105556672"
}'
"https://acmeco.xmatters.com/api/xm/1/device-names"
var parameters = request.parameters;
var deviceID = parameters.deviceID;
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/device-names",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '42469eb6-c58c-4c0e-8c4b-1838bdf853d2';
data.deviceType = 'VOICE';
data.phoneNumber = '+13105556672';
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Modified device name: " + json.targetName);
}
#The following code is formatted to work with Python v.3.6 and later.
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/device-names"
url = base_URL + endpoint_URL
data = {
"id": "42469eb6-c58c-4c0e-8c4b-1838bdf853d2",
"deviceType": "VOICE",
"phoneNumber": "+13105556672",
}
response = requests.post(url, json=data, auth=("username", "password"))
if response.status_code == 200:
print("Success: Modified device " + response.json()["targetName"])
else:
print("Failure: Response code is: " + response.status_code)
RESPONSE
{
"id":"42469eb6-c58c-4c0e-8c4b-1838bdf853d2",
"name":"Mobile Phone",
"deviceType":"VOICE",
"description":"(310)5556672",
"privileged":"false",
"links":
{
"self":"/api/xm/1/device-names/42469eb6-c58c-4c0e-8c4b-1838bdf853d2"
},
}
Changes the properties of an existing device name.
To modify a device name include the id
and deviceType
properties of the device name, and the properties you want to modify.
If a call does not include the id
field, it is treated as a request to create a device name (see Create a device name). Privileged devices redact specific information, such as phone numbers, email addresses, or country location from users without the appropriate permission settings. This is useful to keep certain information, such as a group supervisor’s home phone number from being visible to everyone in the group. Only company supervisors currently have permission to create, edit, and delete priviledged devices. To have this permission setting applied to other roles in your company, contact xMatters Support.
DEFINITION
POST /device-names
BODY PARAMETERS
id | string |
The unique identifier (id ) of the device you want to modify. You can get this value from the response of Create a device name. |
|
deviceType | string |
The type of the device. Use one of the following values:
|
In addition to the above required fields, include the properties you want to modify. For more information about specifying these properties, see Create a device name.
RESPONSES
Success | Response code 200 OK and a Device name object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a device name
Delete a device name
REQUEST (delete a device name using the UUID)
curl --user username -X DELETE
"https://acmeco.xmatters.com/api/xm/1/device-namess/b6a3d8fe-6e8d-415a-81c3-3b970d83b092
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/device-names/b6a3d8fe-6e8d-415a-81c3-3b970d83b092",
"method": "DELETE",
});
response = request.write();
console.log (response.statusCode);
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the device name: " + json.name + " owned by " + json.targetName);
}
else if (response.statusCode == 204){
console.log("The device name could not be found.")
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/device-names/b6a3d8fe-6e8d-415a-81c3-3b970d83b092"
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.delete(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Deleted device name: " + rjson["id"] + "\twith targetName: " + rjson["targetName"]
)
elif responsecode == 204:
print("The device name could not be found.")
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"id":"b6a3d8fe-6e8d-415a-81c3-3b970d83b092",
"deviceType":"VOICE",
"name":"Mobile Phone",
"description":"Cell Phone",
"privileged": false,
"links":
{
"self": "/api/xm/1/deviceName/b6a3d8fe-6e8d-415a-81c3-3b970d83b092"
}
},
Deletes a device name.
To use this method, you must know the unique identifier (id
) of the device name. You can obtain the id from the response of Get a device name. All devices associated with the device name are deleted when the device name is deletd.
If a device name is marked as a privileged device, only company supervisors or company administrators can delete it.
DEFINITION
DELETE /devices/{deviceID}
URL PARAMETERS
deviceID | string |
The unique identifier (id ) of the device name to delete. |
RESPONSES
Success | Response code 200 OK and a Device name object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
DeviceName objects
DeviceName object
DeviceName object
{
"deviceType":"EMAIL",
"name":"Work Email",
"description":"Work Email Address",
"domains":
[
"example.com",
"xmatters.com"
]
}
The name, description, and type of device.
deviceType | string |
The type of the device; e.g., “EMAIL”, “VOICE”, etc. To view which device types are configured for your system, see Get device types. | |
name | string |
The name of the device. These values are customized for your system but typical examples are listed below:
|
|
description | string |
A description of the device. | |
domains | array [string] |
optional | Used only with email devices. Lists the domains allowed as part of the email address for this device name. |
targetDeviceName selector object
targetDeviceName selector object
"targetDeviceNames": [
{
"name": "iPhone",
"selected": true,
"visible": false
},
{
"name": "Android Phone",
"selected": true,
"visible": false
},
{
"name": "Work Email",
"selected": true,
"visible": true
}
]
The name of a device and its selected and visible states, used on forms and subscription forms.
name | string |
The name of the device. These values are customized for your system but typical examples are “Work Email”, “Home Email”, or “Mobile Phone”. To view the device names defined in your instance, see Get device names. | |
selected | string |
Whether the device is selected when a user creates a message or subscription based on the form. | |
visible | string |
Whether the device is visible when a user creates a message or subscription based on the form. |
DEVICE TYPES
Returns a list of device types that are configured for the system.
Get device types
GET device types
REQUEST (get device types)
curl --user username "https://acmeco.xmatters.com/api/xm/1/device-types"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/device-types",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
for (var i in json.data ) {
console.log(json.data[i]);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/device-types"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
print("Sending request to url: " + url)
response = requests.get(url, auth=auth)
if response.status_code == 200:
rjson = response.json()
print(
"Retrieved "
+ str(rjson["count"])
+ " of "
+ str(rjson["total"])
+ " endpoints."
)
for d in rjson["data"]:
print("Found device type: " + d)
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
print(
"The request did not succeed. Response code is: "
+ str(response.status_code)
+ "\n"
+ str(response)
)
RESPONSE
{
"count":4,
"total":4,
"data":
[
"EMAIL",
"TEXT_PAGER",
"TEXT_PHONE",
"VOICE"
]
}
Returns a DeviceTypes object that lists the types of devices that can be configured in xMatters, such as “EMAIL”, “VOICE”, “SMS”, and so on.
DEFINITION
GET /device-types
RESPONSES
Success | Response code 200 OK and a DeviceTypes object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
DeviceTypes object
A list of the types of devices that are configured for the system.
count | integer |
The number of device types available in the system. For device types, this value is the same as the total value. | |
total | integer |
The number of device types available in the system. | |
data | array [string] |
A list of strings that represent the device type names. These may include the following values:
|
DYNAMIC TEAMS
Dynamic teams are created to group together users based on who matches the selected criteria at the time of an event. Use this endpoint to retrieve all dynamic teams in your system or a specific dynamic team by its unique id.
For more information, see Create dynamic teams in the online help.
Get dynamic teams
GET dynamic teams
REQUEST (get all dynamic teams)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/dynamic-teams",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " dynamic teams." );
for (var i in json.data ) {
console.log(json.data[i].targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/dynamic-teams"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
response_code = response.status_code
if response_code == 200:
rjson = response.json()
for d in rjson.get("data"):
print("Found dynamic team with TargetName: " + d["targetName"] + " and id: " + d["id"])
else:
rjson = response.json()
print(
"The request did not succeed. Response code is: "
+ str(response_code)
)
REQUEST (get dynamic teams Anita Sharma supervises)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams?supervisors=asharma"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/dynamic-teams?supervisors=asharma",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " dynamic teams." );
for (var i in json.data ) {
console.log(json.data[i].targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/dynamic-teams?supervisors=asharma"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
response_code = response.status_code
if response_code == 200:
rjson = response.json()
for d in rjson.get("data"):
print("Found dynamic team with TargetName: " + d["targetName"] + " and id: " + d["id"])
else:
rjson = response.json()
print(
"The request did not succeed. Response code is: "
+ str(response_code)
)
REQUEST (get dynamic teams that have the word “operations” in their description)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams?search=operations&fields=DESCRIPTION"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/dynamic-teams?search=operations&fields=DESCRIPTION",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " dynamic teams." );
for (var i in json.data ) {
console.log(json.data[i].targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/dynamic-teams?search=operations&fields=DESCRIPTION"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
response_code = response.status_code
if response_code == 200:
rjson = response.json()
for d in rjson.get("data"):
print("Found dynamic team with TargetName: " + d["targetName"] + " and id: " + d["id"])
else:
rjson = response.json()
print(
"The request did not succeed. Response code is: "
+ str(response_code)
)
RESPONSE
{"count": 7,
"total": 7,
"data": [
{
"id": "1c85cabc-8927-40fe-945a-34733aec7ba4",
"targetName": "ThirdFloorResponseTeam",
"recipientType": "DYNAMIC_TEAM",
"externallyOwned": false,
"description": "Third floor emergency response team",
"criteria": {
"operand": "OR",
"criterion": {
"count": 1,
"total": 1,
"data": [
{
"criterionType": "BASIC_FIELD",
"field": "USER_ID",
"operand": "EQUALS",
"value": "First_Aid_Attendant"
}
]
}
},
"links": {
"self": "/api/xm/1/dynamic-teams/1c85cabc-8927-40fe-945a-34733aec7ba4"
}
},
{ ...a truncated list of dynamic teams...},
],
"links": {
"self": "/api/xm/1/dynamic-teams"
}
}
Returns a list of dynamic teams in your system.
For more information, see Create dynamic teams in the online help.
DEFINITION
GET /dynamic-teams GET /dynamic-teams?embed=supervisors,observers GET /dynamic-teams?search=term1&fields=DESCRIPTION GET /dynamic-teams?supervisors=c21b7cc9-c52a-4878-8d26-82b26469fdc7,asharma
QUERY PARAMETERS
embed | string |
A comma-separated list of objects to embed in the response. Supported values are: observers and supervisors . |
|
search | string |
A list of search terms separated by the + sign or a space character. Searches are case-insensitive and must contain a total of at least two characters. Searches cannot contain whitespace characters within an individual search term. The search looks for the term anywhere in the name or description. When two or more search terms are present, the result includes dynamic teams that match either search term. You can narrow the search to results that include both terms by using the operand query parameter. You can also search only the name or description by setting the fields query parameter. |
|
operand | string |
The operand to use to limit or expand the search query parameter: AND or OR . AND only returns dynamic teams that have all search terms in the name or description. OR returns dynamic teams that have any of the search terms in the name 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. |
|
fields | string |
Defines the field to search when a search term is specified. Valid values include:
|
|
supervisors | string |
A comma-separated list of supervisors whose dynamic teams you want to retrieve. You can specify the supervisors using targetName (case-insensitive) or id (or both if search for multiple supervisors). When two or more supervisors are sent in the request, the response includes dynamic teams for which either user is a supervisor.Example: /dynamic-teams?supervisors=asharma,6f347364-8dc7-4871-819b-e3e7dbfda2de |
|
sortBy | string |
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 value is: NAME. |
|
sortOrder | string |
Specifies whether dynamic teams are sorted in ascending or descending order. This parameter must be used in conjunction with the sortBy query parameter. Valid values include:
|
RESPONSES
Success | Response code 200 OK and a pagination of Dynamic Teams object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a dynamic team
GET a dynamic team
curl --user username
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved : " + json.targetName + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04"
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
rjson = response.json()
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"id": "1c85cabc-8927-40fe-945a-34733aec7ba4",
"targetName": "MIMTeam",
"recipientType": "DYNAMIC_TEAM",
"externallyOwned": false,
"description": "Major Incident Response team - MWF",
"criteria": {
"operand": "OR",
"criterion": {
"count": 1,
"total": 1,
"data": [
{
"criterionType": "BASIC_FIELD",
"field": "USER_ID",
"operand": "EQUALS",
"value": "MIMTeam1"
}
]
}
},
"links": {
"self": "/api/xm/1/dynamic-teams/1c85cabc-8927-40fe-945a-34733aec7ba4"
}
}
Returns a dynamic team using its unique id
. To find the id
of a dynamic team, use GET Dynamic Teams.
For more information, see Create dynamic teams in the online help.
DEFINITION
GET /dynamic-teams/{dynamicTeamId} GET /dynamic-teams/{dynamicTeamId}?embed=supervisors,observers
URL PARAMETERS
dynamicTeamId | string |
The unique id of the dynamic team. |
QUERY PARAMETERS
embed | string |
A comma-separated list of objects to embed in the response. Supported values are: observers and supervisors . |
RESPONSES
Success | Response code 200 OK and a Dynamic Teams object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get dynamic team members
GET dynamic team members
curl --user username
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04/members"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04/members",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved : " + json.targetName + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
limit = "2"
endpoint_URL = "/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04/members"
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
for d in rjson.get("data"):
print(
"Found Team Member with TargetName: "
+ d["targetName"]
+ " at site: "
+ d["site"]["name"]
)
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
rjson = response.json()
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"count": 14,
"total": 14,
"data": [
{
"id": "362f15ba-199e-4808-90ac-d79c1c36c9be",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/362f15ba-199e-4808-90ac-d79c1c36c9be"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "mmcbride",
"site": {
"id": "87165184-f025-46ec-bc8e-11314b4ddeb5",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/87165184-f025-46ec-bc8e-11314b4ddeb5"
}
},
"status": "ACTIVE"
}
{
... truncated list of dynamic team members ...
}
],
"links": {
"self": "/api/xm/1/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04/members?offset=0&limit=100"
}
}
Returns the members of a dynamic team using the team’s unique id
or targetName
. To find the id
of a dynamic team, use GET Dynamic Teams.
DEFINITION
GET /dynamic-teams/{dynamicTeamId}/members
URL PARAMETERS
dynamicTeamId | string |
The unique id or targetName of the dynamic team. |
RESPONSES
Success | Response code 200 OK and a paginated list of Person objects in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a dynamic team
Create a dynamic team
REQUEST - Create a dynamic team
curl --user username --header "Content-Type: application/json" --request POST -d '{
"targetName": "MIMTeam1",
"criteria":
{
"operand": "OR",
"criterion": [{
"criterionType": "BASIC_FIELD",
"field": "USER_ID",
"operand": "EQUALS",
"value": "MIMTeam1"
}]
},
"supervisors": [
"9bccb70b-ab35-4746-b9f5-fa6eca0b1450",
"e623fc32-6201-4089-b6e5-eeec9dd284d6",
]
}'
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams"
javascript
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/dynamic-teams/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.targetName = 'MIMTeam1';
var criteria = {};
criteria.operand = 'OR';
var criterion1 = {};
criterion1.criterionType = 'BASIC_FIELD';
criterion1.field = 'USER_ID';
criterion1.operand = 'EQUALS';
criterion1.value = 'MIMTeam1'
var criterion = []
criterion.push(criterion1)
criteria.criterion = criterion;
data.criteria = criteria;
var supervisors = [];
supervisors.push('4d618961-21d6-417d-a904-8a84893b4e31','e623fc32-6201-4089-b6e5-eeec9dd284d6');
data.supervisors = supervisors;
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created dynamic team: " + json.targetName + ". ID = "+ json.id);
}
#The following code is formatted to work with Python v.3.6 and later.
import requests
base_url = "https://acmeco.xmatters.com/api/xm/1"
endpoint = "/dynamic-teams"
username = "yourUsername"
password = "yourPassword"
payload = {
"targetName": "MIMTeam1",
"criteria": [
{
"operand": "OR",
"criterion": {
"criterionType": "BASIC_FIELD",
"field": "USER_ID",
"operand": "EQUALS",
"value": "MIMTeam1",
},
}
],
"supervisors": ["9bccb70b-ab35-4746-b9f5-fa6eca0b1450", "e623fc32-6201-4089-b6e5-eeec9dd284d6"],
}
response = requests.post(base_url + endpoint, json=payload, auth=(username, password))
if response.status_code == 201:
print("Your dynamic team was created.")
else:
print("The dynamic team could not be created.")
RESPONSE
{
"id": "76896d39-4258-4de0-bc4b-c2aadb120187",
"targetName": "MIMTeam1",
"recipientType": "DYNAMIC_TEAM",
"externallyOwned": false,
"supervisors": {
"count": 2,
"total": 2,
"data": [
{
"id": "9bccb70b-ab35-4746-b9f5-fa6eca0b1450",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/9bccb70b-ab35-4746-b9f5-fa6eca0b1450"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "mmcbride",
"site": {
"id": "87165184-f025-46ec-bc8e-11314b4ddeb5",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/87165184-f025-46ec-bc8e-11314b4ddeb5"
}
},
"lastLogin": "2019-11-05T17:44:42.971Z",
"status": "ACTIVE"
},
{
"id": "e623fc32-6201-4089-b6e5-eeec9dd284d6",
"targetName": "ssmith",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/e623fc32-6201-4089-b6e5-eeec9dd284d6"
},
"firstName": "Steve",
"lastName": "Smith",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "ssmith",
"site": {
"id": "87165184-f025-46ec-bc8e-11314b4ddeb5",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/87165184-f025-46ec-bc8e-11314b4ddeb5"
}
},
"lastLogin": "2019-11-05T17:44:42.971Z",
"status": "ACTIVE"
}
]
},
"observers": {
"count": 0,
"total": 0,
"data": []
},
"criteria": {
"operand": "OR",
"criterion": {
"count": 1,
"total": 1,
"data": [
{
"criterionType": "BASIC_FIELD",
"field": "USER_ID",
"operand": "EQUALS",
"value": "MIMTeam1"
}
]
}
},
"links": {
"self": "/api/xm/1/dynamic-teams/76896d39-4258-4de0-bc4b-c2aadb120187"
}
}
Creates a dynamic team in xMatters.
The response returns a Dynamic team object that represents the newly-created dynamic team. You can use this object to locate the dynamic team’s unique identifier (the id
field).
Dynamic teams must have at least one supervisor.
DEFINITION
POST /dynamic-teams
BODY PARAMETERS
targetName | string |
The unique target name of the dynamic group. | |
recipientType | string |
For dynamic teams, the recipient type field is “DYNAMIC_TEAM”. | |
description | string |
optional | A description of the dynamic team. |
criteria | SubscriptionCriteria object |
The criteria used to determine members of the dynamic team. | |
supervisors | array [string] |
The unique id of the supervisor, or supervisors of a dynamic team. A dynamic team must have at least one supervisor, and the user (or users) set as the supervisor must have the appropriate permissions to supervise the team. | |
observers | Role object |
optional | The id or name of the role or roles set as observers for the dynamic team. |
RESPONSES
Success | Response code 201 Created and a Dynamic team object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Update a dynamic team
Update a dynamic team
REQUEST - Update a dynamic team
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "76896d39-4258-4de0-bc4b-c2aadb120187",
"targetName": "MIMTeam1",
"criteria":
{
"operand": "AND",
"criterion": [{
"criterionType": "BASIC_FIELD",
"field": "USER_ID",
"operand": "EQUALS",
"value": "MIMTeam1"
}]
},
"supervisors": [{
"id": "9bccb70b-ab35-4746-b9f5-fa6eca0b1450"
}]
}'
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams"
javascript
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/dynamic-teams/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '76896d39-4258-4de0-bc4b-c2aadb120187';
data.targetName = 'MIMTeam1';
var criteria = {};
criteria.operand = 'AND';
var criterion1 = {};
criterion1.criterionType = 'BASIC_FIELD';
criterion1.field = 'USER_ID';
criterion1.operand = 'EQUALS';
criterion1.value = 'MIMTeam1'
var criterion = []
criterion.push(criterion1)
criteria.criterion = criterion;
data.criteria = criteria;
var supervisors = [];
supervisors.push('4d618961-21d6-417d-a904-8a84893b4e31');
data.supervisors = supervisors;
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Updated dynamic team: " + json.targetName + ". ID = "+ json.id);
}
#The following code is formatted to work with Python v.3.6 and later.
import requests
base_url = "https://acmeco.xmatters.com/api/xm/1"
endpoint = "/dynamic-teams"
username = "yourUsername"
password = "yourPassword"
payload = {
"id": "76896d39-4258-4de0-bc4b-c2aadb120187",
"targetName": "MIMTeam1",
"criteria": [
{
"operand": "OR",
"criterion": {
"criterionType": "BASIC_FIELD",
"field": "USER_ID",
"operand": "EQUALS",
"value": "MIMTeam1",
},
}
],
"supervisors": {"id": "9bccb70b-ab35-4746-b9f5-fa6eca0b1450"},
}
response = requests.post(base_url + endpoint, json=payload, auth=(username, password))
if response.status_code == 200:
print("Your dynamic team was updated.")
else:
print("The dynamic team could not be created.")
RESPONSE
{
"id": "76896d39-4258-4de0-bc4b-c2aadb120187",
"targetName": "MIMTeam1",
"recipientType": "DYNAMIC_TEAM",
"externallyOwned": false,
"supervisors": {
"count": 1,
"total": 1,
"data": [
{
"id": "9bccb70b-ab35-4746-b9f5-fa6eca0b1450",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/9bccb70b-ab35-4746-b9f5-fa6eca0b1450"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "mmcbride",
"site": {
"id": "87165184-f025-46ec-bc8e-11314b4ddeb5",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/87165184-f025-46ec-bc8e-11314b4ddeb5"
}
},
"lastLogin": "2019-11-05T17:44:42.971Z",
"status": "ACTIVE"
}
]
},
"observers": {
"count": 0,
"total": 0,
"data": []
},
"criteria": {
"operand": "OR",
"criterion": {
"count": 1,
"total": 1,
"data": [
{
"criterionType": "BASIC_FIELD",
"field": "USER_ID",
"operand": "EQUALS",
"value": "MIMTeam1"
}
]
}
},
"links": {
"self": "/api/xm/1/dynamic-teams/76896d39-4258-4de0-bc4b-c2aadb120187"
}
}
Changes the properties of an existing dynamic team in xMatters. Identify the dynamic team by its unique identifier in the id
field, then provide the parameters you want to modify. Use GET /dynamic-team to find the id of the dynamic team.
DEFINITION
POST /dynamic-teams/
BODY PARAMETERS
The only required body parameter is the UUID of the dynamic team you want to update. See the Create a dynamic team body parameters for details on the parameters you can change.
id | string |
The unique identifier (id ) of the dynamic team you want to modify. |
RESPONSES
Success | Response code 200 Updated and a Dynamic team object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a dynamic team
Delete a dynamic team
REQUEST: Delete a dynamic team by name. You can also identify the group by its unique identifier (
id
).
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams/MIM-1"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/dynamic-teams/MIM-1",
/*"path" : "api/xm/1/dynamic-teams/0a344f68-5175-45d0-af6b-20f5e31bf646",*/
"method": "DELETE",
"headers" : {"Content-Type": "application/json"}
});
response = request.write();
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the dynamic team " + json.targetName);
}
import requests
from requests.auth import HTTPBasicAuth
import json
teamId = "438e9245-b32d-445f-916bd3e07932c892"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/dynamic-teams/" + teamId
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
print("Sending request to: " + url)
response = requests.delete(url, auth=auth)
responseCode = response.status_code
print("received response code: " + str(responseCode))
if responseCode == 200:
rjson = response.json()
print(
"Dynamic team "
+ rjson.get("id")
+ " was successfully deleted. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print("The request did not succeed. Response is:\n" + str(response))
RESPONSE
{
"id": "438e9245-b32d-445f-916bd3e07932c892",
"targetName": "MIM-1",
"recipientType": "DYNAMIC_TEAM",
"links":
{
"self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
}
}
Deletes a dynamic team, and terminates all memberships (such as groups, subscriptions, scheduled messages, etc.,) to the team.
Identify the dynamic team using either its name (the targetName
field) or its unique identifier (the id
field).
The response returns a Dynamic Team Object that represents the recently deleted dynamic team.
DEFINITION
DELETE /dynamic-teams/{dynamicTeamId}
URL PARAMETERS
dynamicTeamID | string |
The unique identifier (id ) or name (targetName ) of the dynamic team. Example: MIMTeam1 Example: a6341d69-5683-4621-b8c8-f2e728f6752q |
RESPONSES
Success | Response code 200 OK and a Dynamic team object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Dynamic team object
Dynamic team object
Dynamic team object
{
"id": "7345cdb1-6a59-4e85-addd-fc17ae3cbb04",
"targetName": "SubscriptionDynamicTeam",
"recipientType": "DYNAMIC_TEAM",
"externallyOwned": false,
"description": "Dynamic Team for Subscription tests",
"supervisors": {
"count": 1,
"total": 1,
"data": [
{
"id": "9bccb70b-ab35-4746-b9f5-fa6eca0b1450",
"targetName": "admin",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/9bccb70b-ab35-4746-b9f5-fa6eca0b1450"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "mmcbride",
"site": {
"id": "87165184-f025-46ec-bc8e-11314b4ddeb5",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/87165184-f025-46ec-bc8e-11314b4ddeb5"
}
},
"lastLogin": "2019-08-21T18:50:24.596Z",
"status": "ACTIVE"
}
]
},
"observers": {
"count": 0,
"total": 0,
"data": []
},
"criteria": {
"operand": "OR",
"criterion": {
"count": 1,
"total": 1,
"data": [
{
"criterionType": "BASIC_FIELD",
"field": "USER_ID",
"operand": "EQUALS",
"value": "SubsActivity_DynamicTeamUser"
}
]
}
},
"links": {
"self": "/api/xm/1/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04"
}
}
A representation of an xMatters dynamic team, including embedded supervisors and observers.
id | string |
the unique identifier (id ) of the dynamic group. |
|
targetName | string |
The target name of the dynamic group. | |
recipientType | string |
For dynamic teams, the recipient type field is “DYNAMIC_TEAM”. | |
description | string |
A description of the dynamic team. | |
externallyOwned | boolean |
See externallyOwned. | |
supervisors | Person or PersonReference object |
optional | A Paginated list of the supervisors of a dynamic team. This optional field is included when the request uses the ?embed=supervisors query parameter. Returns a Person object or PersonReference object, depending on what permissions the authenticating user has. |
observers | Role object |
optional | The id or name of the role or roles set as observers for the dynamic team. This optional field is included when the request uses the ?embed=observers query parameter. If no roles are set as observers, an empty data set is returned. |
criteria | SubscriptionCriteria object |
The criteria used to determine members of the dynamic team. | |
links | SelfLink object |
A link that can be used to reference the dynamic team. |
EVENTS
You can use the linked methods to start, stop, resume, and terminate events, as well as add comments to an event.
You can also retrieve a list of events and notifications in the system, or details about a specific event, including comments or annotations that have been added to the event.
Get events
Get events by querying current system data
REQUEST Get all events with a HIGH priority and an English text property named Country that has the value USA.
curl --user username "https://acmeco.xmatters.com/api/xm/1/events?propertyName=Country%23en&propertyValue=USA&priority=HIGH&embed=properties"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/events?propertyName=Country%23en&propertyValue=USA&priority=HIGH&embed=properties",
"method": "GET",
"autoEncodeURI": false
});
var response = request.write();
if (response.statusCode == 200 ) {
var json = JSON.parse(response.body);
console.log("Retrieved events: " + json.count);
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
numOfEvents = "5"
propertyArgs = "&embed=properties&propertyName=country%23en&propertyValue=USA"
priorityArg = "&priority=HIGH"
endpoint_URL = "/events?offset=0&limit=" + numOfEvents + propertyArgs + priorityArg
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
for d in rjson.get("data"):
print(
'Found event with id "'
+ d["eventId"]
+ '" submitted by userid "'
+ d["submitter"]["targetName"]
+ '" on comm plan "'
+ d["plan"]["name"]
+ '" and form "'
+ d["form"]["name"]
+ '"'
)
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
rjson = response.json()
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
Get events by querying historical system data
REQUEST Get all events with a HIGH priority and an English text property named Country that has the value USA.
curl --user username "https://acmeco.xmatters.com/api/xm/1/events?propertyName=Country%23en&propertyValue=USA&priority=HIGH&embed=properties&at=2018-11-02T08:00:00.000Z&from=2018-01-27T08:00:00.000Z&to=2018-06-30T08:00:00.000Z"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/events?propertyName=Country%23en&propertyValue=USA&priority=HIGH&embed=properties&at=2018-11-02T08:00:00.000Z&from=2018-01-27T08:00:00.000Z&to=2018-06-30T08:00:00.000Z",
"method": "GET",
"autoEncodeURI": false
});
var response = request.write();
if (response.statusCode == 200 ) {
var json = JSON.parse(response.body);
console.log("Retrieved events: " + json.count);
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/events?propertyName=Country%23en&propertyValue=USA&priority=HIGH&embed=properties"
url = base_URL + endpoint_URL + \
"?at=2018-11-02T08:00:00.000Z" + \
"&from=2018-01-27T08:00:00.000Z" + \
"&to=2018-06-30T08:00:00.000Z"
username = "myuser"
password = "pa55w0rd"
response = requests.get(url, auth=HTTPBasicAuth(username, password))
if response.status_code == 200:
json = response.json()
print("Retrieved " + str(json["count"]) + " of " + str(json["total"]) + " events.")
for d in json["data"]:
print(d["id"])
RESPONSE
{
"count": 1,
"total": 1,
"data":
[
{
"id": "116f41dc-395c-4bba-a806-df1eda88f4aa",
"name": "An customer-reported issue with Monitoring Tool X requires attention",
"eventType": "USER",
"plan": {
"id": "c56730a9-1435-4ae2-8c7e-b2539e635ac6",
"name": "Database monitoring"
},
"form": {
"id": "b593c84c-497d-461d-9521-7d9a2d09a4f3",
"name": "Situation Management Form"
},
"floodControl": false,
"submitter": {
"id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
"targetName": "xmapi-user",
"firstName": "xmapi",
"lastName": "user",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
},
},
"priority": "HIGH",
"incident": "INCIDENT_ID-981006",
"overrideDeviceRestrictions": false,
"otherResponseCountThreshold" : 2,
"otherResponseCount" : 1,
"escalationOverride": false,
"bypassPhoneIntro": false,
"requirePhonePassword": false,
"revision": {
"id": "34c384ba-eaa4-4278-9ebb-94726232b063",
"at": "2019-08-09T16:59:38.371Z",
"seq": "21866402165008"
},
"conference": {
"id": "54d93cee-d150-44e0-a102-07ac6f18261e",
"bridgeId": "84564207",
"type": "BRIDGE",
"bridgeNumber": "84564207",
"links": {
"self": "/api/xm/1/conferences/54d93cee-d150-44e0-a102-07ac6f18261e"
}
},
"eventId": "981006",
"created":"2016-10-31T22:37:35.301+0000",
"terminated":"2016-10-31T22:38:40.063+0000",
"status": "TERMINATED",
"links": {
"self": "/api/xm/1/events/116f41dc-395c-4bba-a806-df1eda88f4aa"
},
"responseCountsEnabled": false,
"properties": {
"Customer reported": true,
"Customers affected": 100,
"Country#en": "USA"
}
}
],
"links": {
"self": "/api/xm/1/events?propertyName=Country%23en&propertyValue=USA&priority=HIGH&offset=0&limit=100"
}
}
Returns a list of events.
The returned list of events includes basic information about each event. You can enhance the response to include the form properties for each event by including
the ?embed=properties
query parameter in your request.
If this endpoint is called without any search parameters, it returns a paginated list of all the events the authenticating user has permission to view. If search parameters are provided, this endpoint returns only the matching events.
Certain event types are only visible to Company Supervisors, and are not displayed to users without the appropriate permission level. Other event types are available for all users. If you do not see the events you expect, it is possible you do not have the appropriate permission level.
Searching by the following criteria is currently supported:
- Form properties
- Event status or priority
- Time the event was initiated
- The inbound integration request that triggered the event (using
requestId
) - The id or name of the communication plan or form that triggered the event
- Event initiator
- Message subject
- Type of event
- Targeted recipients
Searching for events by form property
You can search for events that have certain form (input) properties by using the propertyName
and propertyValue
query parameters.
Results are returned for whole or partial matches. Property names and property values are not case-sensitive when used in search terms. To narrow down search results, use propertyValueOperator
to perform exact match searches.
- To search by a single property value, use the
propertyName
andpropertyValue
query parameters. For example:?propertyName=eocActivated&propertyValue=false
- To search for a text property, use the property name, followed by the # symbol, followed by the language of the property. The # symbol must be URL-encoded. The following example shows how to search for the English version of the text property “myTextProp”:
?propertyName=myTextProp%23en&propertyValue=hello
- To search for an exact match, use the
propertyName
,propertyValue
, and apropertyValueOperator
. The following example shows how to search for the English version of the text property “myTextProp” that contains the value “hello”:?propertyName=myTextProp%23en&propertyValue=hello&propertyValueOperator=CONTAINS
- To search for hierarchy properties, write the value of each category separated by the
->
characters, with the angle bracket URL-encoded. For example:?propertyName=location&propertyValue=USA+-%3E+Oregon+-%3E+Salem
- To search by more than one property, separate the property names and values with commas.
?propertyName=isTrue,country&propertyValue=true,USA
- To search for properties that contain commas, the comma must be URL-encoded. This example shows how to search for the text “Balcony,upper”:
?propertyName=floor&propertyValue=Balcony%2Cupper
Searching by plan and form
You can search for events by the id or name of the communication plan or form associated with the event. You can use a comma-separated list to include multiple plans or multiple forms in the search.
You can’t mix id
and name
when searching for multiple items of the same type. For example, to search for events created by either plan1 or plan2, you can use ?plan=ID1,ID2 or ?plan=name1,name2, but not ?plan=ID1,name2.
The same applies when searching by forms. But you can mix id
and name
when you search by both plan and form (using ids for the plans and names for the forms, for example).
If you include both plans and forms in the search, this functions as an AND – in other words, FormA&Plan1
only returns events created by FormA in Plan1, not FormA in Plan2.
Ordering search results
By default, the returned events are sorted by the event identifier in descending order. You can use the sortBy
query parameter
to retrieve events sorted by the time they were initiated,
the user who submitted the event, or the status of the event. Use the sortOrder
query parameter to specify whether to return
the results in ascending or descending order.
DEFINITION
GET /events
GET /events?propertyName=customerAffected&propertyValue=false
GET /events?status=ACTIVE,SUSPENDED
GET /events?priority=HIGH,MEDIUM,LOW
GET /events?embed=properties,annotations,responseOptions,suppressions,
GET /events?embed=responseOptions,responseOptions.translations
GET /events?sortBy=START_TIME&sortOrder=ASCENDING
GET /events?requestId=5588db90-6b87-4662-9a2f-107d3bb233bf
GET /events?plan=c56730a9-1435-4ae2-8c7e-b2539e635ac6,d0019da1-7cc3-432c-a97d-136515986980
GET /events?plan=Database%20monitoring&form=8824b5b3-5875-4f04-adbc-e60fb108bef6
GET /events?submitterid=mmcbride
GET /events?search=Database&fields=name
GET /events?eventType=SYSTEM,USER
GET /events?from=2017-05-01T14:00:00.000Z&to=2017-05-01T19:00:00.000Z
GET /events?propertyName=animals,books&propertyValue=dogs,fiction&propertyValueOperator=EQUALS,CONTAINS
GET /events?at=2018-11-02T08:00:00.000Z&from=2018-01-27T08:00:00.000Z&to=2018-06-30T08:00:00.000Z
GET /events?at=2018-04-28TT08:00:00.000Z&priority=HIGH,MEDIUM
GET /events?embed=targetedRecipients
GET /events?targetedRecipients=c56730a9-1435-4ae2-8c7e-b2539e635ac6
GET /events?targetedRecipients=mmcbride,tsmith,jbrown
GET /events?resolvedUsers=mmcbride,tsmith
QUERY PARAMETERS
propertyName | string |
The name of a form property. This value is not case-sensitive. You can have multiple property names in a comma-separated list. | |
propertyValue | string |
The value of a form property. This value is not case-sensitive. You can have multiple property values in a comma-separated list. | |
propertyValueOperator | string |
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 . |
|
status | string |
The status of events that you want to return in the search results. Valid values include:
|
|
priority | string |
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 include:
GET /events?priority=HIGH,MEDIUM .To search historical data, use priority with the “at” parameter and a timestamp. For example: GET /events?at=2018-04-28TT08:00:00.000Z&priority=HIGH,MEDIUM |
|
embed | string |
A comma-separated list of the objects to embed in the response.
|
|
plan | string |
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.Example: c56730a9-1435-4ae2-8c7e-b2539e635ac6 Example: IT%20Communications (this example has the space URI-encoded) Because names can change, we recommend using the unique identifier ( id ). |
|
form | string |
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.Example: c56730a9-1435-4ae2-8c7e-b2539e635ac6 Example: SaaS%20Issues (this example has the space URI-encoded) Because names can change, we recommend using the unique identifier ( id ). You can find the UUID for a communication plan form in the web user interface by selecting the Messaging tab, selecting the form and clicking the API button. |
|
requestId | string |
The unique identifier returned from a request to trigger an Inbound Integration. Searching by requestId returns the event or events that were initiated when the Inbound Integration was triggered. |
|
eventType | string |
The type of event to return in the results. Valid values are either:
|
|
sortBy | string |
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 include:
|
|
sortOrder | string |
Specifies whether events are sorted in ascending or descending order. This parameter must be used in conjunction with the sortBy query parameter. Valid values include:
|
|
submitterid | string |
The unique identifier (id ) or name (targetName ) of the submitter. |
|
search | string |
The “search” parameter allows request results to be constrained by the content of the event’s “name” property. In email notifications, this property appears in the “subject” field. The fields=name constraint limits the search results to email subjects (for user events) or system event type (for system events). Search terms are not case sensitive, and the search returns full and partial string matches. You can search for multiple terms by using the OR parameter. For example, search=foo bar&fields=name returns all events whose subject contains “foo”, or “bar”, or “football”, or “rebar” or “bark”. |
|
targetedRecipients | string |
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. |
|
resolvedUsers | string |
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. |
|
offset | integer |
The number of items to skip before returning results. See Pagination query parameters. | |
limit | integer |
The number of items to return. See Pagination query parameters. | |
from | string |
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.Example: 2017-05-01T14:00:00.000Z |
|
to | string |
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.Example: 2017-05-01T19:00:00.000Z |
|
at | string |
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.To use the priority parameter, use ?at={timestamp} . For all other queries, use the to and from , or after and before parameters.
|
RESPONSES
Success | Response code 200 OK and a Pagination of Event objects in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Get an event
Get an event by querying current system data
REQUEST Get an event by event ID
curl --user username "https://acmeco.xmatters.com/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2?embed=properties,recipients,responseOptions,annotations,messages"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2?embed=properties,recipients,responseOptions,annotations,messages",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved event: " + json.eventId + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
eventId = "ced9fac9-1065-4659-82ab-1c9664a777b2"
embedArg = "embed=properties,recipients,responseOptions,annotations,messages"
endpoint_URL = "/events/" + eventId + "?" + embedArg
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print(
'Found event with id "'
+ rjson["eventId"]
+ '" and UUID "'
+ rjson["id"]
+ '" with name "'
+ rjson["name"]
+ '"'
)
print("The data is:\n\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
rjson = response.json()
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
Get an event by querying historical system data
REQUEST Get an event by event
curl --user username "https://acmeco.xmatters.com/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2?at=2018-11-02T08:00:00.000Z"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2?at=2018-11-02T08:00:00.000Z",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved event: " + json.eventId + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
eventId = "ced9fac9-1065-4659-82ab-1c9664a777b2"
embedArg = "embed=properties,recipients,responseOptions,annotations,messages"
historyArg = "&at=2019-08-09T17:00:00.000Z&from=2019-08-09T08:00:00.000Z&to=2019-08-09T17:00:00.000Z"
endpoint_URL = "/events/" + eventId + "?" + embedArg + historyArg
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print(
'Found event with id "'
+ rjson["eventId"]
+ '" and UUID "'
+ rjson["id"]
+ '" with name "'
+ rjson["name"]
+ '"'
)
print("The data is:\n\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
rjson = response.json()
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"id":"ced9fac9-1065-4659-82ab-1c9664a777b2",
"plan": {
"id": "c56730a9-1435-4ae2-8c7e-b2539e635ac6",
"name": "Database monitoring"
},
"form": {
"id": "0213a4ef-55f2-472a-b514-69c798197b0e",
"name": "Database outage"
},
"eventId":"408005",
"created":"2016-10-31T22:37:35.301+0000",
"terminated":"2016-10-31T22:38:40.063+0000",
"status":"TERMINATED",
"priority":"MEDIUM",
"incident":"INCIDENT_ID-408005",
"expirationInMinutes":180,
"overrideDeviceRestrictions": false,
"bypassPhoneIntro": false,
"requirePhonePassword": false,
"voicemailOptions":
{
"retry": 0,
"every": 60,
"leave": "callbackonly"
},
"floodControl" : false,
"otherResponseCountThreshold" : 2,
"otherResponseCount" : 1,
"submitter":
{
"id":"661f3f18-75ab-44fd-a22a-4bb0fe15917e",
"targetName":"mmcbride",
"firstName":"Mary",
"lastName":"Mcbride",
"recipientType":"PERSON",
"links":
{
"self":"/api/xm/1/people/661f3f18-75ab-44fd-a22a-4bb0fe15917e"
}
},
"recipients":
{
"count":2,
"total":2,
"data": [
{
"id":"b1697b84-c0cf-412c-b956-af810cd86bae",
"targetName":"poravets",
"recipientType":"PERSON",
"externallyOwned":false,
"links":
{
"self":"/api/xm/1/people/b1697b84-c0cf-412c-b956-af810cd86bae"
},
"firstName":"Pauline",
"lastName":"Oravets",
"language":"en_GB",
"timezone":"US/Pacific",
"webLogin":"poravets",
"phoneLogin":"99211",
"site":
{
"id":"8e451c6b-69e3-49d7-979c-e7a6e794f340",
"links":
{
"self":"/api/xm/1/sites/8e451c6b-69e3-49d7-979c-e7a6e794f340"
}
},
"status":"ACTIVE"
},
{
"id": "1ea8906f-be05-410d-9077-fa7587d7b626",
"targetName": "IT",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": true,
"useDefaultDevices": true,
"observedByAll": true,
"description": "",
"responseCount" : 2,
"responseCountThreshold" : 1,
"links": {
"self": "/api/xm/1/groups/1ea8906f-be05-410d-9077-fa7587d7b626"
},
"targeted": true
}],
"links":
{
"self": "/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2/recipients?targeted=true&offset=0&limit=100"
}
},
"annotations":
{
"count": 1,
"total": 1,
"data":
[
{
"id": "f223698e-dbd0-4089-a4c3-e6b7c76c639d",
"event":
{
"id": "ced9fac9-1065-4659-82ab-1c9664a777b2",
"eventId": "408005",
"links":
{
"self": "/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2"
}
},
"author":
{
"id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
"targetName": "admin",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links":
{
"self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
}
},
"comment": "I can help out.",
"created": "2016-10-31T22:17:31.450Z"
}
]
},
"conference":
{
"id": "53d92cee-d150-44e0-a103-07ac6f18261e",
"bridgeId":"67955226",
"type":"BRIDGE",
"bridgeNumber": "67955226",
"links":
{
"self": "/api/xm/1/conferences/53d92cee-d150-44e0-a103-07ac6f18261e"
}
},
"responseOptions":
{
"count":2,
"total":2,
"data": [
{
"id":"5ac343a9-4df3-4bd6-908f-5f42630ceb65",
"number":1,
"text":"Join",
"description":"Join",
"prompt":"I will join the conference.",
"action":"RECORD_RESPONSE",
"contribution":"NONE",
"joinConference":true,
"allowComments":false
},
{
"id":"a5b28147-8aa9-4fa0-82dd-e47e1f3b02f2",
"number":2,
"text":"Reject",
"description":"Reject",
"prompt":"I cannot assist.",
"action":"STOP_NOTIFYING_USER",
"contribution":"NONE",
"joinConference":false,
"allowComments":true
}]
},
"properties":
{
"myNumberProperty": 323423,
"myPasswordProperty": "ilovecats123",
"myTextProperty#en": "This is urgent. Please respond.",
"myListProperty":
[
"iOS",
"Android",
"Windows 10"
],
"myBooleanProperty": true,
"myComboProperty": "Oracle Database",
"myHierarchyProperty":
[
{
"category": "Country",
"value": "USA"
},
{
"category": "State",
"value": "WA"
},
{
"category": "City",
"value": "Seattle"
}
]
},
"messages":
{
"count": 1,
"total": 1,
"data":
[{
"id": "e3d4e459-732d-4b4f-8f85-159ec25db729",
"messageType": "SUBJECT_AND_BODY",
"language": "en",
"subject": "Outage in NOC 4",
"body": "<div><span style=\"white-space: nowrap;\">[First Name] [Last Name] - a new task was assigned to you</span></div><span style=\"white-space: nowrap;\">Description:</span><div><span style=\"white-space: nowrap;\">Please investigate the reported outage.</span></div><div><span style=\"white-space: nowrap;\"><br></span></div><div><span style=\"white-space: nowrap;\">https://servicedesk.example.com/90834903q095</span></div>"
}]
}
}
Returns information about an event, including the following default attributes:
- the person who initiated the event
- the form used to create the event
- any conference bridge details associated with the event
You can enhance the response to include the following attributes:
- the values of form properties
- event recipients (targeted or resolved)
- the response choices included with the event
- the HTML message content for email notifications
- any suppressions that occurred related to the event
- what the event looked like at a specific point in time in the past
When you call GET /events/{eventID} without any query parameters, it includes the response options and the first 100 directly-targeted recipients in the response. If you include any query parameters with the request, the response observes the query parameters and returns the requested information.
Targeted recipients are the users, groups, dynamic teams, and devices that were included in the recipient list when the event was initiated. Targeted recipients include the names of groups and dynamic teams but do not expand to include their members. Targeted recipients include users but do not include their notified devices unless the devices were explicitly added as recipients.
To retrieve an event including targeted recipients, use GET /events/{eventId}?embed=recipients&targeted=true.
Resolved recipients are the actual users and devices that received notifications. This includes members of groups and dynamic teams. There may be several resolved recipients corresponding to a single user, depending on how many of the user’s devices were notified.
To retrieve an event including resolved recipients, use GET /events/{eventId}?embed=recipients
DEFINITION
GET /events/{eventId}
GET /events/{eventId}?embed=properties,recipients,annotations,messages,responseOptions,suppressions
GET /events/{eventId}?embed=responseOptions,responseOptions.translations
GET /events/{eventId}?embed=recipients&targeted=true
GET /events/{eventId}?at=2018-11-02T08:00:00.000Z
URL PARAMETERS
eventId | string |
The unique identifier or id of the event. Examples:
Note: 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. |
QUERY PARAMETERS
embed | string |
A comma-separated list of the properties to embed in the response.
|
|
targeted | Boolean |
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. |
|
at |
string |
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.Example: 2017-05-01T19:00:00.000Z |
RESPONSES
Success | Response code 200 OK and an Event object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Get event annotations
Get all annotations on an event
REQUEST (get all comments or annotations on an event)
curl --user username "https://acmeco.xmatters.com/api/xm/1/events/a7ab8012-0583-4e5b-a5dd-36f67ec016f3/annotations"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/events/a7ab8012-0583-4e5b-a5dd-36f67ec016f3/annotations",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved: " + json.count + " of " + json.total + "comments");
for (var i in json.data) {
console.log(json.data[i].author.targetName + " added comment " + json.data[i].comment);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
numOfResults = "1"
eventId = "add6a38f-bed7-4169-afa2-cbaf5387ef06"
endpoint_URL = "/events/" + eventId + "/annotations?offset=0&limit=" + numOfResults
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
for d in rjson.get("data"):
print(
'Found annotation with id "'
+ d["id"]
+ '" with comment "'
+ d["comment"]
+ '" submitted by userid "'
+ d["author"]["targetName"]
+ '"'
)
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
rjson = response.json()
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"id": "68aff19c-1573-46a4-97f4-f5d83e15c483",
"event": {
"id": "add6a38f-bed7-4169-afa2-cbaf5387ef06",
"eventId": "41159032",
"links": {
"self": "/api/xm/1/events/add6a38f-bed7-4169-afa2-cbaf5387ef06"
}
},
"author": {
"id": "935600d0-ae51-445c-805a-d38e49b80e96",
"targetName": "asamara",
"firstName": "Ali",
"lastName": "Samara",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/935600d0-ae51-445c-805a-d38e49b80e96"
}
},
"comment": "I know what the cause is. I'll get right on it.",
"created": "2018-03-12T17:52:25.080Z",
"links": {
"self": "/api/xm/1/events/add6a38f-bed7-4169-afa2-cbaf5387ef06/annotations/68aff19c-1573-46a4-97f4-f5d83e15c483"
}
},
{
"id": "27320671-0ec7-465c-bcbb-27c62e137c97",
"event": {
"id": "add6a38f-bed7-4169-afa2-cbaf5387ef06",
"eventId": "41159032",
"links": {
"self": "/api/xm/1/events/add6a38f-bed7-4169-afa2-cbaf5387ef06"
}
},
"author": {
"id": "d4513ee9-cee6-4496-abf5-93a9a4d35423",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/d4513ee9-cee6-4496-abf5-93a9a4d35423"
}
},
"comment": "Talked to Ali. Will take about 15 minutes to resolve.",
"created": "2018-03-12T17:52:03.456Z",
"links": {
"self": "/api/xm/1/events/add6a38f-bed7-4169-afa2-cbaf5387ef06/annotations/27320671-0ec7-465c-bcbb-27c62e137c97"
}
}
],
"links": {
"self": "/api/xm/1/events/add6a38f-bed7-4169-afa2-cbaf5387ef04/annotations?offset=0&limit=100"
}
}
Returns a list of all comments (annotations) on the event, with the comment and the author details, but with only basic information on the event itself. If you want detailed information about the event, including comments, use GET/events?embed=annotations
This retrieves comments added either directly on the tracking report or when a recipient responds to a notification.
DEFINITION
GET /events/{eventID}/annotations
URL PARAMETERS
eventID | string |
The unique identifier (id ) or eventID (eventId ) of the event. Example:
Note: 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 user interface. |
|
offset | integer |
The number of items to skip before returning results. See Pagination query parameters. | |
limit | integer |
The number of items to return. See Pagination query parameters. |
RESPONSES
Success | Response code 200 OK and a Pagination of Annotation objects in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get an event annotation
Get an annotation on an event
REQUEST (get a comment using its annotation ID)
curl --user username "https://acmeco.xmatters.com/api/xm/1/events/1e82ef91-fc4f-4d97-b17d-432582c5a36b/annotations/10bc5d79-1a40-426d-8e3b-24dc457672f6"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/events/1e82ef91-fc4f-4d97-b17d-432582c5a36b/annotations/10bc5d79-1a40-426d-8e3b-24dc457672f6",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved comment: " + json.data.comment + " by " + json.data.author.targetName". ID = " + json.data.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
eventId = "1e82ef91-fc4f-4d97-b17d-432582c5a36b"
annotationId = "10bc5d79-1a40-426d-8e3b-24dc457672f6"
endpoint_URL = "/events/" + eventId + "/annotations/" + annotationId
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print(
'Found annotation with author "'
+ rjson["author"]["targetName"]
+ '" with comment "'
+ rjson["comment"]
+ '"'
)
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
rjson = response.json()
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"id": "68aff19c-1573-46a4-97f4-f5d83e15c483",
"event": {
"id": "add6a38f-bed7-4169-afa2-cbaf5387ef06",
"eventId": "41159032",
"links": {
"self": "/api/xm/1/events/add6a38f-bed7-4169-afa2-cbaf5387ef06"
}
},
"author": {
"id": "935600d0-ae51-445c-805a-d38e49b80e96",
"targetName": "asamara",
"firstName": "Ali",
"lastName": "Samara",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/935600d0-ae51-445c-805a-d38e49b80e96"
}
},
"comment": "I know what the cause is. I'll get right on it.",
"created": "2018-03-12T17:52:25.080Z",
"links": {
"self": "/api/xm/1/events/add6a38f-bed7-4169-afa2-cbaf5387ef06/annotations/68aff19c-1573-46a4-97f4-f5d83e15c483"
}
}
Returns a specific comment (annotation) for an event, with the comment and the author details, but with only basic information on the event itself.
This retrieves comments added either directly on the tracking report or when a recipient responds to a notification.
DEFINITION
GET /events/{eventID}/annotations/{annotationID}
URL PARAMETERS
{eventID} | string |
The unique identifier (id ) or eventID (eventId ) of the event. Example:
Note: 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 user interface. |
|
{annotationID} | string |
The unique identifier (id ) of the annotation. Example:
|
RESPONSES
Success | Response code 200 OK and an Annotation object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get user delivery data
Get user delivery data
REQUEST Get a list of users who were notified of an event (from historical data), including the user’s properties in the response.
curl --user username "https://acmeco.xmatters.com/api/xm/1/events/af4cab7-5301-4156-9d9e-33983a7f2b18/user-deliveries?embed=person.properties&at=2019-11-13T21:48:51Z"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/events/af4cab7-5301-4156-9d9e-33983a7f2b18/user-deliveries?embed=person.properties&at=2019-11-13T21:48:51Z",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved event: " + json.eventId + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/events"
url = base_URL + endpoint_URL + \
"/af4cab7-5301-4156-9d9e-33983a7f2b18" + \
"user-deliveries?embed=person.properties&at=2019-11-13T21:48:51Z"
username = "myuser"
password = "pa55w0rd"
response = requests.get(url, auth=HTTPBasicAuth(username, password))
if response.status_code == 200:
print("Retrieved event " + response.json()["eventId"] + ". id = " + response.json()["id"])
elif response.status_code == 404:
print("The event could not be found: " + response.json()["eventId"])
RESPONSE
{
"count": 1,
"total": 1,
"data": [
{
"event": {
"id": "7af4cab7-5301-4156-9d9e-33983a7f2b18",
"eventId": "24721002",
"links": {
"self": "/api/xm/1/events/7af4cab7-5301-4156-9d9e-33983a7f2b18&at=2019-11-13T21:48:51Z"
}
},
"person": {
"id": "bc434d9d-a9a9-4b6d-8520-dc9adce0c57f",
"targetName": "thanks",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/bc434d9d-a9a9-4b6d-8520-dc9adce0c57f&at=2019-11-13T21%3A48%3A51Z"
},
"firstName": "Mary",
"lastName": "McBride",
"site": {
"id": "87165184-f025-46ec-bc8e-11314b4ddeb5",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/87165184-f025-46ec-bc8e-11314b4ddeb5?&at=2019-11-13T21%3A48%3A51Z"
}
},
"properties": {
"isFirstAid": [
"true"
],
"isCPR": [
"true"
],
"firstAidLevel": [
"1"
],
"location": [
"Denver office"
],
}
},
"deliveryStatus": "RESPONDED",
"notifications": {
"count": 1,
"total": 1,
"data": [
{
"id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6",
"category": "DEVICE",
"recipient": {
"id": "32d54bb4-9b3e-438b-bb9f-ea6060f5092b",
"targetName": "1st Aid Email",
"recipientType": "DEVICE",
"deviceType": "EMAIL",
"name": "",
"links": {
"self": "/api/xm/1/devices/32d54bb4-9b3e-438b-bb9f-ea6060f5092b&at=2019-11-13T21%3A48%3A51Z"
}
},
"deliveryStatus": "RESPONDED",
"deliveryAttempted": "2019-11-12T16:54:14.918Z",
"responses": {
"count": 2,
"total": 2,
"data": [
{
"text": "On my way - be there soon.",
"notification": {
"id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6"
},
"received": "2019-11-12T16:54:37.656+0000"
},
{
"text": "Unavailable, call 911.",
"notification": {
"id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6"
},
"received": "2019-11-12T16:54:31.328+0000"
}
]
},
"delivered": "2019-11-12T16:54:15.789Z",
"responded": "2019-11-12T16:54:31.328Z"
}
]
},
"response": {
"text": "On my way - be there soon.",
"notification": {
"id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6"
},
"received": "2019-11-12T16:54:37.656+0000"
}
}
],
"links": {
"self": "/api/xm/1/events/24721002/user-deliveries?limit=100&at=2019-11-13T21%3A48%3A51Z&embed=person.properties&offset=0"
}
}
This endpoint takes the place of GET notifications
, which is now deprecated. It returns detailed information on who was notified for a specific event, the notification delivery status, the date and time of the notification, and which devices were contacted. As the endpoint queries historical data, you must include the at
parameter.
DEFINITION
GET /events/{eventID}/user-deliveries?at={timestamp}
GET /events/{eventID}/user-deliveries?at={timestamp}&embed=person.properties
URL PARAMETERS
eventId | string |
The unique identifier (id ) or event ID of the event. Examples:
Note: We recommend using the unique identifier, since the event ID number might not always return results. To find the event ID or unique id for an event, use GET /events, or locate the Event UUID entry on the event’s Properties screen in the web interface. |
QUERY PARAMETERS
embed | string |
optional | A comma-separated list of the properties to embed in the response. Available property is:
|
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 include:
|
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 include:
|
deliveryStatus | string |
optional | A comma separated list of delivery statuses. Valid values include:
|
offset | integer |
optional | The number of items to skip before returning results. See Pagination query parameters. |
limit | integer |
optional | The number of items to return. See Pagination query parameters. |
at |
string |
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.Example: 2017-05-01T19:00:00.000Z |
RESPONSES
Success | Response code 200 OK and a Pagination of User Delivery Data object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Trigger an event
Trigger an event
REQUEST
/* 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.
* This example shows how to trigger an event using an inbound integration that uses
* the "Create Event" action. For these inbound integrations you can configure form
* settings by including a JSON payload in the body of the request to the inbound
* integration URL.
*
* To see how to customize an inbound integration that uses the "Transform Content to Create Event"
* action, see the Integration Builder example.
*/
curl -H "Content-Type: application/json" -X POST -d '
{
"recipients" :
[
{"id":"mmcbride", "recipientType": "PERSON"},
{"id":"bfdbcb31-d02e-4a4f-a91c-7d68fbe416df", "recipientType": "PERSON"},
{"id":"mmcbride|Work Email", "recipientType": "DEVICE"},
{"id":"4a0fdfb4-7c49-4581-9cd9-804f2956e19b", "recipientType": "DEVICE"},
{"id":"Executives", "recipientType": "GROUP"},
{"id":"f19d8b10-923a-4c23-8348-06ced678075e", "recipientType": "GROUP", "responseCountThreshold" : 3},
{"id":"First Aid Attendants", "recipientType": "DYNAMIC_TEAM", "responseCountThreshold" : 1},
{"id":"ed2606c5-ef2b-4ce8-9259-d5cdacd5bd90", "recipientType": "DYNAMIC_TEAM"}
],
"otherResponseCountThreshold" : 4,
"priority" : "HIGH",
"expirationInMinutes" : 60,
"overrideDeviceRestrictions": true,
"escalationOverride": true,
"bypassPhoneIntro": true,
"requirePhonePassword": true,
"voicemailOptions":
{
"retry": 0,
"every": 60,
"leave": "callbackonly"
},
"conference":
{
"bridgeId": "Corporate WebEx",
"type": "EXTERNAL"
},
"responseOptions" :
[
{
"id" : "fee39ecf-75a7-45eb-9e63-ffc441499c4f"
},
{
"id" : "085d4bea-9dfb-4d2b-8136-22e19b1baaf6",
"redirectUrl" : "https://jira.example.com/view/INCD-2933"
},
{
"number": 3,
"text": "Reject",
"description": "I cannot help",
"prompt": "Reject",
"action": "RECORD_RESPONSE",
"contribution": "NEGATIVE",
"joinConference": false,
"allowComments": false
}
],
"properties" :
{
"myBooleanProperty" : false,
"myNumberProperty": 22183,
"myTextProperty" : "See the attached evacuation route map.",
"myListProperty" : ["Grocery", "Automotive", "Seasonal"],
"myComboProperty" : "Shelter in place.",
"myPasswordProperty" : "e293Usf@di",
"myHierarchyProperty":
[
{
"category": "Country",
"value": "USA"
},
{
"category": "State",
"value": "California"
},
{
"category": "City",
"value": "Los Angeles"
}
]
},
"senderOverrides": {
"displayName": "FIRE MARSHALL",
"callerId": "+12505551234"
},
"targetAllDevices": false,
"targetDeviceNames" : [
{"name" : "Work Email"},
{"name" : "Work Phone"},
{"name" : "Home Email"},
{"name" : "Home Phone"},
{"name" : "SMS Phone"},
{"name" : "Fax"},
{"name" : "Pager"},
{"name" : "Mobile Phone"},
{"name" : "My custom device name"}
]
}' "https://acmeco.xmatters.com/api/integration/1/functions/ba601cb1-3513-4320-b48a-05cb501bb5af/triggers?apiKey=ffcd4dec-8a49-4a67-9e59-ed9fabcb002d"
/***
* This example shows how to customize the built-in trigger object to
* customize form settings and then trigger an event from within an inbound
* integration that uses the "Transform Content to create new xMatters Event" option
*/
//Recipients including some respones counts for groups
var recipients = [];
recipients.push({"id":"mmcbride", "recipientType": "PERSON"});
recipients.push({"id":"bfdbcb31-d02e-4a4f-a91c-7d68fbe416df", "recipientType": "PERSON"});
recipients.push({"id":"mmcbride|Work Email", "recipientType": "DEVICE"});
recipients.push({"id":"4a0fdfb4-7c49-4581-9cd9-804f2956e19b", "recipientType": "DEVICE"});
recipients.push({"id":"Executives", "recipientType": "GROUP"});
recipients.push({"id":"f19d8b10-923a-4c23-8348-06ced678075e", "recipientType": "GROUP", "responseCountThreshold" : 3});
recipients.push({"id":"First Aid Attendants", "recipientType": "DYNAMIC_TEAM", "responseCountThreshold" : 1});
recipients.push({"id":"ed2606c5-ef2b-4ce8-9259-d5cdacd5bd90", "recipientType": "DYNAMIC_TEAM"});
trigger.recipients = recipients;
//Set response counts for others group
trigger.otherResponseCountThreshold = 4;
//Conference bridge (external)
var conference = {};
//Syntax for joining external conference bridge with static bridge number
conference.bridgeId = "Webex";
conference.type = "EXTERNAL";
//Syntax for joining external conference bridge with dynamic bridge number
//conference.bridgeId = "Webex";
//conference.type = "EXTERNAL";
//conference.bridgeNumber = "74747466";
//Syntax for joining in-progress xMatters-hosted bridge
//conference.bridgeId = "3882920";
//conference.type = "BRIDGE";
//Syntax for joining new xMatters-hosted bridge
//conference.type = "BRIDGE";
trigger.conference = conference;
//Responses
var responseOptions = [];
//select an existing response option
responseOptions.push({"id" : "fee39ecf-75a7-45eb-9e63-ffc441499c4f"});
//modify an existing response option
responseOptions.push({"id" : "085d4bea-9dfb-4d2b-8136-22e19b1baaf6",
"joinConference" : false,
"redirectUrl" : "https://jira.example.com/view/INCD-2933"});
//create a new response option
responseOptions.push({"number": 3,
"text": "Reject",
"description": "I cannot help",
"prompt": "Reject",
"action": "RECORD_RESPONSE",
"contribution": "NEGATIVE",
"redirectUrl": "https://www.example.com",
"joinConference": false,
"allowComments": false});
trigger.responseOptions = responseOptions;
//Handling
trigger.expirationInMinutes = 120;
trigger.bypassPhoneIntro = false;
trigger.escalationOverride = false;
trigger.overrideDeviceRestrictions = true;
trigger.priority = "HIGH";
trigger.requirePhonePassword = true;
var voicemailOptions= {};
voicemailOptions.every = 5;
voicemailOptions.leave = "callbackonly";
voicemailOptions.retry = 3;
trigger.voicemailOptions = voicemailOptions;
//Properties
trigger.properties.myTextProperty = "See the attached evacuation route map.";
trigger.properties.myComboBoxProperty = "Shelter in place.";
trigger.properties.myNumberProperty = 22183;
trigger.properties.myBooleanProperty = true;
trigger.properties.myListProperty = ['Stored Procedures', 'Web Services'];
trigger.properties.myPasswordProperty= "e293Usf@di";
var hierarchyProperty = [];
hierarchyProperty.push({"category" : "Country", "value" : "USA"});
hierarchyProperty.push({"category" : "State", "value" : "California"});
hierarchyProperty.push({"category" : "City", "value" : "Los Angeles"});
trigger.properties.myHierarchyProperty = hierarchyProperty;
Override sender display information
senderOverrides.displayName = "FIRE MARSHALL";
senderOverrides.callerId= "+12505551234";
//Devices
trigger.targetAllDevices = false;
var targetDeviceNames = [];
targetDeviceNames.push({"name" : "Work Email"});
targetDeviceNames.push({"name" : "Work Phone"});
targetDeviceNames.push({"name" : "Home Email"});
targetDeviceNames.push({"name" : "Home Phone"});
targetDeviceNames.push({"name" : "SMS Phone"});
targetDeviceNames.push({"name" : "Mobile Phone"});
targetDeviceNames.push({"name" : "Fax"});
targetDeviceNames.push({"name" : "Pager"});
targetDeviceNames.push({"name" : "Numeric Pager"});
targetDeviceNames.push({"name" : "My custom device name"});
trigger.targetDeviceNames = targetDeviceNames;
//Trigger the event
form.post(trigger);
#The following code is formatted to work with Python v.3.6 and later.
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/integration/1/functions/ba60cb1-3513-4320-b48a-05cb501bb5af/triggers"
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"recipients": [
{"id": "mmcbride", "recipientType": "PERSON"},
{"id": "bfdbcb31-d02e-4a4f-a91c-7d68fbe416df", "recipientType": "PERSON"},
{"id": "mmcbride|Work Email", "recipientType": "DEVICE"},
{"id": "4a0fdfb4-7c49-4581-9cd9-804f2956e19b", "recipientType": "DEVICE"},
{"id": "Executives", "recipientType": "GROUP"},
{
"id": "f19d8b10-923a-4c23-8348-06ced678075e",
"recipientType": "GROUP",
"responseCountThreshold": 3,
},
{
"id": "First Aid Attendants",
"recipientType": "DYNAMIC_TEAM",
"responseCountThreshold": 1,
},
{"id": "ed2606c5-ef2b-4ce8-9259-d5cdacd5bd90", "recipientType": "DYNAMIC_TEAM"},
],
"otherResponseCountThreshold": 4,
"priority": "HIGH",
"expirationInMinutes": 60,
"overrideDeviceRestrictions": True,
"escalationOverride": True,
"bypassPhoneIntro": True,
"requirePhonePassword": True,
"voicemailOptions": {"retry": 0, "every": 60, "leave": "callbackonly"},
"conference": {"bridgeId": "Corporate WebEx", "type": "EXTERNAL"},
"responseOptions": [
{"id": "fee39ecf-75a7-45eb-9e63-ffc441499c4f"},
{
"id": "085d4bea-9dfb-4d2b-8136-22e19b1baaf6",
"redirectUrl": "https://jira.example.com/view/INCD-2933",
},
{
"number": 3,
"text": "Reject",
"description": "I cannot help",
"prompt": "Reject",
"action": "RECORD_RESPONSE",
"contribution": "NEGATIVE",
"joinConference": False,
"allowComments": False,
},
],
"properties": {
"myBooleanProperty": False,
"myNumberProperty": 22183,
"myTextProperty": "See the attached evacuation route map.",
"myListProperty": ["Grocery", "Automotive", "Seasonal"],
"myComboProperty": "Shelter in place.",
"myPasswordProperty": "e293Usf@di",
"myHierarchyProperty": [
{"category": "Country", "value": "USA"},
{"category": "State", "value": "California"},
{"category": "City", "value": "Los Angeles"},
],
},
"senderOverrides": {"displayName": "FIRE MARSHALL", "callerId": "+12505551234"},
"targetAllDevices": False,
"targetDeviceNames": [
{"name": "Work Email"},
{"name": "Work Phone"},
{"name": "Home Email"},
{"name": "Home Phone"},
{"name": "SMS Phone"},
{"name": "Fax"},
{"name": "Numeric Pager"},
{"name": "Pager"},
{"name": "Mobile Phone"},
{"name": "My custom device name"},
],
}
data_string = json.dumps(data)
response = requests.post(
inbound_integration_url, headers=headers, data=data_string, auth=auth
)
responseCode = response.status_code
if responseCode == 202:
print("Event triggered = " + response.json()["requestId"])
else:
print("Error: response code is " + str(responseCode))
There are several ways to trigger an event from another cloud-based system or from within your own application. This section will help you choose the best way to integrate with xMatters.
- Prepackaged and built-in integrations: If you want to trigger an event from a third-party system such as ServiceNow, DataDog, Slack, New Relic, and others, check out our prepackaged and built-in integrations, which get you up and running in just a few clicks.
- Generic webhook: If you want to integrate quickly from a third-party system you can use the generic webhook to fire off an event from any system that can send a POST request to a URL. This option does not require you to make your own communication plan.
- Inbound integration (Create event): If you already have a communication plan you want to use, create a new Inbound Integration and choose the Create event option. This allows you to kick off a form and customize its settings by passing a JSON object in the body of the POST request to the Inbound Integration URL. For an example of the JSON payload, see the cURL or Python code samples in this section.
- Inbound integration (Transform content): If you’d like to use a communication plan but your system cannot construct the JSON payload in the format required by xMatters, use an Inbound Integration with the Transform content to create new xMatters event option. You can then pass the payload into the Inbound Integration in any format, and use the Integration Builder’s built-in Javascript editor to transform the payload into the format required by xMatters. For an example of how to use the Integration Builder’s script editor to customize and fire off an event, see the Integration Builder code sample in this section.
- Trigger an event directly (deprecated): The previous version of the REST API allows you to trigger an event by making a direct call to an endpoint. This way of triggering an event is not recommended since you can’t access the enhanced authentication and event customization options available in the Integration Builder, and your script may block while the event is in the queue to be processed. For more information about this endpoint, see POST trigger.
The rest of this section describes how to work with inbound integrations using the Create event or Transform content to create xMatters event options. If you are working with prepackaged integrations, built-in integrations, or generic webhooks, follow the links above for information about how to work with them. Note that inbound integrations can receive a maximum payload size of 200,000 bytes.
Configuring a form for access by an Inbound Integration
In order for a form to be triggered using an inbound integration, it must be deployed as a web service and the communication plan it belongs to must be enabled. Additionally, the authenticating user must have permission to initiate the form.
Customizing form settings
When you trigger an event you can override the following communication plan form settings:
- Recipients: Set the user, devices, groups and dynamic teams that will be notified by the event. If your form uses response counts you can set the number of required responses for each group and dynamic team recipient.
- Properties: Set the value of any form property.
- Conferences: Configure the conference call information for the event. Choose to use a new or in-progress xMatters conference bridge or an external conference bridge.
- Responses: Select the form’s default responses, modify the form’s responses, or create new responses. Use this to dynamically set the URL redirect to open a chat room or service desk ticket when a user responds to a notification.
- Handling Options: Set any handling section option, including the priority, event duration, voicemail options, and escalation and device overrides.
- Response Counts: If the form is configured to use response counts (fill counts), you can specify the number of required responses for each group and dynamic team and how many responses from the “Others” category are required. To specify the response count for a group or dynamic team, use the
responseCountThreshold
field in the recipients list. To specify the “others” response count, include theotherResponseCountThreshold
field. - Targeted Devices: Set whether the notification targets all the user’s available devices or only targets specific devices such as their Work Email and Work Phone.
- Sender Overrides: By setting the sender information (
displayName
andcallerID
) to meaningful values, recipients identify that notifications were sent from xMatters, preventing valid messages from being marked as spam or junk mail.
If you do not provide these settings in your request then xMatters uses the default form settings to create the event.
Enhancing inbound integrations created prior to Oct 2017
Inbound integrations that use the Transform Content option and were created prior to October 20, 2017 customize the form settings by using the payload structure of the deprecated POST trigger endpoint. The Integration Builder still processes this deprecated payload, so you do not need to take any action for your existing integrations to continue to run.
If you want to enhance an Inbound Integration that uses the deprecated payload format so that it can access features made available in the new payload format, you must convert the entire payload to use the new format as described in this section. You cannot mix-and-match parts of the deprecated payload with the new payload.
In particular, this means that you cannot use the previous recipients format, for example "targetName" : "mmcbride"
or the
Integration Builder’s helper methods, for example, trigger.addRecipient ("mmcbride")
to define the form recipients.
Instead, you must use the recipient format described in this section, for example "id" : "mmcbride", "recipientType" :"PERSON"
DEFINITION
Trigger the event by sending a POST request to the inbound integration URL, which you can obtain from the inbound integration. Inbound integration URLs use the following patterns:
POST /api/integration/1/functions/{id}/triggers
POST /api/integration/1/functions/{id}/triggers?apiKey={apiKey}
BODY PARAMETERS
recipients | array [RecipientTrigger object] |
optional | Specifies the people, devices, groups, and dynamic teams that are directly targeted when this form is triggered. If the form is configured to use response counts (fill counts), you can also specify the number of people in a group or dynamic team that are required to respond. If the form is configured to use subscriptions, additional recipients not included in this list may be notified if the notification matches their subscription preferences. |
priority | string |
optional | The priority of the event. Valid values include the following:
|
expirationInMinutes | integer |
optional | The duration of the event in minutes. See note. |
overrideDeviceRestrictions | Boolean |
optional | When this value is set to true, xMatters ignores device timeframes and delays. This allows users to be notified on any device at any time, regardless of their preferences. See note. |
escalationOverride | Boolean |
optional | When this value is set to true, xMatters ignores shift escalation delays and immediately broadcasts the message to all recipients. See note. |
bypassPhoneIntro | Boolean |
optional | When this value is set to true, xMatters omits the standard voice greeting and plays the message immediately. See note. |
requirePhonePassword | Boolean |
optional | When this value is true, the recipient must enter their phone password before a voice notification is played. This option cannot be used with options to leave the message content as voicemail. See note. |
voicemailOptions | VoicemailOptions object |
optional | For voice notifications, this defines whether to try the call again or leave a message. See note. |
properties | PropertyValues object |
optional | Allows you to set the values of form properties. |
conference | ConferencePointer object |
optional | When a form contains a conference bridge, this allows you to select which conference bridge to use. Depending on how the form is configured, you may be able to use an xMatters-hosted conference bridge or an external bridge. Example: New xMatters-hosted bridge "conference": { "type": "BRIDGE" } Example: Existing xMatters-hosted bridge "conference": { "bridgeId": "3882920", "type": "BRIDGE" } Example: Externally-hosted bridge with static bridge number "conference": { "bridgeId": "Corporate WebEx", "type": "EXTERNAL" } Example: Externally-hosted bridge with dynamic bridge number "conference": { "bridgeId": "Corporate WebEx", "type": "EXTERNAL", "bridgeNumber": "74747466" } |
responseOptions | ResponseOptions object |
optional | Overrides the form’s response options.
|
otherResponseCountThreshold | integer |
optional | For forms that use response counts, this specifies the number of responses that are required from the “other recipients” group. You can specify the response counts for individual groups and dynamic teams when you specify them as recipients, for example, to set the response count threshold for the group ‘IT’: "recipients": [ { "id":"IT", "recipientType": "GROUP", "responseCountThreshold" : 3 } ] |
senderOverrides | SenderOverrides |
optional | Provides notification override options that help recipients identify the source of notifications. |
targetAllDevices | Boolean |
When true, notifications target all types of devices in the system. This value cannot be set to true when the targetDeviceNames field is also true. See note. | |
targetDeviceNames | array [DeviceName object] |
Defines the devices that are targeted by notifications. When values are provided for this field, targetAllDevices cannot be set to true. See note. |
RESPONSES
Success | Response code 202 Accepted and a request identifier in the response body. You can use the request identifier with GET /events to search for events triggered by the integration. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Add a comment to an event
Add a comment to an event
REQUEST
curl --user username --header "Content-Type: application/json" --request POST -d '{
"comment": "Looking into the problem"
}' "https://acmeco.xmatters.com/api/xm/1/events/fcf9192d-a647-4e16-b9e2-1768de421e08/annotations"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/events/fcf9192d-a647-4e16-b9e2-1768de421e08/annotations",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.comment = 'Looking into the problem';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Comment added to event ID = "+ json.event.id ": " + json.comment);
}
#The following code is formatted to work with Python v.3.6 and later.
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/events/fcf9192d-a647-4e16-b9e2-1768de421e08/annotations'
headers = {'Content-Type': 'application/json'}
auth = HTTPBasicAuth('username', 'password')
data = {'comment':'Looking into the problem.'}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if (responseCode == 201):
rjson = response.json();
print('The request succeeded:\n ' + json.dumps(rjson, indent=4, sort_keys=True) )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"id": "d0ce6c39-51ff-4c04-a379-478bf074b2c7",
"event": {
"id": "fcf9192d-a647-4e16-b9e2-1768de421e08",
"eventId": "41219002",
"links": {
"self": "/api/xm/1/events/fcf9192d-a647-4e16-b9e2-1768de421e08"
}
},
"author": {
"id": "935600d0-ae51-445c-805a-d38e49b80e96",
"targetName": "monitorx",
"firstName": "monitortoolX",
"lastName": "integration",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/935600d0-ae51-445c-805a-d38e49b80e96"
}
},
"comment": "Looking into the problem",
"created": "2018-04-04T21:11:21.446Z"
}
Adds a comment (or annotation) to an event. The comment appears in the event tracking report and is returned when you request event comments using the GET /audits, GET /event/annotation, and GET /event/annotations endpoints. The authenticating user who posts this request is considered the author of the comment.
DEFINITION
POST /events/{eventId}/annotations
URL PARAMETERS
eventId | string |
The unique identifier or event number of the event you want to add the comment to. Examples:
|
BODY PARAMETERS
comment | string |
The text of the comment you want to add to the event. |
RESPONSES
Success - Comment created | Response code 201 Created and an Annotation object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Change the status of an event
Change the status of an event
REQUEST
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "9102f1c3-b67b-4970-880b-05b2fc566224",
"status": "TERMINATED"
}' "https://acmeco.xmatters.com/api/xm/1/events"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/events/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '9102f1c3-b67b-4970-880b-05b2fc566224';
data.status = 'TERMINATED';
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Terminated event. ID = "+ json.id);
}
#The following code is formatted to work with Python v.3.6 and later.
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/events'
headers = {'Content-Type': 'application/json'}
auth = HTTPBasicAuth('username', 'password')
data = {'id':'9102f1c3-b67b-4970-880b-05b2fc566224', 'status':'TERMINATED' }
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if (responseCode == 200):
print('The request succeeded. The event status was not changed.')
elif (responseCode == 202):
print('The request succeeded. HTTP response code 202 was received.')
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"id": "9102f1c3-b67b-4970-880b-05b2fc566224",
"submitter":
{
"id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
"targetName": "monitoringtool",
"firstName": "MonitoringTool",
"lastName": "Integration",
"recipientType": "PERSON",
"links":
{
"self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
}
},
"priority": "MEDIUM",
"incident": "INCIDENT_ID-981002",
"overrideDeviceRestrictions": false,
"escalationOverride": false,
"bypassPhoneIntro": false,
"requirePhonePassword": false,
"eventId": "981002",
"created": "2017-03-01T21:11:49.742+0000",
"status": "TERMINATED",
"links": {
"self": "/api/xm/1/events/9102f1c3-b67b-4970-880b-05b2fc566224"
}
}
This endpoint allows you to suspend, resume, or terminate an event.
- Suspending an event pauses it temporarily and prevents xMatters from sending new notifications. Users can still respond to notifications that were sent by a suspended event.
- Resuming a suspended event restarts it from the point at which it was initially suspended.
- Terminating an event stops the event processing and removes active notifications from the system. Terminated events cannot be resumed.
The status of the event is the only event property that can be modified after an event has been initiated.
DEFINITION
POST /events
BODY PARAMETERS
id | string |
The unique identifier or event number of the event to suspend, resume, or terminate. Examples:
Note: 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 user interface. |
|
status | string |
The new status of the event. Valid values include the following:
|
RESPONSES
Success - Status changed | Response code 202 ACCEPTED and an Event object in the response body. |
Success - Status unchanged | Response code 200 OK and an Event object in the response body. This indicates that the request was successful but the status of the event did not change, such as when you request to terminate an already-terminated event. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Event objects
Event object
Event object
{
"id":"ced9fac9-1065-4659-82ab-1c9664a777b2",
"name":"SQL Database outage",
"eventType": "USER",
"plan": {
"id": "c56730a9-1435-4ae2-8c7e-b2539e635ac6",
"name": "Database monitoring"
},
"form":
{
"id":"ef62b6ac-ba7e-40e8-9253-a837efcd38ea",
"name" : "Database Outage"
},
"floodControl" : "false",
"submitter":
{
"id":"661f3f18-75ab-44fd-a22a-4bb0fe15917e",
"targetName":"mmcbride",
"firstName":"Mary",
"lastName":"Mcbride",
"recipientType":"PERSON",
"links":
{
"self":"/api/xm/1/people/661f3f18-75ab-44fd-a22a-4bb0fe15917e"
}
},
"recipients":
{
"count":1,
"total":1,
"data": [
{
...truncated Recipient object...
}],
},
"priority":"MEDIUM",
"annotations": {
"count": 1,
"total": 1,
"data": [
{
"id": "f223698e-dbd0-4089-a4c3-e6b7c76c639d",
"event":
{
"id": "ced9fac9-1065-4659-82ab-1c9664a777b2",
"eventId": "408005",
"links":
{
"self": "/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2"
}
},
"author":
{
"id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
"targetName": "admin",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links":
{
"self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
}
},
"comment": "I can help out.",
"created": "2016-10-31T22:17:31.450Z"
}
]
},
"incident":"INCIDENT_ID-408005",
"expirationInMinutes":180,
"eventId":"408005",
"created":"2016-10-31T22:37:35.301+0000",
"terminated":"2016-10-31T22:38:40.063+0000",
"status":"TERMINATED_EXTERNAL",
"otherResponseCount" : 2,
"otherResponseCountThreshold" : 1,
"conference": {
"bridgeId":"67955226",
"type":"BRIDGE"
},
"responseOptions": {
"count":2,
"total":2,
"data": [
{
"id":"b1697b84-c0cf-412c-b956-af810cd86bae",
"number":1,
"text":"Join",
"description":"Join",
"prompt":"I will join the conference bridge",
"action":"RECORD_RESPONSE",
"contribution":"NONE",
"joinConference":true,
"allowComments": false
},
{
"id": "1ea8906f-be05-410d-9077-fa7587d7b626",
"number":2,
"text":"Reject",
"description":"Reject",
"prompt":"I cannot assist",
"action":"STOP_NOTIFYING_USER",
"contribution":"NONE",
"joinConference":false,
"allowComments": true,
"translations": {
"count": 3,
"total": 3,
"data": [
{
"id": "046fd6e9-06a3-4350-acce-f672124b6484",
"language": "hi",
"text": "ठीक",
"description": "ठीक"
},
{
"id": "fb747f5b-10c8-48a9-9f3f-a679d2090963",
"language": "fr",
"text": "d'accord",
"prompt": "",
"description": "d'accord"
},
{
"id": "1775b40f-07b2-45cd-8a05-b140286081d9",
"language": "zh_CN",
"text": "同意"
}
]
}
}]
},
"properties":
{
"myNumberProperty": 323423,
"myPasswordProperty": "ilovecats123",
"myTextProperty#en": "This is urgent. Please respond.",
"myListProperty": [
"iOS",
"Android",
"Windows 10"
],
"myBooleanProperty": true,
"myComboProperty": "Oracle Database",
"myHierarchyProperty": [
{
"category": "Country",
"value": "USA"
},
{
"category": "State",
"value": "WA"
},
{
"category": "City",
"value": "Seattle"
}
]
},
"messages": {
"count": 1,
"total": 1,
"data": [
{
"id": "e3d4e459-732d-4b4f-8f85-159ec25db729",
"messageType": "SUBJECT_AND_BODY",
"subject": "Outage in NOC 4",
"body": "<div><span style=\"white-space: nowrap;"\>[First Name] [Last Name] - a new task was assigned to you</span></div><span style=\"white-space: nowrap;"\>Description:</span><div><span style=\"white-space: nowrap;"\>Please investigate the reported outage.</span></div><div><span style=\"white-space: nowrap;"\><br></span></div><div><span style=\"white-space: nowrap;"\>https://servicedesk.example.com/90834903q095</span></div>"
}]
}
}
The Event object describes information about an xMatters event including the form and response choices, conference bridge information, the event initiator, and up to 100 directly-targeted recipients of the event.
annotations | Pagination of Annotation objects |
The comments that were made when users responded to a notification. This field contains only the first page of results (up to 100 messages). This object is included when ?embed=annotations is included in the request. |
|
bypassPhoneIntro | Boolean |
When this value is set to true, xMatters omits the standard greeting and plays the message immediately. | |
created | string |
The date and time the event was initiated (in UTC format). | |
conference | Conference object |
Describes the conference bridge used with this event. | |
escalationOverride | Boolean |
When this value is set to true, xMatters ignores shift escalation delays and sends an immediate broadcast message to all recipients. | |
eventId | string |
The integer identifier used to identify this event in the xMatters user interface. | |
eventType | string |
The type of event:
|
|
expirationInMinutes | integer |
The number of minutes the event is active before it terminates. | |
floodControl | Boolean |
True if some notifications were not delivered because notification flood control was activated for this event. Because the event is created before notifications are sent, this value will always be FALSE when an event is first created. Once notifications are generated and sent, the value is set to TRUE if any notifications are subject to flood control. |
|
plan | PlanReference object |
The communication plan that triggered the event. | |
form | FormReference object |
The form that triggered the event. | |
id | string |
The unique identifier of this event. | |
incident | string |
The incident ID of the event. | |
messages | Pagination of Messages object |
The messages sent for the event. This field contains only the first page of results (up to 100 messages). This object is included when ?embed=messages is included in the request. |
|
overrideDeviceRestrictions | Boolean |
When this value is set to true, xMatters ignores device timeframes and delays. This allows users to be notified on any device at any time, regardless of their preferences. | |
otherResponseCount | string |
For events that count responses, this represents the number of responses recieved by users counted as ‘others’. When this value is greater than or equal to the otherResponseCountThreshold field, then the response counts (fill counts) for 'others’ is considered to be met. |
|
otherResponseCountThreshold | string |
For events that count responses, this represents the number of responses from users counted as 'others’ required before the event stops sending notifictations to more other users. | |
priority | string |
The priority of the event. Use one of the following values:
|
|
properties | Properties object |
The properties of the form. Use these to look up the event’s message details. This object is included when ?embed=properties is included in the request. |
|
recipients | Pagination of Recipient object |
The recipients of the event. This field contains only the first page of results (up to 100 recipients). This object is included when ?embed=recipients is included in the request. |
|
requirePhonePassword | Boolean |
When this value is true, the recipient must enter their phone password before a voice notification is played. This option cannot be used with options to leave the message content as voicemail. | |
responseCountsEnabled | Boolean |
True if the event is configured to count responses. | |
responseOptions | ResponseOptions object |
The response options sent as part of the notification. This object is included when ?embed=responseOptions is included in the request. Returns the response in the user’s original language when the request includes ?embed=responseOptions,responseOptions.translations . Translations are not currently available for historical data. |
|
submitter | PersonReference object |
The user who initiated the event. | |
status | string |
The current status of this event. Use one of the following values:
|
|
suppressions | Event Suppression object |
A list of any suppressions of this event as a result of an event flood control rule. | |
terminated | string |
The date and time the event was terminated (in UTC format). This field is only present for terminated events. | |
voicemailOptions | VoicemailOptions object |
For voice notifications, this defines whether to try the call again or leave a message. |
EventReference object
EventReference object
{
"id": "a7ab8012-0583-4e5b-a5dd-36f67ec016f3",
"eventId": "1562001",
"links":
{
"self": "/api/xm/1/events/a7ab8012-0583-4e5b-a5dd-36f67ec016f3"
}
}
An EventReference object contains a reference to an event.
id | string |
The unique identifier of the event. | |
eventId | string |
The numeric identifier of the event as displayed in the event report. | |
links | SelfLink object |
A link that can be used to access the event. |
FormReference object
FormReference object
{
"id":"ef62b6ac-ba7e-40e8-9253-a837efcd38ea",
"name" : "Database Outage"
}
Describes a reference to a form, including its name and unique identifier.
id | string |
The unique identifier of the form. | |
name | string |
The name of the form. |
Conference object
Conference object
{
"bridgeId":"67955226",
"bridgeNumber": "67955226",
"type":"BRIDGE"
}
The Conference object describes xMatters-hosted and externally-hosted conference bridges associated with an event. See ConferencePointer object for information on the conference object when triggering an event.
id | string |
The unique identifier of the conference bridge. Returned only for xMatters-hosted conference bridges. | |
bridgeId | string |
For xMatters-hosted bridges, this field contains the xMatters bridge number. For externally-hosted conference bridges, this field contains the name of the external conference bridge. | |
bridgeNumber | string |
For xMatters-hosted bridges, this field repeats the xMatters bridge number. For externally-hosted conference bridges, this field contains the static or dynamic number of the external conference bridge (the number that identifies the conference to the conference bridge provider). | |
type | string |
Whether the conference bridge is an xMatters-hosted conference bridge or hosted by a third-party provider. Use one of the following values:
|
Properties object
Properties object
{
"myNumberProperty": 323423,
"myPasswordProperty": "ilovecats123",
"myTextProperty#en": "Please respond.",
"myListProperty":
[
"iOS",
"Android",
"Windows 10"
],
"myBooleanProperty": true,
"myComboProperty": "Oracle Database",
"myHierarchyProperty":
[
{
"category": "Country",
"value": "USA"
},
{
"category": "State",
"value": "WA"
},
{
"category": "City",
"value": "Seattle"
}
]
}
The Properties object contains information about the event’s form properties.
By inspecting form properties you can extract message details and use them with other systems in your toolchain, for example, you could extract a ticket number from an event and then use it to close a ticket in your service desk system.
The names of fields in the Properties object correspond to the names of the actual form properties and are unique for every form.
The following table shows the example format of each property type:
Property Type | Description | Example |
---|---|---|
Number | An integer. | "myNumberProperty": 323423 |
Text | A string. Text property names include the language code. | "myTextProperty#en": "Please respond." |
Password | A string in plain text. | "myPasswordProperty": "ilovecats123" |
List | An array of strings that represent the selected choices. | "myListProperty": [
"listItem1", |
Boolean | A Boolean value. | "myBooleanProperty" : true |
Combo Box | A string that represents the selected choice. | "myComboProperty": "Oracle Database" |
Hierarchy | An array of objects that include category and value fields that represent each level of the hierarchy of the selected value. |
"myHeirarchyProperty"[ |
VoicemailOptions object
VoicemailOptions object
"voicemailOptions":
{
"retry": 0,
"every": 60,
"leave": "callbackonly"
}
Voicemail Options settings configure the handling behavior for standard phone notifications and conference calls when voicemail is detected.
retry | integer |
optional | The number of times to attempt to contact the user after reaching voicemail on the initial attempt. |
every | integer |
optional | The number of seconds to wait between retry attempts. |
leave | string |
optional | The action to take when voicemail is detected and there are no more retry attempts. Valid values include (web user interface equivalent in brackets):
|
ResponseOptions object
ResponseOptions object
Example: Configure response options. This example shows how to choose an existing response, modify an existing response, and create a new response
"responseOptions" :
[
{
"id" : "fee39ecf-75a7-45eb-9e63-ffc441499c4f"
},
{
"id" : "085d4bea-9dfb-4d2b-8136-22e19b1baaf6",
"redirectUrl" : "https://jira.example.com/view/INCD-2933",
"contribution": "POSITIVE",
"action": "STOP_NOTIFYING_TARGET"
},
{
"number": 3,
"text": "Reject",
"description": "I cannot help",
"prompt": "Reject",
"action": "RECORD_RESPONSE",
"contribution": "NEGATIVE",
"joinConference": true,
"allowComments": false,
"redirectUrl": "https://jira.example.com/",
"translations": {
"count": 3,
"total": 3,
"data": [
{
"id": "046fd6e9-06a3-4350-acce-f672124b6484",
"language": "hi",
"text": "ठीक",
"description": "ठीक"
},
{
"id": "fb747f5b-10c8-48a9-9f3f-a679d2090963",
"language": "fr",
"text": "d'accord",
"prompt": "",
"description": "d'accord"
},
{
"id": "1775b40f-07b2-45cd-8a05-b140286081d9",
"language": "zh_CN",
"text": "同意"
}
]
}
}
]
The ResponseOptions object describes the response options for the event. You can use it to display the form’s existing responses, override properties of existing responses, create new responses, or see the response in the user’s original language. You can configure all parts of the response except for translations and voice recordings.
id | string |
The unique identifier of the response to select. To use a response as it is defined on the form, include the id field and do not provide any other values. To use an existing response and modify part of it, include the id field and the fields you want to modify. To create a new response, omit the id field and provide the remaining fields. |
|
number | integer |
The keypad digit to press when responding to a voice notification. | |
text | string |
Specifies how the response choice is displayed on text devices and the mobile app, and how the link appears in email responses. Corresponds to the Response field in the web interface. | |
description | string |
Allows you to specify a longer description of the response choice to be included in emails. Corresponds to the Email Description field in the web user interface. | |
prompt | string |
The text that is used with Text-To-Speech when delivering a voice notification. Corresponds to the Voice Prompt field in the web user interface. | |
action | string |
If the form is not configured to count responses, valid values include:
|
|
contribution | string |
Describes whether to count the response as positive, negative, or neutral for reporting purposes. Valid values include:
|
|
joinConference | Boolean |
When this is true, choosing the response from a voice notification automatically connects the responder to the conference bridge. | |
allowComments | Boolean |
When this is true, the recipient is given the option to add comments when they select this response option. When this is false, they’re not able to add comments when they respond. | |
redirectUrl | string |
An HTTP or HTTPS URL associated with the response option. When the user responds with this choice from email, mobile apps, or the web user interface, they are automatically redirected to this URL. For example, you can use this to open a service desk ticket related to the incident or direct people to a chat room where they can discuss the issue. | |
translations | string |
The original language of the user’s response. The two-letter code used in the language field adheres to ISO 639 standards. Translations are not available for historical data. For more information, see Languages in the online help. |
ConferencePointer object
ConferencePointer object
Example: New xMatters-hosted conference bridge
"conference":
{
"type": "BRIDGE"
}
Example: In-progress xMatters-hosted conference bridge
"conference":
{
"bridgeId": "3882920",
"type": "BRIDGE"
}
Example: Externally-hosted conference bridge with a static bridge number
"conference":
{
"bridgeId": "Corporate WebEx",
"type": "EXTERNAL"
}
Example: Externally-hosted conference bridge with a dynamic bridge number
"conference":
{
"bridgeId": "Corporate WebEx",
"type": "EXTERNAL",
"bridgeNumber": "88737396"
}
If the form contains a conference section, you can use this section to configure the conference bridge.
If the form is configured to use xMatters-hosted conference bridges, you choose to use an in-progress xMatters conference bridge or to create a new one. You can also select an externally-hosted conference bridge if the form is configured to allow them.
If you do not specify a conference bridge, the event will either use a new xMatters-hosted conference bridge or will return an error if the form is only configured to allow externally-hosted bridges.
See Conference object for information on the conference object in GET /events results.
bridgeId | string |
The name or ID of the bridge.
|
|
type | string |
The type of bridge. Use one of the following values:
|
|
bridgeNumber | string |
The number that identifies the conference to the conference bridge provider. Use only when triggering an externally-hosted conference bridge with a dynamically set bridge number. |
PropertyValues object
PropertyValues object
"properties" :
{
"myBooleanProperty" : false,
"myNumberProperty": 22183,
"myTextProperty" : "See the attached evacuation route map.",
"myListProperty" : ["Grocery", "Automotive", "Seasonal"],
"myComboProperty" : "Shelter in place.",
"myPasswordProperty" : "e293Usf@di",
"myHeirarchyProperty" : [
{"category" : "country", "value": "USA"},
{"category" : "state", "value" : "California"}
{"category" : "city", "value" : "Los Angeles"}
]
}
Sets the values of the form properties.
The names of the properties are unique to each communication plan and form. Depending on how the form is configured, these properties may have minimum and maximum values or other restrictions. Refer to your form in the xMatters user interface to see how the properties are configured.
You must provide values for mandatory form fields that are not configured to use default values. All other form fields are optional.
Property Type | Definition |
---|---|
Boolean | Boolean |
Use true or false .Examples: "EOCActivated" : false "updateRequired" : true |
|
Number | integer |
A whole number. Write negative numbers using the - character. Examples: "severity" : 3 "rating" : -2 |
|
Text | string |
A string that represents the text property. | |
List | array [string] |
Provide an array of string values that represent one or more list box selections. Examples: "Affected Locations" : ["Seattle", "Portland"] "Department" : ["Accounting"] |
|
Combo Box | string |
A string that represents a single selection in a combo box field. Examples: "Severity" : "LOW" |
|
Password | string |
A string representation of a password Examples: "password" : "38se*#Ehww1" |
|
Heirarchy | array [objects] |
Provide an array of objects that define a value for each level of the hierarchy. Each object defines the selection using two key/value pairs: thecategory field defines the name of the level and the value field defines the selection. The following example shows how to select a value from a Country > State > City heirarchy. Example: "region" : [ {"category" : "Country", "value" : "USA"}, {"category" : "State", "value" : "California"}, {"category" : "City", "value" : "Los Angeles"} ] |
Recipient Trigger
Recipient Trigger object
"recipients" :
[
{"id":"mmcbride", "recipientType": "PERSON"},
{"id":"bfdbcb31-d02e-4a4f-a91c-7d68fbe416df", "recipientType": "PERSON"},
{"id":"mmcbride|Work Email", "recipientType": "DEVICE"},
{"id":"4a0fdfb4-7c49-4581-9cd9-804f2956e19b", "recipientType": "DEVICE"},
{"id":"Executives", "recipientType": "GROUP"},
{"id":"f19d8b10-923a-4c23-8348-06ced678075e", "recipientType": "GROUP", "responseCountThreshold" : 3},
{"id":"First Aid Attendants", "recipientType": "DYNAMIC_TEAM", "responseCountThreshold" : 1},
{"id":"ed2606c5-ef2b-4ce8-9259-d5cdacd5bd90", "recipientType": "DYNAMIC_TEAM"}
]
This is the format for specifying recipients when triggering an event. If your form is configured to count responses, you can include the response count (fill count) for each group or dynamic team recipient.
id | string |
The target name or unique identifier of the recipient. | |
recipientType | string |
optional | The type of recipient. It is recommended to provide the recipient type to increase the performance of triggering an event. Value values include the following:
|
responseCountThreshold | integer |
When a form uses response counts, this value specifies the number of responses that are required before xMatters stops notifying the remaining members of a group or dynamic team. This value applies only to group and dynamic team recipients. |
Annotation Object
Annotation object
{
"count": 1,
"totat": 1,
"data": [
"id": "f223698e-dbd0-4089-a4c3-e6b7c76c639d",
"event": {
"id": "ced9fac9-1065-4659-82ab-1c9664a777b2",
"eventId": "408005",
"links": {
"self": "/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2"
}
},
"author": {
"id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
"targetName": "admin",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
}
},
"comment": "I can help out.",
"created": "2017-10-31T22:17:31.450Z",
"links": {
"self": "/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2/annotations/f223698e-dbd0-4089-a4c3-e6b7c76c639d"
}
}
The annotation object contains the comment that was made and links to the person who made the comment and the event that it applies to.
id | string |
The id of the annotation | |
event | EventReference object |
A link to the event where the comment was made | |
author | PersonReference object |
The person who made the comment | |
comment | string |
The comment that was made on the event. | |
created | string |
The date and time the comment was made. |
Device Name Object
DeviceName object
"targetDeviceNames" : [
{"name" : "Work Email"},
{"name" : "Work Phone"}
{"name" : "Home Email"},
{"name" : "Home Phone"},
{"name" : "SMS Phone"},
{"name" : "Fax"},
{"name" : "Numeric Pager"},
{"name" : "Pager"},
{"name" : "Mobile Phone"},
{"name" : "My custom device name"}
]
A list of the device names to target. These names may be customized for your company but typically include options such as 'Work Email’, 'Work Phone’, 'Home Email’, 'Home Phone’, 'Mobile Phone’, 'SMS Phone’, and so on.
To see the list of device names configured for your system, use GET /device-names or log on to the user interface and create a device.
name | string |
The name of the type of device to target. |
Messages Object
Messages object
"messages":
{
"count": 1,
"total": 1,
"data":
[
{
"id": "e3d4e459-732d-4b4f-8f85-159ec25db729",
"messageType": "SUBJECT_AND_BODY",
"subject": "Outage in NOC 4",
"body": "<div><span style=\"white-space: nowrap;\">[First Name] [Last Name] - a new task was assigned to you</span></div><span style=\"white-space: nowrap;\">Description:</span><div><span style=\"white-space: nowrap;\">Please investigate the reported outage.</span></div><div><span style=\"white-space: nowrap;\"><br></span></div><div><span style=\"white-space: nowrap;\">https://servicedesk.example.com/90834903q095</span></div>"
}
]
The Messages object contains the messages that were sent to recipients as notifications for the event.
id | string |
The unique identifier of the message. | |
messageType | string |
The type of message; valid values are:
|
|
subject | string |
The subject of the email or mobile app message. | |
body | string |
The source code (in HTML) of the email or mobile app message body. |
User Delivery Data Object
User Delivery Data Object
{
"count": 1,
"total": 1,
"data": [
{
"event": {
"id": "7af4cab7-5301-4156-9d9e-33983a7f2b18",
"eventId": "24721002",
"links": {
"self": "/api/xm/1/events/7af4cab7-5301-4156-9d9e-33983a7f2b18?at=2019-11-13T21:48:51Z"
}
},
"person": {
"id": "bc434d9d-a9a9-4b6d-8520-dc9adce0c57f",
"targetName": "thanks",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/bc434d9d-a9a9-4b6d-8520-dc9adce0c57f?at=2019-11-13T21%3A48%3A51Z"
},
"firstName": "Tom",
"lastName": "Hanks",
"site": {
"id": "87165184-f025-46ec-bc8e-11314b4ddeb5",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/87165184-f025-46ec-bc8e-11314b4ddeb5?at=2019-11-13T21%3A48%3A51Z"
}
},
"properties": {
"isFirstAid": [
"true"
],
"isCPR": [
"true"
],
"firstAidLevel": [
"1"
],
"location": [
"Denver office"
],
}
},
"deliveryStatus": "RESPONDED",
"notifications": {
"count": 1,
"total": 1,
"data": [
{
"id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6",
"category": "DEVICE",
"recipient": {
"id": "32d54bb4-9b3e-438b-bb9f-ea6060f5092b",
"targetName": "1st Aid Email",
"recipientType": "DEVICE",
"deviceType": "EMAIL",
"name": "",
"links": {
"self": "/api/xm/1/devices/32d54bb4-9b3e-438b-bb9f-ea6060f5092b?at=2019-11-13T21%3A48%3A51Z"
}
},
"deliveryStatus": "RESPONDED",
"deliveryAttempted": "2019-11-12T16:54:14.918Z",
"responses": {
"count": 2,
"total": 2,
"data": [
{
"text": "On my way - be there in 5 minutes.",
"notification": {
"id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6"
},
"received": "2019-11-12T16:54:37.656+0000"
},
{
"text": "First aid attendant unavailable - call 911.",
"notification": {
"id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6"
},
"received": "2019-11-12T16:54:31.328+0000"
}
]
},
"delivered": "2019-11-12T16:54:15.789Z",
"responded": "2019-11-12T16:54:31.328Z"
}
]
},
"response": {
"text": "On my way - be there in 5 minutes",
"notification": {
"id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6"
},
"received": "2019-11-12T16:54:37.656+0000"
}
}
],
"links": {
"self": "/api/xm/1/events/24721002/user-deliveries?limit=100&at=2019-11-13T21%3A48%3A51Z&embed=person.properties&offset=0"
}
}
This object describes notifications for Group
and Device
recipient types. Notifications for group recipients indicate which groups the user was part of. Notifications for devices indicate which user devices were targeted for messages.
event | EventReference object |
The event that triggered the notifications. | |
person | PersonReference object |
The user who received the notification. | |
deliveryStatus | string |
A consolidated status from across all notifications sent to all of a user’s devices based on the most relevant status for an event. For example, a user has four devices and all four are notified of an event. One of the notifications doesn’t reach the device and returns to xMatters as FAILED . The status of the notification (if requested at that moment) would be FAILED . The user receives the notification on the other three devices. The notification status would be DELIVERED if queried at that time. The user responds to the notification on a device and the status is updated to RESPONDED . Valid values include:
|
|
notifications | Notifications object |
A list of the notifications generated for the user. | |
response | User Delivery Response object |
If a user receives notifications to multiple devices, they can respond from each devices that receives the notification. The response field displays the last response received from the user, including the timestamp. |
|
links | SelfLink object |
A link that can be used to access the event. |
Notifications Object
Notifications Object
{
"notifications": {
"count": 1,
"total": 1,
"data": [
{
"id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6",
"category": "DEVICE",
"recipient": {
"id": "32d54bb4-9b3e-438b-bb9f-ea6060f5092b",
"targetName": "1st Aid Email",
"recipientType": "DEVICE",
"deviceType": "EMAIL",
"name": "",
"links": {
"self": "/api/xm/1/devices/32d54bb4-9b3e-438b-bb9f-ea6060f5092b?at=2019-11-13T21%3A48%3A51Z"
}
},
"deliveryStatus": "RESPONDED",
"deliveryAttempted": "2019-11-12T16:54:14.918Z",
"responses": {
"count": 2,
"total": 2,
"data": [
{
"text": "On my way - be there soon.",
"notification": {
"id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6"
},
"received": "2019-11-12T16:54:37.656+0000"
},
{
"text": "Unavailable, call 911.",
"notification": {
"id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6"
},
"received": "2019-11-12T16:54:31.328+0000"
}
]
},
"delivered": "2019-11-12T16:54:15.789Z",
"responded": "2019-11-12T16:54:31.328Z"
}
]
},
This object contains information about the notification that was sent to the users when an event occurred.
id | string |
The unique identifier of this notification. | |
recipient | Recipient object |
The user, group, device or dynamic team in xMatters that can receive notifications. | |
created | string |
The timestamp of when the notification was created. | |
delivered | string |
The timestamp of when the notification was delivered to the user. | |
responded | string |
The timestamp of when the user responded to the notification. | |
deliveryStatus | string |
The status of the delivery. Valid values include:
|
|
responses | string |
A list of the user’s responses, which can include multiple responses from multiple device types. |
User Delivery Response Object
User Delivery Response Object
{
"response": {
"text": "On my way - be there soon",
"notification": {
"id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6"
},
"received": "2019-11-12T16:54:37.656+0000"
}
}
The response object contains information about how a user responded to an event.
text | string |
The text of the response option selected by the user. | |
notification | string |
The unique identifier of the notification. | |
received | string |
The timestamp of when the response was received. |
EVENT SUPPRESSIONS
Event suppressions lets you retrieve the records of any suppressions resulting from event flood control rules for a particular event.
See the online help for more information on event flood control and how to create and edit event flood control rules.
Get suppressed events
Get a list of suppressed events
REQUEST Get the suppressed events of a parent event.
curl --user username "https://acmeco.xmatters.com/api/xm/1/event-suppressions?event=ced9fac9-1065-4659-82ab-1c9664a777b2"
/**
* This script is configured to work within the xMatters Integration Builder.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/event-suppressions?event=ced9fac9-1065-4659-82ab-1c9664a777b2",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " event suppression records for event " + json.data.event.id);
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/event-suppressions"
url = base_URL + endpoint_URL + "?event=ced9fac9-1065-4659-82ab-1c9664a777b2"
username = "myuser"
password = "pa55w0rd"
response = requests.get(url, auth=HTTPBasicAuth(username, password))
if response.status_code == 200:
print("Retrieved " + json.count + " event suppression records for event " + response.json()["id"])
RESPONSE
{
"count": 4,
"total": 4,
"data": [
{
"event": {
"id": "c0c9897e-8b60-4056-84b2-0082d13e48a4",
"eventId": "74959000",
"links": {
"self": "/api/xm/1/events/c0c9897e-8b60-4056-84b2-0082d13e48a4"
}
},
"match": {
"id": "5a3685a8-f254-4766-9994-04b657a63034",
"eventId":"74957000",
"links": {
"self": "/api/xm/1/events/5a3685a8-f254-4766-9994-04b657a63034"
},
"at": "2019-07-08T17:45:44.439Z",
"filters": [
{
"id": "904209f1-ab14-47ff-ba3c-939e856fc3bc",
"name": "Monitoring Tool X Rule"
}
]
},
{
"event": {
"id": "c0c9897e-8b60-4056-84b2-0082d13e48a4",
"eventId": "74959000",
"links": {
"self": "/api/xm/1/events/c0c9897e-8b60-4056-84b2-0082d13e48a4"
}
},
"match": {
"id": "34519906-f90c-4602-b647-c9efc62724eb",
"eventId": "74960000",
"links": {
"self": "/api/xm/1/events/34519906-f90c-4602-b647-c9efc62724eb"
},
"at": "2019-07-08T17:46:16.289Z",
"filters": [
{
"id": "904209f1-ab14-47ff-ba3c-939e856fc3bc",
"name": "Monitoring Tool X Rule"
}
]
},
{...truncated list of event suppressions...}
],
"links": {
"self": "/api/xm/1/event-suppressions?event=c0c9897e-8b60-4056-84b2-0082d13e48a4&offset=0&limit=100"
}
}
Returns records of suppressions related to an event, including information on the parent event and the event flood control rule (filter) that resulted in the suppression.
DEFINITION
GET /event-suppressions?event={eventId}
QUERY PARAMETERS
event | string |
required | The unique identifier of the event you want to retrieve suppressions for. Example: “24abd4c0-bff3-4381-9f84-678580b24428” To find the UUID for an event, use GET /events. |
sortBy | string |
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 include:
|
|
sortOrder | string |
Specifies whether events are sorted in ascending or descending order. This parameter must be used in conjunction with the sortBy query parameter. Valid values include:
|
|
offset |
integer |
The number of items to skip before returning results. See Pagination query parameters. | |
limit | integer |
The number of items to return. See Pagination query parameters. |
RESPONSES
Success | Response code 200 OK and a Pagination of Event Suppression objects in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Event Suppression objects
Event Suppression object
Event Suppression object
Example
{
"event": {
"id": "dadd243e-ad70-4962-8ad7-5431d6faede5",
"eventId": "74959000",
"links": {
"self": "/api/xm/1/events/dadd243e-ad70-4962-8ad7-5431d6faede5"
}
},
"match": {
"id": "22d38c42-551e-4333-aa80-d81df12f33f8",
"eventId": "74957000",
"links": {
"self": "/api/xm/1/events/22d38c42-551e-4333-aa80-d81df12f33f8"
}
},
"at": "2019-10-17T19:20:30.951Z",
"filters": [
{
"id": "f6888e78-5dbb-49fa-aa86-e9cceb252b04",
"name": "Monitoring Tool X Rule"
}
]
}
The Event Suppression object provides information on a suppression for an event, including information on the parent event and the rule that resulted in the suppression.
event | EventReference object |
A reference to the parent event of the suppression. | |
match | SuppressionMatch object |
A reference to the suppression. | |
at | string |
The date and time the suppression occurred (in UTC format). | |
filters | Event Flood Filter object |
A reference to the rule (filter) that resulted in the suppression. | |
links | SelfLink object |
A link that can be used to reference the list of event suppressions. |
SuppressionMatch object
SuppressionMatch object
"match": {
"id": "22d38c42-551e-4333-aa80-d81df12f33f8",
"eventId": "74957000",
"links": {
"self": "/api/xm/1/events/22d38c42-551e-4333-aa80-d81df12f33f8"
}
}
Describes the record of an event suppression.
id | string |
The unique identifier of the suppression. | |
eventId | string |
The event ID of the suppression. | |
links | SelfLink object |
A link that can be used to reference the suppression. |
Event Flood Filter object
Event Flood Filter object
"filters": [
{
"id": "f6888e78-5dbb-49fa-aa86-e9cceb252b04",
"name": "Monitoring Tool X Rule"
}
]
Describes the event flood control rule (filter) that resulted in the suppression. See the online help for more information on event flood control rules.
id | string |
The unique identifier of the rule. | |
name | string |
The user-defined name of the rule. |
FORMS
The linked methods let you work with communication plan forms.
Communication plan forms define the messages that are sent to recipients.
We’ve renamed “communication plans” to “workflows” and are working to update the xMatters REST API guide to reflect those changes. For the time being, xMatters REST API items such as plans
, forms
, constants
, endpoints
, subscriptions
, and integrations
still contain references to plans and communication plans both in their text and code samples.
Get forms
GET forms used by communication plans
REQUEST
curl --user username "https://acmeco.xmatters.com/api/xm/1/forms"
/**
* This script is configured to work within the xMatters Integration Builder.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms"
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " forms." );
for (var d in json.data ) {
var dd = json.data[d];
console.log("\nForm name: " + dd.name + ". Form id: " + dd.id);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/forms?embed=recipients,scenarios"
url = base_URL + endpoint_URL + "&offset=0&limit=2"
auth = HTTPBasicAuth("username", "password")
print("Sending request to url: " + url)
response = requests.get(url, auth=auth)
if response.status_code == 200:
rjson = response.json()
print("Retrieved " + str(rjson["count"]) + " of " + str(rjson["total"]) + " forms.")
for d in rjson["data"]:
print("Found form with id: " + d["id"] + "\tand name " + d["name"])
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
print(
"The request did not succeed. Response code is: "
+ str(response.status_code)
+ "\n"
+ str(response)
)
RESPONSE
{
"count": 3,
"total": 3,
"data": [
{
"id": "7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a",
"formId": "123456",
"name": "IT Alert",
"description": "Notify users when an IT Alert is triggered",
"mobileEnabled": false,
"uiEnabled": false,
"apiEnabled": true,
"senderOverrides": {
"displayName": "PM TESTING",
"callerId": "+12505551234"
},
"plan": {
"id": "95fe8fbb-e095-4845-beb2-15d56829627b",
"name": "IT Administration"
},
"links": {
"self": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a"
}
}
},
{ ... truncated list of forms ... },
"links": {
"self": "/api/xm/1/forms?offset=0&limit=100"
}
Returns a list of forms in the company in xMatters. Depending on your permission level, you will see either a subset of information or all form information.
DEFINITION
GET /forms
GET /forms?search=IT&fields=DESCRIPTION
GET /forms?embed=recipients,scenarios
GET /forms?sortBy=NAME&sortOrder=ASCENDING
QUERY PARAMETERS
search | string |
A list of search terms separated by a space. The results include forms with the search term in either the NAME or DESCRIPTION fields. Searches are case-insensitive (“alert” finds “alert”, “Alert”, as well as “alerting”) and must contain at least two characters. |
|
fields | string |
Defines the fields to search when a search term is specified. Valid values include:
|
|
embed | string |
A comma-separated list of the objects to embed in the response.
|
|
sortBy | string |
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 include:
|
|
sortOrder | string |
Specifies whether forms are sorted in ascending or descending order. This parameter must be used in conjunction with the sortBy query parameter. Valid values include:
|
|
offset |
integer |
The number of items to skip before returning results. See Pagination query parameters. | |
limit | integer |
The number of items to return. See Pagination query parameters. |
RESPONSES
Success | Response code 200 OK and a pagination of Form objects in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get forms in a plan
GET communication plan forms
REQUEST (get the forms in a communication plan and include the available response options and pre-configured recipients)
curl --user username "https://acmeco.xmatters.com/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms?embed=responseOptions,recipients"
/**
* This script is configured to work within the xMatters Integration Builder.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms?embed=responseOptions,recipients"
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " forms." );
for (var d in json.data ) {
var dd = json.data[d];
console.log("\nForm name: " + dd.name + ". Form id: " + dd.id);
var responseOptions = dd.responseOptions.data;
for (var i in responseOptions)
{
console.log("Option " + responseOptions[i].number + ": " + responseOptions[i].text);
}
var recipients = dd.recipients.data;
for (var i in recipients)
{
console.log(recipients[i].targetName);
}
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
planId = "95fe8fbb-e095-4845-beb2-15d56829627b"
endpoint_URL = "/plans/" + planId + "/forms?embed=recipients,responseOptions,scenarios"
url = base_URL + endpoint_URL + "&offset=0&limit=2"
auth = HTTPBasicAuth("username", "password")
print("Sending request to url: " + url)
response = requests.get(url, auth=auth)
if response.status_code == 200:
rjson = response.json()
print("Retrieved " + str(rjson["count"]) + " of " + str(rjson["total"]) + " forms.")
for d in rjson["data"]:
print("Found form with id: " + d["id"] + "\tand name: " + d["name"])
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
print(
"The request did not succeed. Response code is: "
+ str(response.status_code)
+ "\n"
+ str(response)
)
RESPONSE
{
"count": 3,
"total": 3,
"data": [
{
"id": "7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a",
"formId": "123456",
"name": "IT Alert",
"description": "Notify users when an IT Alert is triggered",
"mobileEnabled": false,
"uiEnabled": false,
"apiEnabled": true,
"senderOverrides": {
"displayName": "PM TESTING",
"callerId": "+12505551234"
},
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "d84a8bb5-a924-4d09-936c-5e5e5c0c351c",
"targetName": "ITAdmin",
"recipientType": "GROUP",
"externallyOwned": false,
"allowDuplicates": true,
"useDefaultDevices": true,
"observedByAll": true,
"links": {
"self": "/api/xm/1/groups/d84a8bb5-a924-4d09-936c-5e5e5c0c351c"
}
}
],
"links": {
"self": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a/recipients?offset=0&limit=100"
}
},
"plan": {
"id": "95fe8fbb-e095-4845-beb2-15d56829627b"
},
"responseOptions": {
"count": 3,
"total": 3,
"data": [
{
"id": "499e4a9b-bb2c-40a0-a01b-2bdfedb686b3",
"number": 1,
"text": "Acknowledge",
"description": "Acknowledge",
"prompt": "Acknowledge",
"action": "ASSIGN_TO_USER",
"contribution": "POSITIVE",
"joinConference": false,
"allowComments": true
},
{
"id": "711bf401-53ba-4c0b-8d94-c59641a13ba2",
"number": 2,
"text": "Escalate",
"description": "Stop Notifying For This Event",
"prompt": "Escalate to next on-call",
"action": "ESCALATE",
"contribution": "NEGATIVE",
"joinConference": false,
"allowComments": true
},
{
"id": "58fc3366-bdff-43bc-8b6b-a8a3e849735e",
"number": 3,
"text": "End",
"description": "Terminate and stop notifying",
"prompt": "Terminate event",
"action": "END",
"contribution": "NEUTRAL",
"joinConference": false,
"allowComments": true
}
],
"links": {
"self": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a/response-options?offset=0&limit=100"
}
},
"links": {
"self": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a"
}
},
{ ... truncated list of forms ... },
"links": {
"self": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms?offset=0&limit=100"
}
}
Returns a list of the forms in a communication plan. You can embed the response options available for the form, and include any recipients set in the form. Depending on your permission level, you will see either a subset of information or all form information.
DEFINITION
GET /plans/{planId}/forms
GET /plans/{planId}/forms?embed=responseOptions,recipients,scenarios
GET /plans/{planId}/forms?sortBy=NAME,USER_DEFINED&sortOrder=ASCENDING
URL PARAMETERS
planId | string |
The unique identifier (uuid) or name (targetName) of the plan the forms belong to. Names must be URL-encoded. |
QUERY PARAMETERS
embed | string |
Use embed to list additional objects to include in the response.
|
|
sortBy | string |
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 include:
|
|
sortOrder | string |
Specifies whether forms are sorted in ascending or descending order. This parameter must be used in conjunction with the sortBy query parameter. Valid values include:
|
|
offset |
integer |
The number of items to skip before returning results. See Pagination query parameters. | |
limit | integer |
The number of items to return. See Pagination query parameters. |
RESPONSES
Success | Response code 200 OK and a pagination of Form objects in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a form in a plan
GET a communication plan form
REQUEST (get a form in a communication plan, including response options and recipients)
curl --user username "https://acmeco.xmatters.com/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a?embed=responseOptions,recipients"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a?embed=responseOptions,recipients",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved form " + json.name + " with id " + json.id + "." );
for (var d in json.data ) {
var responseOptions = responseOptions.data;
for (var i in responseOptions)
{
console.log("Option " + responseOptions[i].number + ": " + responseOptions[i].text);
}
var recipientList = recipients.data;
for (var i in recipientList)
{
console.log(recipientList[i].targetName);
}
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
planId = "568914c3-e08d-412f-b0ad-72a8eee3dc99"
formId = "9282f304-9a7f-418c-8d52-96875b18939b"
endpoint_URL = "/plans/" + planId + "/forms/" + formId + "?embed=responseOptions"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
print("Sending request to url: " + url)
response = requests.get(url, auth=auth)
if response.status_code == 200:
rjson = response.json()
print("\nResponse options are:")
for rd in rjson["responseOptions"]["data"]:
print(
"\n Option "
+ str(rd["number"])
+ ': "'
+ rd["text"]
+ '" with action: '
+ rd["action"]
)
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
print(
"The request did not succeed. Response code is: "
+ str(response.status_code)
+ "\n"
+ str(response)
)
RESPONSE
{
"id": "c524d945-8b17-48b4-911e-a21c9c03138b",
"formId": "123456",
"name": "IT Alert",
"description": "Notify users when an IT Alert is triggered",
"mobileEnabled": false,
"uiEnabled": false,
"apiEnabled": true,
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "d84a8bb5-a924-4d09-936c-5e5e5c0c351c",
"targetName": "ITAdmin",
"recipientType": "GROUP",
"externallyOwned": false,
"allowDuplicates": true,
"useDefaultDevices": true,
"observedByAll": true,
"links": {
"self": "/api/xm/1/groups/d84a8bb5-a924-4d09-936c-5e5e5c0c351c"
}
}
],
"links": {
"self": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a/recipients?offset=0&limit=100"
}
},
"plan": {
"id": "95fe8fbb-e095-4845-beb2-15d56829627b"
},
"responseOptions": {
"count": 3,
"total": 3,
"data": [
{
"id": "499e4a9b-bb2c-40a0-a01b-2bdfedb686b3",
"number": 1,
"text": "Acknowledge",
"description": "Acknowledge",
"prompt": "Acknowledge",
"action": "ASSIGN_TO_USER",
"contribution": "POSITIVE",
"joinConference": false,
"allowComments": true
},
{
"id": "711bf401-53ba-4c0b-8d94-c59641a13ba2",
"number": 2,
"text": "Escalate",
"description": "Stop Notifying For This Event",
"prompt": "Escalate to next on-call",
"action": "ESCALATE",
"contribution": "NEGATIVE",
"joinConference": false,
"allowComments": true
},
{
"id": "58fc3366-bdff-43bc-8b6b-a8a3e849735e",
"number": 3,
"text": "End",
"description": "Terminate and stop notifying",
"prompt": "Terminate event",
"action": "END",
"contribution": "NEUTRAL",
"joinConference": false,
"allowComments": true
}
],
"links": {
"self": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a/response-options?offset=0&limit=100"
}
},
"links": {
"self": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a"
}
}
Returns a specific form in a communication plan. You can embed the response options available for the form, and include any recipients set in the form. Depending on your permission level, you will see either a subset of information or all form information.
DEFINITION
GET /plans/{planId}/forms/{formId} GET /plans/{planId}/forms/{formId}/recipients GET /plans/{planId}/forms/{formId}?embed=responseOptions,recipients GET /plans/{planId}/forms/{formId}?embed=responseOptions,responseOptions.translations
URL PARAMETERS
planId | string |
The unique identifier (id) or name (targetName) of the plan the forms belong to. Names must be URL-encoded. | |
formId | string |
The unique identifier (id) or name (targetName) of the form you want to retrieve. Names must be URL-encoded. |
QUERY PARAMETERS
recipients | string |
The targetName or id of users, groups, devices, or dynamic teams that were listed as the default recipient(or recipients) of the form. |
|
embed | string |
A comma-separated list of objects to embed in the response. Available options are:
|
|
offset |
integer |
The number of items to skip before returning results. See Pagination query parameters. | |
limit | integer |
The number of items to return. See Pagination query parameters. |
RESPONSES
Success | Response code 200 OK and a Form object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get form response options
GET details on form response options
REQUEST
curl --user username "https://acmeco.xmatters.com/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a/response-options"
/**
* This script is configured to work within the xMatters Integration Builder.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a/response-options",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved" + json.count + " of " + json.total + " response options." );
for (var i in json.data)
{
console.log("Option " + json.data[i].number + ": " + json.data[i].responseOption);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
planId = "95fe8fbb-e095-4845-beb2-15d56829627b"
formId = "7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a"
endpoint_URL = "/plans/" + planId + "/forms/" + formId + "/response-options"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
print("Sending request to url: " + url)
response = requests.get(url, auth=auth)
if response.status_code == 200:
rjson = response.json()
print(
"Retrieved "
+ str(rjson["count"])
+ " of "
+ str(rjson["total"])
+ " response options."
)
print("\nResponse options are:")
for rd in rjson["data"]:
print(
"\n Option "
+ str(rd["number"])
+ ': "'
+ rd["text"]
+ '" with action: '
+ rd["action"]
)
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
print(
"The request did not succeed. Response code is: " + str(response.status_code)
)
RESPONSE
{
"count": 3,
"total": 3,
"data": [
{
"id": "499e4a9b-bb2c-40a0-a01b-2bdfedb686b3",
"number": 1,
"text": "Acknowledge",
"description": "Acknowledge",
"prompt": "Acknowledge",
"action": "ASSIGN_TO_USER",
"contribution": "POSITIVE",
"joinConference": false,
"allowComments": true
},
{
"id": "711bf401-53ba-4c0b-8d94-c59641a13ba2",
"number": 2,
"text": "Escalate",
"description": "Stop Notifying For This Event",
"prompt": "Escalate to next on-call",
"action": "ESCALATE",
"contribution": "NEGATIVE",
"joinConference": false,
"allowComments": true
},
{
"id": "58fc3366-bdff-43bc-8b6b-a8a3e849735e",
"number": 3,
"text": "End",
"description": "Terminate and stop notifying",
"prompt": "Terminate event",
"action": "END",
"contribution": "NEUTRAL",
"joinConference": false,
"allowComments": true
}
],
"links": {
"self": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a/response-options?offset=0&limit=100"
}
}
Returns a list of the response options for a form in a communication plan.
DEFINITION
GET /plans/{planId}/forms/{formId}/response-options
URL PARAMETERS
planId | string |
The unique identifier (id) or name (targetName) of the plan the forms belong to. Names must be URL-encoded. | |
formId | string |
The unique identifier (uuid) or name (targetName) of the form you want to retrieve. Names must be URL-encoded. |
QUERY PARAMETERS
offset |
integer |
The number of items to skip before returning results. See Pagination query parameters. | |
limit | integer |
The number of items to return. See Pagination query parameters. |
RESPONSES
Success | Response code 200 OK and a pagination of ResponseOption objects in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get form sections
GET sections of a communication plan form
REQUEST - returns information on the sections of a form. (In this example, the form has a Recipient and Custom section.)
curl --user username "https://acmeco.xmatters.com/api/xm/1/forms/07090eb4-b49f-4e27-b730-10ef5683369b/sections"
/**
* This script is configured to work within the xMatters Integration Builder.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/07090eb4-b49f-4e27-b730-10ef5683369b/sections"
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " form sections." );
for (var d in json.data ) {
var dd = json.data[d];
console.log("\nForm name: " + dd.name + ". Form id: " + dd.id);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = 'https://acmeco.xmatters.com/api/xm/1'
formId = '07090eb4-b49f-4e27-b730-10ef5683369b'
endpoint_URL = '/forms/' + formId + '/sections'
url = base_URL + endpoint_URL + '?offset=0&limit=2'
auth = HTTPBasicAuth('username', 'password')
print('Sending request to url: ' + url )
response = requests.get(url, auth=auth)
if response.status_code == 200:
rjson = response.json()
print ( 'Retrieved ' + str(rjson['count']) + ' of ' + str(rjson['total']) + ' form sections.' )
print ( '\nThe sections are:' )
for rd in rjson['data']:
print( 'Title "' + rd['title'] + '" of type: "' + rd['type'] + '" with ID: ' + rd['id'] )
print('The data is:\n' + json.dumps(rjson, indent=4, sort_keys=False) )
else:
print('The request did not succeed. Response code is: ' + str(response.status_code) )
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"id": "d67b4536-1a19-40c3-b24a-b3f28ed24ff8",
"form": {
"id": "07090eb4-b49f-4e27-b730-10ef5683369b"
},
"title": "Recipients",
"type": "RECIPIENTS",
"visible": true,
"collapsed": false,
"orderNum": 0,
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "386e0838-8e68-4429-8bc0-1951829c2b01",
"targetName": "Admin team",
"recipientType": "GROUP"
}
]
}
},
{
"id": "f8b4a0f8-e6c7-42e7-b6d7-d8d0afde914c",
"form": {
"id": "07090eb4-b49f-4e27-b730-10ef5683369b"
},
"title": "Custom Section",
"type": "CUSTOM_SECTION",
"visible": true,
"collapsed": false,
"orderNum": 1,
"items": [
{
"id": "3143c6bc-efff-44af-9e31-7f13fbd34dad",
"formSection": {
"id": "f8b4a0f8-e6c7-42e7-b6d7-d8d0afde914c"
},
"orderNum": 1,
"required": false,
"multilineText": false,
"visible": true,
"includeInCallbacks": false,
"propertyDefinition": {
"id": "9b67ea40-74ac-4bbd-a24f-d83f6d8813ef",
"propertyType": "TEXT",
"name": "project",
"description": "",
"helpText": "",
"default": "breeds-search",
"maxLength": 30,
"minLength": 0,
"pattern": "",
"validate": false
}
},
{
"id": "caa4925e-9861-4a79-aeb5-cce3f354e9a5",
"formSection": {
"id": "f8b4a0f8-e6c7-42e7-b6d7-d8d0afde914c"
},
"orderNum": 2,
"required": false,
"multilineText": false,
"visible": true,
"includeInCallbacks": false,
"propertyDefinition": {
"id": "9c4712b5-d141-4ff7-a981-241094ba4c5e",
"propertyType": "TEXT",
"name": "domain",
"description": "",
"helpText": "",
"default": "docs.thecatapi.com",
"maxLength": 30,
"minLength": 0,
"pattern": "",
"validate": false
}
},
{
"id": "f7f18a8f-733c-4beb-98ce-f1f57a4585cf",
"formSection": {
"id": "f8b4a0f8-e6c7-42e7-b6d7-d8d0afde914c"
},
"orderNum": 4,
"required": false,
"multilineText": false,
"visible": true,
"includeInCallbacks": false,
"propertyDefinition": {
"id": "4e3fc221-78f4-424c-ad0c-f8b32e04d06f",
"propertyType": "BOOLEAN",
"name": "Customer reported",
"description": "",
"helpText": ""
}
},
{
"id": "8e8dd241-a530-49d2-9db6-8f7ee0e24746",
"formSection": {
"id": "f8b4a0f8-e6c7-42e7-b6d7-d8d0afde914c"
},
"orderNum": 5,
"required": false,
"multilineText": false,
"visible": true,
"includeInCallbacks": false,
"propertyDefinition": {
"id": "831fbf7b-d568-48e0-80e5-4d6255aa3f89",
"propertyType": "LIST_TEXT_SINGLE_SELECT",
"name": "Severity",
"description": "Severity of the event",
"helpText": "",
"items": [
"Critical",
"High",
"Medium",
"Low"
]
}
},
{
"id": "f7e4aa5a-a8c3-4cbe-94f2-b5e2685cad9b",
"formSection": {
"id": "f8b4a0f8-e6c7-42e7-b6d7-d8d0afde914c"
},
"orderNum": 6,
"required": false,
"multilineText": true,
"visible": true,
"includeInCallbacks": false,
"propertyDefinition": {
"id": "1452a8a3-2eb7-41c1-b47f-837bcbd79b5e",
"propertyType": "TEXT",
"name": "Issue details",
"description": "Details of the issue or event from the source system (for example, Documentation or problemDetails)",
"helpText": "",
"default": "",
"maxLength": 1500,
"minLength": 0,
"pattern": "",
"validate": false
}
},
{
"id": "4289f3d0-3900-485f-a5d0-7b7a6bb1ec61",
"formSection": {
"id": "f8b4a0f8-e6c7-42e7-b6d7-d8d0afde914c"
},
"orderNum": 3,
"required": false,
"multilineText": false,
"visible": true,
"includeInCallbacks": false,
"propertyDefinition": {
"id": "0a27b3e7-7415-4418-9e1c-8379f55abf79",
"propertyType": "BOOLEAN",
"name": "Customer impacting",
"description": "",
"helpText": ""
}
},
{
"id": "1150c41f-5833-4732-98c8-13816b07ca7c",
"formSection": {
"id": "f8b4a0f8-e6c7-42e7-b6d7-d8d0afde914c"
},
"orderNum": 0,
"required": false,
"multilineText": true,
"visible": true,
"includeInCallbacks": false,
"propertyDefinition": {
"id": "7f187abe-849b-4eb8-a44d-c909b3aa9977",
"propertyType": "TEXT",
"name": "Summary",
"description": "Summary of the issue or event",
"helpText": "",
"default": "",
"maxLength": 140,
"minLength": 0,
"pattern": "",
"validate": false
}
}
]
}
],
"links": {
"self": "/api/xm/1/forms/07090eb4-b49f-4e27-b730-10ef5683369b/sections?offset=0&limit=100"
}
}
Returns information on certain form sections in a communication plan. The available form sections are:
- Conference Bridge
- Custom Section
- Devices
- Handling
- Recipients
- Sender Overrides
- Attachments
- Response Overrides
For more information on form layout and the available sections, see Design your form’s layout.
DEFINITION
GET /forms/{formId}/sections
URL PARAMETERS
formId | string |
The unique identifier (id) or name (targetName) of the form you want to retrieve. Names must be URL-encoded. |
BODY PARAMETERS
offset |
integer |
The number of items to skip before returning results. See Pagination query parameters. | |
limit | integer |
The number of items to return. See Pagination query parameters. |
RESPONSES
Success | Response code 200 OK and a pagination of Form section objects in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Form objects
Form object
Form object
This example shows a form object with embedded response options.
{
"id": "c524d945-8b17-48b4-911e-a21c9c03138b",
"formId": "123456",
"name": "IT Alert",
"description": "Notify users when an IT Alert is triggered",
"mobileEnabled": false,
"uiEnabled": false,
"apiEnabled": true,
"senderOverrides": {
"displayName": "PM TESTING",
"callerId": "+12505551234"
},
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "d84a8bb5-a924-4d09-936c-5e5e5c0c351c",
"targetName": "ITAdmin",
"recipientType": "GROUP",
"externallyOwned": false,
"allowDuplicates": true,
"useDefaultDevices": true,
"observedByAll": true,
"links": {
"self": "/api/xm/1/groups/d84a8bb5-a924-4d09-936c-5e5e5c0c351c"
}
}
],
"links": {
"self": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a/recipients?offset=0&limit=100"
}
},
"plan": {
"id": "95fe8fbb-e095-4845-beb2-15d56829627b",
"name": "IT Administration"
},
"responseOptions": {
"count": 3,
"total": 3,
"data": [
{
"id": "499e4a9b-bb2c-40a0-a01b-2bdfedb686b3",
"number": 1,
"text": "Acknowledge",
"description": "Acknowledge",
"prompt": "Acknowledge",
"action": "ASSIGN_TO_USER",
"contribution": "POSITIVE",
"joinConference": false,
"allowComments": true,
"translations": {
"count": 3,
"total": 3,
"data": [
{
"id": "046fd6e9-06a3-4350-acce-f672124b6484",
"language": "hi",
"text": "ठीक",
"description": "ठीक"
},
{
"id": "fb747f5b-10c8-48a9-9f3f-a679d2090963",
"language": "fr",
"text": "d'accord",
"prompt": "",
"description": "d'accord"
},
{
"id": "1775b40f-07b2-45cd-8a05-b140286081d9",
"language": "zh_CN",
"text": "同意"
}
]
}
{ ...truncated list of response options ... },
}
]
},
"links": {
"self": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a/response-options?offset=0&limit=100"
}
},
"links": {
"self": "/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a"
}
}
Describes a form used in a communication plan.
id | string |
The unique identifier (id ) of the form. |
|
formId | string |
Legacy numeric form identifier. | |
name | string |
The name of the form (for example, Database Alerts). | |
description | string |
The description of the form (for example, Alerts about database events, such as outages or nearing max capacity). | |
mobileEnabled | boolean |
If true, you can use the xMatters app to send messages using the form. | |
uiEnabled | boolean |
If true, you can use the web user interface to send messages using the form. | |
apiEnabled | boolean |
If true, you can use the xMatters Trigger an event endpoint to send messages using the form. | |
senderOverrides | Sender Overrides object |
A list of notification override options configured for the form. | |
plan | PlanReference object |
The communication plan the form belongs to. | |
recipients | Recipients object |
A list of recipients the form is configured to use. Returned when the request includes an explicit search for recipients, or ?embed=recipients . |
|
responseOptions | Pagination of ResponseOptions object |
A list of the response options configured for the form. Returned when the request includes ?embed=responseOptions . Returns the response in the user’s original language when the request includes ?embed=responseOptions,responseOptions.translations . |
|
links | SelfLink object |
A link that can be used to access this site. |
FormReference object
FormReference object
"form": {
"id": "ae200916-1846-4892-b692-2ea7e6cf29cf",
"name": "Database Outage Detected"
}
Describes a reference to a form, including its name and unique identifier.
id | string |
The unique identifier (id ) of the form. |
|
name | string |
The name of the form (not included in all instances). |
Sender Overrides object
Sender Overrides object
"senderOverrides": {
"displayName": "PM TESTING",
"callerId": "+12505551234"
}
Provides notification override options that help recipients identify the source of notifications.
callerId | string |
Allows you to override the caller ID displayed for voice notifications. Caller ID overrides are only supported for use with the Voxeo service provider. They are not compatible with SIP or the conference bridge feature. | |
displayName | string |
Allows you to customize the name associated with a notification or event. The display name is shown as the sender of notifications in the xMatters inbox, the mobile apps, and for email notifications. |
Form section objects
Form section object
"data": [
{
"id": "d67b4536-1a19-40c3-b24a-b3f28ed24ff8",
"form": {
"id": "07090eb4-b49f-4e27-b730-10ef5683369b"
},
"title": "Recipients",
"type": "RECIPIENTS",
"visible": true,
"collapsed": false,
"orderNum": 0,
]
}
Describes the sections of a form. Section-specific information is appended to the base section. Available sections include:
- Conference Bridge
- Custom Section
- Devices
- Handling
- Recipients
- Attachments
- Sender Overrides
- Response Overrides
The following parameters represent the base form section object.
id | string |
The unique identifier (id ) of the section. |
|
form | Form Reference Object |
Describes the form that the section is a part of. | |
title | string |
The section title as provided by the user. | |
type | string |
The section type. Available options include:
|
|
visible | boolean |
If true the section is displayed to the message sender. |
|
collapsed | boolean |
If true the section is collapsed when displayed to the message sender. |
|
orderNum | number |
The order number of the section in the form. |
Conference bridge section object
Conference Bridge section object
"data": [
{
"id": "d67b4536-1a19-40c3-b24a-b3f28ed24ff8",
"form": {
"id": "07090eb4-b49f-4e27-b730-10ef5683369b"
},
"title": "Sev_1_Calls",
"type": "CONFERENCE_BRIDGE",
"visible": true,
"collapsed": false,
"orderNum": 1,
"bridgeType": "XMATTERS_BRIDGES_ONLY"
]
}
Provides information on the Conference Bridge section of a form. The Conference Bridge section on the form allows the message sender to specify new or existing conference bridge information to include with notifications. The following table lists the fields specific to the Conference Bridge section that are appended to the main Form section object.
bridgeType | string |
The type of conference bridge set for the form section. Available options include:
|
Custom section object
Custom section object
"data": [
{
"id": "d67b4536-1a19-40c3-b24a-b3f28ed24ff8",
"form": {
"id": "07090eb4-b49f-4e27-b730-10ef5683369b"
},
"title": "Custom",
"type": "CUSTOM_SECTION",
"visible": true,
"collapsed": false,
"orderNum": 0,
"items": [
{
"id": "f7f18a8f-733c-4beb-98ce-f1f57a4585cf",
"formSection": {
"id": "f8b4a0f8-e6c7-42e7-b6d7-d8d0afde914c"
},
"orderNum": 4,
"required": false,
"multilineText": false,
"visible": true,
"includeInCallbacks": false,
"propertyDefinition": {
"id": "4e3fc221-78f4-424c-ad0c-f8b32e04d06f",
"propertyType": "BOOLEAN",
"name": "Customer reported",
"description": "",
"helpText": ""
}
},
{
"id": "8e8dd241-a530-49d2-9db6-8f7ee0e24746",
"formSection": {
"id": "f8b4a0f8-e6c7-42e7-b6d7-d8d0afde914c"
},
"orderNum": 5,
"required": false,
"multilineText": false,
"visible": true,
"includeInCallbacks": false,
"propertyDefinition": {
"id": "831fbf7b-d568-48e0-80e5-4d6255aa3f89",
"propertyType": "LIST_TEXT_SINGLE_SELECT",
"name": "Severity",
"description": "Severity of the event",
"helpText": "",
"items": [
"Critical",
"High",
"Medium",
"Low"
]
}
},
{
"id": "f7e4aa5a-a8c3-4cbe-94f2-b5e2685cad9b",
"formSection": {
"id": "f8b4a0f8-e6c7-42e7-b6d7-d8d0afde914c"
},
"orderNum": 6,
"required": false,
"multilineText": true,
"visible": true,
"includeInCallbacks": false,
"propertyDefinition": {
"id": "1452a8a3-2eb7-41c1-b47f-837bcbd79b5e",
"propertyType": "TEXT",
"name": "Issue details",
"description": "Details of the issue or event from the source system (for example, Documentation or problemDetails)",
"helpText": "",
"default": "",
"maxLength": 1500,
"minLength": 0,
"pattern": "",
"validate": false
}
},
{
"id": "4289f3d0-3900-485f-a5d0-7b7a6bb1ec61",
"formSection": {
"id": "f8b4a0f8-e6c7-42e7-b6d7-d8d0afde914c"
},
"orderNum": 3,
"required": false,
"multilineText": false,
"visible": true,
"includeInCallbacks": false,
"propertyDefinition": {
"id": "0a27b3e7-7415-4418-9e1c-8379f55abf79",
"propertyType": "BOOLEAN",
"name": "Customer impacting",
"description": "",
"helpText": ""
}
},
]
}
Provides information on the properties specific to items in the Custom section of a form. The Custom section is a special form section that allows the addition of properties to a form. Form creators can add multiple properties to a single custom section, or add multiple custom sections to a form, and add one or more properties to each. The following table lists the item-specific properties of the Custom section that are appended to the main Form section object.
id | string |
The unique identifier (id ) of the item within the Custom section. |
|
formSection | string |
The id of the item in the custom section. |
|
orderNum | number |
The order number of the item within the custom form section. | |
required | boolean |
If true the custom form item is mandatory. Default is false . |
|
multiLineText | boolean |
If true the custom form item is allows users to enter multiple lines of text. |
|
visible | boolean |
If true the section is displayed to the message sender. |
|
includeInCallbask | boolean |
If true , the custom section item is included in callbacks. |
|
propertyDefinition | Pagination of Property objects |
The properties that are available to users when adding items to custom sections of a form. |
Devices section object
Devices section object
"data": [
{
"id": "d67b4536-1a19-40c3-b24a-b3f28ed24ff8",
"form": {
"id": "07090eb4-b49f-4e27-b730-10ef5683369b"
},
"title": "Available Devices",
"type": "DEVICE_FILTER",
"visible": true,
"collapsed": false,
"orderNum": 0,
"targetDeviceNames": {
"count": 2,
"total": 2,
"data": [
{
"name": "Mobile Phone",
"visible": true,
"selected": true,
"description": "Cell Phone",
"deviceType": "VOICE"
},
{
"name": "Work Email",
"visible": false,
"selected": true,
"description": "Work Email Address",
"deviceType": "EMAIL"
},
},
},
]
Provides information on the Devices section of a form. The Devices section provides message senders with granular control over which device types are targeted, and which devices are visible to the form sender. If recipients do not have a device thyat matches one of the specified types, they will not receive messages based on this form. The following table provides the fields specific to the Devices section that are appended to the main Form Section object.
targetDeviceNames | Pagination of targetDeviceName selector objects objects |
A list of devices that can receive notifications based on this form. |
Handling section object
Handling section object
"data": [
{
"id": "d67b4536-1a19-40c3-b24a-b3f28ed24ff8",
"form": {
"id": "07090eb4-b49f-4e27-b730-10ef5683369b"
},
"title": "Default Handling",
"type": "HANDLING_OPTIONS",
"visible": true,
"collapsed": false,
"orderNum": 0,
"otherResponseCountThreshold": 2,
"priority": "MEDIUM",
"expirationInMinutes": 4,
"overrideDeviceRestrictions": false,
"escalationOverride": false,
"bypassPhoneIntro": false,
"requirePhonePassword": false,
"voiceMailOptions": {
"retry": 2,
"every": 60,
"leave": "CALLBACK"
},
},
]
Provides information on the Handling section of a form. The Handling section of a form adds controls that allow the message sender to specify notification priority and expiration, as well as several override, password and voicemail options. The following table provides the specific Device Filter section fields that are appended to the main Form Section object.
otherResponseCountThreshold | string |
For events that count responses, this represents the number of responses from users counted as ‘others’ required before the event stops sending notifictations to more other users. | |
priority | string |
The relative importance of the message. Options are:
|
|
expirationInMinutes | integer |
The maximum time (in minutes) an event is active before it terminates. | |
overrideDeviceRestrictions | boolean |
When enabled, device timeframes and delays are ignored so messages are delivered as quickly as possible. The default value is “false”. | |
escalationOverride | boolean |
When enabled, shift escalation schedules are ignored. The default value is “false”. | |
bypassPhoneIntro | boolean |
When enabled, greeting messages are not played during a phone notification. The default value is “false”. | |
requirePhonePassword | boolean |
When enabled, call recipients must enter a password before messages are played. The default value is “false”. | |
voicemailOptions | VoicemailOptions object |
optional | For voice notifications, this defines whether to try the call again or leave a message. |
Recipients section object
Recipients section object
"data": [
{
"id": "d67b4536-1a19-40c3-b24a-b3f28ed24ff8",
"form": {
"id": "07090eb4-b49f-4e27-b730-10ef5683369b"
},
"title": "Recipients",
"type": "RECIPIENTS",
"visible": true,
"collapsed": false,
"orderNum": 0,
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "386e0838-8e68-4429-8bc0-1951829c2b01",
"targetName": "Admin team",
"recipientType": "GROUP"
}
]
},
},
]
Provides information on the Recipients section of a form. Recipients are users, groups, or devices that can receive notifications. The following table provides the specific Recipients section fields that are appended to the main Form Section object.
recipients | Pagination of Person objects |
The list of recipients targeted by the form. |
Attachments section object
Attachments section object
"data": [
{
"id": "d67b4536-1a19-40c3-b24a-b3f28ed24ff8",
"form": {
"id": "07090eb4-b49f-4e27-b730-10ef5683369b"
},
"title": "Attachment1",
"type": "DOCUMENT_UPLOAD",
"visible": true,
"collapsed": false,
"orderNum": 0,
},
]
Provides a location for recipients to include attachments. This object uses only the base form section fields. Ensure the data type
field is set to “DOCUMENT_UPLOAD”.
Sender Overrides section object
Sender Overrides section object
"data": [
{
"id": "d67b4536-1a19-40c3-b24a-b3f28ed24ff8",
"form": {
"id": "07090eb4-b49f-4e27-b730-10ef5683369b"
},
"title": "MIM_Overrides",
"type": "SENDER_OVERRIDES",
"visible": true,
"collapsed": false,
"orderNum": 0,
"senderOverrides": {
"displayName": {
"value": "PM TESTING",
"visible": true
},
"callerId": {
"value": "+12505551234",
"visible": true
}
}
}
]
Provides notification override options that help recipients identify the source of notifications.
callerId | string |
Allows you to override the caller ID displayed for voice notifications. Caller ID overrides are only supported for use with the Voxeo service provider. They are not compatible with SIP or the conference bridge feature. | |
displayName | string |
Allows you to customize the name associated with a notification or event. The display name is shown as the sender of notifications in the xMatters inbox, the mobile apps, and for email notifications. |
Response Overrides section object
Response Overrides section object
"data": [
{
"id": "d67b4536-1a19-40c3-b24a-b3f28ed24ff8",
"form": {
"id": "07090eb4-b49f-4e27-b730-10ef5683369b"
},
"title": "Response Overrides",
"type": "RESPONSE_CHOICES",
"visible": true,
"collapsed": false,
"orderNum": 0,
},
]
Provides a location for recipients to override available response options. This object uses only the base form section fields. Ensure the type
field is set to RESPONSE_CHOICES.
GROUPS
Groups allow you to notify a set of people, devices, dynamic teams, and other groups according to who is on duty. If a notification is not handled on time, xMatters can then escalate it to the next group member according to the group’s timeline.
The /groups
endpoint allows you to retrieve, create, modify, and delete groups.
Use Group Roster to add or remove members from the group.
Use On Call to retrieve who is currently on duty.
For more information on group settings, see Group Options and Settings
This API does not support legacy groups that use shared teams across shifts. To convert such a group to one that can be accessed with this API, locate it in the user interface and click the Unshare button.
Get a group
GET a group
REQUEST (get a group by name and embed observers)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/groups/Oracle%20Administrators?embed=observers"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/Oracle Administrators?embed=observers",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved group: " + json.targetName + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
groupId = "438e9245-b32d-445f-916bd3e07932c892"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups/" + groupId + "?embed=supervisors,observers"
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
print("Received response: " + str(responseCode))
if int(responseCode) == 200:
rjson = response.json()
print('Retrieved group with name: "' + rjson["targetName"] + '"')
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ str(response)
)
REQUEST (get a group by id by querying current system data)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c89",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved group: " + json.targetName + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
groupId = "438e9245-b32d-445f-916bd3e07932c892"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups/" + groupId
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
print("Received response: " + str(responseCode))
if int(responseCode) == 200:
rjson = response.json()
print('Retrieved group with name: "' + rjson["targetName"] + '"')
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ str(response)
)
REQUEST (get a group by id by querying historical system data)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892?at=2018-11-02T08:00:00.000Z"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c89?at=2018-11-02T08:00:00.000Z",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved group: " + json.targetName + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
groupId = "438e9245-b32d-445f-916bd3e07932c892"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups/" + groupId + "?at=2019-11-05T22:30:00.000Z"
url = base_URL + endpoint_URL
print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
print("Received response: " + str(responseCode))
if int(responseCode) == 200:
rjson = response.json()
print('Retrieved group with name: "' + rjson["targetName"] + '"')
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ str(response)
)
RESPONSE (get a group by name and embed observers)
{
"id": "438e9245-b32d-445f-916bd3e07932c892",
"targetName": "Oracle Administrators",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": false,
"useDefaultDevices": true,
"observedByAll": false,
"observers": {
"count": 1,
"total": 1,
"data": [
{"id": "5fda0343-6940-1752-fb34-603b03819f08",
"name": "Company Admin"}
],
},
"description": "Oracle database administrators",
"links": {"self": "/api/xm/1/groups/6c0aef9f-d19f-4814-ae0d-8becaa13204b"},
"supervisors": {
"count": 1,
"total": 1,
"data": [
{
"id": "b2341d69-8b83-4660-b8c8-f2e728f675f9",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/b2341d69-8b83-4660-b8c8-f2e728f675f9"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Eastern",
"webLogin": "mmcbride",
"phoneLogin": "1111",
"site": {
"id": "f0c572a8-45ec-fe23-289c-df749cf19a5e",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/f0c572a8-45ec-fe23-289c-df749cf19a5e"
},
},
"lastLogin": "2019-11-05T21:25:23.564Z",
"status": "ACTIVE",
}
],
},
}
RESPONSE (get a group by querying current system data)
{
"id": "438e9245-b32d-445f-916bd3e07932c892",
"targetName": "Oracle Administrators",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": false,
"useDefaultDevices": true,
"observedByAll" : true,
"description": "Oracle database administrators",
"site":
{
"id": "dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
"links":
{
"self": "/api/xm/1/sites/dbf90cbf-a745-a054-abf0-cb3b5b56e6bd"
}
},
"links":
{
"self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
}
}
Returns a Group object that contains a representation of the group.
You can identify the group by using its name (targetName
) or its unique identifier (id
).
You can embed up to the first 100 group supervisors in the result by using the ?embed=supervisors
query parameter. If the group has more than 100 supervisors, use GET /groups/{groupId}/supervisors
to retreive a pagination of all group supervisors (see Get a group’s supervisors).
Group visibility is set by the observedByAll
parameter. This parameter defines which roles can send notifications to a group. The default observedByAll
setting is true
, which means the group is visible to all roles with the appropriate permission settings. If a group’s creator has limited the visibility by setting specific roles as observers, the observedByAll
is set to false
, and only the specified roles can send notifications to the group.
To view information about group observers, log on to the xMatters user interface and view the group.
DEFINITION
GET /groups/{groupId}
GET /groups/{groupId}?embed=supervisors,observers
GET /groups/{groupId}?at=2018-11-02T08:00:00.000Z
URL PARAMETERS
{groupID} | string |
The unique identifier (id ) or name (targetName ) of the group. If you use the name to identify the group, it must be URL-encoded.Example: Oracle%20Administrators Example: 438e9245-b32d-445f-916bd3e07932c892 |
QUERY PARAMETERS
embed | string |
A comma-separated list of objects to embed in the response. Supported values include the following:
|
|
at |
string |
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.Example: 2017-05-01T19:00:00.000Z |
RESPONSES
Success | Response code 200 OK and a Group object in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get groups
GET groups
REQUEST (get all groups)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/groups/"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " groups." );
for (var i in json.data ) {
console.log(json.data[i].targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups"
url = base_URL + endpoint_URL + "?offset=0&limit=2"
auth = HTTPBasicAuth("username", "password")
print("Sending request to url: " + url)
response = requests.get(url, auth=auth)
if response.status_code == 200:
rjson = response.json()
print(
"Retrieved " + str(rjson["count"]) + " of " + str(rjson["total"]) + " groups."
)
print("\nThe sections are:")
for rd in rjson["data"]:
print(
'Found group with targetName "'
+ rd["targetName"]
+ '" with ID: '
+ rd["id"]
)
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
print(
"The request did not succeed. Response code is: " + str(response.status_code)
)
REQUEST (get groups with ‘admin’ or 'database’ in the name, and the observers for those groups)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/groups?search=admin database&fields=name?embed=observers"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups?search=admin%20database&fields=NAME?embed=observers",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " groups." );
for (var i in json.data ) {
console.log(json.data[i].targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups"
search_query = "/?search=admin database&fields=NAME&embed=observers"
url = base_URL + endpoint_URL + search_query + "&offset=0&limit=2"
auth = HTTPBasicAuth("username", "password")
print("Sending request to url: " + url)
response = requests.get(url, auth=auth)
if response.status_code == 200:
rjson = response.json()
print(
"Retrieved " + str(rjson["count"]) + " of " + str(rjson["total"]) + " groups."
)
print("\nThe sections are:")
for rd in rjson["data"]:
print(
'Found group with targetName "'
+ rd["targetName"]
+ '" with ID: '
+ rd["id"]
)
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
print(
"The request did not succeed. Response code is: " + str(response.status_code)
)
REQUEST (get groups with 'admin’ and 'database’ in the name or description)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/groups?search=admin database&operand=AND"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups?search=admin%20database&operand=AND",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " groups." );
for (var i in json.data ) {
console.log(json.data[i].targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups"
search_query = "/?search=admin database&operand=AND"
url = base_URL + endpoint_URL + search_query + "&offset=0&limit=2"
auth = HTTPBasicAuth("username", "password")
print("Sending request to url: " + url)
response = requests.get(url, auth=auth)
if response.status_code == 200:
rjson = response.json()
print(
"Retrieved " + str(rjson["count"]) + " of " + str(rjson["total"]) + " groups."
)
print("\nThe sections are:")
for rd in rjson["data"]:
print(
'Found group with targetName "'
+ rd["targetName"]
+ '" with ID: '
+ rd["id"]
)
print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
print(
"The request did not succeed. Response code is: " + str(response.status_code)
)
RESPONSE (get all groups)
{
"count": 2,
"total": 2,
"data":
[
{
"id": "438e9245-b32d-445f-916bd3e07932c892",
"targetName": "Oracle Administrators",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": false,
"useDefaultDevices": true,
"observedByAll" : true,
"description": "Oracle database administrators",
"site":
{
"id": "dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
"links":
{
"self": "/api/xm/1/sites/dbf90cbf-a745-a054-abf0-cb3b5b56e6bd"
}
},
"links":
{
"self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
}
},
{
"id": "827e9245-a48a-9921-955bd3e07932c600",
"targetName": "Sys Admins",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": false,
"useDefaultDevices": true,
"observedByAll" : true,
"description": "System database administrators",
"site":
{
"id": "dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
"links":
{
"self": "/api/xm/1/sites/dbf90cbf-a745-a054-abf0-cb3b5b56e6bd"
}
},
"links":
{
"self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
}
}
],
"links":
{
"self": "/api/xm/1/groups?offset=0&limit=100"
}
RESPONSE (get groups with 'admin’ or 'database’ in the name, and the observers for those groups)
{
"count": 2,
"total": 2,
"data":
[
{
"id": "438e9245-b32d-445f-916bd3e07932c892",
"targetName": "Oracle Administrators",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": false,
"useDefaultDevices": true,
"observedByAll" : false,
"observers": {
"count": 1,
"total": 1,
"data": [
{
"id": "5fda0343-6940-1752-fb34-603b03819f08",
"name": "Company Admin"
}
]
},
"site":
{
"id": "dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
"links":
{
"self": "/api/xm/1/sites/dbf90cbf-a745-a054-abf0-cb3b5b56e6bd"
}
},
"links":
{
"self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
}
},
{
"id": "827e9245-a48a-9921-955bd3e07932c600",
"targetName": "Sys Admins",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": false,
"useDefaultDevices": true,
"observedByAll" : true,
"description": "System database administrators",
"site":
{
"id": "dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
"links":
{
"self": "/api/xm/1/sites/dbf90cbf-a745-a054-abf0-cb3b5b56e6bd"
}
},
"links":
{
"self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
}
}
],
"links":
{
"self": "/api/xm/1/groups?offset=0&limit=100"
}
Returns a list of Group objects that represent the groups in the system.
This endpoint returns only the groups that the authenticated user has permission to access. If search terms are provided with the request, this endpoint returns the groups whose name or description match any of the search criteria. You can specify if you want to search only the name or the description.
Group visibility is set by the observedByAll
parameter. This parameter defines which roles can send notifications to a group. The default observedByAll
setting is true
, which means the group is visible to all roles with the appropriate permission settings. If a group’s creator has limited the visibility by setting specific roles as observers, the observedByAll
is set to false
, and only the specified roles can send notifications to the group.
Groups are returned as a paginated list of Group objects and are sorted in alphabetical order. For more information about working with paginated result sets, see Results Pagination.
DEFINITION
GET /groups
GET /groups?embed=observers,supervisors
GET /groups?search=term1 term2 term3&operand=AND
GET /groups?search=term1&fields=DESCRIPTION
GET /groups?sites=23d3ca36-13d2-4aaf-84da-6218aa768b11
GET /groups?members=asharma,6f347364-8dc7-4871-819b-e3e7dbfda2de
GET /groups?members.exists=ANY_SHIFTS
GET /groups?sortBy=NAME&sortOrder=ASCENDING
GET /groups?status=ACTIVE
GET /groups?supervisors=asharma,6f347364-8dc7-4871-819b-e3e7dbfda2de
QUERY PARAMETERS
embed | string |
A comma-separated list of objects to embed in the response. Supported values are:
|
|
search | string |
A list of search terms separated by the + sign or a space character. Searches are case-insensitive and must contain a total of at least two characters. Searches cannot contain whitespace characters within an individual search term. The search looks for the term anywhere in the name or description (for example, searching for data returns the group “Rigel Database Admins” in the results). When two or more search terms are present, the result includes groups that match either search term. You can narrow the search to results that include both terms by using the operand query parameter. You can also search only the name or description by setting the fields query parameter.Example: /groups?search=admin corporate |
|
operand | string |
The operand to use to limit or expand the search query parameter: AND or OR . AND only returns groups that have all search terms in the name or description. OR returns groups that have any of the search terms in the name or description; this is the default if you don’t specify an operand. The operand is case-sensitive; for example, lowercase 'and’ will return an error. |
|
fields | string |
Defines the field to search when a search term is specified. Valid values include:
|
|
sites | string |
The unique identifier (id ) or name of a site. Adding sites to the search returns a list of groups for a specific site.Example:San Ramon Example:960ffa54-b6d3-42b7-8025-7d95ff599976 . |
|
members | string |
The targetName or id of the users, dynamic teams, or devices that are members of a group. To search for multiple members, use a comma-separated list and UTF-8 encode any spaces in the names. For example, the “DBA Admins” dynamic team becomes “DBA%20Admins”. The returned results show all groups that contain any of the queried members. |
|
members.exists | string |
Returns a list of shifts without members. Available options are:
|
|
sortBy | string |
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 include:
|
|
sortOrder | string |
Specifies whether groups are sorted in ascending or descending order. This parameter must be used in conjunction with the sortBy query parameter. Valid values include:
|
|
status | string |
The status of the group. Valid values include:
|
|
supervisors | string |
A comma-separated list of supervisors whose groups you want to retrieve. You can specify the supervisors using targetName (case-insensitive) or id (or both if search for multiple supervisors). When two or more supervisors are sent in the request, the response includes groups for which either user is a supervisor.Example: /groups?supervisors=asharma,6f347364-8dc7-4871-819b-e3e7dbfda2de |
RESPONSES
Success | Response code 200 OK and a Pagination of Group objects in the response body. |
Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a group
Create a group
REQUEST - Create group This request shows how to create a group named “Executives” with two group supervisors, and the “Developer” role as an observer. This example does not include the
id
field. In this case, xMatters generates anid
for this group and returns it in theid
field of the response.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"recipientType": "GROUP",
"status": "ACTIVE",
"allowDuplicates" : true,
"useDefaultDevices" : true,
"observedByAll" : false,
"observers" : [
{"name:" "Developer"}
],
"description": "C-suite executives",
"site": "dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
"supervisors" :
[
"410c96c4-8fdf-4936-a36f-13890b89ac3f",
"a608fa11-552a-4806-b247-48f083a20081"
],
"targetName": "Executives"
}' "https://acmeco.xmatters.com/api/xm/1/groups"
/**
* This script is configured to work within the xMatters Integration Builder.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.recipientType = 'GROUP';
data.targetName = 'Executives';
data.status = 'ACTIVE';
data.allowDuplicates = true;
data.useDefaultDevices = true;
data.observedByAll = false;
data.observers = [];
data.observers.push( {"name": "Developer"} );
data.description = 'C-suite executives';
data.site = '4d618961-21d6-417d-a904-8a84893b4e31';
var supervisors = [];
supervisors.push("0d5d3032-e5d5-41e6-8d27-0047ffc46528");
supervisors.push("bab4a72f-e118-462d-ad87-e38e28e822e0");
data.supervisors = supervisors;
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created group: " + json.targetName + ". ID = "+ json.id);
}
#The following code is formatted to work with Python v.3.6 and later.
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"recipientType": "GROUP",
"targetName": "Executives",
"status": "ACTIVE",
"allowDuplicates": True,
"useDefaultDevices": True,
"observedByAll": False,
"observers": [{
"name": "Developer"
}],
"description": "C-suite executives",
"site": "bc0a999b-c4d4-4845-b99e-7bf63847c364",
"supervisors": [
"66849723-b6cf-4be1-9898-2d63a2f4236d",
"e4f8d5c3-b0ab-49d9-88a8-e73e6255ec8f",
],
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)<