NAV

User Name

Host Name

cURL Python JavaScript

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:

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:

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.

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:

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:

GETReturns a description of a resource.
POSTCreates or updates a resource.
DELETEDeletes a resource.

Identifying resources

{
  "targetName" : "mmcbride",
  "id" : "031313cc-42d3-4703-a90e-36cc5f5f6209"
}

This API provides two ways of identifying resources:

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 OKResource was retrieved or deleted successfully.
201 CreatedResource was created successfully.
204 No ContentA resource was not found in response to a DELETE request.
400 Bad RequestRequest is malformed. This often occurs when there is an error in the request such as referring to an object that does not exist.
401 UnauthorizedUser authentication failed.
403 ForbiddenAuthenticated 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 foundThe 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 acceptableThe requested media type is not supported. This API supports application/JSON only.
409 ConflictThe 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 TypeThe media type in the request body is not supported. This API supports application/JSON only.
429 Too many requestsThe 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.
{
  "links": 
  {
    "self": "/api/xm/1/people?offset=100&limit=100",
    "previous": "/api/xm/1/people?offset=0&limit=100",
    "next": "/api/xm/1/people?offset=200&limit=100"
  }
}

Provides links to the current, previous, and next pages of a paginated result set. See also Results pagination.

   
next string
A link to the next page of results.
previous string
A link to the previous page of results.
self string
A link to this page of results.

Recipient object

See Group object, Device object, Person object, or Dynamic team object.

A recipient is a user, group, device or dynamic team in xMatters that can receive notifications. The recipient object provides a base for Group object, Device object, Person object, and Dynamic team object.

   
id string
A unique identifier that represents the recipient.
targetName string
The common name of the recipient.
recipientType string
The type of this object. Values include:
  • "GROUP"
  • "PERSON"
  • "DEVICE"
  • "DYNAMIC_TEAM"
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:
  • "ACTIVE"
  • "INACTIVE"
Note: this field is not included with dynamic teams because they are always active.
links SelfLink object
A link that can be used to access the object from within the API.
{
  "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.
{
  "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:
  • mmcbride
  • mmcbride|Work Email
  • Oracle Administrators
  • 438e9245-b32d-445f-916bd3e07932c892
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:
  • "PERSON"
  • "GROUP"
  • "DEVICE"
responseCount| integer | Used when specifying group recipients when triggering forms that have response counts enabled. Sets the number of responses that must be received from this group (or dyanmic team) before xMatters stops notifying additional group members.

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:

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.
ErrorFor 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.

QueryParamReturned AuditDescription
EVENT_ANNOTATEDAudit annotationComments (annotations) entered for the event.
EVENT_CREATEDAudit objectAudit information about when the event was created.
EVENT_SUSPENDEDAudit objectAudit information about when the event was suspended.
EVENT_RESUMEDAudit objectAudit information about when a suspended event was resumed.
EVENT_COMPLETEDAudit objectAudit information about when the event was completed.
EVENT_TERMINATEDAudit objectAudit information about when the event was terminated.
RESPONSE_RECEIVEDResponseThe 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:
  • "24abd4c0-bff3-4381-9f84-678580b24428"
  • "408005"

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.
  • EVENT_ANNOTATED: retrieves event comments (annotations)
  • EVENT_CREATED: retrieves when the event was created
  • EVENT_SUSPENDED: retrieves when an event was suspended
  • EVENT_RESUMED: retrieves when an event resumed
  • EVENT_COMPLETED: retrieves when an event was completed
  • EVENT_TERMINATED: retrieves when an event was terminated
  • RESPONSE_RECEIVED: retrieves the response option a recipient selected when responding to a notification, as well as any comments added when responding using the mobile app
sortOrder string
Sets whether audits are sorted in ascending or descending order by their creation timestamp. Valid values include:
  • "ASCENDING"
  • "DESCENDING"
If not specified, results are sorted in ascending order.

RESPONSES

Success Response code 200 OK and a Pagination of Audit objects of type Response and Audit annotation.
ErrorFor 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_ANNOTATED
  • EVENT_CREATED
  • EVENT_SUSPENDED
  • EVENT_RESUMED
  • EVENT_COMPLETED
  • EVENT_TERMINATED
  • RESPONSE_RECEIVED
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:
  • "BROWSER"
  • "IOS"
  • "ANDROID"
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:
  • "PERSON"
  • "DEVICE"
recipient Recipient object
The recipient of the notification.
deliveryStatus string
Whether the response was delivered to the recipient. Valid values include:
  • "DELIVERED"
  • "FAILED"
  • "RESPONDED"
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.
ErrorFor 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.
ErrorFor 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:
  • DEPLOY: A deployment of a new version of an application.
  • FEATURE_TOGGLE: A change in the features visible to a customer
  • MANUAL: A change made without an automation tool.
  • ORCHESTRATION: A change in infrastructure, such as a scaling up or down, or replacing a container.
  • OTHER: A change that does not belong to the other change types.
  • SOURCE_CODE_COMMIT: A change in a version control system
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.
ErrorFor 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:
  • DEPLOY: A deployment of a new version of an application.
  • FEATURE_TOGGLE: A change in the features visible to a customer
  • MANUAL: A change made without an automation tool.
  • ORCHESTRATION: A change in infrastructure, such as a scaling up or down, or replacing a container.
  • OTHER: A change that does not belong to the other change types.
  • SOURCE_CODE_COMMIT: A change in a version control system
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:
  • 254c95ee-4abe-47ea-ae7c-ae84fb4bee4f
  • mmcbride|Work Phone

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.
ErrorFor 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:
  • ACTIVE
  • INACTIVE
deviceType string
The type of device. Use one of the following values:
  • "ANDROID_PUSH"
  • "APPLE_PUSH"
  • "EMAIL"
  • "FAX"
  • "GENERIC"
  • "TEXT_PAGER"
  • "TEXT_PHONE"
  • "VOICE"
  • "VOICE_IVR"
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:
  • E164: E.164 standard format
  • COUNTRY_CODE: Formatted with spaces
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.
ErrorFor 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 the id field.

curl -H "Content-Type: application/json" --user username -X POST -d 
'{
   "id" : "42469eb6-c58c-4c0e-8c4b1838bdf853d2",
   "recipientType": "DEVICE",
   "defaultDevice" : true,
   "deviceType" : "VOICE",
   "owner": "ceb08e86-2674-4812-9145-d157b0e24c17",
   "phoneNumber": "+16045551212",
   "name": "Mobile Phone",
   "delay" : 5,
   "priorityThreshold": "MEDIUM",
   "sequence" : 2,
   "testStatus" : "UNTESTED",
   "timeframes":[
   {
      "name":"Weekdays",
      "startTime":"08:00",
      "durationInMinutes":840,
      "days": ["MO", "TU", "WE", "TH", "FR"],
      "excludeHolidays": true
   },
   {
      "name":"Weekends",
      "startTime":"09:00",
      "durationInMinutes":480,
      "days": ["SU", "SA"],
      "excludeHolidays": false
   }
  ]
}
' 
 "https://acmeco.xmatters.com/api/xm/1/devices" 
var request = http.request({ 
     "endpoint": "xMatters",
     "path": "/api/xm/1/devices",
     "method": "POST",
     "headers" : {"Content-Type": "application/json"}
 });


var data = {};
data.id = '42469eb6-c58c-4c0e-8c4b1838bdf853d2';
data.recipientType = 'DEVICE';
data.deviceType = 'VOICE';
data.owner ='ceb08e86-2674-4812-9145-d157b0e24c17';
data.name = 'Mobile Phone';
data.phoneNumber = '+16045551212';
data.delay = 5;
data.priorityThreshold = 'MEDIUM';
data.sequence = 2;
data.testStatus = 'UNTESTED';
var timeframe1 = {};
timeframe1.name = 'Weekdays';
timeframe1.startTime = '08:00';
timeframe1.durationInMinutes = 840,
timeframe1.excludeHolidays = true;
timeframe1.days = ['MO' ,'TU', 'WE', 'TH', 'FR'];
var timeframe2 = {};
timeframe2.name = 'Weekends';
timeframe2.startTime = '09:00';
timeframe2.durationInMinutes = 480,
timeframe2.excludeHolidays = true;
timeframe2.days = ['SA' ,'SU'];
var timeframes = [timeframe1, timeframe2];
data.timeframes = timeframes;

response = request.write(data);

if (response.statusCode == 201) {
   json = JSON.parse(response.body);
   console.log( "Created device: " + json.targetName);
}

import requests

base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/devices"
url = base_URL + endpoint_URL

data = {
    "id": "42469eb6-c58c-4c0e-8c4b1838bdf853d2",
    "deviceType": "VOICE",
    "defaultDevice": True,
    "owner": "ceb08e86-2674-4812-9145-d157b0e24c17",
    "name": "Mobile Phone",
    "phoneNumber": "+16045551212",
    "delay": 5,
    "priorityThreshold": "MEDIUM",
    "sequence": 2,
    "testStatus": "UNTESTED",
    "timeframes": [
        {
            "name": "Weekdays",
            "startTime": "08:00",
            "durationInMinutes": 840,
            "excludeHolidays": True,
            "days": ["MO", "TU", "WE", "TH", "FR"],
        },
        {
            "name": "Weekends",
            "startTime": "09:00",
            "durationInMinutes": 480,
            "excludeHolidays": True,
            "days": ["SU", "SA"],
        },
    ],
}
response = requests.post(url, json=data, auth=("username", "password"))
if response.status_code == 201:
    rjson = response.json()
    print("Created device " + rjson.get("targetName"))

RESPONSE

{
  "id":"42469eb6-c58c-4c0e-8c4b1838bdf853d2",
  "name":"Mobile Phone",
  "phoneNumber":"+16045551212",
  "targetName":"mmcbride",
  "deviceType":"VOICE",
  "description":"(604)5551212",
  "testStatus":"UNTESTED",
  "externallyOwned":false,
  "defaultDevice":true,
  "priorityThreshold":"MEDIUM",
  "sequence":2,
  "delay":5,
  "timeframes":
  {
    "count":2,
    "total":1,
    "data":
    [{
      "name":"Weekdays",
      "startTime":"08:00",
      "timezone": "US/Pacific",
      "durationInMinutes":840,
      "excludeHolidays":true,
      "days":["TU","MO","TH","FR","WE"]
    },
    {
      "name":"Weekends",
      "startTime":"09:00",
      "timezone": "US/Pacific",
      "durationInMinutes":480,
      "excludeHolidays":false,
      "days":["SU","SA"]
    }],
    "links":
    {
      "self": "/api/xm/1/devices/f5f76ffe-5fa3-4a1e-a43a-059d8046f9e4/timeframes?offset=0&limit=100"
    }
  },
  "owner":
  {
    "id":"ceb08e86-2674-4812-9145-d157b0e24c17",
    "targetName": "mmcbride",
    "links":
    {
      "self":"/api/xm/1/people/ceb08e86-2674-4812-9145-d157b0e24c17"}
    },
    "links":{
      "self":"/api/xm/1/devices/42469eb6-c58c-4c0e-8c4b-1838bdf853d2"
  },
  "recipientType":"DEVICE",
  "status":"ACTIVE",
  "privileged": false,
  "provider":
  {
    "id":"(x)matters Voice Gateway"
  }
}

Adds a device to xMatters and returns a Device object that represents the newly-created device.

Provide fields in the request body that are common to all devices as well as fields that are specific to the type of device you want to create, for example, include the emailAddress field when creating email devices and include the phoneNumber field for phone, text (SMS), or public address devices.

Privileged devices redact specific information, such as phone numbers, email addresses, or country location from users without the appropriate permission settings. This is useful to keep certain information, such as a group supervisor's home phone number from being visible to everyone in the group. Only company supervisors currently have permission to create, edit, and delete priviledged devices. To have this permission setting applied to other roles in your company, contact xMatters Support.

Mobile app devices such as iPhone, iPad, and Android app devices cannot be created using the xMatters REST API. These devices are added to a user's profile automatically after they install the mobile app on their device and use it to log on to xMatters for the first time. However, once a mobile app device has been added to a user's profile it may be modified with Modify a device.

DEFINITION

POST /devices

BODY PARAMETERS

Include the parameters in the All Devices table in the body of each request to create a device. You must also include the parameters specific to the type of device you are creating as defined in the deviceType field. Refer to the remaining tables in this section to see the fields to include for each type of device:

All devices

   
defaultDevice Boolean
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:
  • "EMAIL" (email devices)
  • "VOICE" (phone devices)
  • "TEXT_PHONE" (text / SMS devices)
  • "TEXT_PAGER" (text pager)
  • "FAX" (fax machine)
  • "VOICE_IVR" (public address system)
  • "GENERIC"
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:
  • "Work Phone"
  • "Home Phone"
  • "Mobile Phone"
  • "Home Email"
  • "Work Email"
  • "SMS Phone"
  • "Pager"
  • "Fax"
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:
  • "LOW"
  • "MEDIUM"
  • "HIGH"
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:
  • ACTIVE
  • INACTIVE
testStatus string
A code indicating whether the device has been tested or if testing is in progress. Valid values include the following:
  • "TESTED"
  • "UNTESTED"
  • "PENDING"
  • "INVALID"
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:
  • +19295551212
  • +441632960577

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:
  • "AR"
  • "AU"
  • "BR"
  • "CA"
  • "FR"
  • "DE"
  • "HK"
  • "IN"
  • "IT"
  • "JP"
  • "PT"
  • "PR"
  • "GB"
  • "US"
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"):
  • 4035551919
  • 7025559820
Note: The phone number format used for fax is different than the phone number format used for voice, public address, and SMS devices. Fax numbers must conform to the following regular expression: "^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

SuccessResponse code 201 Created and a Device object in the response body.
ErrorFor 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:
  • "ANDROID_PUSH"
  • "APPLE_PUSH"
  • "EMAIL"
  • "FAX"
  • "GENERIC"
  • "TEXT_PAGER"
  • "TEXT_PHONE"
  • "VOICE"
  • "VOICE_IVR"
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.
ErrorFor 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:
  • 254c95ee-4abe-47ea-ae7c-ae84fb4bee4f
  • mmcbride|Work Phone

RESPONSES

Success Response code 200 OK and a Device object in the response body.
ErrorFor 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:

Device object

Device Object

This example shows an email device object that includes timeframes. Device objects for other device types omit the emailAddress field and include fields specific to the type of device.

"id": "77c7ec54-8609-47da-9b6b-80d4b24bead1",
"name": "Home Email",
"emailAddress": "akaur@example.com",
"targetName": "akaur|Home Email",
"deviceType": "EMAIL",
"description": "akaur@example.com",
"testStatus": "UNTESTED",
"externallyOwned": false,
"defaultDevice": true,
"priorityThreshold": "LOW",
"sequence": 1,
"delay": 0,
"owner":
{
  "id": "031313cc-42d3-4703-a90e-36cc5f5f6209",
  "targetName": "akaur",
  "links":
  {
     "self": "/api/xm/1/people/031313cc-42d3-4703-a90e-36cc5f5f6209"
  }
},
"links":
{
   "self": "/api/xm/1/devices/77e7ec54-8609-47da-9b6b-80d4b24bead1"
},
"recipientType": "DEVICE",
"status": "ACTIVE",
"provider":
{
  "id": "(x)matters Email Gateway"
}  
"timeframes":
[
  {
    "name":"Weekdays",
    "startTime":"08:00",
    "durationInMinutes":840,
    "days": ["MO", "TU", "WE", "TH", "FR"],
     "excludeHolidays": true
   },
   {
     "name":"Weekends",
     "startTime":"09:00",
     "durationInMinutes":480,
     "days": ["SU", "SA"],
     "excludeHolidays": false
   }
 ]

Contains fields common to recipients and all types of devices.

See also Recipient object.

   
defaultDevice Boolean
True if this device can receive notifications when the person has no active devices.
delay integer
The number of minutes to wait for a response on this device before contacting the next device.
description string
A system-generated description of the device.
deviceType string
The type of device. Use one of the following values:
  • "ANDROID_PUSH"
  • "APPLE_PUSH"
  • "EMAIL"
  • "FAX"
  • "GENERIC"
  • "TEXT_PAGER"
  • "TEXT_PHONE"
  • "VOICE"
  • "VOICE_IVR"
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:
  • "LOW"
  • "MEDIUM"
  • "HIGH"
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:
  • "UNTESTED"
  • "PENDING"
  • "TESTED"
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:
  • "SU"
  • "MO"
  • "TU"
  • "WE"
  • "TH"
  • "FR"
  • "SA"
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:
  • "ANDROID_PUSH"
  • "APPLE_PUSH"
  • "EMAIL"
  • "FAX"
  • "GENERIC"
  • "TEXT_PAGER"
  • "TEXT_PHONE"
  • "VOICE"
  • "VOICE_IVR"
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:
  • "ANDROID_PUSH"
  • "APPLE_PUSH"
  • "EMAIL"
  • "FAX"
  • "GENERIC"
  • "TEXT_PAGER"
  • "TEXT_PHONE"
  • "VOICE"
  • "VOICE_IVR"
For more information about supported device types, see Device Types.
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:
  • NAME
  • DEVICETYPE
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:
  • ASCENDING
  • DESCENDING
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.
ErrorFor 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:
  • "EMAIL" (email devices)
  • "VOICE" (phone devices)
  • "TEXT_PHONE" (text / SMS devices)
  • "TEXT_PAGER" (text pager)
  • "FAX" (fax machine)
  • "VOICE_IVR" (public address system)
  • "GENERIC"
name string
The name of the device. Device names are configured uniquely for each company, but typical values include the following:
  • "Work Phone"
  • "Home Phone"
  • "Mobile Phone"
  • "Home Email"
  • "Work Email"
  • "SMS Phone"
  • "Pager"
  • "Fax"
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

SuccessResponse code 201 Created and a Device name object in the response body.
ErrorFor 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:
  • "ANDROID_PUSH"
  • "APPLE_PUSH"
  • "EMAIL"
  • "FAX"
  • "GENERIC"
  • "TEXT_PAGER"
  • "TEXT_PHONE"
  • "VOICE"
  • "VOICE_IVR"

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.
ErrorFor 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.
ErrorFor 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:
  • "Work Email"
  • "Home Email"
  • "Mobile Phone"
  • "Pager"
  • "Fax"
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.
ErrorFor 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:
  • "ANDROID_PUSH"
  • "APPLE_PUSH"
  • "EMAIL"
  • "FAX"
  • "GENERIC"
  • "TEXT_PAGER"
  • "TEXT_PHONE"
  • "VOICE"
  • "VOICE_IVR"

DYNAMIC TEAMS

Dynamic teams are created to group together users based on who matches the selected criteria at the time of an event. Use this endpoint to retrieve all dynamic teams in your system or a specific dynamic team by its unique id.

For more information, see Create dynamic teams in the online help.

Get dynamic teams

GET dynamic teams

REQUEST (get all dynamic teams)

curl --user username 
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams"
/**
 * This script is configured to work within the xMatters Integration Builder.
 * Configure the "xMatters" endpoint to use a valid username and password.
 */
var request = http.request({ 
   "endpoint": "xMatters",
   "path": "/api/xm/1/dynamic-teams",
   "method": "GET"
 });

var response = request.write();

if (response.statusCode == 200 ) {
   json = JSON.parse(response.body);
   console.log( "Retrieved " + json.count + " of " + json.total + " dynamic teams." );
   for (var i in json.data ) {
     console.log(json.data[i].targetName);
  }
}
import requests
from requests.auth import HTTPBasicAuth
import json

base_URL = "https://acmeco.xmatters.com/api/xm/1"

endpoint_URL = "/dynamic-teams"

url = base_URL + endpoint_URL

auth = HTTPBasicAuth("username", "password")

response = requests.get(url, auth=auth)

response_code = response.status_code
if response_code == 200:
    rjson = response.json()
    for d in rjson.get("data"):
        print("Found dynamic team with TargetName: " + d["targetName"] + " and id: " + d["id"])

else:
    rjson = response.json()
    print(
        "The request did not succeed.  Response code is: "
        + str(response_code)
    )

REQUEST (get dynamic teams Anita Sharma supervises)

curl --user username 
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams?supervisors=asharma"
/**
 * This script is configured to work within the xMatters Integration Builder.
 * Configure the "xMatters" endpoint to use a valid username and password.
 */
var request = http.request({ 
   "endpoint": "xMatters",
   "path": "/api/xm/1/dynamic-teams?supervisors=asharma",
   "method": "GET"
 });

var response = request.write();

if (response.statusCode == 200 ) {
   json = JSON.parse(response.body);
   console.log( "Retrieved " + json.count + " of " + json.total + " dynamic teams." );
   for (var i in json.data ) {
     console.log(json.data[i].targetName);
  }
}
import requests
from requests.auth import HTTPBasicAuth
import json

base_URL = "https://acmeco.xmatters.com/api/xm/1"

endpoint_URL = "/dynamic-teams?supervisors=asharma"

url = base_URL + endpoint_URL

auth = HTTPBasicAuth("username", "password")

response = requests.get(url, auth=auth)

response_code = response.status_code
if response_code == 200:
    rjson = response.json()
    for d in rjson.get("data"):
        print("Found dynamic team with TargetName: " + d["targetName"] + " and id: " + d["id"])

else:
    rjson = response.json()
    print(
        "The request did not succeed.  Response code is: "
        + str(response_code)
    )

REQUEST (get dynamic teams that have the word "operations" in their description)

curl --user username 
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams?search=operations&fields=DESCRIPTION"
/**
 * This script is configured to work 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/dynamic-teams?search=operations&fields=DESCRIPTION",
   "method": "GET"
 });

var response = request.write();

if (response.statusCode == 200 ) {
   json = JSON.parse(response.body);
   console.log( "Retrieved " + json.count + " of " + json.total + " dynamic teams." );
   for (var i in json.data ) {
     console.log(json.data[i].targetName);
  }
}
import requests
from requests.auth import HTTPBasicAuth
import json

base_URL = "https://acmeco.xmatters.com/api/xm/1"

endpoint_URL = "/dynamic-teams?search=operations&fields=DESCRIPTION"

url = base_URL + endpoint_URL

auth = HTTPBasicAuth("username", "password")

response = requests.get(url, auth=auth)

response_code = response.status_code
if response_code == 200:
    rjson = response.json()
    for d in rjson.get("data"):
        print("Found dynamic team with TargetName: " + d["targetName"] + " and id: " + d["id"])

else:
    rjson = response.json()
    print(
        "The request did not succeed.  Response code is: "
        + str(response_code)
    )

RESPONSE

{"count": 7,
"total": 7,
"data": [
    {
      "id": "1c85cabc-8927-40fe-945a-34733aec7ba4",
      "targetName": "ThirdFloorResponseTeam",
      "recipientType": "DYNAMIC_TEAM",
      "externallyOwned": false,
      "description": "Third floor emergency response team",
      "criteria": {
        "operand": "OR",
        "criterion": {
          "count": 1,
          "total": 1,
          "data": [
            {
              "criterionType": "BASIC_FIELD",
              "field": "USER_ID",
              "operand": "EQUALS",
              "value": "First_Aid_Attendant"
            }
          ]
        }
      },
      "links": {
        "self": "/api/xm/1/dynamic-teams/1c85cabc-8927-40fe-945a-34733aec7ba4"
      }
    },
    { ...a truncated list of dynamic teams...},
    ], 
"links": {
    "self": "/api/xm/1/dynamic-teams"
   }
 }  

Returns a list of dynamic teams in your system.

For more information, see Create dynamic teams in the online help.

DEFINITION

GET /dynamic-teams
GET /dynamic-teams?embed=supervisors,observers
GET /dynamic-teams?search=term1 term2&operand=AND
GET /dynamic-teams?search="term 1 term 2"&fields=DESCRIPTION
GET /dynamic-teams?supervisors=c21b7cc9-c52a-4878-8d26-82b26469fdc7,asharma

QUERY PARAMETERS

   
embed string
A comma-separated list of objects to embed in the response. Supported values are: observers and supervisors.
search string
A list of search terms separated by the + sign or a space character. Searches are case-insensitive ("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 dynamic teams 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: /dynamic-teams?search=web operations&fields=NAME returns all dynamic teams with names that contain either "web" or "operations". However, searching /dynamic-teams?search="web operations"&fields=NAME returns all dynamic teams with names that contain "web operations".
operand string
The operand to use to limit or expand the search query parameter: AND or OR. AND only returns dynamic teams that have all search terms in the name or description. OR returns dynamic teams that have any of the search terms in the name or description; this is the default if you don't specify an operand. The operand is case-sensitive; for example, lowercase 'and' returns an error.
fields string
Defines the field to search when a search term is specified. Valid values include:
  • NAME,DESCRIPTION: searches both the name and description (the search term can appear in either – this is the default if the field is not specified)
  • NAME: searches only the dynamic team name
  • DESCRIPTION: searches only the dynamic team description
supervisors string
A comma-separated list of supervisors whose dynamic teams you want to retrieve. You can specify the supervisors using targetName (case-insensitive) or id (or both if search for multiple supervisors). When two or more supervisors are sent in the request, the response includes dynamic teams for which either user is a supervisor.
Example: /dynamic-teams?supervisors=asharma,6f347364-8dc7-4871-819b-e3e7dbfda2de
sortBy string
The criteria for sorting the returned results. Use with the sortOrder query parameter to specify whether the results should be sorted in ascending or descending order. Valid value is: NAME.
sortOrder string
Specifies whether dynamic teams are sorted in ascending or descending order. This parameter must be used in conjunction with the sortBy query parameter. Valid values include:
  • ASCENDING
  • DESCENDING

RESPONSES

Success Response code 200 OK and a pagination of Dynamic Teams object in the response body.
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes.

Get a dynamic team

GET a dynamic team

curl --user username 
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04"
/**
 * This script is configured to work 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/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04",
     "method": "GET"
 });

var response = request.write();

if (response.statusCode == 200 ) {
   json = JSON.parse(response.body);
   console.log("Retrieved : " + json.targetName + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json

base_URL = "https://acmeco.xmatters.com/api/xm/1"

endpoint_URL = "/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04"

url = base_URL + endpoint_URL

print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")

response = requests.get(url, auth=auth)

responseCode = response.status_code
if responseCode == 200:
    rjson = response.json()
    print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
    rjson = response.json()
    print(
        "The request did not succeed.  Response code is: "
        + str(responseCode)
        + "\n"
        + str(response)
    )

RESPONSE

   {
      "id": "1c85cabc-8927-40fe-945a-34733aec7ba4",
      "targetName": "MIMTeam",
      "recipientType": "DYNAMIC_TEAM",
      "externallyOwned": false,
      "description": "Major Incident Response team - MWF",
      "criteria": {
        "operand": "OR",
        "criterion": {
          "count": 1,
          "total": 1,
          "data": [
            {
              "criterionType": "BASIC_FIELD",
              "field": "USER_ID",
              "operand": "EQUALS",
              "value": "MIMTeam1"
            }
          ]
        }
      },
      "links": {
        "self": "/api/xm/1/dynamic-teams/1c85cabc-8927-40fe-945a-34733aec7ba4"
      }
    } 


Returns a dynamic team using its unique id. To find the id of a dynamic team, use GET Dynamic Teams.

For more information, see Create dynamic teams in the online help.

DEFINITION

GET /dynamic-teams/{dynamicTeamId}
GET /dynamic-teams/{dynamicTeamId}?embed=supervisors,observers

URL PARAMETERS

   
dynamicTeamId string
The unique id of the dynamic team.

QUERY PARAMETERS

   
embed string
A comma-separated list of objects to embed in the response. Supported values are: observers and supervisors.

RESPONSES

Success Response code 200 OK and a Dynamic Teams object in the response body.
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes.

Get dynamic team members

GET dynamic team members

curl --user username 
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04/members"
/**
 * This script is configured to work 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/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04/members",
     "method": "GET"
 });

var response = request.write();

if (response.statusCode == 200 ) {
   json = JSON.parse(response.body);
   console.log("Retrieved : " + json.targetName + ". ID = " + json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json

base_URL = "https://acmeco.xmatters.com/api/xm/1"

limit = "2"

endpoint_URL = "/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04/members"

url = base_URL + endpoint_URL

print("Sending request to url: " + url)
auth = HTTPBasicAuth("username", "password")

response = requests.get(url, auth=auth)

responseCode = response.status_code
if responseCode == 200:
    rjson = response.json()
    for d in rjson.get("data"):
        print(
            "Found Team Member with TargetName: "
            + d["targetName"]
            + " at site: "
            + d["site"]["name"]
        )
    print("The data is:\n" + json.dumps(rjson, indent=4, sort_keys=False))
else:
    rjson = response.json()
    print(
        "The request did not succeed.  Response code is: "
        + str(responseCode)
        + "\n"
        + str(response)
    )

RESPONSE

 {
  "count": 14,
  "total": 14,
  "data": [
    {
      "id": "362f15ba-199e-4808-90ac-d79c1c36c9be",
      "targetName": "mmcbride",
      "recipientType": "PERSON",
      "externallyOwned": false,
      "links": {
        "self": "/api/xm/1/people/362f15ba-199e-4808-90ac-d79c1c36c9be"
      },
      "firstName": "Mary",
      "lastName": "McBride",
      "language": "en",
      "timezone": "US/Pacific",
      "webLogin": "mmcbride",
      "site": {
        "id": "87165184-f025-46ec-bc8e-11314b4ddeb5",
        "name": "Default Site",
        "links": {
          "self": "/api/xm/1/sites/87165184-f025-46ec-bc8e-11314b4ddeb5"
        }
      },
      "status": "ACTIVE"
    }
    {
      ... truncated list of dynamic team members ...    
    }
  ],
  "links": {
    "self": "/api/xm/1/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04/members?offset=0&limit=100"
  }
} 


Returns the members of a dynamic team using the team's unique id or targetName. To find the id of a dynamic team, use GET Dynamic Teams.

DEFINITION

GET /dynamic-teams/{dynamicTeamId}/members

URL PARAMETERS

   
dynamicTeamId string
The unique id or targetNameof the dynamic team.

RESPONSES

Success Response code 200 OK and a paginated list of Person objects in the response body.
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes.

Create a dynamic team

Create a dynamic team

REQUEST - Create a dynamic team

curl --user username --header "Content-Type: application/json" --request POST -d '{
    "targetName": "MIMTeam1",
    "criteria": 
        {
        "operand": "OR",
        "criterion": [{
                "criterionType": "BASIC_FIELD",
                "field": "USER_ID",
                "operand": "EQUALS",
                "value": "MIMTeam1"
        }]
    },
    "supervisors": [
         "9bccb70b-ab35-4746-b9f5-fa6eca0b1450",
         "e623fc32-6201-4089-b6e5-eeec9dd284d6",
        ]
}' 
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams" 
javascript
/**
 * This script is configured to work 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/dynamic-teams/",
     "method": "POST",
     "headers" : {"Content-Type": "application/json"}
 });

var data = {};
data.targetName = 'MIMTeam1';

var criteria = {};
criteria.operand = 'OR';

var criterion1 = {};
criterion1.criterionType = 'BASIC_FIELD';
criterion1.field = 'USER_ID';
criterion1.operand = 'EQUALS';
criterion1.value = 'MIMTeam1'

var criterion = []
criterion.push(criterion1)
criteria.criterion = criterion;

data.criteria = criteria;

var supervisors = [];
supervisors.push('4d618961-21d6-417d-a904-8a84893b4e31','e623fc32-6201-4089-b6e5-eeec9dd284d6');
data.supervisors = supervisors;

response = request.write(data);

if (response.statusCode == 201) {
   json = JSON.parse(response.body);
   console.log( "Created dynamic team: " + json.targetName + ". ID = "+ json.id);
}

#The following code is formatted to work with Python v.3.6 and later.

import requests

base_url = "https://acmeco.xmatters.com/api/xm/1"
endpoint = "/dynamic-teams"

username = "yourUsername"
password = "yourPassword"

payload = {
    "targetName": "MIMTeam1",
    "criteria": [
        {
            "operand": "OR",
            "criterion": {
                "criterionType": "BASIC_FIELD",
                "field": "USER_ID",
                "operand": "EQUALS",
                "value": "MIMTeam1",
            },
        }
    ],
    "supervisors": ["9bccb70b-ab35-4746-b9f5-fa6eca0b1450", "e623fc32-6201-4089-b6e5-eeec9dd284d6"],
}

response = requests.post(base_url + endpoint, json=payload, auth=(username, password))

if response.status_code == 201:
    print("Your dynamic team was created.")
else:
    print("The dynamic team could not be created.")

RESPONSE

{
  "id": "76896d39-4258-4de0-bc4b-c2aadb120187",
  "targetName": "MIMTeam1",
  "recipientType": "DYNAMIC_TEAM",
  "externallyOwned": false,
  "supervisors": {
    "count": 2,
    "total": 2,
    "data": [
      {
        "id": "9bccb70b-ab35-4746-b9f5-fa6eca0b1450",
        "targetName": "mmcbride",
        "recipientType": "PERSON",
        "externallyOwned": false,
        "links": {
          "self": "/api/xm/1/people/9bccb70b-ab35-4746-b9f5-fa6eca0b1450"
        },
        "firstName": "Mary",
        "lastName": "McBride",
        "language": "en",
        "timezone": "US/Pacific",
        "webLogin": "mmcbride",
        "site": {
          "id": "87165184-f025-46ec-bc8e-11314b4ddeb5",
          "name": "Default Site",
          "links": {
            "self": "/api/xm/1/sites/87165184-f025-46ec-bc8e-11314b4ddeb5"
          }
        },
        "lastLogin": "2019-11-05T17:44:42.971Z",
        "status": "ACTIVE"
      },
      {
        "id": "e623fc32-6201-4089-b6e5-eeec9dd284d6",
        "targetName": "ssmith",
        "recipientType": "PERSON",
        "externallyOwned": false,
        "links": {
          "self": "/api/xm/1/people/e623fc32-6201-4089-b6e5-eeec9dd284d6"
        },
        "firstName": "Steve",
        "lastName": "Smith",
        "language": "en",
        "timezone": "US/Pacific",
        "webLogin": "ssmith",
        "site": {
          "id": "87165184-f025-46ec-bc8e-11314b4ddeb5",
          "name": "Default Site",
          "links": {
            "self": "/api/xm/1/sites/87165184-f025-46ec-bc8e-11314b4ddeb5"
          }
        },
        "lastLogin": "2019-11-05T17:44:42.971Z",
        "status": "ACTIVE"
      }
    ]
  },
  "observers": {
    "count": 0,
    "total": 0,
    "data": []
  },
  "criteria": {
    "operand": "OR",
    "criterion": {
      "count": 1,
      "total": 1,
      "data": [
        {
          "criterionType": "BASIC_FIELD",
          "field": "USER_ID",
          "operand": "EQUALS",
          "value": "MIMTeam1"
        }
      ]
    }
  },
  "links": {
    "self": "/api/xm/1/dynamic-teams/76896d39-4258-4de0-bc4b-c2aadb120187"
  }
}

Creates a dynamic team in xMatters.

The response returns a Dynamic team object that represents the newly-created dynamic team. You can use this object to locate the dynamic team's unique identifier (the id field).

Dynamic teams must have at least one supervisor.

DEFINITION

POST /dynamic-teams

BODY PARAMETERS

   
targetName string
The unique target name of the dynamic group.
recipientType string
For dynamic teams, the recipient type field is "DYNAMIC_TEAM".
description string
A description of the dynamic team.
criteria Dynamic Team Criteria object
The criteria used to determine members of the dynamic team.
supervisors array [string]
The unique id of the supervisor, or supervisors of a dynamic team. A dynamic team must have at least one supervisor, and the user (or users) set as the supervisor must have the appropriate permissions to supervise the team.
observers Role object
The id or name of the role or roles set as observers for the dynamic team.

RESPONSES

Success Response code 201 Created and a Dynamic team object in the response body.
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes.

Modify a dynamic team

Modify a dynamic team

REQUEST - Modify a dynamic team

curl --user username --header "Content-Type: application/json" --request POST -d '{
    "id": "76896d39-4258-4de0-bc4b-c2aadb120187",
    "targetName": "MIMTeam1",
    "criteria": 
        {
        "operand": "AND",
        "criterion": [{
                "criterionType": "BASIC_FIELD",
                "field": "USER_ID",
                "operand": "EQUALS",
                "value": "MIMTeam1"
        }]
    },
    "supervisors": [{
        "id": "9bccb70b-ab35-4746-b9f5-fa6eca0b1450"
        }]
}' 
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams" 
javascript
/**
 * This script is configured to work 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/dynamic-teams/",
     "method": "POST",
     "headers" : {"Content-Type": "application/json"}
 });

var data = {};
data.id = '76896d39-4258-4de0-bc4b-c2aadb120187';
data.targetName = 'MIMTeam1';

var criteria = {};
criteria.operand = 'AND';

var criterion1 = {};
criterion1.criterionType = 'BASIC_FIELD';
criterion1.field = 'USER_ID';
criterion1.operand = 'EQUALS';
criterion1.value = 'MIMTeam1'

var criterion = []
criterion.push(criterion1)
criteria.criterion = criterion;

data.criteria = criteria;

var supervisors = [];
supervisors.push('4d618961-21d6-417d-a904-8a84893b4e31');
data.supervisors = supervisors;

response = request.write(data);

if (response.statusCode == 200) {
   json = JSON.parse(response.body);
   console.log( "Updated dynamic team: " + json.targetName + ". ID = "+ json.id);
}
#The following code is formatted to work with Python v.3.6 and later.

import requests

base_url = "https://acmeco.xmatters.com/api/xm/1"
endpoint = "/dynamic-teams"

username = "yourUsername"
password = "yourPassword"

payload = {
    "id": "76896d39-4258-4de0-bc4b-c2aadb120187",
    "targetName": "MIMTeam1",
    "criteria": [
        {
            "operand": "OR",
            "criterion": {
                "criterionType": "BASIC_FIELD",
                "field": "USER_ID",
                "operand": "EQUALS",
                "value": "MIMTeam1",
            },
        }
    ],
    "supervisors": {"id": "9bccb70b-ab35-4746-b9f5-fa6eca0b1450"},
}

response = requests.post(base_url + endpoint, json=payload, auth=(username, password))

if response.status_code == 200:
    print("Your dynamic team was updated.")
else:
    print("The dynamic team could not be created.")

RESPONSE

{
  "id": "76896d39-4258-4de0-bc4b-c2aadb120187",
  "targetName": "MIMTeam1",
  "recipientType": "DYNAMIC_TEAM",
  "externallyOwned": false,
  "supervisors": {
    "count": 1,
    "total": 1,
    "data": [
      {
        "id": "9bccb70b-ab35-4746-b9f5-fa6eca0b1450",
        "targetName": "mmcbride",
        "recipientType": "PERSON",
        "externallyOwned": false,
        "links": {
          "self": "/api/xm/1/people/9bccb70b-ab35-4746-b9f5-fa6eca0b1450"
        },
        "firstName": "Mary",
        "lastName": "McBride",
        "language": "en",
        "timezone": "US/Pacific",
        "webLogin": "mmcbride",
        "site": {
          "id": "87165184-f025-46ec-bc8e-11314b4ddeb5",
          "name": "Default Site",
          "links": {
            "self": "/api/xm/1/sites/87165184-f025-46ec-bc8e-11314b4ddeb5"
          }
        },
        "lastLogin": "2019-11-05T17:44:42.971Z",
        "status": "ACTIVE"
      }
    ]
  },
  "observers": {
    "count": 0,
    "total": 0,
    "data": []
  },
  "criteria": {
    "operand": "OR",
    "criterion": {
      "count": 1,
      "total": 1,
      "data": [
        {
          "criterionType": "BASIC_FIELD",
          "field": "USER_ID",
          "operand": "EQUALS",
          "value": "MIMTeam1"
        }
      ]
    }
  },
  "links": {
    "self": "/api/xm/1/dynamic-teams/76896d39-4258-4de0-bc4b-c2aadb120187"
  }
}

Changes the properties of an existing dynamic team in xMatters. Identify the dynamic team by its unique identifier in the id field, then provide the parameters you want to modify. Use GET /dynamic-team to find the id of the dynamic team.

DEFINITION

POST /dynamic-teams/

BODY PARAMETERS

The only required body parameter is the UUID of the dynamic team you want to update. See the Create a dynamic team body parameters for details on the parameters you can change.

   
id string
The unique identifier (id) of the dynamic team you want to modify.

RESPONSES

Success Response code 200 OK and a Dynamic team object in the response body.
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes.

Delete a dynamic team

Delete a dynamic team

REQUEST: Delete a dynamic team by name. You can also identify the group by its unique identifier (id).

curl --user username --request DELETE 
"https://acmeco.xmatters.com/api/xm/1/dynamic-teams/MIM-1"
/**
 * This script is configured to work 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/dynamic-teams/MIM-1",
  /*"path" : "api/xm/1/dynamic-teams/0a344f68-5175-45d0-af6b-20f5e31bf646",*/
  "method": "DELETE",
  "headers" : {"Content-Type": "application/json"}
 });

response = request.write();

if (response.statusCode == 200){
    json = JSON.parse(response.body);
    console.log("Deleted the dynamic team " + json.targetName);
}
import requests
from requests.auth import HTTPBasicAuth
import json

teamId = "438e9245-b32d-445f-916bd3e07932c892"

base_URL = "https://acmeco.xmatters.com/api/xm/1"
endpoint_URL = "/dynamic-teams/" + teamId
url = base_URL + endpoint_URL

auth = HTTPBasicAuth("username", "password")

print("Sending request to: " + url)
response = requests.delete(url, auth=auth)

responseCode = response.status_code
print("received response code: " + str(responseCode))
if responseCode == 200:
    rjson = response.json()
    print(
        "Dynamic team "
        + rjson.get("id")
        + " was successfully deleted.  The object is:\n"
        + json.dumps(rjson, indent=4, sort_keys=False)
    )
else:
    print("The request did not succeed.  Response is:\n" + str(response))

RESPONSE

{
  "id": "438e9245-b32d-445f-916bd3e07932c892",
  "targetName": "MIM-1",
  "recipientType": "DYNAMIC_TEAM",

  "links": 
  {
     "self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
  }
}

Deletes a dynamic team, and terminates all memberships (such as groups, subscriptions, scheduled messages, etc.,) to the team.

Identify the dynamic team using either its name (the targetName field) or its unique identifier (the id field).

The response returns a Dynamic Team Object that represents the recently deleted dynamic team.

DEFINITION

DELETE /dynamic-teams/{dynamicTeamId}

URL PARAMETERS

   
dynamicTeamID string
The unique identifier (id) or name (targetName) of the dynamic team.
Example: MIMTeam1
Example: a6341d69-5683-4621-b8c8-f2e728f6752q

RESPONSES

Success Response code 200 OK and a Dynamic team object in the response body.
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes.

Dynamic team object

Dynamic team object

Dynamic team object


{
  "id": "7345cdb1-6a59-4e85-addd-fc17ae3cbb04",
  "targetName": "SubscriptionDynamicTeam",
  "recipientType": "DYNAMIC_TEAM",
  "externallyOwned": false,
  "description": "Dynamic Team for Subscription tests",
  "supervisors": {
    "count": 1,
    "total": 1,
    "data": [
      {
        "id": "9bccb70b-ab35-4746-b9f5-fa6eca0b1450",
        "targetName": "admin",
        "recipientType": "PERSON",
        "externallyOwned": false,
        "links": {
          "self": "/api/xm/1/people/9bccb70b-ab35-4746-b9f5-fa6eca0b1450"
        },
        "firstName": "Mary",
        "lastName": "McBride",
        "language": "en",
        "timezone": "US/Pacific",
        "webLogin": "mmcbride",
        "site": {
          "id": "87165184-f025-46ec-bc8e-11314b4ddeb5",
          "name": "Default Site",
          "links": {
            "self": "/api/xm/1/sites/87165184-f025-46ec-bc8e-11314b4ddeb5"
          }
        },
        "lastLogin": "2019-08-21T18:50:24.596Z",
        "status": "ACTIVE"
      }
    ]
  },
  "observers": {
    "count": 0,
    "total": 0,
    "data": []
  },
  "criteria": {
    "operand": "OR",
    "criterion": {
      "count": 1,
      "total": 1,
      "data": [
        {
          "criterionType": "BASIC_FIELD",
          "field": "USER_ID",
          "operand": "EQUALS",
          "value": "SubsActivity_DynamicTeamUser"
        }
      ]
    }
  },
  "links": {
    "self": "/api/xm/1/dynamic-teams/7345cdb1-6a59-4e85-addd-fc17ae3cbb04"
  }
}

A representation of an xMatters dynamic team, including embedded supervisors and observers.

   
id string
the unique identifier (id) of the dynamic group.
targetName string
The target name of the dynamic group.
recipientType string
For dynamic teams, the recipient type field is "DYNAMIC_TEAM".
description string
A description of the dynamic team.
externallyOwned boolean
See externallyOwned.
supervisors Person or PersonReference object
A Paginated list of the supervisors of a dynamic team. This optional field is included when the request uses the ?embed=supervisors query parameter. Returns a Person object or PersonReference object, depending on what permissions the authenticating user has.
observers Role object
The id or name of the role or roles set as observers for the dynamic team. This optional field is included when the request uses the ?embed=observers query parameter. If no roles are set as observers, an empty data set is returned.
criteria Criteria object
The criteria used to determine members of the dynamic team.
links SelfLink object
A link that can be used to reference the dynamic team.

Dynamic Team Criteria object

Dynamic team criteria object


{
  "criteria": {
    "operand": "OR",
    "criterion": {
      "count": 1,
      "total": 1,
      "data": [
        {
          "criterionType": "BASIC_FIELD",
          "field": "USER_ID",
          "operand": "EQUALS",
          "value": "SubsActivity_DynamicTeamUser"
        }
      ]
    }
  },
}

The criteria used to determine members of the dynamic team.

   
operand string
The operand to use to limit or expand the search query parameter: AND or OR. AND only returns dynamic teams that have all search terms in the name or description. OR returns dynamic teams that have any of the search terms in the name or description; this is the default if you don't specify an operand. The operand is case-sensitive; for example, lowercase 'and' returns an error.
criterion string
The criteria used to determine members of the dynamic team. Available options are: BASIC_FIELD, CUSTOM_FIELD, CUSTOM_ATTRIBUTE. For more details on the criterion, see Criterion object.

Dynamic Teams 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 team.

   
criterionType string
The criterion type. Available options are:
  • BASIC_FIELD
  • CUSTOM_FIELD
  • CUSTOM_ATTRIBUTE
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.

DynamicTeamReference object

Dynamic team reference object


{
  "id": "7345cdb1-6a59-4e85-addd-fc17ae3cbb04",
  "targetName": "SubscriptionDynamicTeam",
  "recipientType": "DYNAMIC_TEAM",
}

A representation of an xMatters dynamic team returned when the dynamic team is a listed as a recipient on a form.

   
id string
The unique identifier (id) of the dynamic team.
targetName string
The target name of the dynamic team.
recipientType string
For dynamic teams, the recipient type field is "DYNAMIC_TEAM".

EVENTS

You can use the linked methods to start, stop, resume, and terminate events, as well as add comments to an event.

You can also retrieve a list of events and notifications in the system, or details about a specific event, including comments or annotations that have been added to the event.

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:

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.

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.
  • from: A date in UTC format that represents the start of the time range you want to search. All objects created at or after the specified time range are displayed in the query results. Example: 2017-05-01T14:00:00.000Z brings back any events initiated at or past 2 pm on May 1st, 2017.

  • to: A date in UTC format that represents the end of the time range you want to search. All objects created at or before the specified time range are displayed in the query results. Example: 2017-05-01T19:00:00.000Z brings back any events initiated at or prior to 7 pm, May 1, 2017.

    When setting the to parameter, the time cannot be further in the future than the time of the at parameter. For example, if the at parameter is set for 2018-12-01T13:00:00.000Z (1:00 pm, December 1st), the to parameter cannot be set for 2018-12-01T14:30:00.000Z (2:30 pm, December 1st).

  • after: A time in UTC format, used in place of from, that represents the start of the time range you want to search. Only objects created after the specified time range are displayed in the query results.

  • before: A time in UTC format, used in place of to, that represents the end of the time range you want to search. Only objects created before the specified time range are displayed in the query results.

    Access to data using the from or after parameters is limited by your pricing plan. For example, if your pricing plan allows you access to 90 days of historical data, you will receive an error message if you set the from parameter to be greater than 90 days in the past.

    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 historical data. This means that when searching historical data, the "to" or "before" parameters cannot be within 15 minutes of the current time.
embed string
A comma-separated list of the objects to embed in the response.
  • annotations: Comments that were added to the event, either when responding or in the tracking report in the web interface.
    To see just the comments, with minimal event data, use GET /event/annotations.
  • attachments.size: The size of any attached files, in bytes.
  • properties: The form properties.
    This allows you to extract message details from the event.
  • responseOptions: The response options included in the event. When other languages are enabled in your system, you can request responses in the user's original language by adding responseOptions.translations to your request. The two-letter code returned in the language field adheres to ISO 639 standards. For an example of the returned translation, see the ResponseOptions object.
  • suppressions: Adds a list of any suppressions for the event as a result of an event flood control rule. For an example of a returned suppression record, see Event Suppressions.
  • targetedRecipients: A list of users, devices, groups, or dynamic teams that were targeted as part of the event. Based on your system's settings, targeted users may or may not receive notifications at the time of the event.
eventType string
The type of event to return in the results. Valid values are either:
  • "USER": this includes events sent via an integration and events manually triggered using the Messaging tab in the web user interface or using a POST /triggers request.
  • "SYSTEM": notifications from xMatters about events within xMatters (for example, device validation updates, temporary replacement notifications or issues with integrations).
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:
  • "HIGH"
  • "MEDIUM"
  • "LOW"
To search current data, use priority as an explicit search. For example: 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: the search results must contain the value of the propertyValue.
  • EQUALS: the search results must exactly match the value of the propertyValue.
If no value is specified, the default value is 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:
  • "EVENT_ID"
  • "START_TIME"
  • "STATUS"
  • "SUBMITTER"
  • "NAME"
  • "PRIORITY"
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:
  • "ASCENDING"
  • "DESCENDING"
status string
The status of events that you want to return in the search results. Valid values include:
  • "ACTIVE"
  • "SUSPENDED"
  • "TERMINATED"
submitter string
The unique identifier (id) or name (targetName) of the submitter.
targetedRecipients string
The targetName or id of users, groups, devices, or dynamic teams that were targeted as part of the event. Multiple target names or IDs must be comma-separated. Based on your system's settings, targeted users may or may not receive notifications at the time of the event.
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.
ErrorFor 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]&nbsp;[Last Name]&nbsp; - 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:

You can enhance the response to include the following attributes:

When you call GET /events/{eventID} without any query parameters, it includes the response options and the first 100 directly-targeted recipients in the response. If you include any query parameters with the request, the response observes the query parameters and returns the requested information.

Targeted recipients are the users, groups, dynamic teams, and devices that were included in the recipient list when the event was initiated. Targeted recipients include the names of groups and dynamic teams but do not expand to include their members. Targeted recipients include users but do not include their notified devices unless the devices were explicitly added as recipients.

To retrieve an event including targeted recipients, use GET /events/{eventId}?embed=recipients&targeted=true.

Resolved recipients are the actual users and devices that received notifications. This includes members of groups and dynamic teams. There may be several resolved recipients corresponding to a single user, depending on how many of the user's devices were notified.

To retrieve an event including resolved recipients, use GET /events/{eventId}?embed=recipients

DEFINITION

GET /events/{eventId}

GET /events/{eventId}?embed=properties,recipients,annotations,messages,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:
  • "24abd4c0-bff3-4381-9f84-678580b24428"
  • "408005"

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.
  • annotations: Comments that were added to the event, either when responding or in the tracking report in the web interface.
    To see just the comments, with minimal event data, use GET /event/annotations.
  • properties: The form properties.
    This allows you to extract message details from the event.
  • recipients: A list of targeted or resolved recipients.
    By default, the resolved recipients are returned. To retrieve the targeted recipients, use this in conjunction with the ?targeted=true query parameter.
  • responseOptions: The response options included in the event. When other languages are enabled in your system, you can request responses in the user's original language by adding responseOptions.translations to your request. The two-letter code returned in the language field adheres to ISO 639 standards. For an example of the returned translation, see the ResponseOptions object.
  • messages: The HTML message content for email notifications.
    The HTML is automatically escaped, and property values are populated except for person and sender placeholders.
  • suppressions: Adds records of any suppressions for this event as a result of an event flood control rule. For an example of a returned suppression record, see Event Suppressions.
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.
ErrorFor 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:
  • "add6a38f-bed7-4169-afa2-cbaf5387ef06"
  • "41159032"

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.
ErrorFor 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:
  • "add6a38f-bed7-4169-afa2-cbaf5387ef06"
  • "41159032"

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:
  • "68aff19c-1573-46a4-97f4-f5d83e15c483"

RESPONSES

Success Response code 200 OK and an Annotation object in the response body.
ErrorFor 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:
  • "24abd4c0-bff3-4381-9f84-678580b24428"
  • "408005"

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

SuccessResponse code 200 OK and the contents of the attachment in the response body.
ErrorFor 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:
  • "24abd4c0-bff3-4381-9f84-678580b24428"
  • "408005"

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:
  • person.properties: Include the specific properties for each user. See Properties object
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:
  • "NAME"
  • "RESPONSE"
  • "GROUP"
  • "DELIVERY_DATE"
  • "DELIVERY_STATUS"
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:
  • "ASCENDING"
  • "DESCENDING"
deliveryStatus string
A comma separated list of delivery statuses. Valid values include:
  • "RESPONDED"
  • "DELIVERED"
  • "PENDING"
  • "FAILED"
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.
ErrorFor 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.

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:

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 and dynamic teams when you specify them as recipients, for example, to set the response count threshold for the group 'IT':
"recipients":
[
  {
   "id":"IT",
   "recipientType": "GROUP",
   "responseCountThreshold" : 3
  }
]

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:
  • "LOW"
  • "MEDIUM"
  • "HIGH"
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, groups, and dynamic teams that are directly targeted when this form is triggered. If the form is configured to use response counts (fill counts), you can also specify the number of people in a group or dynamic team that are required to respond. If the form is configured to use subscriptions, additional recipients not included in this list may be notified if the notification matches their subscription preferences.
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.
  • To select one of the form's existing responses, set the id field to the unique identifier of the response option (found in the web interface).
  • To modify an existing response option, include the id field of the response and any fields you want to modify.
  • To create a new response option, omit the id field and include the remaining fields.
Note that you can set text-to-speech for voice notifications but you cannot configure voice recordings or translations. See note.
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.
ErrorFor 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:
  • "24abd4c0-bff3-4381-9f84-678580b24428"
  • "408005"
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.

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.
ErrorFor 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.

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:
  • "24abd4c0-bff3-4381-9f84-678580b24428"
  • "408005"

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:
  • "ACTIVE"
  • "SUSPENDED"
  • "TERMINATED"

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.
ErrorFor 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",
  "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]&nbsp;[Last Name]&nbsp; - 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:
  • "USER": this includes events sent via an integration and events manually triggered using the Messages tab in the web user interface or using a POST /triggers request.
  • "SYSTEM": notifications from xMatters about events within xMatters (for example, device validation updates, temporary replacement notifications or issues with integrations).
expirationInMinutes integer
The number of minutes the event is active before it terminates.
floodControl Boolean
True if some notifications were not delivered because notification flood control was activated for this event.
Because the event is created before notifications are sent, this value will always be FALSE when an event is first created. Once notifications are generated and sent, the value is set to TRUE if any notifications are subject to flood control.
plan PlanReference object
The communication plan that triggered the event.
form FormReference object
The form that triggered the event.
id string
The unique identifier of this event.
incident string
The incident ID of the event.
messages Pagination of Messages object
The messages sent for the event. This field contains only the first page of results (up to 100 messages). This object is included when ?embed=messages is included in the request.
overrideDeviceRestrictions Boolean
When this value is set to true, xMatters ignores device timeframes and delays. This allows users to be notified on any device at any time, regardless of their preferences.
otherResponseCount string
For events that count responses, this represents the number of responses recieved by users counted as 'others'. When this value is greater than or equal to the otherResponseCountThreshold field, then the response counts (fill counts) for 'others' is considered to be met.
otherResponseCountThreshold string
For events that count responses, this represents the number of responses from users counted as 'others' required before the event stops sending notifictations to more other users.
priority string
The priority of the event. Use one of the following values:
  • "LOW"
  • "MEDIUM"
  • "HIGH"
properties Properties object
The properties of the form. Use these to look up the event's message details. This object is included when ?embed=properties is included in the request.
recipients Pagination of Recipient object
The recipients of the event. This field contains only the first page of results (up to 100 recipients). This object is included when ?embed=recipients is included in the request.
requirePhonePassword Boolean
When this value is true, the recipient must enter their phone password before a voice notification is played. This option cannot be used with options to leave the message content as voicemail.
responseCountsEnabled Boolean
True if the event is configured to count responses.
responseOptions ResponseOptions object
The response options sent as part of the notification. This object is included when ?embed=responseOptions is included in the request. Returns the response in the user's original language when the request includes ?embed=responseOptions,responseOptions.translations. Translations are not currently available for historical data.
submitter PersonReference object
The user who initiated the event.
status string
The current status of this event. Use one of the following values:
  • "ACTIVE"
  • "SUSPENDED"
  • "TERMINATED"
  • "TERMINATED_EXTERNAL"
  • "SUPPRESSED"
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:
  • "BRIDGE" : for xMatters-hosted bridges
  • "EXTERNAL": for externally-hosted bridges

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 TypeDescriptionExample
NumberAn integer."myNumberProperty": 323423
TextA string. Text property names include the language code."myTextProperty#en": "This is urgent. Please respond."
PasswordA string in plain text."myPasswordProperty": "ilovecats123"
ListAn array of strings that represent the selected choices."myListProperty": [
  "listItem1",
  "listItem2",
  "listItem3"
]
BooleanA Boolean value."myBooleanProperty" : true
Combo BoxA string that represents the selected choice."myComboProperty": "Oracle Database"
HierarchyAn array of objects that include category and value fields that represent each level of the hierarchy of the selected value. "myHeirarchyProperty"[
  {
    "category": "Country",
    "value": "USA"
  },
  {
    "category": "State",
    "value": "WA"
  },
  {
    "category": "City",
    "value": "Seattle"
  }
]

Text Property with Translations: The following table shows the format of each property type if the text property is submitted with translations:

Property TypeDescriptionExample
NumberAn integer."myNumberProperty": {"value": 323423}
TextA 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.",
  "translations": {
    "en": "This is urgent. Please respond.",
    "fr": "C'est urgent. Répond s'il te plait.",
 },
]
PasswordA string in plain text."myPasswordProperty": {"value": "ilovecats123"}
ListAn array of strings that represent the selected choices."myListProperty": {"values": [
  "listItem1",
  "listItem2",
  "listItem3"
]}
BooleanA Boolean value."myBooleanProperty": {"value": true}
Combo BoxA string that represents the selected choice."myComboProperty": {"value": "Oracle Database"}
HierarchyAn array of objects that include category and value fields that represent each level of the hierarchy of the selected value. "myHeirarchyProperty": {"values": [
  {
    "category": "Country",
    "value": "USA"
  },
  {
    "category": "State",
    "value": "WA"
  },
  {
    "category": "City",
    "value": "Seattle"
  }
]
]}

VoicemailOptions object

VoicemailOptions object


"voicemailOptions":
    {
    "retry": 0,
    "every": 60,
    "leave": "callbackonly"
    }

Voicemail Options settings configure the handling behavior for standard phone notifications and conference calls when voicemail is detected.

   
retry integer
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):
  • callbackandmessage: Leave the message and callback information (Message Content and Callback Info). This option cannot be selected when the event requires a phone password.
  • messageonly: Leave the message content but do not leave callback information (Message Content Only). This option cannot be selected when the event requires a phone password.
  • callbackonly: Leave a voicemail message that only includes callback information so the recipient can call in and retrieve the message (Callback Info Only). This is the default if no option is selected.
  • hangup: do not leave a message (Do Not Leave Message).

ResponseOptions object

ResponseOptions object

Example: Configure response options. This example shows how to choose an existing response, modify an existing response, and create a new response

"responseOptions" : 
[
  {
    "id" : "fee39ecf-75a7-45eb-9e63-ffc441499c4f"
  },
  {
    "id" : "085d4bea-9dfb-4d2b-8136-22e19b1baaf6",
    "redirectUrl" : "https://jira.example.com/view/INCD-2933",
    "contribution": "POSITIVE",
    "action": "STOP_NOTIFYING_TARGET"
  },
  {
      "number": 3,
      "text": "Reject",
      "description": "I cannot help",
      "prompt": "Reject",
      "action": "RECORD_RESPONSE",
      "contribution": "NEGATIVE",
      "joinConference": true,
      "allowComments": false,
      "redirectUrl": "https://jira.example.com/",
      "translations": {
        "count": 3,
        "total": 3,
        "data": [
          {
            "id": "046fd6e9-06a3-4350-acce-f672124b6484",
            "language": "hi",
            "text": "ठीक",
            "description": "ठीक"
          },
          {
            "id": "fb747f5b-10c8-48a9-9f3f-a679d2090963",
            "language": "fr",
            "text": "d'accord",
            "prompt": "",
            "description": "d'accord"
          },
          {
            "id": "1775b40f-07b2-45cd-8a05-b140286081d9",
            "language": "zh_CN",
            "text": "同意"
          }
         ]
       }
    }
  ]

The ResponseOptions object describes the response options for the event. You can use it to display the form's existing responses, override properties of existing responses, create new responses, or see the response in the user's original language. You can configure all parts of the response except for translations and voice recordings.

   
id string
The unique identifier of the response to select. To use a response as it is defined on the form, include the id field and do not provide any other values. To use an existing response and modify part of it, include the id field and the fields you want to modify. To create a new response, omit the id field and provide the remaining fields.
number integer
The keypad digit to press when responding to a voice notification.
text string
Specifies how the response choice is displayed on text devices and the mobile app, and how the link appears in email responses. Corresponds to the Response field in the web interface.
description string
Allows you to specify a longer description of the response choice to be included in emails. Corresponds to the Email Description field in the web user interface.
prompt string
The text that is used with Text-To-Speech when delivering a voice notification. Corresponds to the Voice Prompt field in the web user interface.
action string
If the form is not configured to count responses, valid values include:
  • "RECORD_RESPONSE"
  • "STOP_NOTIFYING_USER"
  • "STOP_NOTIFYING_TARGET"
  • "ESCALATE"
  • "ASSIGN_TO_USER"
  • "END"
If the form is configured to count responses, valid values include:
  • "COUNT_RESPONSE"
  • "OMIT_RESPONSE_COUNT"
contribution string
Describes whether to count the response as positive, negative, or neutral for reporting purposes. Valid values include:
  • "NONE"
  • "POSITIVE"
  • "NEUTRAL"
  • "NEGATIVE"
joinConference Boolean
When this is true, choosing the response from a voice notification automatically connects the responder to the conference bridge.
allowComments Boolean
When this is true, the recipient is given the option to add comments when they select this response option. When this is false, they're not able to add comments when they respond.
redirectUrl string
An HTTP or HTTPS URL associated with the response option. When the user responds with this choice from email, mobile apps, or the web user interface, they are automatically redirected to this URL. For example, you can use this to open a service desk ticket related to the incident or direct people to a chat room where they can discuss the issue.
translations string
The original language of the user's response. The two-letter code used in the language field adheres to ISO 639 standards. Translations are not available for historical data. For more information, see Languages in the online help.

ConferencePointer object

ConferencePointer object

Example: New xMatters-hosted conference bridge

"conference":
{
  "type": "BRIDGE"
}

Example: In-progress xMatters-hosted conference bridge

"conference":
{
  "bridgeId": "3882920",
  "type": "BRIDGE"
}

Example: Externally-hosted conference bridge with a static bridge number

"conference":
{
  "bridgeId": "Corporate WebEx",
  "type": "EXTERNAL"
}

Example: Externally-hosted conference bridge with a dynamic bridge number

"conference":
{
  "bridgeId": "Corporate WebEx",
  "type": "EXTERNAL",
  "bridgeNumber": "88737396"
}

If the form contains a conference section, you can use this section to configure the conference bridge.

If the form is configured to use xMatters-hosted conference bridges, you choose to use an in-progress xMatters conference bridge or to create a new one. You can also select an externally-hosted conference bridge if the form is configured to allow them.

If you do not specify a conference bridge, the event will either use a new xMatters-hosted conference bridge or will return an error if the form is only configured to allow externally-hosted bridges.

See Conference object for information on the conference object in GET /events results.

   
bridgeId string
The name or ID of the bridge.
  • To use an existing xMatters-hosted bridge, use the bridge number visible on the Conferences page.
  • To use a new xMatters-hosted bridge, omit this value.
  • To use an externally-hosted bridge, set this value to the name of the external bridge.
type string
The type of bridge. Use one of the following values:
  • "BRIDGE" : xMatters-hosted conferences bridge
  • "EXTERNAL" : externally-hosted conference bridge
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 or dynamic team 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:
  • "PERSON"
  • "DEVICE"
  • "GROUP"
  • "DYNAMIC_TEAM"
responseCountThreshold integer
When a form uses response counts, this value specifies the number of responses that are required before xMatters stops notifying the remaining members of a group or dynamic team. This value applies only to group and dynamic team recipients.

Annotation Object

Annotation object

  {
    "count": 1,
    "totat": 1,
    "data": [
        "id": "f223698e-dbd0-4089-a4c3-e6b7c76c639d",
        "event": {
            "id": "ced9fac9-1065-4659-82ab-1c9664a777b2",
            "eventId": "408005",
            "links": {
                "self": "/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2"
            }
        },
        "author": {
            "id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
            "targetName": "admin",
            "firstName": "Mary",
            "lastName": "McBride",
            "recipientType": "PERSON",
            "links": {
                "self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
            }
        },
        "comment": "I can help out.",
        "created": "2017-10-31T22:17:31.450Z",
        "links": {
            "self": "/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2/annotations/f223698e-dbd0-4089-a4c3-e6b7c76c639d"
        }
  }

The annotation object contains the comment that was made and links to the person who made the comment and the event that it applies to.

   
id string
The id of the annotation
event EventReference object
A link to the event where the comment was made
author PersonReference object
The person who made the comment
comment string
The comment that was made on the event.
created string
The date and time the comment was made.

Device Name Object

DeviceName object

"targetDeviceNames" : [
    {"name" : "Work Email"}, 
    {"name" : "Work Phone"}
    {"name" : "Home Email"}, 
    {"name" : "Home Phone"}, 
    {"name" : "SMS Phone"}, 
    {"name" : "Fax"}, 
    {"name" : "Numeric Pager"},
    {"name" : "Pager"},
    {"name" : "Mobile Phone"},
    {"name" : "My custom device name"}
  ]

A list of the device names to target. These names may be customized for your company but typically include options such as 'Work Email', 'Work Phone', 'Home Email', 'Home Phone', 'Mobile Phone', 'SMS Phone', and so on.

To see the list of device names configured for your system, use GET /device-names or log on to the user interface and create a device.

   
name string
The name of the type of device to target.

Messages Object

Messages object

  "messages": 
  {
    "count": 1,
    "total": 1,
    "data": 
    [
      {
        "id": "e3d4e459-732d-4b4f-8f85-159ec25db729",
        "messageType": "SUBJECT_AND_BODY",
        "subject": "Outage in NOC 4",
        "body": "<div><span style=\"white-space: nowrap;\">[First Name]&nbsp;[Last Name]&nbsp; - 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_AND_BODY": Indicates an email or mobile app message.
  • "TEXT": Indicates a text message.
  • "VOICE": Indicates a voicemail.
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:
  • "RESPONDED": The user has responded to a notification from one or more of their devices.
  • "DELIVERED": A notification has reached one or more of the user's devices.
  • "PENDING": The notification was created but has not yet been sent to any of the user's devices.
  • "FAILED": Any notification that could not be delivered to a user's devices
notifications Notifications object
A list of the notifications generated for the user.
response User Delivery Response object
If a user receives notifications to multiple devices, they can respond from each devices that receives the notification. The response field displays the last response received from the user, including the timestamp.
links SelfLink object
A link that can be used to access the event.

Notifications Object

Notifications Object

{
   "notifications": {
        "count": 1,
        "total": 1,
        "data": [
          {
            "id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6",
            "category": "DEVICE",
            "recipient": {
              "id": "32d54bb4-9b3e-438b-bb9f-ea6060f5092b",
              "targetName": "1st Aid Email",
              "recipientType": "DEVICE",
              "deviceType": "EMAIL",
              "name": "",
              "links": {
                "self": "/api/xm/1/devices/32d54bb4-9b3e-438b-bb9f-ea6060f5092b?at=2019-11-13T21%3A48%3A51Z"
              }
            },
            "deliveryStatus": "RESPONDED",
            "deliveryAttempted": "2019-11-12T16:54:14.918Z",
            "responses": {
              "count": 2,
              "total": 2,
              "data": [
                {
                  "text": "On my way - be there soon.",
                  "notification": {
                    "id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6"
                  },
                  "received": "2019-11-12T16:54:37.656+0000"
                },
                {
                  "text": "Unavailable, call 911.",
                  "notification": {
                    "id": "e6ba5be1-3482-4b61-9d98-eddd049bf1f6"
                  },
                  "received": "2019-11-12T16:54:31.328+0000"
                }
              ]
            },
            "delivered": "2019-11-12T16:54:15.789Z",
            "responded": "2019-11-12T16:54:31.328Z"
          }
        ]
      },

This object contains information about the notification that was sent to the users when an event occurred.

   
id string
The unique identifier of this notification.
recipient Recipient object
The user, group, device or dynamic team in xMatters that can receive notifications.
created string
The timestamp of when the notification was created.
delivered string
The timestamp of when the notification was delivered to the user.
responded string
The timestamp of when the user responded to the notification.
deliveryStatus string
The status of the delivery. Valid values include:
  • "RESPONDED"
  • "DELIVERED"
  • "PENDING"
  • "FAILED"
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:
  • START_TIME, PRIORITY, SUBMITTER, INTEGRATION
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:
  • "ASCENDING"
  • "DESCENDING"

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.
ErrorFor 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,
      "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.
ErrorFor 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(fFound 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,
      "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.
ErrorFor 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"
}' "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';
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"
}

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,
  "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 of the confererence bridge's purpose.
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.
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.

RESPONSES

Success Response code 201 Created and a Conference Bridge object in the response body.
ErrorFor 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"
}' "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';
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"
}
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,
  "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.
ErrorFor 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,
  "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.
ErrorFor 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,
  "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 of the confererence bridge's purpose.
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.
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:
  • NAME: searches only the form name
  • DESCRIPTION: searches only the form description
  • WORKFLOW: searches only the forms with the name of the associated workflow
  • NAME,DESCRIPTION: searches both the name and description (the search term can appear in either – this functions the same as when no field is specified)
embed string
A comma-separated list of the objects to embed in the response.
  • recipients: Includes any recipients specified in the form layout.
  • scenarios: Includes scenarios available for use by a specific form in a plan.
  • integrations:
enabledFor string
Returns all the forms that are enabled for a specific component. Valid values include:
  • MOBILE
  • UI
plans.planType string
Filters forms by the type of the associated workflow. Valid values include:
  • PLAN: returns only the forms that are based on any custom workflows you created, or installed workflow templates that were converted to custom workflows.
  • BUILT_IN: returns only the forms that are part of installed workflow templates.
  • RESERVED: returns only the forms that are part of reserved workflows, such as the xMatters Workflow for Incident Management
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:
  • USER_DEFINED: The order of user-specified items in the web interface
  • NAME: the form name
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:
  • "ASCENDING"
  • "DESCENDING"
triggerType array[string]
Returns forms by trigger type. Valid values include:
  • FLOW: Returns only forms that trigger flows
  • MESSAGING: Returns only forms that trigger messages
  • FLOW,MESSAGING: Returns forms that trigger both flows and messages

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.
ErrorFor 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.
  • responseOptions: includes the available response choices defined for the form.
  • recipients: includes any recipients specified in the form layout. If the recipient's 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.
  • scenarios: Includes scenarios available for use by a specific form in a plan.
enabledFor string
Returns only the forms in the plan that are enabled for a specific component. Valid values include:
  • MOBILE
  • UI
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:
  • USER_DEFINED: The order of user-specified items in the web interface
  • NAME: The form name
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:
  • "ASCENDING"
  • "DESCENDING"
triggerType array [string]
Returns forms by trigger type. Valid values include:
  • FLOW: Returns only forms that trigger flows
  • MESSAGING: Returns only forms that trigger messages
  • FLOW,MESSAGING: Returns forms that trigger both flows and messages

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.
ErrorFor 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 /plans/{planId}/forms/{formId}
GET /plans/{planId}/forms/{formId}/recipients
GET /plans/{planId}/forms/{formId}?embed=responseOptions,recipients
GET /plans/{planId}/forms/{formId}?embed=responseOptions,responseOptions.translations

URL PARAMETERS

   
planId string
The unique identifier (id) or name (targetName) of the plan the forms belong to. Names must be URL-encoded.
formId string
The unique identifier (id) or name (targetName) of the form you want to retrieve. Names must be URL-encoded. 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 users, groups, devices, or dynamic teams that were listed as the default recipient(or recipients) of the form.
embed string
A comma-separated list of objects to embed in the response. Available options are:
  • responseOptions: the response options defined for the form. To return responses in the user's original language, use responseOptions.translations. When other languages are enabled in your system, you can request responses in the user's original language by adding responseOptions.translations to your request. The two-letter code returned in the language field adheres to ISO 639 standards. For an example of the returned translation, see the ResponseOptions object.
  • recipients: The targetName or id of the users, group, devices, or dynamic teams that were listed as the default recipient (or recipients) of the 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 Form object in the response body.
ErrorFor 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:
  • translations: The translated response option for languages supported by the instance. The two-letter code used in the language field adheres to ISO 639 standards.

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.
ErrorFor 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:

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.
ErrorFor 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:
  • FLOW: Forms that trigger flows
  • MESSAGING: Forms that trigger messages

  • 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.
ErrorFor 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. Youre 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                             &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;\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                             &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;\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                             &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;\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                             &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;\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 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.
ErrorFor 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:
  • "RECORD_RESPONSE"
  • "STOP_NOTIFYING_USER"
  • "STOP_NOTIFYING_TARGET"
  • "ESCALATE"
  • "ASSIGN_TO_USER"
  • "END"
If the form is configured to count responses, valid values include:
  • "COUNT_RESPONSE"
  • "OMIT_RESPONSE_COUNT"
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:
  • "NONE"
  • "POSITIVE"
  • "NEUTRAL"
  • "NEGATIVE"
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.
ErrorFor 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.
ErrorFor 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                             &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;\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                             &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;\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                             &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;\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                             &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;\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.
ErrorFor 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.
ErrorFor 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

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 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:

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:
  • CONFERENCE_BRIDGE
  • CUSTOM_SECTION
  • DEVICE_FILTER
  • HANDLING_OPTIONS
  • ATTACHMENTS
  • SENDER_OVERRIDES
  • RECIPIENTS
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:
  • XMATTERS_BRIDGES_ONLY
  • EXTERNAL_BRIDGES_ONLY
  • XMATTERS_AND_EXTERNAL_BRIDGES

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.
includeInCallbask 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 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:
  • "Work Email"
  • "Home Email"
  • "Mobile Phone"
  • "Pager"
  • "Fax"
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:
  • MOBILE_TEXT: This group type applies to ANDROID_PUSH, APPLE_PUSH, and TEXT_PHONE devices.
  • VOICE: This group type applies to VOICE and VOICE_IVR devices.
  • EMAIL_OTHER: This group type applies to all other device types.

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
            }
        }
   ] 

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:
  • HIGH
  • MEDIUM
  • LOW
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:
  • MINUTES
  • HOURS
  • DAYS

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"
                }
            },
          }
        ]
      },
    }, 
   ]

Provides information on the Recipients section of a form. Recipients are users, groups, dynamic teams, 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.

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                             &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;\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: the message is read as written.
  • CHARACTERS: Individual characters are spelled out. For example, ATV is spelled out as the individual letters "A", "T", "V" instead pronounced as one word "Atvee"
  • TTS: A text-to-speech engine is used to read out the phrase.
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:
  • PHRASE: the message is read as written.
  • CHARACTERS: Individual characters are spelled out. For example, ATV is spelled out as the individual letters "A", "T", "V" instead pronounced as one word "Atvee"
  • TTS: A text-to-speech engine is used to read out the phrase.
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:
  • PHRASE: the message is read as written.
  • CHARACTERS: Individual characters are spelled out. For example, ATV is spelled out as the individual letters "A", "T", "V" instead pronounced as one word "Atvee"
  • TTS: A text-to-speech engine is used to read out the phrase.
formProperty string
The unique identifier (UUID) or name of the form property.

GROUPS

Groups allow you to notify a set of people, devices, dynamic teams, and other groups according to who is on duty. If a notification is not handled on time, xMatters can then escalate it to the next group member according to the group's timeline.

The /groups endpoint allows you to retrieve, create, modify, and delete groups.

Use Group Roster to add or remove members from the group.
Use On Call to retrieve who is currently on duty.

For more information on group settings, see Group Options and Settings

This API does not support legacy groups that use shared teams across shifts. To convert such a group to one that can be accessed with this API, locate it in the user interface and click the Unshare button.

Get a group

GET a group

REQUEST (get a group by name and 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:
  • supervisors: Up to the first 100 group supervisors.
  • observers: Returns the id and name of the role or roles set as observers for the group. If the observedByAll field returns true, the group is visible to all roles with the appropriate permission settings. If observedByAll field returns false, the group creator has limited the visibility of the group to specific roles, and the selected roles are displayed in the return.
  • services: Returns the list of services owned by the group.

RESPONSES

Success Response code 200 OK and a Group object in the response body.
ErrorFor 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 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?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:
  • observers: Returns the id and name of the role or roles set as observers for the group. If the observedByAll field returns true, the group is visible to all roles with the appropriate permission settings. If observedByAll field returns false, the group creator has limited the visibility of the group to specific roles, and the selected roles are displayed in the return.
  • supervisors: A Paginated list of the group's supervisors. Returns a Person object or PersonReference object, depending on what permissions the authenticating user has.
fields string
Defines the field to search when a search term is specified. Valid values include:
  • NAME: searches only the group name
  • DESCRIPTION: searches only the group description
  • SERVICE_NAME: searches for the name of a service
  • NAME,DESCRIPTION,SERVICE_NAME: searches the group name, description, and service name fields (the search term can appear in just one of the fields – this functions the same as when no field is specified)
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:
  • ALL_SHIFTS: Returns groups where no shifts have any members.
  • ANY_SHIFTS: Returns groups where at least one shift has no members.
members string
The targetName or id of the users, dynamic teams, or devices that are members of a group. To search for multiple members, use a comma-separated list and UTF-8 encode any spaces in the names. For example, the "DBA Admins" dynamic team becomes "DBA%20Admins". The returned results show all groups that contain any of the queried members.
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
The unique identifier (id) or name of a site. Adding sites to the search returns a list of groups for a specific site.
Example:San Ramon
Example:960ffa54-b6d3-42b7-8025-7d95ff599976.
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:
  • NAME
  • GROUPTYPE: Returns all Broadcast groups together followed by all On-Call groups.
  • STATUS
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:
  • ASCENDING
  • DESCENDING
status string
The status of the group. Valid values include:
  • ACTIVE
  • INACTIVE
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.
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes.

Create a group

Create a group

REQUEST - Create group
This request shows how to create a group named "Executives" with two group supervisors, and the "Developer" role as an observer. This example does not include the id field. In this case, xMatters generates an id for this group and returns it in the id field of the response.

curl --user username --header "Content-Type: application/json" --request POST -d '{
    "recipientType": "GROUP", 
    "status": "ACTIVE", 
    "allowDuplicates" : true, 
    "useDefaultDevices" : true,
    "observedByAll" : false,
    "observers" : [
        {"name:" "Developer"}
    ],
    "description": "C-suite executives",
    "site": "dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
    "supervisors" : 
    [
      "410c96c4-8fdf-4936-a36f-13890b89ac3f", 
      "a608fa11-552a-4806-b247-48f083a20081"
    ],
    "targetName": "Executives"
}' "https://acmeco.xmatters.com/api/xm/1/groups" 
/**
 * This script is configured to work 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 broadcast group
This request shows how to create a broadcast group in your xMatters instance.

curl --user username --header "Content-Type: application/json" --request POST -d '{
    "recipientType": "GROUP",
    "groupType": "BROADCAST", 
    "status": "ACTIVE", 
    "allowDuplicates" : true, 
    "useDefaultDevices" : true,
    "observedByAll" : true,
    "description": "C-suite executives",
    "site": "dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
    "supervisors" : 
    [
      "410c96c4-8fdf-4936-a36f-13890b89ac3f", 
      "a608fa11-552a-4806-b247-48f083a20081"
    ],
    "targetName": "Executive Notifications",
    "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.groupType = 'BROADCAST';
data.targetName = 'Executive Notifications';
data.id '4888989a-3dd2-4edc-b0cd-ce4623cc454c's;
data.status = 'ACTIVE';
data.allowDuplicates = true;
data.useDefaultDevices = true;
data.observedByAll = true;
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",
    "groupType": "BROADCAST"
    "targetName": "Executive Notifications",
    "status": "ACTIVE",
    "allowDuplicates": True,
    "useDefaultDevices": True,
    "observedByAll": True,
    "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 group (with a specific ID)
This request shows how to create the group from the above example but assigns a value to the id field. This allows you to synchronize the id field 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 broadcast group)

{     
  "id": "4888989a-d32d-4edc-b0cd-ce4623ab121c",
  "targetName": "Executive Notifications",
  "groupType": "BROADCAST",
  "recipientType": "GROUP",
  "status": "ACTIVE",
  "externallyOwned": false,
  "allowDuplicates": true,
  "useDefaultDevices": true,
  "observedByAll": true,
  "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-d32d-4edc-b0cd-ce4623ab121c"
  }
}

Creates an empty group in xMatters.

The response returns a 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 or Broadcast 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. 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 teams) as members.

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 groups, see also:

.

DEFINITION

POST /groups

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:
  • ON_CALL: On call groups have shifts and notifications are only sent to members that are on-call during a shift. This is the default if groupType is not specified.
  • BROADCAST: Broadcast groups cannot contain shift or calendar information, and send notifications to all members of the group at once.
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:
  • "ACTIVE"
  • "INACTIVE"
If this value is not provided, the new group is set to "ACTIVE".
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.

RESPONSES

Success Response code 201 Created and a Group object in the response body.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes.

Group objects

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 and ON_CALL. Broadcast groups send notifications to all members at once and cannot contain any calendar or shift information. 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:
  • ACTIVE
  • INACTIVE
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 teams, 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:
  • "GROUP"
  • "PERSON"
  • "DEVICE"
  • "DYNAMIC_TEAM"
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.

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?embed=shifts,site,lastLogin
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:
  • lastLogin: Returns the last login date for each user. Valid for both Broadcast and On-Call groups.
  • shifts: For use with On-Call groups only. Use the ?embed=shifts query parameter to include shift information in the response.
    Example: /groups/IT/members?embed=shifts
  • site: Returns the site object for each user and device owner. Valid for both Broadcast and On-Call groups.
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:
  • ASCENDING
  • DESCENDING

RESPONSES

Success Response code 200 OK and a Pagination of GroupMembership object.
ErrorFor 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, devices, or dynamic teams. 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:
  • "PERSON"
  • "GROUP"
  • "DEVICE"
Dynamic teams cannot be added to the group roster with this API.

RESPONSES

Success Response code 200 OK and a Recipient object in the response body.
ErrorFor 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, dynamic teams, 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.
ErrorFor 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:
  • users-v1: User Upload v1.5
  • epic-v1: Epic ZipSync Upload v1.3
sortBy string
Determines the criteria by which imports are sorted:
  • "NAME": This parameter is only available for User Uploads. The unique upload identifier created when the user upload file was submitted. Default value is "User Upload v1.5 at {date-timestamp}"
  • "STATUS": The status of the upload at the time of the request. Available values are:
    • PENDING
    • PROCESSING
    • COMPLETE
    • FAILED
  • "STARTED": The date and time when the uploaded file began processing.
  • "BY": This parameter is only available for User Uploads. The PersonReference object of the user who uploaded the file.
  • "PROCESSED_COUNT": The percentage of the file processed at the time of the request.
The returned import job results are sorted by the timestamp of when xMatters received the uploaded file. Use 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:
  • "ASCENDING"
  • "DESCENDING"

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.
ErrorFor 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.
ErrorFor 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:
  • "LINE": Sorts messages by the value of the Line column
  • "COLUMN": Groups messages together by the contents of the Column field.
  • "MESSAGE_TYPE": Sorts messages by their type:
    • PROCESSING_ERROR
    • SYNTAX_ERROR
    • VALIDATION_ERROR
    • VALIDATION_WARNING
  • "MESSAGE_LEVEL": Sorts messages by their escalation level:
    • ERROR
    • WARN
    • INFO
  • "DESCRIPTION": Sorts messages by the description of the error.
If not specified, messages are sorted by their line number. Use 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:
  • "ASCENDING"
  • "DESCENDING"

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.
ErrorFor 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:
  • PENDING
  • PROCESSING
  • COMPLETE
  • FAILED
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:
  • ERROR
  • WARN
  • INFO
messageType string
Sorts messages by their type:
  • PROCESSING_ERROR
  • SYNTAX_ERROR
  • VALIDATION_ERROR
  • VALIDATION_WARNING
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:
  • SUMMARY: The title of the incident
  • DESCRIPTION: The description of the incident.
  • INCIDENT_IDENTIFIER: The unique alpha-numeric incident number. The default identifier for incidents created by xMatters is INC. For example: INC-145.
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:
  • OPEN
  • IN_PROGRESS
  • MITIGATED
  • RESOLVED
  • REJECTED
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:
  • CRITICAL
  • HIGH
  • MEDIUM
  • LOW
  • MINIMAL

RESPONSES

Success Response code 200 OK and a Pagination of Incidents objects in the response body.
ErrorFor 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.
ErrorFor 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.

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:

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, groups, and dynamic teams 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.
ErrorFor 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:
  • Critical
  • High
  • Medium
  • Low
  • Minimal
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:
  • Open
  • In_Progress
  • Mitigated
  • Resolved
  • Rejected

RESPONSES

Success Response code 201 Created and a Incidents object in the response body.
ErrorFor 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 = 'Mitigaged';
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:
  • CRITICAL
  • HIGH
  • MEDIUM
  • LOW
  • MINIMAL
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:
  • OPEN
  • IN_PROGRESS
  • MITIGATED
  • RESOLVED
  • REJECTED

RESPONSES

Success Response code 201 Created and a Incident object in the response body.
ErrorFor 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.
ErrorFor 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:
  • CRITICAL
  • HIGH
  • MEDIUM
  • LOW
  • MINIMAL
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:
  • OPEN
  • IN_PROGRESS
  • MITIGATED
  • RESOLVED
  • REJECTED
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. Searching by requestId returns the incident that was initiated when the trigger fired.
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:
  • CRITICAL
  • HIGH
  • MEDIUM
  • LOW
  • MINIMAL

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.
ErrorFor 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:
  • INBOUND_WEBHOOK: returns only inbound integrations
  • OUTBOUND_WEBHOOK: returns only outbound integrations
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.
  • logs: Return the 100 most recent logs associated with each integration.

RESPONSES

Success Response code 200 OK and a pagination of Integration objects in the response body.
ErrorFor 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.
ErrorFor 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:
  • "INBOUND_WEBHOOK"
  • "OUTBOUND_WEBHOOK"
environment string
The location of the inbound or outbound integration. Values include:
  • HOSTED: The integration is hosted on the xMatters Cloud
  • ONPREMISE: The integration is hosted on an xMatters Agent or Integration Agent in your local environment. (This option is currently supported for outbound integrations only.)
operation string
The action the integration performs. Valid values for inbound integrations include:
  • CREATE_EVENT_SIMPLE: Use the incoming request to create a new event using one of the forms in the communication plan. (Create a new xMatters Event)
  • CREATE_EVENT: Use JavaScript to transform the data of the incoming request to create a new event using one of the forms in the communication plan. (Transform content to create a new xMatters event)
  • RUN_SCRIPT: Execute a script, such as a SOAP or REST request, in xMatters online help or on an Integration Agent. (Run a script)
Valid values for outbound integrations include:
  • SEND_WEBHOOK: Send a web request to an HTTP endpoint.(Send a webhook)
  • SEND_TO_IA: Send webhooks to an Integration Agent or integration service. This option requires that your request have the environment set to ONPREMISE, and you must also include an integrationService parameter. (Send to Integration Agent)
  • RUN_SCRIPT: Execute a script, such as a SOAP or REST request, in xMatters. (Run a script)
triggeredBy string
Outbound integrations only: The system activity that triggers the outbound integration. Valid values include:
  • STATUS
  • DELIVERYSTATUS
  • RESPONSE
  • ANNOTATION
  • ESCALATION
  • TARGETEDRECIPIENTFAILURE
authenticationType string
Inbound integrations only: The authentication method used to trigger the integration. The default is ANY, which allows all methods. Valid values are:
  • ANY
  • URL
  • BASIC
  • API_KEY
  • OAUTH
createdBy string
How the integration was created. Valid values include:
  • IB
  • FLOW
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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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:
  • "INBOUND_WEBHOOK"
  • "OUTBOUND_WEBHOOK"
operation string
The action the integration performs. Valid values for inbound integrations include:
  • CREATE_EVENT_SIMPLE: Use the incoming request to create a new event using one of the forms in the communication plan. (Create a new xMatters Event)
  • CREATE_EVENT: Use JavaScript to transform the data of the incoming request to create a new event using one of the forms in the communication plan. (Transform content to create a new xMatters event)
  • RUN_SCRIPT: Execute a script, such as a SOAP or REST request, in xMatters online help or on an Integration Agent. (Run a script)
Valid values for outbound integrations include:
  • SEND_WEBHOOK: Send a web request to an HTTP endpoint.(Send a webhook)
  • SEND_TO_IA: Send webhooks to an Integration Agent or integration service. This option requires that your request have the environment set to ONPREMISE, and you must also include an integrationService parameter. (Send to Integration Agent)
  • RUN_SCRIPT: Execute a script, such as a SOAP or REST request, in xMatters. (Run a script)
triggeredBy string
Outbound integrations only: The system activity that triggers the outbound integration. Valid values include:
  • STATUS
  • DELIVERYSTATUS
  • RESPONSE
  • ANNOTATION
  • ESCALATION
  • TARGETEDRECIPIENTFAILURE
createdBy string
How the integration was created. Valid values include:
  • IB
  • FLOW
authenticationType string
Inbound integrations only: The authentication method used to trigger the integration. The default is ANY, which allows all methods. Valid values are:
  • ANY
  • URL
  • BASIC
  • API_KEY
  • OAUTH
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:
  • HOSTED: The integration is hosted on the xMatters Cloud
  • ONPREMISE: The integration is hosted on an xMatters Agent or Integration Agent in your local environment. (This option is currently supported for outbound integrations only.)
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.
  • Completed: the request was processed successfully.
  • Failed: the request failed during processing.
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:

OAuth Workflow

  1. Use your client ID and authentication credentials to obtain an access token and a refresh token.
  2. Once you have obtained these tokens you do not need to store authentication credentials.
  3. You can now authorize requests using the access token instead of a user ID and password.
  4. 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:
  • shift: ShiftReference objects are enhanced to include additional Shift object information.
  • members.owner: Device members include enhanced information about the device's owner in the owner object, including the following fields:
    • targetName
    • firstName
    • lastName
    • language
    • timezone
    • webLogin
Example:/groups/{groupID}?embed=shift,members.owner

RESPONSES

Success Response code 200 OK and a Pagination of On-call objects in the response body.
ErrorFor 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:
  • NONE
  • PEER
  • MANAGEMENT
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:
  • ACTIVE
  • INACTIVE

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.
ErrorFor 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, DynamicTeam object, or Devices object
Refers to a person, group, dynamic team, or device in xMatters. The displayName field provides the dynamic team name, 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
  • roles: includes the person's roles in the result.
  • supervisors: includes the person's supervisors in the result.

RESPONSES

Success Response code 200 OK and a Person object in the response body.
ErrorFor 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:

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.
ErrorFor 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.
  • true: Returns users who have a device, or devices.
  • false: Returns users with no devices.
devices.email.exists Boolean
Returns a Pagination of users who have (or don't have) email devices associated with their account.
  • true: Returns users who have at least one email device.
  • false: Returns users with no email devices.
devices.failsafe.exists Boolean
Returns a Pagination of users who have (or don't have) failsafe devices associated with their account.
  • true: Returns users who have at least one device marked as failsafe.
  • false: Returns users with no failsafe devices.
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.
  • true: Returns users who have at least one mobile device.
  • false: Returns users with no mobile devices.
devices.sms.exists Boolean
Returns a Pagination of users who have (or don't have) SMS devices associated with their account.
  • true: Returns users who have at least one SMS device.
  • false: Returns users with no SMS devices.
devices.voice.exists Boolean
Returns a Pagination of users who have (or don't have) voice devices associated with their account.
  • true: Returns users who have at least one voice device.
  • false: Returns users with no voice devices.
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:
  • INVALID: The user's device is invalid.
  • TESTED: The user's device was successfully tested.
  • UNTESTED: The user's device has not been tested.
  • UNTESTED_FAILSAFE: The user's device is untested, but is marked as a failsafe/default device.
  • PENDING: The user's device is being tested, but has not completed the test.
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:
  • FIRST_NAME
  • LAST_NAME
  • TARGET_NAME
  • WEB_LOGIN
  • EMAIL_ADDRESS
  • PHONE_NUMBER
When multiple values are provided, the search uses the OR operand to return results that match any of the requested terms.

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.
  • true: Returns users who are members of at least one group.
  • false: Returns users who are not members of any groups.
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:
  • firstName
  • lastName
  • targetName
  • webLogin
  • phoneNumber: Field of one of the user's devices.
  • emailAddress: Field of one of the user's devices.
Examples:
GET /people?search=mary could return the following users:
  • Users whose first name or last name contains "mary"; for example "Mary McBride", "Rosemary Smith", "George Cromary".
  • Users whose user ID contains "mary"; for example "mary.mcbride", "tomarye21".
  • Users who own an email device whose address contains "mary"; for example: "marylou@example.com", "admin@rosemaryandsage.com".
  • Phone number fields cannot contain these characters so this search term would not match phone number devices.
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 /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:
  • FIRST_LAST_NAME
  • TARGET_NAME
  • STATUS
  • WEB_LOGIN
  • LAST_LOGIN
  • SITE
  • ROLES
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:
  • ASCENDING
  • DESCENDING
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.
  • true: Returns users who have a supervisor, or supervisors listed.
  • false: Returns users who do not have 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.
ErrorFor 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:
  • FULL_USER: Full users are users who actively take part during the response process.
  • STAKEHOLDER_USER: Stakeholder users are users who don't need to take action during the response process. They cannot respond to any notifications they receive, act as an incident resolver, trigger forms that send messages, or initiate incidents or flows.
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:
  • "ACTIVE"
  • "INACTIVE"
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.
ErrorFor 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:

  1. If the id provided is not currently in the xMatters system, a new user is created.
  2. If the id currently 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.
ErrorFor 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.
ErrorFor 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:
  • E164: E.164 standard format
  • COUNTRY_CODE: Formatted with spaces

RESPONSES

Success Response code 200 OK and a Pagination of Device objects in the response body.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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:
  • FULL_USER: Full users are users who actively take part during the response process.
  • STAKEHOLDER_USER: Stakeholder users are users who don't need to take action during the response process. They cannot respond to any notifications they receive, act as an incident resolver, trigger forms that send messages, or initiate incidents or flows.
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.
  • "PLAN" returns only integrations based on communication plans, including packaged integrations from xMatters, built-in integrations you converted to communication plans, and any custom plans you created.
  • "BUILT_IN" returns only configurations of built-in integrations.
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:
  • MOBILE
  • UI
embed string
A list of additional objects to include in the response.
  • creator: includes detailed information on the creator of built-in integrations in the response (basic information is included by default).
  • constants: includes any plan constants in the response.
  • endpoints: includes any plan endpoints in the response.
  • forms: any forms associated with a communication plan.
  • propertyDefinitions: includes any properties defined in the plans.
  • integrations: includes any inbound or outbound integrations defined in the plans. Change the embed parameter to integrations.logs to include the 25 most recent logs for each integration 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:
  • NAME: searches only the plan name
  • DESCRIPTION: searches only the plan description
sortBy string
Determines the criteria by which plans are sorted.
  • "NAME": sorts plans by their name.
  • "DESCRIPTION": sorts plans by their description.
If not specified, plans are sorted by their name. Use 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:
  • "ASCENDING"
  • "DESCENDING"
If not specified, results are sorted in ascending order.
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.
ErrorFor 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:
  • a2e6b439-3396-4580-8793-1565b64d417f
  • Monitoring%20Tool%20X (this example has the space URL-encoded)
Because names can change, we recommend using the unique identifier (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.
  • creator: includes detailed information on the creator of built-in integrations in the response (basic information is included by default).
  • constants: includes any plan constants in the response.
  • endpoints: includes any plan endpoints in the response.
  • forms: any forms associated with a communication plan.
  • propertyDefinitions: includes any properties defined in the plan.
  • integrations: includes any inbound or outbound integrations defined in the plan.

RESPONSES

Success Response code 200 OK and a Plan object in the response body.
ErrorFor 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.
creator string
The creator of the communication plan. (Not sure how this works??)

RESPONSES

Success Response code 201 Created and a Plan object in the response body.
ErrorFor 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.
  • "ERROR": only failed requests are logged.
  • "INFO": all requests (up to a maximum) are logged.
For more information, see Activity Stream in the xMatters online help.
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.
ErrorFor 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.
ErrorFor 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.
  • "PLAN": an integration based on a communication plan.
  • "BUILT_IN": a built-in 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.
  • "ERROR": only failed requests are logged.
  • "INFO": all requests (up to a maximum) are logged.
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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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:
  • "NO_AUTH"
  • "BASIC"
  • "OAUTH2"
  • "OAUTH2_FORCE": Salesforce
  • "OAUTH_SLACK": Slack
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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
  • "XMATTERS": The endpoint for your xMatters instance.
  • "EXTERNAL": An endpoint for an external system.
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.
ErrorFor 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.
ErrorFor 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:
  • BOOLEAN
  • HIERARCHY
  • LIST_TEXT_MULTI_SELECT
  • LIST_TEXT_SINGLE_SELECT
  • NUMBER
  • PASSWORD
  • TEXT

RESPONSES

Success Response code 200 Updated and a Plan property object in the response body.
ErrorFor 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:

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:
  • BOOLEAN
  • HIERARCHY
  • LIST_TEXT_MULTI_SELECT
  • LIST_TEXT_SINGLE_SELECT
  • NUMBER
  • PASSWORD
  • TEXT
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:

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.
ErrorFor 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:
  • MOBILE
  • UI

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.
ErrorFor 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.
  • properties: The scenario properties.
  • plan: Use embed=plan to include details on the communication plan the scenario belongs to. Without the embed, a basic plan reference is included.
  • form: Use embed=form to include details on the form used by the scenario. Without the embed, a basic form reference is included.
  • properties.translations: Use embed=properties.translations to include the two letter language code, and the translated text for a text property.

RESPONSES

Success Response code 200 OK and a Scenario object in the response body.
ErrorFor 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.
  • properties.translations: Use embed=properties.translations to include the two letter language code, and the translated text for a text property.
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:
  • USER_DEFINED: The order of user-specified scenarios in the web interface
  • NAME: the scenario name
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:
  • "ASCENDING"
  • "DESCENDING"

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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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))


RESPONSE

{
  "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, groups, and dynamic teams 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.
ErrorFor 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.
ErrorFor 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:

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.
ErrorFor 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.
ErrorFor 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:
  • HIGH
  • MEDIUM
  • LOW
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:
  • NAME: Returns messages by name.
  • OWNER: Returns messages by the owner's name.
  • RECURRENCE: Returns messages by frequency and sheduled start time.
  • LAST_MESSAGE: Returns messages based on the last message sent.
  • NEXT_MESSAGE: Returns messages based on the next message scheduled to be sent.
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:
  • ASCENDING
  • DESCENDING

RESPONSES

Success Response code 200 OK and a Pagination of Scheduled Messages objects in the response body.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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:
  • "ONCE" - Use the startTime parameter to send the message to recipients once.
  • "DAILY" - Use the repeatEvery, end, and startTime parameters to send the message to recipients on a daily basis.
  • "WEEKLY" - Use the repeatEvery, onDays, startTime, and end parameters to send the message to recipients on a weekly basis.
  • "MONTHLY" - The on parameter is required. Use the months, startTime, and end parameters to send the message to recipients on a monthly basis.
    • "DATE_OF_MONTH" - requires dateOfMonth
    • "DAY_OF_WEEK" - requires dayOfWeekClassifier, and dayOfWeek
  • "YEARLY" - Use the end and startTime parameters to send the message recipients on a yearly basis.
repeatEvery string
Number of days between repetitions.

Required when frequency is: DAILY, WEEKLY
onDays array [string]
Valid values include any combination of:
  • "SU"
  • "MO"
  • "TU"
  • "WE"
  • "TH"
  • "FR"
  • "SA"
Required when frequency is: WEEKLY
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:
  • "JAN"
  • "FEB"
  • "MAR"
  • "APR
  • "MAY"
  • "JUN"
  • "JUL"
  • "AUG"
  • "SEP"
  • "OCT"
  • "NOV"
  • "DEC"
The following parameters are available to use with months:
  • dateOfMonth
  • dayOfWeekClassifier
  • dayOfWeek
Required when frequency is: MONTHLY
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:
  • "FIRST"
  • "SECOND"
  • "THIRD"
  • "FOURTH"
  • "LAST"
Required when frequency is: MONTHLY
dayOfWeek string
Used with dayOfWeekClassifier to define which day of the week the message should be sent.
Valid values include:
  • "SU"
  • "MO"
  • "TU"
  • "WE"
  • "TH"
  • "FR"
  • "SA"
Required when frequency is: MONTHLY
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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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:
  • NAME: The name of the service.
  • DESCRIPTION: The description of the service.
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.
ErrorFor 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}

QUERY PARAMETERS

   
serviceId string
The unique identifier (UUID) of a service in xMatters. For example: ab1d6091-7d58-41e2-af72-49c69b3d9b65.

RESPONSES

Success Response code 200 OK and a Services Object in the response body.
ErrorFor 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.

RESPONSES

Success Response code 201 Created and a Services Object in the response body.
ErrorFor 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.
ErrorFor 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 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
  • members: Get the names of the members in a specific shift.
    Example:
    /groups/{groupId}/shifts/{shiftId}?embed=members
    Using the Query Parameter ?embed=members provides more information on the shift, and less information about the members in the shift. To receive a response with more member information, use Get members in a shift.
  • rotation: Get shift rotation information. For more information, see Rotation object.

RESPONSES

Success Response code 200 OK and a Shift object in the response body.
ErrorFor 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

URL PARAMETERS

   
groupID string
The unique idetifier (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: Get the names of the members in a specific shift.
    Example:
    /groups/{groupId}/shifts/{shiftId}?embed=members
    Using the Query Parameter ?embed=members provides more information on the shift, and less information about the members in the shift. To receive a response with more member information, use Get members in a shift.
  • rotation: Get shift rotation information. For more information, see Rotation object.

RESPONSES

Success Response code 200 OK and a Pagination of Shift objects in the response body.
ErrorFor 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.
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes.

Create a shift

Add a shift

REQUEST (add 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.
ErrorFor 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:
  • "None"
  • "Peer"
  • "Management"

If you specify an escalation type other than None you must also specify an escalation delay. You cannot specify an 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.
ErrorFor 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.
ErrorFor 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": "Test1",
    "firstName": "Test",
    "lastName": "Testy",
    "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:
  • "ONCE" - no other parameters required.
  • "DAILY" - requires repeatEvery and end.
  • "WEEKLY" - requires repeatEvery, onDays, and end.
  • "EVERY_WEEKDAY" - requires end
  • "EVERY_WEEKEND_DAY" - requires end
  • "MONTHLY" - requires on, months, and end
    • "DATE_OF_MONTH" - requires dateOfMonth
    • "DAY_OF_WEEK" - requires dayOfWeekClassifier, and dayOfWeek
  • "YEARLY" - requires end
  • "HOLIDAY" - Holiday shifts are active only on site holidays; they are not active on other days. The duration of the holiday shift is determined by the start and end times. For HOLIDAY shifts, the group must have a site to use for holidays and this site must have holidays configured.
repeatEvery string
Number of days between repetitions.

Required when frequency is: DAILY, WEEKLY
onDays array [string]
Valid values include any combination of:
  • "SU"
  • "MO"
  • "TU"
  • "WE"
  • "TH"
  • "FR"
  • "SA"
Required when frequency is: WEEKLY
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:
  • "JAN"
  • "FEB"
  • "MAR"
  • "APR
  • "MAY"
  • "JUN"
  • "JUL"
  • "AUG"
  • "SEP"
  • "OCT"
  • "NOV"
  • "DEC"
The following parameters are available to use with months:
  • dateOfMonth
  • dayOfWeekClassifier
  • dayOfWeek
Required when frequency is: MONTHLY
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:
  • "FIRST"
  • "SECOND"
  • "THIRD"
  • "FOURTH"
  • "LAST"
Required when frequency is: MONTHLY
dayOfWeek string
Used with dayOfWeekClassifier to define which day of the week the shift occurs.
Valid values include:
  • "SU"
  • "MO"
  • "TU"
  • "WE"
  • "TH"
  • "FR"
  • "SA"
Required when frequency is: MONTHLY
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:
  • "None"
  • "Peer"
  • "Management"
Shift members that do not immediately follow an escalation delay have a escalationType value of "None" and a delay of 0. The value None may also represent an escalation delay that is not categorized.
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.

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.
ErrorFor 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:
  • NAME
  • ADDRESS
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:
  • NAME
  • ADDRESS
  • STATUS
  • COUNTRY
  • GEOCODED
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:
  • ASCENDING
  • DESCENDING
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:
  • ACTIVE
  • INACTIVE
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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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:

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.
ErrorFor 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:
  • "ACTIVE"
  • "INACTIVE"
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.
ErrorFor 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:
  • deviceNames: A list of the devices that can receive notifications (based on the subscriptions) using the subscription form.
  • propertyDefinitions: A list of properties available to users when creating subscriptions based on the subscription form.
  • roles: The roles allowed to create subscriptions based on the subscription form.
sortBy string
Determines the criteria by which subscription forms are sorted:
  • "NAME": sorts subscription forms by their name.
  • "DESCRIPTION": sorts subscription forms by their description.
If not specified, subscription forms are sorted by their name. Use 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:
  • "ASCENDING"
  • "DESCENDING"

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.
ErrorFor 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:
  • deviceNames: A list of the devices that can receive notifications (based on the subscriptions) using the subscription form.
  • propertyDefinitions: A list of properties available to users when creating subscriptions based on the subscription form.
  • roles: The roles allowed to create subscriptions based on the subscription form.
sortBy string
Determines the criteria by which subscription forms are sorted:
  • "NAME": sorts subscription forms by their name.
  • "DESCRIPTION": sorts subscription forms by their description.
If not specified, subscription forms are sorted by their name. Use 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:
  • "ASCENDING"
  • "DESCENDING"

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.
ErrorFor 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}")

RESPONSE

{
  "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:
  • ALL_FORMS
  • FORM
If you set this to FORM, you must also include the 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, groups, and dynamic teams 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:
  • Severity
  • 8e84893b-e67c-41b6-b9c4-c2a421af5efe
You can only include properties defined in the communication plan; to find plan properties, use GET /property definitions.
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:
  • Incident Manager
  • Group Supervisor
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.
ErrorFor 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.
ErrorFor 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.
  • ALL_FORMS: subscriptions can be based on any event in the communication plan.
  • FORM: Subscriptions must be based on a specific form 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, groups, and dynamic teams 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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, dynamic teams, or devices.

RESPONSES

Success Response code 200 OK and a Pagination of Recipient objects in the response body.
ErrorFor 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:
  • subscribe: Whether users can subscribe and unsubscribe themselves to the subscription. If the subscribeOthers parameter is true, this parameter cannot be false.
  • subscribeOthers: Whether users can subscribe (and unsubscribe) others.
  • viewSubscription: Whether users can view subscription details. If the editSubscription parameter is set to true, this parameter cannot be set to false.
  • editSubscription: Whether users can edit the subscription.

RESPONSES

Success Response code 200 OK and a Pagination of Subscription permissions objects in the response body.
ErrorFor 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.
ErrorFor 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.
ErrorFor 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:
  • CONTAINS
  • ENDS_WITH
  • STARTS_WITH
  • MATCHES
  • IS_ONE_TYPE_OF
  • IS_TRUE
  • IS_FALSE
  • IS_TRUE_OR_FALSE

The following operators accept multiple values:
  • IS_ONE_OF
  • IS_ONE_OR_MORE_OF

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:
  • CONTAINS
  • ENDS_WITH
  • STARTS_WITH
  • MATCHES
  • IS_ONE_TYPE_OF
  • IS_TRUE
  • IS_FALSE
  • IS_TRUE_OR_FALSE

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:
  • IS_ONE_OF
  • IS_ONE_OR_MORE_OF

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:
  • subscribe: Whether users can subscribe and unsubscribe themselves to the subscription. If the subscribeOthers parameter is true, this parameter cannot be false.
  • subscribeOthers: Whether users can subscribe (and unsubscribe) others.
  • viewSubscription: Whether users can view subscription details. If the editSubscription parameter is set to true, this parameter cannot be set to false.
  • editSubscription: Whether users can edit the subscription.

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:
  • VACANCY: Returns only absences that don't have a replacement specified.
  • REPLACEMENT: Returns only absences with a replacement specified.
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.
ErrorFor 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 an id, so xMatters generates an id for the temporary absence and returns it in the id field 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.
  • VACANCY: No replacement is set for the absence.
  • REPLACEMENT: A replacement is set for the absence. If you set absenceType to REPLACEMENT, make sure you include the replacement parameter in the request body.
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.
ErrorFor 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.
ErrorFor 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:
  • VACANCY: No replacement is set for the absent user.
  • REPLACEMENT: A replacement is specified.
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.
ErrorFor 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.
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes.