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.
Events and alerts
While we've renamed "events" to "alerts" in the web user interface, we are not changing any of the properties, values, or labels associated with events in the REST API. This ensures that your existing integrations and incoming signals will continue to function without interruption. For more information on the Events to Alerts change, see our Support site article.
Roles and permissions
The xMatters REST API enforces data access controls as defined for specific resources. For example, role-on-role permissions are used to govern user data, groups have supervisors and observers, and messaging forms have sender permissions. 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 and 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.
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 xMatters Flow Designer 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 encoded version
of your username and password to the end of the string. You can create a Base64 encoded username and password at https://www.base64encode.org/ or by typing echo “username:password” | base64 into a terminal.
EXAMPLE AUTHENTICATION HEADER
This example uses username and password as the credentials, which are then Base64 encoded into dXNlcm5hbWU6cGFzc3dvcmQ=:
--header Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Base URL
https://acmeco.xmatters.com/api/xm/1/
https://acmeco.xmatters.com/api/xm/1/
/**
* In Flow Designer, 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/",
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>/
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.
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 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 use the at parameter to search for information on an object at a specified point in time.
Currently, the at parameter is available on the following endpoint:
- GET /events/{eventId}
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
fromparameter, the length of time you can set is limited by your pricing plan. Also theattimestamp cannot be earlier than thefromtimestamp.
Example: If your pricing plan allows you to access 90 days of historical data, you will receive an error message if you set thefromparameter to be greater than 90 days in the past. - When setting the
toparameter, the time cannot be further in the future than the time of theatparameter.
Example: If theatis set for 2018-12-01T13:00:00.000Z, thetoparameter 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 /events
- GET /on-call
xmtoolbox
xmtoolbox is a JavaScript package that simplifies interaction with xMatters. By providing a wrapper to documented xMatters APIs, xmtoolbox makes backup/restoration and user/group synchronization easy. You can quickly and easily set up logic-driven data management and retrieval from your xMatters instance.
For the downloadable package and installation instructions, go to xmtoolbox on NPM. Once installed, you can download a quick start project, or view this workshop on Getting Started with xmtoolbox .
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
idfield) - by name (stored in the
targetNamefield)
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 response = request.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.)
Some payloads or responses might contain fields that are not documented. Those fields represent either experimental or deprecated information and are subject to change. We recommend that you use only the documented parameters when submitting your requests.
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 group object.
A recipient is a user, group, device or dynamic group in xMatters that can receive notifications. The recipient object provides a base for Group object, Device object, Person object, and Dynamic group 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. |
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 |
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:
|
ALERTS
While we've renamed "events" to "alerts" in the web user interface, we are not changing any of the properties, values, or labels associated with events in the REST API. This ensures that your existing integrations and incoming signals will continue to function without interruption. See the Events endpoint for all available API commands.
ATTACHMENTS
The attachments endpoint lets you upload files to xMatters so you can then add them as attachments to events and scenarios. Once uploaded, the response returns the temporary location of the file in a path. Copy the path location and use it to connect the uploaded attachment with the event or scenario in your system.
Once a file is uploaded to xMatters it cannot be removed and should be attached to an event or scenario as quickly as possible. Unused files are automatcially discarded after a period of time.
To use the uploaded attachments, see:
Attachment files are available to download after they are attached to an event or scenario. Text files are displayed in the response, graphic files are available for download so you can open them in the viewer of your choice. For more information, see:
Upload an attachment
Upload an attachment
REQUEST - Upload an attachment to xMatters
curl --user username --header "Content-Type: multipart/form-data" --request POST -d '{
"file": "my_company_logo.png",
"fileName": "my_company_logo.png"
}' "https://acmeco.xmatters.com/api/xm/1/attachments"
/**
* As multi-part forms are not supported, this feature is not available in Flow Designer.
*/
import requests
from requests.auth import HTTPBasicAuth
import multipart
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/attachments"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "multipart/form-data"}
data = {
"file": "my_company_logo.png",
"fileName": "./images/my_company_logo.png",
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print(
"Created attachment "
+ response.json()["name"]
+ ". Path = "
+ response.json()["path"]
)
else:
print("Error: Response code is: " + str(responseCode))
]
RESPONSE
{
"name": "my_company_logo.png",
"path": "/attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/my_company_logo.png",
"size": 12635,
"links": {
"self": "/api/xm/1/attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/my_company_logo.png"
}
}
Uploads a file to xMatters for use as an attachment with existing events and scenarios. Each file has a maximum file size of 10 MB each. The following file types are supported:
- Images: BMP, GIF, ICO, JPEG, PNG, SVG+XML, TIFF
- Microsoft Office: DOC, DOCX, XLS, PPT
- Multimedia: MP3, MP4, WAV, MOV, AVI, WMV, MPG, MPEG, VOX
- Open Document: ODT, ODS, ODP, ODG
- Other: CSV, HTML, TXT, XML, XMLA, PDF, ZIP, X-ZIP, BIN
Once uploaded to xMatters, each file is given a temporary location, denoted by a path in the response. Copy the path to an easy-to-find location. You'll need this path location to attach the uploaded file to an event or scenario. Once the file is uploaded to xMatters' temporary storage facility, it cannot be removed. Uploaded files should be attached to events or senarios as quickly as possible. Files that are uploaded but not attached are eventually deleted.
DEFINITION
POST /attachments
BODY PARAMETERS
| file | binary content |
| The file to upload to xMatters. | |
| fileName | string |
| A unique and descriptive name for the file. This can be the name of the file as it exists in your system already, or a new name for the file. |
RESPONSES
| Success | Response code 201 Created and an Attachments object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Attachments objects
Attachments object
Attachments Object
{
"name": "Company_Logo",
"path": "attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/Company_Logo.png",
"size": 12635,
"links": {
"self": "/api/xm/1/attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/Company_Logo.png"
}
}
Describes a file uploaded to xMatters for use as an attachment.
| name | string |
| The unique user-provided name for the attached file. | |
| path | string |
| The temporary storage location of the file in xMatters. Files are held at this location until they are used with a form, event, or scenario. | |
| size | integer |
| The size of the attachment in bytes. |
AttachmentsReference object
Attachments Reference Object
{
"path": "events/a6c6e823-6466-471e-a378-4c6e5ae4f1a2/Company_Logo.png",
}
Describes a file in xMatters that has been used as an attachment to an event or scenario.
| path | string |
| The location of the file in xMatters, based on the event or scenario the file is attached to. |
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 xMatters Flow Designer.
* 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 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 Flow Designer.
* 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"]
)
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?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:
|
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 when information was added to the event. |
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. |
Audit response object
Audit 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. |
CHANGE INTELLIGENCE
Change intelligence describes the creation and retrieval of change records in an xMatters instance. These records give users additional insights into how changes such as deployments, or feature toggles can impact their service health. For example, the implementation of a new section of code could introduce an unforseen bug and cause a system outage. Troubleshooting the cause of the outage is far easier when a change record indicating a possible root cause is available.
This endpoint lets you create and retreive change records for your xMatters instance. Once a change record is created, it cannot be modified or deleted. You can create global change records, or apply a change to a specific service in your instance.
For more information on change intelligence, see Change Intelligence in the online help.
Get changes
GET all changes for your xMatters instance
REQUEST - Get all changes for your xMatters instance
curl --user username
"https://acmeco.xmatters.com/api/xm/1/changes"
/**
* This script is configured to work within xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/changes",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " changes." );
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 = "/changes"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"count": 3,
"total": 3,
"data": [
{
"id": "b9d8826b-ae98-4605-8c11-66a393ebdf57",
"changeType": "OTHER",
"source": "Customer config",
"summary": "Update required.",
"changedAt": "2022-05-18T18:24:17.307Z",
"service": {
"id": "938e07b1-b85e-496a-9851-15a812370a8d",
"targetName": "Antares System Monitoring",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/938e07b1-b85e-496a-9851-15a812370a8d"
}
}
},
{
"id": "a1b40e4d-c95c-4900-8944-d6265ec8b21f",
"changeType": "DEPLOY",
"source": "Jenkins",
"summary": "New build deployed",
"changedAt": "2022-05-18T18:21:04.064Z",
"service": {
"id": "938e07b1-b85e-496a-9851-15a812370a8d",
"targetName": "Proxy service",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/938e07b1-b85e-496a-9851-15a812370a8d"
}
}
},
{
"id": "61638030-4d5a-4e39-92a1-f6e1d7cde3b2",
"changeType": "SOURCE_CODE_COMMIT",
"source": "Git",
"summary": "Change for feature update.",
"changedAt": "2022-05-18T18:00:59.369Z",
"service": {
"id": "7631b885-43cd-4721-a140-86645e4a4daa",
"targetName": "HAProxy",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/7631b885-43cd-4721-a140-86645e4a4daa"
}
}
},
],
"links": {
"self": "/api/xm/1/changes?offset=0&limit=100",
}
}
Returns a list of change records for services within your xMatters instance. Logging changes allows you to more quickly detect problems and troubleshoot them in your instance.
DEFINITION
GET /changes
RESPONSES
| Success | Response code 200 OK and a Pagination of Change objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a change
GET a change
REQUEST - Get a specific change record by its unique identifier
curl --user username
"https://acmeco.xmatters.com/api/xm/1/changes/eb1dc7a7-2024-43b7-9566-8c8c68484e5e"
/**
* This script is configured to work within xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/changes/eb1dc7a7-2024-43b7-9566-8c8c68484e5e",
"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
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/changes/eb1dc7a7-2024-43b7-9566-8c8c68484e5e"
url = base_URL + endpoint_URL
response = requests.get(url, auth=HTTPBasicAuth("username", "password"))
if response.status_code == 200:
groupID = response.json()["id"]
print ("Retrieved change " + response.json()["targetName"])
>RESPONSE
```json
{
"id": "eb1dc7a7-2024-43b7-9566-8c8c68484e5e",
"changeType": "MANUAL",
"source": "Manual FS modification",
"summary": "Updating routing tables",
"changedAt": "2022-06-16T18:42:18.063Z",
"details": "Updated routing tables due to ongoing dns failures.",
"changedBy": "Barry Gull (bgull)",
"externalIdentifier": "",
"service": {
"id": "b12a7d82-4e72-47cd-820e-fe2c5b567129",
"targetName": "API",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/b12a7d82-4e72-47cd-820e-fe2c5b567129"
}
}
},
Description
DEFINITION
GET /changes/{changeID}
URL PARAMETERS
| changeID | string |
The unique identifier (id) of the change. |
RESPONSES
| Success | Response code 200 OK and a Change object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a change record
Create a change record
REQUEST - Create a service-specific change record
curl --user username --header "Content-Type: application/json" --request POST -d '{
"changeType": "SOURCE_CODE_COMMIT",
"source": "Gitlab",
"summary": "Implemented new code to correct a bug",
"changedAt": "2022-06-15T23:07:29.631Z",
"changedBy": "Mary McBride (mmcbride)",
"service": "Antares Proxy"
}' "https://acmeco.xmatters.com/api/xm/1/changes"
/**
* This script is configured to work within xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/changes/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.changeType = 'SOURCE_CODE_COMMIT';
data.source = 'Gitlab';
data.summary = 'Implemented new code to correct a bug';
data.changedAt = '2022-06-15T23:07:29.631Z';
data.changedBy = 'Mary McBride (mmcbride)';
data.service = 'Antares Proxy';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created " + 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 = "/changes"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"changeType": "SOURCE_CODE_COMMIT",
"source": "Gitlab",
"summary": "Implemented new code to correct a bug",
"changedAt": "2022-06-15T23:07:29.631Z",
"changedBy": "Mary McBride (mmcbride)",
"service": "Antares Proxy"
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print ("Created " + response.json()["targetName"] + ". id = " + response.json()[
"id")
]
RESPONSE
{
"id": "528d8579-354c-4a05-a702-c4048ba8001b",
"changeType": "SOURCE_CODE_COMMIT",
"source": "Gitlab",
"summary": "Implemented new code to correct a bug",
"changedAt": "2022-06-15T23:07:29.631Z",
"changedBy": "Mary McBride (mmcbride)",
"service": {
"id": "eb0fa99e-0bd4-4d2c-910f-a464836e1732",
"targetName": "Antares Proxy",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/eb0fa99e-0bd4-4d2c-910f-a464836e1732"
}
}
}
Creates a record of a change to a service in your xMatters instance. Once a change record is created, it cannot be modified or deleted from your system. If you want to create a change record for a specific service, include the service parameter with the payload. If excluded, the change is assumed to be global.
DEFINITION
POST /changes
BODY PARAMETERS
| changeType | string |
The type of change to log. Available options are:
|
|
| source | string |
| The automation tool or version control system where the change occurred. | |
| summary | string |
| A summary of the change. | |
| changedAt | string |
| The timestamp (in ISO format) of when the change took place in the source system. | |
| changedBy | string |
| The name of the person or team that executed the change. By default this field is populated with the credentials of the user who added the change record, but it can be left blank. | |
| details | string |
| Raw data from the change source. | |
| externalIdentifier | string |
| The unique identifier of the change from the source system. | |
| service | string |
| The name or UUID of the xMatters service this change affects. If you do not include a specific service name, the change is considered to apply globally. |
RESPONSES
| Success | Response code 201 Created and a Change object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Change objects
Change object
Change object
{
"changeType": "DEPLOY",
"source": "Jenkins",
"summary": "Update required.",
"changedAt": "2022-05-18T18:24:17.307Z",
"changedBy": "Barry Gull (bugull)",
"externalIdentifier": "BUILD-8817",
"service": {
"id": "938e07b1-b85e-496a-9851-15a812370a8d",
"targetName": "Antares System Monitoring",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/938e07b1-b85e-496a-9851-15a812370a8d"
}
}
},
Describes the contents of a change record in an xMatters instance.
| changeType | string |
The type of change logged. Available options are:
|
|
| source | string |
| The automation tool or version control system where the change occurred. | |
| summary | string |
| A summary of the change. | |
| changedAt | string |
| The timestamp (in ISO format) of when the change took place in the source system. | |
| changedBy | string |
| The name of the person or team that executed the change. By default this field is populated with the credentials of the user who added the change record. | |
| details | string |
| Raw data from the change source. | |
| externalIdentifier | string |
| The unique identifier of the change from the source system. | |
| service | string |
| The name or UUID of the xMatters service this change affects. |
DEVICES
Devices include voice and text phones, email addresses, pagers, mobile apps, and more.
You can configure when xMatters contacts each device, enabling notifications on the most appropriate device according to each user's schedule. You can also configure the device order and setting delays between devices to ensure that each user has time to respond to a notification on one device before xMatters notifies the next device. By combining these features you can minimize notifications to disruptive devices while still ensuring that no one misses an important event.
Get a device
Get a device
REQUEST (get a device by id, including timeframes)
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"]
)
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}
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 |
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"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
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 theidfield.
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 |
| True if the device is a failsafe device. | |
| delay | integer |
| 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 |
| 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 |
| See externalKey. | |
| externallyOwned | Boolean |
| 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 |
The minimum priority of an event for it to be delivered to this device. Valid values include the following:
|
|
| provider | string |
| 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 |
| For devices, the recipient type is "DEVICE". Providing this optional field allows xMatters to process your request more efficiently and improves performance. | |
| sequence | integer |
| 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 |
The status of the devices. Valid values include:
|
|
| testStatus | string |
A code indicating whether the device has been tested or if testing is in progress. Valid values include the following:
|
|
| timeframes | array [DeviceTimeframes object] |
| 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.) |
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.
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
emailAddressfield 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] |
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" |
DeviceReference object
Device reference object
{
"id": "77c7ec54-8609-47da-9b6b-80d4b24bead1",
"recipientType": "DEVICE",
"name": "Home Email",
"deviceType": "EMAIL",
"owner":
{
"id": "031313cc-42d3-4703-a90e-36cc5f5f6209",
"targetName": "akaur",
"links":
{
"self": "/api/xm/1/people/031313cc-42d3-4703-a90e-36cc5f5f6209"
}
},
}
The reference to a device in xMatters returned when the device is a listed as a recipient on a form.
| id | string |
| The unique identifier of the device. | |
| recipientType | string |
| The type of this object. For devices, this value is "DEVICE". | |
| name | string |
| The name of the device. Example: "Work Email" or "Home Phone" |
|
| deviceType | string |
The type of device. Use one of the following values:
|
|
| owner | PersonReference object |
| A link to the person who owns the device. |
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?search="Phone Pager" "Work Device" GET /device-names?deviceTypes=FAX,ANDROID_PUSH,VOICE GET /device-names?sortBy=NAME&sortOrder=ASCENDING
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 list of search terms separated by the + sign or a space character. Searches are case-insensitive ("alert" finds "alert", "Alert", as well as "alerting") and must contain at least two characters. When two or more search terms are present, the result includes device names that match either search term. When your search term contains more than one word, or contains delimiting characters such as spaces, enclose the terms in double quotes to preserve the delimiters. Example: /device-names?search=phone pager returns all device names that contain either "phone" or "pager". However, searching /device-names?search="phone pager" returns all device names that contain "phone pager". |
|
| 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. |
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 |
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] |
| 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 | Boolean |
When true the device is selected when a user creates a message or subscription based on the form. |
|
| visible | Boolean |
When true the device is visible when a user creates a message or subscription based on the form. |
DEVICE TYPES
Device types, in conjuncton with device names, determine what kinds of devices users can be notified on and to standardize naming conventions for all users.
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 now called Dynamic Groups. You can create, edit, and search for dynamic groups through the Groups endpoint. The dynamic teams endpoints previously listed are now deprecated and are no longer available for use.
To view dynamic groups, see:
To create or modify dynamic groups, see:
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.
While we've renamed "events" to "alerts" in the web user interface, we are not changing any of the properties, values, or labels associated with events in the REST API. This ensures that your existing integrations and incoming signals will continue to function without interruption. For more information on the Events to Alerts change, see our Support site article.
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 with xMatters Flow Designer.
* 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,
"attachments": [],
"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
propertyNameandpropertyValuequery 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?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=properties,annotations,responseOptions,suppressions,attachments.size
GET /events?embed=responseOptions,responseOptions.translations
GET /events?embed=targetedRecipients
GET /events?eventType=SYSTEM,USER
GET /events?from=2017-05-01T14:00:00.000Z&to=2017-05-01T19:00:00.000Z
GET /events?incidentId=INC-1234
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?propertyName=customerAffected&propertyValue=false
GET /events?propertyName=animals,books&propertyValue=dogs,fiction&propertyValueOperator=EQUALS,CONTAINS
GET /events?priority=HIGH,MEDIUM,LOW
GET /events?requestId=5588db90-6b87-4662-9a2f-107d3bb233bf
GET /events?resolvedUsers=mmcbride,tsmith
GET /events?search=Database
GET /events?search=Database "Incident status"&fields=NAME
GET /events?sortBy=START_TIME&sortOrder=ASCENDING
GET /events?status=ACTIVE,SUSPENDED
GET /events?submitter=mmcbride
GET /events?targetedRecipients=c56730a9-1435-4ae2-8c7e-b2539e635ac6
GET /events?targetedRecipients=mmcbride,tsmith,jbrown
QUERY PARAMETERS
| 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.
|
|
| embed | string |
A comma-separated list of the objects to embed in the response.
|
|
| eventType | string |
The type of event to return in the results. Valid values are either:
|
|
| fields | string |
Defines the fields to search when a search term is specified. The only valid value is NAME, which limits the search results to the content of the event's "name" property, which are email subjects (for user events) or system event type (for system events). |
|
| 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. |
|
| 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 |
|
| incidentId | string |
The unique identifier (INC-1234) or UUID (id) of a single incident in xMatters. The response returns all events associated with the incident. |
|
| limit | integer |
| The number of items to return. See Pagination query parameters. | |
| offset | integer |
| The number of items to skip before returning results. See Pagination query parameters. | |
| 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). |
|
| 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 |
|
| 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. |
|
| 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. |
|
| 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. |
|
| search | string |
A list of search terms separated by the + sign or a space character. Searches are case-insensitive ("data" finds "data", "Data", as well as "database") and must contain at least two characters. When two or more search terms are present an "AND" search is performed and the result includes events that match all search terms. Use the fields parameter to expand or limit search results.When your search term contains more than one word, or contains delimiting characters such as spaces, enclose the terms in double quotes to preserve the delimiters. Example: /events?search=incident status&fields=NAME returns all events with names that contain either "incident" or "status". However, searching /events?search="incident status"&fields=NAME returns all events with names that contain "incident status". |
|
| 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:
|
|
| status | string |
The status of events that you want to return in the search results. Valid values include:
|
|
| submitter | string |
The unique identifier (id) or name (targetName) of the submitter. |
|
| targetedRecipients | string |
The targetName or id of users, groups, devices, or sites 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. |
|
| 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 |
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,
"attachments": [],
"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",
"groupType": "ON_CALL",
"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, sites, and devices that were included in the recipient list when the event was initiated. Targeted recipients include the names of groups 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 sites. 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,attachments.size,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 with xMatters Flow Designer.
* 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 with xMatters Flow Designer.
* 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 an event attachment
Get an event attachment
REQUEST Get an event attachment
curl --user username "https://acmeco.xmatters.com/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2/attachments/Company_Logo.jpg"
/**
* This script is configured to work with xMatters Flow Designer.
* 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/attachments/Company_Logo.jpg",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved attachment: " + 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"
attachmentId = "Company_Logo.jpg"
endpoint_URL = "/events/" + eventId + "/attachments/" + attachmentId
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 attachment 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
{
... a text representation of a jpg file ...
}
Returns a single attachment for a specific event so that you can download it or view it. If the attachment is a text file, the contents of the file are displayed in the response. Other file types must be saved to your computer to be opened with the viewer of your choice.
DEFINITION
GET /events/{eventId}/attachments/{attachmentId}
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. |
|
| attachmentId | string |
| The unique file name of the attached file. For example: "Mim_process_2.jpg", or "Customer Error Upload 1". |
RESPONSES
| Success | Response code 200 OK and the contents of the attachment 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 with xMatters Flow Designer.
* 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 |
A comma-separated list of the properties to embed in the response. Available property is:
|
|
| 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:
|
|
| deliveryStatus | string |
A comma separated list of delivery statuses. 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 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,
"attachments": [
{
"path": "attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/Company_Logo",
}
],
"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;
//Attachments
var attachments = [];
attachments.push({"path": "attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/Planned_Outage.png"});
trigger.attachments = attachments;
//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,
"attachments": [
{
"path": "attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/Company_Logo",
}
],
"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, and groups that will be notified by the event. If your form uses response counts you can set the number of required responses for each group 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 how many responses from the "Others" category are required. To specify the response count for a group, use the
responseCountThresholdfield in the recipients list. To specify the "others" response count, include theotherResponseCountThresholdfield. - 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 (
displayNameandcallerID) 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
| attachments | array [AttachmentReference object] |
The path to the xMatters temporary file storage facility where the file has been uploaded. You can attach a maximum of 10 files, and the size limit for each file is 10 MB. For a list of available file types, see Upload an attachment. |
|
| bypassPhoneIntro | Boolean |
| When this value is set to true, xMatters omits the standard voice greeting and plays the message immediately. See note. | |
| conference | ConferencePointer object |
| 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"} |
|
| escalationOverride | Boolean |
| When this value is set to true, xMatters ignores shift escalation delays and immediately broadcasts the message to all recipients. See note. | |
| expirationInMinutes | integer |
| The duration of the event in minutes. See note. | |
| otherResponseCountThreshold | integer |
| 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 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}] |
|
| 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. See note. | |
| priority | string |
The priority of the event. Valid values include the following:
|
|
| properties | PropertyValues object |
| Allows you to set the values of form properties. Text property translations are supported upon submission. See Text Property with Translation for the accepted format. | |
| recipients | array [RecipientTrigger object] |
| Specifies the people, devices, and groups 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 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. | |
| 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. See note. | |
| responseOptions | ResponseOptions object |
Overrides the form's response options.
|
|
| senderOverrides | SenderOverrides |
| 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. | |
| voicemailOptions | VoicemailOptions object |
| For voice notifications, this defines whether to try the call again or leave a message. 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 with xMatters Flow Designer.
* 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 with xMatters Flow Designer.
* 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"
}
]
},
"attachments": {
"count": 2,
"total": 2,
"data": [
{
"name": "MIM Error 1",
"path": "events/ced9fac9-1065-4659-82ab-1c9664a777b2/attachments/MIM Error 1",
"links":
{
"self": "/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2/attachments/MIM Error 1"
}
},
{
"name": "Customer_error_1",
"path": "/events/ced9fac9-1065-4659-82ab-1c9664a777b2/attachments/Customer_error_1",
"links":
{
"self": "/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2/attachments/Customer_error_1"
}
}
],
},
"incident":"INCIDENT_ID-408005",
"expirationInMinutes":180,
"eventId":"408005",
"requestId": "4cb646d0-488b-4745-844d-2814058f3578",
"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;"\></span>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. |
|
| attachments | AttachmentsReference objects |
| The files that are attached to the event. | |
| 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'. Whenthis 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. |
|
| requestId | string |
| The unique identifier returned from a request to trigger an event. | |
| 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 - without translations
{
"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"
}
]
}
Properties object - with text property translations
{
"myNumberProperty": {"value": 323423},
"myPasswordProperty": {"value": "ilovecats123"},
"myTextProperty": {
"value": "This is urgent. Please respond.",
"translations": {
"en": "This is urgent. Please respond.",
"fr": "C'est urgent. Répond s'il te plait."
}
},
"myListProperty": {"values":
[
"iOS",
"Android",
"Windows 10"
]
},
"myBooleanProperty": {"value": true},
"myComboProperty": {"value": "Oracle Database"},
"myHierarchyProperty": {"values":
[
{
"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 if the text property is submitted
without translations:
| Property Type | Description | Example |
|---|---|---|
| Number | An integer. | "myNumberProperty": 323423 |
| Text | A string. Text property names include the language code. | "myTextProperty#en": "This is urgent. 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"[
|
Text Property with Translations: The following table shows the format of each
property type if the text property is submitted with translations:
| Property Type | Description | Example |
|---|---|---|
| Number | An integer. | "myNumberProperty": {"value": 323423} |
| Text | A string. Text properties are made up of a value and any language the text property is translated
into. |
"myTextProperty": [
"value": "This is urgent. Please respond.", |
| Password | A string in plain text. | "myPasswordProperty": {"value": "ilovecats123"} |
| List | An array of strings that represent the selected choices. | "myListProperty": {"values": [
"listItem1", |
| Boolean | A Boolean value. | "myBooleanProperty": {"value": true} |
| Combo Box | A string that represents the selected choice. | "myComboProperty": {"value": "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": {"values": [
|
VoicemailOptions object
VoicemailOptions object
"voicemailOptions":
{
"retry": 0,
"every": 60,
"leave": "callbackonly",
"leaveOptions": [
{
"visible": true,
"selected": false,
"name": "CALLBACKANDMESSAGE"
},
{
"visible": true,
"selected": false,
"name": "MESSAGEONLY"
},
{
"visible": true,
"selected": true,
"name": "CALLBACKONLY"
},
{
"visible": true,
"selected": false,
"name": "HANGUP"
}
]
}
Voicemail Options settings configure the handling behavior for standard phone notifications and conference calls when voicemail is detected.
| retry | integer |
| The number of times to attempt to contact the user after reaching voicemail on the initial attempt. | |
| every | integer |
| The number of seconds to wait between retry attempts. | |
| leave | string |
The action to take when voicemail is detected and there are no more retry attempts. Valid values include (web user interface equivalent in brackets):
|
|
| leaveOptions | array [string] |
A list of options available for the leave parameter that includes the following properties:
|
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 theid 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, mobileapps, 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. Text property translations are supported upon submission. See Text Translations for the accepted format. | |
| 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 recipient.
| id | string |
| The target name or unique identifier of the recipient. | |
| recipientType | string |
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. This value applies only to group 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, or device 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 with xMatters Flow Designer.
*/
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. |
EXTERNAL CONFERENCE BRIDGES
You can preconfigure external conference bridges in xMatters and add them to messaging forms. Recipients with voice devices will be prompted to connect directly to the conference bridge by pressing a number on their keypad.
This endpoint describes how to create, modify, retrieve, and delete information about your external conference bridge configuratons in xMatters.
For more information see the external conference bridges in the online help.
Get conference bridges
Get conference bridges
REQUEST (get all external conference bridge configurations in your system)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/conference-bridges"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/conference-bridges",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved conference bridges");
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/conference-bridges"
url = base_URL + endpoint_URL
response = requests.get(url, auth=("username", "password"))
responseCode = response.status_code
if responseCode == 200:
print("Retrieved conference bridges " + response.json())
rjson = response.json()
for d in rjson.get("data"):
print('Found conference bridges.')
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": "bb7ad81d-5e7b-4b1d-b448-1aa6913be2ac",
"name": "INC-211 Zoom Conference",
"description": "Call to discuss incident 211 and restore services",
"tollNumber": "1-877-394-2905",
"tollFreeNumber": "1-888-223-4343",
"preferredConnectionType": "TOLL_FREE",
"pauseBeforeBridgePrompt": 3,
"staticBridgeNumber": false,
"links": {
"self": "/api/xm/1/conference-bridges/bb7ad81d-5e7b-4b1d-b448-1aa6913be2ac"
}
},
{
"id": "3f46b435-919c-4802-a653-eaeb300d201c",
"name": "INC-201 webex Conference",
"description": "Sev-1 main server down",
"tollNumber": "1-877-384-905",
"tollFreeNumber": "1-888-223-4343",
"preferredConnectionType": "TOLL_FREE",
"pauseBeforeBridgePrompt": 1,
"staticBridgeNumber": false,
"meetingLink": "https://mywebexlink.com/",
"links": {
"self": "/api/xm/1/conference-bridges/3f46b435-919c-4802-a653-eaeb300d201c"
}
}
],
"links": {
"self": "/api/xm/1/conference-bridges?offset=0&limit=100"
}
}
Returns all external conference bridge configurations in your system.
To return information about a single conference bridge, use Get a conference bridge.
DEFINITION
GET /conference-bridges
GET /conference-bridges?search=zoom meeting
GET /conference-bridges?search="zoom meeting"&fields=DESCRIPTION
GET /conference-bridges?search="1-(800)-555-1234"&fields=TOLL_FREE
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. | |
| search | string |
| A list of search terms separated by the + sign or a space character. Searches are case-insensitive ("alert" finds "alert", "Alert", as well as "alerting") and must contain at least two characters. When two or more search terms are present, the result includes conference bridges that match either search term. When your search term contains more than one word, or contains delimiting characters such as spaces, enclose the terms in double quotes to preserve the delimiters. Example: /conference-bridges?search=zoom meeting returns all conference bridges that contain either "zoom" or "meeting". However, searching /conference-bridges?search="zoom meeting" returns all conference bridges that contain "zoom meeting". |
|
| fields | string |
| Defines the field to search when a search term is specified. When not specified, all fields are searched. Valid values include: NAME, DESCRIPTION, BRIDGE_NUMBER, TOLL_NUMBER, TOLL_FREE. | |
| 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. |
RESPONSES
| Success | Response code 200 OK and a list of Conference Bridge objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a conference bridge
Get a conference bridge
REQUEST Get an external conference bridge
curl --user username
"https://acmeco.xmatters.com/api/xm/1/conference-bridges/7596f0d8-89e1-49e8-b841-ada1c513417c"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/conference-bridges/7596f0d8-89e1-49e8-b841-ada1c513417c",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved conference bridges");
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/conference-bridges/7596f0d8-89e1-49e8-b841-ada1c513417c"
url = base_URL + endpoint_URL
response = requests.get(url, auth=("username", "password"))
responseCode = response.status_code
if responseCode == 200:
print("Retrieved conference bridges " + response.json())
rjson = response.json()
for d in rjson.get("data"):
print(f”Found conference bridges. {d[‘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)
)
RESPONSE
{"count": 1,
"total": 1,
"data": [
{
"id": "7596f0d8-89e1-49e8-b841-ada1c513417c",
"name": "Sev-1 Zoom Conference",
"description": "Main server down. MIM team call in using this number.",
"tollNumber": "1-877-394-2905",
"tollFreeNumber": "1-888-223-4343",
"preferredConnectionType": "TOLL_FREE",
"pauseBeforeBridgePrompt": 3,
"staticBridgeNumber": false,
"meetingLink": "https://myzoomlink.com/",
"links": {
"self": "/api/xm/1/conference-bridges/7596f0d8-89e1-49e8-b841-ada1c513417c"
}
}
}
Returns a specific external conference bridge configuration in your system. Users must have roles that give sufficient permission to view or edit data.
DEFINITION
GET /conference-bridges/{bridgeId}
URL PARAMETERS
| bridgeId | string |
The unique identifier (id) of the conference bridge to retrieve. |
RESPONSES
| Success | Response code 200 OK and a Conference Bridge object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create an external conference bridge
Create an external conference bridge
REQUEST - Create an external conference bridge
curl --user username --header "Content-Type: application/json" --request POST -d '{
"name": "INC-211 Zoom Conference",
"description": "Call to discuss incident 211 and restore services",
"tollNumber": "1-877-394-2905",
"tollFreeNumber": "1-888-223-4343",
"preferredConnectionType": "TOLL_FREE",
"pauseBeforeBridgePrompt": "3"
"meetingLink": "https://myzoomlink.com/",
}' "https://acmeco.xmatters.com/api/xm/1/conference-bridges"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/conference-bridges/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.name = 'INC-211 Zoom Conference';
data.description = 'Call to discuss incident 211 and restore services';
data.tollNumber = '1-877-394-2905';
data.tollFreeNumber = '1-888-223-4343';
data.preferredConnectionType = 'TOLL_FREE';
data.pauseBeforeBridgePrompt = '3';
data.meetlingLink = ' "https://myzoomlink.com/';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created " + 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 = "/conference-bridges"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
conference_data = {
"name": "INC-211 Zoom Conference",
"description": "Call to discuss incident 211 and restore services",
"tollNumber": "1-877-394-2905",
"tollFreeNumber": "1-888-223-4343",
"preferredConnectionType": "TOLL_FREE",
"pauseBeforeBridgePrompt": "3"
"meetingLink": "https://myzoomlink.com/",
}
response = requests.post(url, headers=headers, json=conference_data, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print ("Created " + response.json()["targetName"] + ". id = " + response.json()[
"id")
]
RESPONSE
{
"id": "bb7ad81d-5e7b-4b1d-b448-1aa6913be2ac",
"name": "INC-211 Zoom Conference",
"description": "Call to discuss incident 211 and restore services",
"tollNumber": "1-877-394-2905",
"tollFreeNumber": "1-888-223-4343",
"preferredConnectionType": "TOLL_FREE",
"pauseBeforeBridgePrompt": 3,
"staticBridgeNumber": false,
"meetingLink": "https://myzoomlink.com/",
"links": {
"self": "/api/xm/1/conference-bridges/bb7ad81d-5e7b-4b1d-b448-1aa6913be2ac"
}
}
Creates the configuration for an external conference bridge in your system. Creating the conference bridge configuration does not automatically initiate a conference bridge. Once created, you can use the external conference bridge with messaging forms and events in your system.
For more information on conference bridges, see the online help.
DEFINITION
POST /conference-bridges
BODY PARAMETERS
| id | string |
The unique identifier (id) of the conference bridge. Required when modifying an existing conference bridge. |
|
| name | string |
| The unique name for the conference bridge. | |
| description | string |
| A description of the conference bridge that provides users with additional information about the purpose of the confererence bridge. | |
| tollNumber | string |
| The toll number used to connect to the conference bridge. | |
| tollFreeNumber | string |
| The toll-free number used to connect to the conference bridge. | |
| preferredConnectionType | string |
The preferreed connection type. Valid values are: TOLL and TOLL_FREE. |
|
| pauseBeforeBridgePrompt | integer |
| The number of seconds to wait after connecting to the conference provider before dialing the bridge number. Use this setting to wait for the system to finish playing greetings before dialing the bridge number. | |
| staticBridgeNumber | Boolean |
When true, the same bridgeNumber is used for every conference bridge. Use bridgeNumber to specify the conference bridge number. The default value is false. |
|
| bridgeNumber | integer |
The number that identifies the conference to the conference bridge provider. This field is required when the staticBridgeNumber is set to true and optional when the staticBridgeNumber is set to false. |
|
| meetingLink | string |
The URL used to connect to the conference bridge.
dialAfterBridge | string
| This setting allows you to dial more digits, characters, and pauses after the bridge number. You can use this field to navigate menus or provide other information that you are prompted for after entering the conference bridge number. This field accepts the characters #, *, and w and the digits 0-9, where the w character denotes a 1-second pause. For example, to wait 5 seconds, dial 1, wait 4 more seconds and then dial #, type wwwww1wwww# in this field.
RESPONSES
| Success | Response code 201 Created and a Conference Bridge object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a conference bridge
Modify a conference bridge
REQUEST (modify an existing external conference bridge configuration)
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "7596f0d8-89e1-49e8-b841-ada1c513417c",
"name": "INC-211 Zoom Conference",
"description": "Call to discuss incident 211 and restore services",
"tollNumber": "1-877-394-2905",
"tollFreeNumber": "1-888-223-4343",
"preferredConnectionType": "TOLL_FREE",
"pauseBeforeBridgePrompt": "3"
"meetingLink": "",
}' "https://acmeco.xmatters.com/api/xm/1/conference-bridges"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/conference-bridges/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '7596f0d8-89e1-49e8-b841-ada1c513417c',
data.name = 'INC-211 Zoom Conference';
data.description = 'Call to discuss incident 211 and restore services';
data.tollNumber = '1-877-394-2905"';
data.tollFreeNumber = '1-888-223-4343';
data.preferredConnectionType = 'TOLL_FREE';
data.pauseBeforeBridgePrompt = '3';
data.meetingLink = '';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Modified " + 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 = "/conference-bridges"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"id": "7596f0d8-89e1-49e8-b841-ada1c513417c",
"name": "INC-211 Zoom Conference",
"description": "Call to discuss incident 211 and restore services",
"tollNumber": "1-877-394-2905",
"tollFreeNumber": "1-888-223-4343",
"preferredConnectionType": "TOLL_FREE",
"pauseBeforeBridgePrompt": "3"
"meetingLink": "",
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print ("Created " + response.json()["targetName"] + ". id = " + response.json()[
"id")
]
RESPONSE
{
"id": "7596f0d8-89e1-49e8-b841-ada1c513417c",
"name": "INC-211 Zoom Conference",
"description": "Call to discuss incident 211 and restore services",
"tollNumber": "1-877-394-2905",
"tollFreeNumber": "1-888-223-4343",
"preferredConnectionType": "TOLL_FREE",
"pauseBeforeBridgePrompt": 3,
"staticBridgeNumber": false,
"meetingLink": "",
"links": {
"self": "/api/xm/1/conference-bridges/bb7ad81d-5e7b-4b1d-b448-1aa6913be2ac"
}
}
Changes the properties of an existing external conference bridge.
Identify the conference bridge by providing its unique identifier in the id field, and then provide the fields that you want to modify.
You can obtain the id field of a conference bridge from the Conference Bridges object returned when retrieving or creating a conference bridge.
If the id field is not provided in the request body, xMatters interprets this as a request to create a new conference bridge.
DEFINITION
POST /conference-bridges
BODY PARAMETERS
The only required body parameter is the UUID of the group you want to update. See the Create a conference bridge for details on the other available parameters.
| id | string |
The unique identifier (id) of the conference bridge you want to modify. |
RESPONSES
| Success | Response code 201 Created and a Conference Bridge object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a conference bridge
Delete a conference bridge
REQUEST: Delete a confierence bridge using its id.
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/conference-bridges/bb7ad81d-5e7b-4b1d-b448-1aa6913be2ac"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/conference-bridges/bb7ad81d-5e7b-4b1d-b448-1aa6913be2ac",
"method": "DELETE",
"headers" : {"Content-Type": "application/json"}
});
response = request.write();
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log("Deleted the : " + json.targetName);
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/conference-bridges/bb7ad81d-5e7b-4b1d-b448-1aa6913be2ac"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.delete(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
print ("Deleted " + response.json()["targetName"])
RESPONSE
{
"id": "bb7ad81d-5e7b-4b1d-b448-1aa6913be2ac",
"name": "INC-211 Zoom Conference",
"description": "Call to discuss incident 211 and restore services",
"tollNumber": "1-877-394-2905",
"tollFreeNumber": "1-888-223-4343",
"preferredConnectionType": "TOLL_FREE",
"pauseBeforeBridgePrompt": 3,
"staticBridgeNumber": false,
"meetingLink": "https://myzoomlink.com/",
"links": {
"self": "/api/xm/1/conference-bridges/bb7ad81d-5e7b-4b1d-b448-1aa6913be2ac"
}
}
Deletes an external conference bridge from the xMatters system. The conference bridge is also deleted from any form or scenario where it is used.
To use this method, you must know the unique identifier (id) of the conference bridge and you must have the appropriate permissions to delete data. You can obtain the id from the response of Get external conference bridges.
DEFINITION
DELETE /conference-bridges/{bridgeID}
URL PARAMETERS
| id | string |
The unique identifier (id) or targetName of the conference bridge to delete. |
RESPONSES
| Success | Response code 200 OK and a Conference Bridge object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Conference Bridge objects
Conference Bridge object
Conference Bridge object
{
"id": "7596f0d8-89e1-49e8-b841-ada1c513417c",
"name": "INC-26 webex Conference",
"description": "test 1",
"tollNumber": "1-877-384-905",
"tollFreeNumber": "1-888-223-4343",
"preferredConnectionType": "TOLL_FREE",
"pauseBeforeBridgePrompt": 1,
"bridgeNumber": "19772343957",
"dialAfterBridge": "wwwww1wwww#",
"staticBridgeNumber": true,
"meetingLink": "https://mywebexlink.com/",
"links": {
"self": "/api/xm/1/conference-bridges/7596f0d8-89e1-49e8-b841-ada1c513417c"
}
}
Describes a reference to an external conference bridge configuration, including its name and unique identifier.
| id | string |
The unique identifier (id) of the conference bridge. |
|
| name | string |
| The unique name for the conference bridge. | |
| description | string |
| A description of the conference bridge that provides users with additional information about the purpose of the confererence bridge. | |
| tollNumber | string |
| The toll number used to connect to the conference bridge. | |
| tollFreeNumber | string |
| The toll-free number used to connect to the conference bridge. | |
| preferredConnectionType | string |
The preferreed connection type. Valid values are: TOLL and TOLL_FREE. |
|
| pauseBeforeBridgePrompt | integer |
| The number of seconds to wait after connecting to the conference provider before dialing the bridge number. Use this setting to wait for the system to finish playing greetings before dialing the bridge number. | |
| staticBridgeNumber | Boolean |
When true the same bridgeNumber is used for every conference bridge. Use bridgeNumber to specify the conference bridge number. The default value is false. |
|
| bridgeNumber | integer |
The number that identifies the conference to the conference bridge provider. This field is required when the staticBridgeNumber is set to true and optional when the staticBridgeNumber is set to false. |
|
| meetingLink | string |
The URL used to connect to the conference bridge. dialAfterBridge | string | This setting allows you to dial more digits, characters, and pauses after the bridge number. You can use this field to navigate menus or provide other information that you are prompted for after entering the conference bridge number. This field accepts the characters # * w and the digits 0-9, where the w character denotes a 1-second pause. For example, to wait 5 seconds, dial 1, wait 4 more seconds and then dial #, type wwwww1wwww# in this field.
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 with xMatters Flow Designer.
*/
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
GET /forms?search=IT alert&operand=AND
GET /forms?search="IT alert" "system alert"&operand=AND&fields=DESCRIPTION
GET /forms?embed=recipients,scenarios
GET /forms?enabledFor=MOBILE
GET /forms?plans.planType=RESERVED
GET /forms?sortBy=NAME&sortOrder=ASCENDING
GET /forms?triggerType=FLOW
QUERY PARAMETERS
| search | string |
A list of search terms separated by the + sign or a space character. Searches are case-insensitive ("alert" finds "alert", "Alert", as well as "alerting") and must contain at least two characters. When two or more search terms are present, the result includes forms that match either search term. The results include forms with the search term in the NAME, DESCRIPTION, or WORKFLOW fields.Use the operand and fields query parameters to expand or limit search results. When the search, operand=AND, and fields parameters are combined in one query, the operand=AND applies only to the search terms; the fields parameter remains an OR search.Example: GET /forms/?search=IT alert&operand=AND&fields=NAME,DESCRIPTION returns all forms that have both "IT" and "alert" in either the name or description fields. So "IT Emergency Alert" would be returned, but "Web Emergency Alert" would not.When your search term contains more than one word, or contains delimiting characters such as spaces, enclose the terms in double quotes to preserve the delimiters. Example: /forms?search=IT alert&fields=NAME returns all forms with names that contain either "IT" or "alert". However, searching /forms?search="IT alert"&fields=NAME returns all forms with names that contain "IT alert". |
|
| operand | string |
Applied to the provided search terms to limit or expand the search query parameter. Available options include: AND or OR. AND only returns forms that have all search terms in the specified fields. OR returns forms that have any of the search terms in the specified fields; this is the default if you don’t specify an operand. The operand is case-sensitive; entering lowercase "and" will return an error. |
|
| 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.
|
|
| enabledFor | string |
Returns all the forms that are enabled for a specific component. Valid values include:
|
|
| plans.planType | string |
Filters forms by the type of the associated workflow. Valid values include:
|
|
| 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:
|
|
| triggerType | array[string] |
Returns forms by trigger type. 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 with xMatters Flow Designer.
*/
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?enabledFor=MOBILE
GET /plans/{planId}/forms?sortBy=NAME,USER_DEFINED&sortOrder=ASCENDING
GET /plans/{planId}/forms?triggerType=FLOW
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.
|
|
| enabledFor | string |
Returns only the forms in the plan that are enabled for a specific component. Valid values include:
|
|
| 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:
|
|
| triggerType | array [string] |
Returns forms by trigger type. Valid values include:
If no values are specified, or if the parameter is not specified, both types of forms are returned. |
|
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 with xMatters Flow Designer.
* 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.
To simplify requests for this endpoint, we've introduced the forms/{formId} alias. This alias abbreviates the required nested paths, and works with all query parameters.
DEFINITION
GET /forms/{formId} GET /forms/{formId}/sender-permissions GET /forms/{formId}/recipients GET /plans/{planId}/forms/{formId} GET /plans/{planId}/forms/{formId}/recipients GET /plans/{planId}/forms/{formId}/sender-permissions 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. The use of formId in the definition refers specifically to the UUID of a form and not to the six-digit legacy form identifier. Using the legacy identifier will result in an error. |
QUERY PARAMETERS
| recipients | string |
The targetName or id of the users, groups, or devices 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 message templates
GET form message templates
REQUEST - Get all message templates for a specific form.
shell curl --user username "https://acmeco.xmatters.com/api/xm/1/forms/07090eb4-b49f-4e27-b730-10ef5683369b/message-templates"
/**
* This script is configured to work with xMatters Flow Designer.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/07090eb4-b49f-4e27-b730-10ef5683369b/message-templates"
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " form message templates." );
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 + '/message-templates'
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 message templates.' )
print ( '\nThe message templates 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
{
"email": [
{
"subject": "${BD712711-5624-4094-908C-E2F452A72C2C} Incident Bridge ",
"body": "Join the conference bridge by calling ${xm.tollFreeNumber} (${xm.tollNumber} from outside of U.S.) and use the following bridge number: ${xm.bridgeNumber}.<div><br><div>${30F78545-0BF3-4013-83A0-F89622B019EA}<br></div><div><br></div><div>Incident Type: ${BD712711-5624-4094-908C-E2F452A72C2C}</div><div>Incident Impact: ${26EA66F4-DD02-4BB8-AC34-16B23E40EF86}</div><div>Services: ${C95DDBC4-BC94-4F53-B384-94D402D76FE7}</div></div>",
"language": "en"
}
],
"sms": [
{
"text": "${BD712711-5624-4094-908C-E2F452A72C2C} Bridge created: ${xm.bridgeNumber}. Call-in number is: ${xm.tollFreeNumber} (${xm.tollNumber} outside U.S.)\n\n\n${xm.tollFreeNumber},,,${xm.bridgeNumber}#\n",
"language" : "en"
}
],
"voice": [
{
"steps": [
{
"id": "083544f8-15ea-409c-bed3-d70eeca03808",
"stepType": "PHRASE",
"playBack": "PHRASE",
"phrase": "Emergency Change Request"
},
{
"id": "ac5bab05-85a1-4197-92e3-823045028633",
"stepType": "PHRASE",
"playBack": "PHRASE",
"phrase": "has been created for C I"
},
{
"id": "0ced119f-d7e7-41d2-9906-ff92c45d8c90",
"stepType": "FORM_PROPERTY",
"playBack": "PHRASE",
"formProperty": {
"id": "1a2bc1ab-eec2-49c9-864e-f08cd49ccf03"
}
},
{
"id": "d5405cce-8193-45aa-8fb9-c94f428549e8",
"stepType": "PHRASE",
"playBack": "PHRASE",
"phrase": "with an impact of "
},
{
"id": "13957a53-2c58-476d-8fb1-8fe76e4f0061",
"stepType": "FORM_PROPERTY",
"playBack": "PHRASE",
"formProperty": {
"id": "52e3645f-be0c-4c45-8cdf-c5720640ea3f"
}
},
{
"id": "3d2df6da-4553-4319-accb-80d43b55ab98",
"stepType": "PHRASE",
"playBack": "PHRASE",
"phrase": "and a short description of"
},
{
"id": "8bc0b15d-9228-4b30-b71c-360b9c808540",
"stepType": "FORM_PROPERTY",
"playBack": "PHRASE",
"formProperty": {
"id": "e0d17510-8bbd-4c34-9428-786dfbdacc37"
}
}
],
}
],
Returns the message templates for email, SMS, and voice devices for a form in a communication plan.
For more information and best practices on the various message templates, see the online help for Voice messages, Email messages, or SMS messages.
DEFINITION
GET /forms/{formId}/message-templates
URL PARAMETERS
| formId | string |
| The unique identifier (id) or name (targetName) of the form you want to retrieve. Names must be URL-encoded. |
RESPONSES
| Success | Response code 200 OK and the Message Template Form section objects 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 with xMatters Flow Designer.
*/
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 GET /plans/{planId}/forms/{formId}/response-options?embed=translations GET /forms/{formId}/response-options?embed=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 (UUID) or name (targetName) of the form you want to retrieve. Names must be URL-encoded. The use of formId in the definition refers specifically to the UUID of a form and not to the six-digit legacy form identifier. Using the legacy identifier will result in an error. |
QUERY PARAMETERS
| embed | string |
A comma-separated list of objects to embed in the response. Supported value is:
|
|
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 form in your system
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/89a37590-83b7-4839-aa0d-fd3550d63ab7/sections"
/**
* This script is configured to work with xMatters Flow Designer.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7/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 = '89a37590-83b7-4839-aa0d-fd3550d63ab7'
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": 3,
"total": 3,
"data": [
{
"id": "b380c341-b947-49cf-88a0-7574ba406566",
"form": {
"id": "89a37590-83b7-4839-aa0d-fd3550d63ab7",
"visibility": "VISIBLE",
"links": {
"self": "/api/xm/1/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7"
}
},
"title": "Recipients",
"type": "RECIPIENTS",
"visible": true,
"collapsed": false,
"orderNum": 0,
"enableResponseCounts": false,
"recipients": {
"count": 0,
"total": 0,
"data": [],
"links": {
"self": "/api/xm/1/forms/2f25e266-a7cf-42cc-9741-dd9cf78bdf63/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7/recipients?offset=0&limit=100"
}
},
"searchableTypes": {
"devices": true,
"dynamicTeams": true,
"groups": true,
"services": true,
"sites": false,
"users": true
},
"expandableGroups": true
},
{
"id": "b1c4f3e1-870b-494f-be9d-ee5b302172a5",
"form": {
"id": "89a37590-83b7-4839-aa0d-fd3550d63ab7",
"visibility": "VISIBLE",
"links": {
"self": "/api/xm/1/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7"
}
},
"title": "Custom Section",
"type": "CUSTOM_SECTION",
"visible": true,
"collapsed": false,
"orderNum": 1
},
{
"id": "e1104a34-d570-45a2-b685-b725d29d193e",
"form": {
"id": "89a37590-83b7-4839-aa0d-fd3550d63ab7",
"visibility": "VISIBLE",
"links": {
"self": "/api/xm/1/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7"
}
},
"title": "Handling",
"type": "HANDLING_OPTIONS",
"visible": true,
"collapsed": false,
"orderNum": 2,
"priority": {
"visible": true,
"orderNum": 0,
"value": "Low"
},
"expiration": {
"visible": true,
"orderNum": 1,
"duration": 3,
"unit": "MINUTES"
},
"expirationInMinutes": {
"visible": true,
"orderNum": 1,
"value": 3
},
"overrideDeviceRestrictions": {
"visible": true,
"orderNum": 2,
"value": true
},
"escalationOverride": {
"visible": true,
"orderNum": 3,
"value": true
},
"bypassPhoneIntro": {
"visible": true,
"orderNum": 4,
"value": true
},
"requirePhonePassword": {
"visible": true,
"orderNum": 5,
"value": true
},
"voicemailOptions": {
"retry": 2,
"every": 60,
"leave": "callbackonly",
"visible": true,
"selected": false,
"leaveOptions": [
{
"visible": true,
"selected": false,
"name": "CALLBACKANDMESSAGE"
},
{
"visible": true,
"selected": true,
"name": "MESSAGEONLY"
},
{
"visible": true,
"selected": false,
"name": "CALLBACKONLY"
},
{
"visible": true,
"selected": false,
"name": "HANGUP"
}
],
"orderNum": 6
}
}
],
"links": {
"self": "/api/xm/1/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7/sections?offset=0&limit=100"
}
}
Returns information on the sections used in a form. The available form sections are:
- Conference Bridge
- Custom Section
- Devices
- Handling
- Recipients
- Sender Overrides
- Attachments
- Response Overrides
Available recipient information includes their unique identifierId, recipientType, targetName, and more depending on the recipient type.
For more information on form layout and the available sections, see Design your form's layout in the online help.
DEFINITION
GET /forms/{formId}/sections
GET /forms/{formId}/sections?embed=voicemailOptions.leaveOptions
URL PARAMETERS
| formId | string |
The unique identifier (UUID) or name (targetName) of the form you want to retrieve. Names must be URL-encoded. The use of formId in the definition refers specifically to the UUID of a form and not to the six-digit legacy form identifier. Using the legacy identifier will result in an error. |
BODY PARAMETERS
| embed | string |
| Available only for Voicemail Options. Provides information on the options available for when a call is answered by an answering machine or voicemail system. Available value is: voicemailOptions.leaveOptions. | |
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. |
Create a plan form
Create a plan form
REQUEST - Create a plan form with a description.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"name": "MIM Playbook 1",
"description": "Use this form for Sev-1 problems."
}
' "https://acmeco.xmatters.com/api/xm/1/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.name = 'MIM Playbook 1';
data.description = 'Use this form for Sev-1 problems.';
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Created form " + json.targetName + ". ID = "+ json.id);
}
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms"
url = base_URL + endpoint_URL
payload = {
"name": "MIM Playbook 1",
"description": "Use this form for Sev-1 problems."
}
response = requests.post(url, json=payload, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Created communication plan form.")
RESPONSE
{
"id": "092ae177-3698-4fb7-ae92-1ee5a837c721",
"formId": "134480",
"name": "MIM Playbook 1",
"description": "Use this form for Sev-1 troubleshooting problems.",
"triggerType": "MESSAGING",
"mobileEnabled": false,
"uiEnabled": false,
"apiEnabled": false,
"recipients": {
"count": 0,
"total": 0,
"data": [],
"links": {
"self": "/api/xm/1/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms/092ae177-3698-4fb7-ae92-1ee5a837c721/recipients?offset=0&limit=100"
}
},
"plan": {
"id": "271283e2-7a31-41f7-99a4-e81c1a58af20",
"name": "Major Incident Playbook",
"planType": "PLAN"
},
"scenarios": {
"count": 0,
"total": 0,
"data": [],
"links": {
"self": "/api/xm/1/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms/092ae177-3698-4fb7-ae92-1ee5a837c721/scenarios?offset=0&limit=100"
}
},
"responseOptions": {
"count": 0,
"total": 0,
"data": [],
"links": {
"self": "/api/xm/1/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms/092ae177-3698-4fb7-ae92-1ee5a837c721/response-options?offset=0&limit=100"
}
},
"links": {
"self": "/api/xm/1/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms/092ae177-3698-4fb7-ae92-1ee5a837c721"
}
}
Create a form for a plan. You can then use the form to define the messages that are sent to recipients during an event or incident.
DEFINITION
POST /plans/{planId}/forms
URL PARAMETERS
| {planID} | string |
The unique identifier (id) or name (targetName) of the plan. |
BODY PARAMETERS
| name | string |
| required | The name of the form in the plan. |
| description | string |
| The description of the form in the plan. | |
| triggerType | string |
The trigger type of the form in the plan. Valid values include:
If the parameter is not specified, the default trigger type is MESSAGING. |
|
| mobileEnabled | Boolean |
If true the form is enabled for mobile devices upon creation. If false the form is not immediately enabled, and must be manually enabled later. The default value upon creation is false, which allows you to build forms before enabling them for use. |
|
| uiEnabled | Boolean |
If true the form is enabled in the web user interface upon creation. If false the form is not immediately enabled, and must be manually enabled later. The default value upon creation is false, which allows you to build forms before enabling them for use. |
|
| apiEnabled | Boolean |
If true the form is enabled for API use upon creation. If false the form is not immediately enabled, and must be manually enabled later. The default value upon creation is false, which allows you to build forms before enabling them for use. |
RESPONSES
| Success | Response code 201 Created and a Form objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create form message templates
Create a voice message template for a form
curl --user username --header "Content-Type: application/json" --request POST -d '{
{
"voice": {
"steps": [
{
"stepType": "PHRASE",
"playStyle": "PHRASE",
"phrase": "Hello. Review and respond to this new incident."
},
{
"stepType": "COMMON_PROPERTY",
"playStyle": "PHRASE",
"commonProperty": "PERSON_ALERT_CONTEXT"
},
{
"stepType": "FORM_PROPERTY",
"playStyle": "PHRASE",
"formProperty":{
"name": "Short Description"
}
}
],
"language": "en"
}
}' "https://acmeco.xmatters.com/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates"
/**
* This script is configured to work with xMatters Flow Designer.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var stepType = {};
stepType.phrase = {};
stepType.phrase.playback = 'phrase';
stepType.phrase = "Hello. You're needed for a new incident.";
stepType['common-property'] = {}
stepType['common-property'].playback = 'phrase';
stepType['common-property'].commonProperty = 'PERSON_ALERT_CONTEXT';
stepType['form-property'] = {}
stepType['form-property'].playback = 'phrase';
stepType['form-property'].formProperty = 'PERSON_ALERT_CONTEXT';
stepType['form-property'].formProperty.name = 'Short Description';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created message template: " + 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 = "/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = [
{
"stepType": "PHRASE",
"playStyle": "PHRASE",
"phrase": "Hello. Review and respond to this new incident."
},
{
"stepType": "COMMON_PROPERTY",
"playStyle": "PHRASE",
"commonProperty": "PERSON_ALERT_CONTEXT"
},
{
"stepType": "FORM_PROPERTY",
"playStyle": "PHRASE",
"formProperty":{
"name": "Short Description"
}
}
]
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print(
"Created message template "
+ response.json()["targetName"]
+ ". id = "
+ response.json()["id"]
)
else:
print("Error: Response code is: " + str(responseCode))
Create an SMS message template for a form
curl --user username --header "Content-Type: application/json" --request POST -d '{
{
"sms": [
{
"text": "Hello. You’re needed for an incident in xMatters.",
"language" : "en"
}
],
}' "https://acmeco.xmatters.com/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates"
/**
* This script is configured to work with xMatters Flow Designer.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {
text: “Hello. You’re needed for an incident in xMatters.”,
language: “en”,
};
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created message template: " + 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 = "/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"text": "Hello. You’re needed for an incident in xMatters.",
"language" : "en"
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print(
"Created message template "
+ response.json()["targetName"]
+ ". id = "
+ response.json()["id"]
)
else:
print("Error: Response code is: " + str(responseCode))
Create an email message template for a form
curl --user username --header "Content-Type: application/json" --request POST -d '{
{
"email": [
{
"subject": "An xMatters incident requires your attention.",
"body": "<link rel=\"stylesheet\" type=\"text/css\" href=\"https://static.xmatters.com/integrations/common/css/primary_table-7.css\">\n<style>\n /* common overrides for specific elements */\n body {\n font-family: \"Gotham SSm A\", \"Gotham SSm B\", verdana, sans-serif;\n }\n\n a, a:hover, a:focus {\n color: #0098cc;\n text-decoration: none;\n }\n\n .body-table {\n font-size: 16px; \n color: #444444; \n border-collapse: collapse; \n margin: 0;\n }\n\n .primary-container {\n display: inline-block; \n max-width: 800px;\n }\n\n .primary-table {\n border: solid 1px #e4e4e4;\n font-size: 14px; \n color: #444444; \n margin: 0; \n border-collapse: collapse;\n }\n\n .primary-table tr:first-of-type td {\n padding-top: 15px;\n }\n\n /* useful classes for various components */\n .background-dark {\n background-color: #f6f6f6;\n }\n\n .background-light {\n background-color: #fcfcfc; \n }\n\n .width-full {\n width: 100%;\n }\n\n .align-left {\n text-align: left;\n }\n\n .align-center {\n text-align: center;\n }\n\n .padding-none {\n padding: 0;\n }\n\n .padding-standard {\n padding: 5px 10px;\n }\n\n .border-none {\n border: 0;\n }\n\n /* Embedded specific stylings */\n div.embedded table {\n text-align: left;\n font-size: 14px; \n color: #444444; \n background-color: #fcfcfc; \n padding: 0; \n margin: 0; \n border: 0; \n border-collapse: collapse;\n width: 100%;\n }\n\n div.embedded table tr:last-of-type {\n border: 0;\n }\n\n div.embedded table tr:last-of-type td {\n border: 0;\n }\n\n div.embedded table tr {\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr:first-of-type td {\n padding-top: 10px;\n }\n\n div.embedded table tr td {\n padding: 10px 10px;\n /* needed to override in-browser message content default styles */\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr td h1 {\n font-size: 14px;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td h2 {\n font-size: 14px;\n color: #777777;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td p {\n color: #444444;\n margin: 0;\n }\n</style>\n\n<table class=\"body-table width-full align-center background-dark border-none padding-none\" id=\"table-6\">\n <tbody>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"><img alt=\"xMatters\" src=\"https://static.xmatters.com/integrations/common/images/xmatters_logo-1.png\" height=\"35px\"></td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\">Emergency Change Request</td>\n </tr>\n <tr>\n <td class=\"border-none\" tabindex=\"0\">\n <div class=\"width-full align-center\">\n <div class=\"primary-container width-full\">\n <table class=\"primary-table width-full align-left background-light padding-none\" id=\"table-7\">\n <tbody>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Number</strong></div>\n <div>${CB9D3E97-B46A-404C-B0E7-76DD8C099DFF}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Severity</strong></div>\n <div>${9BA4916A-E8B3-462D-A07D-0EA3CE52489A}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Impact</strong></div>\n <div>${52E3645F-BE0C-4C45-8CDF-C5720640EA3F}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Impacted CI</b></div>\n <div>${1A2BC1AB-EEC2-49C9-864E-F08CD49CCF03}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Short Description</b></div>\n <div>${E0D17510-8BBD-4C34-9428-786DFBDACC37}<br></div><div></div>\n </td>\n </tr>\n<tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Playbook details</b></div>\n <div>This is the notification sent from xMatters when it receives the alert from your ITSM application.<br>Use the response options below to move the workflow forward.<br></div><div></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Next Steps</strong></div>\n <div>Click <a href=\"http://www.xmatters.com/integration-results/?_sft_integrations=itsm\">here</a> to see a list of IT Service Management integrations. <br></div>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n \n </div>\n </td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"></td>\n </tr>\n </tbody>\n</table>\n",
"language" : "en"
}
]
}' "https://acmeco.xmatters.com/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates"
/**
* This script is configured to work with xMatters Flow Designer.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.subject = 'An xMatters incident requires your attention.';
data.body = '<link rel=\"stylesheet\" type=\"text/css\" href=\"https://static.xmatters.com/integrations/common/css/primary_table-7.css\">\n<style>\n /* common overrides for specific elements */\n body {\n font-family: \"Gotham SSm A\", \"Gotham SSm B\", verdana, sans-serif;\n }\n\n a, a:hover, a:focus {\n color: #0098cc;\n text-decoration: none;\n }\n\n .body-table {\n font-size: 16px; \n color: #444444; \n border-collapse: collapse; \n margin: 0;\n }\n\n .primary-container {\n display: inline-block; \n max-width: 800px;\n }\n\n .primary-table {\n border: solid 1px #e4e4e4;\n font-size: 14px; \n color: #444444; \n margin: 0; \n border-collapse: collapse;\n }\n\n .primary-table tr:first-of-type td {\n padding-top: 15px;\n }\n\n /* useful classes for various components */\n .background-dark {\n background-color: #f6f6f6;\n }\n\n .background-light {\n background-color: #fcfcfc; \n }\n\n .width-full {\n width: 100%;\n }\n\n .align-left {\n text-align: left;\n }\n\n .align-center {\n text-align: center;\n }\n\n .padding-none {\n padding: 0;\n }\n\n .padding-standard {\n padding: 5px 10px;\n }\n\n .border-none {\n border: 0;\n }\n\n /* Embedded specific stylings */\n div.embedded table {\n text-align: left;\n font-size: 14px; \n color: #444444; \n background-color: #fcfcfc; \n padding: 0; \n margin: 0; \n border: 0; \n border-collapse: collapse;\n width: 100%;\n }\n\n div.embedded table tr:last-of-type {\n border: 0;\n }\n\n div.embedded table tr:last-of-type td {\n border: 0;\n }\n\n div.embedded table tr {\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr:first-of-type td {\n padding-top: 10px;\n }\n\n div.embedded table tr td {\n padding: 10px 10px;\n /* needed to override in-browser message content default styles */\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr td h1 {\n font-size: 14px;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td h2 {\n font-size: 14px;\n color: #777777;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td p {\n color: #444444;\n margin: 0;\n }\n</style>\n\n<table class=\"body-table width-full align-center background-dark border-none padding-none\" id=\"table-6\">\n <tbody>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"><img alt=\"xMatters\" src=\"https://static.xmatters.com/integrations/common/images/xmatters_logo-1.png\" height=\"35px\"></td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\">Emergency Change Request</td>\n </tr>\n <tr>\n <td class=\"border-none\" tabindex=\"0\">\n <div class=\"width-full align-center\">\n <div class=\"primary-container width-full\">\n <table class=\"primary-table width-full align-left background-light padding-none\" id=\"table-7\">\n <tbody>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Number</strong></div>\n <div>${CB9D3E97-B46A-404C-B0E7-76DD8C099DFF}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Severity</strong></div>\n <div>${9BA4916A-E8B3-462D-A07D-0EA3CE52489A}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Impact</strong></div>\n <div>${52E3645F-BE0C-4C45-8CDF-C5720640EA3F}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Impacted CI</b></div>\n <div>${1A2BC1AB-EEC2-49C9-864E-F08CD49CCF03}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Short Description</b></div>\n <div>${E0D17510-8BBD-4C34-9428-786DFBDACC37}<br></div><div></div>\n </td>\n </tr>\n<tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Playbook details</b></div>\n <div>This is the notification sent from xMatters when it receives the alert from your ITSM application.<br>Use the response options below to move the workflow forward.<br></div><div></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Next Steps</strong></div>\n <div>Click <a href=\"http://www.xmatters.com/integration-results/?_sft_integrations=itsm\">here</a> to see a list of IT Service Management integrations. <br></div>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n \n </div>\n </td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"></td>\n </tr>\n </tbody>\n</table>\n,';
data.language = 'en';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created message template: " + 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 = "/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"subject": "An xMatters incident requires your attention.",
"body": "<link rel=\"stylesheet\" type=\"text/css\" href=\"https://static.xmatters.com/integrations/common/css/primary_table-7.css\">\n<style>\n /* common overrides for specific elements */\n body {\n font-family: \"Gotham SSm A\", \"Gotham SSm B\", verdana, sans-serif;\n }\n\n a, a:hover, a:focus {\n color: #0098cc;\n text-decoration: none;\n }\n\n .body-table {\n font-size: 16px; \n color: #444444; \n border-collapse: collapse; \n margin: 0;\n }\n\n .primary-container {\n display: inline-block; \n max-width: 800px;\n }\n\n .primary-table {\n border: solid 1px #e4e4e4;\n font-size: 14px; \n color: #444444; \n margin: 0; \n border-collapse: collapse;\n }\n\n .primary-table tr:first-of-type td {\n padding-top: 15px;\n }\n\n /* useful classes for various components */\n .background-dark {\n background-color: #f6f6f6;\n }\n\n .background-light {\n background-color: #fcfcfc; \n }\n\n .width-full {\n width: 100%;\n }\n\n .align-left {\n text-align: left;\n }\n\n .align-center {\n text-align: center;\n }\n\n .padding-none {\n padding: 0;\n }\n\n .padding-standard {\n padding: 5px 10px;\n }\n\n .border-none {\n border: 0;\n }\n\n /* Embedded specific stylings */\n div.embedded table {\n text-align: left;\n font-size: 14px; \n color: #444444; \n background-color: #fcfcfc; \n padding: 0; \n margin: 0; \n border: 0; \n border-collapse: collapse;\n width: 100%;\n }\n\n div.embedded table tr:last-of-type {\n border: 0;\n }\n\n div.embedded table tr:last-of-type td {\n border: 0;\n }\n\n div.embedded table tr {\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr:first-of-type td {\n padding-top: 10px;\n }\n\n div.embedded table tr td {\n padding: 10px 10px;\n /* needed to override in-browser message content default styles */\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr td h1 {\n font-size: 14px;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td h2 {\n font-size: 14px;\n color: #777777;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td p {\n color: #444444;\n margin: 0;\n }\n</style>\n\n<table class=\"body-table width-full align-center background-dark border-none padding-none\" id=\"table-6\">\n <tbody>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"><img alt=\"xMatters\" src=\"https://static.xmatters.com/integrations/common/images/xmatters_logo-1.png\" height=\"35px\"></td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\">Emergency Change Request</td>\n </tr>\n <tr>\n <td class=\"border-none\" tabindex=\"0\">\n <div class=\"width-full align-center\">\n <div class=\"primary-container width-full\">\n <table class=\"primary-table width-full align-left background-light padding-none\" id=\"table-7\">\n <tbody>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Number</strong></div>\n <div>${CB9D3E97-B46A-404C-B0E7-76DD8C099DFF}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Severity</strong></div>\n <div>${9BA4916A-E8B3-462D-A07D-0EA3CE52489A}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Impact</strong></div>\n <div>${52E3645F-BE0C-4C45-8CDF-C5720640EA3F}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Impacted CI</b></div>\n <div>${1A2BC1AB-EEC2-49C9-864E-F08CD49CCF03}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Short Description</b></div>\n <div>${E0D17510-8BBD-4C34-9428-786DFBDACC37}<br></div><div></div>\n </td>\n </tr>\n<tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Playbook details</b></div>\n <div>This is the notification sent from xMatters when it receives the alert from your ITSM application.<br>Use the response options below to move the workflow forward.<br></div><div></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Next Steps</strong></div>\n <div>Click <a href=\"http://www.xmatters.com/integration-results/?_sft_integrations=itsm\">here</a> to see a list of IT Service Management integrations. <br></div>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n \n </div>\n </td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"></td>\n </tr>\n </tbody>\n</table>\n",
"language" : "en"
}
RESPONSE
{
"voice": [
{
"steps": [
{
"stepType": "PHRASE",
"playback": "PHRASE",
"phrase": "Hello. Review and respond to this new incident."
},
{
"stepType": "COMMON_PROPERTY",
"playback": "PHRASE",
"commonProperty": "PERSON_ALERT_CONTEXT"
},
{
"stepType": "FORM_PROPERTY",
"playback": "PHRASE",
"formProperty":{
"name": "Short Description"
}
}
]
}
],
],
"sms": [
{
"text": "Hello. You’re needed for an incident in xMatters.",
"language" : "en"
}
],
"email": [
{
"subject": "An xMatters incident requires your attention.",
"body": "<link rel=\"stylesheet\" type=\"text/css\" href=\"https://static.xmatters.com/integrations/common/css/primary_table-7.css\">\n<style>\n /* common overrides for specific elements */\n body {\n font-family: \"Gotham SSm A\", \"Gotham SSm B\", verdana, sans-serif;\n }\n\n a, a:hover, a:focus {\n color: #0098cc;\n text-decoration: none;\n }\n\n .body-table {\n font-size: 16px; \n color: #444444; \n border-collapse: collapse; \n margin: 0;\n }\n\n .primary-container {\n display: inline-block; \n max-width: 800px;\n }\n\n .primary-table {\n border: solid 1px #e4e4e4;\n font-size: 14px; \n color: #444444; \n margin: 0; \n border-collapse: collapse;\n }\n\n .primary-table tr:first-of-type td {\n padding-top: 15px;\n }\n\n /* useful classes for various components */\n .background-dark {\n background-color: #f6f6f6;\n }\n\n .background-light {\n background-color: #fcfcfc; \n }\n\n .width-full {\n width: 100%;\n }\n\n .align-left {\n text-align: left;\n }\n\n .align-center {\n text-align: center;\n }\n\n .padding-none {\n padding: 0;\n }\n\n .padding-standard {\n padding: 5px 10px;\n }\n\n .border-none {\n border: 0;\n }\n\n /* Embedded specific stylings */\n div.embedded table {\n text-align: left;\n font-size: 14px; \n color: #444444; \n background-color: #fcfcfc; \n padding: 0; \n margin: 0; \n border: 0; \n border-collapse: collapse;\n width: 100%;\n }\n\n div.embedded table tr:last-of-type {\n border: 0;\n }\n\n div.embedded table tr:last-of-type td {\n border: 0;\n }\n\n div.embedded table tr {\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr:first-of-type td {\n padding-top: 10px;\n }\n\n div.embedded table tr td {\n padding: 10px 10px;\n /* needed to override in-browser message content default styles */\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr td h1 {\n font-size: 14px;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td h2 {\n font-size: 14px;\n color: #777777;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td p {\n color: #444444;\n margin: 0;\n }\n</style>\n\n<table class=\"body-table width-full align-center background-dark border-none padding-none\" id=\"table-6\">\n <tbody>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"><img alt=\"xMatters\" src=\"https://static.xmatters.com/integrations/common/images/xmatters_logo-1.png\" height=\"35px\"></td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\">Emergency Change Request</td>\n </tr>\n <tr>\n <td class=\"border-none\" tabindex=\"0\">\n <div class=\"width-full align-center\">\n <div class=\"primary-container width-full\">\n <table class=\"primary-table width-full align-left background-light padding-none\" id=\"table-7\">\n <tbody>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Number</strong></div>\n <div>${CB9D3E97-B46A-404C-B0E7-76DD8C099DFF}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Severity</strong></div>\n <div>${9BA4916A-E8B3-462D-A07D-0EA3CE52489A}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Impact</strong></div>\n <div>${52E3645F-BE0C-4C45-8CDF-C5720640EA3F}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Impacted CI</b></div>\n <div>${1A2BC1AB-EEC2-49C9-864E-F08CD49CCF03}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Short Description</b></div>\n <div>${E0D17510-8BBD-4C34-9428-786DFBDACC37}<br></div><div></div>\n </td>\n </tr>\n<tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Playbook details</b></div>\n <div>This is the notification sent from xMatters when it receives the alert from your ITSM application.<br>Use the response options below to move the workflow forward.<br></div><div></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Next Steps</strong></div>\n <div>Click <a href=\"http://www.xmatters.com/integration-results/?_sft_integrations=itsm\">here</a> to see a list of IT Service Management integrations. <br></div>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n \n </div>\n </td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"></td>\n </tr>\n </tbody>\n</table>\n",
"language" : "en"
}
],
"language": "en"
}
Creates voice, text, or email message templates for a form.
DEFINITION
POST /forms/{formId}/message-templates
URL PARAMETERS
| formId | string |
| The unique identifier (id) or name (targetName) of the form where the message template will be used. Names must be URL-encoded. |
BODY PARAMETERS
| Email Template object | |
The subject, body, and language of an email message. We recommend exporting an existing email message template and modifying it rather than creating a new one as the template must be HTML encoded. While the other fields are optional, the language field is mandatory and must contain a valid two-letter ISO 639 code. |
|
| sms | SMS Template object |
The text and language of an sms message. While the text field is optional, the language field is mandatory and must contain a valid two-letter ISO 639 code. |
|
| voice | Voice Template object |
The steps and language of a voicemail message. While the steps field is optional, the language field is mandatory and must contain a valid two-letter ISO 639 code. |
RESPONSES
| Success | Response code 200 OK and a pagination of Message Templates objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create form response options
Create response options for a form.
curl --user username --header "Content-Type: application/json" --request POST -d '{
{
{
"number": 1,
"text": "Acknowledge",
"description": "Acknowledge",
"prompt": "Acknowledge",
"action": "ASSIGN_TO_USER",
"contribution": "POSITIVE",
"joinConference": false,
"allowComments": true
},
{
"number": 2,
"text": "Escalate",
"description": "Stop Notifying For This Alert",
"prompt": "Escalate to next on-call",
"action": "ESCALATE",
"contribution": "NEGATIVE",
"joinConference": false,
"allowComments": true
},
{
"number": 3,
"text": "End",
"description": "Terminate and stop notifying",
"prompt": "Terminate event",
"action": "END",
"contribution": "NEUTRAL",
"joinConference": false,
"allowComments": true
}
],
}
}' "https://acmeco.xmatters.com/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/response-options"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/response-options",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data1 = {};
data1.number = '1';
data1.text = 'Acknowledge';
data1.description = 'Acknowledge.';
data1.prompt = 'Acknowledge';
data1.action = 'ASSIGN_TO_USER';
data1.contribution = 'POSITIVE';
data1.joinConference = false;
data1.allowComment = true;
var data2 = {};
data2.number = '2';
data2.text = 'Escalate';
data2.description = 'Stop Notifying For This Alert';
data2.prompt = 'Escalate to next on-call';
data2.action = 'ESCALATE';
data2.contribution = 'NEGATIVE';
data2.joinConference = false;
data2.allowComment = true;
var data3 = {};
data3.number = '3';
data3.text = 'End';
data3.description = 'Terminate and stop notifying';
data3.prompt = 'Terminate alert';
data3.action = 'END';
data3.contribution = 'NEUTRAL';
data3.joinConference = false;
data3.allowComment = true;
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created response options: " + 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 = "/forms/95fe8fbb-e095-4845-beb2-15d56829627b/response-options"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = [
{
"number": 1,
"text": "Acknowledge",
"description": "Acknowledge",
"prompt": "Acknowledge",
"action": "ASSIGN_TO_USER",
"contribution": "POSITIVE",
"joinConference": false,
"allowComments": true
},
{
"number": 2,
"text": "Escalate",
"description": "Stop Notifying For This Alert",
"prompt": "Escalate to next on-call",
"action": "ESCALATE",
"contribution": "NEGATIVE",
"joinConference": false,
"allowComments": true
},
{
"number": 3,
"text": "End",
"description": "Terminate and stop notifying",
"prompt": "Terminate event",
"action": "END",
"contribution": "NEUTRAL",
"joinConference": false,
"allowComments": true
}
]
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print(
"Created response options "
+ response.json()["targetName"]
+ ". id = "
+ response.json()["id"]
)
else:
print("Error: Response code is: " + str(responseCode))
RESPONSE
{
{
"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 Alert",
"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
}
}
Create the responses available to users when they receive a notification.
DEFINITION
POST /forms/{formId}/response-options
URL PARAMETERS
| formId | string |
| The unique identifier (id) of the form. |
BODY PARAMETERS
| 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 user 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 |
The effect the response choice has on the alert in xMatters. If action is not specified, the default value returned is RECORD_RESPONSE. Valid values include:
|
|
| contribution | string |
Describes whether to count the response as positive, negative, or neutral for user and group reporting purposes. If option is not specified, the default value returned is NONE. Valid values include:
|
|
| joinConference | Boolean |
| When this is true, choosing the response from a voice notification automatically connects the responder to the conference bridge. The form must have an existing conference bridge section to use this parameter. | |
| 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. |
RESPONSES
| Success | Response code 200 OK and a pagination of ResponseOptions objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a form section
Create a form section
REQUEST - Create a conference bridge section in a form.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"form": {
"id": "89a37590-83b7-4839-aa0d-fd3550d63ab7"
},
"title": "Sev_1_Calls",
"type": "CONFERENCE_BRIDGE",
"visible": true,
"collapsed": false,
"orderNum": 1,
"bridgeType": "XMATTERS_BRIDGES_ONLY"
}' "https://acmeco.xmatters.com/api/xm/1/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7/sections"
/**
* This script is configured to work with xMatters Flow Designer.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7/sections",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.title = 'Sev_1_Calls';
data.type = 'CONFERENCE_BRIDGE';
data.visible = 'true';
data.collapsed = 'false';
data.orderNum = '1';
data.bridgeType = 'XMATTERS_BRIDGES_ONLY';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created form section: " + 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 = "/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7/sections"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = [
{
"form": {
"id": "89a37590-83b7-4839-aa0d-fd3550d63ab7"
},
"title": "Sev_1_Calls",
"type": "CONFERENCE_BRIDGE",
"visible": true,
"collapsed": false,
"orderNum": 1,
"bridgeType": "XMATTERS_BRIDGES_ONLY"
}
]
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print(
"Created form section "
+ response.json()["targetName"]
+ ". id = "
+ response.json()["id"]
)
else:
print("Error: Response code is: " + str(responseCode))
RESPONSE
{
"id": "8a14b684-fa7f-4d26-ba64-0bed327a5f91",
"form": {
"id": "89a37590-83b7-4839-aa0d-fd3550d63ab7",
"visibility": "VISIBLE",
"links": {
"self": "/api/xm/1/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7"
}
},
"title": "Conference Bridge",
"type": "CONFERENCE_BRIDGE",
"visible": true,
"collapsed": false,
"orderNum": 3,
"bridgeType": "XMATTERS_BRIDGES_ONLY"
}
Creates a form section for an existing form. With the exception of Custom sections, a form can only contain one of each type of section and you can only send one form section per request.
Available form sections for messaging forms are:
- Attachments
- Conference Bridge
- Custom Section
- Devices
- Handling
- Recipients
- Response Overrides
- Sender Overrides
Available form sections for Flow Trigger forms are:
- Custom Section
- Devices
- Handling
- Incident Details
- Recipients
- Sender Overrides
DEFINITION
POST /forms/{formId}/sections
URL PARAMETERS
| formId | string |
| The unique identifier (id) or name (targetName) of the form where the message template will be used. Names must be URL-encoded. |
BODY PARAMETERS
For the specific parameters of each available form section, see the Forms Section object. For specific parameters about the incident details section, see the Incident Details object.
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. |
Modify a plan form
Modify a plan form
REQUEST - Modify a plan form by updating its description and changing a parameter.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "092ae177-3698-4fb7-ae92-1ee5a837c721"
"description": "Use this form for Sev-1 and Sev-2 problems.",
"uiEnabled": "true"
}
' "https://acmeco.xmatters.com/api/xm/1/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '092ae177-3698-4fb7-ae92-1ee5a837c721';
data.description = 'Use this form for Sev-1 and Sev-2 problems.';
data.uiEnabled = true;
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Updated form " + json.targetName + ". ID = "+ json.id);
}
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms"
url = base_URL + endpoint_URL
payload = {
"id": "092ae177-3698-4fb7-ae92-1ee5a837c721"
"description": "Use this form for Sev-1 and Sev-2 problems.",
"uiEnabled": "true"
}
response = requests.post(url, json=payload, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Updated communication plan form.")
RESPONSE
{
"id": "092ae177-3698-4fb7-ae92-1ee5a837c721",
"formId": "134480",
"name": "MIM Playbook 1",
"description": "Use this form for Sev-1 and Sev-2 problems.",
"triggerType": "MESSAGING",
"mobileEnabled": false,
"uiEnabled": true,
"apiEnabled": false,
"recipients": {
"count": 0,
"total": 0,
"data": [],
"links": {
"self": "/api/xm/1/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms/092ae177-3698-4fb7-ae92-1ee5a837c721/recipients?offset=0&limit=100"
}
},
"plan": {
"id": "271283e2-7a31-41f7-99a4-e81c1a58af20",
"name": "Major Incident Playbook",
"planType": "PLAN"
},
"scenarios": {
"count": 0,
"total": 0,
"data": [],
"links": {
"self": "/api/xm/1/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms/092ae177-3698-4fb7-ae92-1ee5a837c721/scenarios?offset=0&limit=100"
}
},
"responseOptions": {
"count": 0,
"total": 0,
"data": [],
"links": {
"self": "/api/xm/1/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms/092ae177-3698-4fb7-ae92-1ee5a837c721/response-options?offset=0&limit=100"
}
},
"links": {
"self": "/api/xm/1/plans/271283e2-7a31-41f7-99a4-e81c1a58af20/forms/092ae177-3698-4fb7-ae92-1ee5a837c721"
}
}
Changes the properties of an existing plan form. Identify the form by its unique identifier in the id field, and then provide the fields you want to modify.
DEFINITION
POST /plans/{planId}/forms
URL PARAMETERS
| {planID} | string |
The unique identifier (id) or name (targetName) of the plan. |
BODY PARAMETERS
The only required body parameter is the UUID of the form you want to update. See the Create a form body parameters for details on the other parameters you can change.
| id | string |
The unique identifier (id) or name (targetName) of the form you want to modify. |
RESPONSES
| Success | Response code 200 OK and a Form objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a form message template
Modify a voice message template for a form.
curl --user username --header "Content-Type: application/json" --request POST -d '{
{
"voice": {
"steps": [
{
"stepType": "PHRASE",
"playStyle": "PHRASE",
"phrase": "Hello. You are needed for a new xMatters incident."
},
{
"stepType": "COMMON_PROPERTY",
"playStyle": "PHRASE",
"commonProperty": "PERSON_ALERT_CONTEXT"
},
{
"stepType": "FORM_PROPERTY",
"playStyle": "PHRASE",
"formProperty":{
"name": "Short Description"
}
}
],
"language": "en"
}
}' "https://acmeco.xmatters.com/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates"
/**
* This script is configured to work with xMatters Flow Designer.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var stepType = {};
stepType.phrase = {};
stepType.phrase.playback = 'phrase';
stepType.phrase = "Hello. You are needed for a new xMatters incident.";
stepType['common-property'] = {}
stepType['common-property'].playback = 'phrase';
stepType['common-property'].commonProperty = 'PERSON_ALERT_CONTEXT';
stepType['form-property'] = {}
stepType['form-property'].playback = 'phrase';
stepType['form-property'].formProperty = 'PERSON_ALERT_CONTEXT';
stepType['form-property'].formProperty.name = 'Short Description';
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Updated message template: " + 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 = "/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = [
{
"stepType": "PHRASE",
"playStyle": "PHRASE",
"phrase": "Hello. You are needed for a new xMatters incident."
},
{
"stepType": "COMMON_PROPERTY",
"playStyle": "PHRASE",
"commonProperty": "PERSON_ALERT_CONTEXT"
},
{
"stepType": "FORM_PROPERTY",
"playStyle": "PHRASE",
"formProperty":{
"name": "Short Description"
}
}
]
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 200:
print(
"Updated message template "
+ response.json()["targetName"]
+ ". id = "
+ response.json()["id"]
)
else:
print("Error: Response code is: " + str(responseCode))
Create an SMS message for a specific form.
curl --user username --header "Content-Type: application/json" --request POST -d '{
{
"sms": [
{
"text": "Hello. You are needed for an incident in xMatters.",
"language" : "en"
}
],
}' "https://acmeco.xmatters.com/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates"
/**
* This script is configured to work with xMatters Flow Designer.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {
text: “Hello. You are needed for an incident in xMatters.”,
language: “en”,
};
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Updated message template: " + 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 = "/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"text": "Hello. You are needed for an incident in xMatters.",
"language" : "en"
],
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 200:
print(
"Updated message template "
+ response.json()["targetName"]
+ ". id = "
+ response.json()["id"]
)
else:
print("Error: Response code is: " + str(responseCode))
Create an email message for a specific form
curl --user username --header "Content-Type: application/json" --request POST -d '{
{
"email": [
{
"subject": "An xMatters incident requires your attention.",
"body": "<link rel=\"stylesheet\" type=\"text/css\" href=\"https://static.xmatters.com/integrations/common/css/primary_table-7.css\">\n<style>\n /* common overrides for specific elements */\n body {\n font-family: \"Gotham SSm A\", \"Gotham SSm B\", verdana, sans-serif;\n }\n\n a, a:hover, a:focus {\n color: #0098cc;\n text-decoration: none;\n }\n\n .body-table {\n font-size: 16px; \n color: #444444; \n border-collapse: collapse; \n margin: 0;\n }\n\n .primary-container {\n display: inline-block; \n max-width: 800px;\n }\n\n .primary-table {\n border: solid 1px #e4e4e4;\n font-size: 14px; \n color: #444444; \n margin: 0; \n border-collapse: collapse;\n }\n\n .primary-table tr:first-of-type td {\n padding-top: 15px;\n }\n\n /* useful classes for various components */\n .background-dark {\n background-color: #f6f6f6;\n }\n\n .background-light {\n background-color: #fcfcfc; \n }\n\n .width-full {\n width: 100%;\n }\n\n .align-left {\n text-align: left;\n }\n\n .align-center {\n text-align: center;\n }\n\n .padding-none {\n padding: 0;\n }\n\n .padding-standard {\n padding: 5px 10px;\n }\n\n .border-none {\n border: 0;\n }\n\n /* Embedded specific stylings */\n div.embedded table {\n text-align: left;\n font-size: 14px; \n color: #444444; \n background-color: #fcfcfc; \n padding: 0; \n margin: 0; \n border: 0; \n border-collapse: collapse;\n width: 100%;\n }\n\n div.embedded table tr:last-of-type {\n border: 0;\n }\n\n div.embedded table tr:last-of-type td {\n border: 0;\n }\n\n div.embedded table tr {\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr:first-of-type td {\n padding-top: 10px;\n }\n\n div.embedded table tr td {\n padding: 10px 10px;\n /* needed to override in-browser message content default styles */\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr td h1 {\n font-size: 14px;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td h2 {\n font-size: 14px;\n color: #777777;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td p {\n color: #444444;\n margin: 0;\n }\n</style>\n\n<table class=\"body-table width-full align-center background-dark border-none padding-none\" id=\"table-6\">\n <tbody>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"><img alt=\"xMatters\" src=\"https://static.xmatters.com/integrations/common/images/xmatters_logo-1.png\" height=\"35px\"></td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\">Emergency Change Request</td>\n </tr>\n <tr>\n <td class=\"border-none\" tabindex=\"0\">\n <div class=\"width-full align-center\">\n <div class=\"primary-container width-full\">\n <table class=\"primary-table width-full align-left background-light padding-none\" id=\"table-7\">\n <tbody>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Number</strong></div>\n <div>${CB9D3E97-B46A-404C-B0E7-76DD8C099DFF}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Severity</strong></div>\n <div>${9BA4916A-E8B3-462D-A07D-0EA3CE52489A}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Impact</strong></div>\n <div>${52E3645F-BE0C-4C45-8CDF-C5720640EA3F}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Impacted CI</b></div>\n <div>${1A2BC1AB-EEC2-49C9-864E-F08CD49CCF03}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Short Description</b></div>\n <div>${E0D17510-8BBD-4C34-9428-786DFBDACC37}<br></div><div></div>\n </td>\n </tr>\n<tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Playbook details</b></div>\n <div>This is the notification sent from xMatters when it receives the alert from your ITSM application.<br>Use the response options below to move the workflow forward.<br></div><div></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Next Steps</strong></div>\n <div>Click <a href=\"http://www.xmatters.com/integration-results/?_sft_integrations=itsm\">here</a> to see a list of IT Service Management integrations. <br></div>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n \n </div>\n </td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"></td>\n </tr>\n </tbody>\n</table>\n",
"language" : "en"
}
]
}' "https://acmeco.xmatters.com/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates"
/**
* This script is configured to work with xMatters Flow Designer.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.subject = 'An xMatters incident requires your attention.';
data.body = '<link rel=\"stylesheet\" type=\"text/css\" href=\"https://static.xmatters.com/integrations/common/css/primary_table-7.css\">\n<style>\n /* common overrides for specific elements */\n body {\n font-family: \"Gotham SSm A\", \"Gotham SSm B\", verdana, sans-serif;\n }\n\n a, a:hover, a:focus {\n color: #0098cc;\n text-decoration: none;\n }\n\n .body-table {\n font-size: 16px; \n color: #444444; \n border-collapse: collapse; \n margin: 0;\n }\n\n .primary-container {\n display: inline-block; \n max-width: 800px;\n }\n\n .primary-table {\n border: solid 1px #e4e4e4;\n font-size: 14px; \n color: #444444; \n margin: 0; \n border-collapse: collapse;\n }\n\n .primary-table tr:first-of-type td {\n padding-top: 15px;\n }\n\n /* useful classes for various components */\n .background-dark {\n background-color: #f6f6f6;\n }\n\n .background-light {\n background-color: #fcfcfc; \n }\n\n .width-full {\n width: 100%;\n }\n\n .align-left {\n text-align: left;\n }\n\n .align-center {\n text-align: center;\n }\n\n .padding-none {\n padding: 0;\n }\n\n .padding-standard {\n padding: 5px 10px;\n }\n\n .border-none {\n border: 0;\n }\n\n /* Embedded specific stylings */\n div.embedded table {\n text-align: left;\n font-size: 14px; \n color: #444444; \n background-color: #fcfcfc; \n padding: 0; \n margin: 0; \n border: 0; \n border-collapse: collapse;\n width: 100%;\n }\n\n div.embedded table tr:last-of-type {\n border: 0;\n }\n\n div.embedded table tr:last-of-type td {\n border: 0;\n }\n\n div.embedded table tr {\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr:first-of-type td {\n padding-top: 10px;\n }\n\n div.embedded table tr td {\n padding: 10px 10px;\n /* needed to override in-browser message content default styles */\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr td h1 {\n font-size: 14px;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td h2 {\n font-size: 14px;\n color: #777777;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td p {\n color: #444444;\n margin: 0;\n }\n</style>\n\n<table class=\"body-table width-full align-center background-dark border-none padding-none\" id=\"table-6\">\n <tbody>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"><img alt=\"xMatters\" src=\"https://static.xmatters.com/integrations/common/images/xmatters_logo-1.png\" height=\"35px\"></td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\">Emergency Change Request</td>\n </tr>\n <tr>\n <td class=\"border-none\" tabindex=\"0\">\n <div class=\"width-full align-center\">\n <div class=\"primary-container width-full\">\n <table class=\"primary-table width-full align-left background-light padding-none\" id=\"table-7\">\n <tbody>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Number</strong></div>\n <div>${CB9D3E97-B46A-404C-B0E7-76DD8C099DFF}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Severity</strong></div>\n <div>${9BA4916A-E8B3-462D-A07D-0EA3CE52489A}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Impact</strong></div>\n <div>${52E3645F-BE0C-4C45-8CDF-C5720640EA3F}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Impacted CI</b></div>\n <div>${1A2BC1AB-EEC2-49C9-864E-F08CD49CCF03}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Short Description</b></div>\n <div>${E0D17510-8BBD-4C34-9428-786DFBDACC37}<br></div><div></div>\n </td>\n </tr>\n<tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Playbook details</b></div>\n <div>This is the notification sent from xMatters when it receives the alert from your ITSM application.<br>Use the response options below to move the workflow forward.<br></div><div></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Next Steps</strong></div>\n <div>Click <a href=\"http://www.xmatters.com/integration-results/?_sft_integrations=itsm\">here</a> to see a list of IT Service Management integrations. <br></div>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n \n </div>\n </td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"></td>\n </tr>\n </tbody>\n</table>\n,';
data.language = 'en';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created message template: " + 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 = "/forms/95fe8fbb-e095-4845-beb2-15d56829627b/message-templates"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"subject": "An xMatters incident requires your attention.",
"body": "<link rel=\"stylesheet\" type=\"text/css\" href=\"https://static.xmatters.com/integrations/common/css/primary_table-7.css\">\n<style>\n /* common overrides for specific elements */\n body {\n font-family: \"Gotham SSm A\", \"Gotham SSm B\", verdana, sans-serif;\n }\n\n a, a:hover, a:focus {\n color: #0098cc;\n text-decoration: none;\n }\n\n .body-table {\n font-size: 16px; \n color: #444444; \n border-collapse: collapse; \n margin: 0;\n }\n\n .primary-container {\n display: inline-block; \n max-width: 800px;\n }\n\n .primary-table {\n border: solid 1px #e4e4e4;\n font-size: 14px; \n color: #444444; \n margin: 0; \n border-collapse: collapse;\n }\n\n .primary-table tr:first-of-type td {\n padding-top: 15px;\n }\n\n /* useful classes for various components */\n .background-dark {\n background-color: #f6f6f6;\n }\n\n .background-light {\n background-color: #fcfcfc; \n }\n\n .width-full {\n width: 100%;\n }\n\n .align-left {\n text-align: left;\n }\n\n .align-center {\n text-align: center;\n }\n\n .padding-none {\n padding: 0;\n }\n\n .padding-standard {\n padding: 5px 10px;\n }\n\n .border-none {\n border: 0;\n }\n\n /* Embedded specific stylings */\n div.embedded table {\n text-align: left;\n font-size: 14px; \n color: #444444; \n background-color: #fcfcfc; \n padding: 0; \n margin: 0; \n border: 0; \n border-collapse: collapse;\n width: 100%;\n }\n\n div.embedded table tr:last-of-type {\n border: 0;\n }\n\n div.embedded table tr:last-of-type td {\n border: 0;\n }\n\n div.embedded table tr {\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr:first-of-type td {\n padding-top: 10px;\n }\n\n div.embedded table tr td {\n padding: 10px 10px;\n /* needed to override in-browser message content default styles */\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr td h1 {\n font-size: 14px;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td h2 {\n font-size: 14px;\n color: #777777;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td p {\n color: #444444;\n margin: 0;\n }\n</style>\n\n<table class=\"body-table width-full align-center background-dark border-none padding-none\" id=\"table-6\">\n <tbody>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"><img alt=\"xMatters\" src=\"https://static.xmatters.com/integrations/common/images/xmatters_logo-1.png\" height=\"35px\"></td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\">Emergency Change Request</td>\n </tr>\n <tr>\n <td class=\"border-none\" tabindex=\"0\">\n <div class=\"width-full align-center\">\n <div class=\"primary-container width-full\">\n <table class=\"primary-table width-full align-left background-light padding-none\" id=\"table-7\">\n <tbody>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Number</strong></div>\n <div>${CB9D3E97-B46A-404C-B0E7-76DD8C099DFF}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Severity</strong></div>\n <div>${9BA4916A-E8B3-462D-A07D-0EA3CE52489A}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Impact</strong></div>\n <div>${52E3645F-BE0C-4C45-8CDF-C5720640EA3F}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Impacted CI</b></div>\n <div>${1A2BC1AB-EEC2-49C9-864E-F08CD49CCF03}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Short Description</b></div>\n <div>${E0D17510-8BBD-4C34-9428-786DFBDACC37}<br></div><div></div>\n </td>\n </tr>\n<tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Playbook details</b></div>\n <div>This is the notification sent from xMatters when it receives the alert from your ITSM application.<br>Use the response options below to move the workflow forward.<br></div><div></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Next Steps</strong></div>\n <div>Click <a href=\"http://www.xmatters.com/integration-results/?_sft_integrations=itsm\">here</a> to see a list of IT Service Management integrations. <br></div>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n \n </div>\n </td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"></td>\n </tr>\n </tbody>\n</table>\n",
"language" : "en"
]
}
RESPONSE
{
"voice": [
{
"steps": [
{
"id": "6fcf63d6-84f4-ae35-8fa5-3721ea146677"
"stepType": "PHRASE",
"playback": "PHRASE",
"phrase": "Hello. You are needed for a new xMatters incident."
},
{
"id": "5bbf63d6-84f4-4133-8fa5-3721ea146872"
"stepType": "COMMON_PROPERTY",
"playback": "PHRASE",
"commonProperty": "PERSON_ALERT_CONTEXT"
},
{
"id": "4abf63d6-84f4-4155-3a2b-3721ea141443"
"stepType": "FORM_PROPERTY",
"playback": "PHRASE",
"formProperty":{
"name": "Short Description"
}
}
]
}
],
"sms": [
{
"text": "Hello. You are needed for an incident in xMatters.",
"language" : "en"
}
],
"email": [
{
"subject": "An xMatters incident requires your attention.",
"body": "<link rel=\"stylesheet\" type=\"text/css\" href=\"https://static.xmatters.com/integrations/common/css/primary_table-7.css\">\n<style>\n /* common overrides for specific elements */\n body {\n font-family: \"Gotham SSm A\", \"Gotham SSm B\", verdana, sans-serif;\n }\n\n a, a:hover, a:focus {\n color: #0098cc;\n text-decoration: none;\n }\n\n .body-table {\n font-size: 16px; \n color: #444444; \n border-collapse: collapse; \n margin: 0;\n }\n\n .primary-container {\n display: inline-block; \n max-width: 800px;\n }\n\n .primary-table {\n border: solid 1px #e4e4e4;\n font-size: 14px; \n color: #444444; \n margin: 0; \n border-collapse: collapse;\n }\n\n .primary-table tr:first-of-type td {\n padding-top: 15px;\n }\n\n /* useful classes for various components */\n .background-dark {\n background-color: #f6f6f6;\n }\n\n .background-light {\n background-color: #fcfcfc; \n }\n\n .width-full {\n width: 100%;\n }\n\n .align-left {\n text-align: left;\n }\n\n .align-center {\n text-align: center;\n }\n\n .padding-none {\n padding: 0;\n }\n\n .padding-standard {\n padding: 5px 10px;\n }\n\n .border-none {\n border: 0;\n }\n\n /* Embedded specific stylings */\n div.embedded table {\n text-align: left;\n font-size: 14px; \n color: #444444; \n background-color: #fcfcfc; \n padding: 0; \n margin: 0; \n border: 0; \n border-collapse: collapse;\n width: 100%;\n }\n\n div.embedded table tr:last-of-type {\n border: 0;\n }\n\n div.embedded table tr:last-of-type td {\n border: 0;\n }\n\n div.embedded table tr {\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr:first-of-type td {\n padding-top: 10px;\n }\n\n div.embedded table tr td {\n padding: 10px 10px;\n /* needed to override in-browser message content default styles */\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr td h1 {\n font-size: 14px;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td h2 {\n font-size: 14px;\n color: #777777;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td p {\n color: #444444;\n margin: 0;\n }\n</style>\n\n<table class=\"body-table width-full align-center background-dark border-none padding-none\" id=\"table-6\">\n <tbody>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"><img alt=\"xMatters\" src=\"https://static.xmatters.com/integrations/common/images/xmatters_logo-1.png\" height=\"35px\"></td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\">Emergency Change Request</td>\n </tr>\n <tr>\n <td class=\"border-none\" tabindex=\"0\">\n <div class=\"width-full align-center\">\n <div class=\"primary-container width-full\">\n <table class=\"primary-table width-full align-left background-light padding-none\" id=\"table-7\">\n <tbody>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Number</strong></div>\n <div>${CB9D3E97-B46A-404C-B0E7-76DD8C099DFF}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Severity</strong></div>\n <div>${9BA4916A-E8B3-462D-A07D-0EA3CE52489A}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Impact</strong></div>\n <div>${52E3645F-BE0C-4C45-8CDF-C5720640EA3F}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Impacted CI</b></div>\n <div>${1A2BC1AB-EEC2-49C9-864E-F08CD49CCF03}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Short Description</b></div>\n <div>${E0D17510-8BBD-4C34-9428-786DFBDACC37}<br></div><div></div>\n </td>\n </tr>\n<tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Playbook details</b></div>\n <div>This is the notification sent from xMatters when it receives the alert from your ITSM application.<br>Use the response options below to move the workflow forward.<br></div><div></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Next Steps</strong></div>\n <div>Click <a href=\"http://www.xmatters.com/integration-results/?_sft_integrations=itsm\">here</a> to see a list of IT Service Management integrations. <br></div>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n \n </div>\n </td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"></td>\n </tr>\n </tbody>\n</table>\n",
"language" : "en"
}
]
"language": "en"
}
Modifies an existing voice, text, or email message template for a form. The only required parameter is the unique identifier of the form. See Message Templates objects for details on the parameters for each message template type.
DEFINITION
POST /forms/{formId}/message-templates
URL PARAMETERS
| formId | string |
| The unique identifier (id) or name (targetName) of the form of the form where the message template will be used. Names must be URL-encoded. |
RESPONSES
| Success | Response code 200 OK and a pagination of Message Templates objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a form response option
Modify a form response option
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "499e4a9b-bb2c-40a0-a01b-2bdfedb686b3",
"number": 1,
"text": "Acknowledge",
"description": "Acknowledge",
"prompt": "Acknowledge",
"action": "ASSIGN_TO_USER",
"contribution": "POSITIVE",
"joinConference": true,
"allowComments": true
}' "https://acmeco.xmatters.com/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/response-options"
/**
* This script is configured to work with xMatters Flow Designer.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/95fe8fbb-e095-4845-beb2-15d56829627b/response-options",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '499e4a9b-bb2c-40a0-a01b-2bdfedb686b3';
data.number = '1';
data.text = 'Acknowledge';
data.description = 'Acknowledge.';
data.prompt = 'Acknowledge';
data.action = 'ASSIGN_TO_USER';
data.contribution = 'POSITIVE';
data.joinConference = true;
data.allowComment = true;
var data2 = {};
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Modified response option: " + 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 = "/forms/95fe8fbb-e095-4845-beb2-15d56829627b/response-options"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = [
{
"id": "499e4a9b-bb2c-40a0-a01b-2bdfedb686b3",
"number": 1,
"text": "Acknowledge",
"description": "Acknowledge",
"prompt": "Acknowledge",
"action": "ASSIGN_TO_USER",
"contribution": "POSITIVE",
"joinConference": true,
"allowComments": true
}
]
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print(
"Modified response option "
+ response.json()["targetName"]
+ ". id = "
+ response.json()["id"]
)
else:
print("Error: Response code is: " + str(responseCode))
RESPONSE
{
{
"id": "499e4a9b-bb2c-40a0-a01b-2bdfedb686b3",
"number": 1,
"text": "Acknowledge",
"description": "Acknowledge",
"prompt": "Acknowledge",
"action": "ASSIGN_TO_USER",
"contribution": "POSITIVE",
"joinConference": true,
"allowComments": true
},
}
Modifies the properies of an existing response option.
Identify the response option by providing its unique identifier in the id field, and then provide the fields that you want to modify. If you modify the number field, and that number is already used by another response option, the existing response option information is overwritten with the contents of this request.
If the id field is not provided in the request body, xMatters interprets this as a request to create a new request parameter.
DEFINITION
POST /forms/{formId}/response-options
URL PARAMETERS
| formId | string |
| The unique identifier (id) of the form. |
BODY PARAMETERS
The only required body parameter is the UUID of the response option you want to update. See the Create response options for details on the other available parameters.
| id | string |
| The unique identifier of the group. |
RESPONSES
| Success | Response code 200 OK and a pagination of ResponseOptions objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a form section
Modify a form section
REQUEST - Modify information for an existing conference bridge section.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "8a14b684-fa7f-4d26-ba64-0bed327a5f91",
"form": {
"id": "89a37590-83b7-4839-aa0d-fd3550d63ab7"
},
"title": "Sev_1_Calls",
"type": "CONFERENCE_BRIDGE",
"visible": true,
"collapsed": false,
"orderNum": 1,
"bridgeType": "XMATTERS_AND_EXTERNAL_BRIDGES"
}' "https://acmeco.xmatters.com/api/xm/1/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7/sections"
/**
* This script is configured to work with xMatters Flow Designer.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7/sections",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '8a14b684-fa7f-4d26-ba64-0bed327a5f91';
data.title = 'Sev_1_Calls';
data.type = 'CONFERENCE_BRIDGE';
data.visible = 'true';
data.collapsed = 'false';
data.orderNum = '1';
data.bridgeType = 'XMATTERS_AND_EXTERNAL_BRIDGES';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Modified form section: " + 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 = "/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7/sections"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = [
{
"id": "8a14b684-fa7f-4d26-ba64-0bed327a5f91",
"form": {
"id": "89a37590-83b7-4839-aa0d-fd3550d63ab7"
},
"title": "Sev_1_Calls",
"type": "CONFERENCE_BRIDGE",
"visible": true,
"collapsed": false,
"orderNum": 1,
"bridgeType": "XMATTERS_AND_EXTERNAL_BRIDGES"
}
]
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print(
"Modified form section "
+ response.json()["targetName"]
+ ". id = "
+ response.json()["id"]
)
else:
print("Error: Response code is: " + str(responseCode))
RESPONSE
{
"id": "8a14b684-fa7f-4d26-ba64-0bed327a5f91",
"form": {
"id": "89a37590-83b7-4839-aa0d-fd3550d63ab7",
"visibility": "VISIBLE",
"links": {
"self": "/api/xm/1/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7"
}
},
"title": "Conference Bridge",
"type": "CONFERENCE_BRIDGE",
"visible": true,
"collapsed": false,
"orderNum": 3,
"bridgeType": "XMATTERS_AND_EXTERNAL_BRIDGES"
}
Modifies information in an existing form section. You can only send one form section per request, and the type parameter cannot be modified. For example, you cannot change an existing Conference Bridge section to a Custom section.
DEFINITION
POST /forms/{formId}/sections
URL PARAMETERS
| formId | string |
| The unique identifier (id) or name (targetName) of the form where the message template will be used. Names must be URL-encoded. |
BODY PARAMETERS
For the specific parameters of each available form section, see the Forms Section object. For specific parameters about the incident details section, see the Incident Details object.
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. |
Update form recipients
Update form recipients
REQUEST - Update the list of default recipients for an existing form.
curl --user username --header "Content-Type: application/json" --request PUT -d '{
{
"id": "14fdf697-08ed-479d-b44a-7051b0d86d56"
},
{
"id": "8b761a33-fee0-4e14-94f2-9b73cc728a68"
}
}
' "https://acmeco.xmatters.com/api/xm/1/forms/271283e2-7a31-41f7-99a4-e81c1a58af20/recipients"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/271283e2-7a31-41f7-99a4-e81c1a58af20/recipients",
"method": "PUT",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '14fdf697-08ed-479d-b44a-7051b0d86d56';
data.id = '8b761a33-fee0-4e14-94f2-9b73cc728a68';
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Updated recipients " + json.targetName + ". ID = "+ json.id);
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/forms/271283e2-7a31-41f7-99a4-e81c1a58af20/recipients"
url = base_URL + endpoint_URL
payload = [
{
"id": "14fdf697-08ed-479d-b44a-7051b0d86d56"
},
{
"id": "8b761a33-fee0-4e14-94f2-9b73cc728a68"
}
]
response = requests.post(url, json=payload, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Updated recipients.")
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"id": "8b761a33-fee0-4e14-94f2-9b73cc728a68",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/8b761a33-fee0-4e14-94f2-9b73cc728a68"
},
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"language": "en",
"timezone": "Canada/Pacific",
"webLogin": "mmcbride",
"site": {
"id": "5751f6d8-faf1-4701-8d2a-e9c2294f3eb1",
"name": "Victoria",
"links": {
"self": "/api/xm/1/sites/5751f6d8-faf1-4701-8d2a-e9c2294f3eb1"
}
},
"lastLogin": "2020-08-31T19:58:16.043Z",
"whenCreated": "2020-08-31T18:48:53.713Z",
"whenUpdated": "2022-10-07T21:01:57.917Z",
"targeted": true,
"status": "ACTIVE"
},
{
"id": "6f097eba-5bb4-4413-9daf-5c897a01e06a",
"targetName": "MIM Team 1",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": true,
"useDefaultDevices": true,
"observedByAll": true,
"description": "Group to handle major incidents",
"site": {
"id": "9a8e5d3e-4701-4940-b687-62793d466679",
"name": "Vancouver",
"links": {
"self": "/api/xm/1/sites/9a8e5d3e-4701-4940-b687-62793d466679"
}
},
"links": {
"self": "/api/xm/1/groups/6f097eba-5bb4-4413-9daf-5c897a01e06a"
},
"created": "2023-06-23T15:54:33.176Z",
"groupType": "ON_CALL",
"targeted": true
"status": "ACTIVE"
}
],
"links": {
"self": "/api/xm/1/forms/271283e2-7a31-41f7-99a4-e81c1a58af20/recipients?offset=0&limit=100"
}
}
Update the default recipients for a form. The recipient values in the provided list overwrite all previously stored values. If you want to keep the existing values and add additional recipients, use GET /forms/{formId}/recipients to retrieve the list of recipients, then add the new recipients to it.
DEFINITION
PUT /forms/{formId}/recipients
PUT /plans/{planId}/forms/{formId}/recipients
URL PARAMETERS
| planId | string |
The unique identifier (id) or name (targetName) of the plan. |
|
| formId | string |
| The unique identifier (id) or name (targetName) of the form. |
BODY PARAMETERS
| recipients | array Recipient object |
The unique identifier (id) of the user, group, device or dynamic team in xMatters that can receive notifications. |
RESPONSES
| Success | Response code 200 OK and a pagination of Recipient objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Update sender permissions
Update sender permissions
REQUEST - Update sender permissions for an existing form.
curl --user username --header "Content-Type: application/json" --request PUT -d '{
{
"senderType": "ROLE",
"sender": {
"id": "95c76a6f-39e8-0875-0a7c-cff2e97678d9",
},
"manageScenarios": false
},
{
"senderType": "PERSON",
"sender": {
"id": "ecfc7fa9-96df-4aba-a575-bf39ea8158e1",
},
"manageScenarios": false
},
}
' "https://acmeco.xmatters.com/api/xm/1/forms/271283e2-7a31-41f7-99a4-e81c1a58af20/sender-permissions"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/271283e2-7a31-41f7-99a4-e81c1a58af20/sender-permissions",
"method": "PUT",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.senderType = 'ROLE';
data.manageScenarios = false;
var sender = {};
sender.id = '95c76a6f-39e8-0875-0a7c-cff2e97678d9';
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Updated sender permissions " + json.targetName + ". ID = "+ json.id);
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/forms/271283e2-7a31-41f7-99a4-e81c1a58af20/sender-permissions"
url = base_URL + endpoint_URL
payload = [
{
"senderType": "ROLE",
"sender": {
"id": "95c76a6f-39e8-0875-0a7c-cff2e97678d9",
},
"manageScenarios": false
},
{
"senderType": "PERSON",
"sender": {
"id": "ecfc7fa9-96df-4aba-a575-bf39ea8158e1",
},
"manageScenarios": false
}
]
response = requests.post(url, json=payload, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Updated sender permissions.")
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"senderType": "ROLE",
"sender": {
"id": "e60eb755-c8c6-6fea-2d01-ed0af5df7cf7",
"name": "Developer"
},
"manageScenarios": false
},
{
"senderType": "PERSON",
"sender": {
"id": "b01c85d3-3f08-4324-ab13-467f7eb744c7",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/b01c85d3-3f08-4324-ab13-467f7eb744c7"
}
},
"manageScenarios": false
}
],
"links": {
"self": "/api/xm/1/forms/271283e2-7a31-41f7-99a4-e81c1a58af20/sender-permissions?offset=0&limit=100"
}
}
Update existing sender permissions for a form. The sender permission values in the provided list overwrite all previously stored values. If you want to keep the existing values and add additional sender permissions, use GET /forms/{formId}/sender-permissions to retrieve the existing list, then add the new senders to it.
DEFINITION
PUT /forms/{formId}/sender-permissions
PUT /plans/{planId}/forms/{formId}/sender-permissions
URL PARAMETERS
| planId | string |
The unique identifier (id) or name (targetName) of the plan. |
|
| formId | string |
| The unique identifier (id) or name (targetName) of the form. |
BODY PARAMETERS
| senderType | string |
Identifies whether the listed permissions apply to a single user or to all users with a specific role. Available values are:
|
|
| sender | string |
The unique identifier (id) of the person or role. |
|
| manageScenarios | Boolean |
If true the sender has permission to manage scenarios for the form. Default value is false. |
RESPONSES
| Success | Response code 200 OK and a pagination of Form Sender objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Form objects
The following form objects are available:
- Form object
- FormReference object
- Sender Overrides object
- Form Sender object
- Form Section object
- Message Templates 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 |
| The six digit legacy numeric form identifier. This identifier should not be used in place of the UUID when making API requests. | |
| 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 Sender object
Form Sender object
"data": [{
"senderType": "ROLE",
"sender": {
"id": "e60eb755-c8c6-6fea-2d01-ed0af5df7cf7",
"name": "Developer"
},
"manageScenarios": false
},
{
"senderType": "PERSON",
"sender": {
"id": "b01c85d3-3f08-4324-ab13-467f7eb744c7",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/b01c85d3-3f08-4324-ab13-467f7eb744c7"
}
},
"manageScenarios": false
}
],
Describes the users and roles who have permission to send forms and manage scenarios for the form.
| senderType | string |
Identifies whether the listed permissions apply to a single user or to all users with a specific role. Available values are:
|
|
| sender | string |
The unique identifier (id) of the person or role. |
|
| manageScenarios | Boolean |
If true the sender has permission to manage scenarios for the form. Default value is false. |
Form Section object
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",
"formSection": {
"id": "07090eb4-b49f-4e27-b730-10ef5683369b"
"type": "CUSTOM_SECTION"
},
"title": "Custom",
"visible": true,
"collapsed": false,
"orderNum": 0,
"items": [
{
"id": "string",
"formSection": {
"id": "string",
"type": "CUSTOM_SECTION"
},
"orderNum": 0,
"required": true,
"multilineText": true,
"visible": true,
"includeInCallbacks": true,
"lenientList": true,
"persistOnSubmission": false,
"propertyDefinition": {
"id": "f8b4a0f8-e6c7-42e3-f6a7-a4d0afde824e",
"propertyType": "LIST_TEXT_SINGLE_SELECT",
"name": "City",
"description": "Name of the city where you live",
"helpText": "Select a city from the list, or add your own value",
"includeInCallbacks": true,
"orderNum": 0,
"items": [
"Coombs",
"Edmonton",
"Los Angeles",
"Seattle",
"Victoria"
]
}
}
{
"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. |
|
| includeInCallback | Boolean |
If true, the custom section item is included in callbacks. |
|
| lenientList | Boolean |
If true, users can add their own options to the list. Valid only when the propertyType is LIST_TEXT_SINGLE_SELECT. |
|
| multiLineText | Boolean |
If true the custom form item is allows users to enter multiple lines of text. |
|
| orderNum | number |
| The order number of the item within the custom form section. | |
| persistOnSubmission | Boolean |
Can only be set to true if lenientList is also set to true. Valid only when the propertyType is LIST_TEXT_SINGLE_SELECT. |
|
| propertyDefinition | Pagination of Property objects |
| The properties that are available to users when adding items to custom sections of a form. | |
| required | Boolean |
If true the custom form item is mandatory. Default is false. |
|
| visible | Boolean |
If true the section is displayed to the message sender. |
|
| 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":[
{
"name": "SMS Phone",
"visible": true,
"selected": true,
"description": "Phone with SMS",
"deviceType": "TEXT_PHONE",
"deviceTypeGrouping": "MOBILE_TEXT"
},
{
"name": "Home Email",
"visible": true,
"selected": true,
"description": "Home Email Address",
"deviceType": "EMAIL",
"deviceTypeGrouping": "EMAIL_OTHER"
},
{
"name": "Home number - private",
"visible": true,
"selected": false,
"description": "Private home number",
"deviceType": "VOICE",
"deviceTypeGrouping": "VOICE"
},
]
Provides a list of all available devices in 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 that 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 |
| A list of devices that can receive notifications based on this form. |
| name | string |
The name of the device. These values are customized for your system but typical examples are listed below:
|
|
| visible | Boolean |
| Whether the device is visible when a user creates a message or subscription based on the form. | |
| selected | Boolean |
| Whether the device is selected when a user creates a message or subscription based on the form. | |
| description | string |
| A description of the 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. | |
| deviceTypeGrouping | string |
The group the device type belongs to. Available values are:
|
Handling section object
Handling section object
"data": [
{
"id": "e1104a34-d570-45a2-b685-b725d29d193e",
"form": {
"id": "89a37590-83b7-4839-aa0d-fd3550d63ab7",
"visibility": "VISIBLE",
"links": {
"self": "/api/xm/1/forms/89a37590-83b7-4839-aa0d-fd3550d63ab7"
}
},
"title": "Handling",
"type": "HANDLING_OPTIONS",
"visible": true,
"collapsed": false,
"orderNum": 2,
"priority": {
"visible": true,
"orderNum": 0,
"value": "Low"
},
"expiration": {
"visible": true,
"orderNum": 1,
"duration": 3,
"unit": "MINUTES"
},
"expirationInMinutes": {
"visible": true,
"orderNum": 1,
"value": 3
},
"overrideDeviceRestrictions": {
"visible": true,
"orderNum": 2,
"value": true
},
"escalationOverride": {
"visible": true,
"orderNum": 3,
"value": true
},
"bypassPhoneIntro": {
"visible": true,
"orderNum": 4,
"value": true
},
"requirePhonePassword": {
"visible": true,
"orderNum": 5,
"value": true
},
"voicemailOptions": {
"retry": 2,
"every": 60,
"leave": "callbackonly",
"visible": true,
"selected": false,
"orderNum": 6
"leaveOptions": [
{
"visible": true,
"selected": false,
"name": "CALLBACKANDMESSAGE"
},
{
"visible": true,
"selected": false,
"name": "MESSAGEONLY"
},
{
"visible": true,
"selected": true,
"name": "CALLBACKONLY"
},
{
"visible": true,
"selected": false,
"name": "HANGUP"
}
]
}
}
]
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:
|
|
| expiration | Expiration object |
| The maximum time to send messages. | |
| 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 |
| For voice notifications, this defines whether to try the call again or leave a message. |
Expiration object
Expiration object
"expiration": {
"visible": true,
"orderNum": 1,
"duration": 3,
"unit": "MINUTES"
}
Provides information on the maximum amount of time to send messages. For example, if a situation typically requires a response within 30 minutes, you might set an Expiration of 35 minutes.
| visible | Boolean |
If true the expiration section is visible to the message sender. |
|
| duration | integer |
| The length of time before expiration. | |
| unit | integer |
The unit of expiration time. Available values are:
|
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,
"enableResponseCounts": true,
"responseCountThreshold": 2,
"recipients": {
"count": 4,
"total": 4,
"data": [
{
"id" : "481086d8-357a-4279-b7d5-d7dce48fcd12",
"targetName": "mmcbride",
"firstName": "mary",
"lastName": "mcbride",
"recipientType": "PERSON"
},
{
"id": "e953c223-dd60-45c2-8ebb-0b02845e5dbd",
"targetName": "IT",
"recipientType": "GROUP"
},
{
"id": "7345cdb1-6a59-4e85-addd-fc17ae3cbb04",
"targetName": "SubscriptionDynamicTeam",
"recipientType": "DYNAMIC_TEAM"
},
{
"id": "77c7ec54-8609-47da-9b6b-80d4b24bead1",
"name": "Home Email",
"deviceType": "EMAIL",
"owner":
{
"id": "031313cc-42d3-4703-a90e-36cc5f5f6209",
"targetName": "akaur",
"links":
{
"self": "/api/xm/1/people/031313cc-42d3-4703-a90e-36cc5f5f6209"
}
},
}
]
},
"searchableTypes": {
"devices": true,
"dynamicTeams": true,
"groups": true,
"services": true,
"sites": false,
"users": true
},
"expandableGroups": true
},
]
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 recipient objects |
| The list of recipients targeted by the form. Available recipient options are: | |
| enableResponseCount | Boolean |
Used with responseCountThreshold. When true a specific number of recipients must respond before xMatters stops sending notifications. Default valuefalse. |
|
| responseCountThreshold | integer |
Used with enableResponseCount. An integer greater than zero that sets the number of recipients that must respond before xMatters stops sending notifications. |
|
| searchableTypes | Boolean |
When true the recipient type is searchable. The default value is true. At least one value must be set to true, and the sites option is only true if the Site Recipient section is added to the form. |
|
| expandableGroups | Boolean |
When true, groups listed as recipients can be expanded. The default value is true. |
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.
Message Templates objects
The messages templates objects contain the specific fields required to add email, sms, and voice message templates to a form in your xMatters instance. The following templates are available:
Email Template object
Email Template object
"email": [
{
"subject": "An xMatters incident requires your attention.",
"body": "<link rel=\"stylesheet\" type=\"text/css\" href=\"https://static.xmatters.com/integrations/common/css/primary_table-7.css\">\n<style>\n /* common overrides for specific elements */\n body {\n font-family: \"Gotham SSm A\", \"Gotham SSm B\", verdana, sans-serif;\n }\n\n a, a:hover, a:focus {\n color: #0098cc;\n text-decoration: none;\n }\n\n .body-table {\n font-size: 16px; \n color: #444444; \n border-collapse: collapse; \n margin: 0;\n }\n\n .primary-container {\n display: inline-block; \n max-width: 800px;\n }\n\n .primary-table {\n border: solid 1px #e4e4e4;\n font-size: 14px; \n color: #444444; \n margin: 0; \n border-collapse: collapse;\n }\n\n .primary-table tr:first-of-type td {\n padding-top: 15px;\n }\n\n /* useful classes for various components */\n .background-dark {\n background-color: #f6f6f6;\n }\n\n .background-light {\n background-color: #fcfcfc; \n }\n\n .width-full {\n width: 100%;\n }\n\n .align-left {\n text-align: left;\n }\n\n .align-center {\n text-align: center;\n }\n\n .padding-none {\n padding: 0;\n }\n\n .padding-standard {\n padding: 5px 10px;\n }\n\n .border-none {\n border: 0;\n }\n\n /* Embedded specific stylings */\n div.embedded table {\n text-align: left;\n font-size: 14px; \n color: #444444; \n background-color: #fcfcfc; \n padding: 0; \n margin: 0; \n border: 0; \n border-collapse: collapse;\n width: 100%;\n }\n\n div.embedded table tr:last-of-type {\n border: 0;\n }\n\n div.embedded table tr:last-of-type td {\n border: 0;\n }\n\n div.embedded table tr {\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr:first-of-type td {\n padding-top: 10px;\n }\n\n div.embedded table tr td {\n padding: 10px 10px;\n /* needed to override in-browser message content default styles */\n border: solid #e4e4e4;\n border-width: 0 0 1px 0;\n }\n\n div.embedded table tr td h1 {\n font-size: 14px;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td h2 {\n font-size: 14px;\n color: #777777;\n font-weight: normal;\n margin-bottom: 10px;\n }\n div.embedded table tr td p {\n color: #444444;\n margin: 0;\n }\n</style>\n\n<table class=\"body-table width-full align-center background-dark border-none padding-none\" id=\"table-6\">\n <tbody>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"><img alt=\"xMatters\" src=\"https://static.xmatters.com/integrations/common/images/xmatters_logo-1.png\" height=\"35px\"></td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\">Emergency Change Request</td>\n </tr>\n <tr>\n <td class=\"border-none\" tabindex=\"0\">\n <div class=\"width-full align-center\">\n <div class=\"primary-container width-full\">\n <table class=\"primary-table width-full align-left background-light padding-none\" id=\"table-7\">\n <tbody>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Number</strong></div>\n <div>${CB9D3E97-B46A-404C-B0E7-76DD8C099DFF}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Severity</strong></div>\n <div>${9BA4916A-E8B3-462D-A07D-0EA3CE52489A}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Impact</strong></div>\n <div>${52E3645F-BE0C-4C45-8CDF-C5720640EA3F}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Impacted CI</b></div>\n <div>${1A2BC1AB-EEC2-49C9-864E-F08CD49CCF03}<br></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Short Description</b></div>\n <div>${E0D17510-8BBD-4C34-9428-786DFBDACC37}<br></div><div></div>\n </td>\n </tr>\n<tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><b>Playbook details</b></div>\n <div>This is the notification sent from xMatters when it receives the alert from your ITSM application.<br>Use the response options below to move the workflow forward.<br></div><div></div>\n </td>\n </tr>\n <tr class=\"border-none\">\n <td class=\"padding-standard border-none\" tabindex=\"0\">\n <div><strong>Next Steps</strong></div>\n <div>Click <a href=\"http://www.xmatters.com/integration-results/?_sft_integrations=itsm\">here</a> to see a list of IT Service Management integrations. <br></div>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n \n </div>\n </td>\n </tr>\n <tr>\n <td class=\"border-none align-center\" tabindex=\"0\"></td>\n </tr>\n </tbody>\n</table>\n",
"language" : "en"
}
]
Describes a reference to a hard-coded email message.
| subject | string |
| The subject line of the email. | |
| body | string |
| The contents of the body of the email. | |
| language | string |
| The two-letter ISO 639 language code. |
SMS Template object
SMS Template object
"sms": [
{
"text": "Hello. You are needed for an incident in xMatters.",
"language" : "en"
}
]
Describes a reference to an SMS message.
| text | string |
| The contents of the text message. | |
| language | string |
| The two-letter ISO 639 language code |
Voice Template object
Voice Template object
"voice": {
"steps": [
{
"stepType": "PHRASE",
"playback": "PHRASE",
"phrase": "Hello. Review and respond to this new incident."
},
{
"stepType": "COMMON_PROPERTY",
"playback": "PHRASE",
"commonProperty": "PERSON_ALERT_CONTEXT"
},
{
"stepType": "FORM_PROPERTY",
"playback": "PHRASE",
"formProperty":{
"name": "Short Description"
}
}
],
"language": "en"
}
Describes a reference to a voice message.
| steps | string |
The steps in a of voicemail section, comprised of various stepTypes. Available options are:
|
|
| language | string |
| The two-letter ISO 639 language code. |
Voice phrase object
Voice phrase object
{
"stepType": "PHRASE",
"playback": "PHRASE",
"phrase" : "Hello. You’re needed for an incident in xMatters."
}
Describes the phrase the user hears when a voice template is used.
| stepType | string |
| The voice step type. For phrases, the stepType is: PHRASE. | |
| playback | string |
How the message is read when delivered to the user. Available options are:
|
|
| phrase | string |
| The phrase that the user hears when they receive notification to their phone device. For example, "Hello. You're needed for an xMatters incident.". |
Voice Common Property object
Voice Common Property object
{
"stepType": "COMMON_PROPERTY",
"playback": "PHRASE",
"commonProperty": "PERSON_ALERT_CONTEXT"
},
Describes the properties of a common form item in a voice template.
| stepType | string |
| The voice step type. For common form properties, the stepType is: COMMON_PROPERTY. | |
| playback | string |
How the message is read when delivered to the user. Available options are:
|
|
| commonProperty | string |
| The name of a pre-defined form property. Available options are: PERSON_ALERT_CONTEXT, PERSON_FIRST_NAME, PERSON_LAST_NAME, PERSON_WEB_LOGIN, SENDER_FIRST_NAME, SENDER_LAST_NAME, EVENT_START_DATE, EVENT_EVENT_ID, EVENT_START_TIME, COMPANY_NAME |
Voice Form Property object
Voice Form Property object
{
"stepType": "FORM_PROPERTY",
"playback": "PHRASE",
"formProperty":{
"name": "Short Description"
}
}
Describes the properties of a custom form item in a voice template.
| stepType | string |
| The voice step type. For custom form properties, the stepType is: CUSTOM_PROPERTY. | |
| playback | string |
How the message is read when delivered to the user. Available options are:
|
|
| formProperty | string |
The unique identifier (UUID) or name of the form property. |
GROUPS
Groups allow you to notify a set of people, devices, and 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. This includes Dynamic Groups, formerly known as Dynamic Teams.
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 in the online help.
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 include all services)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/groups/Oracle%20Administrators?embed=services"
/**
* This script is configured to work with xMatters Flow Designer.
* 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=services",
"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=services"
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 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)
)
RESPONSE (get a group by name with embedded services)
{
"id": "438e9245-b32d-445f-916bd3e07932c892",
"targetName": "Oracle Administrators",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": false,
"useDefaultDevices": true,
"observedByAll": false,
"services": {
"count": 2,
"total": 2,
"data": [
{
"id": "cebb7d11-d725-4cd0-9c42-a9427ef3c5c3",
"targetName": "API",
"recipientType": "SERVICE",
"description": "",
"ownedBy": {
"id": "438e9245-b32d-445f-916bd3e07932c892",
"targetName": "Oracle Administrators",
"recipientType": "GROUP",
"groupType": "ON_CALL",
"links": {
"self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
}
},
"links": {
"self": "/api/xm/1/services/cebb7d11-d725-4cd0-9c42-a9427ef3c5c3"
},
"externallyOwned": false,
"status": "ACTIVE"
},
{
"id": "0775d125-6d6e-48fe-818e-27fb185778ca",
"targetName": "Couchbase",
"recipientType": "SERVICE",
"description": "",
"ownedBy": {
"id": "438e9245-b32d-445f-916bd3e07932c892",
"targetName": "Oracle Administrators",
"recipientType": "GROUP",
"groupType": "ON_CALL",
"links": {
"self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
}
},
"links": {
"self": "/api/xm/1/services/0775d125-6d6e-48fe-818e-27fb185778ca"
},
"externallyOwned": false,
"status": "ACTIVE"
},
]
},
"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 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,services
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:
|
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 with xMatters Flow Designer.
* 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",
"groupType": "BROADCAST",
"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",
"groupType": "ON_CALL",
"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",
"groupType": "ON_CALL",
"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",
"groupType": "ON_CALL",
"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 on-call, broadcast, and dynamic 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?groupType=DYNAMIC&embed=criteria GET /groups?members=asharma,6f347364-8dc7-4871-819b-e3e7dbfda2de GET /groups?member.exists=ANY_SHIFTS GET /groups?search=Database Admins MIM&operand=AND GET /groups?search="Database Admins" "MIM Team"&fields=NAME GET /groups?sites=23d3ca36-13d2-4aaf-84da-6218aa768b11 GET /groups?sortBy=NAME&sortOrder=ASCENDING GET /groups?sortBy=GROUPTYPE&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:
|
|
| fields | string |
Defines the field to search when a search term is specified. Valid values include:
|
|
| groupType | string |
Specifies the group type to return in the response. Available values are:
|
|
| 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. |
|
| member.exists | string |
Returns a list of shifts without members. Available options are:
|
|
| members | string |
The targetName or id of the users, 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 group becomes "DBA%20Admins". The returned results show all groups that contain any of the queried members. |
|
| 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. The search returns all results where the term is found. When two or more search terms are present, the result includes groups that match either search term. You can narrow the search by using the operand and fields query parameters.When your search term contains more than one word, or contains delimiting characters such as spaces, enclose the terms in double quotes to preserve the delimiters. For example: "Database Analysts" "Test Team-1". You can also search only the group name, group description, or service name by setting the fields query parameter.Example: /groups?search=corporate admin&fields=NAME returns all groups with names that contain either "corporate" or "admin". However, searching /groups?search="corporate admin"&fields=NAME returns all groups with names that contain "corporate admin". |
|
| sites | string |
A comma-separated list of sites whose groups you want to retreive. You can specify the site using its unique identifier (id) or name (case-insensitive), or both. When two or more sites are sent in the request, the response includes groups for which either site is assigned.Example:San Ramon,north-east headquarters Example:960ffa54-b6d3-42b7-8025-7d95ff599976,ab1d6091-7d58-41e2-af72-49c69b3d9b65s,Vancouver. |
|
| 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
idfield. In this case, xMatters generates anidfor this group and returns it in theidfield 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 with xMatters Flow Designer.
* 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)
responseCode = response.status_code
if responseCode == 201:
print(
"Created group "
+ response.json()["targetName"]
+ ". id = "
+ response.json()["id"]
)
else:
print("Error: Response code is: " + str(responseCode))
REQUEST - Create a dynamic group This request shows how to create a dynamic group in your xMatters instance.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"targetName": "MIMTeam1",
"groupType": "DYNAMIC",
"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/groups"
javascript
/**
* This script is configured to work with xMatters Flow Designer.
* 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.targetName = 'MIMTeam1';
data.groupType = 'DYNAMIC';
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 group: " + 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 = "/groups"
username = "yourUsername"
password = "yourPassword"
payload = {
"targetName": "MIMTeam1",
"groupType": "DYNAMIC",
"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 group was created.")
else:
print("The dynamic group could not be created.")
REQUEST - Create a group (with a specific ID) This request shows how to create the group from the above example but assigns a value to the
idfield. This allows you to synchronize theidfield of the group with an external UUID.
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",
"id": "4888989a-3dd2-4edc-b0cd-ce4623cc454c"
}' "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.id '4888989a-3dd2-4edc-b0cd-ce4623cc454c's;
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": "Oracle Administrators",
"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)
responseCode = response.status_code
if responseCode == 201:
print(
"Created group "
+ response.json()["targetName"]
+ ". id = "
+ response.json()["id"]
)
else:
print("Error: Response code is: " + str(responseCode))
RESPONSE
{
"id": "4888989a-3dd2-4edc-b0cd-ce4623cc454c",
"targetName": "Executives",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": true,
"useDefaultDevices": true,
"observedByAll": false,
"observers": "Developer",
"description": "C-suite executives",
"site":
{
"id":"dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
"links":
{
"self":"/api/xm/1/sites/dbf90cbf-a745-a054-abf0-cb3b5b56e6bd"
}
},
"links":
{
"self": "/api/xm/1/groups/4888989a-3dd2-4edc-b0cd-ce4623cc454c"
}
}
RESPONSE (Create a group)
{
"id": "4888989a-3dd2-4edc-b0cd-ce4623cc454c",
"targetName": "Executives",
"groupType": "ON_CALL",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": true,
"useDefaultDevices": true,
"observedByAll": false,
"observers": "Developer",
"description": "C-suite executives",
"site":
{
"id":"dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
"links":
{
"self":"/api/xm/1/sites/dbf90cbf-a745-a054-abf0-cb3b5b56e6bd"
}
},
"links":
{
"self": "/api/xm/1/groups/4888989a-3dd2-4edc-b0cd-ce4623cc454c"
}
}
RESPONSE (Create a dynamic group)
{
"id": "76896d39-4258-4de0-bc4b-c2aadb120187",
"targetName": "MIMTeam1",
"recipientType": "GROUP",
"status": "ACTIVE",
"useDefaultDevices": true,
"observedByAll": true,
"criteria": {
"operand": "OR",
"criterion": {
"count": 1,
"total": 1,
"data": [
{
"criterionType": "BASIC_FIELD",
"field": "USER_ID",
"operand": "EQUALS",
"value": "MIMTeam1"
}
]
}
},
"links": {
"self": "/api/xm/1/groups/76896d39-4258-4de0-bc4b-c2aadb120187"
},
"created": "2024-03-16T20:33:36.762Z",
"groupType": "DYNAMIC",
"supervisors": {
"count": 2,
"total": 2,
"data": [
{
"id": "48c86bc5-720b-4ce1-a4b7-015c98530eaa",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/48c86bc5-720b-4ce1-a4b7-015c98530eaa"
},
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"language": "en",
"timezone": "Canada/Pacific",
"webLogin": "mmcbride",
"site": {
"id": "5751f6d8-faf1-4701-8d2a-e9c2294f3eb1",
"name": "Victoria",
"links": {
"self": "/api/xm/1/sites/5751f6d8-faf1-4701-8d2a-e9c2294f3eb1"
}
},
"whenCreated": "2020-08-27T17:00:44.902Z",
"whenUpdated": "2024-03-18T15:16:19.514Z",
"status": "ACTIVE"
},
{
"id": "b01c85d3-3f08-4324-ab13-467f7eb744c7",
"targetName": "bgull",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/b01c85d3-3f08-4324-ab13-467f7eb744c7"
},
"firstName": "Barry",
"lastName": "Gull",
"licenseType": "FULL_USER",
"language": "en",
"timezone": "Canada/Pacific",
"webLogin": "bgull",
"site": {
"id": "5751f6d8-faf1-4701-8d2a-e9c2294f3eb1",
"name": "Victoria",
"links": {
"self": "/api/xm/1/sites/5751f6d8-faf1-4701-8d2a-e9c2294f3eb1"
}
},
"lastLogin": "2023-03-21T05:11:52.326Z",
"whenCreated": "2020-08-27T17:03:00.795Z",
"whenUpdated": "2024-03-18T15:17:03.935Z",
"status": "ACTIVE"
}
]
}
"links": {
"self": "/api/xm/1/groups/76896d39-4258-4de0-bc4b-c2aadb120187"
}
}
Creates an empty group in xMatters.
The response returns either a Group object for On-Call and Broadcast groups, or a Dynamic group object that represents the newly-created group. You can use this object to locate the group's unique identifier (the id field). You can create either On-Call, Broadcast, or Dynamic groups by specifying the groupType. On-Call groups send notifications only to the group members on call based on the shift schedule. Broadcast groups contain no shift or calendar information and send notifications to all group members at once. Dynamic groups are created to group together users based on who matches the selected criteria at the time of an event. If you do not specify a groupType, the group is created as an On-Call group. Once a group is created, the groupType cannot be changed.
After an On-Call group is created you can build out the shift schedule and add members to the group roster. After a Broadcast group is created you can add members (users, other broadcast groups, devices, and dynamic groups) as members. When a Dynamic group is created you set the criteria that must be matched to form the group.
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.
For On-Call groups, see also:
For Broadcast and Dynamic groups, see also:
.DEFINITION
POST /groups
ON-CALL AND BROADCAST GROUP BODY PARAMETERS
| allowDuplicates | Boolean |
When set to True, group members can be added to an escalation timeline multiple times, and recipients can receive more than one notification for the same event targeting the group. |
|
| description | string |
| A description of the group. The description can contain a maximum of 1024 characters. | |
| externalKey | string |
| See externalKey. | |
| externallyOwned | Boolean |
| See externallyOwned. | |
| groupType | string |
The type of group to create. Available options are:
|
|
| observedByAll | Boolean |
True if all roles can view and target this group. If this value is false, use the observers parameter to set the roles that can target the group. |
|
| observers | array (ReferenceById object or ReferenceByName object) |
The id or name of the role or roles set as observers for the group. Adding observer roles via the xMatters REST API overwrites any existing observers for the group. To add specific observers to a group observedByAll must be set to false.To find the name or id of roles in your instance, see GET roles. |
|
| recipientType | string |
| For groups, this value is "GROUP". Providing this optional field allows xMatters to process your request more efficiently and improves performance. | |
| id | string |
| If provided, xMatters attempts to use this value as the group'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 group's unique identifier. Set a value in this optional field when you want a group'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. | |
| site | string |
| The identifier of the site that the group uses for holidays. If this value is not provided, the group is set to not use site holidays. | |
| status | string |
Whether the group is active. Inactive groups cannot receive notifications. Use one of the following values:
|
|
| supervisors | array [string] |
| A list of identifiers of people that act as supervisors for this group. These users must have permission to supervise groups. If this value is not provided, the authenticating user becomes the group supervisor. | |
| targetName | string |
| The name of the group. The name can have a maximum of 100 characters. | |
| useDefaultDevices | Boolean |
| True if this group notifies users on their failsafe (default) devices if none of the member's other devices are available. |
DYNAMIC GROUP BODY PARAMETERS
| targetName | string |
| The unique target name of the dynamic group. | |
| groupType | string |
The type of group to create. Available option is:
|
|
| description | string |
| A description of the dynamic group. | |
| criteria | Dynamic Group Criteria object |
| The criteria used to determine members of the dynamic group. | |
| supervisors | array [string] |
| The unique id of the supervisor, or supervisors of a dynamic group. A dynamic group 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 |
The id or name of the role or roles set as observers for the dynamic group. |
RESPONSES
| Success | Response code 201 Created and a Group object or a Dynamic Group object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a group
Modify a group
REQUEST The following request changes the description of the group identified by "138e9245-bded-445f-916b-dda07932b679" to "Executive team members".
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "138e9245-bded-445f-916b-dda07932b679",
"recipientType": "GROUP",
"description": "Executive team members"
}' "https://acmeco.xmatters.com/api/xm/1/groups"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var groupID = "138e9245-bded-445f-916b-dda07932b679";
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.recipientType = 'GROUP';
data.id = groupID;
data.description = 'Executive team members';
response = request.write(data);
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Modified group: " + json.targetName + ". New description: " + json.description);
}
#The following code is formatted to work with Python v.3.6 and later.
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 = {
"id" : "138e9245-bded-445f-916b-dda07932b679",
"recipientType": "GROUP",
"description": "Executive team members"
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if (responseCode == 200):
print('Group was successfully modified.' )
else:
print('Modification did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"id": "138e9245-bded-445f-916b-dda07932b679",
"targetName": "Executives",
"recipientType": "GROUP",
"active": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": true,
"useDefaultDevices": true,
"observedByAll" : true,
"description": "Executive team members",
"links":
{
"self": "/api/xm/1/groups/138e9245-bded-445f-916b-dda07932b679"
}
}
Changes the properties of an existing group.
Identify the group by providing its unique identifier in the id field, and then provide the fields that you want to modify.
Providing the targetName causes xMatters to rename the group.
You can obtain the id field of a group from the Group object returned when retrieving or creating a group.
If the id field is not provided in the request body, xMatters interprets this as a request to create a group.
See Create a group for more information about creating groups.
The response returns a Group object that represents the modified group.
DEFINITION
POST /groups
BODY PARAMETERS
The only required body parameter is the UUID of the group you want to update. See the Create a group for details on the other available parameters.
| id | string |
| The unique identifier of the group. |
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. |
Delete a group
Delete a group
REQUEST: Delete a group 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/groups/Oracle%20Administrators"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/Oracle Administrators",
/*"path" : "api/xm/1/groups/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 group: " + json.targetName);
}
import requests
from requests.auth import HTTPBasicAuth
import json
groupId = "Oracle Administrators"
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.delete(url, auth=auth)
responseCode = response.status_code
print("Received response: " + str(responseCode))
if int(responseCode) == 200:
rjson = response.json()
print('Deleted 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
{
"id": "438e9245-b32d-445f-916bd3e07932c892",
"targetName": "Oracle Administrators",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": false,
"useDefaultDevices": true,
"observedByAll" : true,
"description": "Oracle database administrators",
"timezone": "US/Eastern",
"links":
{
"self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
}
}
Deletes a group.
Identify the group using either the group name (the targetName field) or its unique identifier (the id field).
The response returns a Group Object that represents the recently-deleted group.
DEFINITION
DELETE /groups/{groupID}
URL PARAMETERS
| {groupID} | string |
The unique identifier (id) or name (targetName) of the group. Example: IT Example: a6341d69-5683-4621-b8c8-f2e728f6752q |
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 a group's supervisors
Get a group's supervisors
REQUEST
curl --user username
"https://acmeco.xmatters.com/api/xm/1/groups/DBAdmin/supervisors"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/DBAdmin/supervisors",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " supervisors." );
for (var i in json.data ) {
console.log(json.data[i].targetName);
}
}
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"
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()["supervisors"]
print(
"Retrieved "
+ str(rjson["count"])
+ " of "
+ str(rjson["total"])
+ " supervisors."
)
for d in rjson.get("data"):
print(
"Found supervisor with TargetName: "
+ d["targetName"]
+ " and id: "
+ d["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(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"count": 1,
"total": 1,
"data":
[
{
"id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links":
{
"self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Eastern",
"webLogin": "mmcbride",
"site":
{
"id": "8f2d98ed-eaa9-4b0b-b366-c1db06b27e1f",
"name": "Default Site",
"links":
{
"self": "/api/xm/1/sites/8f2d98ed-eaa9-4b0b-b366-c1db06b27e1f"
}
},
"status": "ACTIVE"
}
],
"links":
{
"self": "/api/xm/1/groups/1ea8906f-be05-410d-9077-fa7587d7b626/supervisors?offset=0&limit=100"
}
}
Returns a paginated list of the users that supervise the specified group.
Use this endpoint to retrieve a paginated list of a group's supervisors. You can also embed one page of group supervisors in a
call to GET /group by using the ?embed=supervisors query parameter.
DEFINITION
GET /groups/{groupId}/supervisors
URL PARAMETERS
| {groupId} | string |
The unique identifier (id) or name (targetName) of the group. |
RESPONSES
| Success | Response code 200 OK and a Pagination of Person objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Get group license quotas
Get group license quotas
REQUEST - Get the number of groups in your system by their status.
curl --user username "https://acmeco.xmatters.com/api/xm/1/groups/license-quotas"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/license-quotas",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " license quotas" );
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups/license-quotas"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"groupQuotaEnabled": true,
"groups": {
"total": 250,
"active": 125,
"unused": 125
}
}
Returns the number of groups currently created for your company and the number of total groups allowed by your plan type.
DEFINITION
GET /groups/license-quotas
RESPONSES
| Success | Response code 200 OK and a GroupQuotas object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a group's recipients
Get a group's recipients
REQUEST
curl --user username
"https://acmeco.xmatters.com/api/xm/1/groups/5510a9ab-6aeb-443f-bef2-861099e1766b/recipients"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/5510a9ab-6aeb-443f-bef2-861099e1766b/recipients",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " recipients." );
for (var i in json.data ) {
console.log(json.data[i].targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
groupId = "5510a9ab-6aeb-443f-bef2-861099e1766b"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups/" + groupId + "recipients"
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:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"count": 3,
"total": 3,
"data":[
{
"id": "89b6c799-3abb-41fb-9f9c-ace2dcba81ae",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"status": "ACTIVE",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/89b6c799-3abb-41fb-9f9c-ace2dcba81ae"
}
},
{
"id": "5510a9ab-6aeb-443f-bef2-861099e1766b",
"targetName": "bgull",
"firstName": "Barry",
"lastName": "Gull",
"status": "ACTIVE",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/5510a9ab-6aeb-443f-bef2-861099e1766b"
}
},
{
"id": "645d3afb-6410-4fba-9f58-e58839507367",
"targetName": "akaur",
"firstName": "Aarohi",
"lastName": "Kaur",
"status": "ACTIVE",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/645d3afb-6410-4fba-9f58-e58839507367"
}
},
],
"links":
{
"self": "/api/xm/1/groups/1ea8906f-be05-410d-9077-fa7587d7b626/recipients?offset=0&limit=100"
}
}
Returns a paginated list of the recipients of a specified group. For Dynamic groups, the response contains all users that would be notified based on the dynamic group criteria.
DEFINITION
GET /groups/{groupId}/recipients
URL PARAMETERS
| {groupId} | string |
The unique identifier (id) or name (targetName) of the group. |
RESPONSES
| Success | Response code 200 OK and a Pagination of Person objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Preview dynamic group members
Preview dynamic group members
REQUEST
curl --user username --header "Content-Type: application/json" --request POST -d '{
"operand": "OR",
"criterion": [
{
"criterionType": "BASIC_FIELD",
"field": "SITE",
"operand": "BEGINS_WITH",
"value": "2"
},
{
"criterionType": "CUSTOM_FIELD",
"field": "NUMBER",
"operand": "EQUALS",
"value": "12"
},
{
"category": "newmulti",
"values": [
"item3"
],
"criterionType": "CUSTOM_ATTRIBUTE"
}
]
}
"https://acmeco.xmatters.com/api/xm/1/groups/criteria-preview"
javascript
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/criteria-preview",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var criteria = {};
criteria.operand = 'OR';
var criterion1 = {};
criterion1.criterionType = 'BASIC_FIELD';
criterion1.field = 'SITE';
criterion1.operand = 'BEGINS_WITH';
criterion1.value = '2'
var criterion2 = {};
criterion1.criterionType = 'CUSTOM_FIELD';
criterion1.field = 'NUMBER';
criterion1.operand = 'EQUALS';
criterion1.value = '12'
var criterion3 = {};
criterion1.criterionType = 'CUSTOM_ATTRIBUTE';
criterion1.category = 'newmulti';
criterion1.value = 'item3'
var criterion = []
criterion.push(criterion1)
criteria.criterion = criterion;
data.criteria = criteria;
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Dynamic group members: " + 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 = "/groups/criteria-preview"
username = "yourUsername"
password = "yourPassword"
payload = {
"operand": "OR",
"criterion": [
{
"criterionType": "BASIC_FIELD",
"field": "SITE",
"operand": "BEGINS_WITH",
"value": "2"
},
{
"criterionType": "CUSTOM_FIELD",
"field": "NUMBER",
"operand": "EQUALS",
"value": "12"
},
{
"category": "newmulti",
"values": [
"item3"
],
"criterionType": "CUSTOM_ATTRIBUTE"
}
]
}
response = requests.post(base_url + endpoint, json=payload, auth=(username, password))
if response.status_code == 200:
print("There are dynamic group members that match the specified criteria.")
else:
print("No dynamic group members match the specified criteria.")
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"id": "7b71d1ad-530d-4eb6-83b6-5a3772994fd6",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/7b71d1ad-530d-4eb6-83b6-5a3772994fd6"
},
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "mmcbride",
"site": {
"id": "4a13d979-67f4-4ce4-9353-9e734cda56c3",
"name": "West Coast Office",
"links": {
"self": "/api/xm/1/sites/4a13d979-67f4-4ce4-9353-9e734cda56c3"
}
},
"lastLogin": "2024-08-31T18:28:29.740Z",
"whenCreated": "2018-04-20T18:41:05.252Z",
"whenUpdated": "2019-08-31T18:28:29.742Z",
"status": "ACTIVE"
},
{
"id": "7b71d1ad-530d-4eb6-83b6-5a3772994fd6",
"targetName": "bgull",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/7b71d1ad-530d-4eb6-83b6-5a3772994fd6"
},
"firstName": "Barry",
"lastName": "Gull",
"licenseType": "FULL_USER",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "bgull",
"site": {
"id": "4a13d979-67f4-4ce4-9353-9e734cda56c3",
"name": "Springfield Office",
"links": {
"self": "/api/xm/1/sites/4a13d979-67f4-4ce4-9353-9e734cda56c3"
}
},
"lastLogin": "2024-10-31T18:28:29.740Z",
"whenCreated": "2020-04-20T18:41:05.252Z",
"whenUpdated": "2023-08-31T18:28:29.742Z",
"status": "ACTIVE"
},
]
}
Returns a paginated list of the recipients that match the specified dynamic group criteria.
DEFINITION
POST /groups/criteria-preview
BODY PARAMETERS
| operand | string |
The operand to use to limit or expand the search query parameter: AND or OR. AND only returns dynamic groups that have all search terms in the name or description. OR returns dynamic 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' returns an error. |
|
| criterion | string |
| The criteria used to determine members of the dynamic group. Available options are: BASIC_FIELD, CUSTOM_FIELD, CUSTOM_ATTRIBUTE. For more details on the criterion, see Criterion object. |
RESPONSES
| Success | Response code 200 OK and a Pagination of Person objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Group objects
The following group objects are available:
- Group object
- Group Reference object
- Recipient Reference object
- Group Membership object
- Group Quotas object
- Dynamic Group object
- Dynamic Group Criteria object
- Dynamic Group Criterion object
- Dynamic Group Reference object
Group object
Group Object
{
"id": "438e9245-b32d-445f-916bd3e07932c892",
"targetName": "Oracle Administrators",
"recipientType": "GROUP",
"groupType": "ON_CALL",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": false,
"useDefaultDevices": true,
"observedByAll" : false,
"observers": "Developer",
"description": "Oracle database administrators",
"services": {
"count": 1,
"total": 1,
"data": [
{
"id": "9600557a-7005-414e-bd70-e22fd3a5e0b8",
"targetName": "East Coast Monitoring",
"recipientType": "SERVICE",
"description": "Service to monitor and maintain East Coast servers.",
"ownedBy": {
"id": "deaf3cb8-d6d6-437d-a809-59e6e369ba41",
"targetName": "East Coast MIM Team 1",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/deaf3cb8-d6d6-437d-a809-59e6e369ba41"
}
},
"links": {
"self": "/api/xm/1/incidents/ab1d6091-7d58-41e2-af72-49c69b3d9b65s"
}
}
],
},
"responseCount" : 2,
"responseCountThreshold" : 1,
"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"
}
}
A representation of an xMatters group.
Group objects include the fields defined in Recipient object in addition to fields specific to group recipients.
To view information about group supervisors, log on to the xMatters user interface and view the group.
See also Recipient object.
| allowDuplicates | Boolean |
When set to True, group members can be added to an escalation timeline multiple times, and recipients can receive more than one notification for the same event targeting the group. |
|
| description | string |
| A description of the group; can contain a maximum 1024 characters. | |
| groupType | string |
| The type of group in xMatters. Available options are BROADCAST, DYNAMIC, and ON_CALL. Broadcast groups send notifications to all members at once and cannot contain any calendar or shift information. Dynamic groups are created to group together users based on who matches the selected criteria at the time of an event. ON_CALL groups send notifications only to the members who are on-call for a shift. If not specified upon group creation, the default value assigned is ON_CALL. | |
| observedByAll | Boolean |
| True if users can locate and send notifications to the group regardless of their role. If this value is false, only users who have the selected roles can observe the group. | |
| observers | Role object |
The id or name of the role or roles set as observers for the group. Adding observer roles via the xMatters REST API overwrites any existing observers for the group. You can only add specific observers to a group if observedByAll is set to false. |
|
| recipientType | string |
| For groups, the recipient type field is "GROUP". | |
| status | string |
The status of the group. Valid values include:
|
|
| responseCount | integer |
| When an event is configured to count responses for this group, this field indicates the number of group members that have responded positively to the event. If this number is greater than the responseCountThreshold then the response or "fill" counts for this group have been met. | |
| responseCountThreshold | integer |
| When an event is configured to count responses for this group, this field indicates the number of group members required to respond to the event. Once this threshold is met, additional group members are no longer notified. | |
| site | ReferenceByIdAndSelfLink object |
| Contains a link you can use to access the site the group uses for holidays. | |
| targetName | string |
| For groups, the target name is the group name. | |
| useDefaultDevices | Boolean |
| True if group recipients may be notified on their default device when they do not have a device with an active timeframe. | |
| supervisors | Person object or PersonReference object |
| A list of the supervisors of the group. | |
| services | array[string] |
| The list of services owned by the group. |
GroupReference object
GroupReference object
{
"id": "e953c223-dd60-45c2-8ebb-0b02845e5dbd",
"targetName": "IT",
"recipientType": "GROUP",
"groupType": "BROADCAST",
"links":
{
"self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd"
}
}
A reference to a group, including a link that can be used to access the group using this API.
| id | string |
| The identifier of the group. | |
| targetName | string |
| The name of the group. | |
| recipientType | string |
| The type of object, in this case "GROUP". | |
| links | SelfLink object |
| A link that can be used to reference the group. |
RecipientReference object
RecipientReference object
{
"id": "ceb08e86-2674-4812-9145-d157b0e24c17",
"targetName": "mmcbride",
"recipientType": "PERSON",
"firstName": "mary",
"lastName":"mcbride",
"links":
{
"self": "/api/xm/1/people/ceb08e86-2674-4812-9145-d157b0e24c17"
}
}
A reference to the group member. Group members can be people, devices, dynamic groups, or other groups, and the RecipientReference object might include additional information depending on the type of group member.
| id | string |
| The identifier of the group member. | |
| targetName | string |
| The target name of the group member, such as the user ID, device name, or group name. | |
| recipientType | string |
The type of group member. Must be one of the following values:
|
|
| links | SelfLink object |
| A link that can be used to reference the group member. |
GroupMembership object
GroupMembership object
{
"group":
{
"id": "e953c223-dd60-45c2-8ebb-0b02845e5dbd",
"targetName": "Executives",
"recipientType": "GROUP",
"groupType": "ON_CALL",
"links":
{
"self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd"
}
},
"member":
{
"id": "ceb08e86-2674-4812-9145-d157b0e24c17",
"targetName": "mmcbride",
"recipientType": "PERSON",
"status": "ACTIVE",
"licenseType": "FULL_USER",
"links":
{
"self": "/api/xm/1/people/ceb08e86-2674-4812-9145-d157b0e24c17"
}
},
"shifts":
{
"count": 1,
"total": 1,
"data":
[{
"id": "07ae192b-614d-4986-931e-2e163f8132ce",
"name": "Weekdays",
"group":
{
"id": "e953c223-dd60-45c2-8ebb-0b02845e5dbd",
"links":
{
"self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd"
}
},
"links":
{
"self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd/shifts/07ae192b-614d-4986-931e-2e163f8132ce"
}
}]
}
}
The GroupMembership object defines the membership of a user, group, or device within this group. It contains a reference to the group and member, and for On-Call groups may optionally contain information about the specific shifts the member belongs to.
To include shift information when getting the group roster for On-Call groups, use the ?embed=shifts query parameter with Get the group roster.
| group | GroupReference object |
| A link to the group the member belongs to. | |
| member | RecipientReference object |
| A link to the group member. | |
| shifts | Pagination of Shift object |
| A list of the shifts the member of an On-Call group belongs to. |
GroupQuotas object
GroupQuotas object
{
"groupQuotaEnabled": true,
"groups": {
"total": 250,
"active": 76,
"unused": 174
}
}
The GroupQuotas object defines the number of groups in your xMatters system.
| total | integer |
| The total number of groups, both active and unused, available for your xMatters instance. | |
| active | integer |
| The number of active, or used, groups for your instance. | |
| unused | integer |
| The number of unused, or available, groups for your instance. |
Dynamic Group object
Dynamic Group Object
{
"id": "7345cdb1-6a59-4e85-addd-fc17ae3cbb04",
"targetName": "SubscriptionDynamicGroup",
"recipientType": "GROUP",
"status": "ACTIVE",
"useDefaultDevices": true,
"observedByAll": true,
"externallyOwned": false,
"description": "Dynamic Group 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_DynamicGroupUser"
}
]
}
},
"links": {
"self": "/api/xm/1/groups/7345cdb1-6a59-4e85-addd-fc17ae3cbb04"
}
}
A representation of an xMatters dynamic group, including embedded supervisors and criteria.
| id | string |
the unique identifier (id) of the dynamic group. |
|
| targetName | string |
| The target name of the dynamic group. | |
| recipientType | string |
| For dynamic groups, the recipient type field is "GROUP". | |
| groupType | string |
The type of group in xMatters. For Dynamic groups, the groupType is DYNAMIC. |
|
| description | string |
| A description of the dynamic group. | |
| externallyOwned | Boolean |
| See externallyOwned. | |
| supervisors | Person or PersonReference object |
A Paginated list of the supervisors of a dynamic group. 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. |
|
| observedByAll | Boolean |
| True if users can locate and send notifications to the group regardless of their role. If this value is false, only users who have the selected roles can observe the group. | |
| observers | Role object |
The id or name of the role or roles set as observers for the group. Adding observer roles via the xMatters REST API overwrites any existing observers for the group. You can only add specific observers to a group if observedByAll is set to false. |
|
| criteria | Criteria object |
| The criteria used to determine members of the dynamic group. | |
| status | string |
Whether the group is currently active in the xMatters instance. Available values are: ACTIVE, INACTIVE. |
|
| links | SelfLink object |
| A link that can be used to reference the dynamic group. |
Dynamic Group Criteria object
Dynamic Group Criteria Object
{
"criteria": {
"operand": "OR",
"criterion": {
"count": 1,
"total": 1,
"data": [
{
"criterionType": "BASIC_FIELD",
"field": "USER_ID",
"operand": "EQUALS",
"value": "SubsActivity_DynamicgroupUser"
}
]
}
},
}
The criteria used to determine members of the dynamic group.
| operand | string |
The operand to use to limit or expand the search query parameter: AND or OR. AND only returns dynamic groups that have all search terms in the name or description. OR returns dynamic 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' returns an error. |
|
| criterion | string |
The criteria used to determine members of the dynamic group. Available options are: BASIC_FIELD, CUSTOM_FIELD, CUSTOM_ATTRIBUTE. For more details on the criterion, see Criterion object.
Dynamic Group Criterion object
Criterion Object
{
"criterionType": "BASIC_FIELD",
"field": "LAST_NAME",
"operand": "EQUALS",
"value": "McBride"
}
{
"criterionType": "CUSTOM_ATTRIBUTE",
"category": "Evacuation Team",
"values": [
"Fire Marshalls",
"Section Leaders"
]
}
{
"criterionType": "BASIC_FIELD",
"field": "ROLE_NAME",
"operand": "EQUALS",
"value": "Supervisor"
}
// Checkbox CUSTOM_FIELD
{
"criterionType": "CUSTOM_FIELD",
"field": "Married",
"operand": "TRUE"
},
{
"criterionType": "CUSTOM_FIELD",
"field": "Divorced",
"operand": "FALSE"
},
// Number CUSTOM_FIELD
{
"criterionType": "CUSTOM_FIELD",
"field": "Age",
"operand": "EQUALS",
"value": "34"
}
// Text, List CUSTOM_FIELD -> BEGINS_WITH, CONTAINS, ENDS_WITH, EQUALS
{
"criterionType": "CUSTOM_FIELD",
"field": "Region",
"operand": "BEGINS_WITH",
"value": "US"
},
{
"criterionType": "CUSTOM_FIELD",
"field": "Region",
"operand": "ENDS_WITH",
"value": "east"
},
{
"criterionType": "CUSTOM_FIELD",
"field": "Region",
"operand": "CONTAINS",
"value": "-east"
},
{
"criterionType": "CUSTOM_FIELD",
"field": "Region",
"operand": "EQUALS",
"value": "US-east"
}
The criteria used to determine members of the dynamic group.
| criterionType | string |
The criterion type. Available options are:
|
|
| field | string |
The field being evaluated. Used with the BASIC_FIELD and CUSTOM_FIELD criterion types. Available options for a basic field are: FIRST_NAME, LAST_NAME, SITE, USER_ID, WEB_LOGIN, ROLE_NAME. The option for a custom field is the user-defined custom field. |
|
| operand | string |
How the property is being evaluated. Used with the BASIC_FIELD and CUSTOM_FIELD criterion types. Available options for a basic field are: EQUALS, BEGINS_WITH, ENDS_WITH, CONTAINS. Available options for a custom field are: EQUALS, BEGINS_WITH, ENDS_WITH, CONTAINS, true, false. |
|
| category | string |
Used only with the CUSTOM_ATTRIBUTE criterion. The category being evaluated. |
|
| value | string |
| The value to evaluate the criteria against. |
Dynamic Group Reference object
Dynamic Group Reference object
{
"id": "7345cdb1-6a59-4e85-addd-fc17ae3cbb04",
"targetName": "SubscriptionDynamicgroup",
"recipientType": "DYNAMIC_GROUP",
}
A representation of an xMatters dynamic group returned when the dynamic group is a listed as a recipient on a form.
| id | string |
The unique identifier (id) of the dynamic group. |
|
| targetName | string |
| The target name of the dynamic group. | |
| recipientType | string |
| For dynamic groups, the recipient type field is "DYNAMIC_GROUP". |
Group Calendar objects
ShiftOccurrence object
ShiftOccurrence object
{
"start": "2016-03-23T04:00:00Z",
"end": "2016-03-24T04:00:00Z",
"shift":
{
"id": "07ae192b-614d-4986-931e-2e163f8132ce",
"links":
{
"self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd/shifts/07ae192b-614d-4986-931e-2e163f8132ce"
}
},
"members":
{
"count": 1,
"total": 1,
"data":
[{
... omitted ...
}
}],
"links":
{
"self": "/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd/shifts/07ae192b-614d-4986-931e-2e163f8132ce?offset=0&limit=100"
}
}
}
| shift | ShiftReference object |
| Identifies a shift. | |
| members | Pagination of a [ShiftOccurrenceMember object] |
| A list of the shift members. | |
| start | string |
| The start time of the shift in UTC format. | |
| end | string |
| The end time of the shift in UTC format. |
ShiftReference object
ShiftReference object
"id": "07ae192b-614d-4986-931e-2e163f8132ce",
"links":
{
"self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd/shifts/07ae192b-614d-4986-931e-2e163f8132ce"
}
This object defines a reference to a shift. If it is returned from a call to GET /calendar with ?embed=shift it includes extra information about the shift such as its name and a reference to the group it belongs to.
| id | string |
| The unique identifier of the shift. | |
| links | SelfLink object |
| A link that can be used to access this resource. | |
| name | string |
The name of the shift. This information is included in the response when ?embed=shifts is used with GET /calendar. |
|
| group | GroupReference object |
A reference to the group that the shift belongs to. This information is included in the response when ?embed=shifts is used with GET /calendar. |
GROUP ROSTER
The group roster contains a list of group members.
Get the group roster
Get the group roster for a broadcast group
REQUEST - get group roster for a broadcast group
curl --user username "https://acmeco.xmatters.com/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892/members"
/**
* This script is configured to work with xMatters Flow Designer.
* 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-916bd3e07932c892/members",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " groups members." );
for (var i in json.data ) {
console.log(json.data[i].targetName);
}
}
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 + "/members"
url = base_URL + endpoint_URL + "&offset=0&limit=2"
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 "
+ str(rjson["count"])
+ " of "
+ str(rjson["total"])
+ " group members."
)
for d in rjson["data"]:
print(
"Found member with TargetName: "
+ d["member"]["targetName"]
+ ", id: "
+ d["member"]["id"]
+ ", and recipientType: "
+ d["member"]["recipientType"]
)
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)
)
Get the roster for an On-Call group, including embedded shift information
REQUEST - get the roster for an On-Call group, including embedded shift information
curl --user username "https://acmeco.xmatters.com/api/xm/1/groups/IT/members?embed=shifts"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/IT/members?embed=shifts",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
for (var d in json.data ) {
console.log ("\nMember = " + json.data[d].member);
var shifts = json.data[d].shifts.data;
for (var i in shifts)
{
console.log(shifts[i].name);
}
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
groupId = "e953c223-dd60-45c2-8ebb-0b02845e5dbd"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups/" + groupId + "/members?embed=shifts"
url = base_URL + endpoint_URL + "&offset=0&limit=2"
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 "
+ str(rjson["count"])
+ " of "
+ str(rjson["total"])
+ " group members."
)
for d in rjson["data"]:
print(
"Found member with TargetName: "
+ d["member"]["targetName"]
+ ", id: "
+ d["member"]["id"]
+ ", and recipientType: "
+ d["member"]["recipientType"]
)
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 - roster for a broadcast group
{
"count": 1,
"total": 1,
"data": [
{
"group":
{
"id": "438e9245-b32d-445f-916bd3e07932c892",
"targetName" : "DatabaseAdmins",
"recipientType": "GROUP",
"groupType": "BROADCAST",
"links":
{
"self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
}
},
"member":
{
"id": "ceb08e86-2674-4812-9145-d157b0e24c17",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links":
{
"self": "/api/xm/1/people/ceb08e86-2674-4812-9145-d157b0e24c17"
}
},
}],
"links":
{
"self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892/members"
}
}
RESPONSE - roster for an on-call group
{
"count": 1,
"total": 1,
"data": [
{
"group":
{
"id": "e953c223-dd60-45c2-8ebb-0b02845e5dbd",
"targetName" : "IT",
"recipientType": "GROUP",
"links":
{
"self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd"
}
},
"member":
{
"id": "ceb08e86-2674-4812-9145-d157b0e24c17",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"licenseType": "FULL_USER",
"links":
{
"self": "/api/xm/1/people/ceb08e86-2674-4812-9145-d157b0e24c17"
}
},
"shifts": {
"count": 1,
"total": 1,
"data": [
{
"id": "07ae192b-614d-4986-931e-2e163f8132ce",
"name": "Weekdays",
"group":
{
"id": "e953c223-dd60-45c2-8ebb-0b02845e5dbd",
"links":
{
"self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd"
}
},
"links":
{
"self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd/shifts/07ae192b-614d-4986-931e-2e163f8132ce"
}
}]
}
}],
"links":
{
"self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd/members?embed=shifts&offset=0&limit=100"
}
}
Returns the members that belong to a group as a Pagination of GroupMembership object.
For On-Call groups you can optionally include information about the shifts each member belongs to by including the ?embed=shifts query parameter in the request.
DEFINITION
GET /groups/{groupID}/members
GET /groups/{groupID}/members?devices.exists=false
GET /groups/{groupID}/members?devices.active.exists=false
GET /groups/{groupID}/members?devices.chat.exists=false
GET /groups/{groupID}/members?devices.email.exists=false
GET /groups/{groupID}/members?devices.failsafe.exists=false
GET /groups/{groupID}/members?devices.mobile.exists=false
GET /groups/{groupID}/members?devices.sms.exists=false
GET /groups/{groupID}/members?devices.voice.exists=false
GET /groups/{groupID}/members?devices.status=ACTIVE
GET /groups/{groupID}/members?devices.testStatus=TESTED
GET /groups/{groupID}/members?embed=shifts,site,lastLogin
GET /groups/{groupID}/members?format=targetableUsers
GET /groups/{groupID}/members?sortBy=NAME&sortOrder=ASCENDING
URL PARAMETERS
| groupID | string |
The unique identifier (id) or name (targetName) of the group. This value must be URL-encoded. |
QUERY PARAMETERS
| embed | string |
A comma-separated list of objects to embed in the response. Available options are:
|
|
| devices.exists | Boolean |
Returns a Pagination of members who have (or don't have) devices associated with their account.
|
|
| devices.active.exists | Boolean |
Returns a Pagination of members who have (or don't have) active devices associated with their account.
|
|
| devices.chat.exists | Boolean |
Returns a Pagination of members who have (or don't have) chat devices associated with their account.
|
|
| devices.email.exists | Boolean |
Returns a Pagination of members who have (or don't have) email devices associated with their account.
|
|
| devices.failsafe.exists | Boolean |
Returns a Pagination of members who have (or don't have) failsafe devices associated with their account.
|
|
| devices.mobile.exists | Boolean |
Returns a Pagination of members who have (or don't have) devices with the xMatters mobile app associated with their account.
|
|
| devices.sms.exists | Boolean |
Returns a Pagination of members who have (or don't have) SMS devices associated with their account.
|
|
| devices.voice.exists | Boolean |
Returns a Pagination of members who have (or don't have) voice devices associated with their account.
|
|
| format | string |
When added to the search query, member data is returned using Person pagination format which includes additional member information, such as sites. When excluded, member data is returned using standard group pagination format. Valid values include: targetableUsers |
|
| 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 groups 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 GroupMembership object. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Add a member to the group roster
Add a member to the group roster
REQUEST (add a member to the group roster)
curl -H "Content-Type: application/json" --user username -X POST -d
'{
"id": "bab4a72f-e118-462d-ad87-ee8e28e722e0",
"recipientType": "PERSON"
}'
"https://acmeco.xmatters.com/api/xm/1/groups/Oracle%20Administrators/members"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/Oracle Administrators/members",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = "bab4a72f-e118-462d-ad87-ee8e28e722e0";
data.recipientType = 'PERSON';
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Added member " + 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/Oracle Administrators/members"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {"id": "bab4a72f-e118-462d-ad87-ee8e28e722e0", "recipientType": "PERSON"}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print("Person " + rjson.get("targetName") + " was successfully added to the group.")
else:
print("Modification did not succeed. Response code is: " + str(responseCode))
RESPONSE
{
"id":"bab4a72f-e118-462d-ad87-ee8e28e722e0",
"targetName":"mmcbride",
"recipientType":"PERSON",
"externallyOwned":false,
"links": {
"self":"/api/xm/1/people/bab4a72f-e118-462d-ad87-ee8e28e722e0"
},
"firstName":"Mary",
"lastName":"McBride",
"language":"en",
"timezone":"US/Eastern",
"webLogin":"mmcbride",
"site": {
"id":"4d618961-21d6-417d-a904-8a84893b4e31",
"links": {
"self":"/api/xm/1/sites/4d618961-21d6-417d-a904-8a84893b4e31"
}
},
"status":"ACTIVE"
}
For broadcast groups, adds a member to the group. For on-call groups, adds a member to the group without adding them to any shift.
Use this endpoint when you know which group you want to add a member, or members to. Group members can be individual users, other groups, or devices. If you are adding groups as members of other groups, know that on-call groups cannot be members of broadcast groups. Broadcast groups do not contain any calendar or shift information.
When adding group members, you can have a maximum of 200 members in an on-call group and 1000 members in a broadcast group.
For on-call groups only: You must add the member to at least one shift before they will be able to receive notifications sent to the group. If you know which shift a member should belong to, use POST /groups/{groupID}/shifts/{shiftID}/members to add the member directly to the shift so they may begin to receive notifications immediately. For more information on adding members to shifts, see Add a member to a shift.
DEFINITION
POST /groups/{groupID}/members
URL PARAMETERS
| {groupID} | string |
The unique identifier (id) or name (targetName) of the group. Example: Oracle Administrators Example: bab4a72f-e118-462d-ad87-e38e28e822e0 |
BODY PARAMETERS
| id | string |
| The unique identifier or target name of the group member. | |
| recipientType | string |
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:
|
RESPONSES
| Success | Response code 200 OK and a Recipient object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Remove a member from the group roster
Remove a member from the group roster
REQUEST (remove a member from the group roster using their name)
curl --user username -X DELETE "https://acmeco.xmatters.com/api/xm/1/groups/IT/members/mmcbride"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/IT/members/mmcbride",
"method": "DELETE"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Deleted member: " + json.member.id);
}
else if (response.statusCode == 204) {
console.log("Member not found.")
}
import requests
from requests.auth import HTTPBasicAuth
import json
groupId = "130cc0c6-b798-4615-ba30-e712ce737a94"
memberId = "d9e6be4c-684b-4b3e-9995-d7f606804bbb"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups/" + groupId + "/members/" + memberId
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
print("Received response: " + str(responseCode))
if int(responseCode) == 200:
rjson = response.json()
print(
'Removed member with name: "'
+ rjson["member"]["id"]
+ '" from group "'
+ rjson["group"]["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
{
"member":
{
"id":"639edc41-80e7-481f-ac5b-6c6e98b498ea",
"recipientType":"DEVICE",
"links":
{
"self":"/api/xm/1/devices/639edc41-80e7-481f-ac5b-6c6e98b498ea"
}
},
"group":
{
"id":"d9e6be4c-684b-4b3e-9995-d7f606804bbb",
"targetName": "First Aid Attendants",
"links":
{
"self":"/api/xm/1/groups/d9e6be4c-684b-4b3e-9995-d7f606804bbb"
}
}
}
Removes a member from a group. For members who are part of an On-Call group, all of the member's corresponding shifts are also deleted. Group members may be people, devices, or other groups.
DEFINITION
DELETE /groups/{groupID}/members/{memberID}
URL PARAMETERS
| {groupID} | string |
The unique identifier (id) or name (targetName) of the group. Example: IT Example:aeb08e86-2674-4812-9145-e157b0e24c16 |
|
| {memberID} | string |
The unique identifier (id) or name (targetName) of the member to remove. Example: mmcbride Example: 62b08afe-2234-48a4-ece4-e157b049e290 |
RESPONSES
| Success | Response code 200 OK and a GroupMembership object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Note: This API returns a code of 204 No Content if the group member does not exist.
IMPORT JOBS
The following endpoints are used to retrieve information on imported files, either all imported files, or using an import's unique ID. You can also review error or warning messages for User Upload files.
For information on how to upload either a User Upload v1.5 file or EPIC ZipSync v1.3 file, see the Upload Users endpoint.
Get import jobs
Get import job records
REQUEST The following example shows how to return a paginated list of uploaded files.
curl --user username "https://acmeco.xmatters.com/api/xm/1/imports"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/imports",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " imports." );
for (var i in json.data ) {
console.log(json.data[i].targetName);
}
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/imports"
url = base_URL + endpoint_URL
response = requests.get(url, auth=("username", "password"))
if response.status_code == 200:
response_data = response.json()
print(
"Retrieved "
+ str(response_data["count"])
+ " of "
+ str(response_data["total"])
+ " imports."
)
for d in response_data["data"]:
print(d["targetName"])
RESPONSE
{
"count": 13,
"total": 13,
"data": [
{
"id": "bd76000f-5a5d-4fb7-89bc-4e90757e42de",
"name": "First Upload",
"transform": {
"name": "User Upload v1.5",
"url": "https://acmeco.xmatters.com/api/xm/1/uploads/users-v1"
},
"status": "FAILED",
"started": "2019-01-15T20:13:44.393Z",
"by": {
"id": "a0657a71-18dc-4f5d-a8b0-a72d6c32ea0a",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/a0657a71-18dc-4f5d-a8b0-a72d6c32ea0a"
}
},
"totalCount": 8,
"processedCount": 0,
"processingAt": "2019-01-15T20:13:50.128Z",
"finishedAt": "2019-01-15T20:13:53.645Z",
"links": {
"self": "/api/xm/1/imports/bd76000f-5a5d-4fb7-89bc-4e90757e42de"
}
},
{
"id": "cc8055d0-133a-4241-8b7e-27305c64524c",
"name": "User Upload v1.5 at 2019-01-25 00:38",
"transform": {
"name": "User Upload v1.5",
"url": "https://acmeco.xmatters.com/api/xm/1/uploads/users-v1"
},
"status": "COMPLETE",
"started": "2019-01-25T00:38:37.217Z",
"by": {
"id": "a0657a71-18dc-4f5d-a8b0-a72d6c32ea0a",
"targetName": "droberts",
"firstName": "Darren",
"lastName": "Roberts",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/a0657a71-18dc-4f5d-a8b0-a72d6c32ea0a"
}
},
"totalCount": 30,
"processedCount": 30,
"processingAt": "2019-01-25T00:38:38.406Z",
"finishedAt": "2019-01-25T00:38:46.004Z",
"links": {
"self": "/api/xm/1/imports/cc8055d0-133a-4241-8b7e-27305c64524c"
}
},
... truncated list of imports...
],
"links": {
"self": "/api/xm/1/imports?offset=0&limit=100"
}
}
Returns a paginated list of uploaded User Upload or EPIC ZipSync files.
DEFINITION
GET /imports
QUERY PARAMETERS
| transformType | string |
The transform type of the submitted file. Available options include:
|
|
| sortBy | string |
Determines the criteria by which imports are sorted:
sortOrder to change whether the results are sorted in ascending or descending order. |
|
| sortOrder | string |
Specifies whether imports 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 Import job objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get an import job
Get the record for an import job
REQUEST The following example shows how to request information for a data import job using its unique identifier.
curl --user username "https://acmeco.xmatters.com/api/xm/1/imports/cc8055d0-133a-4241-8b7e-27305c64524c"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/imports/cc8055d0-133a-4241-8b7e-27305c64524c",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Retrieved import job " + json.id);
}
import requests
base_url = "https://acmeco.xmatters.com/api/xm/1/"
endpoint_url = "/imports/cc8055d0-133a-4241-8b7e-27305c64524c"
url = base_url + endpoint_url
response = requests.get(url, auth=("username", "password"))
if response.status_code == 200:
print("Retrieved import job " + response.json()["id"])
RESPONSE
{
"id": "cc8055d0-133a-4241-8b7e-27305c64524c",
"name": "User Upload v1.5 at 2019-01-25 00:38",
"transform": {
"name": "User Upload v1.5",
"url": "https://acmeco.xmatters.com/api/xm/1/uploads/users-v1"
},
"status": "COMPLETE",
"started": "2019-01-25T00:38:37.217Z",
"by": {
"id": "a0657a71-18dc-4f5d-a8b0-a72d6c32ea0a",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/a0657a71-18dc-4f5d-a8b0-a72d6c32ea0a"
}
},
"totalCount": 30,
"processedCount": 30,
"processingAt": "2019-01-25T00:38:38.406Z",
"finishedAt": "2019-01-25T00:38:46.004Z",
"links": {
"self": "/api/xm/1/imports/cc8055d0-133a-4241-8b7e-27305c64524c"
}
}
Returns upload information for a specific import job.
DEFINITION
GET /imports/{importId}
URL PARAMETERS
| importId | string |
| The id of the import jpb you want to retrieve. Use GET /imports to find the id of the specific job. |
RESPONSES
| Success | Response code 200 OK and an Import job object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get import job messages
Get error or warning messages for an import job
REQUEST Get the list of error or warning messages for a User Upload import job
curl --user username "https://acmeco.xmatters.com/api/xm/1/imports/fa8125c2-729f-4294-88ec-419994b4ddcb/import-messages"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/imports/fa8125c2-729f-4294-88ec-419994b4ddcb/import-messages",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Retrieved" + json.count + " of " json.total _ " import job messages.");
}
import requests
base_url = "https://acmeco.xmatters.com/api/xm/1/"
endpoint_url = "/imports/fa8125c2-729f-4294-88ec-419994b4ddcb/import-messages"
url = base_url + endpoint_url
response = requests.get(url, auth=("username", "password"))
if response.status_code == 200:
print("Retrieved " + response.json()["count"] + " of " + response.json()["total"] + " import job messages.")
RESPONSE
{
"count": 29,
"total": 29,
"data": [
{
"id": "021c9af9-8056-4774-9b9b-571e36100592",
"messageLevel": "ERROR",
"messageType": "PROCESSING_ERROR",
"description": "Unexpected header: Home Email Status. This must be a device name or custom property.",
"column": "Home Email Status",
"line": 3
},
{
"id": "2f6f75e5-3a81-48b8-9dbe-313998ea0f04",
"messageLevel": "ERROR",
"messageType": "VALIDATION_ERROR",
"description": "Could not create user 'amunster'. Returned error: You must provide values for the required properties: Department..",
"line": 5
},
{
"id": "36763d91-3dd3-4a4d-99bc-40e75f5a4cfe",
"messageLevel": "WARN",
"messageType": "VALIDATION_WARNING",
"description": "User Supervisor has not been specified.",
"column": "User Supervisor",
"line": 7
},
...truncated list of warning messages...],
"links": {
"self": "/api/xm/1/imports/a14d72d0-ff7b-405f-a105-0d1ddab6a2cb/import-messages?messageLevels=ERROR%2CWARN&offset=0&limit=100"
}
}
Returns the error or warning messages for a specific User Upload import job.
When xMatters receives a user upload file, fields from the file are mapped to fields in the database. If there is missing, or erroneous information in the file, xMatters records a warning or an error message for the specific row and continues processing the file. Uploaded files that contain errors do not autmatically fail. Retrieving messages for an import job allows you to review the error or warning messages, make corrections to the file if required, and upload it again.
Note: This endpoint is only available for User Upload files and will not return messages for uploaded EPIC ZipSync files.
DEFINITION
GET /imports/{importId}/import-messages
URL PARAMETERS
| importId | string |
| The id of the import job you want to retrieve messages for. Use GET /imports to find the id of the job. |
QUERY PARAMETERS
| sortBy | string |
Determines the criteria by which data import messages are sorted:
sortOrder to change whether the results are sorted in ascending or descending order. |
|
| sortOrder | string |
Specifies whether subscription 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 an Import message object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Import job objects
Import object
Import object
This example shows an import object.
{
"id": "cc8055d0-133a-4241-8b7e-27305c64524c",
"name": "User Upload v1.5 at 2019-01-25 00:38",
"transform": {
"name": "User Upload v1.5",
"url": "https://acmeco.xmatters.com/api/xm/1/uploads/1"
},
"status": "COMPLETE",
"started": "2019-01-25T00:38:37.217Z",
"lastUpdatedAt": "2019-07-19T00:38:37.217Z",
"by": {
"id": "a0657a71-18dc-4f5d-a8b0-a72d6c32ea0a",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/a0657a71-18dc-4f5d-a8b0-a72d6c32ea0a"
}
},
"totalCount": 30,
"processedCount": 30,
"processingAt": "2019-01-25T00:38:38.406Z",
"finishedAt": "2019-01-25T00:38:46.004Z",
"links": {
"self": "/api/xm/1/imports/cc8055d0-133a-4241-8b7e-27305c64524c"
}
}
Describes the fields used by a file uploaded to xMatters.
| id | string |
| The unique id of the file import job. | |
| name | string |
| User upload only: The unique upload identifier created when the upload file was submitted. For example: "User Upload v1.5 at {date-timestamp}". | |
| transform | string |
The name of the transform type, and the url of the upload site. |
|
| status | string |
The status of the file import. Availble statuses are:
|
|
| started | string |
| The timestamp from when the file began processing. | |
| lastUpdatedAt | string |
| The timestamp from the last file upload. | |
| by | PersonReference object |
| The user that uploaded the file for processing. | |
| totalCount | integer |
| The total number of rows in the uploaded file. | |
| processedCount | integer |
| The number of rows that were processed in the uploaded file. | |
| finishedAt | string |
| The timestamp from when the file completd processing. | |
| links | SelfLink object |
| A link that can be used to reference the import. |
Import messages object
Import messages object
This example shows an import job message object.
{
"id": "2f6f75e5-3a81-48b8-9dbe-313998ea0f04",
"messageLevel": "ERROR",
"messageType": "VALIDATION_ERROR",
"description": "Could not create user 'amunster1'. Returned error: You must provide values for the required properties: Department..",
"line": 5
},
Describes a message information for a data import in xMatters.
| id | string |
| The unique id of the row in the import file. | |
| messageLevel | string |
Sorts messages by their escalation level:
|
|
| messageType | string |
Sorts messages by their type:
|
|
| description | string |
| Sorts messages by the description of the error. | |
| line | integer |
| The line or row number in the file where the error or warning applies. |
INCIDENTS
The incidents endpoint lets you retrieve information about incidents within your xMatters system. You can retrieve all incidents you have permission to view, or a specific incident. You can also add timeline notes to any incident currently in your xMatters system. For more information see the Incident Management section in the online help.
Get incidents
GET incidents
REQUEST Get all incidents in your system.
curl --user username
"https://acmeco.xmatters.com/api/xm/1/incidents"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/incidents",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " incidents." );
for (var i in json.data)
{
console.log(json.data[i].name + " created by " + json.data[i].creator.targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/incidents"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"count": 1,
"total": 1,
"data": [
{
"id": "d95ef469-64b7-4899-a5c9-f6062eca164f",
"incidentIdentifier": "INC-14",
"summary": "We are experiencing an issue with Google Compute Engine in us-east1-c and us-east1-d",
"description": "Existing VMs may be unavailable or unreachable, and new VM creation may fail beginning on Wednesday, 2021-06-30 10:15 US/Pacific",
"severity": {
"name": "Critical",
},
"status": {
"name": "In Progress",
},
"initiatedBy": {
"id": "526b6c8a-5fc7-4227-b946-af2220d66524",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/526b6c8a-5fc7-4227-b946-af2220d66524"
}
},
"commander": {
"id": "526b6c8a-5fc7-4227-b946-af2220d66524",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/526b6c8a-5fc7-4227-b946-af2220d66524"
}
},
"createdAt": "2021-04-05T04:51:48.275Z",
"updatedAt": "2021-04-05T04:51:48.275Z",
"impactedServices": [
{
"id": "f1bd9a5c-1113-457f-bae2-aeba775429c8",
"targetName": "API",
"recipientType": "SERVICE",
"description": "",
"links": {
"self": "/api/xm/1/services/f1bd9a5c-1113-457f-bae2-aeba775429c8"
},
"externallyOwned": false,
"status": "ACTIVE"
}
],
"links": {
"self": "/api/xm/1/incidents/d95ef469-64b7-4899-a5c9-f6062eca164f"
}
}
],
"links": {
"self": "/api/xm/1/incidents?offset=0&limit=100"
}
}
Returns a list of incidents in your xMatters instance. You can use the query parameters to limit your search by the requestID, status, or severity of an incident, or search for a particular keyword in the summary, description, or incident identifier. The incidents returned in the results are based on your permission level.
DEFINITION
GET /incidents
GET /incidents?impactedServices=API,47eb2567-38d0-40e5-8fbd-fa1f9e1454fd
GET /incidents?requestId=92eb2567-38d0-40e5-8fbd-fa1f9e1454bd
GET /incidents?resolver.group=Database%20Admins
GET /incidents?search=telecommunication outage&operand=AND
GET /incidents?search="telecommunication outage" "website down"&field=SUMMARY
GET /incidents?status=OPEN
GET /incidents?severity=HIGH
QUERY PARAMETERS
| impactedServices | string |
A comma-separated list of services. You can specify the service either by its target name, or unique identifier. Any spaces or special characters in the service name must be URL-encoded. When impactedServices is included in a request, the response returns incidents that contain any of the services as impacted services. |
|
| requestId | string |
The unique identifier returned from a request to trigger an incident. Searching by requestId returns the incident that was initiated when the trigger fired. |
|
| resolver.group | string |
The target name or unique identifier of a single group in your xMatters instance. Any spaces or special characters in the group name must be URL-encoded. When resolver.group is included in the request, the response returns only incidents where the specified group is a resolver. |
|
| search | string |
A list of search terms separated by the + sign or a space character. The search looks for the term anywhere in the incident summary, description, or incident identifier. Searches are case-insensitive ("alert" finds "alert", "Alert", as well as "alerting") and must contain at least two characters. When two or more search terms are present, the result includes incidents that match either search term. Use the operand and fields query parameters to expand or limit search results.When your search term contains more than one word, or contains delimiting characters such as spaces, enclose the terms in double quotes to preserve the delimiters. Example: /incidents?search=telecommunication outage&fields=SUMMARY returns all incidents with titles that contain either "telecommunication" or "outage". However, searching /incidents?search="telecommunication outage"&fields=SUMMARY returns all incidents with titles that contain "telecommunication outage". |
|
| operand | string |
| The operand to use to limit or expand the search query parameter: AND or OR. AND only returns incidents that have all search terms in the summary or description. OR returns incidents that have any of the search terms in the summary or description; this is the default if you don’t specify an operand. The operand is case-sensitive; for example, lowercase ‘and’ returns an error. | |
| fields | string |
Defines the field to search when a search term is specified. Valid values include:
|
|
| status | string |
The status of the incident at the time of the request. To search for multiple values, use a comma-separated list. Valid values include:
|
|
| severity | string |
The severity of the incident at the time of the request. To search for multiple values, use a comma-separated list. Valid values include:
|
RESPONSES
| Success | Response code 200 OK and a Pagination of Incidents objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get an incident
Get an incident
REQUEST Get an incident by its unique identifier
curl --user username
"https://acmeco.xmatters.com/api/xm/1/incidents/ab1d6091-7d58-41e2-af72-49c69b3d9b65s"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/incidents/ab1d6091-7d58-41e2-af72-49c69b3d9b65s",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved incident " + json.eventId + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/incidents/ab1d6091-7d58-41e2-af72-49c69b3d9b65s"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print(
'Found incident with id "'
+ rjson["incidentId"]
+ '" 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": "ab1d6091-7d58-41e2-af72-49c69b3d9b65s",
"incidentIdentifier": "INC-14",
"summary": "We are experiencing an issue with Google Compute Engine in us-east1-c and us-east1-d",
"description": "Existing VMs may be unavailable or unreachable, and new VM creation may fail beginning on Wednesday, 2021-06-30 10:15 US/Pacific",
"severity": {
"name": "Critical",
},
"status": {
"name": "In Progress",
},
"initiatedBy": {
"id": "526b6c8a-5fc7-4227-b946-af2220d66524",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/526b6c8a-5fc7-4227-b946-af2220d66524"
}
},
"commander": {
"id": "526b6c8a-5fc7-4227-b946-af2220d66524",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/526b6c8a-5fc7-4227-b946-af2220d66524"
}
},
"createdAt": "2021-04-05T04:51:48.275Z",
"updatedAt": "2021-04-05T04:51:48.275Z",
"links": {
"self": "/api/xm/1/incidents/ab1d6091-7d58-41e2-af72-49c69b3d9b65s"
}
}
Returns a specific incident in your xMatters instance by either its UUID or incident identifier. You must have sufficient permissions to view the incident if you did not create it.
DEFINITION
GET /incidents/{incidentID}
GET /incidents/{incidentIdentifier}
QUERY PARAMETERS
| incidentID | string |
| The unique identifier (or UUID) of an incident in xMatters. For example: ab1d6091-7d58-41e2-af72-49c69b3d9b65. | |
| incidentIdentifier | string |
The unique alpha-numeric incident number. The default identifier for incidents created by xMatters is INC. For example: INC-145. |
RESPONSES
| Success | Response code 200 OK and an Incident object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Trigger an incident
Trigger an incident
REQUEST - Trigger an incident in xMatters
curl -H "Content-Type: application/json" -X POST -d '
{
data '{
"incidentDetails":{
"description":"Less than 33% pod availability detected",
"severity":"High",
"summary":"Auth API server is down"
},
"recipients":[
{
"id":"mmcbride",
"recipientType":"PERSON"
}
],
"priority": "Medium",
"expirationInMinutes":180,
"overrideDeviceRestrictions":false,
"escalationOverride": false,
"bypassPhoneIntro":true,
"requirePhonePassword":false,
"voicemailOptions":{
"retry":5,
"every":120,
"leave":"callbackonly"
},
"senderOverrides":{
"callerId":"+0155501001234",
"displayName": "xMatters EMEA"
},
"targetDeviceNames": [
"Home Email",
"Home Phone"
],
"properties":{
"Region": "us-central"
}
}'
"https://acmeco.xmatters.com/api/xm/1/forms/76b2fbf1-6eb3-4d7d-b70e-430346107676/triggers"
/**
* This example shows how to customize the built-in trigger object to
* customize form settings and then trigger an incident.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/76b2fbf1-6eb3-4d7d-b70e-430346107676/triggers",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
// Main request object
var trigger = {}
//Incident Details
var incidentDetails = {}
incidentDetails.description = "Less than 33% pod availability detected";
incidentDetails.severity = "High";
incidentDetails.summary = "Auth API server is down";
trigger.incidentDetails = incidentDetails;
//Recipients
var recipients = [];
recipients.push({"id":"mmcbride", "recipientType": "PERSON"});
trigger.recipients = recipients;
//Handling
trigger.expirationInMinutes = 180;
trigger.bypassPhoneIntro = true;
trigger.escalationOverride = false;
trigger.overrideDeviceRestrictions = false;
trigger.priority = "Medium";
trigger.requirePhonePassword = false;
var voicemailOptions= {};
voicemailOptions.every = 120;
voicemailOptions.leave = "callbackonly";
voicemailOptions.retry = 5;
trigger.voicemailOptions = voicemailOptions;
//Devices
trigger.targetAllDevices = false;
var targetDeviceNames = [];
targetDeviceNames.push({"name" : "Home Email"});
targetDeviceNames.push({"name" : "Home Phone"});
//Properties
var properties = {};
properties.region = "us-central";
trigger.properties = properties;
// Override sender display information
var senderOverrides = {};
senderOverrides.displayName = "xMatters EMEA";
senderOverrides.callerId= "+0155501001234";
trigger.senderOverrides = senderOverrides;
//Trigger the incident
response = request.write(trigger);
if (response.statusCode == 202){
json = JSON.parse(response.body);
console.log("Triggered an Alert. Request ID: " + json.requestId);
}
#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/forms/76b2fbf1-6eb3-4d7d-b70e-430346107676/triggers"
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"incidentDetails": {
"description": "Less than 33% pod availability detected",
"severity": "High",
"summary": "Auth API server is down"
},
"recipients": [
{
"id": "mmcbride",
"recipientType": "PERSON"
}
],
"priority": "Medium",
"expirationInMinutes": 180,
"overrideDeviceRestrictions": False,
"escalationOverride": False,
"bypassPhoneIntro": True,
"requirePhonePassword": False,
"voicemailOptions": {
"retry": 5,
"every": 120,
"leave": "callbackonly"
},
"senderOverrides": {
"callerId": "+0155501001234",
"displayName": "xMatters EMEA"
},
"targetDeviceNames": ["Home Email", "Home Phone"],
"properties": {"Region": "us-central"}
}
headers = {
"Content-Type": "application/json"
}
response = requests.request("POST", url, json=payload, headers=headers)
responseCode = response.status_code
if responseCode == 202:
print("Incident triggered = " + response.json()["requestId"])
else:
print("Error: response code is " + str(responseCode))
There are several ways to trigger an incident from another cloud-based system or from within your own application.
- Form Trigger: Whether you create a new flow, or already have a workflow you want to use, you can use a Flow Trigger form to initiate flows. Once the Flow Trigger form is added to your canvas, add the Initiate an Incident step anywhere in the flow. For more information, see Flow Trigger forms in the online help.
- HTTP Request Trigger: If you’d like to use a workflow but your system cannot construct the JSON payload in the format required by xMatters, create a custom HTTP Request trigger. You can then pass the payload into the HTTP Request trigger in any format, and use Flow Designer’s built-in JavaScript editor to parse and transform the payload into the format required by other xMatters steps. Once the HTTP Request trigger is added to your canvas, connect it to the Initiate an Incident step. For more information, see HTTP Trigger in the online help.
- Initiate Incident step: If you already have a workflow you want to use, you can add and connect the Initiate an Incident step. This allows you to initiate an incident as part of your existing flow process. Not only does this allow you to take advantage of the Incident Console, but you can also extend your flow automation using related incident triggers. For more information see Incident Triggers in the online help.
The rest of this section describes how to work with Flow Triggers that are connected to the Initiate an Incident step.
Configuring a Flow Trigger form for access by an Inbound Integration
In order for a Flow Trigger form to be triggered using an inbound integration, it must be enabled in Web UI and the workflow it belongs to must be enabled. Additionally, the authenticating user must have permission to initiate the form.
Customizing form settings
When you trigger an incident you can override the following form settings:
- Incident Details: Specify the incident summary, description, and severity.
- Recipients: Set the user, devices, and groups that will be notified to participate as resolvers for the incident.
- Properties: Set the value of any form property.
- Handling Options: Set any handling section option, including the priority, event duration, voicemail options, and escalation and device overrides.
- Targeted Devices: Set whether the notification targets all the resolver’s available devices or only targets specific devices such as their Work Email and Work Phone.
- Sender Overrides: By setting the sender information (displayName and callerID) to meaningful values, resolvers 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 when triggering the flow. Alternatively, you can Create an Incident in your instance, but the incident will not have the robust capabilities and features that are available when you trigger an incident.
DEFINITION
Trigger an incident by sending a POST request to the trigger URL. The trigger URL is different depending on how the incident is triggered. If using a custom HTTP Request trigger, you can obtain the trigger URL from the step in the flow canvas. 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
| incidentDetails | IncidentDetails Object |
| The summary, description, and severity of the incident. | |
| recipients | array [RecipientTrigger Object] |
| Specifies the people, devices, and groups that are directly targeted when this incident is triggered. If the form is configured use default recipients, this field is optional. Otherwise, you must specify at least one recipient. | |
| properties | PropertyValues Object |
| Allows you to set the values of form properties. | |
| expirationInMinutes | integer |
| The duration of the event in minutes. | |
| 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. |
|
| escalationOverride | Boolean |
When this value is set to true, xMatters ignores shift escalation delays and immediately broadcasts the message to all recipients. |
|
| bypassPhoneIntro | Boolean |
When this value is set to true, xMatters omits the standard voice greeting and plays the message immediately. |
|
| 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. |
|
| voicemailOptions | VoicemailOptions Object |
| For voice notifications, this defines whether to try the call again or leave a message. | |
| senderOverrides | SenderOverrides Object |
| 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. |
|
| targetDeviceNames | array [DeviceName object] |
Defines the devices that are targeted by notifications. When values are provided for this field, targetDeviceNames cannot be set to true. |
RESPONSES
| Success | Response code 202 Accepted and a request identifier in the response body. You can use the request identifier with GET /incidents to search for incidents. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create an incident
Create an incident
REQUEST - Create an incident in xMatters
curl --user username --header "Content-Type: application/json" --request POST -d '{
"summary": "We are experiencing an issue with Google Compute Engine in us-east1-c and us-east1-d",
"description": "Existing VMs may be unavailable or unreachable, and new VM creation may fail beginning on Wednesday, 2021-06-30 10:15 US/Pacific",
"status": "Open",
"severity": "Critical",
}' "https://acmeco.xmatters.com/api/xm/1/incidents"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/incidents/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.summary = 'We are experiencing an issue with Google Compute Engine in us-east1-c and us-east1-d';
data.description = 'Existing VMs may be unavailable or unreachable, and new VM creation may fail beginning on Wednesday, 2021-06-30 10:15 US/Pacific';
data.status = 'Open';
data.severity = 'Critical';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created " + 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 = "/incidents"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
incidents_data = {
"summary": "We are experiencing an issue with Google Compute Engine in us-east1-c and us-east1-d",
"description": "Existing VMs may be unavailable or unreachable, and new VM creation may fail beginning on Wednesday, 2021-06-30 10:15 US/Pacific",
"status": "Open",
"severity": "Critical",
}
response = requests.post(url, headers=headers, json=conference_data, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print ("Created " + response.json()["targetName"] + ". id = " + response.json()[
"id")
]
RESPONSE
{
"id": "ab1d6091-7d58-41e2-af72-49c69b3d9b65s",
"incidentIdentifier": "INC-14",
"summary": "We are experiencing an issue with Google Compute Engine in us-east1-c and us-east1-d",
"description": "Existing VMs may be unavailable or unreachable, and new VM creation may fail beginning on Wednesday, 2021-06-30 10:15 US/Pacific",
"severity": {
"name": "Critical",
},
"status": {
"name": "Open",
},
"initiatedBy": {
"id": "526b6c8a-5fc7-4227-b946-af2220d66524",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/526b6c8a-5fc7-4227-b946-af2220d66524"
}
},
"commander": {
"id": "526b6c8a-5fc7-4227-b946-af2220d66524",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/526b6c8a-5fc7-4227-b946-af2220d66524"
}
},
"createdAt": "2021-04-05T04:51:48.275Z",
"updatedAt": "2021-04-05T04:51:48.275Z",
"links": {
"self": "/api/xm/1/incidents/ab1d6091-7d58-41e2-af72-49c69b3d9b65s"
}
}
Creates an incident in xMatters. The summary, and description fields are required to create an incident, but are optional when updating an existing incident. By default, the authenticating user that created the incident is set as the incident commander. Incidents created through this endpoint do not trigger flows, and do not have the more robust functionality of user responses, collaboration channels, flood control. To use these extra features, use the [Trigger an incident]{#trigger-incident} endpoint instead.
DEFINITION
POST /incidents
BODY PARAMETERS
| summary | string |
| The high-level summary of the incident. | |
| description | string |
| The concise description of the incident that provides users with additional information. | |
| severity | string |
The initial severity of the incident. If one is not provided during incident creation, the default severity of Medium is used. Available options are:
|
|
| status | string |
The initial status of the incident. If one is not provided during incident creation, the default status of Open is used. Available options are:
|
RESPONSES
| Success | Response code 201 Created and a Incidents object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify an incident
Modify an incident
REQUEST - Modify an existing incident in xMatters by changing its status and severity
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "ab1d6091-7d58-41e2-af72-49c69b3d9b65s",
"status": "Mitigated",
"severity": "Medium"
}' "https://acmeco.xmatters.com/api/xm/1/incidents"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/incidents/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = 'ab1d6091-7d58-41e2-af72-49c69b3d9b65s';
data.status = 'Mitigated';
data.severity = 'Medium';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Modified " + 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 = "/incidents"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
incidents_data = {
"id": "ab1d6091-7d58-41e2-af72-49c69b3d9b65s",
"status": "Mitigated",
"severity": "Medium",
}
response = requests.post(url, headers=headers, json=conference_data, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print ("Modified " + response.json()["targetName"] + ". id = " + response.json()[
"id")
]
RESPONSE
{
"id": "ab1d6091-7d58-41e2-af72-49c69b3d9b65s",
"incidentIdentifier": "INC-14",
"summary": "We are experiencing an issue with Google Compute Engine in us-east1-c and us-east1-d",
"description": "Existing VMs may be unavailable or unreachable, and new VM creation may fail beginning on Wednesday, 2021-06-30 10:15 US/Pacific",
"severity": {
"name": "Medium",
},
"status": {
"name": "Mitigated",
},
"initiatedBy": {
"id": "526b6c8a-5fc7-4227-b946-af2220d66524",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/526b6c8a-5fc7-4227-b946-af2220d66524"
}
},
"commander": {
"id": "526b6c8a-5fc7-4227-b946-af2220d66524",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/526b6c8a-5fc7-4227-b946-af2220d66524"
}
},
"createdAt": "2021-04-05T04:51:48.275Z",
"updatedAt": "2021-04-05T04:51:48.275Z",
"links": {
"self": "/api/xm/1/incidents/ab1d6091-7d58-41e2-af72-49c69b3d9b65s"
}
}
Updates an existing incident in xMatters. To find the id of an incident, use Get incidents.
DEFINITION
POST /incidents
BODY PARAMETERS
| id | string |
The unique identifier (id) of the incident. |
|
| incidentIdentifier | string |
| The unique alpha-numeric incident number used to look up the incident. | |
| summary | string |
| The high-level summary of the incident. | |
| description | string |
| The concise description of the incident that provides users with additional information. | |
| severity | string |
The initial severity of the incident. If one is not provided during incident creation, the default severity of Medium is used. The available options are not case-sensitive:
|
|
| status | string |
The initial status of the incident. If one is not provided during incident creation, the default status of OPEN is used. The available options are not case-sensitive:
|
RESPONSES
| Success | Response code 201 Created and a Incident object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Add a timeline note
Add a note to the timeline of an existing incident.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"entryType": "TIMELINE_NOTE",
"text": "Looking into the problem"
}' "https://acmeco.xmatters.com/api/xm/1/incidents/fcf9192d-a647-4e16-b9e2-1768de421e08/timeline-entries"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/incidents/fcf9192d-a647-4e16-b9e2-1768de421e08/timeline-entries",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.entryType: 'TIMELINE_NOTE';
data.text = 'Looking into the problem';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Note added to incident 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 + '/incidents/fcf9192d-a647-4e16-b9e2-1768de421e08/timeline-entries'
headers = {'Content-Type': 'application/json'}
auth = HTTPBasicAuth('username', 'password')
data = {
'entryType': 'TIMELINE_NOTE',
'text': '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": "afcf04af-b21b-4eb4-bf11-f979ec82b031",
"incident": {
"id": "fcf9192d-a647-4e16-b9e2-1768de421e08",
"links": {
"self": "/api/xm/1/incidents/fcf9192d-a647-4e16-b9e2-1768de421e08"
}
},
"at": "2021-03-30T00:00:17.940Z",
"entryType": "TIMELINE_NOTE",
"text": "Looking into the problem",
"addedBy": {
"id": "a0657a71-18dc-4f5d-a8b0-a72d6c32ea0a",
"targetName": "jdavidson",
"firstName": "Jane",
"lastName": "Davidson",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/a0657a71-18dc-4f5d-a8b0-a72d6c32ea0a"
},
"status": "ACTIVE"
}
}
Adds a note to the timeline of an existing incident in your xMatters system. The authenticating user who posts the request is documented the author of the note.
DEFINITION
POST /incidents/{incidentID}/timeline-entries
URL PARAMETERS
| incidentID | string |
| The unique identifier (or UUID) of an incident in your xMatters system. For example: fcf9192d-a647-4e16-b9e2-1768de421e08 |
BODY PARAMETERS
| entryType | string |
The type of entry to add to the timeline. Valid value is: TIMELINE_NOTE. |
|
| text | string |
| The text of the note you want to add to the incident. |
RESPONSES
| Success | Response code 201 Created and an Incidents note object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Incidents objects
Incident object
Incident Object
{
"data": [
{
"id": "ab1d6091-7d58-41e2-af72-49c69b3d9b65s",
"incidentIdentifier": "INC-14",
"summary": "We are experiencing an issue with Google Compute Engine in us-east1-c and us-east1-d",
"description": "Existing VMs may be unavailable or unreachable, and new VM creation may fail beginning on Wednesday, 2021-06-30 10:15 US/Pacific",
"severity": {
"name": "Critical",
},
"status": {
"name": "In Progress",
},
"initiatedBy": {
"id": "526b6c8a-5fc7-4227-b946-af2220d66524",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/526b6c8a-5fc7-4227-b946-af2220d66524"
}
},
"commander": {
"id": "526b6c8a-5fc7-4227-b946-af2220d66524",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/526b6c8a-5fc7-4227-b946-af2220d66524"
}
},
"createdAt": "2021-04-05T04:51:48.275Z",
"updatedAt": "2021-04-05T04:51:48.275Z",
"impactedServices": [
{
"id": "9600557a-7005-414e-bd70-e22fd3a5e0b8",
"targetName": "East Coast Monitoring",
"recipientType": "SERVICE",
"description": "Service to monitor and maintain East Coast servers.",
"ownedBy": {
"id": "deaf3cb8-d6d6-437d-a809-59e6e369ba41",
"targetName": "East Coast MIM Team 1",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/deaf3cb8-d6d6-437d-a809-59e6e369ba41"
}
},
"links": {
"self": "/api/xm/1/incidents/ab1d6091-7d58-41e2-af72-49c69b3d9b65s"
}
}
],
"links": {
"self": "/api/xm/1/incidents?offset=0&limit=100"
}
}
Describes an incident in xMatters.
| id | string |
The unique identifier (id) of the incident. |
|
| incidentIdentifier | string |
| The unique alpha-numeric incident number. If an incident identifier is not provided, a default identifier beginning with INC is created by xMatters. For example: INC-145. | |
| summary | string |
| The title of the incident. | |
| description | string |
| The description of the incident. | |
| severity | string |
The initial severity of the incident. If one is not provided during incident creation, the default severity of Medium is used. The vailable options are not case-sensitive:
|
|
| status | string |
The initial status of the incident. If one is not provided during incident creation, the default status of OPEN is used. The available options are not case-sensitive:
|
|
| initiatedBy | string |
| PersonReference of the authenticating user, or the authentication credentials used to create the incident. | |
| commander | string |
| PersonReference of the user responsible for the incident. By default, the authenticating credentials of the person who initiated the incident are used until the commander is changed to another user. | |
| requestId | string |
| The unique identifier returned from a request to trigger an incident. | |
| resolver.group | string |
| The target name or unique identifier of a group in your xMatters instance. Any spaces or special characters in the group name must be URL-encoded. | |
| impactedServices | string |
| A list of services impacted by this incident. An incident can impact multiple services. |
Incident note object
Incident Note Object
{
"id": "afcf04af-b21b-4eb4-bf11-f979ec82b031",
"incident": {
"id": "fcf9192d-a647-4e16-b9e2-1768de421e08",
"links": {
"self": "/api/xm/1/incidents/fcf9192d-a647-4e16-b9e2-1768de421e08"
}
},
"at": "2021-03-30T00:00:17.940Z",
"entryType": "TIMELINE_NOTE",
"text": "Looking into the problem",
"addedBy": {
"id": "a0657a71-18dc-4f5d-a8b0-a72d6c32ea0a",
"targetName": "jdavidson",
"firstName": "Jane",
"lastName": "Davidson",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/a0657a71-18dc-4f5d-a8b0-a72d6c32ea0a"
},
"status": "ACTIVE"
}
}
Describes a timeline note added to an incident in xMatters.
| id | string |
The unique identifier (id) of the incident. |
|
| at | string |
| A timestamp in UTC format of when the note was added to the incident. | |
| entryType | string |
The type of entry to add to the timeline. Valid value is: TIMELINE_NOTE. |
|
| text | string |
| The comment provided by the authenticating user. | |
| addedBy | string |
| PersonReference of the user that added the comment to the incident. |
IncidentDetails object
IncidentDetails Object
{
"summary": "We are experiencing an issue with Google Compute Engine in us-east1-c and us-east1-d",
"description": "Existing VMs may be unavailable or unreachable, and new VM creation may fail beginning on Wednesday, 2021-06-30 10:15 US/Pacific",
"severity": {
"name": "Critical",
},
}
Describes the incident details required to trigger an incident in xMatters.
| summary | string |
| The title of the incident. | |
| description | string |
| The description of the incident. | |
| severity | string |
The initial severity of the incident. If one is not provided during incident creation, the default severity of MEDIUM is used. The vailable options are not case-sensitive:
|
INTEGRATIONS
You can use the Integrations endpoint to retrieve data about integrations in your system, or to create an integration between your communication plan and another application, and you can create multiple integrations for a single communication plan. For more information about integrations in xMatters and the Integration Builder, see the Integration Builder section in the xMatters online help.
For information on other plan components, see Plans.
Integration scripts
Integration scripts are base64-encoded before they are returned via the response. Encoding the script ensures that any special characters (newlines, tabs, etc.) are transmitted in the JSON payload without issues. You can view the decoded contents of the script using the script editor in the Integration Builder.
See the xMatters online help for more information on scripting for integrations.
Get an integration
GET an integration
REQUEST
curl --user username
"https://acmeco.xmatters.com/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations/2eebaa7f-c66a-453c-8ce1-a11441548121"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations/2eebaa7f-c66a-453c-8ce1-a11441548121",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved integration plan: " + json.name + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
planId = "0482202f-bc59-4f4d-a5c7-4a451c5f80ac"
integrationId = "2eebaa7f-c66a-453c-8ce1-a11441548121"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/" + planId + "/integrations/" + integrationId
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 integration with name: "'
+ rjson["name"]
+ '" of type: "'
+ rjson["integrationType"]
+ '"'
)
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": "2eebaa7f-c66a-453c-8ce1-a11441548121",
"plan":
{
"id": "0482202f-bc59-4f4d-a5c7-4a451c5f80ac",
},
"form":
{
"id": "c5100198-2820-4fe6-a4e4-4c98a0d5894e",
},
"name": "Slack Post",
"integrationType": "OUTBOUND_WEBHOOK",
"operation": "RUN_SCRIPT",
"triggeredBy": "STATUS",
"deployed": true,
"environment": "HOSTED",
"script":
"Ci8qKioqKioqKioq
[truncated base-64 encoded script]
0byBTbGFjayBjaGFubmVsLicpOw=="
}
Returns information about an inbound or outbound integration for a specific communication plan.
DEFINITION
GET /plans/{planId}/integrations/{integrationId}
URL PARAMETERS
| {planId} | string |
| The UUID of the communication plan that the integration belongs to. To get the ID of a plan, see Get communication plans. | |
| {integrationId} | string |
The name or unique identifier (id) of the integration. To get a list of integration IDs for a plan, see Get integrations. |
RESPONSES
| Success | Response code 200 OK and an Integration object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get integrations
GET integrations
REQUEST
curl --user username
"https://acmeco.xmatters.com/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " integrations." );
for (var i in json.data ) {
console.log(json.data[i].name);
}}
import requests
from requests.auth import HTTPBasicAuth
import json
planId = "0482202f-bc59-4f4d-a5c7-4a451c5f80ac"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/integrations"
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"])
+ " integrations."
)
for rd in rjson["data"]:
print(
'Found integration with name "'
+ rd["name"]
+ '", type: "'
+ rd["type"]
+ '", and 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" : 3,
"total" : 3,
"data" :[
{
{
"id": "2eebaa7f-c66a-453c-8ce1-a11441548121",
"plan":
{
"id": "0482202f-bc59-4f4d-a5c7-4a451c5f80ac",
},
"form":
{
"id": "c5100198-2820-4fe6-a4e4-4c98a0d5894e",
},
"name": "OUTBOUND INTEGRATION NAME",
"integrationType": "OUTBOUND_WEBHOOK",
"operation": "RUN_SCRIPT",
"triggeredBy": "STATUS",
"deployed": true,
"environment": "HOSTED",
"script":
"dmFyIHBsYW5faWQgPSAnNT
[base-64 encoded script]
3RhdHVzQ29kZTsKfQoK"
},
...truncated list of Integration objects...
}],
"links":
{
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations?offset=0&limit=100"
}
}
Returns a list of the inbound and outbound integrations for the specified communication plan.
DEFINITION
GET /plans/{planId}/integrations
GET /plans/{planId}/integrations?integrationType=INBOUND_WEBHOOK&deployed=true&embed=logs
URL PARAMETERS
| planId | string |
| The UUID of the communication plan that you want to list integrations for. Use GET /communication plans to get the UUID of a plan. |
QUERY PARAMETERS
| integrationType | string |
Filter the results to only include integrations of the specified type. Valid values include:
|
|
| deployed | Boolean |
Filter the results to only include integrations that are active or inactive (use true to return only active integrations.) |
|
| embed | string |
A list of objects to embed in the response.
|
RESPONSES
| Success | Response code 200 OK and a pagination of Integration objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get integration logs
GET all logs for an integration
REQUEST
curl --user username
"https://acmeco.xmatters.com/api/xm/1/integrations/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/logs"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/integrations/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/logs",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " logs." );
}
import requests
from requests.auth import HTTPBasicAuth
import json
integrationId = "2eebaa7f-c66a-453c-8ce1-a11441548121"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/integrations/" + integrationId + "/logs"
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"])
+ " integration logs."
)
for rd in rjson["data"]:
print(
'Found integration log with id "'
+ rd["id"]
+ '", completed on: "'
+ rd["completed"]
+ '"'
)
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": 100,
"total": 129,
"data": [
{
"id": "3111e2db-1bce-4217-90b1-6fc7bbacf212",
"integration": {
"id": "2eebaa7f-c66a-453c-8ce1-a11441548121",
"name": "Get Assignee",
"plan": {
"id": "0482202f-bc59-4f4d-a5c7-4a451c5f80ac",
"links": {
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac"
}
},
"links": {
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations/2eebaa7f-c66a-453c-8ce1-a11441548121"
}
},
"by": {
"id": "9bccb70b-ab35-4746-b9f5-fa6eca0b1450",
"targetName": "integrationUser",
"firstName": "Integration",
"lastName": "User",
"recipientType": "PERSON"
},
"completed": "2019-08-07T16:50:54.162Z",
"remoteAddress": "192.02.0.212",
"requestHeaders": {...request header parameters...},
"requestId": "c46019b2-ecda-47fe-9280-a91f035621fc",
"requestMethod": "POST",
"requestParameters": {...request query parameters...},
"url": "http://yourcompany.xmatters.com/api/integration/1/functions/9471ab34-f213-46b7-98fa-ec3187d9f9e8/triggers",
"status": "COMPLETED"
},
{...truncated list of integration logs...}
]
}
Returns all the Integration Log objects for an inbound or outbound integration, including integrations created when you add a built-in configuration or an event activity trigger in Flow Designer. The logs can be useful when debugging issues with integrations or flow steps. Logging must be enabled for the integration, flow, or built-in configuration to see successful requests; otherwise only failed requests are logged. Use the web user interface to enable and disable logging.
DEFINITION
GET /integrations/{integrationId}/logs
URL PARAMETERS
| integrationId | string |
| The UUID of the integration that you want to retrieve the logs for. Use GET /integrations to get the UUID of an integration. |
RESPONSES
| Success | Response code 200 OK and a pagination of Integration Log objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create an integration
Create an integration
REQUEST - Create an outbound integration This example shows how to create an outbound integration.
curl --user username:password --header "Content-Type: application/json" --request POST -d '{
"createdBy": "IB"
"form":
{
"id": "c5100198-2820-4fe6-a4e4-4c98a0d5894e"
},
"deployed" : true,
"name" : "My Outbound Integration",
"integrationType" : "OUTBOUND_WEBHOOK",
"environment" : "HOSTED",
"operation": "SEND_WEBHOOK",
"triggeredBy": "STATUS",
"endpoint":"33bdc52d-6294-4465-8ddf-12f872e627ce",
"script": "dmFyIHBsYW5faWQgPSAnNT
[base-64 encoded script]
3RhdHVzQ29kZTsKfQoK"
}' "https://acmeco.xmatters.com/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.createdBy = 'IB';
var form = {};
form.id = 'c5100198-2820-4fe6-a4e4-4c98a0d5894e';
data.form = form;
data.name = 'My Outbound Integration';
data.integrationType = 'OUTBOUND_WEBHOOK';
data.environment = 'HOSTED';
data.operation = 'SEND_WEBHOOK';
data.triggeredBy = 'STATUS';
data.deployed = 'TRUE';
data.script = 'dmFyIHBsYW5faWQgPSAnNT [base-64 encoded script] 3RhdHVzQ29kZTsKfQoK';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created integration: " + json.name + ". 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
plan_id = "0482202f-bc59-4f4d-a5c7-4a451c5f80ac"
url = "https://acmeco.xmatters.com/api/xm/1/plans/{plan_id}/integrations"
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"form": {"id": "c5100198-2820-4fe6-a4e4-4c98a0d5894e"},
"deployed": True,
"name": "My Outbound Integration",
"integrationType": "OUTBOUND_WEBHOOK",
"environment": "HOSTED",
"operation": "SEND_WEBHOOK",
"triggeredBy": "STATUS",
"createdBy": "IB",
"endpoint": "33bdc52d-6294-4465-8ddf-12f872e627ce",
"script": "dmFyIHBsYW5faWQgPSAnNT...[base-64 encoded script]...3RhdHVzQ29kZTsKfQoK",
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print(
"Integration "
+ rjson.get("name")
+ " was successfully created with ID: "
+ rjson.get("id")
)
else:
print("The request did not succeed. Response code is: " + str(responseCode))
print(json.dumps(response.json(), indent=4, sort_keys=True))
RESPONSE
{
"id": "f0b88866-6ccd-462f-a514-24a4b93da601",
"plan":
{
"id": "0482202f-bc59-4f4d-a5c7-4a451c5f80ac",
"links":
{
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac"
}
},
"form":
{
"id": "c5100198-2820-4fe6-a4e4-4c98a0d5894e",
"links":
{
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/forms/c5100198-2820-4fe6-a4e4-4c98a0d5894e"
}
},
"deployed": true,
"endpoint":
{
"id": "118f3fb2-685e-4837-b562-a2a9781546b3",
"plan":
{
"id": "0482202f-bc59-4f4d-a5c7-4a451c5f80ac",
"links":
{
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac"
}
},
"links":
{
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/endpoints/118f3fb2-685e-4837-b562-a2a9781546b3"
}
},
"environment": "HOSTED",
"name": "My Outbound Integration",
"operation": "SEND_WEBHOOK",
"triggeredBy": "STATUS",
"createdBy": "IB",
"integrationType": "OUTBOUND_WEBHOOK"
}
Creates a new integration in the specified communication plan.
DEFINITION
POST /plans/{planId}/integrations
URL PARAMETERS
| {planId} | string |
| The UUID of the communication plan to create the integration in. To get the ID of a plan, see Get communication plans |
BODY PARAMETERS
| form | ReferenceById |
| A reference to the form associated with this integration. | |
| name | string |
| The name of the integration. | |
| integrationType | string |
Whether the integration is inbound or outbound. Values include:
|
|
| environment | string |
The location of the inbound or outbound integration. Values include:
|
|
| operation | string |
The action the integration performs. Valid values for inbound integrations include:
|
|
| triggeredBy | string |
Outbound integrations only: The system activity that triggers the outbound integration. Valid values include:
|
|
| authenticationType | string |
Inbound integrations only: The authentication method used to trigger the integration. The default is ANY, which allows all methods. Valid values are:
|
|
| createdBy | string |
How the integration was created. Valid values include:
|
|
| deployed | Boolean |
| Whether the inbound or outbound integration is active. True if the integration is active. | |
| script | string |
The text of the transformation script. Scripts should be base64-encoded, and do not apply to CREATE_EVENT_SIMPLE inbound integrations. |
|
| endpoint | Endpoint object |
| Outbound integrations only: The endpoint that xMatters will send data to when the specified system activity occurs. | |
| integrationService | string |
For outbound integrations with the SEND_TO_IA operation, the name of the integration service that the integration will target. |
RESPONSES
| Success | Response code 200 Created and an Integration object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify an Integration
Modifies an Integration
REQUEST The following example shows how to modify an integration so it is not deployed.
curl --user username:password --header "Content-Type: application/json" --request POST -d '{
"deployed" : false,
"id": "4133b46b-e19e-411f-8bb7-74babf482e1e"
}' "https://acmeco.xmatters.com/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '4133b46b-e19e-411f-8bb7-74babf482e1e';
data.deployed = 'FALSE';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Modified integration: " + json.name + ". 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
plan_id = "0482202f-bc59-4f4d-a5c7-4a451c5f80ac"
url = "https://acmeco.xmatters.com/api/xm/1/plans/{plan_id}/integrations"
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
data = {
"id": "c5100198-2820-4fe6-a4e4-4c98a0d5894e",
"deployed" : False
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if (responseCode == 200):
rjson = response.json();
print('Integration ' + rjson.get('name') + ' was successfully updated with ID: ' + rjson.get('id') )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
print(json.dumps(response.json(), indent=4, sort_keys=True))
RESPONSE
{
"id": "4133b46b-e19e-411f-8bb7-74babf482e1e",
"plan":
{
"id": "0482202f-bc59-4f4d-a5c7-4a451c5f80ac",
"links":
{
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac"
}
},
"form":
{
"id": "c5100198-2820-4fe6-a4e4-4c98a0d5894e",
"links":
{
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/forms/c5100198-2820-4fe6-a4e4-4c98a0d5894e"
}
},
"deployed": false,
"endpoint":
{
"id": "118f3fb2-685e-4837-b562-a2a9781546b3",
"plan":
{
"id": "0482202f-bc59-4f4d-a5c7-4a451c5f80ac",
"links":
{
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac"
}
},
"links":
{
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/endpoints/118f3fb2-685e-4837-b562-a2a9781546b3"
}
},
"environment": "HOSTED",
"name": "My Integration",
"operation": "SEND_WEBHOOK",
"triggeredBy": "STATUS",
"integrationType": "OUTBOUND_WEBHOOK"
}
To modify an integration, provide its identifier in the id field and then provide a list of fields that you want to modify.
DEFINITION
POST /plans/{planId}/integrations
URL PARAMETERS
| planId | string |
| The UUID of the communication plan that is associated with the integration. |
BODY PARAMETERS
| id | string |
| The unique identifier of the integration you want to modify. |
Provide the id of the integration and the fields you want to modify. To view the list of field that you can modify, see Create an integration.
RESPONSES
| Success | Response code 200 OK and an Integration object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete an integration
Delete an integration
REQUEST: Delete an integration
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations/DataDog"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations/DataDog",
"method": "DELETE",
"headers" : {"Content-Type": "application/json"}
});
response = request.write();
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the " + json.targetName + "integration");
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/"
plan_ID = "0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations/DataDog"
url = base_URL + endpoint_URL + plan_ID
response = requests.delete(url, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Deleted the " + json.targetName + "integration");
RESPONSE
{
"id": "2eebaa7f-c66a-453c-8ce1-a11441548121",
"plan":
{
"id": "0482202f-bc59-4f4d-a5c7-4a451c5f80ac",
"links":
{
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac"
}
},
"form":
{
"id": "c5100198-2820-4fe6-a4e4-4c98a0d5894e",
"links":
{
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/forms/c5100198-2820-4fe6-a4e4-4c98a0d5894e"
}
},
"deployed": true,
"environment": "HOSTED",
"name": "My Integration",
"operation": "RUN_SCRIPT",
"script": "
var callback = JSON.parse(request.body);
console.log('Executing outbound integration for xMatters event ID: ' + callback.eventIdentifier);
var json = {};
json.ticket = {};
json.ticket.subject = 'Update from xMatters at ' + callback.date;
var response = request.write(json);",
"triggeredBy" : "STATUS",
"integrationType" : "OUTBOUND_WEBHOOK"
}
}
Deletes an integration associated with a communication plan.
DEFINITION
DELETE /plans/{planId}/integrations/{integrationId}
URL PARAMETERS
| planId | string |
| The UUID of the communication plan that is associated with the integration. | |
| integrationId | string |
| The name or UUID of the integration. |
RESPONSES
| Success | Response code 200 OK and an Integration object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Integration objects
Integration object
Integration object
{
"count": 2,
"total": 4,
"data": [
{
"id": "0c8892bf-fd3f-4d76-96f8-056f6d4cdf02",
"plan": {
"id": "54dcaeab-0c7b-45d7-a0c3-9db75c69be64"
},
"form": {
"id": "7dde3bf9-79b9-4901-aeda-ca5878e8130c"
},
"name": "Event Injection",
"integrationType": "INBOUND_WEBHOOK",
"operation": "CREATE_EVENT",
"authenticationType": "API_KEY",
"deployed": true,
"environment": "HOSTED",
"script":
"dmFyIHBsYW5faWQgPSAnNT
[base-64 encoded script]
3RhdHVzQ29kZTsKfQoK",
"logs": {
"count": 1,
"total": 1,
"data": [...integration log objects...],
"links": {
"self": "/api/xm/1/plans/54dcaeab-0c7b-45d7-a0c3-9db75c69be64/integrations/0c8892bf-fd3f-4d76-96f8-056f6d4cdf02/logs?offset=0&limit=100"
}
}
},
{
"id": "a7b59b84-19c0-4ec9-a990-4f7f50b9c3ee",
"plan": {
"id": "54dcaeab-0c7b-45d7-a0c3-9db75c69be64"
},
"form": {
"id": "7dde3bf9-79b9-4901-aeda-ca5878e8130c"
},
"name": "Slack Post",
"integrationType": "OUTBOUND_WEBHOOK",
"operation": "RUN_SCRIPT",
"triggeredBy": "STATUS",
"createdBy": "FLOW",
"deployed": true,
"environment": "HOSTED",
"script":
"LyoqKioqKioqKioq
[base-64 encoded script]
XIgc2NyaXB0LicpOwo=",
"logs": {
"count": 100,
"total": 125,
"data": [...integration log objects...],
"links": {
"self": "/api/xm/1/plans/54dcaeab-0c7b-45d7-a0c3-9db75c69be64/integrations/a7b59b84-19c0-4ec9-a990-4f7f50b9c3ee/logs?offset=0&limit=100"
}
}
}
],
"links": {
"self":"/api/xm/1/plans/54dcaeab-0c7b-45d7-a0c3-9db75c69be64/integrations?offset=0&limit=100"
}
}
An integration object describes an inbound or outbound integration associated with a communication plan.
| id | string |
| The unique identifier of the integration. This value can be used to build the URL path to trigger an integration. | |
| plan | ReferenceById |
| A reference to the communication plan associated with this integration. | |
| form | ReferenceById |
| A reference to the form associated with this integration. | |
| name | string |
| The name of the integration. | |
| integrationType | string |
Whether the integration is inbound or outbound. Values include:
|
|
| operation | string |
The action the integration performs. Valid values for inbound integrations include:
|
|
| triggeredBy | string |
Outbound integrations only: The system activity that triggers the outbound integration. Valid values include:
|
|
| createdBy | string |
How the integration was created. Valid values include:
|
|
| authenticationType | string |
Inbound integrations only: The authentication method used to trigger the integration. The default is ANY, which allows all methods. Valid values are:
|
|
| endpoint | Endpoint object |
| Outbound integrations only: The endpoint that xMatters will send data to when the specified system activity occurs. | |
| deployed | Boolean |
| Whether or not the inbound or outbound integration is active. True if the integration is active. | |
| environment | string |
The location of the inbound or outbound integration. Values include:
|
|
| script | string |
| The base64-encoded script. | |
| logs | Pagination of Integration Log objects |
| A list of log entries associated with the integration. |
Integration Log object
Integration Log object
{
"id": "3111e2db-1bce-4217-90b1-6fc7bbacf212",
"integration": {
"id": "2eebaa7f-c66a-453c-8ce1-a11441548121",
"name": "Get Assignee",
"plan": {
"id": "0482202f-bc59-4f4d-a5c7-4a451c5f80ac",
"links": {
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac"
}
},
"links": {
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/integrations/2eebaa7f-c66a-453c-8ce1-a11441548121"
}
},
"by": {
"id": "9bccb70b-ab35-4746-b9f5-fa6eca0b1450",
"targetName": "integrationUser",
"firstName": "Integration",
"lastName": "User",
"recipientType": "PERSON"
},
"completed": "2019-08-07T16:50:54.162Z",
"remoteAddress": "192.02.0.212",
"requestHeaders": {...request header parameters...},
"requestId": "c46019b2-ecda-47fe-9280-a91f035621fc",
"requestMethod": "POST",
"requestParameters": {...request query parameters...},
"url": "http://yourcompany.xmatters.com/api/integration/1/functions/9471ab34-f213-46b7-98fa-ec3187d9f9e8/triggers",
"status": "COMPLETED"
},
An integration log object describes a log entry of an inbound or outbound integration.
| id | string |
| The unique identifier (UUID) of the integration log. | |
| integration | Integration Reference |
| A reference to the integration the log relates to. | |
| completed | string |
| The date and time the integration request finished processing. | |
| requestMethod | string |
| The HTTP method that triggered the request (for example, POST). | |
| requestHeaders | requestHeaders object |
| An object containing the HTTP headers included in the request. See https://en.wikipedia.org/wiki/List_of_HTTP_header_fields for more information on HTTP request headers. | |
| requestParameters | requestParameters object |
| An object containing any query parameters included in the HTTP request (for example, if the trigger URL contained the apiKey of the authenticating user, it would be listed under request parameters). See https://en.wikipedia.org/wiki/Query_string for information on query parameters. | |
| requestBody | string |
| The body of the HTTP request. | |
| remoteAddress | string |
| The IP address that sent the request to xMatters. | |
| requestId | string |
| The unique identifier (UUID) assigned to the request by xMatters. | |
| status | string |
The status of the request.
|
|
| by | Person Reference object |
| Information on the authenticating user of the HTTP request that triggered the request. |
Integration Reference object
Integration Reference object
"integration": {
"id": "2eebaa7f-c66a-453c-8ce1-a11441548121",
"name": "Get Assignee",
"plan": {
"id": "0482202f-bc59-4f4d-a5c7-4a451c5f80ac",
"links": {
"self": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac"
}
}
Describes a reference to an integration, including its name, unique identifier and the plan it belongs to.
| id | string |
| The unique identifier of the integration. | |
| plan | Plan Reference object |
| A reference to the communication plan the integration belongs to. | |
| name | string |
| The user-defined name of the integration. |
OAUTH
OAuth2.0 authentication allows you to access the xMatters REST API by providing an authentication token in the header of each request. This allows you to access the xMatters REST API without storing sensitive user credentials.
Access tokens are temporary and must be refreshed periodically. You can revoke tokens at any time.
Prerequisites
You need the following information before getting started with OAuth:
- The client ID of your xMatters instance. To locate your client ID, go to the xMatters Web user interface, expand the Workflows menu, and select OAuth. The OAuth page opens and your client ID is displayed.
- The user name and password of the account that you want to use to authenticate requests.
OAuth Workflow
- Use your client ID and authentication credentials to obtain an access token and a refresh token.
- Once you have obtained these tokens you do not need to store authentication credentials.
- You can now authorize requests using the access token instead of a user ID and password.
- When an access token expires, you can obtain a new access token by using the refresh access token and client ID.
Revoking tokens
Revoking authentication tokens is done using the xMatters Web user interface. For detailed instructions on deleting your authentication tokens, or the tokens of another user in your system, see OAuth Authentication
Obtain an access token and refresh token
Obtain an access token and refresh token
REQUEST (obtain an access token)
curl --request POST --data 'grant_type=password&client_id=7469ebe0-4dff-4a1b-84fe-0d1b3baf9dcf&username=username&password=password''https://acmeco.xmatters.com/api/xm/1/oauth2/token'
/**
* Flow Designer currently uses HTTP Basic Authentication
* for xMatters endpoints.
*/
import requests
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/oauth2/token"
client_id = "7469ebe0-4dff-4a1b-84fe-0d1b3baf9dcf"
username = "username"
password = "password"
grant_type = "password"
url = (
base_URL
+ endpoint_URL
+ "?grant_type="
+ grant_type
+ "&client_id="
+ client_id
+ "&username="
+ username
+ "&password="
+ password
)
headers = {"Content-Type": "application/json"}
response = requests.post(url, headers=headers)
if response.status_code == 200:
rjson = response.json()
print(
"Access token: "
+ rjson.get("access_token")
+ ", \nRefresh token: "
+ rjson.get("refresh_token")
)
else:
print("Could not get an access token")
RESPONSE
{
"access_token":"eyJhbGciOiJSUzI1NiJ9.eyJwIjoiLy8vL3ovLy8vLy8vLy8vLy8vLy8vLy8vLy8vLytmLy8vLy8vLy9QLy8vLy8vLy8vQi83Ly8vLy8vLy8vLy8vLy8vLy8vLy8vLy8vL0R3PT0iLCJhdWQiOlsiaWJhdXRvMS5iZXNwaW4uc2hhcmVkLWRldi54bWF0dGVycy5jb20iXSwic3ViIjoic2FuZHJhIiwiYXpwIjoiNzQ2OWViZTAtNGRmZi00YTFiLTg0ZmUtMGQxYjNiYWY5ZGNmIiwiaXNzIjoieG1hdHRlcnMiLCJzYmkiOjUxNDY0MiwiZXhwIjoxNDc1ODYxMzQwLCJpYXQiOjE0NzU4NjA0NDAsImFpZCI6MjAwMDIyLCJqdGkiOiI1YTNkNWY3MC0yYmZiLTQ1YTUtOWVhOC1mZDY5ZDUzMDU5ZGYifQ.B0_fslYEiq7mNiTDR7QUg1n3aFmQtlsXanzLZi5FGXJooqZo-OqgpkfSekkNTXwED7kTPkg8Yw3TgyO8V5UIGvstpuibvuu130z0hRCQU0UOMN8O1f9xlpLl3Z3ZqOhGjIQfS4WJKyKI7lA98KnFJ7z9zNN98X59AgBA3PFdf7OSsHDPpBHZakxolRfa85gFxONzpZSVCxPaIN7SE179a-VYbZPvIVieXC4BSUi7S5zVhgCJFynsTfmUe62SWWqrvjq09rEi1I-MhsQNnASL1xuXHyiJrBBUoiM8rid9q9LKU8eB6aZmAET72-URDk3ym1xMfGgpDFO8dnKpersnLA",
"token_type":"bearer",
"refresh_token":"4a90179e-12e8-4965-bc0c-66c0f6b70458",
"expires_in":588,
"jti":"5a3d5f70-2bfb-45a5-9ea8-fd69d53059df"
}
To obtain an OAuth2.0 access token and a refresh token, provide your client ID and the credentials of an account that you want to use to authorize requests. The authorization token provides the same xMatters permissions as the user account used to create the token.
Once you have obtained these tokens, you can use them (along with your client ID) to
access this API. This enables you to access this API without storing a user name and password. The access tokens expire after a fixed number of seconds as described by the expires_in field returned in the response body.
DEFINITION
POST /oauth2/token
QUERY PARAMETERS
| grant_type | string |
The grant type. To obtain a new OAuth token, set the grant type to password. |
|
| client_id | string |
| Your client ID. You can locate your client ID in the Web user interface by opening the Workflows menu and selecting OAuth. Example: 1432ebe0-4dff-4c3b-84fe-0d1aa31f51ee |
|
| username | string |
| The name of the user that is used to authenticate requests. | |
| password | string |
| The password of the user that is used to authenticate requests. |
RESPONSES
| Success | Response code 200 OK and an AccessToken object |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response codes. |
Authorize a request
Authorize a request
This example shows how to authorize a simple request to GET /people by using an OAuth Authorization token in the header instead of using HTTP Basic authentication
curl --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJwIjoiLy8vL3ovLy8vLy8vLy8vLy8vLy8vLy8vLy8vLytmLy8vLy8vLy9QLy8vLy8vLy8vQi83Ly8vLy8vLy8vLy8vLy8vLy8vLy8vLy8vL0R3PT0iLCJhdWQiOlsiaWJhdXRvMS5iZXNwaW4uc2hhcmVkLWRldi54bWF0dGVycy5jb20iXSwic3ViIjoic2FuZHJhIiwiYXpwIjoiNzQ2OWViZTAtNGRmZi00YTFiLTg0ZmUtMGQxYjNiYWY5ZGNmIiwiaXNzIjoieG1hdHRlcnMiLCJzYmkiOjUxNDY0MiwiZXhwIjoxNDc1ODY1MDU4LCJpYXQiOjE0NzU4NjQxNTgsImFpZCI6MjAwMDIyLCJqdGkiOiJiNjFkNDQ1ZC1kNzExLTRiNDgtYWFmYS01NmU5MjBiNTQ0ZmEifQ.JxfyQC2tuhTrXz0UtDxBJVKprV0d6unMKKD77VIQ_JxJb9BBtPr0q1mqPghIihP1RT5XmdLU9eV7aC-W5GbZVXarLuily5c1toa_zvkopOFH3-Hejk8HHWeilNiSl5tkU8mllEmGLaS_6t91dXAHDj4l_9a4e2JEY2tfSiORHNPx65GIPNhl95o1zg0GRCKcCGOujLT6FMG-hUy8-LztMal38lwsZ-FuOUsHhQhBRz5KI7CFuXQIpcIEmjxmHPZwuTmS2RveI7S4VLirUS_VFBgbMzwhKVMhaowyE-srjlZQiv4PTtNJqY4GBTfs9sivw4QYk5xCJoaex7p8kf6KUg'
'https://acmeco.xmatters.com/api/xm/1/people/mmcbride'
/**
* Flow Designer currently uses HTTP Basic Authentication for xMatters endpoints.
*/
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/people/mmcbride"
url = base_URL + endpoint_URL
token = "eyJhbGciOiJSUzI1NiJ9.eyJwIjoiMzEzalR2Ly8vLy8zLy8vLy82LzcvLy8vLy8vLytmLy8vLy8vLy9QLy8vLy8vLy8vQi83Ly8vLy8veC84Ly8vLy8vLy8vLy8vLy8vL0R3PT0iLCJhdWQiOlsiaWJhdXRvMS5iZXNwaW4uc2hhcmVkLWRldi54bWF0dGVycy5jb20iXSwic3ViIjoic2FuZHJhIiwiYXpwIjoiNzQ2OWViZTAtNGRmZi00YTFiLTg0ZmUtMGQxYjNiYWY5ZGNmIiwiaXNzIjoieG1hdHRlcnMiLCJzYmkiOjUxNDY0MiwiZXhwIjoxNDc5MzIzMzY0LCJpYXQiOjE0NzkzMjI0NjQsImFpZCI6MjAwMDIyLCJqdGkiOiI2ZjlkNGY0Yy1hZGJjLTQ3YzMtYjk5ZS00YjIzNWU1YTNkMzMifQ.5RQ7r8NQL_-_BO53T4ie_5a1MAISYDalmyVjzwZIUtadu8xd0WiFn2nFFlAZj9l6iFLxQuDbN8OVzh7jVB3pLu6EUKNO9V6_7woSycFq9iKGisO-QxKuG6eUPwSbRSwhVzqV8v3Zjcw2cpQAtZeTKmTUi8vma7dAKxq4cevSlcop2WZAHPckMI3lEFQ4CTT2_na11i55V8vdP54kRa95fLigDsDLt64gn6Xl5-kP-Z2FlZ8qy_gQ5GIf3iVXq3ASVmEq-93dPgpmSJOVXZGVG3zQIGt8706ofVvNmrGkUWpAKljo-A7IBhpMJFEex6grw35754v96VkSPdKzYSJ8KQ"
headers = {"Authorization": "bearer " + token}
print("Sending request to url: " + url)
response = requests.get(url, headers=headers)
responseCode = response.status_code
print("Received rsponse: " + str(responseCode))
if int(responseCode) == 200:
rjson = response.json()
print('Retrieved person 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)
)
To authorize a request using an OAuth token, include the Authorization: Bearer header in each request and set its value to a
valid access token.
To obtain an initial access token (and refresh token) using your client ID, username, and password, see obtain an access token and a refresh token.
To obtain a new access token using your refresh token and client ID, see refresh an access token.
Example Authentication Header:
Authorization: Bearer eyJhbGciOiJ ... BTfs9sivw4QYk5xCJoaex7p8kf6KUg
Refresh an access token
Refresh an access token
REQUEST (refresh an access token)
curl --request POST --data
'grant_type=refresh_token&client_id=7469ebe0-4dff-4a1b-84fe-0d1b3baf9dcf&refresh_token=2c0a3418-2159-404a-8b04-88b5cf0a2b62'
"https://acmeco.xmatters.com/api/xm/1/oauth2/token"
/**
* Flow Designer currently uses HTTP Basic Authentication for xMatters endpoints.
*/
endpoint_URL = "/oauth2/token"
client_id = "7469ebe0-4dff-4a1b-84fe-0d1b3baf9dcf"
refresh_token = "2c0a3418-2159-404a-8b04-88b5cf0a2b62"
grant_type = "refresh_token"
url = (
base_URL
+ endpoint_URL
+ "?grant_type="
+ grant_type
+ "&client_id="
+ client_id
+ "&refresh_token="
+ refresh_token
)
headers = {"Content-Type": "application/json"}
response = requests.post(url, headers=headers)
if response.status_code == 200:
rjson = response.json()
print(
"Access token: "
+ rjson.get("access_token")
+ ", \nRefresh token: "
+ rjson.get("refresh_token")
)
else:
print("Could not get access token")
RESPONSE
{
"access_token": "eyJhbGciOiJSUzI1NiJ9.eyJwIjoiLy8vL3ovLy8vLy8vLy8vLy8vLy8vLy8vLy8vLytmLy8vLy8vLy9QLy8vLy8vLy8vQi83Ly8vLy8vLy8vLy8vLy8vLy8vLy8vLy8vL0R3PT0iLCJhdWQiOlsiaWJhdXRvMS5iZXNwaW4uc2hhcmVkLWRldi54bWF0dGVycy5jb20iXSwic3ViIjoiYWRtaW4iLCJhenAiOiI3NDY5ZWJlMC00ZGZmLTRhMWItODRmZS0wZDFiM2JhZjlkY2YiLCJpc3MiOiJ4bWF0dGVycyIsInNiaSI6NTE0NTE1LCJleHAiOjE0NzYyMTYzMzgsImlhdCI6MTQ3NjIxNTQzOCwiYWlkIjoyMDAwMjIsImp0aSI6IjUyYzc5NDExLTNkMWUtNDUyZS1iOGM5LTJmNTAzYTc3NzFmOCJ9.TZPluCuR8RAXvtxPjO8E4FyFttLJNKD5KgkchZAKbYv5SpfpovBekJXTPnLIEVQ8NE88-rS0g6NnwRte8aDGN_hb5Y9-cNF1V5K-g9fuAXoYT1CIPMEDf-LFRGHeSkoo6yYkzQEloclOi6GFprLtm1XvKoPSK5hB8QT5uU6TJVc2UMjM7QTO7j3Tya8h0KByU_CE0wZxic45qrtRpyE__PIE_JqQJ8bwOuFUE3LC0Wfzcf0zIHrBIkv_jV2Wi_ktBwJwEmoRCMeDXvPozW2iFUC_5KhYWjO9eCVEU8u2tWqdwfQ7muPZnsIFTiH1rAvL_8sxaM3ZSke1AulwzadSYg",
"token_type": "bearer",
"refresh_token": "2b0a3418-2159-4042-8b04-38b5cf0a2b62",
"expires_in": 899,
"jti": "52c79411-3d1e-452e-b8c9-2f503a7771f8"
}
When an access token expires, you can obtain a new one by providing the client ID and a refresh token.
This method enables you to refresh an access token without storing the user name and password of an xMatters account. Access tokens can be revoked at any time.
The initial access token and refresh token are obtained by making a call to POST /oauth2/token and authenticating with a client ID, user name, and password.
DEFINITION
POST /oauth2/token
QUERY PARAMETERS
| grant_type | string |
The grant type. To refresh the OAuth token, set the grant type to refresh_token. |
|
| client_id | string |
| Your client ID. You can locate your client ID in the Web user interface by opening the Workflows menu and selecting OAuth. Example: 1432ebe0-4dff-4c3b-84fe-0d1aa31f51ee |
|
| refresh_token | string |
The refresh token obtained from a call to POST /oauth2/token.Example: 4a90179e-12e8-4965-bc0c-66c0f6b70458 |
RESPONSES
| Success | Response code 200 OK and an AccessToken object |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response codes. |
OAuth objects
AccessToken object
AccessToken object
{
"access_token": "eyJhbGciOiJSUzI1NiJ9.eyJwIjoiLy8vL3ovLy8vLy8vLy8vLy8vLy8vLy8vLy8vLytmLy8vLy8vLy9QLy8vLy8vLy8vQi83Ly8vLy8vLy8vLy8vLy8vLy8vLy8vLy8vL0R3PT0iLCJhdWQiOlsiaWJhdXRvMS5iZXNwaW4uc2hhcmVkLWRldi54bWF0dGVycy5jb20iXSwic3ViIjoiYWRtaW4iLCJhenAiOiI3NDY5ZWJlMC00ZGZmLTRhMWItODRmZS0wZDFiM2JhZjlkY2YiLCJpc3MiOiJ4bWF0dGVycyIsInNiaSI6NTE0NTE1LCJleHAiOjE0NzYyMTMwODMsImlhdCI6MTQ3NjIxMjE4MywiYWlkIjoyMDAwMjIsImp0aSI6ImRlYTMxOTk1LWY3OTAtNDNhMS1hZTNkLWUyM2RmNTg5MWM2NCJ9.4wCifLosOQJEsvkjogRQMlrnI5a6OAwjTwquU8tELNmeN6mxrgO6ZdQFZqtLXfOsYpNdQ_mJ_V-ZZVy99fxcxYVfBgOCv_S4s3-5S39HolCwh-2zaa9slJeg30fCv6_1huEGknnyp4u02JN6TMj8sNq0dtES0OowANhNlx3mp9VJUZTI08qZ1yXRUNQyt9B7tOeANuoHJjrdKobVdDKCihT1YrFZNloL-qJw8ry5tEC478BGn4RSlt1xLiQm1r_GS512zNNlzCjECXS2cBQah4vjhZSp6pHbjp46ALHm-_5LtUTOZDB5_-XH-lHQECanAOg7VjJz3w1gNNS16XHAuw",
"token_type": "bearer",
"refresh_token": "2b0a3418-2159-4042-8b04-38b5cf0a2b62",
"expires_in": 899,
"jti": "dea31995-f790-43a1-ae3d-e23df5891c64"
}
The AccessToken object contains an access token that can be used to authenticate with the xMatters REST API and a refresh token that can be used to obtain a new access token.
| access_token | string |
| A token that can temporarily be used to authenticate requests. | |
| expires_in | integer |
| The number of seconds that the access token is valid. | |
| refresh_token | string |
| The token that can be used, along with the client ID, to obtain a new access token. | |
| token | string |
| This API returns tokens of type "bearer". |
ON-CALL
Returns information about who is on call over a given timeframe.
Get who is on call
GET who is on call
REQUEST
curl --user username
"https://acmeco.xmatters.com/api/xm/1/on-call?groups=IT"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/on-call?groups=IT",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
for (var d in json.data ) {
var dd = json.data[d];
console.log("\nShift " + dd.shift.id + " members:");
var memberData = dd.members.data;
for (var i in memberData)
{
console.log(memberData[i].member.targetName);
}
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
groupId = "954ada78-7b89-4356-b02c-df85ff30dfd2"
limit = "2"
membersPerShift = "5"
endpoint_URL = (
"/on-call?groups="
+ groupId
+ "&offset=0&limit="
+ limit
+ "&membersPerShift="
+ membersPerShift
+ "&embed=shift,members.owner"
)
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 shift with name: "
+ d["shift"]["name"]
+ " and id: "
+ d["shift"]["id"]
)
# print('members.data is: ' + json.dumps( d['members']['data'], indent=4, sort_keys=True ) )
for md in d["members"]["data"]:
print(
"\tFound member with targetName: "
+ md["member"]["targetName"]
+ ", id: "
+ md["member"]["id"]
+ ", and recipientType: "
+ md["member"]["recipientType"]
)
# print('The data object 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": 1,
"total": 1,
"data":
[
{
"group":
{
"id": "954ada78-7b89-4356-b02c-df85ff30dfd2",
"targetName": "IT",
"links":
{
"self": "/api/xm/1/groups/954ada78-7b89-4356-b02c-df85ff30dfd2"
}
},
"shift":
{
"id": "62bdfe6b-6825-4c53-82e4-d147269666ff",
"links":
{
"self": "/api/xm/1/groups/954ada78-7b89-4356-b02c-df85ff30dfd2/shifts/62bdfe6b-6825-4c53-82e4-d147269666ff"
}
},
"members":
{
"count": 1,
"total": 1,
"data":
[
{
"position": 1,
"delay": 0,
"escalationType": "NONE",
"replacements":
{
"count": 2,
"total": 2,
"data":
[
{
"start": "2017-04-17T04:00:00Z",
"end": "2017-04-17T07:00:00Z",
"replacement":
{
"id": "e87403fb-f8ca-40e7-a105-0330e2d125ba",
"targetName": "balves",
"recipientType": "PERSON",
"links":
{
"self": "/api/xm/1/people/e87403fb-f8ca-40e7-a105-0330e2d125ba"
},
"firstName": "Benito",
"lastName": "Alves",
"status": "ACTIVE"
}
},
{
"start": "2017-04-17T07:00:00Z",
"end": "2017-04-18T04:00:00Z",
"replacement":
{
"id": "9f426e39-4292-4418-8c33-8678d787ffe2",
"targetName": "kkapoor",
"recipientType": "PERSON",
"links":
{
"self": "/api/xm/1/people/9f426e39-4292-4418-8c33-8678d787ffe2"
},
"firstName": "Kareem",
"lastName": "Kapoor",
"status": "ACTIVE"
}
}
]
},
"member":
{
"id": "e87403fb-f8ca-40e7-a105-0330e2d125ba",
"targetName": "balves",
"recipientType": "PERSON",
"externallyOwned": false,
"links":
{
"self": "/api/xm/1/people/e87403fb-f8ca-40e7-a105-0330e2d125ba"
},
"firstName": "Benito",
"lastName": "Alves",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "balves",
"site":
{
"id": "8fc2259d-ba18-42e3-be5c-3c39744e4bc4",
"links":
{
"self": "/api/xm/1/sites/8fc2259d-ba18-42e3-be5c-3c39744e4bc4"
}
},
"status": "ACTIVE"
}
}
],
"links":
{
"self": "/api/xm/1/groups/954ada78-7b89-4356-b02c-df85ff30dfd2/shifts/62bdfe6b-6825-4c53-82e4-d147269666ff/occurrences/2017-04-17T04:00:00Z/members?offset=0&limit=3"
}
},
"end": "2017-04-18T04:00:00Z",
"start": "2017-04-17T04:00:00Z"
}
],
"links":
{
"self": "/api/xm/1/on-call?groups=IT&at=2017-04-17T21%3A25%3A00Z&offset=0&limit=100"
}
}
This endpoint replaces GET /groups/{groupId}/calendar.
You can identify groups by their name (targetName) or unique identifier (id).
Use the ?embed query parameters to enhance the result to include more information about the shift or the owner
of device members.
Tip: To view a group's on-call schedule in universal time, view the group in the xMatters user interface and set the display timezone to (UTC+0000)GMT.
If users' 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.
Historical data and the at parameter
You can access historical data using to and from without using the at parameter.
By setting the to and from parameters to dates in the past, you automatically query historical data to return results. However, you cannot have a timeframe that spans from the past to the future and there is a 24-hour synchronization window for on-call data before it is available. This is to ensure that if you request on-call data for the current day, the request doesn't try to simultaneously draw data from both historical data and the runtime data.
For example: If today was January 3, 2019, you can't request on call information from Dec 31, 2018 to January 10, 2019. Additionally, because most requests for on-call data are based on a 24-hour period (00:00 - 23:59 on a single day), requesting a historical search which includes a current day's shifts also spans from past to future and cannot be performed.
When accessing who is on call now, or for a shift in the future, you'll need to set the from parameter to a time no more than 24 hours in the past, and the to parameter for a time that is in the future.
If no timeframe is specified, the query returns only the shifts that are currently on call. Shift times are defined in universal time (UTC) format and may not reflect the time zone of the authenticating user.
DEFINITION
GET /on-call?groups=group1,group2
GET /on-call?groups=18d30051-81d1-42bf-9dd8-9093ba7d9fac
GET /on-call?groups=IT&from=2017-04-14T04:00:00Z&to=2017-04-16T04:00:00Z
GET /on-call?groups=IT&embed=shift,members.owner
GET /on-call?groups=IT&membersPerShift=100
QUERY PARAMETERS
| groups | string |
| A comma-separated list of group names or unique identifiers to retrieve the on-call schedule for. You can specify up to 30 groups. For groups that have commas in the name, URL-encode the comma (replace it with %2C) or use the group's unique identifier to identify the group. | |
| membersPerShift | number |
| The maximum number of shift members to include in the members object (max value 100). If this parameter is omitted, the response includes a maximum of 3 shift members. | |
| at | string |
A date time value in UTC format. When provided, the response shows the on-call schedule for the given time. This query parameter cannot be used with the from and to query parameters, and should not be used for historical data searches. |
|
| from | string |
A date time value in UTC format that defines the start of the time range. When used with the to parameter, the response includes all shift instances in the specified time range. For historical data queries, the length of time you can set is limited by your pricing plan.Example:2017-02-23T04:00:00Z |
|
| to | string |
A date time value in UTC format that defines the end of the time range. When used with the from parameter, the response includes all shift instances in the specified time range. For historical data queries, this value cannot be within 15 minutes of the current time. For future queries, this value cannot be more than 90 days in the future.Example:2017-02-26T04:00:00Z |
|
| embed | string |
A list of extra information to embed in the response. These values must be separated by the , (comma) character. The following options are available:
/groups/{groupID}?embed=shift,members.owner |
RESPONSES
| Success | Response code 200 OK and a Pagination of On-call objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
On-call objects
On-call object
On-call Object
{
"group":{ ... },
"shift":{ ... },
"members":
{
"count": 1,
"total": 1,
"data":
[
{ ... }
],
"links":
{
"self": "/api/xm/1/groups/954ada78-7b89-4356-b02c-df85ff30dfd2/shifts/62bdfe6b-6825-4c53-82e4-d147269666ff/occurrences/2017-04-17T04:00:00Z/members?offset=0&limit=3"
}
},
"end": "2017-04-18T04:00:00Z",
"start": "2017-04-17T04:00:00Z"
}
Describes the on-call schedule of a group.
| group | GroupReference object |
| A reference to the group. | |
| shift | ShiftReference object |
| A reference to the shift. | |
| start | string |
| The start of the timeframe in UTC format. | |
| end | string |
| The end of the timeframe in UTC format. | |
| members | A Pagination of ShiftOccurrenceMember object |
| A list of the members included in the shift. |
ShiftReference object
ShiftReference object
"shift":
{
"id": "31f69e50-fd0c-45d7-a212-63b300c68340",
"name": "Weekend On-call",
"links":
{
"self": "/api/xm/1/groups/292a2cd7-53d7-4523-b752-d10209532ed4/shifts/31f69e50-fd0c-45d7-a212-63b300c68340"
}
}
| id | string |
| A unique identifier that represents the shift. | |
| links | SelfLink object |
| A link that can be used to access this shift. | |
| name | string |
| The target name of the shift. |
ShiftOccurrenceMember object
ShiftOccurrenceMember object
"position": 1,
"delay": 0,
"member":
{
"id": "ceb08e86-2674-4812-9145-d157b0e24c17",
"targetName": "ddirk",
"recipientType": "PERSON",
"externallyOwned": false,
"links":
{
"self": "/api/xm/1/people/ceb08e86-2674-4812-9145-d157b0e24c17"
},
"firstName": "Don",
"lastName": "Dirk",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "ddirk",
"phoneLogin": "3244",
"site":
{
"id": "8f2d98ed-eaa9-4b0b-b366-c1db06b27e1f",
"links":
{
"self": "/api/xm/1/sites/8f2d98ed-eaa9-4b0b-b366-c1db06b27e1f"
}
},
"status": "ACTIVE"
}
| member | Recipient |
| The shift member. Shift members can be one of the following objects: | |
| position | integer |
| The position of the member in the escalation timeline, where 1 represents the first person in the timeline. | |
| delay | integer |
| The number of minutes to wait after notifying this shift member before notifying the next shift member. | |
| escalationType | string |
The type of escalation. Valid values include:
|
|
| replacements | Pagination of TemporaryReplacement |
| Lists any temporary replacements for this shift. |
Temporary Replacement object
Temporary Replacement object
"start": "2017-04-17T04:00:00Z",
"end": "2017-04-17T07:00:00Z",
"replacement":
{
"id": "e87403fb-f8ca-40e7-a105-0330e2d125ba",
"targetName": "balves",
"recipientType": "PERSON",
"links":
{
"self": "/api/xm/1/people/e87403fb-f8ca-40e7-a105-0330e2d125ba"
},
"firstName": "Benito",
"lastName": "Alves",
"status": "ACTIVE"
}
Represents a temporary replacement.
| start | string |
| The time the replacement starts. | |
| end | string |
| The time the replacement ends. | |
| replacement | Replacer object |
| A description of the person who is covering the shift over the specified timeframe. |
Replacer object
Replacer object
{
"id": "e87403fb-f8ca-40e7-a105-0330e2d125ba",
"targetName": "balves",
"recipientType": "PERSON",
"links":
{
"self": "/api/xm/1/people/e87403fb-f8ca-40e7-a105-0330e2d125ba"
},
"firstName": "Benito",
"lastName": "Alves",
"status": "ACTIVE"
}
Defines the person who is acting as a temporary replacement.
| id | string |
| The unique identifier of the replacer | |
| targetName | string |
| The user ID of the replacer. | |
| recipientType | string |
| The type of the replacer. Temporary replacements are of type PERSON. | |
| links | SelfLink |
| A link that can be used to get more information about the replacer. | |
| firstName | string |
| The first name of the replacer. | |
| lastName | string |
| The last name of the replacer. | |
| status | string |
Whether the replacer is active in the system or if their account has been deactivated. Valid values include:
|
ON-CALL SUMMARY
This endpoint provides a summary of who is on call for a specific group. The on-call summary differs from the on-call endpoint by providing a recipient-centric list of shifts that includes shift rotations, temporary absences, and recipient escalation order.
The summary excludes inactive users or group members who are on temporary absence with no replacement. The summary also excludes broadcast groups with more than 200 members, because large groups can't contain escalations or rotations.
Get on-call summary
GET on-call summary
REQUEST (get the on-call summary for a group)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/on-call-summary?groups=2b6cf1a8-2186-41bb-951e-f79e9e776c95"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/on-call-summary?groups=2b6cf1a8-2186-41bb-951e-f79e9e776c95",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
var body = JSON.parse(response.body);
// Response body is an array of on-call recipients
if (body.length === 0) {
console.log('No on-call members found');
} else {
var first = body[0];
// e.g. "First on-call is Mary McBride (mmcbride)"
console.log('First on-call is ' + first.recipient.displayName + ' (' + first.recipient.targetName + ')');
}
}
import requests
base_url = "https://acmeco.xmatters.com/api/xm/1"
endpoint_url = "/on-call-summary?groups=2b6cf1a8-2186-41bb-951e-f79e9e776c95"
url = base_url + endpoint_url
response = requests.get(url, auth=("username", "password"))
if response.status_code == 200:
print("On-call summary successfully retrieved.")
RESPONSE
[
{
"group": {
"name": "MIM-TEAM-1",
"id": "2b6cf1a8-2186-41bb-951e-f79e9e776c95"
},
"shift": {
"name": "MainShift",
"id": "be25c9aa-09aa-43eb-8bc3-9ebd52380382"
},
"recipient": {
"displayName": "Mary McBride",
"id": "d1b9cc11-9119-4774-ab34-34ef044ed51f",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON"
},
"delay": 0,
"escalationLevel": 1
},
{
"group": {
"name": "MIM-TEAM-1",
"id": "2b6cf1a8-2186-41bb-951e-f79e9e776c95"
},
"shift": {
"name": "MainShift",
"id": "be25c9aa-09aa-43eb-8bc3-9ebd52380382"
},
"recipient": {
"displayName": "James Smith",
"id": "d0309fc9-89c2-4a61-8ad6-27be805b9d64",
"targetName": "jsmith443",
"firstName": "James",
"lastName": "Smith",
"recipientType": "PERSON"
},
"delay": 3,
"escalationLevel": 2,
"absence": {
"member": {
"displayName": "Samantha Ellis",
"id": "d1b9cc11-9119-4774-ab34-34ef044ed51f",
"targetName": "sellis"
}
}
},
{
"group": {
"name": "MIM-TEAM-1",
"id": "2b6cf1a8-2186-41bb-951e-f79e9e776c95"
},
"shift": {
"name": "MainShift",
"id": "be25c9aa-09aa-43eb-8bc3-9ebd52380382"
},
"recipient": {
"displayName": "Adam Jones",
"id": "e4a542f2-b4e0-4ec4-b02a-ba1bb2cf06a0",
"targetName": "ajones",
"firstName": "Adam",
"lastName": "Jones",
"recipientType": "PERSON"
},
"delay": 4,
"escalationLevel": 3
}
]
Returns the active members of a group in their order of escalation for each shift. The maximum number of returned results per request is 1000.
DEFINITION
GET /on-call-summary?groups=2b6cf1a8-2186-41bb-951e-f79e9e776c95
GET /on-call-summary?groups=2b6cf1a8-2186-41bb-951e-f79e9e776c95,Oracle%20Administrators&escalationOrder=PRIMARY
GET /on-call-summary?groups=Oracle%20Administrators&at=2020-05-08T16:00:00Z
URL PARAMETERS
| groups | string |
| A comma-separated list of group names or unique identifiers to retrieve the on-call summary for. You can specify up to 30 groups. For groups that have commas in the name, URL-encode the comma (replace it with %2C) or use the group's unique identifier to identify the group. | |
| escalationOrder | string |
| Narrows down results to display all users at the requested escalation level. If left blank, the return provides all escalation levels. Available options are: PRIMARY, and PRIMARY_SECONDARY. PRIMARY, and PRIMARY_SECONDARY status is based on time delays in the escalation order for a group, not the user's position in the list of users in the group. Multiple users may have primary or secondary escalation positions in a group. | |
| recipientsPerShift | integer |
| Limits the number of recipients returned per shift. The default value is 3, and the maximum value is 100. | |
| at | string |
| A date time value in UTC format up to 30 days in the future. When provided, the response provides the on-call summary for the given time. This query parameter should not be used for historical data searches. |
RESPONSES
| Success | Response code 200 OK and an On Call Summary object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
On-call summary objects
OnCallSummary object
On call summary object
[
{
"group": {
"name": "MIM-TEAM-1",
"id": "2b6cf1a8-2186-41bb-951e-f79e9e776c95"
},
"shift": {
"name": "MainShift",
"id": "be25c9aa-09aa-43eb-8bc3-9ebd52380382"
},
"recipient": {
"displayName": "Mary McBride Work Email",
"id": "b3a542f2-b2a0-6ec4-b54a-ba1bb2df06e0",
"targetName": "MaryMcBride|WorkEmail",
"recipientType": "DEVICE",
"owner": {
"displayName": "Mary McBride",
"id": "d1b9cc11-9119-4774-ab34-34ef044ed51f",
"targetName": "mmcbride",
"firstName": "Mary",
"lasttName": "McBride",
"recipientType": "PERSON"
}
},
"delay": 2,
"escalationLevel": 1
}
{
"group": {
"name": "MIM-TEAM-1",
"id": "2b6cf1a8-2186-41bb-951e-f79e9e776c95"
},
"shift": {
"name": "MainShift",
"id": "be25c9aa-09aa-43eb-8bc3-9ebd52380382"
},
"recipient": {
"displayName": "Adam Jones",
"id": "e4a542f2-b4e0-4ec4-b02a-ba1bb2cf06a0",
"targetName": "ajones",
"firstName": "Adam",
"lastName": "Jones",
"recipientType": "PERSON",
"absence": {
"member": {
"displayName": "Samantha Ellis",
"id": "d1b9cc11-9119-4774-ab34-34ef044ed51f",
"targetName": "sellis"
}
}
},
"delay": 4,
"escalationLevel": 3
}
]
Describes the on-call summary for a group.
| group | GroupReference object |
| A reference to the group. | |
| shift | ShiftReference object |
| A reference to the shift. | |
| recipient | PersonReference object, GroupReference object, Dynamic Group object, or Devices object |
Refers to a person, group, or device in xMatters. The displayName field provides the device name, group name, or first and last name of a person. If the recipient is a device, information on the device's owner information is also returned. |
|
| absence | PersonReference object |
| The user who is on temporary absence. | |
| delay | integer |
| The amount of time in minutes to wait before escalating to this member. | |
| escalationLevel | integer |
| The position of the user in the escalation order of a shift. Users with the same escalation level are notified at the same time. |
PEOPLE
The /people endpoints allow you to work with users in xMatters.
There are two user license types in xMatters: fullUsers and stakeholderUsers. Based on your pricing plan, your account has a specific number of Full Users licenses, and could be entitled to a number of Stakeholder User licenses. Stakeholder Users are users who don't need to take action during the response process. Users with a Stakeholder license type can be assigned the same roles and permissions as full users and they can access information in the web user interface and mobile app, but they cannot respond to any notifications they receive, act as an incident resolver, trigger forms that send messages, or initiate incidents or flows. For more informationon the two license types, see Manage stakeholder users in the online help.
Get a person (by id)
Get a person by id
REQUEST (get a person by their user name and include their roles)
curl --user username "https://acmeco.xmatters.com/api/xm/1/people/mmcbride?embed=roles"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people/mmcbride?embed=roles",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved person " + 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 = "/people/" + "mmcbride" + "?embed=roles"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print(
"Retrieved person "
+ rjson.get("targetName")
+ " with ID "
+ rjson.get("id")
+ ". The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
REQUEST (get a person by their identifier and include their roles)
curl --user username "https://acmeco.xmatters.com/api/xm/1/people/b2341d69-8b83-4660-b8c8-f2e728f675f9?embed=roles"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people/b2341d69-8b83-4660-b8c8-f2e728f675f9?embed=roles",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved person " + 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 = "/people/" + "b2341d69-8b83-4660-b8c8-f2e728f675f9" + "?embed=roles"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print(
"Retrieved person "
+ rjson.get("targetName")
+ " with ID "
+ rjson.get("id")
+ ". The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"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/Pacific",
"webLogin": "mmcbride",
"phoneLogin": "23423",
"site":
{
"id": "f0c572a8-45ec-fe23-289c-df749cf19a5e",
"name": "Default Site",
"links":
{
"self": "/api/xm/1/sites/f0c572a8-45ec-fe23-289c-df749cf19a5e"
}
},
"properties":
{
"Building" : "Engineering Wing",
"hasFirstAid" : true,
"Level" : 7.4,
"RoomNumber" : 422,
"Post-secondary Degrees" : ["BA", "MA", "PhD"],
},
"lastLogin": "2019-06-14T22:17:31.450Z",
"roles": {
"count": 2,
"total": 2,
"data": [
{
"id": "c2bdcd9e-1a18-0ff6-ffde-76e4022c94e6",
"name": "Standard User"
},
{
"id": "593433b0-e3b7-2e4c-f0cf-9faf2110b069",
"name": "Group Monitor"
}
]
},
"revision": {
"id": "4e4dd8b7-7179-4dbd-a54e-2ae6a90b035e",
"at": "2019-05-01T20:25:52.259Z",
"seq": "12121789793112"
},
"status": "ACTIVE"
}
You can identify a person using either their user name (targetName) or their unique identifier (id).
To include a list of the person's roles in the response, use the ?embed=roles query parameter with the request.
To include a list of one page of a person's supervisors in the response, use the ?embed=supervisors query parameter with the request. To retrieve a complete list of a person's supervisors when there is more than one page of results, use GET a person's supervisors.
Returns a Person object that represents a user in xMatters.
DEFINITION
GET /people/{personID}
GET /people/{personID}?embed=roles,supervisors
URL PARAMETERS
| {personID} | string |
The unique identifier (id) or name (targetName) of the person. Example: mmcbride Example: b2341d69-8b83-4660-b8c8-f2e728f675f9 |
QUERY PARAMETERS
| embed | string |
|
RESPONSES
| Success | Response code 200 OK and a Person object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a person (by query)
Get a person using an explicit search query
REQUEST (find user John Smith whose phone number is 1-250-123-4567)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/people?firstName=john&lastName=smith&phoneNumber=+12501234567"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people?firstName=john&lastName=smith&phoneNumber=+12501234567",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " people" );
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/people?firstName=john&lastName=smith&phoneNumber=+12501234567"
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(
"Retrieved "
+ str(rjson["count"])
+ " of "
+ str(rjson["total"])
+ " person records."
)
for rd in rjson["data"]:
print(
"Retrieved person with targetName: "
+ rd["targetName"]
+ " and id: "
+ rd["id"]
+ "."
)
print("The object 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": "b2341d69-8b83-4660-b8c8-f2e728f675f9",
"targetName": "jsmith",
"recipientType": "PERSON",
"externallyOwned": false,
"links":
{
"self": "/api/xm/1/people/b2341d69-8b83-4660-b8c8-f2e728f675f9"
},
"firstName": "John",
"lastName": "Smith",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "jsmith",
"phoneNumber": "12501234567",
"site":
{
"id": "f0c572a8-45ec-fe23-289c-df749cf19a5e",
"links":
{
"self": "/api/xm/1/sites/f0c572a8-45ec-fe23-289c-df749cf19a5e"
}
},
"properties":
{
"Building" : "Engineering Wing",
"hasFirstAid" : true,
"Level" : 6.5,
"RoomNumber" : 532,
"Post-secondary Degrees" : ["BA", "MA"],
},
"roles": {
"count": 2,
"total": 2,
"data": [
{
"id": "c2bdcd9e-1a18-0ff6-ffde-76e4022c94e6",
"name": "Standard User"
},
{
"id": "593433b0-e3b7-2e4c-f0cf-9faf2110b069",
"name": "Group Monitor"
}
]
},
"lastLogin": "2019-06-14T22:17:31.450Z",
"status": "ACTIVE"
}
You can search for a specific user by using the following explicit query parameters:
firstNamelastNametargetNamewebLoginphoneNumberemailAddress
Each of these queries performs an exact match search. Combining these parameters cumulatively narrows down your search results, and they can be used with propertyName/propertyValue to perform more explicit searches.
Returns a Person object that represents a specific user in xMatters.
DEFINITION
GET /people?firstName={first name}
GET /people?lastName={last name}
GET /people?targetName={target name}
GET /people?webLogin={web login name}
GET /people?phoneNumber={phone number}
GET /people?emailAddress={email address}
QUERY PARAMETERS
| firstName | string |
The first name of the user. Can be combined with propertyName, propertyValue to further narrow your search results. |
|
| lastName | string |
The last name of the user. Can be combined with propertyName, propertyValue to further narrow your search results. |
|
| targetName | string |
The common name of the user, for example: mmcbride. Can be combined with propertyName, propertyValue to further narrow your search results. |
|
| webLogin | string |
The identifier a person can use to log in to the web user interface. If this field is not defined, the webLogin is set to the targetName. This field can be a maximum of 100 characters. Can be combined with propertyName, propertyValue to further narrow your search results. |
|
| phoneNumber | string |
The phone number of the user. Phone numbers must be in E.164 format, for example: 13065552241. Can be combined with propertyName, propertyValue to further narrow your search results. |
|
| emailAddress | string |
The valid email address of the user. Can be combined with propertyName, propertyValue to further narrow your search results. |
RESPONSES
| Success | Response code 200 OK and a Person object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get people
Get people
REQUEST get all people by querying current system data
curl --user username "https://acmeco.xmatters.com/api/xm/1/people"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people?",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " people" );
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/people"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
REQUEST (get one page of results)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/people?offset=300&limit=100"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people?offset=300&limit=100",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " people" );
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/people?offset=300&limit=100"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
REQUEST (get people with contact information "mmcbride@xmatters.com") If multiple search parameters are provided, the result will be a union of the results for parameter 1 plus the results for parameter 2, etc. For example, if a search for "bsmith@xmatters.com" returns 2 results and a search for "mmcbride@xmatters.com" returns 3 results, then a search for "bsmith@xmatters.com+mmcbride@xmatters.com" will return 5 results.
curl --user username
"https://acmeco.xmatters.com/api/xm/1/people/?search=mmcbride@xmatters.com"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people?search=mmcbride@xmatters.com",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " people" );
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/people?search=bsmith@xmatters.com%20mmcbride@xmatters.com"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
REQUEST (get people with information in a specific field) Search for all users whose first name or last name contains Jackson.
curl --user username
"https://acmeco.xmatters.com/api/xm/1/people/?search=jackson&fields=FIRST_NAME,LAST_NAME"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people?search=jackson&fields=FIRST_NAME,LAST_NAME",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " people" );
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/people?search=jackson&fields=FIRST_NAME,LAST_NAME"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
REQUEST (get people with a custom field or attribute of "First Aid" that has the value "CPR") A name/value pair that represents a Custom Field or a Custom Attribute. If no Custom Field or Custom Attribute with the specified property name is defined, xMatters returns an empty data set (not an error).
curl --user username
"https://acmeco.xmatters.com/api/xm/1/people/?propertyNames=First%20Aid&propertyValues=CPR"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people?propertyName=First%20Aid&propertyValue=CPR",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " people" );
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/people?propertyName=First Aid&propertyValue=CPR"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
REQUEST (get people in the Denver Sales Office site)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/people?site=Denver%20Sales%20Office"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people?site=Denver Sales Office",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " people" );
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/people?site=Denver%20Sales%20Office"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"count":100,
"total":229,
"data":[
{
"id":"7658a7d7-1340-47da-b121-22a3fc765c16",
"targetName":"mmcbride",
"recipientType":"PERSON",
"externallyOwned":false,
"links":{
"self":"/api/xm/1/people/7658a7d7-1340-47da-b121-22a3fc765c16"
},
"firstName":"Mary",
"lastName":"McBride",
"language":"en",
"timezone":"US/Eastern",
"webLogin":"admin",
"site":
{
"id":"005f11f8-3614-479e-acaf-c5762ecd23c2",
"links":
{
"self":"/api/xm/1/sites/005f11f8-3614-479e-acaf-c5762ecd23c2"}
},
"lastLogin": "2019-06-14T22:17:31.450Z",
"status":"ACTIVE"
},
{
...truncated list of Person objects...
}],
"links":
{
"self":"/api/xm/1/people?offset=0&limit=100",
"next":"/api/xm/1/people?offset=100&limit=100"
}
}
Returns a paginated list of the users that are visible to the authenticating user. Use the embed=roles query parameter to include a list of each user's assigned roles in the response.
You can request a list of all users or search for users that match specific search criteria.
Use the search query parameter to return users with matching names, user IDs, email address, or phone numbers. When two or more search terms are present, the result includes people that match either search term.
Use the propertyNames/propertyValues query parameters to return users that have matching custom fields and attributes. When two or more propertyNames/propertyValues pairs are specified, the result includes only people who match all the criteria.
DEFINITION
GET /people
GET /people?createdFrom={timestamp}
GET /people?createdTo={timestamp}
GET /people?createdBefore={timestamp}
GET /people?createdAfter={timestamp}
GET /people?devices.exists=false
GET /people?devices.email.exists=false
GET /people?devices.failsafe.exists=false
GET /people?devices.mobile.exists=false
GET /people?devices.sms.exists=false
GET /people?devices.voice.exists=false
GET /people?devices.status=ACTIVE
GET /people?devices.testStatus=TESTED
GET /people?embed=roles,devices
GET /people?groups=DevOps,25070811-5b97-4e39-887c-a81639598864
GET /people?groups.exists=true
GET /people?licenseType=STAKEHOLDER_USER
GET /people?propertyNames={name1},{name2}&propertyValues={value1},{value2}
GET /people?roles={name}
GET /people?search=don
GET /people?search=don jack&operand=AND
GET /people?search="don jack"&fields=FIRST_NAME&operand=AND
GET /people?site={siteId}
GET /people?sortBy=FIRST_LAST_NAME&sortOrder=ASCENDING
GET /people?status=ACTIVE
GET /people?supervisors={name},{id}
GET /people?supervisors.exists=true
QUERY PARAMETERS
| createdAfter | string |
Returns a list of people created after the provided timestamp (in ISO format). Can be used on its own or inconjunction with createdBefore and createdTo. |
|
| createdBefore | string |
Returns a list of people created before (and excluding) the provided timestamp (in ISO format). Can be used on its own or inconjunction with createdAfter and createdFrom. |
|
| createdFrom | string |
Returns a list of people created from the provided timestamp (in ISO format). Can be used on its own or inconjunction with createdTo and createdBefore. |
|
| createdTo | string |
Returns a list of people created up to (and including) the provided timestamp (in ISO format). Can be used on its own or inconjunction with createdFrom and createdAfter. |
|
| devices.exists | Boolean |
Returns a Pagination of users who have (or don't have) devices associated with their account.
|
|
| devices.email.exists | Boolean |
Returns a Pagination of users who have (or don't have) email devices associated with their account.
|
|
| devices.failsafe.exists | Boolean |
Returns a Pagination of users who have (or don't have) failsafe devices associated with their account.
|
|
| devices.mobile.exists | Boolean |
Returns a Pagination of users who have (or don't have) devices with the xMatters mobile app associated with their account.
|
|
| devices.sms.exists | Boolean |
Returns a Pagination of users who have (or don't have) SMS devices associated with their account.
|
|
| devices.voice.exists | Boolean |
Returns a Pagination of users who have (or don't have) voice devices associated with their account.
|
|
| devices.status | string |
Returns a Pagination of devices for each user and includes whether each device is active or inactive. Valid values include: ACTIVE and INACTIVE. |
|
| devices.testStatus | string |
Returns a Pagination of devices for each user and includes whether each device was successfully tested or not. Valid values include:
|
|
| embed | string |
Use ?embed=roles to include a list of each person's roles in the result. Use ?embed=devices to include a list of each person's devices. 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. |
|
| fields | string |
Use with the search parameter to limit the fields searched. Values can be combined in a comma-separated list. Available values are:
For example: GET /people/?search=don jackson&fields=FIRST_NAME,LAST_NAME returns any user whose first name or last name contains the search terms "don" or "jackson". |
|
| groups | string |
| A comma-separated list of group target names or UUIDs. Groups with commas in their names must character encode the comma. When multiple groups are specified, the results return users a who are members of either group. Only users that are direct members of a group are returned. For example, if a user's device is a member of a group, that user is not returned in the results. Nested groups, and the at parameter are not supported. |
|
| groups.exists | Boolean |
Returns a Pagination of users who are (or aren't) members of at least one group.
|
|
| licenseType | string |
Returns all users in your system that have the specified license type. Available options are: FULL_USER, STAKEHOLDER_USER |
|
| operand | string |
Applied to the provided search terms to limit or expand the search query parameter. Available options include: AND or OR. AND only returns people that have all search terms in the specified fields. OR returns people that have any of the search terms in the specified fields; this is the default if you don’t specify an operand. The operand is case-sensitive; entering lowercase "and" will return an error. |
|
| propertyNames, propertyValues | string, value |
A list of name/value pairs that represent custom fields and attributes. The search returns information that matches all search parameters. You can supply multiple name/value pairs in a comma-separated list, but the commas must be character encoded, and there must be an equal number of propertyNames and propertyValues. For example, if you supply three propertyNames, you must also supply three propertyValues. If the system has not defined a custom field or custom attribute with the specified property name, xMatters returns an empty data set (not an error). Combine with site to further narrow search results.Example: GET people?propertyNames=First%20Aid&propertyValues=CPR&site=Seattle HQ returns a list of users that have a custom field or custom attribute named "First Aid" with the value "CPR" and are located at the Seattle HQ site. |
|
| roles | string |
The name or unique identifier of a role (or roles) in xMatters. You can search for multiple roles using a comma delimiter. For example, searching GET /people?roles=developer,DBA,ITAdmin returns all users who matches any of the listed roles. When searching by role name, the spelling of the role must exactly match the name in xMatters, however the case does not have to match. For example, searching for roles=developer and roles=Developer return the same results. Based on your permission level, you will either receive a subset or a complete list of user information. |
|
| search | string |
A list of search terms separated by the + sign or a space character. Searches are case-insensitive ("alert" finds "alert", "Alert", as well as "alerting") and must contain at least two characters. When two or more search terms are present, the result includes users that match either search term. The result set includes users where any of the following fields match any of the search terms:
GET /people?search=mary could return the following users:
operand and fields query parameters to expand or limit search results. When the search, operand=AND, and fields parameters are combined in one query, the operand=AND applies only to the search terms; the fields parameter remains an OR search. Example: GET /people/?search=don jack&operand=AND&fields=FIRST_NAME,LAST_NAME returns all users who have "don" and "jack" in either the first or last name fields. So Jack Donaldson and Don Jackson would be returned, but Don Smith would not.When your search term contains more than one word, or contains delimiting characters such as spaces, enclose the terms in double quotes to preserve the delimiters. Example: /people?search=don jack&fields=FIRST_NAME returns all users who have either "don" or "jack" in the first name field. However, searching /people?search="don jack" returns all users that contain "don jack" in the first name field. |
|
| site | string |
Return a list of people belonging to a specific site. You can identify the site by its unique identifier (id) or its name. Combine with propertyName, propertyValue to further narrow your search results. If using the name, it is case-sensitive – seattle hq will not return results for Seattle HQ.Example: GET people?site=Denver%20Sales%20Office returns only people that belong to the Denver Sales Office site.Note: If you include the site query parameter, it takes precedence over any other query parameters. |
|
| 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:
|
|
| status | string |
| The status of a user in xMatters. Available options include: ACTIVE and INACTIVE. | |
| supervisors.exists | Boolean |
Returns a Pagination of users who have (or don't have) assigned supervisors.
|
|
| supervisors | string |
The name or unique identifier of the supervisor you want to return the users for. You can return users for multiple supervisors using a comma delimiter. For example, searching GET /people?supervisors=mmcbride,asamara returns all users who have either of those two as a supervisor. |
RESPONSES
| Success | Response code 200 OK and a Pagination of Person object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a person
Create a person
REQUEST (create a person)
curl --user username -H "Content-Type: application/json" -d
'{
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"licenseType": "FULL_USER",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "mmcbride",
"phoneLogin": "23423",
"phonePin": "46189",
"password": "test1234!",
"forcePasswordReset": true,
"roles": [
"Standard User"
],
"site": "671b58b4-9b8b-4b79-8801-8d9001dc180f",
"status": "ACTIVE",
"supervisors": [
"481086d8-357a-4279-b7d5-d7dce48fcd12"
],
"properties": {
"myTextCustomField": "myText",
"myCheckboxCustomField": true,
"myDecimalCustomField": 7.4,
"myIntegerCustomField": 422,
"myListCustomField": "ListItem5",
"myPasswordCustomField": "42*W$E)121",
"myCustomAttribute": [
"value1",
"value2",
"value3"
]
},
}'
"https://acmeco.xmatters.com/api/xm/1/people"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.targetName = 'mmcbride';
data.firstName = 'Mary';
data.lastName = 'McBride';
data.recipientType = 'PERSON';
data.licenseType = 'FULL_USER';
data.language = 'en';
data.timezone = 'US/Pacific';
data.webLogin = 'mmcbride';
data.phoneLogin = '23423';
data.phonePin = '46189';
data.password = 'test1234!';
data.forcePasswordReset = true;
data.status = 'ACTIVE';
data.roles = ['Standard User'];
data.site = '671b58b4-9b8b-4b79-8801-8d9001dc180f';
var supervisors = [];
supervisors.push('481086d8-357a-4279-b7d5-d7dce48fcd12');
data.supervisors = supervisors;
var properties = {};
properties.myTextCustomField = 'myText';
properties.myCheckboxCustomField = true;
properties.myDecimalCustomField = 7.4;
properties.myIntegerCustomField = 422;
properties.myListCustomField = 'ListItem5';
properties.myPasswordCustomField = '42*W$E)121';
properties.myCustomAttribute = ['value1', 'value2', 'value3'];
data.properties = properties;
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( 'Created user: ' + json.targetName + '. ID = '+ json.id);
}
else if (response.statusCode == 409){
console.log('The user already exists');
}
#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 = '/people'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
properties = {
"myTextCustomField" : "myText",
"myCheckboxCustomField" : true,
"myDecimalCustomField" : 7.4,
"myIntegerCustomField" : 422,
"myListCustomField" : "ListItem5",
"myPasswordCustomField" : "42*W$E)121",
"myCustomAttribute" : ["value1", "value2", "value3"]
}
data = {
"targetName" : "mmcbride",
"firstName" : "Mary",
"lastName": "McBride",
"recipientType" : "PERSON",
"licenseType" : "FULL_USER",
"status" : "ACTIVE",
"language" : "en",
"timezone": "US/Pacific",
"webLogin" : "mmcbride",
"phoneLogin" : "23423",
"phonePin": "46189",
"password": "test1234!"
"forcePasswordReset": true,
"roles": ["Standard User"],
"site": "671b58b4-9b8b-4b79-8801-8d9001dc180f",
"supervisors" : ["481086d8-357a-4279-b7d5-d7dce48fcd12"],
"properties": properties
}
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('Person ' + rjson.get('targetName') + ' was successfully created.' )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"id": "b2341d69-8b83-4660-b8c8-f2e728f675f9",
"targetName": "mmcbride",
"recipientType": "PERSON",
"licenseType" : "FULL_USER",
"externallyOwned": false,
"links":
{
"self": "/api/xm/1/people/b2341d69-8b83-4660-b8c8-f2e728f675f9"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "mmcbride",
"phoneLogin": "23423",
"site":
{
"id": "f0c572a8-45ec-fe23-289c-df749cf19a5e",
"links":
{
"self": "/api/xm/1/sites/f0c572a8-45ec-fe23-289c-df749cf19a5e"
}
},
"properties":
{
"myTextCustomField": "myText",
"myCheckboxCustomField": true,
"myDecimalCustomField": 7.4,
"myIntegerCustomField": 422,
"myListCustomField": "ListItem5",
"myPasswordCustomField": "42*W$E)121",
"myCustomAttribute": [
"value1",
"value2",
"value3"
]
},
"supervisors": {
"count": 1,
"total": 1,
"data": [
{
"id":"481086d8-357a-4279-b7d5-d7dce48fcd12",
"targetName":"agreenberg",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/481086d8-357a-4279-b7d5-d7dce48fcd12"
},
"firstName": "Abe",
"lastName": "Greenberg",
"status": "ACTIVE"
}
],
"links": {
"self": "/api/xm/1/people/b2341d69-8b83-4660-b8c8-f2e728f675f9/supervisors?offset=0&limit=100"
}
},
"status": "ACTIVE"
}
Creates a new user in xMatters.
When adding new users, you can only use properties that are already defined in the web user interface. Newly-created users do not have assigned web or phone passwords. You can set these passwords manually in the xMatters user interface, or you can add a device to their profile which will enable them to use the "Forgot Password" work flow to reset their own password.
You must assign at least one role to a new user and you may optionally assign one or more supervisors. The supervisors must have permission to supervise users and the authenticating account must have permission to assign supervisors. If you do not assign a supervisor then the authenticating account becomes the user's supervisor.
To assign the person to a site, you must provide the unique identifier of the site. Locating site identifiers in the xMatters user interface requires advanced permissions. For more information, see Locate the identifier for a site.
DEFINITION
POST /people
BODY PARAMETERS
| externalKey | string |
| See externalKey. | |
| externallyOwned | Boolean |
| See externallyOwned. | |
| firstName | string |
| The first name of the user. This value can be a maximum of 100 characters. | |
| id | string |
| If provided, xMatters attempts to use this value as person'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 person's unique identifier. Use this field when you want a person'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. | |
| language | string |
| The person's preferred language. The language must be enabled in xMatters before you can set it here. | |
| lastName | string |
| The last name of the person. This value can be a maximum of 100 characters. | |
| licenseType | string |
The license type of the user in xMatters. Available options are:
|
|
| phoneLogin | string |
An access code that the person can use to identify themselves when they phone in to xMatters to retrieve messages. The phone login may contain only digits and cannot exceed a length of 30 characters. You can optionally set a phonePin for the user. |
|
| phonePin | string |
The PIN a user enters with their phone login to identify themselves when they phone in to xMatters to retrieve messages. The PIN may contain only digits and cannot exceed a length of 30 characters. In order to set a phonePin, you must specify a phoneLogin for the user. Once submitted in the request, the phonePin is not returned or displayed in the response object. |
|
| password | string |
A password that meets the complexity guidelines of your organization. Once submitted in the request, the password is not returned or displayed in the response object. |
|
| forcePasswordReset | Boolean |
When set to true the user must reset their password when they next log in. Once submitted in the request, this parameter is not returned or displayed in the response object. |
|
| properties | Properties object |
| Values of custom fields and custom attributes for this person. | |
| recipientType | string |
| For people, this value is "PERSON". Providing this optional field allows xMatters to process your request more efficiently and improves performance. | |
| roles | array [string] |
An array of user roles. The roles correspond to the role names that are configured for your system. The following example shows how to assign the roles "Standard User", "Group Supervisor", and "Person Supervisor" to this person. "roles": ["Standard User", "Group Supervisor", "Person Supervisor"]To find the name of roles in your system, see GET roles. |
|
| site | string |
| The unique identifier of the site to assign the user to. If a site is not provided, the site of the authenticated user making the request is used. Example: "671b58b4-9b8b-4b79-8801-8d9001dc180f" |
|
| status | string |
Whether the person is active. Inactive people cannot receive notifications. Use one of the following values:
|
|
| supervisors | array [string] |
| A list of unique identifiers that represent the person's supervisors. The supervisors must have the role-based permissions required to supervise the user and the authenticating account must have permission to assign supervisors to the user.If the property is set to an empty array or null, the new user has no supervisors. If the property is omitted, the authenticated user making the request is set as the supervisor. Example: "supervisors": ["481086d8-357a-4279-b7d5-d7dce48fcd12","545686d8-3491-4a12-ddb7-a33239e82bc7"] |
|
| targetName | string |
| The user name of the person. This value becomes the person's user ID in xMatters, and can be a maxmimum of 100 characters. | |
| timezone | string |
| The person's time zone. Example: US/Pacific |
|
| webLogin | string |
The identifier a person can use to log in to the web user interface. If this field is not defined, the webLogin is set to the targetName. This field can be a maximum of 100 characters. |
RESPONSES
| Success | Response code 201 Created and a Person object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a person
Modify a person
REQUEST (set a user to be inactive)
curl -H "Content-Type: application/json" --user username -X POST -d
'{
"id": "b2341d69-8b83-4660-b8c8-f2e728f675f9",
"status": "INACTIVE"
}'
"https://acmeco.xmatters.com/api/xm/1/people"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = 'b2341d69-8b83-4660-b8c8-f2e728f675f9';
data.status = 'INACTIVE';
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Modified user: " + 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 = '/people'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
data = {
"id" : "b2341d69-8b83-4660-b8c8-f2e728f675f9",
"status" : "INACTIVE"
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if (responseCode == 200):
rjson = response.json();
print('Person ' + rjson.get('targetName') + ' was successfully modified. The updated person object is:\n' + json.dumps(rjson, indent=4, sort_keys=True) )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"id": "b2341d69-8b83-4660-b8c8-f2e728f675f9",
"targetName": "mmcbride",
"recipientType": "PERSON",
"licenseType": "FULL_USER",
"externallyOwned": false,
"links":
{
"self": "/api/xm/1/people/b2341d69-8b83-4660-b8c8-f2e728f675f9"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "mmcbride",
"phoneLogin": "23423",
"site":
{
"id": "f0c572a8-45ec-fe23-289c-df749cf19a5e",
"links":
{
"self": "/api/xm/1/sites/f0c572a8-45ec-fe23-289c-df749cf19a5e"
}
},
"status": "INACTIVE"
}
Modifies the properties of a user in xMatters.
Provide the identifier of the person you want to modify in the id field and then specify the properties that you want to modify.
If the id field is not included xMatters treats this as a request to create a new person. If an inaccruate id is submitted with the request, xMatters will do one of two things:
- If the
idprovided is not currently in the xMatters system, a new user is created. - If the
idcurrently exists in the system, xMatters will modify the existing id with the information provided in the request.
DEFINITION
POST /people
BODY PARAMETERS
| id | string |
The unique identifier (id) of the person you want to modify. |
Include body parameters that represent the properties you want to modify. For a list of these values, see Create a person.
RESPONSES
| Success | Response code 200 OK and a Person object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a person
Delete a person
REQUEST (delete a person)
curl --user username -X DELETE
"https://acmeco.xmatters.com/api/xm/1/people/mmcbride"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people/mmcbride"
"method": "DELETE",
});
response = request.write();
console.log (response.statusCode);
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the person: " + json.targetName);
}
else if (response.statusCode == 204){
console.log("The person " + personName + " could not be found.")
}
import requests
from requests.auth import HTTPBasicAuth
import json
userId = "b2341d69-8b83-4660-b8c8-f2e728f675f9"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/people/" + userId
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
print("Received response: " + str(responseCode))
if int(responseCode) == 200:
rjson = response.json()
print('Deleted user 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
{
"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/Pacific",
"webLogin": "mmcbride",
"phoneLogin": "23423",
"site":
{
"id": "f0c572a8-45ec-fe23-289c-df749cf19a5e",
"links":
{
"self": "/api/xm/1/sites/f0c572a8-45ec-fe23-289c-df749cf19a5e"
}
},
"status": "INACTIVE"
}
Deletes a person.
You can identify the person using either their user name (the targetName field) or their unique identifier (the id field).
DEFINITION
DELETE /people/{personID}
URL PARAMETERS
| {personID} | string |
The unique identifier (id) or name (targetName) of the person. Example:mmcbride Example:b2341d69-8b83-4660-b8c8-f2e728f675f9 |
RESPONSES
| Success: person deleted | Response code 200 OK and a Person object in the response body. |
| Success: person not found | Response code 204 No Content. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a person's devices
Get a person's devices
REQUEST (get a person's devices by querying, including when each device is configured to receive notificaitons)
curl --user username "https://acmeco.xmatters.com/api/xm/1/people/akaur/devices?embed=timeframes"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people/akaur/devices?embed=timeframes",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " devices." );
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/people/" + "akaur" + "/devices?embed=timeframes"
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(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " devices. 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":3,
"total":3,
"data":[
{
"id":"a4d69579-f436-4e85-9d93-703714d85d72",
"name":"Home Phone",
"recipientType":"DEVICE",
"phoneNumber":"+13235553643",
"targetName":"akaur",
"deviceType":"VOICE",
"description":"(323)5553643",
"active":"ACTIVE",
"testStatus":"UNTESTED",
"externallyOwned":false,
"defaultDevice":true,
"priorityThreshold":"LOW",
"sequence":0,
"delay":0,
"timeframes":
{
"count":1,
"total":1,
"data":[
{
"name":"Home Phone - Default 24 x 7",
"startTime":"08:00",
"timezone": "US/Pacific",
"durationInMinutes":1440,
"excludeHolidays":false,
"days":["SU","MO","TU","WE","TH","FR","SA"]
}]
},
"owner":
{
"id":"a608fa11-552a-4806-b247-48f083a20081",
"targetName" : "akaur",
"links":{"self":"/api/xm/1/people/a608fa11-552a-4806-b247-48f083a20081"}
},
"links":
{
"self":"/api/xm/1/devices/a4d69579-f436-4e85-9d93-703714d85d72"}
},
{
"id":"f5cdb445-3933-40c0-a308-a9a2c7ae50e1",
"name":"Work Email",
"recipientType":"DEVICE",
"emailAddress":"a.kaur@xmatters.com",
"targetName":"akaur",
"deviceType":"EMAIL",
"description":"a.kaur@xmatters.com",
"active":"ACTIVE",
"testStatus":"TESTED",
"externallyOwned":false,
"defaultDevice":true,
"priorityThreshold":"LOW",
"sequence":1,
"delay":0,
"timeframes":
{
"count":1,
"total":1,
"data":[
{
"name":"Work Email - Default 24 x 7",
"startTime":"08:00",
"timezone": "US/Pacific",
"durationInMinutes":1440,
"excludeHolidays":false,
"days":["SU","MO","TU","WE","TH","FR","SA"]
}]
},
"owner":
{
"id":"a608fa11-552a-4806-b247-48f083a20081",
"targetName" : "akaur",
"links":
{
"self":"/api/xm/1/people/a608fa11-552a-4806-b247-48f083a20081"
}
},
"links":
{
"self":"/api/xm/1/devices/f5cdb445-3933-40c0-a308-a9a2c7ae50e1"
}
},
{
"id":"744b0a36-a8b6-4d78-bb06-63cdc89dc475",
"name":"Work Phone",
"recipientType":"DEVICE",
"phoneNumber":"+13235558965",
"targetName":"akaur",
"deviceType":"VOICE",
"description":"(323)5558965",
"active":"ACTIVE",
"testStatus":"UNTESTED",
"externallyOwned":false,
"defaultDevice":true,
"priorityThreshold":"LOW",
"sequence":2,
"delay":0,
"timeframes":
{
"count":1,
"total":1,
"data":[
{
"name":"Work Phone - Default 24 x 7",
"startTime":"08:00",
"timezone": "US/Pacific",
"durationInMinutes":1440,
"excludeHolidays":false,
"days":["SU","MO","TU","WE","TH","FR","SA"]
}]
},
"owner":
{
"id":"a608fa11-552a-4806-b247-48f083a20081",
"targetName" : "akaur",
"links":{"self":"/api/xm/1/people/a608fa11-552a-4806-b247-48f083a20081"}
},
"links":
{
"self":"/api/xm/1/devices/744b0a36-a8b6-4d78-bb06-63cdc89dc475"
}
}],
"links":
{
"self":"/api/xm/1/people/akaur/devices?expand=timeframes&offset=0&limit=100"
}
}
Returns a list of devices that belong to the specified user. 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.
You can optionally include the ?embed=timeframes query parameter to include the timeframes each device is configured to receive notifications.
DEFINITION
GET /people/{personId}/devices
GET /people/{personId}/devices?embed=timeframes
GET /people/{personId}/devices?phoneNumberFormat=COUNTRY_CODE
URL PARAMETERS
| {personId} | string |
The unique identifier (id) or name (targetName) of the person. Example: akaur Example: a608fa11-552a-4806-b247-48f083a20081 |
QUERY PARAMETERS
| embed | string |
Use ?embed=timeframes include a list of Device timeframes objects that represent when the devices are configured to receive notifications.Example: GET /people/{personID}/devices?embed=timeframes |
|
| 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:
|
RESPONSES
| Success | Response code 200 OK and a Pagination of Device objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a person's groups
Get a person's groups
REQUEST
curl --user username "https://acmeco.xmatters.com/api/xm/1/people/mmcbride/group-memberships"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var username = 'mmcbride';
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people/" + username + "/group-memberships",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200)
{
json = JSON.parse(response.body);
console.log ('Retrieving group memberships for: ' + username);
for (var i in json.data)
{
console.log('User belongs to group "' + json.data[i].group.targetName + '" as a "' + json.data[i].member.recipientType + '" named "' + json.data[i].member.targetName + '"');
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
person_name = "mmcbride"
endpoint_URL = "/people/" + person_name + "/group-memberships"
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(
'User "'
+ person_name
+ '" belongs to group "'
+ d["group"]["targetName"]
+ '" as a "'
+ d["member"]["recipientType"]
+ '" named "'
+ d["member"]["targetName"]
+ '"'
)
RESPONSE
{
"count": 2,
"total": 2,
"data":
[
{
"group":
{
"id": "4eee0564-adcd-4d3a-84de-da3b7bd14898",
"targetName": "Database Administrators",
"recipientType": "GROUP",
"links":
{
"self": "/api/xm/1/groups/4eee0564-adcd-4d3a-84de-da3b7bd14898"
}
},
"member":
{
"id": "90c65d8b-f001-4baf-818e-080c85b89c9a",
"targetName": "mmcbride|Work Email",
"recipientType": "DEVICE",
"links":
{
"self": "/api/xm/1/devices/90c65d8b-f001-4baf-818e-080c85b89c9a"
}
}
},
{
"group":
{
"id": "857a341a-487a-47d6-a540-857f25854e2d",
"targetName": "Operations",
"recipientType": "GROUP",
"links":
{
"self": "/api/xm/1/groups/857a341a-487a-47d6-a540-857f25854e2d"
}
},
"member":
{
"id": "48244154-b9df-4397-b91f-ee5b67dc485f",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links":
{
"self": "/api/xm/1/people/48244154-b9df-4397-b91f-ee5b67dc485f"
}
}
],
"links":
{
"self": "/api/xm/1/people/209125/group-memberships?offset=0&limit=100"
}
}
Returns a list of groups that a person belongs to.
The returned list includes groups that the user or one of their devices belongs to directly. It does not return groups that the user belongs to indirectly by way of their membership in a dynamic team or subgroup.
The group field in the response provides a reference to the
group that the user belongs to and the member field describes
whether it is the user or one of their devices that is included in the group.
DEFINITION
GET /people/{personID}/group-memberships
URL PARAMETERS
| {personID} | string |
The unique identifier (id) or name (targetName) of the person. Example: mmcbride Example:b2341d69-8b83-4660-b8c8-f2e728f675f9 |
RESPONSES
| Success | Response code 200 OK and a Pagination of Group Membership object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a person's supervisors
Get a person's supervisors
REQUEST
curl --user username
"https://acmeco.xmatters.com/api/xm/1/people/jsmith/supervisors"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people/jsmith/supervisors",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " supervisors." );
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"
person_name = "mmcbride"
endpoint_URL = "/people/" + person_name + "/supervisors"
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(
'User "'
+ person_name
+ '" has supervisor "'
+ d["targetName"]
+ '" with first name "'
+ d["firstName"]
+ '" and last name "'
+ d["lastName"]
+ '"'
)
RESPONSE
{
"count": 1,
"total": 1,
"data": [
{
"id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Eastern",
"webLogin": "admin",
"site": {
"id": "8f2d98ed-eaa9-4b0b-b366-c1db06b27e1f",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/8f2d98ed-eaa9-4b0b-b366-c1db06b27e1f"
}
},
"lastLogin": "2019-08-15T19:27:14.100Z",
"status": "ACTIVE"
}
],
"links": {
"self": "/api/xm/1/people/e4f8d5c3-b0ab-49d9-88a8-e73e6255ec8f/supervisors?offset=0&limit=100"
}
}
Returns a list of a person's supervisors.
Use this endpoint to retrieve a paginated list of a person's supervisors. You can also embed one page of supervisors in a
call to Get a person (by id) by using the ?embed=supervisors query parameter.
DEFINITION
GET /people/{personId}/supervisors
URL PARAMETERS
| {personId} | string |
The unique identifier (id) or name (targetName) of the person. |
RESPONSES
| Success | Response code 200 OK and a Pagination of Person objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Get user license quotas
Get user license quotas
REQUEST - Get the number of users in your system by their license type.
curl --user username "https://acmeco.xmatters.com/api/xm/1/people/license-quotas"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/people/license-quotas",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " license quotas" );
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/people/license-quotas"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"stakeholderUsersEnabled": true,
"stakeholderUsers": {
"total": 10,
"active": 6,
"unused": 4
},
"fullUsers": {
"total": 300,
"active": 169,
"unused": 131
}
}
Returns the number of user licenses for your company, separated by license type. There are two user license types in xMatters: fullUsers and stakeholderUsers. Based on your pricing plan, your xMatters account could be entitled to a specific number of Stakeholder Users. Stakeholder Users are users who don't need to take action during the response process. Users with a Stakeholder license type can be assigned the same roles and permissions as full users and they can access information in the web user interface and mobile app, but they cannot respond to any notifications they receive, act as an incident resolver, trigger forms that send messages, or initiate incidents or flows. If your xMatters account is not entitled to Stakeholder users, an empty response is returned.
DEFINITION
GET /people/license-quotas
RESPONSES
| Success | Response code 200 OK and a UserQuota object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Person objects
Person object
Person Object
This example shows a person object including roles. Roles are included in the Person object when the query parameter ?embed=roles is used with the request.
{
"id":"9407eb2e-8eb2-43d9-88a8-875237af941d",
"targetName":"mmcbride",
"recipientType":"PERSON",
"licenseType": "FULL_USER",
"externallyOwned":false,
"links":
{
"self":"/api/xm/1/people/9407eb2e-8eb2-43d9-88a8-875237af941d"
},
"firstName":"Mary",
"lastName":"McBride",
"language":"en",
"timezone":"US/Pacific",
"webLogin":"mmcbride",
"phoneLogin": "23423",
"phonePin": "46189",
"site":
{
"id":"f0c572a8-45ec-fe23-289c-df749cf19a5e",
"links":
{
"self":"/api/xm/1/sites/f0c572a8-45ec-fe23-289c-df749cf19a5e"
}
},
"roles": {
"count": 2,
"total": 2,
"data": [
{
"id": "c2bdcd9e-1a18-0ff6-ffde-76e4022c94e6",
"name": "Standard User"
},
{
"id": "593433b0-e3b7-2e4c-f0cf-9faf2110b069",
"name": "Group Monitor"
}
]
},
"lastLogin": "2019-06-14T22:17:31.450Z",
"status":"ACTIVE"
}
Describes a person in xMatters. A person object is a Recipient object with a recipientType of PERSON.
A Person object contains the fields of the Recipient object as well as the fields described in the table below.
The Person object includes a list of the person's roles when the ?embed=roles query parameter is used with the request.
See also: Recipient object.
| firstName | string |
| The first name of the person. | |
| language | string |
| The person's default language. | |
| lastName | string |
| The last name of the person. | |
| licenseType | string |
The license type of the person in xMatters. Available options are:
|
|
| phoneLogin | string |
An access code that the person can use to identify themselves when they phone in to xMatters to retrieve messages. You can also optionally set a phonePin for the user. |
|
| phonePin | string |
The PIN a user enters with their phone login to identify themselves when they phone in to xMatters to retrieve messages. The user must have a phoneLogin set in order to use a phonePin. |
|
| properties | Properties object |
| A list of the custom fields and attributes that are defined for this person. | |
| roles | Pagination of Role object |
A list of the user's roles. This optional field is included when the request uses the ?embed=roles query parameter. |
|
| site | ReferenceByIdAndSelfLink object |
| A link to a resource that you can use to find out information about the site to which the person is assigned. | |
| supervisors | Person object or PersonReference |
A Paginated list of the user's supervisors. 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. |
|
| timezone | string |
| The person's time zone. Example: "US/Eastern" | |
| lastLogin | string |
| The date and time of the last time the person logged into xMatters. | |
| webLogin | string |
The identifier the person can use to log in to the xMatters user interface. This is often identical to the targetName value. |
Properties object
Properties object
"properties":
{
"myTextCustomField" : "myText",
"myCheckboxCustomField" : true,
"myDecimalCustomField" : 7.4,
"myIntegerCustomField" : 422,
"myListCustomField" : "ListItem5",
"myPasswordCustomField" : "42*W$E)121",
"myCustomAttribute" : ["value1", "value2", "value3"],
"removeACustomField" : null
}
The properties object refers to the values of the custom fields and custom attributes assigned to a person.
Custom fields contain a single value of type text, check box (Boolean), decimal, list (a text field that is required to match one of the predefined values in the custom field), integer, or password. Custom attributes are of type text and may have multiple values. You can locate custom fields and attributes on the Profile tab of the user profile.
To set the values of custom fields and attributes, include name/value pairs where the name is the name of the field or attribute
and the value is its value. To remove a non-mandatory custom field or attribute, include the name of the field and set the value to null.
Example: "firstAid" : "CPR level 1"
| {property_name} | {property_value} |
{property_name} is a string that represents the name of the custom field. property_value is a string, number, integer, or Boolean value that represents the type of custom field or attribute. Use null to remove the value of a non-mandatory property. |
PersonReference object
PersonReference object
{
"id" : "481086d8-357a-4279-b7d5-d7dce48fcd12",
"targetName": "mmcbride",
"firstName": "mary",
"lastName": "mcbride",
"recipientType": "PERSON",
"links":
{
"self":"/api/xm/1/people/481086d8-357a-4279-b7d5-d7dce48fcd12"
},
}
Refers to a person in xMatters.
| id | string |
| The unique identifier of the person. | |
| targetName | string |
| The user id of the person. | |
| firstName | string |
| The first name of the person. | |
| lastName | string |
| The last name of the person. | |
| recipientType | string |
| The type of user (for example, PERSON). | |
| links | SelfLink object |
| A link that can be used to retrieve the person using this API. |
UserQuota object
UserQuota object
{
"stakeholderUsersEnabled": true,
"stakeholderUsers": {
"total": 10,
"active": 6,
"unused": 4
},
"fullUsers": {
"total": 300,
"active": 169,
"unused": 131
}
}
Refers to the type and number of licenses for the users in your xMatters system. Users with a Stakeholder license type can be assigned the same roles and permissions as full users and they can access information in the web user interface and mobile app, but they cannot respond to any notifications they receive, act as an incident resolver, trigger forms that send messages, or initiate incidents or flows.
| total | integer |
| The total number of licenses, both unused and active, available for your xMatters instance. | |
| active | integer |
| The number of active, or used, licenses for your instance. | |
| unused | integer |
| The number of unused, or available, licenses for your instance. |
PLANS
We've renamed "communication plans" to "workflows" and are working to update the xMatters REST API guide to reflect those changes. At this time, 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.
Communication plans and built-in integration configurations are used to define how an event is processed, including message templates, response options, and any actions triggered by updates to the event. These communication plans and configurations are the foundation of integrations with xMatters.
Get communication plans
GET communication plans
REQUEST (get plans for built-in integrations where the name or description includes the term 'alert', and include detailed creator information in the response)
curl --user username "https://acmeco.xmatters.com/api/xm/1/plans?embed=creator&planType=BUILT_IN&search=alert"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans?embed=creator&planType=BUILT_IN&search=alert",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " plans." );
for (var i in json.data)
{
console.log(json.data[i].name + " created by " + json.data[i].creator.targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans?embed=creator&planType=BUILT_IN&search=alert"
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"]) + " comments."
)
for d in rjson["data"]:
print(
"Found plan with planType: "
+ d["planType"]
+ "\tname: "
+ d["name"]
+ "\tand id: "
+ d["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)
+ "\n"
+ str(response)
)
RESPONSE
{
"count": 5,
"total": 15,
"data": [
{
"id": "4cb646d0-488b-4745-844d-2814058f3578",
"planType": "BUILT_IN",
"name": "Monitoring Tool X",
"description": "Alerts from Montiroing Tool X",
"enabled": true,
"editable": true,
"loggingLevel": "INFO",
"accessibleByAll": false,
"floodControl": false,
"created": "2017-12-08T22:27:14.516Z",
"creator": {
"id": "934600d0-ae51-445c-805a-d38e49b80e96",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/934600d0-ae51-445c-805a-d38e49b80e96"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Eastern",
"webLogin": "mmcbride",
"site": {
"id": "fe8123c2-229f-4294-88ec-419994b4dbca",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/fe8123c2-229f-4294-88ec-419994b4dbca"
}
},
"status": "ACTIVE"
},
"links": {
"self": "/api/xm/1/plans/4cb646d0-488b-4745-844d-2814058f3578"
},
"position": 3
},
{
...truncated list of Plan objects...
}],
"links": {
"self": "/api/xm/1/plans?planType=BUILT_IN&offset=0&limit=10"
}
}
Returns a list of communication plans in your xMatters instance. This includes any built-in integration configurations and any integrations based on communication plans (packaged, custom, and ones converted from built-in integrations).
You can use the query parameters to limit your search by plan type (built-in or communication plan), search for a particular keyword in the name or description, or request more detailed information on the user that created the plan.
Depending on your permission level, you will see either a subset of information or all plan information.
DEFINITION
GET /plans
GET /plans?enabled=false
GET /plans?enabledFor=MOBILE
GET /plans?embed=creator,constants,endpoints,forms,propertyDefinitions,integrations
GET /plans?search=alert
GET /plans?search=alert playbook&operand=AND
GET /plans?search="alert playbook" "incident resolution workflow"&operand=AND&fields=NAME
QUERY PARAMETERS
| planType | string |
Use this if you want the request to only return integrations of a specific type.
|
|
| enabled | Boolean |
When true the response displays only enabled plans. When false the response displays disabled plans. |
|
| enabledFor | string |
Returns only plans that have forms enabled for a specific component. Valid values include:
|
|
| embed | string |
A list of additional objects to include in the response.
|
|
| search | string |
A list of search terms separated by the + sign or a space character. The results include plans 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. When two or more search terms are present, the result includes plans that match either search term. Use the operand and fields query parameters to expand or limit search results.When your search term contains more than one word, or contains delimiting characters such as spaces, enclose the terms in double quotes to preserve the delimiters. Example: /plans?search=alert playbook&fields=NAME returns all plans with names that contain either "alert" or "playbook". However, searching /plans?search="alert playbook"&fields=NAME returns all plans with names that contain "alert playbook". |
|
| operand | string |
Applied to the provided search terms to limit or expand the search query parameter. Available options include: AND or OR. AND only returns plans that have all search terms in the specified fields. OR returns plans that have any of the search terms in the specified fields; this is the default if you don’t specify an operand. The operand is case-sensitive; entering lowercase "and" will return an error. |
|
| fields | string |
Defines the fields to search when a search term is specified. Valid values include:
|
|
| sortBy | string |
Determines the criteria by which plans are sorted.
sortOrder to change whether the results are sorted in ascending or descending order. |
|
| sortOrder | string |
Sets whether plans are sorted in ascending or descending order. This parameter must be used in conjunction with the sortBy query parameter. Valid values include:
|
|
| subscription-forms | string |
| A list of subscription forms that belong to the plan. For more details, see Subscription forms. | |
| 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 Plan objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a communication plan
GET a communication plan
REQUEST (get a plan and include detailed creator information)
curl --user username "https://acmeco.xmatters.com/api/xm/1/plans/a2e6b439-3396-4580-8793-1565b64d417f?embed=creator"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/a2e6b439-3396-4580-8793-1565b64d417f?embed=creator",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved plan: " + json.name + ". Plan Id: " + json.id + ". Created by " + json.creator.targetName);
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/a2e6b439-3396-4580-8793-1565b64d417f?embed=creator"
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(
"Found plan with planType: "
+ rjson["planType"]
+ "\tand name: "
+ rjson["name"]
)
# Not all plans have a "creator" property, so need to test for this.
if hasattr(rjson, "creator"):
print("\tcreated by: " + rjson["creator"]["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(response.status_code)
+ "\n"
+ str(response)
)
RESPONSE
{
"id": "a2e6b439-3396-4580-8793-1565b64d417f",
"planType": "BUILT_IN",
"name": "Monitoring Tool X",
"enabled": true,
"editable": false,
"loggingLevel": "INFO",
"accessibleByAll": false,
"floodControl": false,
"created": "2017-12-08T22:27:14.516Z",
"creator": {
"id": "934600d0-ae51-445c-805a-d38e49b80e96",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/934600d0-ae51-445c-805a-d38e49b80e96"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Eastern",
"webLogin": "mmcbride",
"site": {
"id": "fe8123c2-229f-4294-88ec-419994b4dbca",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/fe8123c2-229f-4294-88ec-419994b4dbca"
}
},
"status": "ACTIVE"
},
"links": {
"self": "/api/xm/1/plans/a2e6b439-3396-4580-8793-1565b64d417f"
},
"position": 5
}
Returns a specific communication plan or built-in integration configuration in your xMatters instance. Depending on your permission level, you will see either a subset of information or all plan information.
DEFINITION
GET /plans/{planId} GET /plans/{planId}?embed=creator,constants,endpoints,forms,propertyDefinitions,integrations
URL PARAMETERS
| planId | string |
The unique identifier (id) or name of the plan.Examples:
id). Use GET /plans to get the id of a communication plan or built-in integration. |
QUERY PARAMETERS
| embed | string |
A list of additional objects to include in the response.
|
RESPONSES
| Success | Response code 200 OK and a Plan object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a communication plan
Create a communication plan
REQUEST - Create a communication plan
curl --user username --header "Content-Type: application/json" --request POST -d '{
"name": "Severe Weather Warnings",
"enabled": true,
"accessibleByAll": false,
"floodControl": false,
"position": 2
}
' "https://acmeco.xmatters.com/api/xm/1/plans/"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.plan.name = 'Severe Weather Warnings';
data.plan.enabled = true;
data.plan.accessibleByAll = false;
data.plan.floodControl = false;
data.plan.position = 2;
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Created plan " + json.targetName + ". ID = "+ json.id);
}
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans"
url = base_URL + endpoint_URL
payload = {
"name": "Severe Weather Warnings",
"enabled": True,
"accessibleByAll": False,
"floodControl": False,
"position": 2
}
response = requests.post(url, json=payload, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Created communication plan.")
RESPONSE
{
"id": "4cb646d0-488b-4745-844d-2814058f3578",
"name": "Severe Weather Warnings",
"description": "",
"enabled": true,
"accessibleByAll": false,
"created": "2017-12-08T22:27:14.516Z",
"creator": {
"id": "934600d0-ae51-445c-805a-d38e49b80e96",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/934600d0-ae51-445c-805a-d38e49b80e96"
},
},
"links": {
"self": "/api/xm/1/plans/4cb646d0-488b-4745-844d-2814058f3578"
},
"position": 2
},
Communication plans allow you to tailor your communications to suit the situation, recipient, and required action based on any business process, emergency, or technology. With a communication plan in place, you can target specific information to a specific user, or communicate important information to multiple users. This endpoint allows users with appropriate permission settings to create communication plans.
DEFINITION
POST /plans
BODY PARAMETERS
| name | string |
| required | The name of the communication plan. |
| description | string |
| The description of the communication plan. | |
| enabled | Boolean |
| required | This is true if the communication plan is enabled. |
| accessibleByAll | Boolean |
When true, this indicates if the plan is accessible by everyone in your xMatters company. When false, only the plan creator can view the plan. You can set this using the Access Permissions for the integration in the web user interface. |
|
| position | integer |
| The display order of the plan in the web user interface. If a position is not provided when a plan is created, the plan is displayed at the top of the list in the web user interface. |
RESPONSES
| Success | Response code 201 Created and a Plan object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify communication plan
Modify or update a communication plan
REQUEST - The following request shows how to add a description to an existing communication plan.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "0482202f-bc59-4f4d-a5c7-4a451c5f80ac",
"name": "Severe Weather Warnings",
"description": "Use this plan to notify users of upcoming severe weather systems.",
"enabled": true,
"loggingLevel": "INFO",
"accessibleByAll": false,
"floodControl": false,
"position": 3
}'
"https://acmeco.xmatters.com/api/xm/1/plans/
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.plan.id = '0482202f-bc59-4f4d-a5c7-4a451c5f80ac';
data.plan.name = 'Severe Weather Warnings';
data.plan.description = 'Use this plan to notify users of upcoming severe weather systems.';
data.plan.enabled = true;
data.plan.loggingLevel = 'INFO';
data.plan.accessibleByAll = false;
data.plan.floodControl = false;
data.plan.position = 3;
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Modified plan " + json.targetName + ". ID = "+ json.id);
}
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/4cb646d0-488b-47b5-844d-2814058f3578"
url = base_URL + endpoint_URL
payload = {
"name": "Severe Weather Warnings",
"description": "Use this plan to notify users of upcoming severe weather systems.",
"enabled": True,
"loggingLevel": "INFO",
"accessibleByAll": False,
"floodControl": False,
"position": 3,
}
response = requests.post(url, json=payload, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Modified communication plan.")
RESPONSE
{
"id": "4cb646d0-488b-4745-844d-2814058f3578",
"planType": "PLAN",
"name": "Severe Weather Warnings",
"description": "Use this plan to notify users of upcoming severe weather systems.",
"enabled": true,
"loggingLevel": "INFO",
"accessibleByAll": false,
"created": "2017-12-08T22:27:14.516Z",
"creator": {
"id": "934600d0-ae51-445c-805a-d38e49b80e96",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/934600d0-ae51-445c-805a-d38e49b80e96"
},
},
"links": {
"self": "/api/xm/1/plans/4cb646d0-488b-4745-844d-2814058f3578"
},
"position": 3
},
Changes the properties of an existing communication plan. Identify the plan by its unique identifier in the id field, and then provide the fields you want to modify. Use GET /plans to find the id of the plan.
DEFINITION
POST /plans
BODY PARAMETERS
| id | string |
| required | The unique identifier (id) of the communication plan. |
| name | string |
| The name of the communication plan. | |
| description | string |
| The description of the communication plan. | |
| enabled | Boolean |
| This is true if the communication plan is enabled. If changed to false the plan is disabled. | |
| loggingLevel | string |
Indicates if all requests (including successful requests) or only failed requests are logged to the Activity Stream.
|
|
| accessibleByAll | Boolean |
When true, this indicates if the plan is accessible by everyone in your xMatters company. When false, only the plan creator can view the plan. You can set this using the Access Permissions for the integration in the web user interface. |
|
| position | integer |
| The display position of the plan in the web user interface. Changing the existing position number moves the plan in the web user interface, and the other plans are renumbered accordingly. If the position is not modified or included when modifying other communication plan properties, the plan's position is unchanged. |
RESPONSES
| Success | Response code 201 Modified and a Plan object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a plan
Delete a plan
REQUEST: Delete a built in plan by name. You can also identify the plan by its unique identifier (
id).
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/plans/438e9245-b32d-445f-916bd3e07932c89"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/438e9245-b32d-445f-916bd3e07932c89",
/*"path" : "api/xm/1/plans/438e9245-b32d-445f-916bd3e07932c89",*/
"method": "DELETE",
"headers" : {"Content-Type": "application/json"}
});
response = request.write();
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the plan " + json.targetName);
}
import requests
base_url = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_url = '/plans/438e9245-b32d-445f-916bd3e07932c89'
url = base_url + endpoint_url
response = requests.delete(url, auth=('username', 'password'))
if response.status_code == 200:
print('Deleted plan ' + response.json()['targetName'])
RESPONSE
{
"id": "438e9245-b32d-445f-916bd3e07932c89",
"planType": "BUILT_IN",
"name": "Monitoring Tool X",
"enabled": true,
"editable": true,
"loggingLevel": "INFO",
"accessibleByAll": false,
"floodControl": false,
"created": "2017-12-08T22:27:14.516Z",
"creator": {
"id": "934600d0-ae51-445c-805a-d38e49b80e96",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/934600d0-ae51-445c-805a-d38e49b80e96"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Eastern",
"webLogin": "mmcbride",
"site": {
"id": "fe8123c2-229f-4294-88ec-419994b4dbca",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/fe8123c2-229f-4294-88ec-419994b4dbca"
}
},
"status": "ACTIVE"
},
"links": {
"self": "/api/xm/1/plans/438e9245-b32d-445f-916bd3e07932c89"
}
}
Allows an user with appropriate permission settings to delete a plan using either the plan name or its unique identifier (the id field). The planType must be PLAN.
The response returns a Plan Object that represents the recently deleted plan.
DEFINITION
DELETE /plans/{planId}
URL PARAMETERS
| planId | string |
The unique identifier (id) or name (targetName) of the plan. Only communication plans with a planType of PLAN can be deleted.Example: Monitoring Tool X Example: a6341d69-5683-4621-b8c8-f2e728f6752q |
RESPONSES
| Success | Response code 200 OK and a Plan object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Communication plan objects
Plan object
Plan object
This example shows a built-in integration.
{
"id": "4cb646d0-488b-4745-844d-2814058f3578",
"planType": "BUILT_IN",
"name": "Monitoring Tool X",
"enabled": true,
"editable": true,
"loggingLevel": "INFO",
"accessibleByAll": false,
"floodControl": false,
"created": "2017-12-08T22:27:14.516Z",
"creator": {
"id": "934600d0-ae51-445c-805a-d38e49b80e96",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/934600d0-ae51-445c-805a-d38e49b80e96"
},
"firstName": "Mary",
"lastName": "McBride",
"language": "en",
"timezone": "US/Eastern",
"webLogin": "mmcbride",
"site": {
"id": "fe8123c2-229f-4294-88ec-419994b4dbca",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/fe8123c2-229f-4294-88ec-419994b4dbca"
}
},
"status": "ACTIVE"
},
"links": {
"self": "/api/xm/1/plans/4cb646d0-488b-4745-844d-2814058f3578"
},
"position": 4
}
Describes a communication plan, including its name, id, type, and creator (for built-in integrations).
| id | string |
The unique identifier (id) of the communication plan or built-in integration configuration. |
|
| planType | string |
The type of communication plan or integration.
|
|
| name | string |
| The name of the configuration or communication plan. | |
| description | string |
| The description of the configuration or communication plan. | |
| enabled | Boolean |
| This is true if the communication plan or configuration is enabled. | |
| editable | Boolean |
| When true, this indicates the authenticating user has permissions to edit the communication plan or configuration. | |
| loggingLevel | string |
Indicates if all requests (including successful requests) or only failed requests are logged to the Activity Stream.
|
|
| accessibleByAll | Boolean |
| When true, this indicates if the plan is accessible by everyone in your xMatters company. You can set this using the Access Permissions for the integration in the web user interface. | |
| floodControl | Boolean |
For built-in integrations only. This is true if the configuration has notification flood control enabled. You can set this using the Flood Control settings for the configuration in the web user interface. For more information see Notification Flood Control in the xMatters online help. |
|
| created | string |
| The date and time the communication plan or configuration was created. | |
| creator | personReference object / Person object |
This is returned only for built-in integrations. By default, this is a personReference object. If ?embed=creator is used in the request, it contains a Person object. |
|
| constants | Pagination of Constant objects |
A list of any constants configured in the plan, returned when the request uses the ?embed=constants query parameter. |
|
| endpoints | Pagination of Endpoint objects |
A list of any endpoints configured in the plan, returned when the request uses the ?embed=endpoints query parameter. |
|
| forms | Pagination of Form objects |
A list of any forms configured in the plan, returned when the request uses the ?embed=forms query parameter. |
|
| integrations | Pagination of Integration objects |
A list of any inbound or outbound integrations configured in the plan, returned when the request uses the ?embed=integrations query parameter. |
|
| propertyDefinitions | Pagination of Plan Property objects |
A list of any properties defined in the plan, returned when the request uses the ?embed=propertyDefinitions query parameter. |
|
| links | SelfLink object |
| A link that can be used to reference the communication plan or configuration. | |
| position | integer |
| The display position of plans in the web user interface. |
PlanReference object
PlanReference object
"plan": {
"id": "ae200916-1846-4892-b692-2ea7e6cf29cf",
"name": "Database monitoring"
}
Describes a reference to a communication plan, including its name and unique identifier.
| id | string |
The unique identifier (id) of the communication plan or built-in integration configuration. |
|
| name | string |
| The name of the plan (not included in all instances). |
PlanPointer object
PlanPointer object
"plan": {
"id": "ae200916-1846-4892-b692-2ea7e6cf29cf"
}
Describes a reference to a communication plan that uses only the unique identifier of the plan.
| id | string |
The unique identifier (id) of the communication plan or built-in integration configuration. |
PLAN CONSTANTS
Constants are used to set parameters that should remain the same wherever they're called in the transformation scripts. They can also be used to provide a human-readable name for the parameter to users.
While GET returns constants for plans types of both PLAN and BUILT-IN, you can only create, modify and delete constants for the plan type of PLAN.
Get plan constants
Get plan constants
REQUEST (get a list of constants in a communication plan)
curl --user username "https://acmeco.xmatters.com/api/xm/1/plans/a2e6b439-3396-4580-8793-1565b64d417f/constants"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/a2e6b439-3396-4580-8793-1565b64d417f/constants",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " constants.");
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/a2e6b439-3396-4580-8793-1565b64d417f/constants"
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"])
+ " plan constants."
)
for d in rjson.get("data"):
print(
"Found plan constant with id: "
+ d["id"]
+ "\t name: "
+ d["name"]
+ "\tand value: "
+ d["value"]
)
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": 1,
"total": 1,
"data": [
{
"id": "00000000-0000-0000-0000-0000000004d7",
"plan": {
"id": "a2e6b439-3396-4580-8793-1565b64d417f"
},
"name": "Email Device Name",
"value": "WORK_EMAIL",
"description": "The xMatters email device to use for all handles within Monitoring Tool X."
}
],
"links": {
"self": "/api/xm/1/plans/479066b7-3aab-46e5-9f72-192831cc65d0/constants?offset=0&limit=100"
}
}
Returns a list of constants configured in the specified communication plan.
DEFINITION
GET /plans/{planId}/constants
URL PARAMETERS
| planId | string |
The unique identifier (id) or name of the plan you want to list the constants for. Use GET /plans to find the id or name of the plan. |
|
| 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 paginated list of Constant objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a plan constant
Create a plan constant
REQUEST - Create a communication plan constant
curl --user username --header "Content-Type: application/json" --request POST -d '{
"name": "From",
"value": "Awesome Software Co.",
"description": "The company name to attach to all chat bot conversations."
}'
"https://acmeco.xmatters.com/api/xm/1/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/constants"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/constants",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.name = 'From';
data.value = 'Awesome Software Co.';
data.description = 'The company name to attach to all chat bot conversations.';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created constant " + json.name + ". ID = " + json.id);
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/constants"
url = base_URL + endpoint_URL
payload = {
"name": "From",
"value": "Awesome Software Co.",
"description": "The company name to attach to all chat bot conversations.",
}
if response.status_code == 201:
print("Created plan constant.")
RESPONSE
{
"id": "a01cc337-14ed-47f4-b6a9-2b7108017b7f",
"plan": {
"id": "c56730a9-1435-4ae2-8c7e-b2539e635ac6"
},
"name": "From",
"value": "Awesome Software Co.",
"description": "The company name to attach to all chat bot conversations."
}
Creates a constant for a communication plan.
DEFINITION
POST /plans/{planId}/constants
URL PARAMETERS
| planId | string |
The unique identifier (id) or name of the plan you want to list the constants for. Use GET /plans to find the id or name of the plan. |
BODY PARAMETERS
| name | string |
| The configurable name of the constant. | |
| value | string |
| The value of the constant that will be used wherever it appears in the integration scripts | |
| description | string |
| A description of the purpose of the constant. |
RESPONSES
| Success | Response code 201 Created and a Plan constant object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a plan constant
REQUEST - Modify a plan constant
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "a01cc337-14ed-47f4-b6a9-2b7108017b7f",
"name": "From",
"value": "ACME Video Game Consulting",
"description": "The company name to attach to all chat bot conversations."
}'
"https://acmeco.xmatters.com/api/xm/1/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/constants/"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/constants",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = 'a01cc337-14ed-47f4-b6a9-2b7108017b7f';
data.name = 'From';
data.value = 'ACME Video Game Consulting';
data.description = 'The company name to attach to all chat bot conversations.';
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Updated constant " + json.name + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/constants"
url = base_URL + endpoint_URL
payload = (
{
"id": "a01cc337-14ed-47f4-b6a9-2b7108017b7f",
"name": "From",
"value": "ACME Video Game Consulting",
"description": "The company name to attach to all chat bot conversations.",
},
)
response = requests.post(url, json=payload, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Updated plan constant.")
RESPONSE See Create Constants for an example of the response object.
This endpoint lets you modify or update an existing communication plan constant.
DEFINITION
POST /plans/{planId}/constants
URL PARAMETERS
| planId | string |
| Identifies the communication plan where the constant is added. |
BODY PARAMETERS
The only required body parameters is the UUID of the constant you want to update. See the Create Constants body parameters for details on the parameters you can change.
| id | string |
| Identifies the constant to be modified. |
RESPONSES
| Success | Response code 201 Created and a Plan constant object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a plan constant
Delete a plan constant
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/plans/438e9245-b32d-445f-916bd3e07932c89/constants/a01cc337-14ed-47f4-b6a9-2b7108017b7f"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/438e9245-b32d-445f-916bd3e07932c89/constants/a01cc337-14ed-47f4-b6a9-2b7108017b7f",
"method": "DELETE",
"headers" : {
"Content-Type": "application/json"
}
});
response = request.write();
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log("Deleted the constant " + json.name);
}
import requests
base_url = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_url = '/plans/438e9245-b32d-445f-916bd3e07932c89/constants/a01cc337-14ed-47f4-b6a9-2b7108017b7f'
url = base_url + endpoint_url
response = requests.delete(url, auth=('username', 'password'))
if response.status_code == 200:
print('Deleted constant ' + response.json()['name'])
RESPONSE
{
"id": "a01cc337-14ed-47f4-b6a9-2b7108017b7f",
"plan": {
"id": "438e9245-b32d-445f-916bd3e07932c89"
},
"name": "From",
"value": "Awesome Software Co.",
"description": "The company name to attach to all chat bot conversations.",
"link": {
"self": "/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/constants/a01cc337-14ed-47f4-b6a9-2b7108017b7f"
}
}
Allows a user with appropriate permission settings to delete a constant using the planId and the constantId.
The response returns a Plan Constant Object that represents the recently deleted constant.
DEFINITION
DELETE /plans/{planId}/constants/{constantId}
URL PARAMETERS
| planId | string |
The unique identifier (id) or name (targetName) of the plan. |
|
| constantId | string |
| The unique identifier of the constant to be deleted. |
RESPONSES
| Success | Response code 200 OK and a Plan constant object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Plan constant objects
Plan constant object
Constant object
This example shows a constant setting WORK_EMAIL as the email device name to use for handles from the target system.
{
"id": "00000000-0000-0000-0000-0000000004d7",
"plan": {
"id": "a2e6b439-3396-4580-8793-1565b64d417f"
},
"name": "Email Device Name",
"value": "WORK_EMAIL",
"description": "The xMatters email device to use for all handles within Monitoring Tool X.",
"links": {
"self": "/plans/a2e6b439-3396-4580-8793-1565b64d417f/constants?offset=0&limit=100"
}
}
Describes a communication plan constant.
| id | string |
The unique identifier (id) of the constant. |
|
| plan | PlanPointer object |
| Identifies the communication plan the constant belongs to. | |
| name | string |
| The configurable name of the constant. | |
| value | string |
| The value of the constant that will be used wherever it appears in the integration scripts. | |
| description | string |
| A description of the purpose of the constant. | |
| links | SelfLink object |
| A link that can be used to reference the list of constants. |
PLAN ENDPOINTS
The endpoints in a communication plan define the base URL and authentication used for applications in an integration. By defining this outside of the transformation scripts and referencing the endpoint, rather than hard-coding it, you can easily update the endpoint details in the web user interface and have that change populate throughout the integration. For more information on endpoints, see HTTP Endpoints in the xMatters online help.
Get plan endpoints
Get plan endpoints
REQUEST (get a list of endpoints configured for a communication plan)
curl --user username "https://acmeco.xmatters.com/api/xm/1/plans/a2e6b439-3396-4580-8793-1565b64d417f/endpoints"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/a2e6b439-3396-4580-8793-1565b64d417f/endpoints",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " endpoints.");
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/a2e6b439-3396-4580-8793-1565b64d417f/endpoints"
url = base_URL + endpoint_URL + "?offset=0&limit=10"
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 endpoint with id: "
+ d["id"]
+ "\tname: "
+ d["name"]
+ "\t and url: "
+ d["url"]
)
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": 2,
"total": 2,
"data": [
{
"id": "a01cc337-14ed-47f4-b6a9-2b7108017b7f",
"plan": {
"id": "a2e6b439-3396-4580-8793-1565b64d417f"
},
"name": "MyEndpoint",
"url": "http://example.com",
"authentication": {
"username": "rest"
},
"endpointType": "EXTERNAL",
"authenticationType": "BASIC"
},
{
"id": "f311ee85-b256-4f36-b369-1380901183e3",
"plan": {
"id": "a2e6b439-3396-4580-8793-1565b64d417f"
},
"name": "Acme Endpoint",
"url": "http://acme.com",
"authentication": {
"username": "rest",
"oauthTokenUrl": "https://api.acme.com/oauth2/access_token"
},
"endpointType": "EXTERNAL",
"authenticationType": "OAUTH2"
}
],
"links": {
"self": "/api/xm/1/plans/a2e6b439-3396-4580-8793-1565b64d417f/endpoints?offset=0&limit=100"
}
Returns a list of endpoints configured for the specified communication plan or built-in integration.
DEFINITION
GET /plans/{planId}/endpoints
URL PARAMETERS
| planId | string |
The unique identifier (id) or name of the plan that you want to retrieve the endpoints for. Use GET /plans to find the id or name of the plan. |
|
| 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 paginated list of Endpoint objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create plan endpoint
Create a communication plan endpoint
REQUEST - Create a communication plan endpoint
curl --user username --header "Content-Type: application/json" --request POST -d '{
"name": "Stargazer Endpoint",
"url": "http://stargazer.com",
"authentication": {
"username": "rest",
"oauthTokenUrl": "https://api.stargazer.com/oauth2/access_token"
},
"endpointType": "EXTERNAL",
"authenticationType": "OAUTH2"
}'
"https://acmeco.xmatters.com/api/xm/1/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/endpoints"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.name = 'Stargazer Endpoint';
data.url = 'http://stargazer.com';
data.type = 'EXTERNAL';
var authentication = {};
authentication.type = 'OAUTH2';
authentication.username = 'rest';
authentication.oauthTokenUrl = 'https://api.stargazer.com/oauth2/access_token';
data.authentication = authentication;
response = request.write(data);
if (response.statusCode == 201)
{ json = JSON.parse(response.body); console.log( "Created endpoint " + json.targetName + ". ID = "+ json.id); }
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/endpoints"
url = base_URL + endpoint_URL
payload = {
"name": "Stargazer Endpoint",
"url": "http://stargazer.com",
"authentication": {
"username": "rest",
"oauthTokenUrl": "https://api.stargazer.com/oauth2/access_token"
},
"endpointType": "EXTERNAL",
"authenticationType": "OAUTH2",
}
response = requests.post(url, json=payload, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Created plan endpoint.")
RESPONSE
{
"id": "a01cc337-14ed-47f4-b6a9-2b7108017b7f",
"plan": {
"id": "c56730a9-1435-4ae2-8c7e-b2539e635ac6"
},
"name": "Stargazer Endpoint",
"url": "http://stargazer.com",
"authentication": {
"username": "rest",
"oauthTokenUrl": "https://api.stargazer.com/oauth2/access_token"
},
"endpointType": "EXTERNAL",
"authenticationType": "OAUTH2",
"link": {
"self": "/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/endpoints"
}
}
Creates an endpoint for a communication plan. Depending on the type, you will have to provide various authentication parameters. For information on the specific authentication requirements, see Endpoint Authentication objects.
DEFINITION
POST /plans/{planId}/endpoints
URL PARAMETERS
| planId | string |
| Identifies the communication plan where the endpoint is added. |
BODY PARAMETERS
| name | string |
| The name of the endpoint. | |
| url | string |
| The base URL that is inserted into paths where you reference the endpoint by name (https://acme.com/api/xm/1/plans/...). | |
| endpointType | string |
| The type of endpoint. Valid value is EXTERNAL | |
| authenticationType | string |
The authentication type set up for the endpoint in xMatters. Acceptable values include:
|
|
| authentication | Endpoint authentication object |
| Provides additional details about the authentication of the endpoint. |
RESPONSES
| Success | Response code 201 Created and a Plan endpoints object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a plan endpoint
Modify a communication plan endpoint
REQUEST - Modify a communication plan endpoint name using its unique ID.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "a01cc337-14ed-47f4-b6a9-2b7108017b7f",
"name": "Comet Tracker Endpoint",
"url": "http://stargazer.com",
"authentication": {
"username": "rest",
"oauthTokenUrl": "https://api.stargazer.com/oauth2/access_token"
},
"endpointType": "EXTERNAL",
"authenticationType": "OAUTH2"
}'
"https://acmeco.xmatters.com/api/xm/1/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/endpoints"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/ednpoints",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = 'a01cc337-14ed-47f4-b6a9-2b7108017b7f'
data.name = 'Comet Tracker Endpoint';
data.url = 'http://stargazer.com';
data.type = 'EXTERNAL';
var authentication = {};
authentication.type = 'OAUTH2';
authentication.username = 'rest';
authentication.oauthTokenUrl = 'https://api.stargazer.com/oauth2/access_token';
data.authentication = authentication;
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Modified endpoint " + json.targetName + ". ID = "+ json.id);
}
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/endpoints"
url = base_URL + endpoint_URL
payload = {
"id": "a01cc337-14ed-47f4-b6a9-2b7108017b7f",
"name": "Comet Tracker Endpoint",
"url": "http://stargazer.com",
"authentication": {
"username": "rest",
"oauthTokenUrl": "https://api.stargazer.com/oauth2/access_token",
},
"endpointType": "EXTERNAL",
"authenticationType": "OAUTH2",
}
response = requests.post(url, json=payload, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Modified plan endpoint.")
RESPONSE
{
"id": "a01cc337-14ed-47f4-b6a9-2b7108017b7f",
"plan": {
"id": "c56730a9-1435-4ae2-8c7e-b2539e635ac6"
},
"name": "Comet Tracker Endpoint",
"url": "http://stargazer.com",
"authentication": {
"username": "rest",
"oauthTokenUrl": "https://api.stargazer.com/oauth2/access_token"
},
"endpointType": "EXTERNAL",
"authenticationType": "OAUTH2",
"link": {
"self": "/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/endpoints"
}
}
Modifies an endpoint for a communication plan. Depending on the type, you will have to provide various authentication parameters. For information on the specific authentication requirements, see Endpoint Authentication objects.
DEFINITION
POST /plans/{planID}/endpoints
BODY PARAMETERS
The only required body parameter is the UUID of the plan you want to update. See Create Endpoint for details on the other other available parameters
| plan | PlanReference object |
| Identifies the communication plan where the endpoint is added. |
RESPONSES
| Success | Response code 201 Created and a Plan endpoint object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a plan endpoint
Delete a communication plan endpoint
REQUEST: Delete a plan endpoint by id.
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/plans/438e9245-b32d-445f-916bd3e07932c89/endpoints/4cb646d0-488b-4745-844d-2814058f3578"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/438e9245-b32d-445f-916bd3e07932c89/endpoints/4cb646d0-488b-4745-844d-2814058f3578",
"method": "DELETE",
"headers" : {"Content-Type": "application/json"}
});
response = request.write();
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the plan " + json.targetName);
}
import requests
plan_id = '438e9245-b32d-445f-916bd3e07932c89'
endpoint_id = '4cb646d0-488b-4745-844d-2814058f3578'
base_url = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_url = f'/plans/{plan_id}/endpoints/{endpoint_id}'
url = base_url + endpoint_url
response = requests.delete(url, auth=('username', 'password'))
if response.status_code == 200:
print('Deleted endpoint ' + response.json()['targetName'])
RESPONSE
{
"id": "4cb646d0-488b-4745-844d-2814058f3578",
"plan": {
"id": "438e9245-b32d-445f-916bd3e07932c89"
},
"name": "Acme Endpoint",
"url": "http://acme.com",
"endpointType": "EXTERNAL",
"authenticationType": "OAUTH2"
"links": {
"self": "/api/xm/1/plans/438e9245-b32d-445f-916bd3e07932c89/endpoints/4cb646d0-488b-4745-844d-2814058f3578"
}
}
Deletes a communication plan endpoint.
Identify the plan using either the plan name or its unique identifier (the id field), and the endpoint by it's unique identifier id.
The response returns a Plan Endpoint Object that represents the recently deleted endpoint.
DEFINITION
DELETE /plans/{planId}/endpoint/{endpointId}
URL PARAMETERS
| planId | string |
The unique identifier (id) or name (targetName) of the plan. Example: Monitoring Tool X Example: a6341d69-5683-4621-b8c8-f2e728f6752q |
|
| endpointId | string |
The unique identifier (id) of the endpoint to be deleted. |
RESPONSES
| Success | Response code 200 OK and a Plan Endpoint object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Plan endpoint objects
Endpoint object
Endpoint object
This example shows an endpoint configured with OAuth 2 authentication.
{
"id": "a01cc337-14ed-47f4-b6a9-2b7108017b7f",
"plan": {
"id": "c56730a9-1435-4ae2-8c7e-b2539e635ac6"
},
"name": "Acme Endpoint",
"url": "http://acme.com",
"authentication": {
"username": "rest",
"oauthTokenUrl": "https://api.acme.com/oauth2/access_token"
},
"endpointType": "EXTERNAL",
"authenticationType": "OAUTH2",
"trustSelfSigned": "true"
}
"links": {
"self": "/api/xm/1/plans/c56730a9-1435-4ae2-8c7e-b2539e635ac6/endpoints/a01cc337-14ed-47f4-b6a9-2b7108017b7f"
}
Describes a communication plan endpoint.
| id | string |
The unique identifier (id) of the endpoint. |
|
| plan | PlanReference object |
| Identifies the communication plan the endpoint belongs to. | |
| name | string |
| The name of the endpoint. | |
| url | string |
| The base URL that is inserted into paths where you reference the endpoint by name (https://acme.com/api/xm/1/plans/...). | |
| endpointType | string |
The type of endpoint.
|
|
| authenticationType | string |
| The authentication type that is set up for the endpoint in xMatters: "NO_AUTH", "BASIC", "OAUTH2", "OAUTH2_FORCE" (Salesforce), "OAUTH_SLACK" (Slack) | |
| authentication | An Endpoint authentication object |
| Provides additional details about the authentication of the endpoint. | |
| trustSelfSigned | Boolean |
When true, self-signed certificates are trusted. |
|
| links | SelfLink object |
| A link that can be used to reference the list of endpoints. |
Endpoint Authentication objects
Basic Authentication object
Basic Authentication object
This example shows the authentication object for an endpoint configured with basic authentication.
"authentication": {
"username": "rest",
"password": "pa$$word143",
}
Describes the basic authentication type of a communication plan endpoint.
| username | string |
| The targetName of the autheticating user (returned for Basic and OAuth authentication types). | |
| password | string |
| The password of the authenticating user. |
OAuth2 Authentication object
OAuth2 Authentication object
This example shows the authentication object for an endpoint configured with OAuth 2 authentication.
"authentication": {
"username": "rest",
"oauthTokenUrl": "https://api.acme.com/oauth2/access_token",
"oauthClientId": "client_id",
"client_secret": "oauthClientSecret",
"password": "pa$$word143"
}
Describes the authentication of a communication plan endpoint for OAuth2 and Salesforce authentications.
| username | string |
| The targetName of the autheticating user (returned for Basic and OAuth authentication types). | |
| oauthTokenUrl | string |
For the endpoints configured with one of the OAuth authenticationType options, this is the Access Token URL for the target system. |
|
| oauthClientId | string |
For endpoints configured with one of the OAuth authenticationType options, this is the Client ID associated with the OAuth username (if this was included in the setup). |
|
| client_secret | string |
| A secret key created by the user. | |
| password | string |
| The password of the authenticating user. |
PLAN PROPERTIES
This endpoint describes the available properties for existing communication plans. For more information on how properties work with forms and communication plans, see Define form properties in the online help.
Get plan properties
Get plan properties
REQUEST (get a list of of properties defined in a communication plan)
curl --user username "https://acmeco.xmatters.com/api/xm/1/plans/a2e6b439-3396-4580-8793-1565b64d417f/property-definitions"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/a2e6b439-3396-4580-8793-1565b64d417f/property-definitions",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " properties.");
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/a2e6b439-3396-4580-8793-1565b64d417f/property-definitions"
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)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print(
"Retrieved "
+ str(rjson["count"])
+ " of "
+ str(rjson["total"])
+ " plan properties."
)
for d in rjson.get("data"):
print(
"Found a property with id: "
+ d["id"]
+ "\t name: "
+ d["name"]
+ "\tand description: "
+ d["description"]
)
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
{
"count": 10,
"total": 10,
"data": [
{
"id": "e4fa745c-b0a3-421b-b1ad-ec025dc85544",
"propertyType": "TEXT",
"name": "Event details",
"description": "Details of the issue or event",
"helpText": "",
"default": "",
"maxLength": 1500,
"minLength": 0,
"pattern": "",
"validate": false
},
{
"id": "8c37b146-6411-4e3c-ad3c-cb5c475c7a4e",
"propertyType": "TEXT",
"name": "First reported",
"description": "Time the issue was first reported",
"helpText": "Enter the time the issue was first reported in the format DD/MM/YYYY 23:00",
"default": "01/01/2001 8:00:00",
"maxLength": 30,
"minLength": 0,
"pattern": "\\d{1,2}/\\d{1,2}/\\d{1,4} \\d{1,2}:\\d{2}(:\\d{2})?",
"validate": true
},
{ ...truncated list of property definitions...}
],
"links": {
"self": "/api/xm/1/plans/a2e6b439-3396-4580-8793-1565b64d417f/property-definitions?offset=0&limit=100"
}
Returns a list of properties defined for a specified communication plan.
DEFINITION
GET /plans/{planId}/property-definitions
URL PARAMETERS
| planId | string |
The unique identifier (id) or name of the plan that you want to retrieve the properties for. Use GET /plans to find the id or name of the plan. |
|
| 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 paginated list of Plan property objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create plan properties
Create plan properties
REQUEST - Create a text property for a communication plan.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"propertyType": "TEXT",
"name": "First reported",
"description": "Time the issue was first reported",
"helpText": "Enter the time the issue was first reported in the format DD/MM/YYYY 23:00",
"default": "2019-01-01T08:00:00Z",
"maxLength": 30,
"minLength": 0,
"pattern": "\\d{4}\\-\\d{2}\\-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(Z)?",
"validate": true
}
' "https://acmeco.xmatters.com/api/xm/1/plans/8c37b146-6411-4e3c-ad3c-cb5c475c7a4e/property-definitions"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/8c37b146-6411-4e3c-ad3c-cb5c475c7a4e/property-definitions",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.propertyType = 'TEXT';
data.name = 'First reported';
data.description = 'Time the issue was first reported';
data.helpText = 'Enter the time the issue was first reported in the format DD/MM/YYYY 23:00';
data.default = '2019-01-01T08:00:00Z';
data.maxLength = 30;
data.minLength = 0;
data.pattern = '\\d{4}\\-\\d{2}\\-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(Z)?';
data.validate = 'true'
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created plan property " + json.targetName + ". ID = "+ json.id);
}
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/8c37b146-6411-4e3c-ad3c-cb5c475c7a4e/property-definitions"
url = base_URL + endpoint_URL
payload = {
"propertyType": "TEXT",
"name": "First reported",
"description": "Time the issue was first reported",
"helpText": "Enter the time the issue was first reported in the format DD/MM/YYYY 23:00",
"default": "2019-01-01T08:00:00Z",
"maxLength": 30,
"minLength": 0,
"pattern": "\\d{4}\\-\\d{2}\\-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(Z)?",
"validate": true
}
response = requests.post(url, json=payload, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Created plan property.")
RESPONSE
{
"id": "8c37b146-6411-4e3c-a23b-cb5c475c9aw4",
"propertyType": "TEXT",
"name": "First reported",
"description": "Time the issue was first reported",
"helpText": "Enter the time the issue was first reported in the format DD/MM/YYYY 23:00",
"default": "2019-01-01T08:00:00Z",
"maxLength": 30,
"minLength": 0,
"pattern": "\\d{4}\\-\\d{2}\\-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(Z)?",
"validate": true,
"links": {
"self": "/api/xm/1/plans/8c37b146-6411-4e3c-ad3c-cb5c475c7a4e"
}
},
This endpoint allows you to add properties to your existing communication plans.
DEFINITION
POST /plans/{planId}/property-definitions
BODY PARAMETERS
Available property types include: Boolean, Hierarchy, Multi-select List, Single-select List, Number, Password, and Text. For definitions of the various properties and their required fields, see Plan Property Objects.
| planId | string |
| required | The unique ID of the communication plan. |
RESPONSES
| Success | Response code 201 Created and Plan property objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify plan properties
Modify plan properties
REQUEST - Modify or update a text property in a communication plan.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "4c37b889-26ee-1e3b-ad3c-cb5c475cb69f"
"propertyType": "TEXT",
"name": "First incident time",
"description": "The time of the first incident.",
"helpText": "Enter the time the issue was first reported in the format DD/MM/YYYY 23:00",
"default": "2019-01-01T08:00:00Z",
"maxLength": 30,
"minLength": 0,
"pattern": "\\d{4}\\-\\d{2}\\-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(Z)?",
"validate": true
}
' "https://acmeco.xmatters.com/api/xm/1/plans/8c37b146-6411-4e3c-ad3c-cb5c475c7a4e/property-definitions"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/8c37b146-6411-4e3c-ad3c-cb5c475c7a4e/property-definitions",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '4c37b889-26ee-1e3b-ad3c-cb5c475cb69f';
data.propertyType = 'TEXT';
data.name = 'First incident time';
data.description = 'The time of the first incident.';
data.helpText = 'Enter the time the issue was first reported in the format DD/MM/YYYY 23:00';
data.default = '2019-01-01T08:00:00Z';
data.maxLength = 30;
data.minLength = 0;
data.pattern = '\\d{4}\\-\\d{2}\\-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(Z)?';
data.validate = 'true'
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Modified plan property " + json.targetName + ". ID = "+ json.id);
}
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/8c37b146-6411-4e3c-ad3c-cb5c475c7a4e/property-definitions"
url = base_URL + endpoint_URL
payload = {
"id": "4c37b889-26ee-1e3b-ad3c-cb5c475cb69f",
"propertyType": "TEXT",
"name": "First incident time",
"description": "The time of the first incident.",
"helpText": "Enter the time the issue was first reported in the format DD/MM/YYYY 23:00",
"default": "2019-01-01T08:00:00Z",
"maxLength": 30,
"minLength": 0,
"pattern": "\\d{4}\\-\\d{2}\\-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(Z)?",
"validate": true
}
response = requests.post(url, json=payload, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Modified plan property.")
RESPONSE See Create Plan Properties for an example of the response object.
This endpoint allows you to modify existing properties in a existing communication plan. To find the id of a property in a plan, use Get plan properties.
DEFINITION
POST /plans/{planId}/property-definitions
URL PARAMETERS
| planId | string |
| The UUID of the plan you want to add the property to. To get the ID of a plan, use GET plans. |
BODY PARAMETERS
The required body parameters are the UUID and propertyType of the property you want to update. See the Plan Property Objects for each property's required fields.
| id | string |
| required | The unique ID of the property. |
| propertyType | string |
| required | The type of the property. Available property types are:
|
RESPONSES
| Success | Response code 200 Updated and a Plan property object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Plan property objects
The Property object is a base for specific types of properties, such as number and password.
When you retrieve properties, they contain the general Property object, then fields relevant to the specific type of property. The properties currently available for a communication plan are:
- Boolean object
- Hierarchy object: select a set of values from levels of dependent lists
- Multi-select List object: select multiple items from a list
- Single-select List object: select a single item from a list
- Number object
- Password object
- Text object
Property object
Property object
This example shows the fields in the general property object.
{
"id": "8c37b146-6411-4e3c-ad3c-cb5c475c7a4e",
"propertyType": "BOOLEAN",
"name": "Default_Name",
"description": "Time the issue was first reported",
"helpText": "Enter the time the issue was first reported in the format DD/MM/YYYY 23:00"
}
Defines the fields common to all properties.
| id | string |
The unique identifier (id) of the property. |
|
| propertyType | string |
The type of the property. Available property types are:
|
|
| name | string |
| The name of the property. | |
| description | string |
| Descriptive text providing information on the property. | |
| helpText | string |
| Text that appears with the property in the web user interface to help users understand how to set the property. |
Boolean object
Boolean object
{
"propertyType": "BOOLEAN",
"default": "false"
}
Defines the properties of a Boolean object.
| propertyType | string |
The type of the property: BOOLEAN |
|
| default | string |
The default value of the Boolean object when presented to the message sender. Valid values include: None, True, orFalse. |
Hierarchy object
Hierarchy object
{
"propertyType": "HIERARCHY",
"default": [
{
"value": "USA"
},
{
"value": "Washington"
},
{
"value": "Seattle"
}
],
"validate": false,
"delimiter": "|",
"categories": [
"Country",
"State",
"City"
],
"paths": [
[
{
"value": "USA"
},
{
"value": "Washington"
},
{
"value": "Seattle"
}
],
[
{
"value": "Canada"
},
{
"value": "Ontario"
},
{
"value": "Toronto"
}
],
]
}
}
Defines the properties of a hierarchy object.
| propertyType | string |
The type of the property: HIERARCHY |
|
| default | string |
| The values of the options that will appear in the category drop-down lists. | |
| delimiter | string |
| Sets the delimiter that is used to separate different levels in a hierarchy when editing the property in the web user interface. | |
| categories | array |
| Defines the categories or levels in a hierarchy. For example, a location hierarchy might have categories of country -> state -> city. | |
| paths | array |
| Each path item delineates one set of steps in the hierarchy. For example, a location hierarchy might have a one path set for Australia -> New South Wales -> Sydney and one for Australia -> Victoria -> Melbourne. For details, see Define a hierarchy property in the online help. |
Multi-line select object
Multi-select list object
{
"propertyType": "LIST_TEXT_MULTI_SELECT",
"items": [
"item 1",
"item 2",
"item 3",
"item 4",
"item 5"
]
}
Defines the properties of a list object where users can select multiple items from the list of available options.
| propertyType | string |
The type of the property: LIST_TEXT_MULTI_SELECT |
|
| items | array |
| Sets the values available for users in a list property. In this property, the user can select multiple items from the list of available options. |
Single-select list object
Single-select list object
{
,
"propertyType": "LIST_TEXT_SINGLE_SELECT",
"items": [
"item 1",
"item 2",
"item 3",
"item 4",
"item 5"
]
}
Defines the properties of a list object where users can select one item from the list of available options.
| propertyType | string |
The type of the property: LIST_TEXT_SINGLE_SELECT |
|
| items | array |
| Sets the values available for users in a list property. In this property, the user can only select one item from the list of available options. |
Number object
Number object
{
"propertyType": "NUMBER",
"name": "Number Field 1",
"default": "0",
"maxLength": 3000,
"minLength": 0,
"units": "m"
}
Defines the properties of a number object.
| propertyType | string |
The type of the property: NUMBER |
|
| default | string |
Default value of the property. This is the value used if another value is not specified when a message is sent. If validate is set to true, the default must conform to the pattern. |
|
| maxLength | number |
| Specifies the maximum number of characters that can be entered for a password, number, and text property type. | |
| minLength | number |
| Specifies the minimum number of characters that must be entered for a password, number, and text property type. | |
| units | string |
| The units a number property type is in (for example, GB, kg, BTU). This appears in the web user interface in parentheses beside the property name. |
Password object
Password object
{
"propertyType": "PASSWORD",
"maxLength": 30,
"minLength": 4,
"pattern": "^(?=.*\\d)(?=.*\\p{Alpha}).+",
"validate": true
}
Defines the properties of a password object.
| propertyType | string |
The type of the property: PASSWORD |
|
| maxLength | number |
| Specifies the maximum number of characters that can be entered for a password, number, and text property type. | |
| minLength | number |
| Specifies the minimum number of characters that must be entered for a password, number, and text property type. | |
| pattern | string |
Provides the pattern a text or password property is validated against, if validate is set to true. For example, for a date property, you might use "\d{4}\-\d{2}\-\d{2}T\d{2}:\d{2}(:\d{2})?(Z)?" to validate that dates are in ISO 8601 format. |
|
| validate | Boolean |
If true, specifies that the text or password property value is validated against a specified pattern. |
Text object
Text object
This example shows a text property with validation set to
true.
{
"propertyType": "TEXT",
"default": "2019-01-01T08:00:00Z",
"maxLength": 30,
"minLength": 0,
"pattern": "",
"validate": true
}
Defines the properties of a text object.
| propertyType | string |
The type of the property: TEXT |
|
| default | string |
Default value of the property. This is the value used if another value is not specified when a message is sent. If validate is set to true, the default must conform to the pattern. |
|
| maxLength | number |
| Specifies the maximum number of characters that can be entered for a password, number, and text property type. | |
| minLength | number |
| Specifies the minimum number of characters that must be entered for a password, number, and text property type. | |
| pattern | string |
Provides the pattern a text or password property is validated against, if validate is set to true. For example, for a date property, you might use "\d{4}\-\d{2}\-\d{2}T\d{2}:\d{2}(:\d{2})?(Z)?" to validate that dates are in ISO 8601 format. |
|
| validate | Boolean |
If true, specifies that the text property value is validated against a specified pattern. |
ROLES
Roles control how a user can interact with xMatters, including which features they can access. Roles determine whether a user can send notifications, manage other users, create workflows, configure xMatters, and more. See the online help for more information on roles.
Get roles
Get roles
REQUEST (get all the roles)
curl --user username "https://acmeco.xmatters.com/api/xm/1/roles"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/roles",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " roles" );
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/roles"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
REQUEST (get all roles with 'incident' in the name)
curl --user username
"https://acmeco.xmatters.com/api/xm/1/roles?name=*incident*&allowWildcards=true"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/roles?name=*incident*&allowWildcards=true",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " roles" );
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/roles?name=*incident*&allowWildcards=true"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"count":29,
"total":29,
"data":[
{
"id": "57ba7d3f-475c-4f05-a8e9-8eb7408e58c8",
"name": "Communication Center User",
"description": "Adds the ability to access and edit the Communication Center on the Home page."
},
{
"id": "10109bef-40cb-4871-af3b-0e84ced6050b",
"name": "Conference Bridge Supervisor",
"description": "Adds the ability to view, edit, delete, and manage ongoing conference bridges."
},
{
"id": "8fccc361-6d31-49e9-b008-671ee499e78f",
"name": "Developer",
"description": "User can act as a Person Supervisor and also maintain subscriptions, and manage phone recordings and Text-to-Speech (TTS) services."
},
{
...truncated list of roles objects...
}
],
"links":
{
"self":"/api/xm/1/roles?offset=0&limit=100"
}
}
Returns a paginated list of the roles that are visible to the authenticating user.
You can request a list of all roles or narrow the results by searching for the role name.
Use the allowWildcards query paramater and asterisks in the name (or names) to search for a partial match. For example, if your query is:
?name=*incident*&allowWildcards=true, the response includes any roles with 'incident' in the name;?name=*incident man*&allowWildcards=true, the response only includes 'incident manager' since that's the only role with those characters in the name;?name=*incident*,*manager*&allowWildcards=true, the response includes any roles with either incident or manager in the name.
DEFINITION
GET /roles
GET /roles?name={roleName}
GET /roles?name=*super*&allowWildcards=true
QUERY PARAMETERS
| name | string |
The name of the role to return. This is an exact match unless you use the allowWildcards parameter and add asterisks to the name (or names). |
|
| allowWildcards | Boolean |
Set to true to use wildcards (*) in the name. For example, set this to true and submit a request with name=*super* to return all roles with Supervisor in the name. |
|
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 Role objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Role objects
Role object
Role Object
This example shows a single role object.
{
"id":"9407eb2e-8eb2-43d9-88a8-875237af941d",
"name":"Incident Manager",
"description": "Adds the ability to access major incident workflows and associated events."
}
Describes a role in xMatters.
| id | string |
| The unique identifier of the role. | |
| name | string |
| The name of the role. | |
| description | string |
| A description of the functions the role can perform. |
SCENARIOS
The following methods let you retrieve, create, and update scenarios for plan forms.
For more information, see Scenarios in the online help.
Get scenarios
GET scenarios for all communication plan forms
REQUEST - Get all scenarios in your system
curl --user username "https://acmeco.xmatters.com/api/xm/1/scenarios"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/scenarios",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved" + json.count + " of " + json.total + " scenarios." );
for (var i in json.data)
{
console.log("Scenarios: " + json.data[i].name + ". Scenario ID: " + json.data[i].id);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
planId = "95fe8fbb-e095-4845-beb2-15d56829627b"
formId = "7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/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"])
+ " scenarios."
)
for rd in rjson["data"]:
print(
'Found scenario with name "' + rd["name"] + '" and 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": 3,
"total": 3,
"data": [
{
"id": "b9c3b4ce-f557-4955-92d9-2d20a1df103c",
"name": "Earthquake Evacuation Notice - Northwest United States",
"description": "Evacuation information for US locations in case of earthquake in the Northwest",
"plan": {
"id": "8cd46aa1-6fb9-42e8-a7c9-a581c1dae45c",
"name": "Evacuation Notifications"
},
"form": {
"id": "b5d6725d-f13e-4c30-9c2d-894b5e3215e1",
"name": "Earthquake Evacuation"
},
"position": 0,
"bypassPhoneIntro": false,
"escalationOverride": false,
"overrideDeviceRestrictions": false,
"requirePhonePassword": false,
"attachments": [],
"voicemailOptions": {
"retry": 2,
"every": 60
},
"created": "2019-03-26T20:44:08.222Z",
"links": {
"self": "/api/xm/1/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c"
}
},
{
"id": "577d8161-ec27-4f72-8bf8-df07182b10ce",
"name": "Earthquake Evacuation Notice - British Columbia, Canada",
"description": "Evacuation information for Canadian locations in case of earthquake in the Northwest",
"plan": {
"id": "8cd46aa1-6fb9-42e8-a7c9-a581c1dae45c",
"name": "Evacuation Notifications"
},
"form": {
"id": "b5d6725d-f13e-4c30-9c2d-894b5e3215e1",
"name": "Earthquate Evacuation"
},
"position": 1,
"bypassPhoneIntro": false,
"escalationOverride": false,
"overrideDeviceRestrictions": false,
"requirePhonePassword": false,
"voicemailOptions": {
"retry": 1,
"every": 60
},
"created": "2019-04-01T17:27:40.081Z",
"links": {
"self": "/api/xm/1/scenarios/577d8161-ec27-4f72-8bf8-df07182b10ce"
}
},
{
... truncated list of scenarios ...
}
],
"links": {
"self": "/api/xm/1/plans/8cd46aa1-6fb9-42e8-a7c9-a581c1dae45c/forms/b5d6725d-f13e-4c30-9c2d-894b5e3215e1/scenarios?offset=0&limit=100"
}
}
Returns a list of all scenarios in your system.
DEFINITION
GET /scenarios
GET /scenarios?enabledFor=MOBILE
GET /scenarios?search=Service Outage
GET /scenarios?search="Service Outage" "System Slowdown"&operand=AND
QUERY PARAMETERS
| search | string |
A list of search terms separated by the + sign or a space character. Searches are case-insensitive ("alert" finds "alert", "Alert", as well as "alerting") and must contain at least two characters. When two or more search terms are present, the result includes scenarios that match either search term. Use the operand parameter to expand or limit search results.When your search term contains more than one word, or contains delimiting characters such as spaces, enclose the terms in double quotes to preserve the delimiters. Example: /scenarios?search=system outage&operand=AND returns all scenarios that contain both "service" and "outage". However, searching /scenarios?search="service outage" returns all scenarios that contain "service outage". |
|
| operand | string |
Applied to the provided search terms to limit or expand the search query parameter. Available options include: AND or OR. AND only returns scenarios that have all search terms in the specified fields. OR returns scenarios that have any of the search terms in the specified fields; this is the default if you don’t specify an operand. The operand is case-sensitive; entering lowercase "and" will return an error. |
|
| enabledFor | string |
Returns all the scenarios that have forms enabled for a specific component. 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 Scenario objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a scenario
GET a scenario
REQUEST (get a scenario using its specific ID)
curl --user username "https://acmeco.xmatters.com/api/xm/1/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Scenario name: " + json.name + ".Scenario Id: " + json.id );
}
import requests
from requests.auth import HTTPBasicAuth
import json
scenarioId = "b9c3b4ce-f557-4955-92d9-2d20a1df103c"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/scenarios/" + scenarioId
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 scenario with name: "'
+ rjson["name"]
+ '", created on: '
+ rjson["created"]
)
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": "b9c3b4ce-f557-4955-92d9-2d20a1df103c",
"name": "Earthquake Evacuation Notice - Pacific Northwest",
"description": "Evacuation information for US locations in case of earthquake in the Northwest",
"plan": {
"id": "8cd46aa1-6fb9-42e8-a7c9-a581c1dae45c",
"name": "Weather Phenomenon"
},
"form": {
"id": "b5d6725d-f13e-4c30-9c2d-894b5e3215e1",
"name": "Earthquake Evacuation Notice"
},
"position": 0,
"bypassPhoneIntro": false,
"escalationOverride": false,
"overrideDeviceRestrictions": false,
"requirePhonePassword": false,
"attachments": {
"count": 2,
"total": 2,
"data": [
{
"name": "Earthquake Staff List",
"path": "/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c/attachments/Earthquake Staff List",
"size": 2644,
"links":
{
"self": "/api/xm/1/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c/attachments/Earthquake Staff List"
}
},
{
"name": "Evacuation checklist",
"path": "/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c/attachments/Evacuation checklist",
"size": 7521,
"links":
{
"self": "/api/xm/1/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c/attachments/Evacuation checklist"
}
}
],
},
"voicemailOptions": {
"retry": 1,
"every": 60
},
"created": "2019-03-26T20:44:08.222Z",
"links": {
"self": "/api/xm/1/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c"
}
},
Returns a scenario by its unique identifier.
DEFINITION
GET /scenarios/{scenarioId}
GET /scenarios/{scenarioId}?embed=properties,plan,form,properties.translations
URL PARAMETERS
| scenarioId | string |
| The unique identifier (uuid) of the scenario you want to retrieve. Names must be URL-encoded. Use Get scenarios to find the id of the scenario. |
QUERY PARAMETERS
| embed | string |
A comma-separated list of the objects to embed in the response.
|
RESPONSES
| Success | Response code 200 OK and a Scenario object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get scenarios in a form
GET scenarios for a communication plan form
REQUEST (get all scenarios for a specific communication plan form)
curl --user username "https://acmeco.xmatters.com/api/xm/1/plans/95fe8fbb-e095-4845-beb2-15d56829627b/forms/7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a/scenarios"
/**
* This script is configured to work with xMatters Flow Designer.
* 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/scenarios",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved" + json.count + " of " + json.total + " scenarios." );
for (var i in json.data)
{
console.log("Scenario: " + json.data[i].name + ". Scenario ID: " + json.data[i].id);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
planId = "95fe8fbb-e095-4845-beb2-15d56829627b"
formId = "7f6aa6f7-64d7-4ac3-a7f8-f2657c81eb0a"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/" + planId + "/forms/" + formId + "/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"])
+ " scenarios."
)
for rd in rjson["data"]:
print(
'Found scenario with name "' + rd["name"] + '" and 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": 3,
"total": 3,
"data": [
{
"id": "b9c3b4ce-f557-4955-92d9-2d20a1df103c",
"name": "Earthquake Evacuation Notice- Northwest United States",
"description": "Evacuation information for US locations in case of earthquake in the Northwest",
"plan": {
"id": "8cd46aa1-6fb9-42e8-a7c9-a581c1dae45c",
"name": "Evacuation Notifications"
},
"form": {
"id": "b5d6725d-f13e-4c30-9c2d-894b5e3215e1",
"name": "Earthquake Evacuation"
},
"position": 0,
"bypassPhoneIntro": false,
"escalationOverride": false,
"overrideDeviceRestrictions": false,
"requirePhonePassword": false,
"voicemailOptions": {
"retry": 2,
"every": 60
},
"created": "2019-03-26T20:44:08.222Z",
"links": {
"self": "/api/xm/1/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c"
}
},
{
"id": "577d8161-ec27-4f72-8bf8-df07182b10ce",
"name": "Earthquake Evacuation Notice - British Columbia, Canada",
"description": "Evacuation information for Canadian locations in case of earthquake in the Northwest",
"plan": {
"id": "8cd46aa1-6fb9-42e8-a7c9-a581c1dae45c",
"name": "Evacuation Notifications"
},
"form": {
"id": "b5d6725d-f13e-4c30-9c2d-894b5e3215e1",
"name": "Earthquate Evacuation"
},
"position": 1,
"bypassPhoneIntro": false,
"escalationOverride": false,
"overrideDeviceRestrictions": false,
"requirePhonePassword": false,
"voicemailOptions": {
"retry": 1,
"every": 60
},
"created": "2019-04-01T17:27:40.081Z",
"links": {
"self": "/api/xm/1/scenarios/577d8161-ec27-4f72-8bf8-df07182b10ce"
}
},
{
... truncated list of scenarios ...
}
],
"links": {
"self": "/api/xm/1/plans/8cd46aa1-6fb9-42e8-a7c9-a581c1dae45c/forms/b5d6725d-f13e-4c30-9c2d-894b5e3215e1/scenarios?offset=0&limit=100"
}
}
Returns a list of scenarios for a form in a communication plan.
DEFINITION
GET /plans/{planId}/forms/{formId}/scenarios
GET /plans/{planId}/forms/{formId}/scenarios?sortBy=USER_DEFINED&sortOrder=ASCENDING
GET /plans/{planId}/forms/{formId}/scenarios?embed=properties.translations
URL PARAMETERS
| planId | string |
| The unique identifier (uuid) or name (targetName) of the plan the scenario belongs to. Names must be URL-encoded. Use GET /plans to find the uuid of a communication plan. | |
| formId | string |
| The unique identifier (uuid) or name (targetName) of the form with the scenario you want to retrieve. Names must be URL-encoded. Use Get /forms to find the uuid of a form. |
QUERY PARAMETERS
| 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 subscription 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 Scenario objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a scenario attachment
Get a scenario attachment
REQUEST Get a scenario attachment
curl --user username "https://acmeco.xmatters.com/api/xm/1/scenarios/ced9fac9-1065-4659-82ab-1c9664a777b2/attachments/Company_Logo.jpg"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/scenarios/ced9fac9-1065-4659-82ab-1c9664a777b2/attachments/Company_Logo.jpg",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved attachment: " + json.eventId + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
scenarioId = "ced9fac9-1065-4659-82ab-1c9664a777b2"
attachmentId = "Company_Logo.jpg"
endpoint_URL = "/scenarios/" + scenarioId + "/attachments/" + attachmentId
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 attachment with id "'
+ rjson["scenarioId"]
+ '" 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
{
... a text represenation of a jpg file ...
}
Returns a single attachment for a specific scenario so that you can download it or view it. If the attachment is a text file, the contents of the file are displayed in the response. Other file types must be saved to your computer to be opened with the viewer of your choice.
DEFINITION
GET /scenarios/{scenarioId}/attachments/{attachmentId}
URL PARAMETERS
| scenarioId | string |
The unique identifier or id of the scenario. |
|
| attachmentId | string |
| The unique file name of the attached file. For example: "Mim_process_2.jpg", or "Customer Error Upload 1". |
RESPONSES
| Success | Response code 200 OK and the contents of the attachment in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Get scenario sender permissions
GET scenario sender permissions
REQUEST (get the scenario sender permissions for a single scenario)
curl --user username "https://acmeco.xmatters.com/api/xm/1/scenarios/4148d1d8-83ab-4f0e-b0b2-cf53cabdc4df/sender-permissions"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/scenarios/4148d1d8-83ab-4f0e-b0b2-cf53cabdc4df/sender-permissions",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved scenario sender permissions" + json.name + " with ID " + json.id + "." )
}
import requests
base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/scenarios/4148d1d8-83ab-4f0e-b0b2-cf53cabdc4df/sender-permissions'
url = base_URL + endpoint_URL
response = requests.get(url, auth=('username', 'password'))
if response.status_code == 200:
json = response.json()
print('Retrieved scenario sender permissions' + str(json['name']) + ' with ID ' + str(json['id']) + '.')
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"senderType": "PERSON",
"sender": {
"id": "ecfc7fa9-96df-4aba-a575-bf39ea8158e1",
"targetName": "bgull",
"firstName": "Barry",
"lastName": "Gull",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/ecfc7fa9-96df-4aba-a575-bf39ea8158e1"
}
},
"editScenarios": true
},
{
"senderType": "ROLE",
"sender": {
"id": "aef9d29d-bed4-3cb3-81df-4c8bc216330c",
"name": "Group Supervisor"
},
"editScenarios": false
}
],
"links": {
"self": "/api/xm/1/scenarios/4f9e90da-1034-4e5b-a71e-db0b67850867/sender-permissions?offset=0&limit=100"
}
}
Returns information on the users and roles who have permission to view and edit a scenario.
DEFINITION
GET /scenarios/{scenarioId}/sender-permissions
QUERY PARAMETERS
| id | string |
The unique identifier (id) of the scenario. Example: 6c96a506-a111-4f64-81ca-859b687dd61e |
RESPONSES
| Success | Response code 200 OK and a pagenation of scenario permissions objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a scenario
REQUEST - Create a scenario This request shows how to add a new scenario for a form.
curl --user username --header "Content-Type: application/json" --request POST -d
'{
"name": "APAC Network outage",
"description": "Notification of planned network outage - APAC",
"bypassPhoneIntro": false,
"escalationOverride": true,
"expirationInMinutes": 60,
"overrideDeviceRestrictions": false,
"requirePhonePassword": false,
"attachments": [
{"path": "attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/Planned_Outage.png"}
],
"priority": "LOW",
"senderOverrides": {
"displayName": "Antares support",
"callerId": "+18885552233"
},
"targetDeviceNames": [
{
"name": "Android phone"
},
{
"name": "iPhone"
}
],
"properties": {
"Summary": "Planned network outage impacting employees in the Antares organization",
"Start time": "2019-10-10T17:00:00Z",
"Assignment": [
{"category": "Organization", "value": "Antares"},
{"category": "Application", "value": "Network"},
{"category": "Region", "value": "APAC"}
],
"Event details": "A network outage is planned starting at the given time. Ensure you make the appropriate arrangements, and contact APAC support if there are any issues.",
"Services affected": ["Network", "Email"],
"Customer impacting": false
},
"permitted": [
{
"permissibleType": "PERSON",
"person": {
"id": "25dce2c3-defe-4610-8c55-4c6edbf50496"
},
"editor": false
},
{
"permissibleType": "ROLE",
"role": {
"name": "Scenario Administrator"
},
"editor": true
}
],
"recipients": [
{"id": "APAC employees", "recipientType": "GROUP"}
]
}'
"https://acmeco.xmatters.com/api/xm/1/forms/756a2021-7d79-4452-bac8-bdc287ca5c81/scenarios"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/{formId}
/scenarios",
"method": "POST"
});
var data = {};
data.name = 'APAC Network outage';
data.description = 'Notification of planned network outage - APAC';
data.bypassPhoneIntro = false;
data.escalationOverride = true;
data.expirationInMinutes = 60;
data.overrideDeviceRestrictions = false;
data.requirePhonePassword = false;
data.priority = "LOW";
var senderOverrides = {};
senderOverrides.displayName = 'Antares support';
senderOverrides.callerId = '+18885552233';
data.senderOverrides = senderOverrides;
var attachments = [];
attachments.push({"path": "attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/Planned_Outage.png"});
var targetDeviceNames = [];
targetDeviceNames.push(
{'name' : 'Android phone'}
);
targetDeviceNames.push(
{'name' : 'iPhone'}
);
data.targetDeviceNames = targetDeviceNames;
var properties = {};
properties.Summary = 'Planned network outage impacting employees in the Antares organization';
properties['Start time'] = '2019-10-10T17:00:00Z';
var assignment = [];
assignment.push(
{"category" : "Organization", "value" : "Antares"}
);
assignment.push(
{"category" : "Application", "value" : "Network"}
);
assignment.push(
{"category" : "Region", "value" : "APAC"}
);
properties.Assignment = assignment;
properties['Event details'] = 'A network outage is planned starting at the given time. Ensure you make the appropriate arrangements, and contact APAC support if there are any issues.';
properties['Services affected'] = ['Network', 'Email'];
properties['Customer impacting'] = false;
data.properties = properties;
var permitted = [];
permissions1 = {};
permissions1.permissibleType = "PERSON";
permissions1.person =
{ "id": "25dce2c3-defe-4610-8c55-4c6edbf50496" }
;
permissions1.editor = false;
permitted.push(permissions1);
permissions2 = {};
permissions2.permissibleType = "ROLE";
permissions2.role =
{ "name": "Scenario Administrator" }
;
permissions2.editor = true;
permitted.push(permissions2);
data.permitted = permitted;
var recipients = [];
recipients.push(
{'id' : 'APAC employees', 'recipientType': 'GROUP'}
);
data.recipients = recipients;
response = request.write(data);
if (response.statusCode == 201)
{ json = JSON.parse(response.body); console.log( "Created scenario" + response.json()["name"] + "with ID " + response.json()["id"]); }
else
{ console.log( "The request did not succeed. Response code is: " + response.statusCode) }
#The following code is formatted to work with Python v.3.6 and later.
import requests
from requests.auth import HTTPBasicAuth
base_url = "https://acmeco.xmatters.com/api/xm/1"
endpoint_url = "/forms/756a2021-7d79-4452-bac8-bdc287ca5c81/scenarios"
url = base_url + endpoint_url
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"name": "APAC Network outage",
"description": "Notification of planned network outage - APAC",
"bypassPhoneIntro": false,
"escalationOverride": true,
"expirationInMinutes": 60,
"overrideDeviceRestrictions": false,
"requirePhonePassword": false,
"priority": "LOW",
"senderOverrides": {"displayName": "Antares support", "callerId": "+18885552233"},
"targetDeviceNames": [{"name": "Android phone"}, {"name": "iPhone"}],
"attachments": [
{
"path": "attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/Planned_Outage.png",
}
],
"properties": {
"Summary": "Planned network outage impacting employees in the Antares organization",
"Start time": "2019-10-10T17:00:00Z",
"Assignment": [
{"category": "Organization", "value": "Antares"},
{"category": "Application", "value": "Network"},
{"category": "Region", "value": "APAC"},
],
"Event details": "A network outage is planned starting at the given time. Ensure you make the appropriate arrangements, and contact APAC support if there are any issues.",
"Services affected": ["Network", "Email"],
"Customer impacting": false,
},
"permitted": [
{
"permissibleType": "PERSON",
"person": {"id": "25dce2c3-defe-4610-8c55-4c6edbf50496"},
"editor": false,
},
{
"permissibleType": "ROLE",
"role": {"name": "Scenario Administrator"},
"editor": true,
},
],
"recipients": [{"id": "APAC employees", "recipientType": "GROUP"}],
}
response = requests.post(url, headers=headers, json=data, auth=auth)
response_code = response.status_code
if response_code == 201:
rjson = response.json()
print("Created scenario " + rjson.get("name") + "with ID " + rjson.get("name"))
else:
print("The request did not succeed. Response code is: " + str(response_code))
{
"id": "9c33b67c-5d42-45a0-9eb1-c1e4fc30f5cf",
"name": "APAC Network outage",
"description": "Notification of planned network outage - APAC",
"plan": {
"id": "b4660bcc-212a-45ff-98f4-35ff3b40b7d7",
"name": "IT Communications"
},
"form": {
"id": "e38593ad-4c7a-4237-a3f0-5368df49c7d0",
"name": "Stellar Support"
},
"priority": "LOW",
"position": 0,
"bypassPhoneIntro": false,
"escalationOverride": true,
"expirationInMinutes": 60,
"overrideDeviceRestrictions": false,
"requirePhonePassword": false,
"attachments": {
"count": 1,
"total": 1,
"data": {
"name": "Planned_Outage.png",
"path": "/scenarios/attachments/Planned_Outage.png",
"size": 2487,
"links": {
"self": "/api/xm/1/scenarios/attachments/Planned_Outage.png",
},
},
},
"senderOverrides": {
"displayName": "Antares support",
"callerId": "+18885552233"
},
"voicemailOptions": {
"retry": 1,
"every": 5,
"leave": "CONTENT"
},
"targetDeviceNames": {
"count": 2,
"total": 2,
"data": [
{
"deviceType": "ANDROID_PUSH",
"name": "Android phone"
},
{
"deviceType": "APPLE_PUSH",
"name": "iPhone"
}
]
},
"created": "2019-07-31T20:07:45.627Z",
"properties": {
"Summary": "Planned network outage impacting employees in the Antares organization",
"Start time": "2019-10-10T17:00:00Z",
"Assignment": [
{"category": "Organization", "value": "Antares"},
{"category": "Application", "value": "Network"},
{"category": "Region", "value": "APAC"}
],
...truncated list of properties...
},
"permitted": {
"count": 3,
"total": 3,
"data": [
{
"recipientId": "3bde07b6-22cd-42f7-ba58-40dbb6bbdf16",
"displayName": "Mary Mcbride (mmcbride)",
"person": {
"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"
}
},
"hasEditPermission": false,
"permissionType": "PERSON"
},
{...truncated list of Scenario Permissions objects...}
]
},
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "4dd79d53-342e-412e-9983-74ac970fab1f",
"targetName": "APAC Employees",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": true,
"useDefaultDevices": true,
"observedByAll": true,
"description": "APAC Employees",
"links": {
"self": "/api/xm/1/groups/4dd79d53-342e-412e-9983-74ac970fab1f"
},
"targeted": true
}
]
},
"links": {
"self": "/api/xm/1/scenarios/9c33b67c-5d42-45a0-9eb1-c1e4fc30f5cf"
}
}
This endpoint allows you to create scenarios for a form. Scenarios enable you to pre-populate settings and fields for a message. When the message is sent, these values can be changed by the message sender.
Any optional parameters not set in the scenario use the form defaults. You can set values for sections that are hidden or not included on the form in the web user interface; when the scenario is triggered, the values are ignored. If you later unhide or add the sections to the form, the scenario settings for those sections become active.
When creating a scenario, you can add up to 10 attachment files. The combined size of the attachments must not exceed 10 MB. For more information on uploading an attachment to xMatters for use with a scenario, see Upload an attachment.
To update a scenario, the authenticating user needs permission to manage scenarios for the form.
DEFINITION
POST /forms/{formId}/scenarios
URL PARAMETERS
| {formId} | string |
| The UUID of the form you want to add the scenario for. To get the ID of a form, use GET forms or GET a form in a plan. |
BODY PARAMETERS
| attachments | array [AttachmentReference object] |
The path to the xMatters temporary file storage facility where the file has been uploaded. You can attach a maximum of 10 files, and the size limit for all files is 10 MB. For a list of available file types, see Upload an attachment. |
|
| bypassPhoneIntro | Boolean |
When this value is set to true, xMatters omits the standard greeting and plays the message immediately. |
|
| description | string |
| The user-provided description to help users of your system know when to use the scenario. | |
| escalationOverride | Boolean |
When this value is set to true, xMatters ignores shift escalation delays and sends an immediate broadcast message to all recipients. |
|
| expirationInMinutes | integer |
| The number of minutes the event is active before it terminates. | |
| name | string |
| The user-provided name of the scenario. This name must be unique within the form. | |
| 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. |
|
| permitted | array [Scenario Permissions object] |
| Sets which users and roles can access the scenario on the Messaging tab in addition to the creator, and determines whether they can only use the scenario or if they can edit, rename, and save changes to it. If permitted is excluded from the request, only the creator has permissions to access and edit the scenario on the Messaging tab. To remove the creator, use Modify a scenario to resubmit the permitted object without the creator. |
|
| priority | string |
| The priority of the event created by the scenario: HIGH, MEDIUM, or LOW. | |
| properties | PropertyValues object |
| Set the values of the form properties, overriding any defaults configured in the form. | |
| recipients | array [RecipientTrigger object] |
| Specifies the people, devices, and groups that are directly targeted when this scenario is triggered. This replaces any default recipients configured on the form. | |
| 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. |
|
| senderOverrides | Sender Overrides object |
| Override sender information displayed in the notifications (for example, who it is from and the caller ID). | |
| targetDeviceNames | array [DeviceName object] |
Defines the devices that will be targeted by notifications from this scenario (for example, Home Email). |
|
| voicemailOptions | VoicemailOptions object |
| Voicemail Options settings configure the handling behavior for standard phone notifications and conference calls when voicemail is detected. |
RESPONSES
| Success | Response code 201 Created and a Scenario object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a scenario
REQUEST - Modify a scenario This request shows how to update the name and target devices of a scenario for a form.
curl --user username --header "Content-Type: application/json" --request POST -d
'{
"id": "9c33b67c-5d42-45a0-9eb1-c1e4fc30f5cf",
"name": "Asia-Pacific Network outage",
"targetDeviceNames": [{"name": "Work Email"}]
}'
"https://acmeco.xmatters.com/api/xm/1/forms/756a2021-7d79-4452-bac8-bdc287ca5c81/scenarios"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var data = {};
data.id = '9c33b67c-5d42-45a0-9eb1-c1e4fc30f5cf';
data.name = 'Asia-Pacific Network outage';
var targetDeviceNames = [];
targetDeviceNames.push( {'name' : 'Work Email'} );
data.targetDeviceNames = targetDeviceNames;
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/forms/{formId}/scenarios",
"method": "POST"
});
var response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Updated scenario" + response.json()["name"] + "with ID " + response.json()["id"]);
} else {
console.log( "The request did not succeed. Response code is: " + response.statusCode)
}
#The following code is formatted to work with Python v.3.6 and later.
import requests
from requests.auth import HTTPBasicAuth
base_url = "https://acmeco.xmatters.com/api/xm/1"
endpoint_url = "/forms/756a2021-7d79-4452-bac8-bdc287ca5c81/scenarios"
url = base_url + endpoint_url
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"id": "9c33b67c-5d42-45a0-9eb1-c1e4fc30f5cf",
"name": "Asia Pacific Network outage",
"targetDeviceNames": [{"name": "Work Email"}],
}
response = requests.post(url, headers=headers, json=data, auth=auth)
response_code = response.status_code
if response_code == 200:
rjson = response.json()
print("Updated scenario " + rjson.get("name") + "with ID " + rjson.get("name"))
else:
print("The request did not succeed. Response code is: " + str(response_code))
RESPONSE See Create a scenario for an example of the response object.
This endpoint lets you to update a scenario. Any parameters not included in the update retain their current values.
To update a scenario, the authenticating user needs permission to manage scenarios for the form.
DEFINITION
POST /forms/{formId}/scenarios
URL PARAMETERS
| {formId} | string |
| The UUID of the form you want to add the scenario for. To get the ID of a form, use GET forms or GET a form in a plan. |
BODY PARAMETERS
The only required body parameter is the UUID of the scenario you want to update. See the Create a scenario body parameters for details on the other parameters you can change.
To update a single item in any of the array parameters (targetedDeviceNames, permitted, and recipients), you need to include all of the current items in the array; any items not included are removed. For example, to change a user's editor permission to false, you need to include all other users and roles currently listed in the permitted parameter.
| id | string |
| The id (UUID) of the scenario you want to update. To get the ID of a scenario, use GET a scenario or GET a form's scenarios. |
RESPONSES
| Success | Response code 200 OK and a Scenario object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Upload attachment to a scenario
REQUEST - Upload attachment to a scenario This request shows how to upload a file and attach it to an existing scenario in your xMatters instance.
curl --user username --header "Content-Type: multi-part/form" --request POST -d '{
"file": "welcome_message.wav",
"fileName": "welcome_message.wav"
}' "https://acmeco.xmatters.com/api/xm/1/forms/756a2021-7d79-4452-bac8-bdc287ca5c81/scenarios/9c33b67c-5d42-45a0-9eb1-c1e4fc30f5cf/attachments"
/**
* As multi-part forms are not supported, this feature is not available in Flow Designer.
*/
```python
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/forms/756a2021-7d79-4452-bac8-bdc287ca5c81/scenarios/9c33b67c-5d42-45a0-9eb1-c1e4fc30f5cf/attachments"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "multi-part/form"}
data =
{
"file": "welcome_message.wav",
"fileName": "welcome_message.wav"
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print(
"Created attachment "
+ response.json()["name"]
+ ". Path = "
+ response.json()["path"]
)
else:
print("Error: Response code is: " + str(responseCode))
]
RESPONSE
{
"name": "welcome_message.wav",
"path": "/scenarios/9c33b67c-5d42-45a0-9eb1-c1e4fc30f5cf/attachments/welcome_message.wav",
"size": 21643,
"links": {
"self": "/api/xm/1/scenarios/9c33b67c-5d42-45a0-9eb1-c1e4fc30f5cf/attachments/welcome_message.wav"
}
}
This endpoint allows you to upload a file to use as an attachment to an existing scenario in your xMatters instance. It uploads the file to xMatters and attaches it directly to the specified scenario.
You can upload a file in any of the following formats:
- Images: BMP, GIF, ICO, JPEG, PNG, SVG+XML, TIFF
- Microsoft Office: DOC, DOCX, XLS, PPT
- Multimedia: MP3, MP4, WAV, MOV, AVI, WMV, MPG, MPEG
- Open Document: ODT, ODS, ODP, ODG
- Other: CSV, HTML, TXT, XML, PDF, ZIP, X-ZIP
The attachment size must not exceed 10 MB.
DEFINITION
POST /forms/{formId}/scenarios/{scenarioId}/attachments
URL PARAMETERS
| formId | string |
| The unique identifier (UUID) of the form that contains the scenario. To get the ID of a form, use GET forms or GET a form in a plan. | |
| scenarioId | string |
| The unique identifier (UUID) of the scenario the files should be attached to. Names must be URL-encoded. Use Get scenarios to find the id of the scenario. |
BODY PARAMETERS
| file | binary content |
| The file to upload to xMatters. | |
| fileName | string |
| A unique and descriptive name for the file. This can be the name of the file as it exists in your system already, or a new name for the file. |
RESPONSES
| Success | Response code 201 Created and an Attachments object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Set scenario sender permissions
REQUEST - Set scenario sender permissions Set the users or roles that can initiate and edit a scenario in your system.
curl --user username --header "Content-Type: application/json" --request PUT -d
'[
{
"senderType": "ROLE",
"sender": "87819792-382d-438d-ae58-4753a265fdb3",
"editScenarios": "true"
},
{
"senderType": "PERSON",
"sender": "dbe5f254-e85e-4368-8cfb-15d2609457e4",
"editScenarios": "false"
}
]'
"https://acmeco.xmatters.com/api/xm/1/scenarios/4f9e90da-1034-4e5b-a71e-db0b67850867/sender-permissions"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
const data = [
{
senderType: 'ROLE',
sender: '87819792-382d-438d-ae58-4753a265fdb3',
editScenarios: true
},
{
senderType: 'PERSON',
sender: 'dbe5f254-e85e-4368-8cfb-15d2609457e4',
editScenarios: 'false'
}
]
const apiRequest = http.request({
endpoint: 'xMatters',
path:
'/api/xm/1/scenarios/4f9e90da-1034-4e5b-a71e-db0b67850867/sender-permissions',
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
});
const apiResponse = apiRequest.write(data);
if (apiResponse.statusCode === 200) {
//As needed, parse the response for logging, assigning step output values, etc.,
}
#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 = '/scenarios/4f9e90da-1034-4e5b-a71e-db0b67850867/sender-permissions'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
data = [
{
"senderType": "ROLE",
"sender": {
"id": "87819792-382d-438d-ae58-4753a265fdb3"
},
"editScenarios" : "true",
},
{
"senderType": "PERSON",
"sender": {
"id": "dbe5f254-e85e-4368-8cfb-15d2609457e4"
},
"editScenarios": "false"
}
]
data_string = json.dumps(data)
response = requests.put(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if (responseCode == 200):
rjson = response.json();
print('Senders were granted permission. Response object is:\n')
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"senderType": "ROLE",
"sender": {
"id": "87819792-382d-438d-ae58-4753a265fdb3",
"name": "Company Supervisor"
},
"editScenarios": true
}
{
"senderType": "PERSON",
"sender": {
"id": "dbe5f254-e85e-4368-8cfb-15d2609457e4",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/14fdf697-08ed-479d-b44a-7051b0d86d56"
}
},
"editScenarios": false
},
],
"links": {
"self": "/api/xm/1/scenarios/4f9e90da-1034-4e5b-a71e-db0b67850867/sender-permissions?offset=0&limit=100"
}
}
This endpoint allows users with appropriate permission settings to set which users and roles can edit and initiate scenarios. The users and roles in the provided list overwrite all previously stored values.
DEFINITION
PUT /scenarios/{scenarioId}/sender-permissions
URL PARAMETERS
| scenarioId | string |
The unique identifier (id) of the scenario. Example: 6c96a506-a111-4f64-81ca-859b687dd61e |
BODY PARAMETERS
| senderType | string |
| Identifies whether the listed permissions apply to a single user or to all users with a specific role. Available values are: PERSON, ROLE. | |
| sender | string |
The unique identifier (id) or name (targetName) of the user or role. |
|
| editScenarios | Boolean |
Whether users can edit the scenario. The default value is false. |
RESPONSES
| Success | Response code 200 OK and a Scenario permissions object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Scenario objects
Scenario object
Scenario Object
{
"id": "b9c3b4ce-f557-4955-92d9-2d20a1df103c",
"name": "Earthquake Evacuation - Northwest United States",
"description": "Evacualtion Alerts for locations in the Northwest United States",
"plan": {
"id": "8cd46aa1-6fb9-42e8-a7c9-a581c1dae45c",
"name": "Evacuation Notifications"
},
"form": {
"id": "b5d6725d-f13e-4c30-9c2d-894b5e3215e1",
"name": "Earthquake Evacuation"
},
"priority": "MEDIUM",
"position": 0,
"bypassPhoneIntro": false,
"escalationOverride": false,
"expirationInMinutes": 4,
"overrideDeviceRestrictions": false,
"requirePhonePassword": false,
"attachments": {
"count": 2,
"total": 2,
"data": [
{
"name": "Earthquake Staff List",
"path": "/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c/attachments/Earthquake Staff List",
"links":
{
"self": "/api/xm/1/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c/attachments/Earthquake Staff List",
}
},
{
"name": "Evacuation checklist",
"path": "/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c/attachments/Evacuation checklist",
"links":
{
"self": "/api/xm/1/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c/attachments/Evacuation checklist"
}
}
],
},
"senderOverrides": {
"displayName": "mmcbride",
"callerId": "12123123"
},
"voicemailOptions": {
"retry": 2,
"every": 60,
"leave": "CALLBACK"
},
"targetDeviceNames": {
"count": 2,
"total": 2,
"data": [
{
"deviceType": "EMAIL",
"name": "Home Email",
"description": "Home Email Address"
},
{
"deviceType": "VOICE",
"name": "Home Phone",
"description": "Phone Number at Home"
}
],
"created": "2019-03-26T20:44:08.222Z",
"properties": {
"AlertName": "aleratao",
"Richter Scale Classification": ["3.0", "3.5", "4.0", "4.5" ]
},
"permitted": {
"count": 2,
"total": 2,
"data": [
{
"permissibleType": "PERSON",
"person": {
"id": "25dce2c3-defe-4610-8c55-4c6edbf50496",
"targetName": "aalbaf",
"firstName": "Aisha",
"lastName": "Albaf",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/25dce2c3-defe-4610-8c55-4c6edbf50496"
}
},
"editor": false
},
{
"permissibleType": "ROLE",
"role": {
"id": "393fb6b7-2d51-436b-9eec-621db703293e",
"name": "Scenario Administrator"
},
"editor": true
}
]
},
"recipients": {
"count": 2,
"total": 2,
"data": [
{
"id": "ab38da9d-2296-4669-b766-e0ea039dd153",
"targetName": "Northwest News Stations",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": true,
"useDefaultDevices": false,
"observedByAll": true,
"description": "A group of weather forecasters",
"links": {
"self": "/api/xm/1/groups/ab38da9d-2296-4669-b766-e0ea039dd153"
},
"targeted": true
},
{
"id": "6362ee92-4887-49a3-a6f7-0de1b98569fc",
"targetName": "msmith",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/6362ee92-4887-49a3-a6f7-0de1b98569fc"
},
"firstName": "Mike",
"lastName": "Smith",
"language": "en",
"timezone": "Canada/Pacific",
"webLogin": "msmith133",
"site": {
"id": "27e09caf-c078-4dd4-bc60-b7ecefc2a922",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/27e09caf-c078-4dd4-bc60-b7ecefc2a922"
}
},
"targeted": true,
"status": "ACTIVE"
}
]
},
"links": {
"self": "/api/xm/1/scenarios/b9c3b4ce-f557-4955-92d9-2d20a1df103c"
}
}
Describes the scenario used with a communication plan form.
| id | string |
The unique identifier (id) of the scenario. |
|
| name | string |
| The name of the scenario. | |
| description | string |
| The description of the scenario. | |
| plan | PlanReference object |
| The communication plan the form belongs to. | |
| form | FormReference object |
| The form to which scenarios are attached. | |
| priority | string |
The relative importance of the message. Options are:
|
|
| postion | integer |
| The scenario's position in the user interface. | |
| bypassPhoneIntro | Boolean |
| When enabled, greeting messages are not played during a phone notification. The default value is "false". | |
| escalationOverride | Boolean |
| When enabled, shift escalation schedules are ignored. The default value is "false". | |
| expirationInMinutes | integer |
The maximum time (in minutes) to send messages. For example, a situation requires a response within 30 minutes. Set the expirationInMinutes to 35 minutes so messages are not sent out after 30 minutes have elapsed. |
|
| overrideDeviceRestrictions | Boolean |
| When enabled, device timeframes and delays are ignored so messages are delivered as quickly as possible. The default value is "false". | |
| requirePhonePassword | Boolean |
| When enabled, call recipients must enter a password before messages are played. The default value is "false". | |
| attachments | AttachmentsReference objects |
| The files that were attached to the scenario. | |
| senderOverrides | Sender Overrides object |
| A list of notification override options configured for the form. | |
| voicemailOptions | VoicemailOptions object |
| Voicemail Options settings configure the handling behavior for standard phone notifications and conference calls when voicemail is detected. | |
| 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. | |
| created | string |
| The date and time the scenario was created. | |
| 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. |
|
| permitted | Scenario Permissions object |
| The permissions a user (PERSON) or role (ROLE) has to view or edit the scenario from the Messaging tab. | |
| recipients | Pagination of Recipient objects |
| The recipients of the event. This field contains only the first page of results (up to 100 recipients). | |
| links | SelfLink object |
| A link that can be used to access this scenario. |
Scenario permissions object
Scenario permissions object
"permitted": [
{
"permissibleType": "PERSON",
"person": {
"id": "25dce2c3-defe-4610-8c55-4c6edbf50496",
"targetName": "aalbaf",
"firstName": "Aisha",
"lastName": "Albaf",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/25dce2c3-defe-4610-8c55-4c6edbf50496"
},
"editor": false
}
},
{
"permissibleType": "ROLE",
"role": {
"id": "393fb6b7-2d51-436b-9eec-621db703293e",
"name": "Scenario Administrator"
},
"editor": true
}
]
Describes which users and roles can access the scenario on the Messaging tab and whether they can edit, rename and save changes to the scenario. See the online help for more information on scenario permissions.
| permissibleType | string |
For permissions associated with a user, permissibleType = PERSON. For permissions associated with a role, permissibleType = ROLE. |
|
| person | PersonReference object |
A reference to a person with permission to act on the scenario. When creating a scenario or modifying the permissions, you only need to include the id or targetName of the user you want to grant permission to. |
|
| role | Role object |
A reference to a role with permission to act on the scenario. When creating a scenario or modifying the permissions, you only need to include the id or name of the role you want to grant permission to. |
|
| editor | Boolean |
| Whether the user has permission to rename and save changes to the scenario in the Messaging tab. |
SCHEDULED MESSAGES
Scheduled messages are a way to send future notifications to users. For example, you can schedule a message to send the notification during off hours to a recipient in a different time zone. A scheduled message can be sent once or on a recurring basis.
For more information on scheduled messages, see Scheduled Messages in the online help.
Get scheduled messages
GET scheduled messages
REQUEST - Get all scheduled messages in your system
curl --user username
"https://acmeco.xmatters.com/api/xm/1/scheduled-messages"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/scheduled-messages",
"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 ) {
console.log(json.data[i].targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "scheduled-messages"
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"]))
for d in json["data"]:
print(d["targetName"])
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"id": "82220da3-52d4-4deb-aa3e-dfb71c8bedb6",
"name": "Holiday shift rotation",
"owner": {
"id": "ecfc7fa9-96df-4aba-a575-bf39ea8158e1",
"targetName": "mmcbride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/ecfc7fa9-96df-4aba-a575-bf39ea8158e1"
},
"firstName": "Mary",
"lastName": "McBride",
"status": "ACTIVE"
},
"event": {
"eventType": "USER",
"plan": {
"id": "5cb643e7-a6b8-4d78-bef8-5c9e64f90045",
"name": "Holiday rotation schedule",
"links": {
"self": "/api/xm/1/plans/5cb643e7-a6b8-4d78-bef8-5c9e64f90045"
}
},
"form": {
"id": "8cc0e258-8287-4d88-8b09-a69c4990a026",
"name": "Holiday shift schedule ",
"links": {
"self": "/api/xm/1/forms/8cc0e258-8287-4d88-8b09-a69c4990a026"
}
},
"floodControl": false,
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "cd7eecfd-ce55-4228-bf15-18ce490356c4",
"targetName": "Shift Supervisors",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/cd7eecfd-ce55-4228-bf15-18ce490356c4"
}
}
]
},
"priority": "MEDIUM",
"expirationInMinutes": 180,
"overrideDeviceRestrictions": false,
"escalationOverride": false,
"bypassPhoneIntro": false,
"requirePhonePassword": false,
"voicemailOptions": {
"retry": 0,
"every": 60,
"leave": "callbackonly"
},
"created": "2021-09-30T18:35:56.652+0000",
"status": "ACTIVE",
"responseCountsEnabled": false,
"properties": {
"Is the schedule changing?": true,
"Have workers been notified yet?": false
}
},
"recurrence": {
"frequency": "ONCE",
"startTime": "2021-09-30T18:41:00.000Z"
},
"previousFireTime": "2021-09-30T18:41:00.045Z",
"links": {
"self": "/api/xm/1/scheduled-messages/82220da3-52d4-4deb-aa3e-dfb71c8bedb6"
}
},
},
{
"id": "bc68d5bc-9316-4775-a83f-d5d6e5df55b9",
"name": "Antares Gate service monitoring",
"owner": {
"id": "ecfc7fa9-96df-4aba-a575-bf39ea8158e1",
"targetName": "bgull",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/ecfc7fa9-96df-4aba-a575-bf39ea8158e1"
},
"firstName": "Barry",
"lastName": "Gull",
"status": "ACTIVE"
},
"event": {
"plan": {
"id": "d965e0c9-5958-4b44-9def-8662f623c9da",
"name": "Antares Gate service monitoring",
"links": {
"self": "/api/xm/1/plans/d965e0c9-5958-4b44-9def-8662f623c9da"
}
},
"form": {
"id": "08c68d25-17bb-4c5e-bb35-e1587dcaf562",
"name": "Send Alert",
"links": {
"self": "/api/xm/1/forms/08c68d25-17bb-4c5e-bb35-e1587dcaf562"
}
},
"floodControl": false,
"recipients": {
"count": 2,
"total": 2,
"data": [
{
"id": "87819792-382d-438d-ae58-4753a265fdb3",
"targetName": "akaur",
"firstName": "Aarohi",
"lastName": "Kaur",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/87819792-382d-438d-ae58-4753a265fdb3"
}
},
{
"id": "21ec867f-2b3d-46f1-be14-81de786e1723",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/21ec867f-2b3d-46f1-be14-81de786e1723"
}
}
]
},
"priority": "MEDIUM",
"expirationInMinutes": 60,
"overrideDeviceRestrictions": false,
"escalationOverride": false,
"bypassPhoneIntro": false,
"requirePhonePassword": false,
"voicemailOptions": {
"retry": 0,
"every": 60,
"leave": "callbackonly"
},
"responseOptions": {
"count": 3,
"total": 3,
"data": [
{
"id": "badcd2a8-06dc-40d8-b3f7-65cc3627db71",
"number": 1,
"text": "Acknowledge",
"description": "Acknowledge the alert and stop notifying other recipients",
"prompt": "Acknowledge",
"action": "ASSIGN_TO_USER",
"contribution": "POSITIVE",
"order": 0,
"joinConference": false,
"redirectUrl": "",
"allowComments": true,
"translations": {
"count": 1,
"total": 1,
"data": [
{
"id": "16874dcb-e216-4ded-aa29-3a0f2749a799",
"language": "en",
"text": "Acknowledge",
"prompt": "Acknowledge",
"description": "Acknowledge the alert and stop notifying other recipients"
}
]
}
},
{
"id": "ed663715-4975-43dd-8fe0-4546fed4719b",
"number": 2,
"text": "Close",
"description": "Stop notifying other recipients and terminate the event",
"prompt": "Close",
"action": "END",
"contribution": "POSITIVE",
"order": 1,
"joinConference": false,
"redirectUrl": "",
"allowComments": true,
"translations": {
"count": 1,
"total": 1,
"data": [
{
"id": "a8cb3b17-eb4c-467b-b54d-a9324849e148",
"language": "en",
"text": "Close",
"prompt": "Close",
"description": "Stop notifying other recipients and terminate the event"
}
]
}
},
{
"id": "889433b2-89be-4ea0-9567-8374a1100fef",
"number": 3,
"text": "Escalate",
"description": "Immediately notify the next recipient in the escalation",
"prompt": "Escalate",
"action": "ESCALATE",
"contribution": "NEGATIVE",
"order": 2,
"joinConference": false,
"redirectUrl": "",
"allowComments": true,
"translations": {
"count": 1,
"total": 1,
"data": [
{
"id": "05b3d795-db79-4463-9d82-781c37f42b48",
"language": "en",
"text": "Escalate",
"prompt": "Escalate",
"description": "Immediately notify the next recipient in the escalation"
}
]
}
}
]
},
"created": "2021-12-01T21:25:19.745+0000",
"status": "ACTIVE",
"responseCountsEnabled": false,
"properties": {
"Message#en": "Antares Gate requires a special service time.",
"Summary#en": "Check your time zone to ensure service is performed on time."
}
},
"recurrence": {
"end": {
"endBy": "DATE",
"date": "2021-12-29T16:00:59.000Z"
},
"onDays": [
"MO"
],
"frequency": "WEEKLY",
"startTime": "2021-12-06T16:00:00.000Z"
},
"nextFireTime": "2021-12-06T16:00:00.000Z",
"links": {
"self": "/api/xm/1/scheduled-messages/bc68d5bc-9316-4775-a83f-d5d6e5df55b9"
}
}
],
"links": {
"self": "/api/xm/1/scheduled-messages?offset=0&limit=100"
}
Returns a list of scheduled messages in your system.
DEFINITION
GET /scheduled-messages
GET /scheduled-messages?search=service maintenance
GET /scheduled-messages?search="service maintenance"
GET /scheduled-messages?sortBy=OWNER&sortOrder=DESCENDING
QUERY PARAMETERS
| search | string |
| A list of search terms separated by the + sign or a space character. Searches are case-insensitive ("alert" finds "alert", "Alert", as well as "alerting") and must contain at least two characters. When two or more search terms are present, the result includes scheduled messages that match either search term. When your search term contains more than one word, or contains delimiting characters such as spaces, enclose the terms in double quotes to preserve the delimiters. Example: /scheduled-messages?search=service maintenance returns all scheduled messages that contain either "service" or "maintenance". However, searching /scheduled-messages?search="service maintenance" returns all scheduled messages that contain "service maintenance". |
|
| 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:
|
RESPONSES
| Success | Response code 200 OK and a Pagination of Scheduled Messages objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a scheduled message
GET a scheduled message
REQUEST - Get a single scheduled messages using its unique identifier
curl --user username
"https://acmeco.xmatters.com/api/xm/1/scheduled-messages/82220da3-52d4-4deb-aa3e-dfb71c8bedb6"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/scheduled-messages/82220da3-52d4-4deb-aa3e-dfb71c8bedb6",
"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 ) {
console.log(json.data[i].targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "scheduled-messages/82220da3-52d4-4deb-aa3e-dfb71c8bedb6"
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"]))
for d in json["data"]:
print(d["targetName"])
RESPONSE
{
"id": "82220da3-52d4-4deb-aa3e-dfb71c8bedb6",
"name": "Holiday shift rotation",
"owner": {
"id": "ecfc7fa9-96df-4aba-a575-bf39ea8158e1",
"targetName": "mmcbride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/ecfc7fa9-96df-4aba-a575-bf39ea8158e1"
},
"firstName": "Mary",
"lastName": "McBride",
"status": "ACTIVE"
},
"event": {
"eventType": "USER",
"plan": {
"id": "5cb643e7-a6b8-4d78-bef8-5c9e64f90045",
"name": "Holiday rotation schedule",
"links": {
"self": "/api/xm/1/plans/5cb643e7-a6b8-4d78-bef8-5c9e64f90045"
}
},
"form": {
"id": "8cc0e258-8287-4d88-8b09-a69c4990a026",
"name": "Holiday shift schedule ",
"links": {
"self": "/api/xm/1/forms/8cc0e258-8287-4d88-8b09-a69c4990a026"
}
},
"floodControl": false,
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "cd7eecfd-ce55-4228-bf15-18ce490356c4",
"targetName": "Shift Supervisors",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/cd7eecfd-ce55-4228-bf15-18ce490356c4"
}
}
]
},
"priority": "MEDIUM",
"expirationInMinutes": 180,
"overrideDeviceRestrictions": false,
"escalationOverride": false,
"bypassPhoneIntro": false,
"requirePhonePassword": false,
"voicemailOptions": {
"retry": 0,
"every": 60,
"leave": "callbackonly"
},
"created": "2021-09-30T18:35:56.652+0000",
"status": "ACTIVE",
"responseCountsEnabled": false,
"properties": {
"Is the schedule changing?": true,
"Have workers been notified yet?": false
}
},
"attachments": {
"count": 1,
"total": 1,
"data": [
{
"name": "Break Rotation.jpg",
"path": "/scheduled-messages/b9c3b4ce-f557-4955-92d9-2d20a1df103c/attachments/Break Rotation.jpg",
"size": 2644,
"links":
{
"self": "/api/xm/1/scheduled-messages/b9c3b4ce-f557-4955-92d9-2d20a1df103c/attachments/Break Rotation.jpg"
},
}
],
},
"recurrence": {
"frequency": "ONCE",
"startTime": "2021-09-30T18:41:00.000Z"
},
"previousFireTime": "2021-09-30T18:41:00.045Z",
}
}
Returns a single scheduled message in your system.
DEFINITION
GET /scheduled-messages/{scheduledMessageId}
URL PARAMETERS
| scheduledMessageId | string |
| The unique identifier (or UUID) of a scheduled message in xMatters. For example: ab1d6091-7d58-41e2-af72-49c69b3d9b65. |
RESPONSES
| Success | Response code 200 OK and a Scheduled Message object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a scheduled message attachment
Get a scheduled message attachment
REQUEST Get a scheduled message attachment
curl --user username "https://acmeco.xmatters.com/api/xm/1/scheduled-messages/ced9fac9-1065-4659-82ab-1c9664a777b2/attachments/Company_Logo.jpg"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/scheduled-messages/ced9fac9-1065-4659-82ab-1c9664a777b2/attachments/Company_Logo.jpg",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved attachment: " + json.eventId + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
scheduledMessageId = "ced9fac9-1065-4659-82ab-1c9664a777b2"
attachmentId = "Company_Logo.jpg"
endpoint_URL = "/scheduled-messages/" + scheduledMessageId + "/attachments/" + attachmentId
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 attachment with id "'
+ rjson["scheduledMessageId"]
+ '" 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
{
... a text represenation of a jpg file ...
}
Returns a single attachment for a specific scheduled message so that you can download it or view it. If the attachment is a text file, the contents of the file are displayed in the response. Other file types must be saved to your computer to be opened with the viewer of your choice.
DEFINITION
GET /scheduled-messages/{scheduledMessageId}/attachments/{attachmentId}
URL PARAMETERS
| scheduledMessageId | string |
The unique identifier or id of the scheduled message. |
|
| attachmentId | string |
| The unique file name of the attached file. For example: "Mim_process_2.jpg", or "Customer Error Upload 1". |
RESPONSES
| Success | Response code 200 OK and the contents of the attachment in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes |
Create a scheduled message
Create a scheduled message
REQUEST - Create a single scheduled message
curl --user username --header "Content-Type: application/json" --request POST -d '{
"name": "Server Maintenence Outage",
"event": {
"plan": {
"id": "8af8ca58-8a55-46cc-bb05-d3b4a9741965"
},
"form": {
"id": "7767fc7c-59f7-4b8c-b93c-6a359f585047"
},
"recipients": [
{"id": "Shift Supervisors", "recipientType": "GROUP"}
],
"attachments": [
{"path": "attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/Planned_Outage.png"}
],
"properties": {
"myTextProperty": {
"value": "This is urgent. Please respond."
},
"myNumberProperty": 22183
}
},
"recurrence": {
"frequency": "ONCE",
"startTime": "2021-11-16T21:25:00.000Z"
}
}' "https://acmeco.xmatters.com/api/xm/1/scheduled-messages"
/**
* This script is configured to work within the xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/scheduled-messages",
"method": "POST"
});
var data = {};
data.name = "Server Maintenence Outage";
var event = {};
var plan = {};
plan.id = "8af8ca58-8a55-46cc-bb05-d3b4a9741965";
var form = {};
form.id = "7767fc7c-59f7-4b8c-b93c-6a359f585047";
var recipients = [];
recipients.push({"id": "Shift Supervisors", "recipientType": "GROUP"});
var properties ={};
properties.myTextProperty = "This is urgent. Please respond.";
properties.myNumberProperty = 22183;
var attachments = [];
attachments.push({"path": "attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/Planned_Outage.png"});
event.plan = plan;
event.form = form;
event.recipients = recipients;
event.attachments = attachments;
var recurrence = {};
recurrence.frequency = "ONCE";
recurrence.startTime = "2021-11-16T22:00:00.000Z";
data.event = event;
data.recurrence = recurrence;
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body); console.log( "Created scheduled message" + json["name"] + "with ID " + json["id"]);
} else {
console.log( "The request did not succeed. Response code is: " + response.statusCode)
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/scheduled-messages"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"name": "Server Maintenence Outage",
"event": {
"plan": {
"id": "8af8ca58-8a55-46cc-bb05-d3b4a9741965"
},
"form": {
"id": "7767fc7c-59f7-4b8c-b93c-6a359f585047"
},
"recipients": [
{
"id": "Shift Supervisors",
"recipientType": "GROUP"
}
],
"properties": {
"myTextProperty": {
"value": "This is urgent. Please respond."
},
"myNumberProperty": 22183
},
"attachments": [
{
"path": "attachments/18a2e807-6466-471e-a378-4c6e5bb5bccb/Planned_Outage.png"
}
]
},
"recurrence": {
"frequency": "ONCE",
"startTime": "2021-09-30T18:41:00.000Z"
}
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print ("Created " + response.json()["targetName"] + ". id = " + response.json()[
"id")
]
RESPONSE
{
"id": "82220da3-52d4-4deb-aa3e-dfb71c8bedb6",
"name": "Server Maintenence Outage",
"owner": {
"id": "ecfc7fa9-96df-4aba-a575-bf39ea8158e1",
"targetName": "mmcbride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/ecfc7fa9-96df-4aba-a575-bf39ea8158e1"
},
"firstName": "Mary",
"lastName": "McBride",
"status": "ACTIVE"
},
"event": {
"eventType": "USER",
"plan": {
"id": "5cb643e7-a6b8-4d78-bef8-5c9e64f90045",
"name": "Holiday maintenence schedule",
"links": {
"self": "/api/xm/1/plans/5cb643e7-a6b8-4d78-bef8-5c9e64f90045"
}
},
"form": {
"id": "8cc0e258-8287-4d88-8b09-a69c4990a026",
"name": "Holiday server maintencence schedule ",
"links": {
"self": "/api/xm/1/forms/8cc0e258-8287-4d88-8b09-a69c4990a026"
}
},
"floodControl": false,
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "cd7eecfd-ce55-4228-bf15-18ce490356c4",
"targetName": "Shift Supervisors",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/cd7eecfd-ce55-4228-bf15-18ce490356c4"
}
}
]
},
"properties": {
"myTextProperty": {
"value": "This is urgent. Please respond."
},
"myNumberProperty": 22183
},
"priority": "MEDIUM",
"expirationInMinutes": 180,
"overrideDeviceRestrictions": false,
"escalationOverride": false,
"bypassPhoneIntro": false,
"requirePhonePassword": false,
"voicemailOptions": {
"retry": 0,
"every": 60,
"leave": "callbackonly"
},
"attachments": [
{
"count": 1,
"total": 1,
"data": {
"name": "Planned_Outage.png",
"path": "/scheduled-messages/attachments/Planned_Outage.png",
"size": 2487,
"links": {
"self": "/api/xm/1/scheduled-messages/attachments/Planned_Outage.png",
},
},
}
],
"created": "2021-09-30T18:35:56.652+0000",
"status": "ACTIVE",
"responseCountsEnabled": false,
},
"recurrence": {
"frequency": "ONCE",
"startTime": "2021-09-30T18:41:00.000Z"
},
}
Creates a scheduled message based on an existing communication plan and form to be sent to recipients at a future date and time. When the scheduled message is sent, it creates an event in xMatters and notifies the specified recipients.
When creating a scheduled message, you can add up to 10 attachment files. The combined size of the attachments must not exceed 10 MB. For more information on uploading an attachment to xMatters for use with a scheduled message, see Upload an attachment.
DEFINITION
POST /scheduled-messages
BODY PARAMETERS
| name | string |
| A unique name for the scheduled event, up to a maximum of 250 characters. | |
| event | Event Object |
| A description of the xMatters event that will be created when the scheduled message is sent. | |
| attachments | array [AttachmentReference object] |
The path to the xMatters temporary file storage facility where the file has been uploaded. You can attach a maximum of 10 files, and the size limit for all files is 10 MB. For a list of available file types, see Upload an attachment. |
|
| recurrence | MessageRecurrence object |
| A description of how often the message should be sent to the list of targeted recipients. |
RESPONSES
| Success | Response code 201 Created and a Scheduled Message object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a scheduled message
Modify a scheduled message
REQUEST - Modify an existing scheduled message in your system
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "82220da3-52d4-4deb-aa3e-dfb71c8bedb6",
"name": "Server Maintenence Outage",
"event": {
"plan": {
"id": "8af8ca58-8a55-46cc-bb05-d3b4a9741965"
},
"form": {
"id": "7767fc7c-59f7-4b8c-b93c-6a359f585047"
},
"recipients": [
{"id": "Shift Supervisors", "recipientType": "GROUP"}
]
},
"recurrence": {
"frequency": "ONCE",
"startTime": "2021-11-16T21:25:00.000Z"
}
}' "https://acmeco.xmatters.com/api/xm/1/scheduled-messages"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/scheduled-messages",
"method": "POST"
});
var data = {};
data.id = "82220da3-52d4-4deb-aa3e-dfb71c8bedb6";
data.name = "Server Maintenence Outage";
var event = {};
var plan = {};
plan.id = "8af8ca58-8a55-46cc-bb05-d3b4a9741965";
var form = {};
form.id = "7767fc7c-59f7-4b8c-b93c-6a359f585047";
var recipients = [];
recipients.push({"id": "Shift Supervisors", "recipientType": "GROUP"});
event.plan = plan;
event.form = form;
event.recipients = recipients;
var recurrence = {};
recurrence.frequency = "ONCE";
recurrence.startTime = "2021-11-16T22:00:00.000Z";
data.event = event;
data.recurrence = recurrence;
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body); console.log( "Created scheduled mesage" + json["name"] + "with ID " + json["id"]);
} else {
console.log( "The request did not succeed. Response code is: " + response.statusCode)
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/scheduled-messages"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"id": "82220da3-52d4-4deb-aa3e-dfb71c8bedb6",
"name": {Server Maintenence Outage},
"plan": {
"id": "8af8ca58-8a55-46cc-bb05-d3b4a9741965"
},
"form": {
"id": "7767fc7c-59f7-4b8c-b93c-6a359f585047"
},
"recipients": {
"targetName": "Shift Supervisors",
"recipientType": "GROUP"
},
"recurrence": {
"frequency": "ONCE",
"startTime": "2021-09-30T18:41:00.000Z"
}
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print ("Created " + response.json()["targetName"] + ". id = " + response.json()[
"id")
]
RESPONSE
{
"id": "82220da3-52d4-4deb-aa3e-dfb71c8bedb6",
"name": "Server Maintenence Outage",
"owner": {
"id": "ecfc7fa9-96df-4aba-a575-bf39ea8158e1",
"targetName": "mmcbride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/ecfc7fa9-96df-4aba-a575-bf39ea8158e1"
},
"firstName": "Mary",
"lastName": "McBride",
"status": "ACTIVE"
},
"event": {
"eventType": "USER",
"plan": {
"id": "5cb643e7-a6b8-4d78-bef8-5c9e64f90045",
"name": "Holiday maintenence schedule",
"links": {
"self": "/api/xm/1/plans/5cb643e7-a6b8-4d78-bef8-5c9e64f90045"
}
},
"form": {
"id": "8cc0e258-8287-4d88-8b09-a69c4990a026",
"name": "Holiday server maintencence schedule ",
"links": {
"self": "/api/xm/1/forms/8cc0e258-8287-4d88-8b09-a69c4990a026"
}
},
"floodControl": false,
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "cd7eecfd-ce55-4228-bf15-18ce490356c4",
"targetName": "Shift Supervisors",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/cd7eecfd-ce55-4228-bf15-18ce490356c4"
}
}
]
},
"priority": "MEDIUM",
"expirationInMinutes": 180,
"overrideDeviceRestrictions": false,
"escalationOverride": false,
"bypassPhoneIntro": false,
"requirePhonePassword": false,
"voicemailOptions": {
"retry": 0,
"every": 60,
"leave": "callbackonly"
},
"created": "2021-09-30T18:35:56.652+0000",
"status": "ACTIVE",
"responseCountsEnabled": false,
"properties": {
"Is the schedule changing?": true,
"Have workers been notified yet?": false
}
},
"attachments": {
"count": 1,
"total": 1,
"data": [
{
"name": "Break Rotation.jpg",
"path": "/scheduled-messages/b9c3b4ce-f557-4955-92d9-2d20a1df103c/attachments/Break Rotation.jpg",
"size": 2644,
"links":
{
"self": "/api/xm/1/scheduled-messages/b9c3b4ce-f557-4955-92d9-2d20a1df103c/attachments/Break Rotation.jpg"
},
}
],
},
"recurrence": {
"frequency": "ONCE",
"startTime": "2021-09-30T18:41:00.000Z"
}
}
}
Changes the properties of an existing scheduled message.
DEFINITION
POST /scheduled-messages
BODY PARAMETERS
The only required body parameter is the UUID of the scheduled message you want to update. See the Create scheduled messages for details on the other available parameters.
| id | string |
| The unique identifier of the scheduled message. |
RESPONSES
| Success | Response code 200 OK and a Scheduled Message object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a scheduled message
Delete a scheduled message
REQUEST - Delete a scheduled message using its unique identifier before it is sent
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/scheduled-messages/82220da3-52d4-4deb-aa3e-dfb71c8bedb6"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/scheduled-messages/82220da3-52d4-4deb-aa3e-dfb71c8bedb6",
"method": "DELETE",
"headers" : {"Content-Type": "application/json"}
});
response = request.write();
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the : " + json.targetName);
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/scheduled-messages/82220da3-52d4-4deb-aa3e-dfb71c8bedb6"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.delete(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
print ("Deleted " + response.json()["targetName"])
RESPONSE
{
"id": "82220da3-52d4-4deb-aa3e-dfb71c8bedb6",
"name": "Holiday shift rotation",
"owner": {
"id": "ecfc7fa9-96df-4aba-a575-bf39ea8158e1",
"targetName": "mmcbride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/ecfc7fa9-96df-4aba-a575-bf39ea8158e1"
},
"firstName": "Mary",
"lastName": "McBride",
"status": "ACTIVE"
},
"event": {
"eventType": "USER",
"plan": {
"id": "5cb643e7-a6b8-4d78-bef8-5c9e64f90045",
"name": "Holiday rotation schedule",
"links": {
"self": "/api/xm/1/plans/5cb643e7-a6b8-4d78-bef8-5c9e64f90045"
}
},
"form": {
"id": "8cc0e258-8287-4d88-8b09-a69c4990a026",
"name": "Holiday shift schedule ",
"links": {
"self": "/api/xm/1/forms/8cc0e258-8287-4d88-8b09-a69c4990a026"
}
},
"floodControl": false,
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "cd7eecfd-ce55-4228-bf15-18ce490356c4",
"targetName": "Shift Supervisors",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/cd7eecfd-ce55-4228-bf15-18ce490356c4"
}
}
]
},
"priority": "MEDIUM",
"expirationInMinutes": 180,
"overrideDeviceRestrictions": false,
"escalationOverride": false,
"bypassPhoneIntro": false,
"requirePhonePassword": false,
"voicemailOptions": {
"retry": 0,
"every": 60,
"leave": "callbackonly"
},
"created": "2021-09-30T18:35:56.652+0000",
"status": "ACTIVE",
"responseCountsEnabled": false,
"properties": {
"Is the schedule changing?": true,
"Have workers been notified yet?": false
}
},
"recurrence": {
"frequency": "ONCE",
"startTime": "2021-09-30T18:41:00.000Z"
},
"previousFireTime": "2021-09-30T18:41:00.045Z",
}
}
Deletes a scheduled message before it is sent to the list of recipients.
DEFINITION
DELETE /scheduled-messages/{scheduledMessageId}
URL PARAMETERS
| scheduledMessageId | string |
| The unique identifier (or UUID) of a scheduled message in xMatters. For example: ab1d6091-7d58-41e2-af72-49c69b3d9b65. |
RESPONSES
| Success | Response code 200 OK and a Scheduled Message object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Scheduled Message objects
Scheduled Message object
Scheduled Message Object
{
"id": "82220da3-52d4-4deb-aa3e-dfb71c8bedb6",
"name": "Holiday shift rotation",
"owner": {
"id": "ecfc7fa9-96df-4aba-a575-bf39ea8158e1",
"targetName": "mmcbride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/ecfc7fa9-96df-4aba-a575-bf39ea8158e1"
},
"firstName": "Mary",
"lastName": "McBride",
"status": "ACTIVE"
},
"event": {
"eventType": "USER",
"plan": {
"id": "5cb643e7-a6b8-4d78-bef8-5c9e64f90045",
"name": "Holiday rotation schedule",
"links": {
"self": "/api/xm/1/plans/5cb643e7-a6b8-4d78-bef8-5c9e64f90045"
}
},
"form": {
"id": "8cc0e258-8287-4d88-8b09-a69c4990a026",
"name": "Holiday shift schedule ",
"links": {
"self": "/api/xm/1/forms/8cc0e258-8287-4d88-8b09-a69c4990a026"
}
},
"floodControl": false,
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "cd7eecfd-ce55-4228-bf15-18ce490356c4",
"targetName": "Shift Supervisors",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/cd7eecfd-ce55-4228-bf15-18ce490356c4"
}
}
]
},
"properties": {
"myTextProperty": {
"value": "This is urgent. Please respond."
},
"myNumberProperty": 22183
},
"priority": "MEDIUM",
"expirationInMinutes": 180,
"overrideDeviceRestrictions": false,
"escalationOverride": false,
"bypassPhoneIntro": false,
"requirePhonePassword": false,
"voicemailOptions": {
"retry": 0,
"every": 60,
"leave": "callbackonly"
},
"created": "2021-09-30T18:35:56.652+0000",
"status": "ACTIVE",
"responseCountsEnabled": false
},
"attachments": {
"count": 1,
"total": 1,
"data": {
"name": "Planned_Outage.png",
"path": "/scheduled-messages/attachments/Planned_Outage.png",
"size": 2487,
"links": {
"self": "/api/xm/1/scheduled-messages/attachments/Planned_Outage.png"
}
}
},
"recurrence": {
"frequency": "ONCE",
"startTime": "2021-09-30T18:41:00.000Z"
},
"previousFireTime": "2021-09-30T18:41:00.045Z",
"links": {
"self": "/api/xm/1/scheduled-messages/82220da3-52d4-4deb-aa3e-dfb71c8bedb6"
}
}
Describes a scheduled message in your xMatters system.
| id | string |
| The unique identifier (or UUID) of a scheduled message in xMatters. | |
| name | string |
| The name of the scheduled message. | |
| owner | PersonReference object |
| The user that created the scheduled message. | |
| event | Event object |
| Description of the event that is created when the message is sent. | |
| attachments | AttachmentsReference objects |
| The files that were attached to the scheduled message. | |
| recurrance | MessageRecurrence object |
| When and how often the message is sent. |
MessageRecurrence object
MessageRecurrence object
This example shows the recurrence object for a message that should be sent on the first Monday of the third month of every quarter and repeats 4 times.
"recurrence":
{
"frequency": "MONTHLY",
"on": "DAY_OF_WEEK",
"months": [
"MAR",
"JUN",
"SEP",
"DEC"
],
"end": {
"endBy": "REPETITIONS",
"repititions": "4"
},
"dayOfWeekClassifier": "FIRST",
"dayOfWeek": "MO"
}
The message recurrence defines when and how often a message is sent to recipients.
| frequency | string |
The detailed parameters vary depending on the value of the scheduled message frequency. Valid values include:
|
|
| repeatEvery | string |
| Number of days between repetitions. Required when frequency is: DAILY, WEEKLY |
|
| onDays | array [string] |
Valid values include any combination of:
|
|
| on | string |
Valid values include: DATE_OF_MONTH, DAY_OF_WEEK See dateOfMonth and dayOfWeek for additional information.Required when frequency is: MONTHLY |
|
| months | array [string] |
Valid values include any combination of:
months:
|
|
| dateOfMonth | string |
| Defines a specific date of a month when a message should be sent. Valid values include: "1", "2", "3"..."31", and "LAST" Required when frequency is: MONTHLY |
|
| dayOfWeekClassifier | string |
Specifies if message should be sent on a relative day each month. Used with dayOfWeek. For example, for a message to go out to recipients on the last Friday of the month, dayOfWeekClassifier is set to LAST and dayOfWeek to FR.Valid values include:
|
|
| dayOfWeek | string |
Used with dayOfWeekClassifier to define which day of the week the message should be sent. Valid values include:
|
|
| end | MessageEnd object |
| The date and time in UTC format when a message should cease being sent, or the number of repetitions that must occur before a message stops being sent. Required when frequency is: DAILY, WEEKLY, MONTHLY, YEARLY |
|
| startTime | string |
| UTC date and time in the future when the message should be sent. For example: 2021-12-18T23:55:00.000Z |
MessageEnd object
This example shows the recurrence object, including the MessageEnd object, for a message that is sent to recipients on the first Monday of the month and repeats 4 times.
"recurrence":
{
"frequency": "MONTHLY",
"on": "DAY_OF_WEEK",
"end": {
"endBy": "REPETITIONS",
"repetitions": "4"
},
"dayOfWeekClassifier": "FIRST",
"dayOfWeek": "MO"
}
This example shows the recurrence object, including the MessageEnd object, for a message that is sent to recipients on the first Monday of the month until November 1, 2022.
"recurrence":
{
"frequency": "MONTHLY",
"on": "DAY_OF_WEEK",
"end": {
"endBy": "DATE",
"date": "2022-11-01T08:00:00.000Z"
},
"dayOfWeekClassifier": "FIRST",
"dayOfWeek": "MO"
}
These values define when a message recurrence ends. If the message should always be sent, no additional information is required. If the message ends on a specific date, or after a number of repetitions, those values must be added to the request.
| endBy | string |
| The parameter used to set when a message recurrence ends. Valid values include: NEVER, DATE, and REPETITIONS. | |
| date | string |
UTC date and time to end the recurrence. Used only when endBy is DATE. |
|
| repetitions | integer |
Number of times the message should be sent to recipients. Used only when endBy is REPETITIONS. |
SERVICE DEPENDENCIES
Service dependencies describe the relationship between a service and its direct dependent in your xMatters system. If a service has multiple dependencies or depends on multiple services, those relationships cannot currently be displayed in the request response via the xMatters REST API. To view multiple dependencies, use the service map in the xMatters web user interface. For more information on Service Dependencies and the Service Map, see Service dependencies in the online help.
Get service dependencies
GET service dependencies
REQUEST Get all service dependencies in your system
curl --user username
"https://acmeco.xmatters.com/api/xm/1/service-dependencies"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/service-dependencies",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " service dependencies." );
for (var i in json.data)
{
console.log(json.data[i].name + " created by " + json.data[i].creator.targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/service-dependencies"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"count": 3,
"total": 3,
"data": [
{
"id": "091c7fe0-9b48-4b48-bc43-b597f10d9fd9",
"service": {
"id": "95db21ed-9a67-4ad5-9273-2b67ddae1644",
"targetName": "Antares Gate",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/95db21ed-9a67-4ad5-9273-2b67ddae1644"
}
},
"dependentService": {
"id": "10aa3749-463a-4241-88d1-c8e60b0ac6e2",
"targetName": "TV Services",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/10aa3749-463a-4241-88d1-c8e60b0ac6e2"
}
}
},
{
"id": "0a84f952-c6a0-4ca8-bc7e-92d2c76a4c10",
"service": {
"id": "2e67710d-15f4-4b6b-a887-f7ec7b17fd0b",
"targetName": "Bladedamus 3",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/2e67710d-15f4-4b6b-a887-f7ec7b17fd0b"
}
},
"dependentService": {
"id": "dd16102d-b965-4207-8d83-fbaab1387ac8",
"targetName": "Bladedamus 1",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/dd16102d-b965-4207-8d83-fbaab1387ac8"
}
}
},
{
"id": "0c737e11-1cff-4d92-b108-32c7762a0a3e",
"service": {
"id": "fcf6289a-0df8-42bd-ba37-c40b1110acdc",
"targetName": "Wx 1.4",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/fcf6289a-0df8-42bd-ba37-c40b1110acdc"
}
},
"dependentService": {
"id": "f643163c-14dc-4b2a-b33a-74f31d091e03",
"targetName": "Wx 1",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/f643163c-14dc-4b2a-b33a-74f31d091e03"
}
}
},
]
Returns a paginated list of service dependncies in your xMatters instance. The service dependencies in the response represent a direct relationship between a service and its dependent. Multiple or nested dependencies are not returned in the response.
DEFINITION
GET /service-dependencies
GET /service-dependencies?serviceId=fcf6289a-0df8-42bd-ba37-c40b1110acdc
GET /service-dependencies?dependentServiceId=577d8161-ec27-4f72-8bf8-df07182b10ce
QUERY PARAMETERS
| serviceId | string |
| The unique identifier (uuid) of a service. The response returns all services that depend on the specified service. | |
| dependentServiceId | string |
| The unique identifier (uuid) of a service. The response returns all services that the specified service depends on. |
RESPONSES
| Success | Response code 200 OK and a Pagination of Service Dependency Objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a service dependency
Create a service dependency
REQUEST Create a service dependency between two existing services in your xMatters instance
curl --user username --header "Content-Type: application/json" --request POST -d ' {
"serviceId": "ac523c52-4873-4883-8e51-760eb47cf6f9",
"dependentServiceId": "6ef8791b-113e-4e58-b76a-320e8b58ec64"
}' "https://acmeco.xmatters.com/api/xm/1/service-dependencies"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/service-dependencies/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.serviceId = 'ac523c52-4873-4883-8e51-760eb47cf6f9';
data.dependentServiceId = '6ef8791b-113e-4e58-b76a-320e8b58ec64';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created " + 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 = "/service-dependencies"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
services_data = {
"serviceId": "ac523c52-4873-4883-8e51-760eb47cf6f9",
"dependentServiceId": "6ef8791b-113e-4e58-b76a-320e8b58ec64"
}
response = requests.post(url, headers=headers, json=conference_data, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print ("Created " + response.json()["targetName"] + ". id = " + response.json()[
"id")
]
RESPONSE
{
"id": "85a2fb22-14ad-4bed-80ab-f3878181e266",
"service": {
"id": "ac523c52-4873-4883-8e51-760eb47cf6f9",
"targetName": "API Gateway",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/ac523c52-4873-4883-8e51-760eb47cf6f9"
}
},
"dependentService": {
"id": "6ef8791b-113e-4e58-b76a-320e8b58ec64",
"targetName": "Simple Email Service",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/6ef8791b-113e-4e58-b76a-320e8b58ec64"
}
}
}
Creates a depencency between two existing services in your xMatters instance. To find the IDs of services in your system see Get services
DEFINITION
POST /service-dependencies
BODY PARAMETERS
| serviceId | string |
| The unique identifier (UUID) or target name of the service depended on by the second service. | |
| dependentServiceId | string |
| The unique identifier (UUID) or target name of the service that depends on the first service. |
RESPONSES
| Success | Response code 201 Created and a Service Dependency Object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a service dependency
Modify a service dependency
REQUEST Modify an existing service dependency in your xMatters instance
curl --user username --header "Content-Type: application/json" --request POST -d ' {
"id": "b1775dbe-91be-4170-8e11-f7551759b1da",
"serviceId": "API Gateway",
"dependentServiceId": "Simple Email Service"
}' "https://acmeco.xmatters.com/api/xm/1/service-dependencies"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/service-dependencies/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = 'b1775dbe-91be-4170-8e11-f7551759b1da';
data.serviceId = 'Simple Email Service';
data.dependentServiceId = 'Service to manage inbound emails';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Modified " + 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 = "/service-dependencies"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
services_data = {
"id": "b1775dbe-91be-4170-8e11-f7551759b1da",
"serviceId": "API Gateway",
"dependentServiceId": "Simple Email Service"
}
response = requests.post(url, headers=headers, json=conference_data, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print ("Modified " + response.json()["targetName"] + ". id = " + response.json()[
"id")
]
RESPONSE
{
"id": "b1775dbe-91be-4170-8e11-f7551759b1da",
"service": {
"id": "ac523c52-4873-4883-8e51-760eb47cf6f9",
"targetName": "API Gateway",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/ac523c52-4873-4883-8e51-760eb47cf6f9"
}
},
"dependentService": {
"id": "6ef8791b-113e-4e58-b76a-320e8b58ec64",
"targetName": "Simple Email Service",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/6ef8791b-113e-4e58-b76a-320e8b58ec64"
}
}
}
Modify a service depencency by changing either the serviceId or dependentServiceId. To find the IDs of services in your system see Get services.
DEFINITION
POST /service-dependencies
BODY PARAMETERS
| id | string |
| The unique identifier (UUID) of the service dependency. | |
| serviceId | string |
| The unique identifier (UUID) or target name of the service depended on by the second service. | |
| dependentServiceId | string |
| The unique identifier (UUID) or target name of the service that depends on the first service. |
RESPONSES
| Success | Response code 200 OK and a Service Dependency Object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a service dependency
Delete a service dependency from your xMatters instance
REQUEST Delete a service dependency
curl --user username -X DELETE
"https://acmeco.xmatters.com/api/xm/1/service-dependencies/2649789e-6071-4679-94f5-46327a7b0c97"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/service-dependencies/2649789e-6071-4679-94f5-46327a7b0c97"
"method": "DELETE",
});
response = request.write();
console.log (response.statusCode);
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the service dependency: " + json.targetName);
}
else if (response.statusCode == 204){
console.log("The service dependency " + targetName + " could not be found.")
}"
"method": "DELETE",
});
#The following code is formatted to work with Python v.3.6 and later.
import requests
from requests.auth import HTTPBasicAuth
import json
serviceId = "2649789e-6071-4679-94f5-46327a7b0c97"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/service-dependencies/" + 2649789e-6071-4679-94f5-46327a7b0c97
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
print("Received response: " + str(responseCode))
if int(responseCode) == 200:
rjson = response.json()
print('Deleted service dependency 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
{
"id": "2649789e-6071-4679-94f5-46327a7b0c97",
"service": {
"id": "627c35a9-2f23-4c08-91f5-57156024d0b6",
"targetName": "Solene - Web UI 2",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/627c35a9-2f23-4c08-91f5-57156024d0b6"
}
},
"dependentService": {
"id": "e0a3dbfa-52f3-4513-b8ff-0d150275c675",
"targetName": "Solene - Web UI",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/e0a3dbfa-52f3-4513-b8ff-0d150275c675"
}
},
}
Deletes a service dependecy from your instance using its unique identifier (UUID).
DEFINITION
DELETE /service-dependencies/{id}
URL PARAMETERS
| id | string |
| The unique identifier (or UUID) of a service dependency in your xMatters system. For example: fcf9192d-a647-4e16-b9e2-1768de421e08 |
RESPONSES
| Success | Response code 200 OK and an Service Dependency Object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Service Dependencies objects
Service Dependency object
Service Dependency Object
{
"id": "85a2fb22-14ad-4bed-80ab-f3878181e266",
"service": {
"id": "ac523c52-4873-4883-8e51-760eb47cf6f9",
"targetName": "API Gateway",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/ac523c52-4873-4883-8e51-760eb47cf6f9"
}
},
"dependentService": {
"id": "6ef8791b-113e-4e58-b76a-320e8b58ec64",
"targetName": "Simple Email Service",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/6ef8791b-113e-4e58-b76a-320e8b58ec64"
}
}
}
Describes the services in a service dependency.
| service | ServiceReference object |
| A list of fields that define a service. | |
| dependentService | DependentServiceReference object |
| A list of fields that define the dependent service. | |
| recipientType | string |
| For services, this value is "SERVICE". |
ServiceReference object
ServiceReference Object
{
"service": {
"id": "ac523c52-4873-4883-8e51-760eb47cf6f9",
"targetName": "API Gateway",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/ac523c52-4873-4883-8e51-760eb47cf6f9"
}
}
}
Describes the service in a service dependency. This service is relied upon by the dependent service.
| id | string |
The unique identifier (id) of the service. |
|
| targetName | string |
| The name of the service. | |
| recipientType | string |
| For services, this value is "SERVICE". |
###DependentServiceReference object
DependentServiceReference Object
{
"dependentService": {
"id": "6ef8791b-113e-4e58-b76a-320e8b58ec64",
"targetName": "Simple Email Service",
"recipientType": "SERVICE",
"links": {
"self": "/api/xm/1/services/6ef8791b-113e-4e58-b76a-320e8b58ec64"
}
}
}
Describes the dependent service.
| id | string |
The unique identifier (id) of the service. |
|
| targetName | string |
| The name of the service. | |
| recipientType | string |
| For services, this value is "SERVICE". |
SERVICES
The Service Catalog lets you define the business, technical, and external services performed by, within, or available to your enterprise – and the teams supporting them. Each service has a group assigned as its owner — a group can own multiple services, but each service can only have one owner. You can create, modify, and delete services, as well as retrieve either all services you have permission to view, or a specific service. For more information see Manage Services section in the online help.
Get services
GET services
REQUEST Get all services in your system
curl --user username
"https://acmeco.xmatters.com/api/xm/1/services"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/services",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log( "Retrieved " + json.count + " of " + json.total + " services." );
for (var i in json.data)
{
console.log(json.data[i].name + " created by " + json.data[i].creator.targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/services"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
rjson = response.json()
if responseCode == 200:
print(
"Retrieved "
+ str(rjson.get("count"))
+ " of "
+ str(rjson.get("total"))
+ " records. The object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
else:
print(
"The request did not succeed. Response code is: "
+ str(responseCode)
+ "\n"
+ json.dumps(rjson, indent=4, sort_keys=False)
)
RESPONSE
{
"count": 3,
"total": 3,
"data": [
{
"id": "b421ba14-57bb-474a-8e0e-614d97f26612",
"targetName": "API",
"recipientType": "SERVICE",
"description": "West Coast API servers",
"ownedBy": {
"id": "460e6099-bbac-4bf0-a403-e8dbc0f46526",
"targetName": "API Admins",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/460e6099-bbac-4bf0-a403-e8dbc0f46526"
}
},
"links": {
"self": "/api/xm/1/services/b421ba14-57bb-474a-8e0e-614d97f26612"
},
},
{
"id": "a421b334-57bb-474a-8e0e-914d97f2aed2",
"targetName": "Simple Email Service",
"recipientType": "SERVICE",
"description": "Service to manage inbound emails",
"ownedBy": {
"id": "332e6099-bbac-4be2-a403-e8dbc0f3e5ca",
"targetName": "Client Services",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/332e6099-bbac-4be2-a403-e8dbc0f3e5ca"
}
},
"links": {
"self": "/api/xm/1/services/a421b334-57bb-474a-8e0e-914d97f2aed2"
},
},
{
"id": "c421ba14-bb57-474a-8e03-614d97f2aaed",
"targetName": "Storage Gateway",
"recipientType": "SERVICE",
"description": "Service that controls East Coast storage facilities",
"ownedBy": {
"id": "8d4b816d-d400-4221-b63d-927dc0934ac5",
"targetName": "DBA Admins",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/8d4b816d-d400-4221-b63d-927dc0934ac5"
}
},
"links": {
"self": "/api/xm/1/services/c421ba14-bb57-474a-8e03-614d97f2aaed"
},
},
}
Returns a list of services in your xMatters instance. You can use search for a particular keyword in the name or description. The services returned in the results are based on your permission level.
DEFINITION
GET /services
GET /services?search=web service&operand=AND
GET /services?search="web service"&fields=DESCRIPTION
GET /services?ownedBy=Distribution
QUERY PARAMETERS
| search | string |
A list of search terms separated by the + sign or a space character. The results include services 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. When two or more search terms are present, the result includes services that match either search term. Use the operand and fields query parameters to expand or limit search results.When your search term contains more than one word, or contains delimiting characters such as spaces, enclose the terms in double quotes to preserve the delimiters. Example: /services?search=web service&fields=NAME returns all services with names that contain either "web" or "service". However, searching /services?search="web service"&fields=NAME returns all services with names that contain "web service". |
|
| operand | string |
| The operand to use to limit or expand the search query parameter: AND or OR. AND only returns services that have all search terms in the name or description. OR returns services 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:
|
|
| ownedBy | string |
The targetName or unique id (UUID) of the group that owns the service. |
RESPONSES
| Success | Response code 200 OK and a Pagination of Services Objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a service
Get a service
REQUEST Get a service by its unique identifier
curl --user username
"https://acmeco.xmatters.com/api/xm/1/services/b421ba14-57bb-474a-8e0e-614d97f26612"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/services/b421ba14-57bb-474a-8e0e-614d97f26612",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved service " + json.eventId + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/services/b421ba14-57bb-474a-8e0e-614d97f26612"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
response = requests.get(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print(
'Found service with id "'
+ rjson["serviceId"]
+ '" 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
{
"count": 1,
"total": 1,
"data": [
{
"id": "b421ba14-57bb-474a-8e0e-614d97f26612",
"targetName": "Simple Email Service",
"recipientType": "SERVICE",
"description": "Service to manage inbound emails",
"ownedBy": {
"id": "460e6099-bbac-4bf0-a403-e8dbc0f46526",
"targetName": "Client Services",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/460e6099-bbac-4bf0-a403-e8dbc0f46526"
}
},
"links": {
"self": "/api/xm/1/services/b421ba14-57bb-474a-8e0e-614d97f26612"
},
},
}
Returns a specific service in your xMatters instance by its unique identifier (UUID).
DEFINITION
GET /services/{serviceId}
URL PARAMETERS
| serviceId | string |
The target name or unique identifier (UUID) of a service in xMatters. For example: ab1d6091-7d58-41e2-af72-49c69b3d9b65 or Account Database. |
RESPONSES
| Success | Response code 200 OK and a Services Object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a service
Create a service
REQUEST Create a service in xMatters with an assigned owner
curl --user username --header "Content-Type: application/json" --request POST -d ' {
"targetName": "Simple Email Service",
"description": "Service to manage inbound emails",
"ownedBy": {
"targetName": "Client Services"
}
}' "https://acmeco.xmatters.com/api/xm/1/services"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/services/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.targetName = 'Simple Email Service';
data.description = 'Service to manage inbound emails';
var ownedBy = {};
ownedBy.targetName = 'Client Services';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created " + 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 = "/services"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
services_data = {
"targetName": "Simple Email Service",
"description": "Service to manage inbound emails",
"ownedBy": {
"targetName": "Client Services",
}
}
response = requests.post(url, headers=headers, json=services_data, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print ("Created " + response.json()["targetName"] + ". id = " + response.json()[
"id")
]
RESPONSE
{
"id": "3b636f4f-7403-4b60-ba79-8f49de4509b6",
"targetName": "Simple Email Service",
"recipientType": "SERVICE",
"description": "Service to manage inbound emails",
"ownedBy": {
"id": "75d5e342-3d7f-4de2-8b59-ab9a9b66ade4",
"targetName": "Client Services",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/75d5e342-3d7f-4de2-8b59-ab9a9b66ade4"
}
},
"links": {
"self": "/api/xm/1/services/3b636f4f-7403-4b60-ba79-8f49de4509b6"
}
}
Creates a service in xMatters.
DEFINITION
POST /services
BODY PARAMETERS
| targetName | string |
| The name of the service. | |
| description | string |
| The concise description of the service that provides users with additional information. | |
| ownedBy | GroupReference object |
The targetName or unique id (UUID) of the group that will own the service. A service can only have one owner, but a group can own multiple services. Note: Dynamic groups cannot be set as service owners. |
RESPONSES
| Success | Response code 201 Created and a Services Object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a service
Modify a service
REQUEST Change the owner of a service in xMatters
curl --user username --header "Content-Type: application/json" --request POST -d ' {
"id": "3b636f4f-7403-4b60-ba79-8f49de4509b6",
"ownedBy": {
"targetName": "Customer Support"
}
}' "https://acmeco.xmatters.com/api/xm/1/services"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/services/",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '3b636f4f-7403-4b60-ba79-8f49de4509b6'
var ownedBy = {};
ownedBy.targetName = 'Customer Support';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Updated " + 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 = "/services"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
services_data = {
"id": "3b636f4f-7403-4b60-ba79-8f49de4509b6",
"ownedBy": {
"targetName": "Customer Support"
}
}
response = requests.post(url, headers=headers, json=services_data, auth=auth)
responseCode = response.status_code
if responseCode == 201:
print ("Updated " + response.json()["targetName"] + ". id = " + response.json()[
"id")
]
RESPONSE
{
"id": "3b636f4f-7403-4b60-ba79-8f49de4509b6",
"targetName": "Simple Email Service",
"recipientType": "SERVICE",
"description": "Service to manage inbound emails",
"ownedBy": {
"id": "75d5e342-3d7f-4de2-8b59-ab9a9b66ade4",
"targetName": "Customer Support",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/75d5e342-3d7f-4de2-8b59-ab9a9b66ade4"
}
},
"links": {
"self": "/api/xm/1/services/3b636f4f-7403-4b60-ba79-8f49de4509b6"
}
Updates a service in xMatters. Identify the service by its unique identifier in the id field, and then provide the fields you want to modify.
DEFINITION
POST /services
BODY PARAMETERS
The only required body parameter is the UUID of the service you want to update. See the Create a service body parameters for details on the other parameters you can change.
| id | string |
The unique identifier (id) or name (targetName) of the service you want to modify. |
RESPONSES
| Success | Response code 200 OK and a Services Object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a service
Delete a service from your xMatters instance
REQUEST Delete a service
curl --user username -X DELETE
"https://acmeco.xmatters.com/api/xm/1/services/b3d77406-ba58-4ff4-bb5c-4cb0c6787b2d"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/services/b3d77406-ba58-4ff4-bb5c-4cb0c6787b2d"
"method": "DELETE",
});
response = request.write();
console.log (response.statusCode);
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the service: " + json.targetName);
}
else if (response.statusCode == 204){
console.log("The service " + targetName + " could not be found.")
}"
"method": "DELETE",
});
#The following code is formatted to work with Python v.3.6 and later.
import requests
from requests.auth import HTTPBasicAuth
import json
serviceId = "b3d77406-ba58-4ff4-bb5c-4cb0c6787b2d"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/services/" + serviceId
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
print("Received response: " + str(responseCode))
if int(responseCode) == 200:
rjson = response.json()
print('Deleted service 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
{
"id": "b3d77406-ba58-4ff4-bb5c-4cb0c6787b2d",
"targetName": "Simple Email Service",
"recipientType": "SERVICE",
"description": "Service to manage inbound emails",
"ownedBy": {
"id": "75d5e342-3d7f-4de2-8b59-ab9a9b66ade4",
"targetName": "Client Services",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/75d5e342-3d7f-4de2-8b59-ab9a9b66ade4"
}
},
"links": {
"self": "/api/xm/1/services/b3d77406-ba58-4ff4-bb5c-4cb0c6787b2d"
}
}
Deletes a service from your instance using its unique identifier (UUID).
DEFINITION
DELETE /services/{serviceId}
URL PARAMETERS
| serviceId | string |
| The target name or unique identifier (or UUID) of a service in your xMatters system. For example: fcf9192d-a647-4e16-b9e2-1768de421e08 |
RESPONSES
| Success | Response code 200 OK and an Services Object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Services objects
Service object
Service Object
{
"id": "b421ba14-57bb-474a-8e0e-614d97f26612",
"targetName": "Simple Email Service",
"recipientType": "SERVICE",
"description": "Service to manage inbound emails",
"ownedBy": {
"id": "460e6099-bbac-4bf0-a403-e8dbc0f46526",
"targetName": "Customer Support",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/460e6099-bbac-4bf0-a403-e8dbc0f46526"
}
},
"links": {
"self": "/api/xm/1/services/b421ba14-57bb-474a-8e0e-614d97f26612"
},
},
}
Describes a service in xMatters.
| id | string |
The unique identifier (id) of the service. |
|
| targetName | string |
| The name of the service. | |
| recipientType | string |
| For services, this value is "SERVICE". | |
| description | string |
| The description of the service. | |
| ownedBy | GroupReference object |
The targetName or unique id (UUID) of the group that owns the service. |
SHARED LIBRARIES
For information on other plan components, see Plans.
Shared library scripts
For shared libraries, the script is base64-encoded before it is sent. Encoding the script helps ensure that any special characters (newlines, tabs, etc.) can be transmitted in the JSON payload without issues. You can view the decoded contents of the script using the Integration Builder.
See the xMatters online help for more information on using shared libraries.
Get shared libraries
GET a list of shared libraries in a communication plan
REQUEST
curl --user username
"https://acmeco.xmatters.com/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/shared-libraries
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/shared-libraries",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " shared libraries." );
for (var i in json.data)
{
console.log(json.data[i].id + " with id " + json.data[i].id + "\nScript: " + json.data[i].script);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/plans/0482202f-bc59-4f4d-a5c7-4a451c5f80ac/shared-libraries"
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)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print(
"Retrieved "
+ str(rjson["count"])
+ " of "
+ str(rjson["total"])
+ " shared libraries."
)
for d in rjson.get("data"):
print(
"Found a shared library with id: " + d["id"] + "\t and 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(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"id": "ad400fcd-bcef-4b8c-adc4-16d44c9cd508",
"name": "integration-util",
"script": "ZXhwb3J0cy5teUZ1bmN0aW9uID0gZnVuY3Rpb24oKSB7CiAgICB2YXIgbXNnID0gJ0hlbGxvIFdvcmxkISc7CiAgICBjb25zb2xlLmxvZygnbXlGdW5jdGlvbiBzYXlzICcgKyBtc2cpOwogICAgcmV0dXJuIG1zZzsKfTs=",
"plan": {
"id": "aebe8a74-bc89-497a-bf03-30d2d4a07ac0",
"name": "Monitoring Tool X"
}
},
{
"id": "c08d5565-7301-43a4-bd1e-aaf4c426052f",
"name": "util",
"script": "ZXhwb3J0cy5teUZ1bmN0aW9uID0gZnVuY3Rpb24oKSB7CiAgICB2YXIgbXNnID0gJ0kgYW0gYXdlc29tZSEnOwogICAgY29uc29sZS5sb2coJ215RnVuY3Rpb24gc2F5cyAnICsgbXNnKTsKICAgIHJldHVybiBtc2c7Cn07",
"plan": {
"id": "aebe8a74-bc89-497a-bf03-30d2d4a07ac0",
"name": "Monitoring Tool X"
}
},
{...truncated list of Plan objects...}
],
"links": {
"self": "/api/xm/1/shared-libraries?offset=0&limit=100"
}
}
Returns a list of shared libraries in a communication plan.
DEFINITION
GET /plans/{planId}/shared-libraries
URL PARAMETERS
| {planId} | string |
The unique identifier (id) or name of the plan that you want to retrieve the shared libraries for. Use GET /plans to find the id or name of the plan. |
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 paginated list of SharedLibrary objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a shared library
GET a shared library
REQUEST
curl --user username
"https://acmeco.xmatters.com/api/xm/1/shared-libraries/ad400fcd-bcef-4b8c-adc4-16d44c9cd508"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/shared-libraries/ad400fcd-bcef-4b8c-adc4-16d44c9cd508",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved shared library " + json.name + " with id " + json.id + "\nScript: " + json.script);
}
import requests
from requests.auth import HTTPBasicAuth
import json
libraryId = "ad400fcd-bcef-4b8c-adc4-16d44c9cd508"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/shared-libraries/" + libraryId
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
print("Sending request to url: " + url)
response = requests.get(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print(
"Retrieved shared library with name: "
+ rjson["name"]
+ "\t and id: "
+ rjson["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(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"id": "ad400fcd-bcef-4b8c-adc4-16d44c9cd508",
"name": "integration-util",
"script": "ZXhwb3J0cy5teUZ1bmN0aW9uID0gZnVuY3Rpb24oKSB7CiAgICB2YXIgbXNnID0gJ0hlbGxvIFdvcmxkISc7CiAgICBjb25zb2xlLmxvZygnbXlGdW5jdGlvbiBzYXlzICcgKyBtc2cpOwogICAgcmV0dXJuIG1zZzsKfTs=",
"plan": {
"id": "aebe8a74-bc89-497a-bf03-30d2d4a07ac0",
"name": "Monitoring Tool X"
}
}
Returns information about a single shared library.
DEFINITION
GET /shared-libraries/{libraryId}
URL PARAMETERS
| {libraryId} | string |
The name or unique identifier (id) of the shared library. Use GET /plan/{planId}/shared-libraries to find the id for a library. |
RESPONSES
| Success | Response code 200 OK and a SharedLibrary object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a shared library
Create a shared library
REQUEST - Create a shared library This example shows how to create a shared library with a function to write 'Hello World'.
curl --user username --header "Content-Type: application/json" --request POST -d '{
{
"name": "HelloWorldSample",
"script": "ZXhwb3J0cy5teUZ1bmN0aW9uID0gZnVuY3Rpb24oKSB7CiAgICB2YXIgbXNnID0gJ0hlbGxvIFdvcmxkISc7CiAgICBjb25zb2xlLmxvZygnbXlGdW5jdGlvbiBzYXlzICcgKyBtc2cpOwogICAgcmV0dXJuIG1zZzsKfTs=",
"plan":
{
"id": "479056b7-3adb-48e5-9f72-197831cc65d0"
}
}' "https://acmeco.xmatters.com/api/xm/1/shared-libraries"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/shared-libraries",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.name = 'HelloWorldSample';
data.script = 'ZXhwb3J0cy5teUZ1bmN0aW9uID0gZnVuY3Rpb24oKSB7CiAgICB2YXIgbXNnID0gJ0hlbGxvIFdvcmxkISc7CiAgICBjb25zb2xlLmxvZygnbXlGdW5jdGlvbiBzYXlzICcgKyBtc2cpOwogICAgcmV0dXJuIG1zZzsKfTs=';
data.plan = planPointer;
var planPointer = {};
planPointer.id = '479056b7-3adb-48e5-9f72-197831cc65d0';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( 'Created shared library: ' + json.name + ' in plan ' + json.plan.name);
}
#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 = "/shared-libraries"
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
headers = {"Content-Type": "application/json"}
data = {
"name": "HelloWorldSample",
"script": "...base64-encoded-script-code-here...",
"plan": {"id": "479056b7-3adb-48e5-9f72-197831cc65d0"},
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
response_code = response.status_code
if response_code == 201:
rjson = response.json()(
"Shared library "
+ rjson.get("name")
+ " was successfully created in plan: "
+ rjson.get("plan", {}).get("name")
)
else:
print("The request did not succeed. Response code is: " + str(responseCode))
RESPONSE
{
"id": "2b807a24-851f-481d-8289-50138953a5f1",
"name": "HelloWorldSample",
"script": "ZXhwb3J0cy5teUZ1bmN0aW9uID0gZnVuY3Rpb24oKSB7CiAgICB2YXIgbXNnID0gJ0hlbGxvIFdvcmxkISc7CiAgICBjb25zb2xlLmxvZygnbXlGdW5jdGlvbiBzYXlzICcgKyBtc2cpOwogICAgcmV0dXJuIG1zZzsKfTs=",
"plan": {
"id": "479056b7-3adb-48e5-9f72-197831cc65d0",
"name": "Ping messages"
}
}
Creates a new shared library to use in a communication plan.
DEFINITION
POST /shared-libraries
BODY PARAMETERS
| name | string |
| The name you want to give the shared library. This appears as the name in the list of shared libraries in the Integration Builder in the web user interface. | |
| script | string |
| The base64-encoded script for the shared library. | |
| plan | PlanPointer |
The unique identifier (id) of the communication plan you want to add the shared library to. Use GET /plans to find the id of the plan. |
RESPONSES
| Success | Response code 201 Created and a SharedLibrary object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a shared library
Modify a shared library
REQUEST - Modify an existing shared library This example shows how to update the script in a shared library that already exists.
curl --user username --header "Content-Type: application/json" --request POST -d '{
{
"id": "2b807a24-851f-481d-8289-50138953a5f1",
"name": "AwesomeWorldSample",
"script": "ZXhwb3J0cy5teUZ1bmN0aW9uID0gZnVuY3Rpb24oKSB7CiAgICB2YXIgbXNnID0gJ0kgYW0gYXdlc29tZSEnOwogICAgY29uc29sZS5sb2coJ215RnVuY3Rpb24gc2F5cyAnICsgbXNnKTsKICAgIHJldHVybiBtc2c7Cn07"
}' "https://acmeco.xmatters.com/api/xm/1/shared-libraries"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/shared-libraries",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '2b807a24-851f-481d-8289-50138953a5f1';
data.name = 'AwesomeWorldSample';
data.script = 'ZXhwb3J0cy5teUZ1bmN0aW9uID0gZnVuY3Rpb24oKSB7CiAgICB2YXIgbXNnID0gJ0kgYW0gYXdlc29tZSEnOwogICAgY29uc29sZS5sb2coJ215RnVuY3Rpb24gc2F5cyAnICsgbXNnKTsKICAgIHJldHVybiBtc2c7Cn07';
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( 'Updated shared library: ' + json.name + ' in plan ' + json.plan.name);
}
#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 = '/shared-libraries'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
data = {
"name" : "HelloWorldSample-renamed",
"id":"2b807a24-851f-481d-8289-50138953a5f1",
"script" : "ZXhwb3J0cy...Base64-encoded-script...VybiBtc2c7Cn07"
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if (responseCode == 200):
rjson = response.json();
print('Shared library was successfully renamed to ' + rjson.get('name') + ' in plan: ' + rjson.get('plan',{}).get('name') )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"id": "2b807a24-851f-481d-8289-50138953a5f1",
"name": "AwesomeWorldSample",
"script": "ZXhwb3J0cy5teUZ1bmN0aW9uID0gZnVuY3Rpb24oKSB7CiAgICB2YXIgbXNnID0gJ0kgYW0gYXdlc29tZSEnOwogICAgY29uc29sZS5sb2coJ215RnVuY3Rpb24gc2F5cyAnICsgbXNnKTsKICAgIHJldHVybiBtc2c7Cn07",
"plan": {
"id": "479056b7-3adb-48e5-9f72-197831cc65d0",
"name": "Ping messages"
}
}
Updates the name or script of an existing shared library.
DEFINITION
POST /shared-libraries
BODY PARAMETERS
| id | string |
The unique identifier (id) of the shared library. Use GET /plans/{planId}/shared-libraries to find the id for a library. |
|
| name | string |
| The name of the shared library. Include if you want to update the name. NOTE: The name is used to reference the shared library in integration scripts. Changing the name will break those scripts until that reference is updated. |
|
| script | string |
| The base64-encoded script for the shared library. Include if you want to update the script. |
RESPONSES
| Success | Response code 200 Created and a SharedLibrary object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a shared library
Delete a shared library
REQUEST: Delete a shared library.
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/shared-libraries/ad400fcd-bcef-4b8c-adc4-16d44c9cd508"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/shared-libraries/ad400fcd-bcef-4b8c-adc4-16d44c9cd508",
"method": "DELETE",
"headers" : {"Content-Type": "application/json"}
});
response = request.write();
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the " + json.targetName + "shared library");
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpointURL = 'shared-libraries/ad400fcd-bcef-4b8c-adc4-16d44c9cd508'
url = baseURL + endpointURL
auth = HTTPBasicAuth('username', 'password')
response = requests.delete(url, auth=auth)
responseCode = response.status_code
if (responseCode == 200):
print ("Deleted the " + json.name + "shared library");
RESPONSE
{
"id": "ad400fcd-bcef-4b8c-adc4-16d44c9cd508",
"name": "integration-util",
"script": "ZXhwb3J0cy5teUZ1bmN0aW9uID0gZnVuY3Rpb24oKSB7CiAgICB2YXIgbXNnID0gJ0hlbGxvIFdvcmxkISc7CiAgICBjb25zb2xlLmxvZygnbXlGdW5jdGlvbiBzYXlzICcgKyBtc2cpOwogICAgcmV0dXJuIG1zZzsKfTs=",
"plan": {
"id": "aebe8a74-bc89-497a-bf03-30d2d4a07ac0",
"name": "Monitoring Tool X"
},
"links":
{
"self": "/api/xm/1/shared-libraries/ad400fcd-bcef-4b8c-adc4-16d44c9cd508"
}
}
Deletes a shared library.
The response returns a SharedLibrary Object that represents the recently deleted library.
DEFINITION
DELETE /shared-libraries/{libraryID}
URL PARAMETERS
| libraryID | string |
The unique identifier (id) of the shared library. Example: ad400fcd-bcef-4b8c-adc4-16d44c9cd508 |
RESPONSES
| Success | Response code 200 OK and a SharedLibrary object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Shared Library objects
SharedLibrary object
SharedLibrary object
This example shows the format of a shared library object in a plan called Monitoring Tool X
{
"id": "ad400fcd-bcef-4b8c-adc4-16d44c9cd508",
"name": "integration-util",
"script": "ZXhwb3J0cy5teUZ1bmN0aW9uID0gZnVuY3Rpb24oKSB7CiAgICB2YXIgbXNnID0gJ0hlbGxvIFdvcmxkISc7CiAgICBjb25zb2xlLmxvZygnbXlGdW5jdGlvbiBzYXlzICcgKyBtc2cpOwogICAgcmV0dXJuIG1zZzsKfTs=",
"plan": {
"id": "aebe8a74-bc89-497a-bf03-30d2d4a07ac0",
"name": "Monitoring Tool X"
}
}
The SharedLibrary object describes a shared library.
| id | string |
| The unique identifier that represents the shared library. When you create a new shared library, xMatters automatically generates and assigns a UUID to the library. | |
| name | string |
| The name of the shared library. | |
| script | string |
| The base64-encoded script. | |
| plan | PlanReference object |
| Identifies the communication plan the shared library is a part of. |
SHIFTS
Shifts are used within groups to determine when group members are available to receive notifications. Shifts control the dates that members are on duty as well as the order in which they are contacted.
Get a shift
Get a shift
REQUEST (get a shift by name)
curl --user username "https://acmeco.xmatters.com/api/xm/1/groups/IT/shifts/24x7"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/IT/shifts/24x7",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved shift : " + json.name + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json
groupId = "1bad48fa-5eac-4c2e-aed4-fd7d4ca3f538"
shiftId = "8a63013a-870c-4f02-8afc-c174a235318d"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups/" + groupId + "/shifts/" + shiftId
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 shift with name: " + rjson["name"] + "\tand id: " + rjson["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(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"id": "8a63013a-870c-4f02-8afc-c174a235318d",
"name": "24x7",
"group":
{
"id": "1bad48fa-5eac-4c2e-aed4-fd7d4ca3f538",
"targetName": "IT",
"links":
{
"self": "/api/xm/1/groups/1bad48fa-5eac-4c2e-aed4-fd7d4ca3f538"
}
},
"links":
{
"self": "/api/xm/1/groups/1bad48fa-5eac-4c2e-aed4-fd7d4ca3f538/shifts/8a63013a-870c-4f02-8afc-c174a235318d"
}
}
Returns a Shift object object that represents a shift in xMatters.
You can specify a shift by its name or identifier. To locate the identifier or name for a group, see Get groups. To located the identifier for a shift, see Get Shifts. You can also locate the name of a group or a shift in the user interface.
DEFINITION
GET /groups/{groupID}/shifts/{shiftID} GET /groups/{groupID}/shifts/{shiftID}?embed=rotation
URL PARAMETERS
| {groupID} | string |
The unique identifier (id) or name (targetName) of the group whose shift list you want. Example:IT Example:2633ba0e-4e2a-44a4-91f8-9133da60692b |
|
| {shiftID} | string |
The unique identifier (id) or name (targetName) of the shift. Example:24x7 Example:8a63013a-870c-4f02-8afc-c174a235318d |
QUERY PARAMETERS
| embed | string |
A comma-separated list of the objects to embed in the response.
|
RESPONSES
| Success | Response code 200 OK and a Shift object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get shifts in a group
Get a list of shifts in a group
REQUEST (get all shifts in a group by querying system data)
curl --user username "https://acmeco.xmatters.com/api/xm/1/groups/IT/shifts"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/IT/shifts",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " +json.total + "shifts");
}
import requests
from requests.auth import HTTPBasicAuth
import json
groupId = "2633ba0e-4e2a-44a4-91f8-9133da60692b"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups/" + groupId + "/shifts"
url = base_URL + endpoint_URL + "?offset=0&limit=2"
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 " + str(rjson["count"]) + " of " + str(rjson["total"]) + " shifts."
)
for d in rjson["data"]:
print("Found a shift with name: " + d["name"] + "\tand id: " + d["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(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"count": 3,
"total": 3,
"data": [
{
"id": "de352ca6-9072-4073-a270-964c4dc30ce1",
"group": {
"id": "2633ba0e-4e2a-44a4-91f8-9133da60692b",
"targetName": "IT",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/2633ba0e-4e2a-44a4-91f8-9133da60692b"
}
},
"name": "Evenings",
"description": "",
"start": "2017-12-27T22:00:00.000Z",
"end": "2017-12-28T13:00:00.000Z",
"timezone": "America/New_York",
"recurrence": {
"frequency": "WEEKLY",
"repeatEvery": 1,
"onDays": [
"MO",
"TU",
"WE",
"TH",
"FR",
"SA",
"SU"
],
"end": {
"endBy": "NEVER"
}
},
"links": {
"self": "/api/xm/1/groups/2633ba0e-4e2a-44a4-91f8-9133da60692b/shifts/de352ca6-9072-4073-a270-964c4dc30ce1"
}
},
{
"id": "5db6915e-9611-4930-8d3e-2d5928a3a009",
"group": {
"id": "2633ba0e-4e2a-44a4-91f8-9133da60692b",
"targetName": "IT",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/2633ba0e-4e2a-44a4-91f8-9133da60692b"
}
},
"name": "Weekdays",
"description": "",
"start": "2017-12-18T13:00:00.000Z",
"end": "2017-12-19T22:00:00.000Z",
"timezone": "America/New_York",
"recurrence": {
"frequency": "EVERY_WEEKDAY",
"end": {
"endBy": "NEVER"
}
},
"links": {
"self": "/api/xm/1/groups/2633ba0e-4e2a-44a4-91f8-9133da60692b/shifts/5db6915e-9611-4930-8d3e-2d5928a3a009"
}
},
{
"id": "072de3ac-64a6-4208-b56c-b157363dd4ff",
"group": {
"id": "2633ba0e-4e2a-44a4-91f8-9133da60692b",
"targetName": "IT",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/2633ba0e-4e2a-44a4-91f8-9133da60692b"
}
},
"name": "Weekends",
"start": "2017-12-18T13:00:00.000Z",
"end": "2017-12-19T22:00:00.000Z",
"timezone": "America/New_York",
"recurrence": {
"frequency": "EVERY_WEEKEND_DAY",
"end": {
"endBy": "NEVER"
}
},
"links": {
"self": "/api/xm/1/groups/2633ba0e-4e2a-44a4-91f8-9133da60692b/shifts/072de3ac-64a6-4208-b56c-b157363dd4ff"
}
}
],
"links": {
"self": "/api/xm/1/groups/2633ba0e-4e2a-44a4-91f8-9133da60692b/shifts?offset=0&limit=100"
}
}
Returns a list of shifts in the specified group.
You can specify a group by its name or identifier. To locate the identifier or name for a group, see Get groups. You can locate the name of a group in the web user interface.
DEFINITION
GET /groups/{groupID}/shifts
GET /groups/{groupID}/shifts?embed=rotation
GET /groups/{groupID}/shifts?members.exists=false
URL PARAMETERS
| groupID | string |
The unique identifier (id) or name (targetName) of the group you want a list of shifts for. Example:IT Example:2633ba0e-4e2a-44a4-91f8-9133da60692b |
QUERY PARAMETERS
| embed | string |
A comma-separated list of the objects to embed in the response.
|
|
| members.exists | Boolean |
Returns either a list of empty shifts or a list of shifts with assigned members.
|
RESPONSES
| Success | Response code 200 OK and a Pagination of Shift objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get members in a shift
Get members in a shift
REQUEST (get a shift by name, and all the members assigned to the shift)
curl --user username "https://acmeco.xmatters.com/api/xm/1/groups/IT/shifts/24x7/members"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/de4f1760-79c7-412f-b79e-a0219a44f0e4/shifts/c3165afd-2b82-4f4c-82fd-7cb3f8c403c2/members",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " members." );
for (var i in json.data ) {
console.log(" recipient: " + json.data[i].recipient.targetName + ". ID = " + json.data[i].recipient.id);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
groupId = "de4f1760-79c7-412f-b79e-a0219a44f0e4"
shiftId = "c3165afd-2b82-4f4c-82fd-7cb3f8c403c2"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups/" + groupId + "/shifts/" + shiftId + "/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
print("Received response: " + str(responseCode))
if responseCode == 200:
rjson = response.json()
print(
"Retrieved " + str(rjson["count"]) + " of " + str(rjson["total"]) + " members."
)
for d in rjson["data"]:
print(
"Found member with targetName: "
+ d["recipient"]["targetName"]
+ "\tand id: "
+ d["recipient"]["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(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"count": 1,
"total": 1,
"data": [
{
"shift": {
"id": "de352ca6-9072-4073-a270-964c4dc30ce1",
"name": "24x7",
"links": {
"self": "/api/xm/1/groups/2633ba0e-4e2a-44a4-91f8-9133da60692b/shifts/de352ca6-9072-4073-a270-964c4dc30ce1"
}
},
"recipient": {
"id": "d501b8ff-56ac-4134-be52-03bb38c9ac0a",
"targetName": "Test1",
"firstName": "Testy",
"lastName": "McTester",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/d501b8ff-56ac-4134-be52-03bb38c9ac0a"
}
},
"position": 1,
"delay": 0,
"escalationType": "NONE",
"inRotation": true
},
}
Returns a Shift object that represents a shift in xMatters, and all members assigned to that shift.
You can specify a shift by its name or identifier. To locate the identifier for a group, see Get groups. To locat the identifier for a shift, see Get Shifts. You can also locate the name of a group or a shift in the user interface.
This call provides more information on the members in a shift, and less information about the shift itself. To receive a response with more shift information, use Get a shift.
DEFINITION
GET /groups/{groupID}/shifts/{shiftID}/members
URL PARAMETERS
| {groupID} | string |
The unique identifier (id) or name (targetName) of the group whose shift list you want. Example:IT Example:2633ba0e-4e2a-44a4-91f8-9133da60692b |
|
| {shiftID} | string |
The unique identifier (id) or name (Name) of the shift. Example:24x7 Example:8a63013a-870c-4f02-8afc-c174a235318d |
Note: Because names can change, we recommend using the unique identifier (id).
RESPONSES
| Success | Response code 200 OK and a Shift object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a shift
Create a shift
REQUEST (create a default shift (always active) with a description and two members)
This example identifies the group by its name (targetName). You can also identify it by its unique identifier (id).
curl -H "Content-Type: application/json" --user username -X POST -d
'{
"name": "Emergency Response",
"description": "Shift to respond to critical issues whenever they occur",
"members": [
{
"delay": 0,
"position": 1,
"recipient": {
"id": "b6d943bb-4a25-440b-b701-9f4c843370ac",
"recipientType": "PERSON"
}
},
{
"delay":5,
"position": 2,
"escalationType": "PEER",
"recipient": {
"id": "1271ad23-5aba-4d97-bc43-3a3a25c5dc05",
"recipientType": "PERSON"
}
}
]
}'
"https://acmeco.xmatters.com/api/xm/1/groups/Database%20Administrators/shifts"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/Database Administrators/shifts",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.name = 'Emergency Response';
data.description = 'Shift to respond to critical issues whenever they occur';
var data1 = {};
data1.position = 1;
data1.delay = 0;
data1.inRotation = true;
var memberInfo1 = {};
memberInfo1.id = 'd77b60f9-b65d-4573-b2aa-476987f3170f';
memberInfo1.recipientType = "PERSON";
data1.recipient = memberInfo1;
var data2 = {};
data2.position = 2;
data2.delay = 5;
data2.escalationType = "Peer";
data2.inRotation = true;
var memberInfo2 = {};
memberInfo2.id = '99fffd6d-ace1-4eaa-9b7d-75e9b733856b';
memberInfo2.recipientType = "PERSON";
data2.recipient = memberInfo2;
data.members=[data1, data2];
var response = request.write(data);
if (response.statusCode == 201) {
var json = JSON.parse(response.body);
console.log("Created shift: " + json.name + ". ID = "+ json.id);
}
#The following code is formatted to work with Python v.3.6 and later.
from urllib.parse import quote as urlquote
import requests
group = "Database Administrators"
url = "https://acmeco.xmatters.com/api/xm/1/groups/{urlquote(group)}/shifts"
username = "myuser"
password = "$ecretpassw0rd"
new_shift = {
"name": "Emergency Response",
"description": "Shift to respond to critical issues whenever they occur",
"members": [
{
"delay": 0,
"position": 1,
"recipient": {
"id": "b6d943bb-4a25-440b-b701-9f4c843370ac",
"recipientType": "PERSON",
},
},
{
"delay": 5,
"position": 2,
"escalationType": "PEER",
"recipient": {
"id": "1271ad23-5aba-4d97-bc43-3a3a25c5dc05",
"recipientType": "PERSON",
},
},
],
}
response = requests.post(url, json=new_shift, auth=(username, password))
response_code = response.status_code
if response.status_code == 201:
print(
"Shift "
+ rjson.get("name")
+ " was successfully added. The shift object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=True)
)
else:
print("The request did not succeed. Response code is: " + responseCode)
REQUEST (add a shift that recurs on the first Monday of the 3rd month every quarter)
This example identifies the group by its name (targetName). You can also identify it by its unique identifier (id).
curl -H "Content-Type: application/json" --user username -X POST -d
'{
"name": "Quarterly Monday Stock",
"description": "Shift to cover first Monday of 3rd month each quarter",
"start": "2018-03-05T13:00:00.000Z",
"end": "2018-03-05T22:00:00.000Z",
"recurrence": {
"frequency": "MONTHLY",
"on": "DAY_OF_WEEK",
"months": [
"MAR",
"JUN",
"SEP",
"DEC"
],
"end": {
"endBy": "NEVER"
},
"dayOfWeekClassifier": "FIRST",
"dayOfWeek": "MO"
}
}'
"https://acmeco.xmatters.com/api/xm/1/groups/Database%20Administrators/shifts"
/**
* 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/Database Administrators/shifts",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.name = 'Quarterly Monday Stock';
data.description = 'Shift to cover first Monday of 3rd month each quarter';
data.start = "2018-03-05T13:00:00.000Z";
data.end = "2018-03-05T22:00:00.000Z";
var recurrence = {};
recurrence.frequency = "MONTHLY";
recurrence.on = 'DAY_OF_WEEK';
recurrence.months = ["MAR", "JUN", "SEP","DEC"];
var end = {};
end.endBy = "NEVER";
recurrence.end = end;
recurrence.dayOfWeekClassifier = "FIRST";
recurrence.dayOfWeek = "MO";
data.recurrence = recurrence;
var response = request.write(data);
if (response.statusCode == 201) {
var json = JSON.parse(response.body);
console.log("Created shift: " + json.name + ". 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/Database Administrators/shifts'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
data = {
"name": "Quarterly Monthly Stock",
"description" : "Shift to cover first Monday of 3rd month each quarter",
"start" : "2018-03-05T13:00:00.000Z",
"end" : "2018-03-05T22:00:00.000Z",
"recurrence": {
"frequency" : "MONTHLY",
"on" : "DAY_OF_WEEK",
"months" : ["MAR", "JUN", "SEP", "DEC"],
"dayOfWeekClassifier": "FIRST",
"dayOfWeek": "MO",
"end" : {
"endBy" : "NEVER"
}
}
}
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('Shift ' + rjson.get('name') + ' was successfully added. The shift object is:\n' + json.dumps(rjson, indent=4, sort_keys=True) )
else:
print('The request did not succeed. Response code is: ' + responseCode )
RESPONSE
{
"id": "29371c5e-4c3b-44d9-bcde-6671e27521df",
"group": {
"id": "1ef7a91a-dde0-45e1-83b4-d95c184edc29",
"targetName": "IT Admin",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/1ef7a91a-dde0-45e1-83b4-d95c184edc29"
}
},
"members": [
{
"position": 1,
"delay": 0,
"escalationType": "Peer",
"inRotation": true,
"recipient":{
"id": "1271ad23-5aba-4d97-bc43-3a3a25c5dc05",
"recipientType": "PERSON"
}
},
{
"position": 2,
"delay": 5,
"escalationType": "Peer",
"inRotation": true,
"recipient":{
"id": "b6d943bb-4a25-440b-b701-9f4c843370ac",
"recipientType": "PERSON"
},
}
],
"name": "Quarterly Monday Stock",
"description": "Shift to cover first Monday of 3rd month each quarter",
"start": "2018-03-05T13:00:00.000Z",
"end": "2018-03-05T22:00:00.000Z",
"timezone": "US/Eastern",
"recurrence": {
"frequency": "MONTHLY",
"on": "DAY_OF_WEEK",
"months": [
"MAR",
"JUN",
"SEP",
"DEC"
],
"end": {
"endBy": "NEVER"
},
"dayOfWeekClassifier": "FIRST",
"dayOfWeek": "MO"
},
"links": {
"self": "/api/xm/1/groups/1ef7a91a-dde0-45e1-83b4-d95c184edc29/shifts/29371c5e-4c3b-44d9-bcde-6671e27521df"
}
}
Adds a shift to the specified group.
You can add a shift that is active 24x7 (the default if you don't specify a time or recurrence) or you can configure it to occur at a specific time or in a recurring pattern. For example, you could configure a shift to be active: from 8 AM to 5 PM Monday to Friday; on the third Thursday of every month; or once on the 1st of July. We recommmend you use the xMatters web user interface to add new shifts, since it provides a simple dialog where you can create the most complex shifts, in addition to adding escalations and rotations. You can also use the UI to modify a shift after you create it.
Time values in the API are specified in universal time (UTC). When setting the start and end time of the shift, make sure you convert the date and time in your group's time zone to UTC. For example, if your group's time zone is in Melbourne, Australia, and you want their shift to start at 8:00 AM and end at 5:00 PM on Friday, Sept 21, you need to enter a start time in UTC of 2018-09-20T22:00:00Z and an end time of 2018-09-21T07:00:00Z.
For complex shifts, remember that the time is relative to the authenticating user. For example, you might get an error if you try to set a shift occuring on the first Monday of every month in Australia if you're accessing the API with a user whose time zone is US/Eastern, since this would need to start on a Sunday in UTC time.
You can add members to the shift when the shift is created, or add them afterwards. See Add a member to a shift for more information about adding a member (or members) to a shift after it's been created.
DEFINITION
POST groups/{groupID}/shifts/
URL PARAMETERS
| {groupID} | string |
The unique identifier (id) or name (targetName) of the group to which you want to add a shift. |
BODY PARAMETERS
You must give the shift a name; if you don't specify any other parameters, this creates a "Default Shift" that is active 24x7. You can also give your shift a description and include other parameters, such as a start and end time, to create a more complex shift. If you want to configure a recurring shift, there are other parameters specific to the different recurrence types and frequency; see the remaining tables in this section for the appropriate fields.
| name | string |
| The name of the shift. The name can contain a maximum of 100 characters. | |
| description | string |
| A description of the shift. The description can contain a maximum of 200 characters. | |
| start | string |
A time in UTC that defines the start of the first shift occurrence. The start time cannot be in the past. While both start and end parameters are optional, if one is specified, the other must be set. If shift start and end parameters are not provided, a 24 x 7 shift is created. |
|
| end | string |
A time in UTC that defines the end of the first shift occurrence. Must be used if a shift start time is specified. |
|
| recurrence | ShiftRecurrence object |
| Sets the recurrence of the shift (when and how often it is active). | |
| members | ShiftMember object |
| A list of members in the shift. |
RESPONSES
| Success | Response code 201 Created and a Shift object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Add a member to a shift
Add a member to a shift
REQUEST (add a member to a shift)
curl -H "Content-Type: application/json" --user username -X POST -d
'{
"position" : 6,
"delay" : 15,
"escalationType": "Peer",
"inRotation": true,
"recipient":
{
"id": "ceb08e86-2674-4812-9145-d157b0e24c17",
"recipientType" : "PERSON"
}
}'
"https://acmeco.xmatters.com/api/xm/1/groups/IT/shifts/24x7/members"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/IT/shifts/24x7/members",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.position = 6;
data.delay = 15;
data.escalationType = "Peer";
data.inRotation = true;
var memberInfo = {};
memberInfo.id = 'ceb08e86-2674-4812-9145-d157b0e24c17';
memberInfo.recipientType = "PERSON";
data.recipient = memberInfo;
response = request.write(data);
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log( "Added member: " + json.recipient.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/IT/shifts/24x7/members'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
data = {
"position" : 6,
"delay" : 15,
"escalationType" : "Peer",
"inRotation" : True,
"recipient" : {
"id" : "recipientID",
"recipientType" : "PERSON"
}
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if (responseCode == 200):
rjson = response.json();
print('Person ' + rjson.get('recipient').get('id') + ' was successfully added to the shift. The shift object is:\n' + json.dumps(rjson, indent=4, sort_keys=True) )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"shift":
{
"id": "07ae192b-614d-4986-931e-2e163f8132ce",
"links":
{
"self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd/shifts/07ae192b-614d-4986-931e-2e163f8132ce"
}
},
"position": 6,
"delay": 15,
"escalationType": "Peer",
"inRotation": true,
"recipient":
{
"id": "ceb08e86-2674-4812-9145-d157b0e24c17",
"recipientType": "PERSON"
}
}
Adds a member (group, person, or device) to a shift.
You can identify the shift and group by either its targetName or id.
This method allows you to specify how to insert the member into the escalation timeline, and whether the member rotates according to the shift rotation rules. If you do not specify a position to insert the member, it is added to the end of the escalation timeline. If the group allows duplicates you may add a member to a shift more than once.
If you would like to add a member to the group but do not know which shift to add them to, you can add them to the group roster and adjust the shift schedule later. For more information about adding members to the group roster without adding them to a shift, see Add a member to the group roster.
DEFINITION
POST /groups/{groupID}/shifts/{shiftID}/members
URL PARAMETERS
| groupID | string |
The targetName or id of the group that contains the shift. |
|
| shiftID | string |
The targetName or id of the shift. |
BODY PARAMETERS
| recipient | RecipientPointer object |
An object that defines the member to add to the shift. Example: "recipient":{ "id": "ceb08e86-2674-4812-9145-d157b0e24c17", "recipientType": "PERSON"} |
|
| position | integer |
| The position of the recipient in the shift. The value 1 represents the first member of the shift. If this value is not specified (or is larger than the total number of shift members) the member is added to the end of the shift. | |
| delay | integer |
The number of minutes to wait before escalating a notification to this member. Using a non-zero value for the delay causes xMatters to create an escalation before the shift member. Use the escalationType field to specify the category of this escalation. |
|
| escalationType | string |
The category of the escalation that precedes the shift member. Use one of the following values:
escalationType value other than None for the first shift member. |
|
| inRotation | Boolean |
| This value is true if the member rotates according to the shift's rotation rules and false if the member stays in the same position for each notification. If omitted, this value defaults to true. |
RESPONSES
| Success | Response code 200 OK and a ShiftMember object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a shift
Delete a shift
REQUEST: Delete a shift from a group, using the name or unique identifier (
id) for both the shift and the group.
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/groups/Oracle%20Administrators/shifts/Evenings"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/groups/Oracle Administrators/shifts/Evenings",
/*"path" : "api/xm/1/groups/Oracle Administrators/shifts/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 shift: " + json.name + " belonging to " +json.targetName);
}
else if (response.status.Code == 204){
console.log("The shift could not be found.")
}
import requests
from requests.auth import HTTPBasicAuth
import json
groupId = "2633ba0e-4e2a-44a4-91f8-9133da60692b"
shiftId = "438e9245-b32d-445f-916bd3e07932c892"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/groups/" + groupId + "/shifts/" + shiftId
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
print("Received response: " + str(responseCode))
if int(responseCode) == 200:
rjson = response.json()
print('Deleted shift with name: "' + rjson["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(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"id": "438e9245-b32d-445f-916bd3e07932c892",
"group":
{"id": "2633ba0e-4e2a-44a4-91f8-9133da60692b",
"targetName": "Oracle Administrators",
"recipientType": "GROUP",
"links": {
"self": "/api/xm/1/groups/2633ba0e-4e2a-44a4-91f8-9133da60692b"
},
"name": "Evenings",
"description":"Evenings On-call",
"start": "2017-12-27T22:00:00.000Z",
"end": "2017-12-28T13:00:00.000Z",
"timezone": "America/New_York",
"recurrence": {
"frequency": "WEEKLY",
"repeatEvery": 1,
"onDays": [
"MO",
"TU",
"WE",
"TH",
"FR"
],
"end": {
"endBy": "NEVER"
},
"links":
{
"self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
}
}
Deletes a shift from a group. If members in the shift do not belong to any other shift in the group, they will be removed from the group.
Identify the shift using either the shift name (for example, Evenings) or its unique identifier (the id field). You can also identify the group the shift belongs to using its name (the targetName field) or its unique identifier (the id field).
The response returns a Shift Object that represents the recently-deleted shift.
DEFINITION
DELETE /groups/{groupID}/shifts/{shiftID}
URL PARAMETERS
| {groupID} | string |
The unique identifier (id) or name (targetName) of the group. Example: IT Example: a6341d69-5683-4621-b8c8-f2e728f6752q |
|
| {shiftID} | string |
The unique identifier (id) or name (targetName) of the shift. Example: Evenings Example: a6341d69-5683-4621-b8c8-f2e728f6752q |
RESPONSES
| Success | Response code 200 OK and a Shift object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Shift objects
Shift object
Shift object
{
"id": "8a63013a-870c-4f02-8afc-c174a235318d",
"name": "24x7",
"recipient":
{
"id": "680fa081-2956-4d2f-a1ce-b6e02a70b051",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links":
{
"self": "/api/xm/1/people/680fa081-2956-4d2f-a1ce-b6e02a70b051"
}
}
"group":
{
"id": "1bad48fa-5eac-4c2e-aed4-fd7d4ca3f538",
"targetName": "IT",
"links":
{
"self": "/api/xm/1/groups/1bad48fa-5eac-4c2e-aed4-fd7d4ca3f538"
}
},
"links":
{
"self": "/api/xm/1/groups/1bad48fa-5eac-4c2e-aed4-fd7d4ca3f538/shifts/8a63013a-870c-4f02-8afc-c174a235318d"
}
}
Describes a shift, including its name, ID, the group to which it belongs, and the members it contains.
| id | string |
| A unique identifier that represents the shift. | |
| group | GroupReference object |
| The group to which the shift belongs. | |
| links | SelfLink object |
| A link that can be used to access this shift. | |
| name | string |
| The target name of the shift. | |
| start | string |
| The start time of the shift. | |
| end | string |
| The end time of the shift. | |
| timezone | string |
| The time zone the shift occurs in. | |
| recurrence | ShiftRecurrence object |
| The recurrence parameters of the shift (for example, frequency, number of times the shift repeats, and which days or months the shift occurs). | |
| members | ShiftMember object |
A list of members assigned to a shift. When called in the Get a Shift or Get members in a shift, the response displays member information as recipient. |
ShiftRecurrence object
ShiftRecurrence object
This example shows the recurrence object for a shift that occurs on the first Monday of the third month of every quarter and repeats 4 times.
"recurrence":
{
"frequency": "MONTHLY",
"on": "DAY_OF_WEEK",
"months": [
"MAR",
"JUN",
"SEP",
"DEC"
],
"end": {
"endBy": "NEVER"
},
"dayOfWeekClassifier": "FIRST",
"dayOfWeek": "MO"
}
The shift recurrence defines when and how often a shift is active.
| frequency | string |
The detailed parameters vary depending on the value of the shift frequency. Valid values include:
|
|
| repeatEvery | string |
| Number of days between repetitions. Required when frequency is: DAILY, WEEKLY |
|
| onDays | array [string] |
Valid values include any combination of:
|
|
| on | string |
Valid values include: DATE_OF_MONTH, DAY_OF_WEEK See dateOfMonth and dayOfWeek for additional information.Required when frequency is: MONTHS |
|
| months | array [string] |
Valid values include any combination of:
months:
|
|
| dateOfMonth | string |
| Defines a specific date of a month that a monthly shift occurs on. Valid values include: "1", "2", "3"..."31", and "LAST" Required when frequency is: MONTHLY |
|
| dayOfWeekClassifier | string |
Specifies if a monthly shift occurs on a relative day each month. Used with dayOfWeek.For example, for a shift that occurs on the last Friday of the month, dayOfWeekClassifier is set to LAST and dayOfWeek to FR.Valid values include:
|
|
| dayOfWeek | string |
Used with dayOfWeekClassifier to define which day of the week the shift occurs. Valid values include:
|
|
| end | end object |
| The date and time in UTC format when a shift ends, or the number of repetitions that must occur before a shift ends. Required when frequency is: DAILY, WEEKLY, EVERY_WEEKDAY, EVERY_WEEKEND_DAY, MONTHLY, YEARLY |
End object
This example shows the recurrence object for a shift that occurs on the first Monday of the month and repeats 4 times.
"recurrence":
{
"frequency": "MONTHLY",
"on": "DAY_OF_WEEK",
"end": {
"endBy": "REPETITIONS",
"repetitions": "4"
},
"dayOfWeekClassifier": "FIRST",
"dayOfWeek": "MO"
}
This example shows the recurrence object for a shift that occurs on the first Monday of the month until November 1, 2022.
"recurrence":
{
"frequency": "MONTHLY",
"on": "DAY_OF_WEEK",
"end": {
"endBy": "DATE",
"date": "2022-11-01T08:00:00.000Z"
},
"dayOfWeekClassifier": "FIRST",
"dayOfWeek": "MO"
}
These values define when a shift recurrence ends. If the shift never ends, no additional information is required. If the shift ends on a specific date, or after a number of repetitions, those values must be added to the request.
| endBy | string |
| The parameter used to set when a shift recurrence ends. Valid values include: NEVER, DATE, and REPETITIONS. | |
| date | string |
| UTC date and time to end the recurrence. Used only when endBy is DATE. | |
| repetitions | integer |
| Number of times the shift occurs. Used only when endBy is REPETITIONS. |
Rotation object
Rotation Object
This example shows the rotation object for a shift where the last shift member becomes the first member every three shifts.
"rotation": {
"type": "SHIFT",
"direction": "LAST_TO_FIRST",
"interval": 3,
"nextRotationTime": "2020-01-12T08:00:00.000Z"
},
Defines when members of a shift rotate positions.
| type | string |
| The type of shift rotation. Available options include: NONE, EVENT, SCHEDULE, SHIFT. | |
| direction | string |
When type is SCHEDULE or SHIFT, the direction in which members rotate. Available options include: SECOND_TO_FIRST, LAST_TO_FIRST. |
|
| interval | integer |
| The number of events, shifts, or scheduled time between rotations. | |
| intervalUnit | string |
When the interval type is SCHEDULE, the amount of time between shift rotations. Available options include: DAYS, WEEKS, MONTHS |
|
| nextRotationTime | string |
| The timestamp of the next scheduled shift rotation. |
ShiftMember object
ShiftMember object
This example shows a group that is the ninth member of the shift and does not rotate its position. This group immediately follows a management-level escalation delay of 30 minutes.
{
"shift":
{
"id": "07ae192b-614d-4986-931e-2e163f8132ce",
"links":
{
"self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd/shifts/07ae192b-614d-4986-931e-2e163f8132ce"
}
},
"position":9,
"delay":30,
"escalationType":"Management",
"inRotation":false,
"recipient":
{
"id":"ceb08e86-2674-4812-9145-d157b0e24c17",
"recipientType":"PERSON"
}
}
Defines how a person, group, or device belongs to a shift. This includes the position of the member in the shift, whether this position rotates according to the shift rotation rules, and information about any escalation that immediately precedes the member's position in the shift.
If there is an escalation immediately preceding the shift member, the delay and escalationType values describe this escalation. If the shift member does not immediately follow an escalation then the delay value is 0 and the escalationType value is None.
| position | integer |
| The position of the member in the shift. | |
| delay | integer |
| The number of minutes to wait before escalating the notification to this shift member. Shift members that do not immediately follow an escalation have a delay value of 0. | |
| escalationType | string |
This value describes the category of a preceding escalation. This field has one of the following values:
|
|
| inRotation | Boolean |
| This value is true if the shift member's position rotates according to the shift's rotation rules. This value is false if the shift member stays in the same position when the shift rotates. | |
| recipient | Recipient object |
| Describes the person, group or device to add to the shift. | |
| shift | ReferenceByIdAndSelfLink object |
| A link to the shift. |
SiteHolidays object
SiteHolidays Object
Describes how a site holiday interfor a recurring shift.
"siteHolidays": {
"onCall": true,
"start": "2023-05-22T08:00:00.000Z",
"end": "2023-05-24T08:00:00.000Z"
},
Defines when a site holiday applies to a shift.
| onCall | Boolean |
| Whether the site holday shift is an on-call shift or not. This field is required if the group is has a site assigned. | |
| start | string |
| Defines when the site holiday shift begins | |
| end | string |
| Defines when the site holiday shift ends |
ShiftOccurrence object
ShiftOccurrence Object
Defines the occurance of a shift for a specified group.
{
"start": "2023-05-31T07:00:00Z",
"end": "2023-06-01T07:00:00Z",
"shift": {
"id": "803c2459-94bf-4f62-9cab-c662035f1697",
"name": "Emergency Repair",
"links": {
"self": "/api/xm/1/groups/2384a5f3-6557-4e29-9898-f9609171479e/shifts/803c2459-94bf-4f62-9cab-c662035f1697"
}
},
"group": {
"id": "2384a5f3-6557-4e29-9898-f9609171479e",
"targetName": "Repair Shop",
"recipientType": "GROUP",
"groupType": "ON_CALL",
"links": {
"self": "/api/xm/1/groups/2384a5f3-6557-4e29-9898-f9609171479e"
}
}
},
Defines the occurance of a shift for a specified group
| onCall | Boolean |
| Whether the site holday shift is an on-call shift or not. This field is required if the group is has a site assigned. | |
| start | string |
| Defines when the site holiday shift begins | |
| end | string |
| Defines when the site holiday shift ends |
SITES
Sites in xMatters group users by their physical location. A user's default settings for location-specific settings such as language and time zones are determined from their site. Sites are also used to notify users based on their geographic location.
You can identify a site by its name or id.
Get a site
GET a site
REQUEST (get a site by name)
curl --user username "https://acmeco.xmatters.com/api/xm/1/sites/San%20Ramon"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var siteName = "San Ramon";
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/sites/" + siteName,
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved site: " + json.name + ". ID = " + json.id);
}
else if (response.statusCode == 404){
console.log("The site could not be found: " + siteName);
}
import requests
from requests.auth import HTTPBasicAuth
import json
siteId = "960ffa54-b6d3-42b7-8025-7d95ff599976"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/sites/" + siteId
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 site with name: " + rjson["name"] + "\tand id: " + rjson["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(responseCode)
+ "\n"
+ str(response)
)
REQUEST (get a site by identifier)
curl --user username "https://acmeco.xmatters.com/api/xm/1/sites/960ffa54-b6d3-42b7-8025-7d95ff599976"
var siteID = "960ffa54-b6d3-42b7-8025-7d95ff599976";
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/sites/" + siteID,
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved site: " + json.name + ". ID = " + json.id);
}
else if (response.statusCode == 404){
console.log("The site could not be found: " + siteID);
}
import requests
from requests.auth import HTTPBasicAuth
site_id = "960ffa54-b6d3-42b7-8025-7d95ff599976"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/sites"
url = base_URL + endpoint_URL + "/" + site_ID
response = requests.get(url, auth=HTTPBasicAuth("username", "password"))
if response.status_code == 200:
print "Retrieved site " + response.json()["id"]
elif response.status_code == 404:
print "The site could not be found: " + site_ID
RESPONSE
{
"id":"960ffa54-b6d3-42b7-8025-7d95ff599976",
"links":
{
"self":"/api/xm/1/sites/960ffa54-b6d3-42b7-8025-7d95ff599976"
},
"name":"San Ramon",
"status":"ACTIVE",
"externallyOwned":false,
"language":"en",
"timezone":"US/Los Angeles",
"address1":"12647 Alcosta Blvd",
"city":"San Ramon",
"country":"USA",
"postalCode":"94583",
"latitude":39.77,
"longitude":-121.95,
"state":"CA"
}
Returns a Site object that represents a site in xMatters.
You can identify a site by its name or identifier. To locate the identifier for a site in the xMatters user interface, use Get Sites or see Locate the identifier for a site.
You can access site information if you have permission to either view sites on your own devices in the xMatters user interface. Depending on your permission level, you will see either the unique identifier (id) and name of the site or all site information.
When you request a site, the language code is returned as a two-letter code following the ISO 639 format and the country code is returned as a three-letter code following ISO 3166-2 format.
DEFINITION
GET /sites/{siteID}
URL PARAMETERS
| {siteID} | string |
The unique identifier (id) or name (targetName) of the site. Example:San Ramon Example:960ffa54-b6d3-42b7-8025-7d95ff599976 |
RESPONSES
| Success | Response code 200 OK and a Site object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get sites
Get all sites
REQUEST (get all sites from the system)
curl --user username "https://acmeco.xmatters.com/api/xm/1/sites"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/sites",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + "sites");
}
import requests
from requests.auth import HTTPBasicAuth
import json
siteId = ""
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/sites?offset=0&limit=2"
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 " + str(rjson["count"]) + " of " + str(rjson["total"]) + " sites.")
for d in rjson["data"]:
print("Found site with name: " + d["name"] + "\tand id: " + d["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(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"count": 3,
"total": 3,
"data": [
{
"id": "23d3ca36-13d2-4aaf-84da-6218aa768b11",
"links": {
"self": "/api/xm/1/sites/23d3ca36-13d2-4aaf-84da-6218aa768b11"
},
"name": "Default Site",
"status": "ACTIVE",
"externallyOwned": false,
"language": "en",
"timezone": "US/Eastern",
"address1": "Unit 307",
"address2": "1347 Admirals Rd",
"city": "Seattle",
"country": "USA",
"postalCode": "98101",
"state": "WA"
},
{
... truncated list of Sites object...
}
}
Returns a pagenated list of sites. Each site contains a unique identifier in the id field. You can use this identifier with the GET site and POST sites methods to identify the site. To learn how you can locate this identifier in the user interface, see Locate the identifier for a site
Depending on your permission level, you will see either the unique identifier (id) and name of the site or all site information. To return information for a specific site, see Get a Site.
When you request a site, the language code is returned as a two-letter code following the ISO 639 format and the country code is returned as a three-letter code following ISO 3166-2 format.
DEFINITION
GET /sites
GET /sites?search=term
GET /sites?search=denver colorado&operand=AND
GET /sites?search="denver colorado"&fields=NAME
GET /sites?sortBy=ADDRESS&sortOrder=ASCENDING
GET /sites?country=Canada
GET /sites?geocoded=true
GET /sites?status=ACTIVE
QUERY PARAMETERS
| search | string |
A list of search terms separated by the + sign or a space character. Searches are case-insensitive ("alert" finds "alert", "Alert", as well as "alerting") and must contain at least two characters. When two or more search terms are present, the result includes sites that match either search term. The search looks for the term anywhere in the name or description. Use the operand and fields query parameters to expand or limit search results.When your search term contains more than one word, or contains delimiting characters such as spaces, enclose the terms in double quotes to preserve the delimiters. Example: /sites?search=Denver Colorado&fields=NAME returns all sites with names that contain either "Denver" or "Colorado". However, searching /sites?search="Denver Colorado"&fields=NAME returns all sites with names that contain "Denver Colorado". |
|
| operand | string |
Applied to the provided search terms to limit or expand the search query parameter. Available options include: AND or OR. AND only returns sites that have all search terms in the specified fields. OR returns sites that have any of the search terms in the specified fields; this is the default if you don’t specify an operand. The operand is case-sensitive; entering lowercase "and" will return an error. |
|
| fields | string |
Use with the search parameter to limit the fields searched. Available values 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 sites are sorted in ascending or descending order. This parameter must be used in conjunction with the sortBy query parameter. Valid values include:
|
|
| country | string |
| The full name, two-letter, or three-letter code for a country. For example: CA, CAN, Canada. This field is not case-sensitive. See the ISO 3166-2 standard for country codes. | |
| geocoded | Boolean |
| If "true" all sites whose full latitude and longitude coordinates are set are returned. If "false" all sites with no latitude or longitude, or with partial coordinates are returned. | |
| status | string |
The status of the site. Valid values 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 Pagination of Site objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a site
Create a site
REQUEST (create a site)
curl -X POST --user username -H 'content-type: application/json' --data
'{
"name" : "TestSite1",
"country": "USA",
"language": "EN",
"timezone": "US/Pacific"
}'
"https://acmeco.xmatters.com/api/xm/1/sites"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/sites",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.name = 'TESTSITE1';
data.country = 'USA';
data.language = 'en';
data.timeZone = 'US/PACIFIC';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( 'Created site: ' + json.Name + '. ID = '+ json.id);
}
else if (response.statusCode == 409){
console.log('The site already exits");
}
#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 = '/sites'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
data = {
"name" : "TestSite1",
"country" : "USA",
"status" : "ACTIVE",
"language" : "EN",
"timezone" : "US/Pacific"
}
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('Site ' + rjson.get('name') + ' was successfully added. The site object is:\n' + json.dumps(rjson, indent=4, sort_keys=True) )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"id": "b2341d69-8b83-4660-b8c8-f2e728f675f9",
"name": "TestSite1",
"country": "USA",
"language": "en",
"timezone": "US/Pacific",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/sites/b2341d69-8b83-4660-b8c8-f2e728f675f9"
},
"status": "ACTIVE"
}
Creates a new site.
To create a new site, make a POST request to /sites and include a Site object in the request body. A new site is created with the properties defined by the Site object. Responses to site creation requests return a JSON object that includes the ID of the newly created site.
The unique identifier for a site is included in the response of the GET sites method and is displayed in the xMatters web user interface. For more information about locating this identifier in the user interface, see Locate the identifier for a site
DEFINITION
POST /sites
BODY PARAMETERS
The following table lists the mandatory body parameters for creating a site. Additional body parameters for creating a site are listed in the Site object.
| name | string |
| The name of the site. This value has a maximum of 100 characters. | |
| country | string |
| The name of the country (in ISO 3166-2 format) for the site. The country must be marked as Active in the web user interface Admin tab before you can set it here. | |
| language | string |
| The preferred language (in ISO 639 format) for the site. The language must be enabled in xMatters before you can set it here. | |
| timezone | string |
| The site's time zone. The time zone must be marked as Active in the Admin tab before you can set it here. Example: US/Pacific |
RESPONSES
| Success | Response code 201 Created and a Site object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a site
Modify a site
REQUEST (modify or update a site)
curl -H "Content-Type: application/json" --user username -X POST -d
'{
"id": "b2341d69-8b83-4660-b8c8-f2e728f675f9",
"name": "TestSite1",
"country": "FRA",
"language": "fr",
"timezone": "Europe/Paris"
}' "https://acmeco.xmatters.com/api/xm/1/sites"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/sites",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = 'b2341d69-8b83-4660-b8c8-f2e728f675f9';
data.name = 'TESTSITE1';
data.country = 'FRA';
data.language = 'fr';
data.timeZone = 'Europe/Paris';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( 'Modified site: ' + json.Name + '. ID = '+ json.id);
}
else if (response.statusCode == 409){
console.log('The action cannot be performed in the system");
}
#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 = '/sites'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {"Content-Type": "application/json"}
data = {
"id" : "b2341d69-8b83-4660-b8c8-f2e728f675f9",
"name": "TestSite1",
"country": "FRA",
"language": "fr",
"timezone": "Europe/Paris"
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if (responseCode == 200):
rjson = response.json();
print('Site ' + rjson.get('name') + ' was successfully modified. The updated site object is:\n' + json.dumps(rjson, indent=4, sort_keys=True) )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
See Create a site for an example of the response object.
Modify or update an existing site.
To modify or update an existing site, make a POST request to /sites, and include a Site object in the request body. The request must include the site id and name, plus any properties that you wish to add or modify.
Properties are not modified if they are not included in the request. The response consists of a Site object that contains any non-default properties of the updated site.
The unique identifier for a site is included in the response of the GET sites method and is displayed in the xMatters web user interface. For more information about locating this identifier in the user interface, see Locate the identifier for a site.
DEFINITION
POST /sites/
BODY PARAMETERS
The only required body parameter is the UUID of the site you want to update. See the Site object for details on the other available parameters.
| id | string |
| The UUID of the site you want to modify. To get the ID of a site, use GET sites. |
RESPONSES
| Success | Response code 201 Created and a Site object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a site
Delete a site
REQUEST: Delete a site by name. You can also identify the site by its unique identifier (
id).
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/sites/West_Coast_Weather"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/sites/West_Coast_Weather",
"method": "DELETE",
"headers" : {"Content-Type": "application/json"}
});
response = request.write();
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the site " + json.targetName);
}
import requests
from requests.auth import HTTPBasicAuth
import json
siteId = "438e9245-b32d-445f-916bd3e07932c892"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/sites/" + siteId
url = base_URL + endpoint_URL
auth = HTTPBasicAuth("username", "password")
print("Sending delete request to URL: " + url)
response = requests.delete(url, auth=auth)
responseCode = response.status_code
if responseCode == 200:
rjson = response.json()
print(
"Site "
+ siteId
+ " was successfully deleted.\nThe deleted object is:\n"
+ json.dumps(rjson, indent=4, sort_keys=True)
)
else:
print("The request did not succeed. The response is: " + str(response))
RESPONSE
{
"id": "438e9245-b32d-445f-916bd3e07932c892",
"targetName": "West_Coast_Weather",
"country": "Canada",
"language": "en",
"timezone": "CA/Pacific",
"links":
{
"self": "/api/xm/1/sites/438e9245-b32d-445f-916bd3e07932c892"
}
}
Deletes a site.
Identify the site using either the site name (the targetName field) or its unique identifier (the id field).
A site cannot be deleted if:
- it is the default site
- it is in use by any Users or Groups
The response returns a Site Object that represents the recently deleted site.
DEFINITION
DELETE /sites/{siteID}
URL PARAMETERS
| {siteID} | string |
The unique identifier (id) or name (targetName) of the site. Example: IT Example: a6341d69-5683-4621-b8c8-f2e728f6752q |
RESPONSES
| Success | Response code 200 OK and a Site object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Site objects
Site object
Site Object
{
"id":"960ffa54-b6d3-42b7-8025-7d95ff599976",
"links":
{
"self":"/api/xm/1/sites/960ffa54-b6d3-42b7-8025-7d95ff599976"
},
"name":"San Ramon",
"status":"ACTIVE",
"externallyOwned":false,
"language":"en",
"timezone":"US/Los Angeles",
"address1":"12647 Alcosta Blvd",
"city":"San Ramon",
"country":"USA",
"postalCode":"94583",
"latitude":39.77,
"longitude":-121.95,
"state":"CA"
}
The Site object represents a site in xMatters. A list of country names is available in the xMatters web user interface under the Admin tab.
| address1 | string |
| The first line of the site address. | |
| address2 | string |
| The second line of the site address. | |
| city | string |
| The city in which the site is located. | |
| country | string |
| The country in which the site is located. When specifying the country, you can use either the full country name, or the two-letter or three-letter country code as specified by the ISO 3166-2 standard. | |
| externalKey | string |
| See externalKey. | |
| externallyOwned | Boolean |
| See externallyOwned. | |
| id | string |
| A unique identifier that represents this site. | |
| language | string |
| The default language used by this site. When specifying the language, use the two-letter ISO 639 language code. | |
| latitude | string |
| The latitude of the site's physical location. | |
| links | SelfLink object |
| A link that can be used to access this site. | |
| longitude | string |
| The longitude of the site's physical location. | |
| name | string |
| The name that is used to identify this site within xMatters. | |
| postalCode | string |
| The ZIP or postal code for the site. | |
| state | string |
| The region, state or province in which the site is located. | |
| status | string |
Whether the site is active. Users assigned to inactive sites cannot log in to xMatters or receive notifications. Use one of the following values:
|
|
| timezone | string |
| The default time zone of the site. When specifying the time zone, use the two-letter country code followed by the city name. Three-letter country codes are not supported. For more information, see time zones. Example: "US/Los Angeles" |
SUBSCRIPTION FORMS
Subscription forms are created within a communication plan to allow users to subscribe to events. The following methods allow you to see the details for a specific subscription form or for all subscription forms in your system. You can also create new subscription forms and update existing ones.
For more information about subscription forms, see the Online Help.
Get a subscription form
GET a subscription form
REQUEST
curl --user username "https://acmeco.xmatters.com/api/xm/1/subscription-forms/db962bcd-22e6-4c74-8193-93a64209051b"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/subscription-forms/db962bcd-22e6-4c74-8193-93a64209051b"
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved subscription form " + json.name + ". Form Id: " + json.id + "." );
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
subscriptionFormId = "db962bcd-22e6-4c74-8193-93a64209051b"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/subscription-forms/" + subscriptionFormId
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 subscription form with name: "
+ rjson["name"]
+ "\tand id: "
+ rjson["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(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"id": "db962bcd-22e6-4c74-8193-93a64209051b",
"name": "North American Outages",
"description": "NA service outage stakeholder notifications",
"plan": {
"id": "8192a2ad-1531-42ab-8bfb-1eac133341a4",
"name": "Major Incident Notifications"
},
"scope": "FORM",
"form": {
"id": "7498c42c-8563-4b06-861e-80c4fda7bbee",
"name": "Internal Service Outage"
},
"created": "2018-11-15T21:10:03.321Z",
"oneWay": false,
"subscribeOthers": false,
"notificationDelay": 0,
"propertyDefinitions": {
"count": 2,
"total": 2,
"data": [
{
"id": "751be5e9-5106-4035-a04d-0e99d05ce3af",
"propertyType": "TEXT",
"name": "Description",
"description": "Enter the description of the issue",
"helpText": "Enter the description of the issue",
"default": "",
"maxLength": 2000,
"minLength": 0,
"pattern": "",
"validate": false
},
{
"id": "0b454ad5-1919-49bb-95a2-b9c2efad4f99",
"propertyType": "NUMBER",
"name": "Outage Minutes",
"description": "The number of minutes the services have been impacted.",
"helpText": "Specify the number of minutes the services have been impacted.",
"default": "1",
"maximum": 9999999,
"minimum": 1,
"units": "mins"
}
]
},
"roles": {
"count": 2,
"total": 2,
"data": [
{
"id": "dc3f02fd-4609-4a02-a791-affe0547ec3d",
"name": "Standard User"
},
{
"id": "47a7345d-28a3-439a-83be-005fee05764b",
"name": "REST Web Service User"
}
]
},
"targetDeviceNames": {
"count": 2,
"total": 2,
"data": [
{
"deviceType": "VOICE",
"name": "Mobile Phone",
"description": "Cell Phone"
},
{
"deviceType": "EMAIL",
"name": "Work Email",
"description": "Work Email Address"
}
]
},
"visibleTargetDeviceNames": {
"count": 2,
"total": 2,
"data": [
{
"deviceType": "VOICE",
"name": "Mobile Phone",
"description": "Cell Phone"
},
{
"deviceType": "EMAIL",
"name": "Work Email",
"description": "Work Email Address"
}
]
},
"links": {
"self": "/api/xm/1/subscription-forms/db962bcd-22e6-4c74-8193-93a64209051b"
}
}
Returns a specific subscription form based on its unique identifier. Depending on your permission level, you will see either the unique identifier (id) and name of the subscription form or all subscription form information.
DEFINITION
GET /subscription-forms/{subscriptionFormId}
URL PARAMETERS
| subscriptionFormId | string |
The unique identifier (id) of the subscription form. |
RESPONSES
| Success | Response code 200 OK and a Subscription Form object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get subscription forms
GET subscription forms
REQUEST
curl --user username "https://acmeco.xmatters.com/api/xm/1/subscription-forms"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/subscription-forms",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " subscription 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 = "/subscription-forms?embed=deviceNames,propertyDefinitions,roles"
url = base_URL + endpoint_URL + "&offset=0&limit=2"
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 "
+ str(rjson["count"])
+ " of "
+ str(rjson["total"])
+ " subscription forms."
)
for d in rjson["data"]:
print(
"Found subscription form with name: "
+ d["name"]
+ "\tand id: "
+ d["id"]
+ ", belonging to form: "
+ d["form"]["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(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"count": 3,
"total": 3,
"data": [
{
"id": "db962bcd-22e6-4c74-8193-93a64209051b",
"name": "North American Outages",
"description": "NA service outage stakeholder notifications",
"plan": {
"id": "8192a2ad-1531-42ab-8bfb-1eac133341a4",
"name": "Major Incident Notifications"
},
"scope": "FORM",
"form": {
"id": "7498c42c-8563-4b06-861e-80c4fda7bbee",
"name": "Internal Service Outage"
},
"created": "2018-11-15T21:10:03.321Z",
"oneWay": false,
"subscribeOthers": false,
"notificationDelay": 0,
"links": {
"self": "/api/xm/1/subscription-forms/db962bcd-22e6-4c74-8193-93a64209051b"
}
},
{ ... truncated list of forms ... },
"links": {
"self": "/api/xm/1/subscription-forms?offset=0&limit=100"
}
Returns a list of all subscription forms in xMatters. Depending on your permission level, you will see either the unique identifier (id) and name of the subscription form or all subscription form information.
DEFINITION
GET /subscription-forms
GET /subscription-forms?sortBy=NAME&sortOrder=ASCENDING
GET /subscription-forms?embed=deviceNames,propertyDefinitions,roles
QUERY PARAMETERS
| embed | string |
A comma-separated list of the objects to embed in the response. Supported values include the following:
|
|
| sortBy | string |
Determines the criteria by which subscription forms are sorted:
sortOrder to change whether the results are sorted in ascending or descending order. |
|
| sortOrder | string |
Specifies whether subscription 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 Subscription Form objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get subscription forms in a plan
GET subscription forms in a specific communication plan
REQUEST
curl --user username "https://acmeco.xmatters.com/api/xm/1/plans/8192a2ad-1531-42ab-8bfb-1eac133341a4/subscription-forms"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/8192a2ad-1531-42ab-8bfb-1eac133341a4/subscription-forms",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " subscription 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
planId = "8192a2ad-1531-42ab-8bfb-1eac133341a4"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = (
"/plans/"
+ planId
+ "/subscription-forms?embed=deviceNames,propertyDefinitions,roles"
)
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 "
+ str(rjson["count"])
+ " of "
+ str(rjson["total"])
+ " subscription forms."
)
for d in rjson["data"]:
print(
"Found subscription form with name: "
+ d["name"]
+ "\tand id: "
+ d["id"]
+ ", belonging to form: "
+ d["form"]["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(responseCode)
+ "\n"
+ str(response)
)
RESPONSE
{
"count": 1,
"total": 1,
"data": [
{
"id": "db962bcd-22e6-4c74-8193-93a64209051b",
"name": "North American Outages",
"description": "NA service outage stakeholder notifications",
"plan": {
"id": "8192a2ad-1531-42ab-8bfb-1eac133341a4",
"name": "Major Incident Notifications"
},
"scope": "FORM",
"form": {
"id": "7498c42c-8563-4b06-861e-80c4fda7bbee",
"name": "Internal Service Outage"
},
"created": "2018-11-15T21:10:03.321Z",
"oneWay": false,
"subscribeOthers": false,
"notificationDelay": 0,
"links": {
"self": "/api/xm/1/subscription-forms/db962bcd-22e6-4c74-8193-93a64209051b"
}
}
],
"links": {
"self": "/api/xm/1/plans/8192a2ad-1531-42ab-8bfb-1eac133341a4/subscription-forms?offset=0&limit=100"
}
}
Returns a list of subscription forms in a specific communication plan.
DEFINITION
GET /plans/{planId}/subscription-forms
GET /plans/{planId}/subscription-forms?sortBy=NAME&sortOrder=ASCENDING
GET /plans/{planId}/subscription-forms?embed=deviceNames,propertyDefinitions,roles
URL PARAMETERS
| planId | string |
The unique identifier (id) of the plan. |
QUERY PARAMETERS
| planId | string |
The unique identifier id or name of the communication plan. |
|
| embed | string |
A comma-separated list of the objects to embed in the response. Supported values include the following:
|
|
| sortBy | string |
Determines the criteria by which subscription forms are sorted:
sortOrder to change whether the results are sorted in ascending or descending order. |
|
| sortOrder | string |
Specifies whether subscription 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 Subscription Form objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a subscription form
Create a subscription form
REQUEST - Create a subscription form This request shows how to create a subscription form that allows users to create subscriptions for all forms in a communication plan. There are two properties to subscribe against, and Incident Managers can subscribe themselves or others. A targetDeviceNames object is not included; all devices will be selected and visible to people creating subscriptions based on the subscription form.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"name": "Stellar App SEV-1",
"description": "Alerts subscribers when an event is created using any form in the plan",
"scope": "ALL_FORMS",
"oneWay": true,
"subscribeOthers": true,
"notificationDelay": 5,
"propertyDefinitions": [
{
"id": "8e84893b-e67c-41b6-b9c4-c2a421af5efe"
},
{
"name": "Customer impacting"
}
],
"roles": [
{
"name": "Incident Manager"
}
],
"devicesSectionCollapsed": true,
"devicesSectionVisible": true
}' "https://acmeco.xmatters.com/api/xm/1/plans/512819e2-86d6-4a76-e126-b60f2c446e5d/subscription-forms"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/512819e2-86d6-4a76-e126-b60f2c446e5d/subscription-forms",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.name = 'Stellar App SEV-1';
data.description = 'Alerts subscribers when an event is created using any form in the plan';
data.scope = 'ALL_FORMS';
data.oneWay = true;
data.subscribeOthers = true;
data.notificationDelay = 5;
var propertyDefinitions = [];
propertyDefinitions.push(
{'id' : '8e84893b-e67c-41b6-b9c4-c2a421af5efe'}
);
propertyDefinitions.push(
{'name' : 'Customer impacting'}
);
data.propertyDefinitions = propertyDefinitions;
var roles = []
roles.push(
{'name' : 'Incident Manager'}
)
data.roles = roles;
data.devicesSectionCollapsed = true;
data.devicesSectionVisible = true;
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created subscription form: " + json.name + ". 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_URL = "/plans/512819e2-86d6-4a76-e126-b60f2c446e5d/subscription-forms"
url = base_URL + endpoint_URL
auth = ("username", "password")
data = {
"name": "Stellar App SEV-1",
"description": "Alerts subscribers when an event is created using any form in the plan",
"scope": "ALL_FORMS",
"oneWay": True,
"subscribeOthers": True,
"notificationDelay": 5,
"propertyDefinitions": [
{"id": "8e84893b-e67c-41b6-b9c4-c2a421af5efe"},
{"name": "Customer impacting"},
],
"roles": [{"name": "Incident Manager"}],
"devicesSectionCollapsed": True,
"devicesSectionVisible": True,
}
response = requests.post(url, json=data, auth=auth)
if response.status_code == 201:
print(
f"Created subscription form {response.json()['name']}. "
f"id = {response.json()['id']}"
)
else:
print(f"Error: Response code is: {response.status_code}")
REQUEST - Create a subscription form for a specific form in the plan This request shows how to create a subscription form that allows users to create subscriptions for a single form in the plan. This requires you to set the scope to FORM and identify the form in the request. Incident Managers and Group Supervisors can subscribe themselves only. A subset of devices is pre-selected; work email is not visible, meaning this device will always receive notifications based on this subscription form.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"name": "Stellar App Monitoring SEV-1",
"description": "Alerts subscribers when an event is created using the Stellar Monitoring form",
"scope": "FORM",
"form":
{
"id": "0fcc6b8c-2573-4651-87f4-ca030cbae057"
},
"oneWay": true,
"subscribeOthers": false,
"notificationDelay": 5,
"propertyDefinitions": [
{
"id": "8e84893b-e67c-41b6-b9c4-c2a421af5efe"
},
{
"name": "Customer impacting"
}
],
"roles": [
{
"name": "Incident Manager"
},
{
"name": "Group Supervisor"
}
],
"devicesSectionCollapsed": "true",
"devicesSectionVisible": "true",
"targetDeviceNames": [
{
"name": "iPhone",
"selected": true
},
{
"name": "Android Phone",
"selected": true
},
{
"name": "Work Email",
"selected": true,
"visible": false
}
]
}
}' "https://acmeco.xmatters.com/api/xm/1/plans/512819e2-86d6-4a76-e126-b60f2c446e5d/subscription-forms"
/**
* 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/512819e2-86d6-4a76-e126-b60f2c446e5d/subscription-forms",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.name = 'Stellar App Monitoring SEV-1';
data.description = 'Alerts subscribers when an event is created using the Stellar Monitoring form';
data.scope = 'FORM';
var form = {};
form.id = '0fcc6b8c-2573-4651-87f4-ca030cbae057';
data.form = form;
data.oneWay = true;
data.subscribeOthers = false;
data.notificationDelay = 5;
var propertyDefinitions = [];
propertyDefinitions.push(
{'id' : '8e84893b-e67c-41b6-b9c4-c2a421af5efe'}
);
propertyDefinitions.push(
{'name' : 'Customer impacting'}
);
data.propertyDefinitions = propertyDefinitions;
var roles = []
roles.push(
{'name' : 'Incident Manager'},
{'name' : 'Group Supervisor'}
)
data.roles = roles;
data.devicesSectionCollapsed: true,
data.devicesSectionVisible: true,
var targetDeviceNames = [];
targetDeviceNames.push(
{'name' : 'iPhone', 'selected' : true}
);
targetDeviceNames.push(
{'name' : 'Android Phone', 'selected' : true}
);
targetDeviceNames.push(
{'name' : 'Work Email', 'selected' : true, 'visible' : false}
);
data.targetDeviceNames = targetDeviceNames;
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created subscription form: " + json.name + ". 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_URL = "/plans/512819e2-86d6-4a76-e126-b60f2c446e5d/subscription-forms"
url = base_URL + endpoint_URL
auth = ("username", "password")
data = {
"name": "Stellar App Monitoring SEV-1",
"description": "Alerts subscribers when an event is created using the Stellar Monitoring form",
"scope": "FORM",
"form": {"id": "0fcc6b8c-2573-4651-87f4-ca030cbae057"},
"oneWay": True,
"subscribeOthers": False,
"notificationDelay": 5,
"propertyDefinitions": [
{"id": "8e84893b-e67c-41b6-b9c4-c2a421af5efe"},
{"name": "Customer impacting"},
],
"roles": [
{"name": "Incident Manager"}, {"name": "Group Supervisor"}],
"devicesSectionCollapsed": True,
"devicesSectionVisible": True,
"targetDeviceNames": [
{"name": "iPhone", "selected": True},
{"name": "Android Phone", "selected": True},
{"name": "Work Email","selected": True,"visible": False},
]
}
response = requests.post(url, json=data, auth=auth)
if response.status_code == 201:
print(
f"Created subscription form {response.json()['name']}. "
f"id = {response.json()['id']}"
)
else:
print("Error: Response code is: {response.status_code}")
{
"id": "8b9515cb-0fc8-4ca8-bc0e-7ebe36667919",
"name": "Stellar App Monitoring SEV-1",
"description": "Alerts subscribers when an event is created using the Stellar Monitoring form",
"plan": {
"id": "512819e2-86d6-4a76-a106-b60f2c446e4d",
"name": "Stellar App Status"
},
"scope": "FORM",
"form": {
"id": "0fcc6b8c-2573-4651-87f4-ca030cbae057",
"name": "Stellar app monitoring"
},
"created": "2020-04-09T22:06:02.724Z",
"oneWay": true,
"subscribeOthers": false,
"notificationDelay": 5,
"showNotificationDelay": true,
"propertyDefinitions": {
"count": 2,
"total": 2,
"data": [
{
"id": "9c2fe3b8-4bba-4399-b664-7939ec2d205a",
"propertyType": "BOOLEAN",
"name": "Customer impacting",
"description": "Whether the issue impacts customers",
"helpText": "",
"default": true
},
{
"id": "8e84893b-e67c-41b6-b9c4-c2a421af5efe",
"propertyType": "LIST_TEXT_SINGLE_SELECT",
"name": "Urgency",
"description": "Urgency to address the issue",
"helpText": "",
"default": "Medium",
"items": [
"Critical",
"High",
"Medium",
"Low"
]
}
]
},
"roles": {
"count": 1,
"total": 1,
"data": [
{
"id": "aef9d29d-bed4-3cb3-81df-4c8bc216330c",
"name": "Group Supervisor",
"description": "User can act as a Person Supervisor and also add and maintain groups."
}
]
},
"devicesSectionCollapsed": true,
"devicesSectionVisible": false,
"targetDeviceNames": {
"count": 3,
"total": 3,
"data": [
{
"deviceType": "ANDROID_PUSH",
"name": "Android Phone"
},
{
"deviceType": "APPLE_PUSH",
"name": "iPhone"
},
{...truncated list of targetDeviceNames objects...}
]
},
"visibleTargetDeviceNames": {
"count": 19,
"total": 3,
"data": [
{
"deviceType": "ANDROID_PUSH",
"name": "Android Phone"
},
{
"deviceType": "APPLE_PUSH",
"name": "iPhone"
},
{...truncated list of targetDeviceNames objects...}
]
},
"links": {
"self": "/api/xm/1/subscription-forms/8b9515cb-0fc8-4ca8-bc0e-7ebe36667919"
}
}
Creates a subscription form that allows users to subscribe to notifications created by forms in the plan.
You can create a subscription form for all forms in the plan or for a specific form. To specify a specific form, set the scope parameter to FORM, then include the form id in the form parameter.
When a user creates a subscription based on this form, they can edit the default values you provide.
DEFINITION
POST /plans/{planId}/subscription-forms
URL PARAMETERS
| planId | string |
The unique identifier (id) of the plan. |
BODY PARAMETERS
| name | string |
| The name of the subscription form, which must be unique within your company. This is the name users see when they first create a subscription based on the form (though they can change the name of their subscription). | |
| description | string |
| The description of the subscription form, which helps you and other users identify it. If not specified, the description is left blank. | |
| scope | string |
Whether subscriptions created using this subscription form send notifications of events from all forms in the plan or only a specific form. Valid values are:
form parameter. |
|
| form | ReferenceById object |
The communication plan form which subscriptions using this form are based on — only events created by the specified form result in a subscription notification. If you set scope to FORM, you need to specify a form using its id; otherwise do not include the form parameter in the request. |
|
| oneWay | Boolean |
If true, all subscriptions based on the form are read-only (with no response options shown). Set this to false if you want subscription notifications to include response options. If not specified, the default is false. |
|
| subscribeOthers | Boolean |
If true, subscription creators can subscribe other users, devices, and groups as recipients. If false, the creator can only subscribe themselves. If not specified, the default is false. |
|
| notificationDelay | integer |
| The number of minutes xMatters waits before sending the subscription notification. If not specified, the value is 0, meaning subscription notifications are sent without delay. | |
| propertyDefinitions | array [ReferenceById objects or ReferenceByName objects] |
The plan properties to set as the criteria users can create subscriptions against. If propertyDefintions are not specified, subscriptions created using the form are sent for every event. Specify the properties using name or id. For example:
|
|
| roles | array [ReferenceByName objects] |
The roles that can create subscriptions based on this form. Any user with one of the specified roles can use the form to create a subscription. If no role is specified, only the user who created the subscription form can use it. Specify the roles that can subscribe using the role name. For example:
|
|
| devicesSectionCollapsed | Boolean |
If true, the Devices section in the web user interface is collapsed when a user creates a subscription based on this form (the user can still expand the devices section and select or clear any devices that are visible). |
|
| devicesSectionVisible | Boolean |
If true, the Devices section is visible in the web user interface when a user creates a subscription based on this form, and the user can select or clear any devices that are visible. If false, the section is not visible and the devices notified are determined by the targetDeviceNames settings. |
|
| targetDeviceNames | array [targetDeviceName selector objects] |
| The devices that can receive notifications from subscriptions based on this form. If not specified, all devices names are selected and visible. If you include a device but don't set whether it's selected or visible, the device is selected and visible by default. If you set a device to selected but not visible, this will result in subscription notifications always being sent to that device. |
RESPONSES
| Success | Response code 201 Created and a Subscription Form object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a subscription form
Modify a subscription form
REQUEST - Modify a subscription form This request shows how to update a subscription form to allow a subscription creator to subscribe others and to add an additional property.
curl --user username --header "Content-Type: application/json" --request POST -d '{
"id": "8b9515cb-0fc8-4ca8-bc0e-7ebe36667919",
"scope": "FORM",
"form":
{
"id": "0fcc6b8c-2573-4651-87f4-ca030cbae057"
},
"subscribeOthers": true,
"propertyDefinitions": [
{
"id": "8e84893b-e67c-41b6-b9c4-c2a421af5efe"
},
{
"name": "Customer impacting"
},
{
"name": "Services affected"
}
]
}' "https://acmeco.xmatters.com/api/xm/1/plans/512819e2-86d6-4a76-e126-b60f2c446e5d/subscription-forms"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/plans/512819e2-86d6-4a76-e126-b60f2c446e5d/subscription-forms",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '0fcc6b8c-2573-4651-87f4-ca030cbae057';
data.scope = 'FORM';
var form = {};
form.id = '0fcc6b8c-2573-4651-87f4-ca030cbae057';
data.form = form;
data.subscribeOthers = true;
var propertyDefinitions = [];
propertyDefinitions.push(
{'id' : '8e84893b-e67c-41b6-b9c4-c2a421af5efe'}
);
propertyDefinitions.push(
{'name' : 'Customer impacting'}
);
propertyDefinitions.push(
{'name' : 'Services affected'}
);
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Updated subscription form: " + json.name + ". 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_URL = "/plans/512819e2-86d6-4a76-e126-b60f2c446e5d/subscription-forms"
url = base_URL + endpoint_URL
auth = ("username", "password")
data = {
"id": "8b9515cb-0fc8-4ca8-bc0e-7ebe36667919",
"scope": "FORM",
"form": {"id": "0fcc6b8c-2573-4651-87f4-ca030cbae057"},
"subscribeOthers": True,
"propertyDefinitions": [
{"id": "8e84893b-e67c-41b6-b9c4-c2a421af5efe"},
{"name": "Customer impacting"},
{"name": "Services affected"},
],
}
response = requests.post(url, json.data, auth=auth)
if response.status_code == 201:
print(
f"Updated subscription form {response.json()['name']}."
f"id = {response.json()['id']}"
)
else:
print("Error: Response code is: {response.status_code}")
RESPONSE See Create a subscription form for an example of the response object.
This endpoint lets you update a subscription form.
DEFINITION
POST /plans/{planId}/subscription-forms
URL PARAMETERS
| planId | string |
The unique identifier (id) of the plan. |
BODY PARAMETERS
The id of the subscription form you want to update is required. To update a subscription form that applies to a specific form in the communication plan, you must include both the scope and the form parameters. See the Create a subscription form body parameters for details on the other parameters you can change.
Any parameters not included in the update retain their current values. To update a single item in any of the array parameters (propertyDefinitons, roles, or targetDeviceNames), you must include any current values you want to retain; any values not included are removed. For example, say you have a subscription form that allows Incident Managers to create subscriptions and you want to add Group Supervisor to the list, you must include both Incident Manager and Group Supervisor in the roles parameter; otherwise Group Supervisor overwrites Incident Manager.
| id | string |
| The id (UUID) of the subscription form you want to update. To get the ID of a subscription form, use GET subscription forms in a plan or GET subscription forms. |
RESPONSES
| Success | Response code 200 OK and a Subscription Form object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Subscription form objects
Subscription form object
Subscription Form object
This example shows a subscription form object.
{
"id": "db962bcd-22e6-4c74-8193-93a64209051b",
"name": "North American Outages",
"description": "NA service outage stakeholder notifications",
"plan": {
"id": "8192a2ad-1531-42ab-8bfb-1eac133341a4",
"name": "Major Incident Notifications"
},
"scope": "FORM",
"form": {
"id": "7498c42c-8563-4b06-861e-80c4fda7bbee",
"name": "Internal Service Outage"
},
"created": "2018-11-15T21:10:03.321Z",
"oneWay": false,
"subscribeOthers": false,
"notificationDelay": 0,
"propertyDefinitions": {
"count": 2,
"total": 2,
"data": [
{
"id": "751be5e9-5106-4035-a04d-0e99d05ce3af",
"propertyType": "TEXT",
"name": "Description",
"description": "Enter the description of the issue",
"helpText": "Enter the description of the issue",
"default": "",
"maxLength": 2000,
"minLength": 0,
"pattern": "",
"validate": false
},
{
"id": "0b454ad5-1919-49bb-95a2-b9c2efad4f99",
"propertyType": "NUMBER",
"name": "Outage Minutes",
"description": "The number of minutes the services have been impacted.",
"helpText": "Specify the number of minutes the services have been impacted.",
"default": "1",
"maximum": 9999999,
"minimum": 1,
"units": "mins"
}
]
},
"roles": {
"count": 2,
"total": 2,
"data": [
{
"id": "dc3f02fd-4609-4a02-a791-affe0547ec3d",
"name": "Standard User"
},
{
"id": "47a7345d-28a3-439a-83be-005fee05764b",
"name": "REST Web Service User"
}
]
},
"targetDeviceNames": {
"count": 2,
"total": 2,
"data": [
{
"deviceType": "VOICE",
"name": "Mobile Phone",
"description": "Cell Phone"
},
{
"deviceType": "EMAIL",
"name": "Work Email",
"description": "Work Email Address"
},
]
},
"visibleTargetDeviceNames": {
"count": 2,
"total": 2,
"data": [
{
"deviceType": "VOICE",
"name": "Mobile Phone",
"description": "Cell Phone"
},
{
"deviceType": "EMAIL",
"name": "Work Email",
"description": "Work Email Address"
},
]
},
"links": {
"self": "/api/xm/1/subscription-forms/db962bcd-22e6-4c74-8193-93a64209051b"
}
}
Describes a subscription form used in a communication plan.
| id | string |
The unique identifier (id) of the form. |
|
| name | string |
| The name of the subscription 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). | |
| plan | PlanReference object |
| The communication plan the subscription form belongs to. | |
| scope | string |
Identifies whether subscriptions based on this subscription form can subscribe to events for a specific form, or all forms in the communication plan.
|
|
| form | FormReference object |
The form on which subscriptions must be based. (If FORM is specified for scope.) |
|
| created | string |
| The date and time the subscription form was created. | |
| oneWay | Boolean |
If true, the subscriptions based on this form are read-only. If false, subscriptions might offer response options. |
|
| subscribeOthers | Boolean |
If true, subscription creators can add other users, devices, and groups as subscribers. |
|
| notificationDelay | integer |
| The amount of time in minutes that xMatters waits before sending the notification. The notification is not delivered if the event is terminated before this time has elapsed. | |
| propertyDefinitions | Pagination of Property objects |
| The properties that are available to users when creating subscriptions based on the subscription form. | |
| roles | Pagination of Role objects |
| The roles that can create subscriptions based on this subscription form. | |
| targetDeviceNames | Pagination of DeviceName objects |
| A list of devices that can receive notifications from the subscriptions based on this subscription form. | |
| visibleTargetDeviceNames | Pagination of DeviceName objects |
| A list of available devices that are displayed to subscription creators. | |
| links | SelfLink object |
| A link that can be used to access this subscription form. |
Subscription Form Reference object
Subscription Form Reference object
This example shows a subscription form reference object.
"id": "92105ca8-7a69-4d71-a13c-8a66efg805f7",
"name": "All database issues",
"plan": {
"id": "330f9639-937d-499c-b66d-b44946584786",
"name": "IT Monitoring"
},
This provides basic information on the subscription form when returned in other requests, such as GET /subscriptions.
| id | string |
The unique identifier (id) of the subscription form. |
|
| name | string |
| The name of the subscription form. | |
| plan | Plan Reference object |
| The plan the subscription form belongs to. |
SUBSCRIPTIONS
Subscriptions allow you to receive notifications even if you are not targeted as a recipient of the event. Learn more about using, creating and managing subscriptions in the xMatters online help.
Get subscriptions
GET a list of subscriptions
REQUEST (get the subscriptions owned by Mary McBride based on the IT Communications subscription form)
curl --user username "https://acmeco.xmatters.com/api/xm/1/subscriptions?owner=mmcbride&subscriptionForm=IT%20Communications"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/subscriptions?owner=mmcbride&subscriptionForm=IT%20Communications",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " subscriptions." );
for (var i in json.data)
{
console.log(json.data[i].name + " with ID " + json.data[i].id + ".");
}
}
import requests
base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/subscriptions?owner=mmcbride&subscriptionForm=IT%20Communications'
url = base_URL + endpoint_URL
response = requests.get(url, auth=('username', 'password'))
if response.status_code == 200:
json = response.json()
print('Retrieved ' + str(json['count']) + ' of ' + str(json['total']) + ' subscriptions.')
for d in json['data']:
print(d['name'] + ' with ID ' + d['ID'] + '.')
RESPONSE
{
"count": 5,
"total": 5,
"data": [
{
"id": "3190215b-10fb-4740-84ff-926a4aaa51db",
"name": "All Oracle Priority issues",
"description": "Only alert for Sev 1 and Sev 2 issues on Oracle backbone",
"form": {
"id": "6fbefa73-558c-49c8-b098-7c817b49c08e",
"name": "DB Issues Alert",
"plan": {
"id": "330f9639-937d-499c-b66d-b44946584786",
"name": "IT Monitoring",
"links": {
"self": "/api/xm/1/plans/330f9639-937d-499c-b66d-b44946584786"
}
},
"links": {
"self": "/api/xm/1/subscription-forms/6fbefa73-558c-49c8-b098-7c817b49c08e"
}
},
"owner": {
"id": "d7bbbc6d-06f2-4eca-902a-f93ff165aa05",
"targetName": "mmcbride",
"firstName": "mary",
"lastName": "mcbride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/d7bbbc6d-06f2-4eca-902a-f93ff165aa05"
}
},
"created": "2017-12-08T22:27:14.516Z",
"notificationDelay": 5,
"criteria": {
"count": 2,
"total": 2,
"data": [
{
"name": "Database platform",
"operator": "IS_ONE_OF",
"value": "Oracle"
},
{
"name": "Severity",
"operator": "IS_ONE_OR_MORE_OF",
"value": "1-High,2-Med"
}
]
},
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "bf267877-2049-4924-bdcd-af161200bc63",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/bf267877-2049-4924-bdcd-af161200bc63"
},
"firstName": "mary",
"lastName": "mcbride",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "mmcbride",
"site": {
"id": "804d2646-0f16-dc49-d00a-2bce6eae2fa0",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/804d2646-0f16-dc49-d00a-2bce6eae2fa0"
}
},
"lastLogin": "2019-06-11T20:09:21.821Z",
"targeted": true,
"status": "ACTIVE",
}
]
"links": {
"self": "/api/xm/1/subscriptions/3190215b-10fb-4740-84ff-926a4aaa51db/subscribers?offset=0&limit=100"
}
},
"targetDeviceNames": {
"count": 5,
"total": 5,
"data": [
{
"deviceType": "ANDROID_PUSH",
"name": "Android Phone"
},
{
"deviceType": "EMAIL",
"name": "Work Email",
"description": "Work Email Address",
"domains": [
"example.com",
"xmatters.com"
]
},
{...truncated list of device names...},
]
},
"links": {
"self": "/api/xm/1/subscriptions/3190215b-10fb-4740-84ff-926a4aaa51db"
}
},
{...truncated list of subscription objects...},
"links": {"self": "/api/xm/1/subscritions?owner=mmcbride&subscriptionForm=oracle&offset=0&limit=10"}
}
Returns a list of subscriptions. You can use the query parameters to filter the results.
DEFINITION
GET /subscriptions
GET /subscriptions?subscriptionName=Oracle&subscriptionDescription=sev1&subscriptionForm=IT%20Communications
QUERY PARAMETERS
| owner | string |
The unique identifier (id) or name (targetName) of the owner of the subscription. Example: mmcbride Example: d7bbbc6d-06f2-4eca-902a-f93ff165aa05 |
|
| subscriber | string |
The unique identifier (id) or name (targetName) of a subscriber.Example: akaur Example: a608fa11-552a-4806-b247-48f083a20081 |
|
| sharedWith | string |
The unique identifier (id) or name (targetName) of a user the subscription is shared with. Example: asamara Example: 69173e7d-e4c5-4f48-b01c-b1dea1b587d7 |
|
| managedBy | string |
The unique identifier (id) or name (targetName) of a user that can manage the subscription. Example: cleroy Example: 4e1d8651-887e-4164-a511-1b7c98b1145a |
|
| subscriptionName | string |
| Specifies a term to search for in the subscription name. This filter is case-insensitive (in other words, "alpha" and "Alpha" both work) and must contain at least two characters. You can enter multiple words in the string to filter the results further (for example, use "Alpha" to find all subscriptions with "Alpha" in the name or use "Alpha alerts" to find only those with both words in the string. |
|
| subscriptionDescription | string |
Specifies a term to search for in the subscription description. Filters the results in the same way as subscriptionName but looks in the subscription description instead. |
|
| subscriptionForm | string |
Specifies a term to search for in the name of the subscription form the subscription is based on. Filters the results in the same way as subscriptionName but looks in the subscription form name instead.Use GET /subscription forms to find the name of a subscription form. |
|
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 Subscription objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get a subscription
GET a single subscription
REQUEST (get a single subscription)
curl --user username "https://acmeco.xmatters.com/api/xm/1/subscriptions/86b1c8aa-e581-4af1-8c42-3ba818bd28f6"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/subscriptions/86b1c8aa-e581-4af1-8c42-3ba818bd28f6",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved subscription" + json.name + " with ID " + json.id + "." )
}
import requests
base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/subscriptions/86b1c8aa-e581-4af1-8c42-3ba818bd28f6'
url = base_URL + endpoint_URL
response = requests.get(url, auth=('username', 'password'))
if response.status_code == 200:
json = response.json()
print('Retrieved subscription' + str(json['name']) + ' with ID ' + str(json['id']) + '.')
RESPONSE
{
"id": "3190215b-10fb-4740-84ff-926a4aaa51db",
"name": "All Oracle Priority issues",
"description": "Only alert for Sev 1 and Sev 2 issues on Oracle backbone",
"form": {
"id": "6fbefa73-558c-49c8-b098-7c817b49c08e",
"name": "DB Issues Alert",
"plan": {
"id": "330f9639-937d-499c-b66d-b44946584786",
"name": "IT Monitoring"
},
"links": {
"self": "/api/xm/1/subscription-forms/6fbefa73-558c-49c8-b098-7c817b49c08e"
}
},
"owner": {
"id": "d7bbbc6d-06f2-4eca-902a-f93ff165aa05",
"targetName": "mmcbride",
"firstName": "mary",
"lastName": "mcbride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/d7bbbc6d-06f2-4eca-902a-f93ff165aa05"
}
},
"created": "2017-12-08T22:27:14.516Z",
"notificationDelay": 5,
"criteria": {
"count": 2,
"total": 2,
"data": [
{
"name": "Database platform",
"operator": "IS_ONE_OF",
"value": "Oracle"
},
{
"name": "Severity",
"operator": "IS_ONE_OR_MORE_OF",
"value": "1-High,2-Med"
}
]
},
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "acab0309-12e6-4bd7-bb92-56448c5d96b8",
"targetName": "DB-Admins",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": true,
"useDefaultDevices": true,
"observedByAll": true,
"description": "Group of users who are admins for any of the databases",
"links": {
"self": "/api/xm/1/groups/acab0309-12e6-4bd7-bb92-56448c5d96b8"
},
"targeted": true
}
]
},
"targetDeviceNames": {
"count": 5,
"total": 5,
"data": [
{
"deviceType": "ANDROID_PUSH",
"name": "Android Phone"
},
{
"deviceType": "EMAIL",
"name": "Work Email",
"description": "Work Email Address",
"domains": [
"example.com",
"xmatters.com"
]
},
{...truncated list of DeviceNames...}
]
},
"links": {
"self": "/api/xm/1/subscriptions/3190215b-10fb-4740-84ff-926a4aaa51db"
}
}
Returns information on a single subscription.
DEFINITION
GET /subscriptions/{subscriptionId}
QUERY PARAMETERS
| id | string |
The unique identifier (id) of the subscription. Example: 6c96a506-a111-4f64-81ca-859b687dd61e |
RESPONSES
| Success | Response code 200 OK and a Subscription object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Get subscribers
GET all subscribers for a single subscription
REQUEST (get all subscribers for a single subscription)
curl --user username "https://acmeco.xmatters.com/api/xm/1/subscriptions/86b1c8aa-e581-4af1-8c42-3ba818bd28f6/subscribers"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/subscriptions/86b1c8aa-e581-4af1-8c42-3ba818bd28f6/subscribers",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " subscribers." );
for (var i in json.data)
{
console.log(json.data[i].targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
import json
subscriptionId = "86b1c8aa-e581-4af1-8c42-3ba818bd28f6"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/subscriptions/" + subscriptionId + "/subscribers"
url = base_URL + endpoint_URL + "?offset-0&limit=2"
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 "
+ str(rjson["count"])
+ " of "
+ str(rjson["total"])
+ " subscribers."
)
for d in rjson["data"]:
print(
"Found subscriber with name: "
+ d["targetName"]
+ "\tand id: "
+ d["id"]
+ ", of type: "
+ d["recipientType"]
)
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
{
"count": 2,
"total": 2,
"data": [
{
"id": "bf267877-2049-4924-bdcd-af161200bc63",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/bf267877-2049-4924-bdcd-af161200bc63"
},
"firstName": "mary",
"lastName": "mcbride",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "mmcbride",
"site": {
"id": "804d2646-0f16-dc49-d00a-2bce6eae2fa0",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/804d2646-0f16-dc49-d00a-2bce6eae2fa0"
}
},
"lastLogin": "2019-06-11T20:09:21.821Z",
"targeted": true,
"status": "ACTIVE"
},
{
"id": "bf267877-2049-4924-bdcd-af161200bc63",
"targetName": "ssmith",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/bf267877-2049-4924-bdaa-af161224bc64"
},
"firstName": "stuart",
"lastName": "smith",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "ssmith24",
"site": {
"id": "804d2646-0f16-dc49-d00a-5bce6eae233a3",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/804d2646-0f16-dc49-d00a-5bce6eae233a3"
}
},
"lastLogin": "2019-06-11T20:09:21.821Z",
"targeted": true,
"status": "ACTIVE"
}
],
"links": {
"self": "/api/xm/1/subscriptions/b34062b8-266b-4c9a-9706-13f70751e6d8/subscribers?offset=0&limit=100"
}
}
Returns a list of all users who subscribe to a subscription. Authenticating users must have permission to see subscribers. Roles without appropriate permission settings receive an error message in the return.
DEFINITION
GET /subscriptions/{subscriptionId}/subscribers
QUERY PARAMETERS
| id | string |
The unique identifier (id) of the subscription. Example: 6c96a506-a111-4f64-81ca-859b687dd61e |
|
| 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 pagenated 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. |
Get subscription share permissions
GET subscription share permissions
REQUEST (get the subscription share permissions for a single subscription)
curl --user username "https://acmeco.xmatters.com/api/xm/1/subscriptions/4148d1d8-83ab-4f0e-b0b2-cf53cabdc4df/share-permissions"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/subscriptions/4148d1d8-83ab-4f0e-b0b2-cf53cabdc4df/share-permissions",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved subscription share permissions" + json.name + " with ID " + json.id + "." )
}
import requests
base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/subscriptions/4148d1d8-83ab-4f0e-b0b2-cf53cabdc4df/share-permissions'
url = base_URL + endpoint_URL
response = requests.get(url, auth=('username', 'password'))
if response.status_code == 200:
json = response.json()
print('Retrieved subscription share permissions' + str(json['name']) + ' with ID ' + str(json['id']) + '.')
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"shareType": "PERSON",
"sharedWith": {
"id": "d233d991-692f-46aa-8144-bb794977b51a",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/d233d991-692f-46aa-8144-bb794977b51a"
}
},
"permissibleActions": {
"subscribe": true,
"subscribeOthers": false,
"viewSubscription": true,
"editSubscription": false
}
},
{
"shareType": "ROLE",
"sharedWith": {
"id": "aef9d29d-bed4-3cb3-81df-4c8bc216330c",
"name": "Group Supervisor"
},
"permissibleActions": {
"subscribe": true,
"subscribeOthers": false,
"viewSubscription": true,
"editSubscription": true
}
}
],
"links": {
"self": "/api/xm/1/subscriptions/4148d1d8-83ab-4f0e-b0b2-cf53cabdc4df/share-permissions?offset=0&limit=100"
}
}
Returns information on the users and roles who have permission to view, edit, and share the subscription.
DEFINITION
GET /subscriptions/{subscriptionId}/share-permissions
QUERY PARAMETERS
| id | string |
The unique identifier (id) of the subscription. Example: 6c96a506-a111-4f64-81ca-859b687dd61e |
RESPONSES
| Success | Response code 200 OK and a pagenation of Subscription permissions objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a subscription
REQUEST - Create a subscription This request shows how to add a new subscription to your system.
curl --user username --header "Content-Type: application/json" --request POST -d
'{
"name": "Quarterly Sales Goals",
"description": "Compiliation of sales targets for Northwest stores",
"form": {
"id": "254cf49f-0a79-4eb5-8784-5f3ea590f2b8"
},
"owner": {
"id": "67d25090-23a1-405b-96b8-0f19f4e28328"
},
"notificationDelay": 0,
"criteria": [
{
"name": "Incident Description",
"operator": "CONTAINS",
"value": "Some Text"
},
{
"name": "Resolved",
"operator": "IS_TRUE"
},
{
"name": "Incident Impact",
"operator": "IS_ONE_OF",
"values": ["Core System"]
},
{
"name": "Line of Business (LOB)",
"operator": "IS_ONE_OR_MORE_OF",
"values": ["Card Services"]
},
{
"name": "Services",
"operator": "IS_ONE_TYPE_OF",
"value": "External"
}
],
"recipients": [
{
"id": "67d25090-23a1-405b-96b8-0f19f4e28328"
}
],
"targetDeviceNames": [
{
"name": "Home Email"
},
{
"name": "Work Email"
}
]
}
'
"https://acmeco.xmatters.com/api/xm/1/subscriptions"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var data = {};
data.name = 'P1 and P2 in New Jersey';
data.description = 'My test subscription api';
data.notificationDelay = '0';
var form = {};
form.id = '254cf49f-0a79-4eb5-8784-5f3ea590f2b8';
data.form = form;
var owner = {};
owner.id = '67d25090-23a1-405b-96b8-0f19f4e28328';
data.owner = owner;
var criteria = [];
var criteria1 = {};
criteria1.name = 'Incident Description';
criteria1.operator = 'CONTAINS';
criteria1.value = 'Text';
criteria.push(criteria1);
var criteria2 = {};
criteria2.name = 'Resolved';
criteria2.operator = 'IS_TRUE';
criteria.push(criteria2);
var criteria3 = {};
criteria3.name = 'Incident Impact';
criteria3.operator = 'IS_ONE_OF';
criteria3.values = ['Core Services'];
criteria.push(criteria3);
var criteria4 = {};
criteria4.name = 'Line of Business (LOB)';
criteria4.operator = 'IS_ONE_OR_MORE_OF';
criteria4.values = ['Card Services'];
criteria.push(criteria4);
var criteria5 = {};
criteria5.name = 'Services';
criteria5.operator = 'IS_ONE_TYPE_OF';
criteria5.value = 'External';
criteria.push(criteria5);
data.criteria = criteria;
var recipients = [];
recipients.push( {'id' : '67d25090-23a1-405b-96b8-0f19f4e28328'} );
data.recipients = recipients;
var targetDeviceNames = [];
targetDeviceNames.push( {'name' : 'Home Email'} );
targetDeviceNames.push( {'name' : 'Work Email'} );
data.targetDeviceNames = targetDeviceNames;
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/subscriptions",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created " + response.json()["targetName"] + ". id = " + response.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 = '/subscriptions'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
data = {
"name": "Quarterly Sales Goals",
"description": "Compiliation of sales targets for Northwest stores",
"form": {"id": "254cf49f-0a79-4eb5-8784-5f3ea590f2b8"},
"owner": {"id": "67d25090-23a1-405b-96b8-0f19f4e28328"},
"notificationDelay": 0,
"criteria": [
{"name": "Incident Description", "operator": "CONTAINS", "value": "Some Text"},
{"name": "Resolved", "operator": "IS_TRUE"},
{"name": "Incident Impact", "operator": "IS_ONE_OF", "values": ["Core System"]},
{
"name": "Line of Business (LOB)",
"operator": "IS_ONE_OR_MORE_OF",
"values": ["Card Services"],
},
{"name": "Services", "operator": "IS_ONE_TYPE_OF", "value": "External"},
],
"recipients": [{"id": "67d25090-23a1-405b-96b8-0f19f4e28328"}],
"targetDeviceNames": [{"name": "Home Email"}, {"name": "Work Email"}],
}
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('Subscription ' + rjson.get('name') + ' was successfully added. The subscription object is:\n' + json.dumps(rjson, indent=4, sort_keys=True) )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"id": "0444383f-4ae7-42e6-aa44-adaffc577eb5",
"name": "Quarterly Sales Goals",
"description": "Compiliation of sales targets for Northwest stores",
"form": {
"id": "254cf49f-0a79-4eb5-8784-5f3ea590f2b8",
"name": "All Incident Communications",
"plan": {
"id": "53de64dd-4143-4e5b-bf64-8a45f19d58cb",
"name": "Incident Management"
},
"links": {
"self": "/api/xm/1/subscription-forms/254cf49f-0a79-4eb5-8784-5f3ea590f2b8"
}
},
"owner": {
"id": "4d0402d5-791e-46d3-b723-654c2f6b47bb",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/4d0402d5-791e-46d3-b723-654c2f6b47bb"
}
},
"created": "2019-02-14T22:53:27.600Z",
"notificationDelay": 0,
"criteria": {
"count": 5,
"total": 5,
"data": [{
"name": "Resolved",
"operator": "IS_TRUE"
},
{
"name": "Incident Description",
"operator": "CONTAINS",
"value": "Some Text"
},
{
"name": "Incident Impact",
"operator": "IS_ONE_OF",
"value": "Core System"
},
{
"name": "Line of Business (LOB)",
"operator": "IS_ONE_OR_MORE_OF",
"value": "Card Services"
},
{
"name": "Services",
"operator": "IS_ONE_TYPE_OF",
"value": "External"
}
]
},
"recipients": {
"count": 1,
"total": 1,
"data": [{
"id": "4d0402d5-791e-46d3-b723-654c2f6b47bb",
"targetName": "jsmith",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/4d0402d5-791e-46d3-b723-654c2f6b47bb"
},
"firstName": "John",
"lastName": "Smith",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "jsmith",
"site": {
"id": "804d2646-0f16-dc49-d00a-2bce6eae2fa0",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/804d2646-0f16-dc49-d00a-2bce6eae2fa0"
}
},
"properties": {
"Incident Manager": false,
"checkbox": false
},
"targeted": true,
"status": "ACTIVE"
}]
},
"targetDeviceNames": {
"count": 2,
"total": 2,
"data": [{
"deviceType": "EMAIL",
"name": "Home Email",
"description": "Home Email Address"
},
{
"deviceType": "EMAIL",
"name": "Work Email",
"description": "Work Email Address"
}
]
},
"links": {
"self": "/api/xm/1/subscriptions/0444383f-4ae7-42e6-aa44-adaffc577eb5"
}
}
This endpoint allows users with appropriate permission settings to create subscriptions. You must have a subscription form created in the web user interface before you can create a subscription. Use Get subscription forms in a plan to get the UUID of the subsciption form.
DEFINITION
POST /subscriptions
BODY PARAMETERS
| name | string |
| The user-provided name of the subscription. | |
| description | string |
| The user-provided description of the subscription. | |
| form | Subscription Form object |
| Provides information on the form the subscription is based on. | |
| owner | PersonReference object |
| The id (UUID) of the person who owns the subscription. | |
| notificationDelay | integer |
| The delay in minutes after the initial event notification before the subscription notification is sent. | |
| criteria | SubscriptionCriteria object |
| The criteria being used to determine whether or not the subscription notification is sent. | |
| recipients | ReferenceById object |
| The list of ids (UUID) of the people, groups, or devices that will receive notifications for this subscription. | |
| targetDeviceNames | array [DeviceName object] |
Defines the devices that can be targeted by notifications from this subscription. For example Home Email |
RESPONSES
| Success | Response code 201 Created and a Subscription object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Modify a subscription
Modify a subscription
REQUEST This example shows how to change the owner of a subscription
curl -H "Content-Type: application/json" --user "username" -d '{ "id":"b4eb7b68-3fee-47e4-8a62-ebfa8edae670", "targetAllDevices":false, "targetDeviceNames":[{"name":"Mobile Phone"}] }' https://acmeco.xmatters.com/api/xm/1/subscriptions
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/subscriptions",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.id = '0444383f-4ae7-42e6-aa44-adaffc577eb5';
data.name = 'P1 and P2 in New Jersey';
data.description = 'My test subscription api';
data.notificationDelay = '0';
var form = {};
form.id = '254cf49f-0a79-4eb5-8784-5f3ea590f2b8';
data.form = form;
var owner = {};
owner.id = '67d25090-23a1-405b-96b8-0f19f4e28328';
data.owner = owner;
var criteria = [];
var criteria1 = {};
criteria1.name = 'Incident Description';
criteria1.operator = 'CONTAINS';
criteria1.value = 'Text';
criteria.push(criteria1);
var criteria2 = {};
criteria2.name = 'Resolved';
criteria2.operator = 'IS_TRUE';
criteria.push(criteria2);
var criteria3 = {};
criteria3.name = 'Incident Impact';
criteria3.operator = 'IS_ONE_OF';
criteria3.values = ['Core Services'];
criteria.push(criteria3);
var criteria4 = {};
criteria4.name = 'Line of Business (LOB)';
criteria4.operator = 'IS_ONE_OR_MORE_OF';
criteria4.values = ['Card Services'];
criteria.push(criteria4);
var criteria5 = {};
criteria5.name = 'Services';
criteria5.operator = 'IS_ONE_TYPE_OF';
criteria5.value = 'External';
criteria.push(criteria5);
data.criteria = criteria;
var recipients = [];
recipients.push( {'id' : '67d25090-23a1-405b-96b8-0f19f4e28328'} );
data.recipients = recipients;
var targetDeviceNames = [];
targetDeviceNames.push( {'name' : 'Home Email'} );
targetDeviceNames.push( {'name' : 'Work Email'} );
data.targetDeviceNames = targetDeviceNames;
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created " + response.json()["targetName"] + ". id = " + response.json()["id"]);
}
# This script is configured to work with Python v3.6 and later.
import requests
from requests.auth import HTTPBasicAuth
import json
base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/subscriptions'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
data = {
"id": "b4eb7b68-3fee-47e4-8a62-ebfa8edae670",
"targetAllDevices":False,
"targetDeviceNames":[
{"name":"Mobile Phone"}
]
}
data_string = json.dumps(data)
response = requests.post(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if (responseCode == 200):
rjson = response.json();
print('Subscription ' + rjson.get('name') + ' was successfully added. The subscription object is:\n' + json.dumps(rjson, indent=4, sort_keys=True) )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"id": "b4eb7b68-3fee-47e4-8a62-ebfa8edae670",
"name": "Quarterly Sales Goals",
"description": "Compiliation of sales targets for Northwest stores",
"form": {
"id": "254cf49f-0a79-4eb5-8784-5f3ea590f2b8",
"name": "test-subscription",
"plan": {
"id": "568914c3-e08d-412f-b0ad-72a8eee3dc99",
"name": "Sample Plan"
},
"links": {
"self": "/api/xm/1/subscription-forms/254cf49f-0a79-4eb5-8784-5f3ea590f2b8"
}
},
"owner": {
"id": "67d25090-23a1-405b-96b8-0f19f4e28328",
"targetName": "jsmith",
"firstName": "john",
"lastName": "smith",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/67d25090-23a1-405b-96b8-0f19f4e28328"
}
},
"created": "2019-04-26T22:48:04.354Z",
"notificationDelay": 0,
"criteria": {
"count": 2,
"total": 2,
"data": [
"name": "Incident Description",
"operator": "CONTAINS",
"value": "Some Text"
},
{
"name": "Resolved",
"operator": "IS_TRUE"
}
]
},
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "67d25090-23a1-405b-96b8-0f19f4e28328",
"targetName": "bsmith",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/67d25090-23a1-405b-96b8-0f19f4e28328"
},
"firstName": "Bob",
"lastName": "Smith",
"language": "en",
"timezone": "Canada/Pacific",
"webLogin": "bsmith",
"site": {
"id": "3b2be179-b98d-4bbe-a1db-f7172411e3f8",
"name": "Vancouver",
"links": {
"self": "/api/xm/1/sites/3b2be179-b98d-4bbe-a1db-f7172411e3f8"
}
},
"properties": {
"Incident Manager": false,
"checkbox": false
},
"targeted": true,
"status": "ACTIVE"
}
]
},
"targetDeviceNames": {
"count": 1,
"total": 1,
"data": [
{
"deviceType": "VOICE",
"name": "Mobile Phone",
"description": "Cell Phone"
}
]
},
"links": {
"self": "/api/xm/1/subscriptions/b4eb7b68-3fee-47e4-8a62-ebfa8edae670"
}
}'
This endpoint allows a user with appropriate permissions to modify settings for a subscription, such as changing the owner, updating the recipients list or device names. The request must include the subscription ID, and any other properties that are to be modified. The form itself cannot be modified, and the request must not include the form property.
DEFINITION
POST /subscriptions
BODY PARAMETERS
| id | string |
The unique identifier (id) of the subscription. Example: 6c96a506-a111-4f64-81ca-859b687dd61e Use Get subscriptions to find the subscription ID. |
|
| name | string |
| The user-provided name of the subscription. | |
| description | string |
| The user-provided description of the subscription. | |
| owner | PersonReference object |
| The id (UUID) of the person who owns the subscription. | |
| notificationDelay | integer |
| The delay in minutes after the initial event notification before the subscription notification is sent. | |
| criteria | SubscriptionCriteria object |
| The criteria being used to determine whether or not the subscription notification is sent. | |
| recipients | ReferenceById object |
| The list of ids (UUID) of the people, groups, or devices that will receive notifications for this subscription. | |
| 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 from this subscription. For example Home Email |
RESPONSES
| Success | Response code 200 OK and a Subscription object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Add subscribers
REQUEST - Add subscribers Add subscribers to an existing subscription in your system.
curl --user username --header "Content-Type: application/json" --request PUT -d
'{
"recipients":
[
{"id": "87819792-382d-438d-ae58-4753a265fdb3"},
{"id": "dbe5f254-e85e-4368-8cfb-15d2609457e4"}
]
}'
"https://acmeco.xmatters.com/api/xm/1/subscriptions/4f9e90da-1034-4e5b-a71e-db0b67850867/subscribers"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
const recipients = [
{ id: '87819792-382d-438d-ae58-4753a265fdb3' },
{ id: 'dbe5f254-e85e-4368-8cfb-15d2609457e4' },
];
const apiRequest = http.request({
endpoint: 'xMatters',
path:
'/api/xm/1/subscriptions/4f9e90da-1034-4e5b-a71e-db0b67850867/subscribers',
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
});
const apiResponse = apiRequest.write({ recipients });
if (apiResponse.statusCode === 200) {
//As needed, parse the response for logging, assigning step output values, etc.,
}
#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 = '/subscriptions/4f9e90da-1034-4e5b-a71e-db0b67850867/subscribers'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
data = {
"recipients":
[
{"id": "87819792-382d-438d-ae58-4753a265fdb3"},
{"id": "dbe5f254-e85e-4368-8cfb-15d2609457e4"}
]
}
data_string = json.dumps(data)
response = requests.put(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if (responseCode == 200):
rjson = response.json();
print('Subscribers ' + rjson.get('name') + ' were successfully added. The subscription object is:\n' + json.dumps(rjson, indent=4, sort_keys=True) )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"id": "87819792-382d-438d-ae58-4753a265fdb3",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/87819792-382d-438d-ae58-4753a265fdb3"
},
"firstName": "Mary",
"lastName": "McBride",
"licenseType": "FULL_USER",
"language": "en",
"timezone": "US/Eastern",
"webLogin": "mmcbride",
"site": {
"id": "804d2646-0f16-dc49-d00a-2bce6eae2fa0",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/804d2646-0f16-dc49-d00a-2bce6eae2fa0"
}
},
"lastLogin": "2021-10-01T17:54:34.964Z",
"whenCreated": "2020-08-13T22:29:01.541Z",
"whenUpdated": "2021-10-01T17:54:34.967Z",
"targeted": true,
"status": "ACTIVE"
},
{
"id": "dbe5f254-e85e-4368-8cfb-15d2609457e4",
"targetName": "MIM Team 1",
"recipientType": "GROUP",
"status": "ACTIVE",
"externallyOwned": false,
"allowDuplicates": true,
"useDefaultDevices": true,
"observedByAll": true,
"description": "",
"links": {
"self": "/api/xm/1/groups/dbe5f254-e85e-4368-8cfb-15d2609457e4"
},
"created": "2021-04-25T04:37:17.059Z",
"groupType": "ON_CALL",
"targeted": true
},
],
"links": {
"self": "/api/xm/1/subscriptions/4f9e90da-1034-4e5b-a71e-db0b67850867/subscribers?offset=0&limit=100"
}
}
This endpoint allows users with appropriate permission settings to add recipients to an existing subscription. To add recipients, the subscription form must have the subscribeOthers field set to true.
DEFINITION
PUT /subscriptions/{subscriptionId}/subscribers
URL PARAMETERS
| subscriptionId | string |
The unique identifier (id) of the subscription. Example: 6c96a506-a111-4f64-81ca-859b687dd61e |
BODY PARAMETERS
| recipients | array [Recipient object] |
The unique identifier or id of the notification recipient. Recipients can be users, groups, or devices. |
RESPONSES
| Success | Response code 200 OK and a Pagination of Recipient objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Set subscription share permissions
REQUEST - Set subscription share permissions Set which users and roles can subscribe, view, edit, and share a subscription.
curl --user username --header "Content-Type: application/json" --request PUT -d
'{
[
{
"shareType": "PERSON",
"sharedWith": {
"id": "87819792-382d-438d-ae58-4753a265fdb3"
},
"permissibleActions": {
"subscribe": true,
"subscribeOthers": false,
"viewSubscription": true,
"editSubscription": false
}
},
{
"shareType": "ROLE",
"sharedWith": {
"id": "44baca28-65f1-44ed-81e1-0318be8903c2",
"name": "Communication Center User"
},
"permissibleActions": {
"subscribe": true,
"subscribeOthers": false,
"viewSubscription": true,
"editSubscription": true
}
}
]
}'
"https://acmeco.xmatters.com/api/xm/1/subscriptions/4148d1d8-83ab-4f0e-b0b2-cf53cabdc4df/share-permissions"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
const permissions = [
{
shareType: 'PERSON',
sharedWith: {
id: '87819792-382d-438d-ae58-4753a265fdb3'
},
permissibleActions: {
subscribe: true,
subscribeOthers: false,
viewSubscription: true,
editSubscription: false
}
},
{
shareType: 'ROLE',
sharedWith: {
id: '44baca28-65f1-44ed-81e1-0318be8903c2',
name: 'Communication Center User'
},
permissibleActions: {
subscribe: true,
subscribeOthers: false,
viewSubscription: true,
editSubscription: true
}
}
]
const apiRequest = http.request({
endpoint: 'xMatters',
path:
'/api/xm/1/subscriptions/4148d1d8-83ab-4f0e-b0b2-cf53cabdc4df/share-permissions',
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
});
const apiResponse = apiRequest.write({ permissions });
if (apiResponse.statusCode === 200) {
//As needed, parse the response for logging, assigning step output values, etc.,
}
#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 = '/subscriptions/4148d1d8-83ab-4f0e-b0b2-cf53cabdc4df/share-permissions'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
data = [
{
"shareType": "PERSON",
"sharedWith": {
"id": "87819792-382d-438d-ae58-4753a265fdb3"
},
"permissibleActions": {
"subscribe": true,
"subscribeOthers": false,
"viewSubscription": true,
"editSubscription": false
}
},
{
"shareType": "ROLE",
"sharedWith": {
"id": "44baca28-65f1-44ed-81e1-0318be8903c2",
"name": "Communication Center User"
},
"permissibleActions": {
"subscribe": true,
"subscribeOthers": false,
"viewSubscription": true,
"editSubscription": true
}
}
]
data_string = json.dumps(data)
response = requests.put(url, headers=headers, data=data_string, auth=auth)
responseCode = response.status_code
if (responseCode == 200):
rjson = response.json();
print('Subscription permissions were successfully added. The subscription permission object is:\n' + json.dumps(rjson, indent=4, sort_keys=True) )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"shareType": "PERSON",
"sharedWith": {
"id": "87819792-382d-438d-ae58-4753a265fdb3",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/87819792-382d-438d-ae58-4753a265fdb3"
}
},
"permissibleActions": {
"subscribe": true,
"subscribeOthers": false,
"viewSubscription": true,
"editSubscription": false
}
},
{
"shareType": "ROLE",
"sharedWith": {
"id": "44baca28-65f1-44ed-81e1-0318be8903c2",
"name": "Communication Center User"
},
"permissibleActions": {
"subscribe": true,
"subscribeOthers": false,
"viewSubscription": true,
"editSubscription": true
}
}
],
"links": {
"self": "/api/xm/1/subscriptions/4148d1d8-83ab-4f0e-b0b2-cf53cabdc4df/share-permissions?offset=0&limit=100"
}
}
This endpoint allows users with appropriate permission settings to set which users and roles can subscribe (and unsubscribe), view, edit, and share the subscription. The users and roles in the provided list overwrite all previously stored share permissions for the subscription.
DEFINITION
PUT /subscriptions/{subscriptionId}/share-permissions
URL PARAMETERS
| subscriptionId | string |
The unique identifier (id) of the subscription. Example: 6c96a506-a111-4f64-81ca-859b687dd61e |
BODY PARAMETERS
| shareType | string |
| Identifies whether the listed permissions apply to a single user or to all users with a specific role. Available values are: PERSON, ROLE. | |
| sharedWith | string |
The unique identifier (uuid) or target name of the user or role the subscription is shared with. The sharedWith parameter must match the shareType parmeter. For example, if the shareType is ROLE, you must supply the uuid or target name of an existing role in xMatters. |
|
| permissibleActions | Boolean |
The permission settings for the subscription. Available values are:
|
RESPONSES
| Success | Response code 200 OK and a Pagination of Subscription permissions objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a subscription
Delete a subscription
REQUEST: The following example describes how to delete a subscription.
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/subscriptions/0444383f-4ae7-42e6-aa44-adaffc577eb5"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/subscriptions/0444383f-4ae7-42e6-aa44-adaffc577eb5",
"method": "DELETE",
"headers" : {"Content-Type": "application/json"}
});
response = request.write();
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted the " + json.targetName + "subscription");
}
import requests
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/subscriptions"
subscription_ID = "/0444383f-4ae7-42e6-aa44-adaffc577eb5"
url = base_URL + endpoint_URL + subscription_ID
response = requests.delete(url, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Deleted the " + json.targetName + "subscription");
RESPONSE
{
{
"id": "0444383f-4ae7-42e6-aa44-adaffc577eb5",
"name": "Quarterly Sales Goals",
"description": "Compliation of sales targest for Northwest stores",
"form": {
"id": "254cf49f-0a79-4eb5-8784-5f3ea590f2b8",
"name": "All Incident Communications",
"plan": {
"id": "53de64dd-4143-4e5b-bf64-8a45f19d58cb",
"name": "Incident Management"
},
"links": {
"self": "/api/xm/1/subscription-forms/254cf49f-0a79-4eb5-8784-5f3ea590f2b8"
}
},
"owner": {
"id": "4d0402d5-791e-46d3-b723-654c2f6b47bb",
"targetName": "xm-rest",
"firstName": "xM",
"lastName": "REST",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/4d0402d5-791e-46d3-b723-654c2f6b47bb"
}
},
"created": "2019-02-14T22:53:27.600Z",
"notificationDelay": 0,
"criteria": {
"count": 5,
"total": 5,
"data": [
{
"name": "Resolved",
"operator": "IS_TRUE"
},
{
"name": "Incident Description",
"operator": "CONTAINS",
"value": "Some Text"
},
{
"name": "Incident Impact",
"operator": "IS_ONE_OF",
"value": "Core System"
},
{
"name": "Line of Business (LOB)",
"operator": "IS_ONE_OR_MORE_OF",
"value": "Card Services"
},
{
"name": "Services",
"operator": "IS_ONE_TYPE_OF",
"value": "External"
}
]
},
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "4d0402d5-791e-46d3-b723-654c2f6b47bb",
"targetName": "xm-rest",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/4d0402d5-791e-46d3-b723-654c2f6b47bb"
},
"firstName": "xM",
"lastName": "REST",
"language": "en",
"timezone": "US/Pacific",
"webLogin": "xm-rest",
"site": {
"id": "804d2646-0f16-dc49-d00a-2bce6eae2fa0",
"name": "Default Site",
"links": {
"self": "/api/xm/1/sites/804d2646-0f16-dc49-d00a-2bce6eae2fa0"
}
},
"targeted": true,
"status": "ACTIVE"
}
]
},
"targetDeviceNames": {
"count": 2,
"total": 2,
"data": [
{
"deviceType": "EMAIL",
"name": "Home Email",
"description": "Home Email Address"
},
{
"deviceType": "EMAIL",
"name": "Work Email",
"description": "Work Email Address"
}
]
},
"links": {
"self": "/api/xm/1/subscriptions/0444383f-4ae7-42e6-aa44-adaffc577eb5"
}
},
}
This endpoint allows a user with the appropriate permissions to delete a single subscription from the system.
DEFINITION
DELETE /subscriptions/{subscriptionId}
URL PARAMETERS
| subscriptionId | string |
The unique identifier (id) of the subscription. To find the subscription ID, use Get subscriptions.Example: 6c96a506-a111-4f64-81ca-859b687dd61e |
RESPONSES
| Success | Response code 200 OK and a Subscription object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Unsubscribe a user
Unsubscribe a user
REQUEST: The following example shows how to unsubscribe a user from a subscription.
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/subscriptions/0444383f-4ae7-42e6-aa44-adaffc577eb5/subscribers/4d0402d5-791e-46d3-b723-654c2f6b47bb"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/subscriptions/0444383f-4ae7-42e6-aa44-adaffc577eb5/subscribers/4d0402d5-791e-46d3-b723-654c2f6b47bb",
"method": "DELETE",
"headers" : {"Content-Type": "application/json"}
});
response = request.write();
if (response.statusCode == 200){
json = JSON.parse(response.body);
console.log("Deleted subscriber " + subscriber + " from subscription " + subscription);
}
import requests
subscription = "0444383f-4ae7-42e6-aa44-adaffc577eb5"
subscriber = "9c96a50b-a041-6g62-a1c6-255b877ab61f"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
subscription_URL = "/subscriptions/" + subscription
subscriber_URL = "/subscribers/" + subscriber
url = base_URL + subscription_URL + subscriber_URL
response = requests.delete(url, auth=("username", "pa$$w0rd"))
if response.status_code == 200:
print("Deleted subscriber " + subscriber + " from subscription " + subscription)
RESPONSE
{
{
"id": "0444383f-4ae7-42e6-aa44-adaffc577eb5",
"name": "Quarterly Sales Goals",
"description": "Compliation of sales targest for Northwest stores",
"form": {
"id": "254cf49f-0a79-4eb5-8784-5f3ea590f2b8",
"name": "All Incident Communications",
"plan": {
"id": "53de64dd-4143-4e5b-bf64-8a45f19d58cb",
"name": "Incident Management"
},
"links": {
"self": "/api/xm/1/subscription-forms/254cf49f-0a79-4eb5-8784-5f3ea590f2b8"
}
},
"owner": {
"id": "4d0402d5-791e-46d3-b723-654c2f6b47bb",
"targetName": "xm-rest",
"firstName": "xM",
"lastName": "REST",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/4d0402d5-791e-46d3-b723-654c2f6b47bb"
}
},
"created": "2019-02-14T22:53:27.600Z",
"notificationDelay": 0,
"criteria": {
"count": 5,
"total": 5,
"data": [
{
"name": "Resolved",
"operator": "IS_TRUE"
},
{
"name": "Incident Description",
"operator": "CONTAINS",
"value": "Some Text"
},
{
"name": "Incident Impact",
"operator": "IS_ONE_OF",
"value": "Core System"
},
{
"name": "Line of Business (LOB)",
"operator": "IS_ONE_OR_MORE_OF",
"value": "Card Services"
},
{
"name": "Services",
"operator": "IS_ONE_TYPE_OF",
"value": "External"
}
]
},
"targetDeviceNames": {
"count": 2,
"total": 2,
"data": [
{
"deviceType": "EMAIL",
"name": "Home Email",
"description": "Home Email Address"
},
{
"deviceType": "EMAIL",
"name": "Work Email",
"description": "Work Email Address"
}
]
},
"links": {
"self": "/api/xm/1/subscriptions/0444383f-4ae7-42e6-aa44-adaffc577eb5"
}
},
}
This endpoint describes how a user with appropriate permissions can unsubscribe a single user from a single subscription. Although the delete command is used, the subscription itself is not deleted. To delete a subscription, see Delete a subscription.
DEFINITION
DELETE /subscriptions/{subscriptionId}/subscribers/{personId}
URL PARAMETERS
| subscriptionId | string |
The unique identifier (id) of the subscription. To find the subscription ID, use Get subscriptions.Example: 6c96a506-a111-4f64-81ca-859b687dd61e |
|
| personID | string |
The unique identifier (id) of the person you want to remove from the subscription. To find the person ID, use Get people.Example: 9c96a50b-a041-6g62-a1c6-255b877ab61f |
RESPONSES
| Success | Response code 200 OK and a Subscription object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Subscription objects
Subscription object
Subscription object
This example shows a single subscription object.
{
"id": "3190215b-10fb-4740-84ff-926a4aaa51db",
"name": "All Oracle Sev 1 issues",
"description": "Only send subscription notification for Sev 1 issues on an Oracle backbone",
"form": {
"id": "6fbefa73-558c-49c8-b098-7c817b49c08e",
"name": "DB Issues Alert",
"plan": {
"id": "330f9639-937d-499c-b66d-b44946584786",
"name": "IT Monitoring"
},
"links": {
"self": "/api/xm/1/subscription-forms/6fbefa73-558c-49c8-b098-7c817b49c08e"
}
},
"owner": {
"id": "d7bbbc6d-06f2-4eca-902a-f93ff165aa05",
"targetName": "asamara",
"firstName": "ali",
"lastName": "samara",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/d7bbbc6d-06f2-4eca-902a-f93ff165aa05"
}
},
"created": "2019-01-21T23:12:39.456Z",
"notificationDelay": 5,
"criteria": {
"count": 2,
"total": 2,
"data": [
{
"name": "Database platform",
"operator": "IS_ONE_OF",
"value": "Oracle"
},
{
"name": "Severity",
"operator": "IS_ONE_OR_MORE_OF",
"value": "1-High,2-Med"
}
]
},
"recipients": {
"count": 1,
"total": 1,
"data": [
{
"id": "d7bbbc6d-06f2-4eca-902a-f93ff165aa05",
"targetName": "mmcbride",
"recipientType": "PERSON",
"externallyOwned": false,
"links": {
"self": "/api/xm/1/people/d7bbbc6d-06f2-4eca-902a-f93ff165aa05"
},
"firstName": "mary",
"lastName": "mcbride",
"language": "en",
"timezone": "America/Canada",
"webLogin": "mmcbride",
"site": {
"id": "fd7cc28c-06bc-4985-b052-6ca2ba409b23",
"name": "Toronto",
"links": {
"self": "/api/xm/1/sites/fd7cc28c-06bc-4985-b052-6ca2ba409b23"
}
},
"targeted": true,
"status": "ACTIVE"
}
]
},
"targetDeviceNames": {
"count": 5,
"total": 5,
"data": [
{
"deviceType": "ANDROID_PUSH",
"name": "Android Phone"
},
{...truncated list of DeviceNames...}
]
},
"links": {
"self": "/api/xm/1/subscriptions/3190215b-10fb-4740-84ff-926a4aaa51db"
}
},
Describes a subscription, including its id, name, the subscription form used, and the criteria being evaluated.
| id | string |
The unique identifier (id) of the subscription. |
|
| name | string |
| The user-provided name of the subscription. | |
| description | string |
| The user-provided description of the subscription. | |
| form | Subscription Form object |
| Provides information on the subscription form the subscription is based on. | |
| owner | PersonReference |
| The person who owns the subscription. | |
| created | string |
| The date and time the subscription was created. | |
| notificationDelay | integer |
| The delay in minutes after the initial event notification before the subscription notification is sent. | |
| criteria | Pagination of SubscriptionCriteriaReference objects |
| The criteria being used to determine whether or not the subscription notification is sent. | |
| recipients | Pagination of Person objects |
| The list of recipients targeted by the subscription. | |
| targetDeviceNames | Pagination of DeviceName objects |
| A list of device names the subscription notification is configured to deliver to. | |
| links | SelfLink object |
| A link that can be used to reference the subscription. |
SubscriptionCriteria Reference object
SubscriptionCriteriaReference object
{
{
"name": "text",
"operator": "CONTAINS",
"value": "5"
},
{
"name": "list",
"operator": "IS_ONE_OR_MORE_OF",
"values": [
"1",
"2",
"3"
]
}
}
Describes one of the criteria being used to determine if the subscription notification is delivered.
| name | string |
| The name of the property to be evaluated. | |
| operator | string |
How the property is being evaluated. The following operators accept a single value:
The following operators accept multiple values:
Not all operators apply to all property types. |
|
| value | string |
The value to evaluate the criteria against. You can submit single values with the following operators:
Boolean properties do not list a value because they are only evaluated as true, false, or both. |
|
| values | array [string] |
The values to evaluate the criteria against. You can only submit multiple values with the following operators:
|
Subscription Permissions object
Subscription Permissions object
[
{
"shareType": "PERSON",
"sharedWith": {
"id": "87819792-382d-438d-ae58-4753a265fdb3",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/87819792-382d-438d-ae58-4753a265fdb3"
}
},
"permissibleActions": {
"subscribe": true,
"subscribeOthers": false,
"viewSubscription": true,
"editSubscription": false
}
},
{
"shareType": "ROLE",
"sharedWith": {
"id": "44baca28-65f1-44ed-81e1-0318be8903c2",
"name": "Communication Center User"
},
"permissibleActions": {
"subscribe": true,
"subscribeOthers": false,
"viewSubscription": true,
"editSubscription": true
}
}
],
Describes one of the criteria being used to set share permissions for a subscription.
| shareType | string |
| Identifies whether the listed permissions apply to a single user or to all users with a specific role. Available values are: PERSON, ROLE. | |
| sharedWith | string |
The unique identifier (uuid)or target name of the user or role the subscription is shared with. The sharedWith parameter must match the shareType parmeter. For example, if the shareType is ROLE, you must supply the uuid or target name of an existing role in xMatters. |
|
| permissibleActions | Boolean |
The permission settings for the subscription. Available values are:
|
TEMPORARY ABSENCES
Temporary absences allow you to add an absence in a user's schedule during times when they're unavailable to receive or act on notifications. (For example, when a user requests vacation time, calls in sick, or is temporarily assigned to another role.) When creating a temporary absence, you can choose to set a replacement to receive notifications on the user's behalf.
For more information on how temporary absences and replacement users work, see the xMatters online help.
Get temporary absences
GET temporary absences
REQUEST Get temporary absences for a specific user, including absences that apply to all groups or a specified group.
curl --user username
"https://acmeco.xmatters.com/api/xm/1/temporary-absences?member=baf8ae6e-96ee-4cf7-83b2-2b89401444b1&groups=Antares%20Service%20Support"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/temporary-absences?member=baf8ae6e-96ee-4cf7-83b2-2b89401444b1&groups=Antares%20Service%20Support",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " temporary absences." );
for (var i in json.data)
{
console.log(json.data[i].member.targetName + " on " + json.data[i].group.targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/temporary-absences?member=baf8ae6e-96ee-4cf7-83b2-2b89401444b1&groups=Antares%20Service%20Support'
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']) + " temporary absences.")
for d in json['data']:
print (d['member']['targetName'] + " on " + d['group']['targetName'])
REQUEST Get all temporary absences where a replacement is specified.
curl --user username
"https://acmeco.xmatters.com/api/xm/1/temporary-absences?absenceType=REPLACEMENT"
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/temporary-absences?absenceType=REPLACEMENT",
"method": "GET"
});
var response = request.write();
if (response.statusCode == 200 ) {
json = JSON.parse(response.body);
console.log("Retrieved " + json.count + " of " + json.total + " temporary absences." );
for (var i in json.data)
{
console.log(json.data[i].replacement.targetName + " filling in for " + json.data[i].member.targetName);
}
}
import requests
from requests.auth import HTTPBasicAuth
base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/temporary-absences?absenceType=REPLACEMENT'
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']) + " temporary absences.")
for d in json['data']:
print (d['replacement']['targetName'] + " filling in for " + d['member']['targetName'])
RESPONSE
{
"count": 2,
"total": 2,
"data": [
{
"id": "9c8c9169-229c-45ad-afd5-fb1f90227954",
"start": "2018-09-05T08:30:00.000Z",
"end": "2018-09-06T17:30:00.000Z",
"member": {
"id": "baf8ae6e-96ee-4cf7-83b2-2b89401444b1",
"targetName": "smccumber",
"firstName": "Sean",
"lastName": "McCumber",
"recipientType": "PERSON",
"status": "ACTIVE",
"links": {
"self": "/api/xm/1/people/baf8ae6e-96ee-4cf7-83b2-2b89401444b1"
}
},
"group": {
"id": "d2d79866-6094-444e-ab78-d9c52f45bc3a",
"targetName": "Antares Service Support",
"recipientType": "GROUP",
"status": "ACTIVE",
"links": {
"self": "/api/xm/1/groups/d2d79866-6094-444e-ab78-d9c52f45bc3a"
}
},
"replacement": {
"id": "e50b73ef-7428-404e-a65a-56279c915730",
"targetName": "nedwards",
"firstName": "Nicole",
"lastName": "Edwards",
"recipientType": "PERSON",
"status": "ACTIVE",
"links": {
"self": "/api/xm/1/people/e50b73ef-7428-404e-a65a-56279c915730"
}
},
"absenceType": "REPLACEMENT",
"links": {
"self": "/api/xm/1/temporary-absences/9c8c9169-229c-45ad-afd5-fb1f90227954"
}
},
{...truncated list of absences...}
],
}
Returns a list of current and upcoming temporary absences for all users you have permission to see, including their start and end times, and any temporary replacements for the absent user.
The start and end times are defined in universal time (UTC) format and may not reflect the time zone of the authenticating user, the absent user, or the replacement. To limit the results to a specific timeframe, use the from and to query parameters.
All query parameters are optional; you can use them to fine-tune the results you receive.
DEFINITION
GET /temporary-absences
GET /temporary-absences?member=baf8ae6e-96ee-4cf7-83b2-2b89401444b1&groups=Antares%20Service
GET /temporary-absences?absenceType=VACANCY&from=2020-01-01T00:00:00.000Z&to=2020-01-31T00:00:00.000Z
QUERY PARAMETERS
| member | string |
The id of the user whose temporary absences you want to retrieve. |
|
| groups | string |
The id or targetName of the groups you want to retrieve absence information for. Separate multiple groups with a comma. Absences that apply to all groups also appear in the response. |
|
| absenceType | string |
The type of absence you want to retrieve:
|
|
| from | string |
A date-time value in UTC format that defines the beginning of the time range to search. When used with the to parameter, the response includes all absences in the specified time range. Example: 2018-12-01T04:00:00 |
|
| to | string |
A date-time value in UTC format that defines the end of the time range. When used with the from parameter, the response includes all absences in the specified time range. Example:2018-12-15T04:00:00 |
|
| 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 Temporary Absence objects in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Create a temporary absence
POST temporary absence
REQUEST Create a temporary absence
This request shows how to create a temporary absence for a user in a particular group, with a replacement specified. This example doesn't include anid, so xMatters generates anidfor the temporary absence and returns it in theidfield of the response.
curl --user username --header "Content-Type: application/json" --request POST -d '{
{
"absenceType": "REPLACEMENT",
"start": "2018-09-05T08:30:00.000Z",
"end": "2018-09-06T17:30:00.0000Z",
"member": "baf8ae6e-96ee-4cf7-83b2-2b89401444b1",
"group": "d2d79866-6094-444e-ab78-d9c52f45bc3a",
"replacement": "9b3555c9-c9fa-4951-9b24-2238a3b47134"
}
"https://acmeco.xmatters.com/api/xm/1/temporary-absences"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/temporary-absences",
"method": "POST",
"headers" : {"Content-Type": "application/json"}
});
var data = {};
data.absenceType = 'REPLACEMENT';
data.start: '2018-09-05T08:30:00.000Z';
data.end: '2018-09-06T17:30:00.0000Z';
data.member: 'baf8ae6e-96ee-4cf7-83b2-2b89401444b1';
data.group: 'd2d79866-6094-444e-ab78-d9c52f45bc3a';
data.replacement: '9b3555c9-c9fa-4951-9b24-2238a3b47134';
response = request.write(data);
if (response.statusCode == 201) {
json = JSON.parse(response.body);
console.log( "Created temporary replacement: " + json.member.targetName + " is being replaced by " + json.replacement.targetName);
}
#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 = '/temporary-absences'
url = base_URL + endpoint_URL
auth = HTTPBasicAuth('username', 'password')
headers = {'Content-Type': 'application/json'}
data = {
"absenceType": "REPLACEMENT",
"start": "2019-06-05T08:30:00.000Z",
"end": "2019-06-06T17:30:00.0000Z",
"member": "baf8ae6e-96ee-4cf7-83b2-2b89401444b1",
"replacement": "e50b73ef-7428-404e-a65a-56279c915730"
}
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('Temporary absence ' + rjson.get('id') + ' was successfully added. The object is:\n' + json.dumps(rjson, indent=4, sort_keys=True) )
else:
print('The request did not succeed. Response code is: ' + str(responseCode) )
RESPONSE
{
"id": "9c8c9169-229c-45ad-afd5-fb1f90227954",
"start": "2018-09-05T08:30:00.000Z",
"end": "2018-09-06T17:30:00.000Z",
"member": {
"id": "baf8ae6e-96ee-4cf7-83b2-2b89401444b1",
"targetName": "smccumber",
"firstName": "Sean",
"lastName": "McCumber",
"recipientType": "PERSON",
"status": "ACTIVE",
"links": {
"self": "/api/xm/1/people/baf8ae6e-96ee-4cf7-83b2-2b89401444b1"
}
},
"group": {
"id": "d2d79866-6094-444e-ab78-d9c52f45bc3a",
"targetName": "ITAdmin",
"recipientType": "GROUP",
"status": "ACTIVE",
"links": {
"self": "/api/xm/1/groups/d2d79866-6094-444e-ab78-d9c52f45bc3a"
}
},
"replacement": {
"id": "9b3555c9-c9fa-4951-9b24-2238a3b47134",
"targetName": "nedwards",
"firstName": "Nicole",
"lastName": "Edwards",
"recipientType": "PERSON",
"status": "ACTIVE",
"links": {
"self": "/api/xm/1/people/e50b73ef-7428-404e-a65a-56279c915730"
}
},
"includeDirectNotification": "false",
"absenceType": "REPLACEMENT"
"links": {
"self": "/api/xm/1/temporary-absences/9c8c9169-229c-45ad-afd5-fb1f90227954"
}
Creates a temporary absence for an xMatters user, either with or without a replacement. Your company may require you to specify a replacement.
If you want to set up an absence for multiple groups, but not all, or you want to name different replacements for different groups, you need to send multiple requests.
The response returns a Temporary Absence object.
DEFINITION
POST /temporary-absences
BODY PARAMETERS
| id | string |
| If you provide a UUID (for example, if you want the id to match a value in an external system), xMatters attempts to use this value as the unique identifier for the absence. If this value is not provided, xMatters generates a UUID. 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. | |
| absenceType | string |
This value sets the absence type.
|
|
| member | string |
The id of the absent person. |
|
| start | string |
| A date-time value in UTC format that defines the start of the start of the absence. This value cannot be in the past. Example:2018-02-23T04:00:00 is not an acceptable value as it occurs in the past. | |
| end | string |
| A date-time value in UTC format that defines the end of the absence. This value cannot be in the past, and cannot be more than 90 days in the future. | |
| group | string |
The id of the group the absence applies to. If you include a group, the absence and any specified replacement apply only to that group. If you don't include a group, the absence and the specified replacement (if set) apply to all groups the absent user is a member of. |
|
| includeDirectNotifications | Boolean |
When set to true, notifications that target you directly (not as part of a group) are sent to your specified replacement or discarded if a replacement is not set. This parameter can only be set to true when the absence applies to all groups. The default value is false. |
|
| replacement | string |
The id of the person replacing the absent user. You must set this if the absenceType is set to REPLACEMENT. |
RESPONSES
| Success | Response code 200 OK and a Temporary Absence object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Delete a temporary absence
DELETE a temporary absence
REQUEST (delete a temporary absence)
curl --user username --request DELETE
"https://acmeco.xmatters.com/api/xm/1/temporary-absences/9c8c9169-229c-45ad-afd5-fb1f90227954"
/**
* This script is configured to work with xMatters Flow Designer.
* Configure the "xMatters" endpoint to use a valid username and password.
*/
var request = http.request({
"endpoint": "xMatters",
"path": "/api/xm/1/temporary-absences/9c8c9169-229c-45ad-afd5-fb1f90227954",
"method": "DELETE",
"headers" : {"Content-Type": "application/json"}
});
response = request.write();
if (response.statusCode == 200) {
json = JSON.parse(response.body);
console.log("Deleted temporary absence " + json.absenceId + " for " json.member.targetName);
}
import requests
from requests.auth import HTTPBasicAuth
import json
absenceId = "9c8c9169-229c-45ad-afd5-fb1f90227954"
base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/temporary-absences/" + absenceId
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(
"Temporary absence "
+ 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": "9c8c9169-229c-45ad-afd5-fb1f90227954",
"start": "2018-09-05T08:30:00.000Z",
"end": "2018-09-06T17:30:00.000Z",
"member": {
"id": "baf8ae6e-96ee-4cf7-83b2-2b89401444b1",
"targetName": "smccumber",
"firstName": "Sean",
"lastName": "McCumber",
"recipientType": "PERSON",
"status": "ACTIVE",
"links": {
"self": "/api/xm/1/people/baf8ae6e-96ee-4cf7-83b2-2b89401444b1"
}
},
"group": {
"id": "d2d79866-6094-444e-ab78-d9c52f45bc3a",
"targetName": "ITAdmin",
"recipientType": "GROUP",
"status": "ACTIVE",
"links": {
"self": "/api/xm/1/groups/d2d79866-6094-444e-ab78-d9c52f45bc3a"
}
},
"replacement": {
"id": "e50b73ef-7428-404e-a65a-56279c915730",
"targetName": "nedwards",
"firstName": "Nicole",
"lastName": "Edwards",
"recipientType": "PERSON",
"status": "ACTIVE",
"links": {
"self": "/api/xm/1/people/e50b73ef-7428-404e-a65a-56279c915730"
}
},
"absenceType": "REPLACEMENT"
}
Deletes a temporary absence for a user using the temporary absence's unique ID.
The response returns a Temporary absence object that represents the deleted absence.
DEFINITION
DELETE /temporary-absences/{temporaryAbsenceId}
URL PARAMETERS
| {temporaryAbsenceId} | string |
The unique identifier (id) of the absence. |
RESPONSES
| Success | Response code 200 OK and a Temporary Absence object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Temporary absence objects
Temporary absence object
Temporary absence object that only applies to one group and has a replacement specified
{
"id": "9c8c9169-229c-45ad-afd5-fb1f90227954",
"start": "2018-09-05T08:30:00.000Z",
"end": "2018-09-06T17:30:00.000Z",
"member": {
"id": "baf8ae6e-96ee-4cf7-83b2-2b89401444b1",
"targetName": "smccumber",
"firstName": "Sean",
"lastName": "McCumber",
"recipientType": "PERSON",
"status": "ACTIVE",
"links": {
"self": "/api/xm/1/people/baf8ae6e-96ee-4cf7-83b2-2b89401444b1"
}
},
"group": {
"id": "d2d79866-6094-444e-ab78-d9c52f45bc3a",
"targetName": "ITAdmin",
"recipientType": "GROUP",
"status": "ACTIVE",
"links": {
"self": "/api/xm/1/groups/d2d79866-6094-444e-ab78-d9c52f45bc3a"
}
},
"replacement": {
"id": "e50b73ef-7428-404e-a65a-56279c915730",
"targetName": "nedwards",
"firstName": "Nicole",
"lastName": "Edwards",
"recipientType": "PERSON",
"status": "ACTIVE",
"links": {
"self": "/api/xm/1/people/e50b73ef-7428-404e-a65a-56279c915730"
}
},
"includeDirectNotifications": "false",
"absenceType": "REPLACEMENT"
}
Describes a temporary absence, including the group it applies to (if it doesn't apply to all) and any replacement that was set.
| id | string |
The unique identifier (id) of the absence. |
|
| absenceType | string |
The type of absence:
|
|
| member | PersonReference |
| The user that is absent. | |
| start | string |
| A date-time value in UTC format that defines the start of the start of the absence.Example:2017-02-23T04:00:00Z | |
| end | string |
| A date-time value in UTC format that defines the end of the absence. Example:2017-02-26T04:00:00Z | |
| group | GroupReference |
| The group the absence applies to if it doesn't apply to all groups the user belongs to. If the absence applies to more than one group (but not all), a separate absence record is returned for each group. | |
| includeDirectNotifications | Boolean |
When set to true, notifications that target you directly (not as part of a group) are sent to your specified replacement or discarded if a replacement is not set. This parameter can only be set to true when the absence applies to all groups. The default value is false. |
|
| replacement | PersonReference |
| The person that is replacing the absent user. This section is only returned if a replacement is specified. |
UPLOAD USERS
The following endpoints allow you to quickly import data into xMatters from external sources. You can use the User Upload endpoint to import user data from a spreadsheet, or use the EPIC ZipSync endpoint to synchronize user, group, and site data with an external system.
All imported files must be either User Upload template v1.5 .csv or EPIC ZipSync v1.3 .zip files.
For more information on uploading user data, see the xMatters online help for User Upload Information or EPIC ZipSync information.
Upload a User Upload file
Upload a User Upload template file
REQUEST (import a file of user data) The following example shows how to add users to xMatters by importing a .csv or .txt multi-part form file.
curl https://acmeco.xmatters.com/api/xm/1/uploads/users-v1 \
-X POST \
-H "Content-Type: multipart/form-data" \
-F "name=Upload 1" \
-F "file=@user_data.csv" \
--user $USERNAME:$PASSWORD
/**
* As multi-part forms are not supported, this feature is not available in the Integration Builder.
*/
#The following code is formatted to work with Python v.3.6 and later.
import requests
username = "replace-me"
password = "replace-me"
base_url = "https://acmeco.xmatters.com/api/xm/1"
endpoint_url = "/uploads/users-v1"
url = base_url + endpoint_url
headers = {"Content-Type": "multipart/form-data"}
user_data_filename = "user_data.csv"
data = {"file": open(user_data, "rb").read(), "name": "Upload 1"}
# print("Data file contains: " + data)
response = requests.post(url, files=[data], auth=(username, password))
print("Received response with status code: " + response.status_code)
print("Response JSON object is: " + response.json())
RESPONSE
{
"id": "461c2ff8-09e2-4e89-9c32-69155a0a0669",
"name": "Upload 1",
"transform": {
"name": "User Upload v1.5",
"url": "https://acmeco.xmatters.com/api/xm/1/uploads/users-v1"
},
"status": "PENDING",
"started": "2019-02-04T23:07:20.211Z",
"by": {
"id": "fada8bdf-98ea-4e87-a57e-54b282c9ed93",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/fada8bdf-98ea-4e87-a57e-54b282c9ed93"
}
},
"totalCount": 227,
"processedCount": 0,
"links": {
"self": "/api/xm/1/imports/461c2ff8-09e2-4e89-9c32-69155a0a0669"
}
}
Uploads a user upload v1.5 template file and creates a user upload job that performs an asynchronous bulk import of user data. Upload files must be in .csv format.
To support the upload, this POST operation does not use the typical JSON format, but instead requires a multipart/form-data content type. Once a file has been processed, you can use its import id to review any error or warning messages generated during processing.
DEFINITION
POST /uploads/users-v1
BODY PARAMETERS
| file | string |
| The CSV multi-part form you want to upload. | |
| name | string |
| The unique name of the import job. If a name is not specified, the default name is: "User Upload v1.5 at {date/timestamp}". |
RESPONSES
| Success | Response code 202 Accepted and an Import job object object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |
Upload an EPIC ZipSync file
Upload an EPIC ZipSync file
REQUEST (import an EPIC ZipSync file in .csv format)
curl https://acmeco.xmatters.com/api/xm/1/uploads/epic-v1 \
-X POST \
-H "Content-Type: multipart/form-data" \
-F "file=@epic_zipsync.zip" \
--user $USERNAME:$PASSWORD
/**
* As multi-part forms are not supported, this feature is not available in the Integration Builder.
*/
#The following code is formatted to work with Python v.3.6 and later.
import requests
username = "replace-me"
password = "replace-me"
base_url = "https://acmeco.xmatters.com/api/xm/1"
endpoint_url = "/uploads/epic-v1"
url = base_url + endpoint_url
headers = {"Content-Type": "multipart/form-data"}
user_data_filename = "epic_zipsync.zip"
data = {"file": open(user_data_filename, "rb").read()}
# print("Data file contains: " + data)
response = requests.post(url, files=[data], auth=(username, password))
print("Received response with status code: " + response.status_code)
print("Response JSON object is: " + response.json())
RESPONSE
{
"id": "461c2ff8-09e2-4e89-9c32-69155a0a0669",
"transform": {
"name": "EPIC Upload v1.3",
"url": "https://acmeco.xmatters.com/api/xm/1/uploads/epic-v1"
},
"status": "PENDING",
"lastUpdatedAt": "2019-02-04T23:07:20.211Z",
"by": {
"id": "fada8bdf-98ea-4e87-a57e-54b282c9ed93",
"targetName": "mmcbride",
"firstName": "Mary",
"lastName": "McBride",
"recipientType": "PERSON",
"links": {
"self": "/api/xm/1/people/fada8bdf-98ea-4e87-a57e-54b282c9ed93"
}
},
"totalCount": 0,
"processedCount": 0,
"links": {
"self": "/api/xm/1/imports/461c2ff8-09e2-4e89-9c32-69155a0a0669"
}
}
Uploads an EPIC ZipSync file to merge user data from an external system into xMatters.
Previously, sending EPIC files required the use of the downloadable EPIC client, which was not feasible for some of our clients. Uploading EPIC ZipSync files through the xMatters REST API removes the need for the EPIC client.
To support the upload, this POST operation does not use the typical JSON format, but instead requires a multipart/form-data content type to accept EPIC ZipSync files.
For more information on EPIC, see Synchronize user data with EPIC.
You can download a set of sample files (previously distributed as part of the EPIC client) to use as a template when creating your ZipSync files.
DEFINITION
POST /uploads/epic-v1
BODY PARAMETERS
| file | string |
| The EPIC file you want to upload. Upload files must be formatted for ZipSync version 1.3 format and cannot be larger than 150 MB. |
RESPONSES
| Success | Response code 202 Accepted and an Import job object in the response body. |
| Error | For a list of response codes returned by the xMatters REST API, see HTTP Response Codes. |