NAV

User Name

Host Name

cURL Python Integration Builder

xMatters REST API

The xMatters REST API allows you to interact with xMatters using RESTful requests over the HTTP protocol.

The xMatters REST API is currently a work in progress. As new methods are added to it, they will 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.

Roles and permissions

The xMatters REST API controls access to features using the same roles and permissions as the xMatters web user interface. If the authenticating user has permission to perform an action the web user interface they can use the corresponding endpoints 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 they have permission to access an endpoint, it returns the data that they have permission view, for example, the GET /people endpoint returns only those users that the authenticating user has permission to view (not necessarily all users in the system).

For more information about the standard roles available with xMatters, see the Roles topic in the online help.

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

Regardless of which authentication method you use, ensure that you use HTTPS when making RESTful requests so that sensitive information such as passwords and tokens are secured during transmission.

HTTP Basic authentication

curl --user username "https://acmeco.xmatters.com/api/xm/1/myendpoint" 
import requests
from requests.auth import HTTPBasicAuth
auth = HTTPBasicAuth('username', 'password')

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

/**
 * Authentication in the xMatters Integration Builder is done through the 'xMatters' endpoint. 
 * This endpoint contains the host name of the system. Configure it with the user ID and 
 * password of the account that you want to use to access the xMatters REST API.
 *
 * You can then authenticate your requests by passing the 'xMatters' endpoint to the http.request method.
 */

"endpoint": "xMatters",

xMatters uses HTTP basic authentication to authenticate endpoints in the REST API. This allows you to authenticate requests with the same web login ID and password that you use to log on natively to the xMatters web user interface.

To authenticate with HTTP basic authentication, include an Authorization header with each request. This header contains an encoded version of your user ID 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.

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 encryption of your username and password in the format username:password to the end of the string.

EXAMPLE AUTHENTICATION HEADER:
Authorization: Basic YWRtaW46aWxvdmVjYXRz

Base URL

https://acmeco.xmatters.com/api/xm/1/

The base URL identifies your xMatters company and the version of the API you are using. It forms the base of each request to the xMatters REST API.

FORMAT

https://<company>.<deployment>.xmatters.com/api/xm/<version>/

/**
 * In the Integration Builder, the host name is stored in the 'xmatters' endpoint.
 * The rest of the base URL is passed to the request as part of the path attribute.
 */

  "endpoint": "xMatters",
  "path": "/api/xm/1/",

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. (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 format.

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

Encoding URI Parameters

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

URI Encoding in the Integration Builder

var groupName = IT%20%2F%20Ops;   //group is named ‘IT / Ops'
var request = http.request({
    'endpoint': 'xMatters',
    'path': '/api/xm/1/groups/' + groupName,
    'autoEncodeURI' : false,
    'method': 'GET'
});
var request = getGroupsRequest.write();

When you use the Integration Builder to access an endpoint, it automatically encodes some characters in the URI so that you do not have to manually encode characters such as spaces. However, you may need to turn off automatic URI encoding if the URI contains control characters such as / and ? or if you want the + character to be interpreted as the plus symbol instead of a space.

To turn off URI encoding in the integration builder, add 'autoEncodeURI' : false to the request parameters.
You are then responsible for manually encoding any special characters in the URI.

Click the Integration Builder 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.

It is recommended to use a JSON parser to process responses. This allows you to easily access the properties of the response and enables your scripts to process any new fields that may be added to the response in the future. (The addition of a new field to the response is not considered a breaking change. For more information on what is considered to be a breaking change, see Versions.)

HTTP response codes

Responses use standard HTTP response codes to describe whether the operation was completed successfully. The following table describes common response codes returned by this API

200 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 xMattersReturned Result
“Corporate Executives”\“Corporate Executives\”
Sales \ MarketingSales \\ Marketing

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 object.
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. This link is not included with dynamic team recipients because they cannot yet be directly manipulated with this API.

Dynamic team object

{
  "targetName": "DynamicTeam",
  "useEmergencyDevice": false,
  "externallyOwned": false,
  "recipientType": "DYNAMIC_TEAM",
  "id": "88ba7243-a4bc-477e-9b76-c49200a54b35",
  "responseCount" : 2,
  "responseCountThreshold" : 1
 }

A dynamic team is a set of users that are automatically generated based on a common attribute such as their skills, location, or other attributes.

Dynamic teams cannot be accessed and manipulated directly with this API. However, when a dynamic team is a member of a group it is included in the returned list of group members.

A dynamic team is based on the Recipient object but does not include the status field (because dynamic teams are always active) and does not include the links field (because dynamic teams cannot be accessed with this API).

   
id string
A unique identifier that represents the dynamic team.
targetName string
The name of the dynamic team.
recipientType string
For dynamic teams, this value is “DYNAMIC_TEAM”.
responseCount integer
When an event is configured to count responses for this dynamic team, this field indicates the number of dynamic team members that have responded positively to the event. If this number is greater than the responseCountThreshold then the response or “fill” counts for this team have been met.
responseCountThreshold integer
When an event is configured to count responses for this dynamic team, this field indicates the number of dynamic team members required to respond to the event. Once this threshold is met, additional dynamic team members are no longer notified.
externallyOwned Boolean
See externallyOwned.
useEmergencyDevice Boolean
True if the dynamic team is configured to contact failsafe devices when no other devices are configured to receive notifications.
{
  "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.
{
  "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
optional The type of the group member. Providing this optional field allows xMatters to process your request more efficiently and improves performance. Use one of the following values:
  • “PERSON”
  • “GROUP”
  • “DEVICE”
responseCount| integer optional | 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.

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_ANNOTATEDAnnotationA comment (annotation) was entered directly on the tracking report. Such comments are not associated with a response.
RESPONSE_RECEIVEDResponseA user has responded to a notification. Use this to see how a user responded and any comments (annotations) they made when responding.

Get event comments

Get event comments

REQUEST The following requests finds the audit records for all comments made on event 1562001, including those made by responding to a notification and those added directly to the tracking report.

curl --user username "https://acmeco.xmatters.com/api/xm/1/audits?eventId=1562001&auditType=EVENT_ANNOTATED,RESPONSE_RECEIVED" 
/**
 * This script is configured to work within the xMatters Integration Builder.
 * Configure the "xMatters" endpoint to use a valid username and password.
 */
var request = http.request({ 
     "endpoint": "xMatters",
     "path": "/api/xm/1/audits?eventId=1562001&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 + " comments");
   for (var i in json.data)
   {
      if (json.data[i].type == "EVENT_ANNOTATED")
        console.log ("Comment added to tracking report. \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 ("Comment made responding to notification. \tUser: " + json.data[i].response.notification.recipient.targetName + "\tComment: " + json.data[i].response.comment);
   }
}


# 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=1562001&auditType=EVENT_ANNOTATED,RESPONSE_RECEIVED'

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 to tracking report. \t\t User: ' + d['annotation']['author']['targetName'] + '\tComment: '+ d['annotation']['comment'] 
        elif(d['type'] == 'RESPONSE_RECEIVED'):
            print 'Comment made responding to notification. \t User: ' + d['response']['notification']['recipient']['targetName'] + '\tComment: '+ d['response']['comment'] 

RESPONSE The response contains a paginated list of EVENT_ANNOTATED and RESPONSE_RECEIVED audit records.


{
  "count": 2,
  "total": 2,
  "data":
  [
    {
      "orderId": "384915",
      "type": "EVENT_ANNOTATED",
      "at": "2017-03-27T18:45:21.718Z",
      "annotation":
      {
        "event":
        {
          "id": "a7ab8012-0583-4e5b-a5dd-36f67ec016f3",
          "eventId": "1562001",
          "links":
          {
            "self": "/api/xm/1/events/a7ab8012-0583-4e5b-a5dd-36f67ec016f3"
          }
        },
        "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."
      }
    },
    {
      "orderId": "384927",
      "type": "RESPONSE_RECEIVED",
      "at": "2017-03-27T18:48:11.655Z",
      "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
       },
       "received": "2017-03-27T18:45:47.111Z",
       "response": "Accept"
     }
   }
  ],
  "links":
  {
    "self": "/api/xm/1/audits?eventId=a7ab8012-0583-4e5b-a5dd-36f67ec016f3&auditType=event.annotated%2Cresponse.received&limit=100"
  }
}

Event comments can be added directly to the tracking report or they can be made when a user responds to a notification. To retrieve all event comments, set the auditType query parameter to EVENT_ANNOTATED and RESPONSE_RECEIVED.

DEFINITION

GET /audits?eventId={eventId}&auditType=EVENT_ANNOTATED,RESPONSE_RECEIVED

QUERY PARAMETERS

   
eventId string
The event ID or unique identifier of the event that you want to retrieve comments for.
auditType string
A comma-separated list of the type of audit events to retrieve. To retrieve event comments, use the following audit types:
  • EVENT_ANNOTATED: contains comments added directly to the tracking report.
  • RESPONSE_RECEIVED: contains comments made when responding to a notification.

RESPONSES

Records returned in response to the RESPONSE_RECEIVED query parameter contain the comments that were made when responding to a notification. Records returned in response to the EVENT_ANNOTATED query parameter contain the comments that were added directly to the event tracking report.

Success Response code 200 OK and a Pagination of Audit objects of type Response and Annotation.
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes.

Get responses

Get responses

REQUEST

curl --user username "https://acmeco.xmatters.com/api/xm/1/audits?eventId=1562001&auditType=RESPONSE_RECEIVED" 
/**
 * This script is configured to work within the xMatters Integration Builder.
 * Configure the "xMatters" endpoint to use a valid username and password.
 */
var request = http.request({ 
     "endpoint": "xMatters",
     "path": "/api/xm/1/audits?eventId=7855105&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=865032&auditType=RESPONSE_RECEIVED'

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


{
  "count": 2,
  "total": 2,
  "data":
  [
    {
      "orderId": "453532",
      "type": "RESPONSE_RECEIVED",
      "at": "2017-04-11T20:47:11.773Z",
         "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,
         "redirectUrl": "https://jira.example.com/view/INCD-4822"
       },
       "received": "2017-03-27T18:45:47.111Z",
       "response": "Accept"
     },
     {
       "id": "bb72f97c-ae19-11e7-aab9-03604daf2a86",
       "orderId": "456105",
       "type": "RESPONSE_RECEIVED",
       "at": "2017-10-11T00:18:40.006Z",
       "response":
       {
         "notification":
         {
           "id": "f2f4177e-8406-4740-8a05-49a6e14fa4e9",
           "category": "DEVICE",
           "recipient":
           {
             "id": "8a752214-cb5c-4050-b033-113973c929e8",
             "targetName": "poravets|Work Email",
             "recipientType": "DEVICE",
             "deviceType": "EMAIL",
             "name": "Work Email",
             "links":
             {
               "self": "/api/xm/1/devices/8a752214-cb5c-4050-b033-113973c929e8"
             }
           },
           "deliveryStatus": "RESPONDED",
           "created": "2017-10-11T00:18:31.224Z",
           "event":
           {
             "id": "d10f8a30-9830-43d6-88a2-16e41007c857",
             "eventId": "5914013",
             "links":
             {
               "self": "/api/xm/1/events/d10f8a30-9830-43d6-88a2-16e41007c857"
             }
           }
         }, 
         "option":
         {
           "id": "eabf5117-163a-4f84-bea8-f8a672df08de",
           "number": 2,
           "text": "Reject",
           "description": "I cannot assist.",
           "prompt": "I cannot assist",
           "action": "RECORD_RESPONSE",
           "contribution": "NONE",
           "joinConference": false,
           "redirectUrl": ""
         },
        "received": "2017-10-11T00:18:31.224Z",
        "response": "Reject"
      }
    },
  ],
  "links":
  {
    "self": "/api/xm/1/audits?eventId=e3f5b01f-40f3-4273-94bb-fce10d0f2d10&auditType=RESPONSE_RECEIVED&limit=100"
  }
}

Use the /audits endpoint to view how recipients have responded to notifications, including any comments made when responding.

(To view all comments for an event, including those that were made directly to the tracking report, see Get event comments.)

When a response is made from a device, the "category" field is "DEVICE" and the "recipient" field contains information about the device that the user responded from, 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.

DEFINITION

GET /audits?eventId={eventId}&auditType=RESPONSE_RECEIVED

QUERY PARAMETERS

   
eventId string
The event ID or unique identifier of the event that you want to retrieve responses for.
auditType string
A comma-separated list of the type of audit events to retrieve. To retrieve responses, use the following audit type:
  • RESPONSE_RECEIVED

RESPONSES

The RESPONSE_RECEIVED audit records contain the response that was made when a user responded to a notification.

Success Response code 200 OK and a Pagination of Audit objects of type Response.
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",   
 ...
}

Audit objects contain basic information about an audit record, and additional information specific to the type of audit record that is being returned.

See the Audit types table for a list of supported audit types.

   
at string
The time the entry occurred.
type string
The type of audit. For a list of audit types, see Audit types.
orderId string
deprecated This field has been deprecated and will be removed from the API in a future release. An identifier for this audit entry.

Annotation object

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

Annotation objects are Audit objects that represent a comment that was added directly to the tracking report. 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. These annotations are not associated with a response.

For information about comments that were made when responding to a notification, see Response object.

Annotation objects contain the fields in Audit objects as well as the fields in the following table.

   
event EventPointer 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 tracking report.

Response object

Response object


"response":
{
  "comment": "This comment was made by mmcbride when she responded on her iPhone.",
  "notification":
  {
    "id": "1d204d66-32d7-41af-aeb1-fb18cbb43b66",
    "category": "PERSON",
    "recipient":
    {
      "id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
      "targetName": "mmcbride",
      "firstName": "Mary",
      "lastName": "McBride",
      "links":
      {
        "self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
      },
      "recipientType": "PERSON"
    },
    "deliveryStatus": "RESPONDED",
    "created": "2017-03-27T18:45:47.111Z",
    "deliveryAttempted": "2017-03-27T18:48:19.216Z",
    "event":
    {
      "id": "a7ab8012-0583-4e5b-a5dd-36f67ec016f3",
      "eventId": "1562001",
      "links":
      {
        "self": "/api/xm/1/events/a7ab8012-0583-4e5b-a5dd-36f67ec016f3"
      }
    }
  },
  "option":
  {
    "number": 1,
    "text": "Accept",
    "description": "I can take care of this.",
    "prompt": "Assign this task to me.",
    "action": "RECORD_RESPONSE",
    "contribution": "NONE",
    "joinConference": false
  },
  "received": "2017-03-27T18:45:47.111Z",
  "response": "Accept"
}

Event response objects contain information about how a user responded to an event, including any comments they made when responding. To retrieve responses, call the /audits endpoint with the ?auditType=RESPONSE_RECEIVED query parameter.

For information about comments that were added directly to the tracking report, see Annotation object.

Response objects contain the fields in Audit objects as well as the fields in the following table.

   
comment string
optional If a comment was made when responding, contains the comment text.
notification Notification object
The notification that the user responded to.
option ResponseOption 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.

   
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 EventPointer object
A link to the event that generated the notification.

EventPointer object

EventPointer object

{
  "id": "a7ab8012-0583-4e5b-a5dd-36f67ec016f3",
  "eventId": "1562001",
  "links":
  {
    "self": "/api/xm/1/events/a7ab8012-0583-4e5b-a5dd-36f67ec016f3"
  }
}

An EventPointer 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.

NotificationDelivered

NotificationDelivered object

{
  "id": "a91225ce-a3e1-11e7-a21c-c70b12c280fb",
  "orderId": "449118",
  "type": "NOTIFICATION_DELIVERED",
  "at": "2017-09-28T00:12:04.517Z",
  "notification":
  {
    "id": "475059d8-404e-493c-8972-933edd4a6ad0",
    "category": "LIVE",
    "recipient":
    {
      "id": "6eb07b40-bdb1-4679-94fc-354c4c163897",
      "targetName": "poravets|Work Email",
      "recipientType": "DEVICE",
      "deviceType": "EMAIL",
      "name": "Work Email",
      "owner":
      {
        "id": "ceb08e86-2674-4812-9145-d157b0e24c17",
        "targetName": "poravets",
        "firstName": "Pauline",
        "lastName": "Oravets",
        "recipientType": "PERSON",
        "links":
        {
          "self": "/api/xm/1/people/ceb08e86-2674-4812-9145-d157b0e24c17"
        }
      },
      "links":
      {
        "self": "/api/xm/1/devices/6eb07b40-bdb1-4679-94fc-354c4c163897"
      }
    },
    "deliveryStatus": "DELIVERED",
    "created": "2017-09-28T00:06:33.002Z",
    "event":
    {
      "id": "33bb4c2c-dc83-4d67-8d75-4442972b2aa5",
      "eventId": "5864002",
      "links":
      {
        "self": "/api/xm/1/events/33bb4c2c-dc83-4d67-8d75-4442972b2aa5"
      }
    }
  }
}

A notification delivery object is returned when a notificaiton is sucessfully delivered.

   
id string

NotificationFailed

NotificationFailed object

{
  "id": "a0ba584c-a3e1-11e7-ba8e-2344639bb1eb",
  "orderId": "449116",
  "type": "NOTIFICATION_FAILED",
  "at": "2017-09-28T00:11:51.332Z",
  "notification":
  {
    "id": "475059d8-404e-493c-8972-933edd4a6ad0",
    "category": "LIVE",
    "recipient":
    {
      "id": "6eb07b40-bdb1-4679-94fc-354c4c163897",
      "targetName": "poravets|Home Email",
      "recipientType": "DEVICE",
      "deviceType": "EMAIL",
      "name": "Home Email",
      "owner":
      {
        "id": "ceb08e86-2674-4812-9145-d157b0e24c17",
        "targetName": "poravets",
        "firstName": "Pauline",
        "lastName": "Oravets",
        "recipientType": "PERSON",
        "links":
        {
          "self": "/api/xm/1/people/ceb08e86-2674-4812-9145-d157b0e24c17"
        }
      },
      "links":
      {
        "self": "/api/xm/1/devices/6eb07b40-bdb1-4679-94fc-354c4c163897"
      }
    },
    "deliveryStatus": "DELIVERED",
    "created": "2017-09-28T00:06:33.002Z",
    "event":
    {
      "id": "33bb4c2c-dc83-4d67-8d75-4442972b2aa5",
      "eventId": "5864002",
      "links":
      {
        "self": "/api/xm/1/events/33bb4c2c-dc83-4d67-8d75-4442972b2aa5"
      }
    }
  }
}

DEVICES

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

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

endpoint_URL = '/devices/254c95ee-4abe-47ea-ae7c-ae84fb4bee4f?embed=timeframes'
url = base_URL + endpoint_URL 

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    print 'Retrieved device ' + response.json()['id'] + ' owned by ' + response.json()['targetName']
elif (response.status_code == 404):
    print 'The device could not be found.' 

RESPONSE

{
  "id":"254c95ee-4abe-47ea-ae7c-ae84fb4bee4f",
  "name":"Work Email",
  "emailAddress":"m.mcbride@xmatters.com",
  "targetName":"mmcbride",
  "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.

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

Create a device

Create a device

REQUEST (create a device)
The following example shows how to create a mobile phone device for Mary McBride that is active on weekdays from 8 AM to 10 PM and weekends from 9 AM to 5 PM. This device is only contacted for medium and high-priority events. After this device is contacted there is a five-minute delay before xMatters contacts the next device.

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


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

response = request.write(data);

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

import requests
from requests.auth import HTTPBasicAuth
import json

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

headers = {'Content-Type': 'application/json'}

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

data = { 
     'recipientType' : 'DEVICE',
     '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']
         }]
    }

data_string = json.dumps(data)

response = requests.post(url, headers=headers, data=data_string, auth=auth)

if (response.status_code == 201):
   rjson = response.json();
   print 'Created device ' + rjson.get('targetName') 

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
from requests.auth import HTTPBasicAuth
import json

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

headers = {'Content-Type': 'application/json'}

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

data = { 
     'id' : '42469eb6-c58c-4c0e-8c4b1838bdf853d2',
     'recipientType' : 'DEVICE',
     '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']
         }]
    }

data_string = json.dumps(data)

response = requests.post(url, headers=headers, data=data_string, auth=auth)

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",
  "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.

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

DEFINITION

POST /devices

BODY PARAMETERS

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

All devices

   
defaultDevice Boolean
optional True if the device is a failsafe device.
delay integer
optional The number of minutes to wait for a response before contacting the next device.
deviceType string
The type of device to be created. Valid values include the following:
  • “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
optional If provided, xMatters attempts to use this value as a device’s unique identifier. This value must be a valid UUID and cannot be used to identify any other objects within xMatters. If this value is not provided, xMatters generates a UUID and uses it as the device’s unique identifier. Set a value in this optional field when you want a device’s identifier to match a UUID stored in an external system.
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
optional The minimum priority of an event for it to be delivered to this device. Valid values include the following:
  • “LOW”
  • “MEDIUM”
  • “HIGH”
provider string
optional The name of the provider to use when sending notifications to this device. You do not need to include this value if there is only one provider configured for this type of device.
recipientType string
optional For devices, the recipient type is “DEVICE”. Providing this optional field allows xMatters to process your request more efficiently and improves performance.
sequence integer
optional The order in which the device will be contacted, where 1 represents the first device contacted. If the provided sequence number is higher than the number of existing devices, the device is added to the end of the device order.
status string
optional The status of the devices. Valid values include:
  • ACTIVE
  • INACTIVE
testStatus string
optional 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]
optional A list of timeframes when xMatters may contact this device. (If the device is a failsafe device, it may be contacted outside these times in certain situations.)

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, APPLE_PUSH, BLACKBERRY_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);
}
import requests
from requests.auth import HTTPBasicAuth
import json

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

headers = {'Content-Type': 'application/json'}
auth = HTTPBasicAuth('username', 'password')

data = {
        'id': '42469eb6-c58c-4c0e-8c4b-1838bdf853d2',
        'deviceType':'VOICE', 
        'phoneNumber' : '+13105556672'
        }
data_string = json.dumps(data)

response = requests.post(url, headers=headers, data=data_string, auth=auth)
if (response.status_code == 200):
    print 'Modified device ' + response.json()['targetName']
else:
   print 'Device could not be found'


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, call POST /devices 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 to POST /devices does not include the id field, it is treated as a request to create a device (see Create a device).

Note: You can use this API to modify properties of mobile app devices but you cannot use this API to create mobile app devices.

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”
  • “BLACKBERRY_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.

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)

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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/devices/5cee7597-8cee-4f89-a969-850c8cae1fe7'
url = base_URL + endpoint_URL

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

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

if (response.status_code == 200):
    print 'Deleted device ' +  response.json().get('id') + ' belonging to ' + response.json().get('targetName')
elif (response.status_code == 204):
    print 'The device could not be found.'       

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 of the device. You can obtain this identifier from the response of Create a device or Get a person’s devices.

DEFINITION

DELETE /devices/{deviceID}

URL PARAMETERS

   
{deviceID} string
The unique identifier or target name of the device to delete. 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

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”
  • “BLACKBERRY_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]
optional The timeframes the device is active and able to receive notifications. This field is included when the query parameter ?embed=timeframes is included in supported requests.

Email device object

Email device object

"deviceType": "EMAIL",
"emailAddress": "akaur@example.com",

Email device objects include the fields of Recipient object and Device object, as well as the following fields:

   
deviceType string
For email devices, the device type is “EMAIL”.
emailAddress string
The email address associated with the device. Your system administrator may restrict the domains that are allowed to be associated with an email device.

Voice device object

Voice device object

"deviceType": "VOICE",
"phoneNumber": "+16045551234;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 numbers associated with this device. The phone number uses E.164 international format including country code and extension.
Example: +16045551234;ext=88

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

BlackBerry push device object

BlackBerry push device object

"deviceType": "BLACKBERRY_PUSH",
"accountId": "",
"registrationId": "",

BlackBerry push devices are BlackBerry 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.

BlackBerry push device objects include the fields of Recipient object and Device object, as well as the following fields:

   
deviceType string
For BlackBerry push devices, the device type is “BLACKBERRY_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”

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":[
  {
    "deviceType":"EMAIL",
    "name":"Home Email",
    "description":"Home Email Address"
  },
  {
    "deviceType":"EMAIL",
    "name":"Work Email",
    "description":"Work Email Address",
    "domains":
    [
       "xmatters.com",
       "example.com"
    ]
  },
  {
    "deviceType":"FAX",
    "name":"Fax",
    "description":"Fax"
  },
  {
    "deviceType":"NUMERIC_PAGER",
    "name":"Numeric Pager",
    "description":"Numeric Pager"
  },
  {
    "deviceType":"TEXT_PAGER",
    "name":"Pager",
    "description":"Text Pager"
  },
  {
    "deviceType":"TEXT_PHONE",
    "name":"SMS Phone",
    "description":"Phone with SMS"
  },
  {
    "deviceType":"VOICE",
    "name":"Home Phone",
    "description":"Phone Number at Home"
  },
  {
    "deviceType":"VOICE",
    "name":"Mobile Phone",
    "description":"Cell Phone"
  },
  {
    "deviceType":"VOICE",
    "name":"Work Phone",
    "description":"Phone Number at Work"
  }
],
"links":{"self":"/api/xm/1/device-names?offset=0&limit=100"}}

Returns a paginated list of the DeviceName objects that represent the devices users can add to their profile.

You can request devices of a specific type by including the ?deviceType query parameter, for example, use /device-names?deviceType=EMAIL to retrieve a list of email devices.

DEFINITION

GET /device-names

QUERY PARAMETERS

   
deviceType string
Returns devices of only the specified type. Use one of the following values:
  • “ANDROID_PUSH”
  • “APPLE_PUSH”
  • “BLACKBERRY_PUSH”
  • “EMAIL”
  • “FAX”
  • “GENERIC”
  • “TEXT_PAGER”
  • “TEXT_PHONE”
  • “VOICE”
  • “VOICE_IVR”
For more information about supported device types, see Device Types.
offset integer
The number of items to skip before returning results. Use with the limit parameter to return a single page of results. For more information about working with paginated result sets, see Pagination.
limit integer
The number of items to return. Use with the offset parameter to return a single page of results. For more information about working with paginated result sets, see Pagination.

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.

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 a device.

   
deviceType string
The type of the device. 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]
optional Used only with email devices. Lists the domains included in the email domain whitelist for this type of device.

DEVICE TYPES

Returns a list of device types that are configured for the system.

Get device types

GET device types

REQUEST (get device types)

curl --user username "https://acmeco.xmatters.com/api/xm/1/device-types" 
var request = http.request({ 
     "endpoint": "xMatters",
     "path": "/api/xm/1/device-types",
     "method": "GET"
 });

var response = request.write();

if (response.statusCode == 200 ) {
   json = JSON.parse(response.body);
   for (var i in json.data ) {
     console.log(json.data[i]);
  }
}
import requests
from requests.auth import HTTPBasicAuth

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/device-types'
url = base_URL + endpoint_URL

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    json = response.json();
    for d in json['data']:
        print d

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”
  • “BLACKBERRY_PUSH”
  • “EMAIL”
  • “FAX”
  • “GENERIC”
  • “TEXT_PAGER”
  • “TEXT_PHONE”
  • “VOICE”
  • “VOICE_IVR”

EVENTS

The linked methods can start, stop, resume, and terminate events.

You can also retrieve a list of events and notifications in the system.

Get events

Get events

REQUEST Get all events with 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"
/**
 * 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",
     "method": "GET"
 });

var response = request.write();

if (response.statusCode == 200 ) {
   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'

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']) + ' events.')
    for d in json['data']:
        print d['id']

RESPONSE


{
    "count": 1,
    "total": 1,
    "data":
      [
        {
            "id": "116f41dc-395c-4bba-a806-df1eda88f4aa",
            "submitter":
            {
                "id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
                "targetName": "xmapi-user",
                "links":
                {
                    "self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
                }
            },
            "priority": "MEDIUM",
            "incident": "INCIDENT_ID-981006",
            "overrideDeviceRestrictions": false,
            "otherResponseCountThreshold" : 2,
            "otherResponseCount" : 1,
            "escalationOverride": false,
            "bypassPhoneIntro": false,
            "requirePhonePassword": false,
            "conference": 
            {
              "bridgeId": "84564207",
              "type": "BRIDGE",
              "links": 
              {
                "self": "/api/xm/1/conferences/84564207"
              }
            },
            "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"
            }
        }
    ],
    "links":
    {
        "self": "/api/xm/1/events"
    }
}

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 the events the authenticating user has permission to view. If search parameters are provided, this endpoint returns only the matching events.

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.

Searches match whole or partial search terms. Search property names and property values are not case-sensitive.

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 initated, the user who sumbitted the event, or the status of the event. Use the sortOrder query parameter to specify whether to return the results in ascending or descending order.

DEFINITION

GET /events

GET /events?propertyName=customerAffected&propertyValue=false

GET /events?status=ACTIVE,SUSPENDED

GET /events?from=2017-05-01T14:00:00.000Z&to=2017-05-01T19:00:00.000Z

GET /events?embed=properties,annotations

GET /events?sortBy=START_TIME&sortOrder=ASCENDING

GET /events?requestId=5588db90-6b87-4662-9a2f-107d3bb233bf

QUERY PARAMETERS

   
{annotations} string
Include comments that were made when responding to the notification.
{propertyName} string
The name of a form property. This value is not case-sensitive.
{propertyValue} string
The value of a form property. This value is not case-sensitive.
{offset} number
The number of items to skip before returning results. Use with the limit parameter to return a single page of results. For more information about working with paginated result sets, see Pagination.
{limit} number
The number of items to return. Use with the offset parameter to return a single page of results. For more information about working with paginated result sets, see Pagination.
{status} string
A list of the types of events that you want to return as determined by their status. Valid values include the following:
  • “ACTIVE”
  • “SUSPENDED”
  • “TERMINATED”
{embed} string
A comma-separated list of the properties to embed in the response.
  • 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.
{from} string
A date in UTC format that represents the start of the time range you want to search. Use with the to query parameter.
Example: 2017-05-01T14:00:00.000Z
{to} string
A date in UTC format that represents the end of the time range you want to search. Use this with the from query parameter.
Example: 2017-05-01T19:00:00.000Z
{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 the following:
  • “EVENT_ID”
  • “START_TIME”
  • “STATUS”
  • “SUBMITTER”
{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 the following:
  • “ASCENDING”
  • “DESCENDING”
{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.

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

REQUEST (get an event by event ID)

curl --user username "https://acmeco.xmatters.com/api/xm/1/events/408005?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/408005?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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/events'

url = base_URL + endpoint_URL + '/408005?embed=properties,recipients,responseOptions,annotations,messages'

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: ' + '408005'

RESPONSE


{
  "id":"ced9fac9-1065-4659-82ab-1c9664a777b2",
  "eventId":"408005",
  "created":"2016-10-31T22:37:35.301+0000",
  "terminated":"2016-10-31T22:38:40.063+0000",
  "status":"TERMINATED",
  "priority":"MEDIUM",
  "incident":"INCIDENT_ID-408005",
  "expirationInMinutes":180,
  "overrideDeviceRestrictions": false,
  "bypassPhoneIntro": false,
  "requirePhonePassword": false,
  "voicemailOptions":
  {
    "retry": 0,
    "every": 60,
    "leave": "callbackonly"
  },
  "floodControl" : false,
  "otherResponseCountThreshold" : 2,
  "otherResponseCount" : 1,
  "submitter":
  {
    "id":"661f3f18-75ab-44fd-a22a-4bb0fe15917e",
    "targetName":"mmcbride",
    "links":
    {
      "self":"/api/xm/1/people/661f3f18-75ab-44fd-a22a-4bb0fe15917e"
      }
  },
  "recipients":
  {
    "count":2,
    "total":2,
    "data":
    [{
      "id":"b1697b84-c0cf-412c-b956-af810cd86bae",
      "targetName":"poravets",
      "recipientType":"PERSON",
      "externallyOwned":false,
      "links":
      {
        "self":"/api/xm/1/people/b1697b84-c0cf-412c-b956-af810cd86bae"
      },
      "firstName":"Pauline",
      "lastName":"Oravets",
      "language":"en_GB",
      "timezone":"US/Pacific",
      "webLogin":"poravets",
      "phoneLogin":"99211",
      "site":
      {
        "id":"8e451c6b-69e3-49d7-979c-e7a6e794f340",
        "links":
        {
          "self":"/api/xm/1/sites/8e451c6b-69e3-49d7-979c-e7a6e794f340"
        }
      },
      "status":"ACTIVE"
    },
    {
      "id": "1ea8906f-be05-410d-9077-fa7587d7b626",
      "targetName": "IT",
      "recipientType": "GROUP",
      "status": "ACTIVE",
      "externallyOwned": false,
      "allowDuplicates": true,
      "useDefaultDevices": true,
      "observedByAll": true,
      "description": "",
      "responseCount" : 2,
      "responseCountThreshold" : 1,
      "links": {
        "self": "/api/xm/1/groups/1ea8906f-be05-410d-9077-fa7587d7b626"
      },
      "targeted": true
    }],
    "links": 
    {
      "self": "/api/xm/1/events/ced9fac9-1065-4659-82ab-1c9664a777b2/recipients?targeted=true&offset=0&limit=100"
    }
  },
  "form":
  {
    "id":"ef62b6ac-ba7e-40e8-9253-a837efcd38ea",
    "name" : "Database Outage"
  },
  "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":
  {
    "bridgeId":"67955226",
    "type":"BRIDGE",
    "links":
    {
      "self": "/api/xm/1/conferences/67955226"
    }
  },
  "responseOptions":
  {
    "count":2,
    "total":2,
    "data":
    [{
      "number":1,"text":"Join",
      "description":"Join",
      "prompt":"I will join the conference.",
      "action":"RECORD_RESPONSE",
      "contribution":"NONE",
      "joinConference":true
     },
    {
      "number":2,
      "text":"Reject",
      "description":"Reject",
      "prompt":"I cannot assist.",
      "action":"STOP_NOTIFYING_USER",
      "contribution":"NONE",
      "joinConference":false
    }]
  },
  "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:

Identify an event by using its event ID or its unique identifier. The event ID can be located on the Events Report in the xMatters user interface. An event’s unique identifier cannot be located in the user interface but is returned in the response of some endpoints in this API.

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,responseOptions,annotations,messages

GET /events/{eventId}?embed=recipients&targeted=true

URL PARAMETERS

   
{eventID} string
The event number or the unique identifier of the event.
Examples:
  • “408005”
  • “24abd4c0-bff3-4381-9f84-678580b24428”

QUERY PARAMETERS

   
{embed} string
A comma-separated list of the properties to embed in the response.
  • annotations: The event comments from responses.
  • 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.
  • messages: The HTML message content for email notifications.
    The HTML is automatically escaped, and property values are populated except for person and sender placeholders.
{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.

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

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": "981002", 
    "status": "TERMINATED"
}' "https://acmeco.xmatters.com/api/xm/1/events" 
/**
 * This script is configured to work within the xMatters Integration Builder.
 * Configure the "xMatters" endpoint to use a valid username and password.
 */

var request = http.request({ 
     "endpoint": "xMatters",
     "path": "/api/xm/1/events/",
     "method": "POST",
     "headers" : {"Content-Type": "application/json"}
 });

var data = {};
data.id = '981002';
data.status = 'TERMINATED';

response = request.write(data);

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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/events'
url = base_URL + endpoint_URL 

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

headers = {'Content-Type': 'application/json'}

data = {'id':'981002', 
        '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 'Event id = ' + response.json()['id'] + ' changed to ' + response.json()['status']

RESPONSE

{
  "id": "9102f1c3-b67b-4970-880b-05b2fc566224",
  "form":
  {
    "id": "4eb794ca-01dd-4a23-994f-19cac8ba529f"
  },
  "submitter":
  {
    "id": "c21b7cc9-c52a-4878-8d26-82b26469fdc7",
    "targetName": "xmapi-user",
    "links":
    {
      "self": "/api/xm/1/people/c21b7cc9-c52a-4878-8d26-82b26469fdc7"
    }
  },
  "recipients":
  {
    "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",
          "links":
          {
            "self": "/api/xm/1/sites/8f2d98ed-eaa9-4b0b-b366-c1db06b27e1f"
          }
        },
        "properties":
        {
           "First AId": "CPR",
        },
        "targeted": true,
        "status": "ACTIVE"
      }
    ],
    "links":
    {
      "self": "/api/xm/1/events/9102f1c3-b67b-4970-880b-05b2fc566224/recipients?targeted=true&offset=0&limit=100"
    }
  },
  "priority": "MEDIUM",
  "incident": "INCIDENT_ID-981002",
  "expirationInMinutes": 180,
  "notificationAuditCount": 7,
  "overrideDeviceRestrictions": false,
  "escalationOverride": false,
  "bypassPhoneIntro": false,
  "requirePhonePassword": false,
  "responseOptions":
  {
    "count": 1,
    "total": 1,
    "data":
    [
      {
        "number": 1,
        "text": "Join",
        "description": "I will join the conference",
        "prompt": "I will join the conference",
        "action": "RECORD_RESPONSE",
        "contribution": "NONE",
        "joinConference": true
       }
     ]
   },
   "eventId": "981002",
   "created": "2017-03-01T21:11:49.742+0000",
   "status": "TERMINATED"
}

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

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 the request to the inbound 
 * integration URL.
 * 
 * To see how to customize an inbound integration that uses the "Transform Content to Create Event"
 * action, see the Integration Builder example.
 */

curl -H "Content-Type: application/json" -X POST -d '
"recipients" :
  [

    {"id":"mmcbride", "recipientType": "PERSON"},
    {"id":"bfdbcb31-d02e-4a4f-a91c-7d68fbe416df", "recipientType": "PERSON"},
    {"id":"mmcbride|Work Email", "recipientType": "DEVICE"},
    {"id":"4a0fdfb4-7c49-4581-9cd9-804f2956e19b", "recipientType": "DEVICE"},
    {"id":"Executives", "recipientType": "GROUP"},
    {"id":"f19d8b10-923a-4c23-8348-06ced678075e", "recipientType": "GROUP", "responseCountThreshold" : 3},
    {"id":"First Aid Attendants", "recipientType": "DYNAMIC_TEAM", "responseCountThreshold" : 1},
    {"id":"ed2606c5-ef2b-4ce8-9259-d5cdacd5bd90", "recipientType": "DYNAMIC_TEAM"} 
  ],
  "otherResponseCountThreshold" : 4,
  "priority" : "HIGH",
  "expirationInMinutes" : 60,
  "overrideDeviceRestrictions": true,
  "escalationOverride": true,
  "bypassPhoneIntro": true,
  "requirePhonePassword": true,
  "voicemailOptions":
  {
    "retry": 0,
    "every": 60,
    "leave": "callbackonly"
  },
  "conference":
  {
    "bridgeId": "Corporate WebEx",
    "type": "EXTERNAL"
  },
  "responseOptions" : 
  [
    {
      "id" : "fee39ecf-75a7-45eb-9e63-ffc441499c4f"
    },
    {
      "id" : "085d4bea-9dfb-4d2b-8136-22e19b1baaf6",
      "redirectUrl" : "https://jira.example.com/view/INCD-2933"
    },
    {
      "number": 3,
      "text": "Reject",
      "description": "I cannot help",
      "prompt": "Reject",
      "action": "COUNT_RESPONSE",
      "contribution": "NEGATIVE",
      "joinConference": 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"
      }
    ]
  },
  "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"}
  ]
' 
https://acmeco.xmatters.com/api/integration/1/functions/ba601cb1-3513-4320-b48a-05cb501bb5af/triggers?apiKey=ffcd4dec-8a49-4a67-9e59-ed9fabcb002d

/***
 * This example shows how to customize the built-in trigger object to 
 * customize form settings and then trigger an event from within an inbound
 * integration that uses the "Transform Content to create new xMatters Event" option
 */

//Recipients including some respones counts for groups
var recipients = [];
recipients.push({"id":"mmcbride", "recipientType": "PERSON"});  
recipients.push({"id":"bfdbcb31-d02e-4a4f-a91c-7d68fbe416df", "recipientType": "PERSON"}); 
recipients.push({"id":"mmcbride|Work Email", "recipientType": "DEVICE"}); 
recipients.push({"id":"4a0fdfb4-7c49-4581-9cd9-804f2956e19b", "recipientType": "DEVICE"}); 
recipients.push({"id":"Executives", "recipientType": "GROUP"}); 
recipients.push({"id":"f19d8b10-923a-4c23-8348-06ced678075e", "recipientType": "GROUP", "responseCountThreshold" : 3}); 
recipients.push({"id":"First Aid Attendants", "recipientType": "DYNAMIC_TEAM", "responseCountThreshold" : 1}); 
recipients.push({"id":"ed2606c5-ef2b-4ce8-9259-d5cdacd5bd90", "recipientType": "DYNAMIC_TEAM"}); 

trigger.recipients = recipients;

//Set response counts for others group
trigger.otherResponseCountThreshold = 4;


//Conference bridge (external)
var conference = {};
//Syntax for joining external conference bridge with static bridge number
conference.bridgeId =  "Webex";
conference.type = "EXTERNAL";

//Syntax for joining external conference bridge with dynamic bridge number
//conference.bridgeId =  "Webex";
//conference.type = "EXTERNAL";
//conference.bridgeNumber = "74747466";

//Syntax for joining in-progress xMatters-hosted bridge
//conference.bridgeId =  "3882920";
//conference.type = "BRIDGE";

//Syntax for joining new xMatters-hosted bridge
//conference.type = "BRIDGE";

trigger.conference = conference;

//Responses 
var responseOptions = [];

//select an existing response option    
responseOptions.push({"id" : "fee39ecf-75a7-45eb-9e63-ffc441499c4f"}); 

//modify an existing response option
responseOptions.push({"id" : "085d4bea-9dfb-4d2b-8136-22e19b1baaf6",
  "joinConference" : false,
  "redirectUrl" : "https://jira.example.com/view/INCD-2933"}); 

//create a new response option
responseOptions.push({"number": 3,
  "text": "Reject",
  "description": "I cannot help",
  "prompt": "Reject",
  "action": "COUNT_RESPONSE",
  "contribution": "NEGATIVE",
  "redirectUrl": "https://www.example.com",
  "joinConference": 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;

//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); 

import requests
from requests.auth import HTTPBasicAuth
import json


inbound_integration_url = 'https://acmeco.xmatters.com/api/integration/1/functions/4cd6ba69-4910-4a4c-ae4d-a175e4456cfd/triggers'

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

headers = {'Content-Type': 'application/json'}

data = {
    'recipients' : [
    {'id':'mmcbride', 'recipientType': 'PERSON'}, 
    {'id':'bfdbcb31-d02e-4a4f-a91c-7d68fbe416df', 'recipientType': 'PERSON'},
    {'id':'mmcbride|Work Email', 'recipientType': 'DEVICE'},
    {'id':'4a0fdfb4-7c49-4581-9cd9-804f2956e19b', 'recipientType': 'DEVICE'},
    {'id':'Executives', 'recipientType': 'GROUP'},
    {'id':'f19d8b10-923a-4c23-8348-06ced678075e', 'recipientType': 'GROUP', 'responseCountThreshold' : 3},
    {'id':'First Aid Attendants', 'recipientType': 'DYNAMIC_TEAM', 'responseCountThreshold' : 1},
    {'id':'ed2606c5-ef2b-4ce8-9259-d5cdacd5bd90', 'recipientType': 'DYNAMIC_TEAM'} 
    ],
    'otherResponseCountThreshold' : 4,
    'priority' : 'HIGH',
    'expirationInMinutes' : 60,
    'overrideDeviceRestrictions': True,
    'escalationOverride': True,
    'bypassPhoneIntro': True,
    'requirePhonePassword': True,
    'voicemailOptions':
    {
        'retry': 0,
        'every': 60,
        'leave': 'callbackonly'
    },
    'conference':
    {
        'bridgeId': 'Corporate WebEx',
        'type': 'EXTERNAL'
    },
    'responseOptions' : 
    [
      {
        'id' : 'fee39ecf-75a7-45eb-9e63-ffc441499c4f'
      },
      {
        'id' : '085d4bea-9dfb-4d2b-8136-22e19b1baaf6',
        'redirectUrl' : 'https://jira.example.com/view/INCD-2933'
      },
      {
        'number': 3,
        'text': 'Reject',
        'description': 'I cannot help',
        'prompt': 'Reject',
        'action': 'COUNT_RESPONSE',
        'contribution': 'NEGATIVE',
        'joinConference': 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'
       }
     ],
   },
   '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)

responseCode = response.status_code
if (responseCode == 202):
    print 'Event triggiered = ' + response.json()['requestId'] 
else :
    print 'error'     

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.

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 "taregetName" : "mmcbride" or the Integration Builder’s helper methods, for example, trigger.addRecipient ("mmcbride") to define the form recipients. Instead, you must use the recipient format described in this section, for example "id" : "mmcbride", "recipientType" :"PERSON"

DEFINITION

Trigger the event by sending a POST request to the inbound integration URL, which you can obtain from the inbound integration. Inbound integration URLs use the following patterns:

POST /api/integration/1/functions/{id}/triggers

POST /api/integration/1/functions/{id}/triggers?apiKey={apiKey}

BODY PARAMETERS

   
recipients array [RecipientTrigger object]
optional Specifies the people, devices, groups, and dynamic teams that are directly targeted when this form is triggered. If the form is configured to use response counts (fill counts), you can also specify the number of people in a group or dynamic team that are required to respond. If the form is configured to use subscriptions, additional recipients not included in this list may be notified if the notification matches their subscription preferences.
priority string
optional The priority of the event. Valid values include the following:
  • “LOW”
  • “MEDIUM”
  • “HIGH”
expirationInMinutes integer
optional The duration of the event in minutes. See note.
overrideDeviceRestrictions Boolean
optional When this value is set to true, xMatters ignores device timeframes and delays. This allows users to be notified on any device at any time, regardless of their preferences. See note.
escalationOverride Boolean
optional When this value is set to true, xMatters ignores shift escalation delays and immediately broadcasts the message to all recipients. See note.
bypassPhoneIntro Boolean
optional When this value is set to true, xMatters omits the standard voice greeting and plays the message immediately. See note.
requirePhonePassword Boolean
optional When this value is true, the recipient must enter their phone password before a voice notification is played. This option cannot be used with options to leave the message content as voicemail. See note.
voicemailOptions VoicemailOptions object
optional For voice notifications, this defines whether to try the call again or leave a message. See note.
properties PropertyValues object
optional Allows you to set the values of form properties.
conference ConferencePointer object
optional When a form contains a conference bridge, this allows you to select which conference bridge to use. Depending on how the form is configured, you may be able to use an xMatters-hosted conference bridge or an external bridge.
Example: New xMatters-hosted bridge
"conference":
{
"type": "BRIDGE"
}
Example: Existing xMatters-hosted bridge
"conference":
{
"bridgeId": "3882920",
"type": "BRIDGE"
}
Example: Externally-hosted bridge with static bridge number
"conference":
{
  "bridgeId": "Corporate WebEx",
  "type": "EXTERNAL"
}
Example: Externally-hosted bridge with dynamic bridge number
"conference":
{
  "bridgeId": "Corporate WebEx",
  "type": "EXTERNAL",
  "bridgeNumber": "74747466"
}
responseOptions ResponseOptions object
optional Overrides the form’s response options.
  • To select one of the form’s existing responses set the id field to the unique identifier of the response option (found in the user 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.
otherResponseCountThreshold integer
optional For forms that use response counts, this specifies the number of responses that are required from the “other recipients” group.
You can specify the response counts for individual groups and dynamic teams when you specify them as recipients, for example, use "recipients" :[{"id":"IT", "recipientType": "GROUP", "responseCountThreshold" : 3}] to set the response count threshold for the group ‘IT’.
targetAllDevices Boolean
When true, notifications target all types of devices in the system. This value cannot be set to true when the targetDeviceNames field is also true. See note.
targetDeviceNames Array [DeviceName object]
Defines the devices that are targeted by notifications. When values are provided for this field, targetAllDevices cannot be set to true. See note.

RESPONSES

Success Response code 202 Accepted and a request identifier in the response body. You can use the request identifier with GET /events to search for events triggered by the integration.
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes

Get notifications

To get a list of notifications, use GET notifications from the previous version of the REST API.

The linked endpoint will eventually be deprecated and replaced with an endpoint in this API.

Event objects

Event object

Event object

Example


{
  "id":"ced9fac9-1065-4659-82ab-1c9664a777b2",
  "eventId":"408005",
  "created":"2016-10-31T22:37:35.301+0000",
  "terminated":"2016-10-31T22:38:40.063+0000",
  "status":"TERMINATED_EXTERNAL",
  "priority":"MEDIUM",
  "incident":"INCIDENT_ID-408005",
  "expirationInMinutes":180,
  "floodControl" : "false",
  "otherResponseCount" : 2,
  "otherResponseCountThreshold" : 1,
  "submitter":
  {
    "id":"661f3f18-75ab-44fd-a22a-4bb0fe15917e",
    "targetName":"mmcbride",
    "links":
    {
      "self":"/api/xm/1/people/661f3f18-75ab-44fd-a22a-4bb0fe15917e"
    }
  },
  "recipients":
  {
    "count":1,
    "total":1,
    "data":
    [{
      ...truncated Recipient object...
    },
  },
  "form":
  {
    "id":"ef62b6ac-ba7e-40e8-9253-a837efcd38ea",
    "name" : "Database Outage"
  },
  "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":
  {
    "bridgeId":"67955226",
    "type":"BRIDGE"
  },
  "responseOptions":
  {
    "count":2,
    "total":2,
    "data":
    [{
      "number":1,
      "text":"Join",
      "description":"Join",
      "prompt":"I will join the conference bridge",
      "action":"RECORD_RESPONSE",
      "contribution":"NONE",
      "joinConference":true
     },
    {
      "number":2,
      "text":"Reject",
      "description":"Reject",
      "prompt":"I cannot assist",
      "action":"STOP_NOTIFYING_USER",
      "contribution":"NONE",
      "joinConference":false
    }]
  },
  "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>"
    }]
  }  
}

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 object
The comments that were made when users responded to a notification. This field contains only the first page of results (up to 100 messages). This object is included when ?embed=annotations is included in the request.
bypassPhoneIntro Boolean
When this value is set to true, xMatters omits the standard greeting and plays the message immediately.
created string
The date and time the event was initiated (in UTC format).
conference Conference object
Describes the conference bridge used with this event.
escalationOverride Boolean
When this value is set to true, xMatters ignores shift escalation delays and sends an immediate broadcast message to all recipients.
eventId string
The integer identifier used to identify this event in the xMatters user interface.
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.
form FormReference object
The identifier of the form.
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”
  • “MEDUIM”
  • “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.
responseOptions Pagination of ResponseOption object
The response options sent as part of the notification. This object is included when ?embed=responseOptions is included in the request.
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”
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.

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

ResponseOption object

ResponseOption object


 {
      "number":2,
      "text":"Reject",
      "description":"Reject",
      "prompt":"I cannot assist",
      "action":"STOP_NOTIFYING_USER",
      "contribution":"NONE",
      "joinConference":false
    }

The ResponseOption object describes the response options that are included in the event.

   
action string
The action to take when this response option is chosen. This is one of the following values:
  • “RECORD_RESPONSE”
  • “STOP_NOTIFYING_USER”
  • “STOP_NOTIFYING_TARGET”
  • “ESCALATE”
  • “ASSIGN_TO_USER”
  • “END”
contribution string
How to classify this response. This is one of the following values:
  • “POSITIVE”
  • “NEGATIVE”
  • “NEUTRAL”
  • “NONE”
description string
A description of the response to be included in email messages.
number integer
The keypad digit associated with this response, used when responding to voice notifications on a touch-tone phone.
prompt string
A phrase that is read aloud using text-to-speech translation for voice messages.
text string
The response option displayed on text devices and as a link in email messages.
joinConference Boolean
True if selecting this response from a touch-tone phone automatically connects you to the conference bridge.

Conference object

Conference object


{
  "bridgeId":"67955226",
  "type":"BRIDGE"
}

The Conference object describes xMatters-hosted and externally-hosted conference bridges associated with an event.

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


  {
    "myNumberProperty": 323423,
    "myPasswordProperty": "ilovecats123",
    "myTextProperty#en": "Please respond.",
    "myListProperty":
    [
      "iOS",
      "Android",
      "Windows 10"
    ],
    "myBooleanProperty": true,
    "myComboProperty": "Oracle Database",
    "myHierarchyProperty":
    [
      {
        "category": "Country",
        "value": "USA"
      },
      {
        "category": "State",
        "value": "WA"
      },
      {
        "category": "City",
        "value": "Seattle"
      }
    ]
  }  

The Properties object contains information about the event’s form properties.

By inspecting form properties you can extract message details and use them with other systems in your toolchain, for example, you could extract a ticket number from an event and then use it to close a ticket in your service desk system.

The names of fields in the Properties object correspond to the names of the actual form properties and are unique for every form.

The following table shows the example format of each property type:

Property TypeDescriptionExample
NumberAn integer."myNumberProperty": 323423
TextA string. Text property names include the language code. "myTextProperty#en": "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"
  }
]

VoicemailOptions object

VoicemailOptions object


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

   
retry integer
optional The nubmer of times to retry the call when voicemail is detected.
every integer
optional The number of seconds between retry attempts.
leave string
optional The action to take when voicemail is detected and there are no more retry attempts. Valid values include:
  • callbackandmessage: Leave the message and callback information. This option cannot be selected when the event requires a phone password.
  • messageonly: Leave the message content but do not leave callback information. 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.
  • hangup: do not leave a 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,
      "redirectUrl" : "https://jira.example.com/"
    }
  ]
}

You can choose to display the form’s existing responses, override properties of existing responses or create new responses. 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 will be presented on text devices and the mobile app, and how the link will appear in email responses. Corresponds to the Response field in the 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 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 user interface.
action string
If the form is not configured to count responses, valid values include the following:
  • “RECORD_RESPONSE”
  • “ASSIGN_TO_USER”
  • “STOP_NOTIFYING_USER”
  • “ESCALATE”
  • “END”
  • “STOP_NOTIFYING_TARGET”
If the form is configured to count responses, valid values include the following:
  • “COUNT_RESPONSE”
  • “OMIT_RESPONSE_COUNT”
contribution string
Describes whether to count the response as positive, negative, or neutral for reporting purposes. Valid values include the following:
  • “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.
redirectUrl string
When the user responds with this choice from email, mobile apps or the web UI, they are automatically redirected to this URL. You can use this to open a service desk ticket related to the incident or open chat room where people can discuss the issue.

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

```json
"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.

   
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.
List array[string]
Provide an array of string values that represent one or more list box selections.
Examples:
"Affected Locations" : ["Seattle", "Portland"]
"Department" : ["Accounting"]
Combo Box string
A string that represents a single selection in a combo box field.
Examples:
"Severity" : "LOW"
Password string
A string representation of a password
Examples:
"password" : "38se*#Ehww1"
Heirarchy array[objects]
Provide an array of objects that define a value for each level of the hierarchy. Each object defines the selection using two key/value pairs: thecategory field defines the name of the level and the value field defines the selection. The following example shows how to select a value from a Country > State > City heirarchy.
Example:
"region" : [
  {"category" : "Country", "value" : "USA"},
  {"category" : "State", "value" : "California"},
  {"category" : "City", "value" : "Los Angeles"}
]

Recipient Trigger

Recipient Trigger object

"recipients" :
[

  {"id":"mmcbride", "recipientType": "PERSON"},
  {"id":"bfdbcb31-d02e-4a4f-a91c-7d68fbe416df", "recipientType": "PERSON"},
  {"id":"mmcbride|Work Email", "recipientType": "DEVICE"},
  {"id":"4a0fdfb4-7c49-4581-9cd9-804f2956e19b", "recipientType": "DEVICE"},
  {"id":"Executives", "recipientType": "GROUP"},
  {"id":"f19d8b10-923a-4c23-8348-06ced678075e", "recipientType": "GROUP", "responseCountThreshold" : 3},
  {"id":"First Aid Attendants", "recipientType": "DYNAMIC_TEAM", "responseCountThreshold" : 1},
  {"id":"ed2606c5-ef2b-4ce8-9259-d5cdacd5bd90", "recipientType": "DYNAMIC_TEAM"} 
]

This is the format for specifying recipients when triggering an event. If your form is configured to count responses, you can include the response count (fill count) for each group or dynamic team recipient.

   
id string
The target name or unique identifier of the recipient.
recipientType string
optional The type of recipient. It is recommended to provide the recipient type to increase the performance of triggering an event. Value values include the following:
  • “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

  {
    "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"
  }

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 Event object
A link to the event where the comment was made
author Person object
The person who made the comment
comment string
The comment that was made when responding to 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",
        "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>"
      }
    ]

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.
language string
The language code (usually two letters) indicating the targeted user’s preferred language; for example, en for English, fr for French, de for German, and so on.
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.

FORMS

The linked methods let you to work with communication plan forms.

Communication plan forms define the messages that are sent to recipients.

Set form properties

The previous version of the REST API allows you to set the values of properties on a form.

This method will eventually be deprecated and replaced with a method in this API.

See PUT property values.

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 Group Calendar to retrieve who is currently on duty.

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)

curl --user username 
"https://acmeco.xmatters.com/api/xm/1/groups/Oracle%20Administrators"
/**
 * This script is configured to work within the xMatters Integration Builder.
 * Configure the "xMatters" endpoint to use a valid username and password.
 */
var request = http.request({ 
     "endpoint": "xMatters",
     "path": "/api/xm/1/groups/Oracle Administrators",
     "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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/groups/Oracle Administrators'
url = base_URL + endpoint_URL

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    groupID = response.json()['id']
    print 'Retrieved group ' + response.json()['targetName']

REQUEST (get a group by id)

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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/groups/438e9245-b32d-445f-916bd3e07932c89'
url = base_URL + endpoint_URL

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    print 'Retrieved group ' + response.json()['id']

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",
  "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).

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

URL PARAMETERS

   
{groupID} string
The unique identifier (id) or name (targetName) of the group. Group names 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.

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 within the xMatters Integration Builder.
 * Configure the "xMatters" endpoint to use a valid username and password.
 */
var request = http.request({ 
  "endpoint": "xMatters",
  "path": "/api/xm/1/groups",
  "method": "GET"
 });

var response = request.write();

if (response.statusCode == 200 ) {
   json = JSON.parse(response.body);
   console.log( "Retrieved " + json.count + " of " + json.total + " groups." );
   for (var i in json.data ) {
     console.log(json.data[i].targetName);
  }
}

import requests
from requests.auth import HTTPBasicAuth

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/groups'
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']) + " groups.")
    for d in json['data']:
        print d['targetName']

REQUEST (get groups with ‘admin’ or 'database’ in the name)

curl  --user username 
"https://acmeco.xmatters.com/api/xm/1/groups?search=admin database"
/**
 * 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",
  "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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/groups'
search_query = '/?search=admin database'

url = base_URL + endpoint_URL + search_query

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']) + " groups.")
    for d in json['data']:
        print d['targetName']

REQUEST (get groups with 'admin’ and 'database’ in the name)

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

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

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']) + " groups.")
    for d in json['data']:
        print d['targetName']

RESPONSE

{
  "count": 2,
  "total": 2,
  "data":
  [
  {
    "id": "438e9245-b32d-445f-916bd3e07932c892",
    "targetName": "Oracle Administrators",
    "recipientType": "GROUP",
    "status": "ACTIVE",
    "externallyOwned": false,
    "allowDuplicates": false,
    "useDefaultDevices": true,
    "observedByAll" : true,
    "description": "Oracle database administrators",
    "site":
    {
      "id": "dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
      "links":
      {
        "self": "/api/xm/1/sites/dbf90cbf-a745-a054-abf0-cb3b5b56e6bd"
      }
    },
    "links": 
    {
      "self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
    }
  },
  {
    "id": "827e9245-a48a-9921-955bd3e07932c600",
    "targetName": "Sys Admins",
    "recipientType": "GROUP",
    "status": "ACTIVE",
    "externallyOwned": false,
    "allowDuplicates": false,
    "useDefaultDevices": true,
    "observedByAll" : true,
    "description": "System database administrators",
    "site":
    {
      "id": "dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
      "links":
      {
        "self": "/api/xm/1/sites/dbf90cbf-a745-a054-abf0-cb3b5b56e6bd"
      }
    },
    "links": 
    {
      "self": "/api/xm/1/groups/438e9245-b32d-445f-916bd3e07932c892"
    }
  }
],
"links":    
{
    "self": "/api/xm/1/groups?offset=0&limit=100"
}

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.

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?search=term1 term2 term3&operand=AND

QUERY PARAMETERS

   
search string
A list of search terms separated by the + sign or a space character. Searches are case-insensitive and must contain a total of at least two characters. Searches cannot contain whitespace characters within an individual search term. When two or more search terms are present, the result includes groups that match either search term. You can narrow the search to results that include both terms by using the operand query parameter.
Example: /groups?search=admin corporate
operand string
The operand to use to limit or expand the search query parameter. 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 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. 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" : true,
    "description": "C-suite executives",
    "site": "dbf90cbf-a745-a054-abf0-cb3b5b56e6bd",
    "supervisors" : 
    [
      "410c96c4-8fdf-4936-a36f-13890b89ac3f", 
      "a608fa11-552a-4806-b247-48f083a20081"
    ],
    "targetName": "Executives"
}' "https://acmeco.xmatters.com/api/xm/1/groups" 
/**
 * This script is configured to work within the xMatters Integration Builder.
 * Configure the "xMatters" endpoint to use a valid username and password.
 */
var request = http.request({ 
     "endpoint": "xMatters",
     "path": "/api/xm/1/groups/",
     "method": "POST",
     "headers" : {"Content-Type": "application/json"}
 });

var data = {};
data.recipientType = 'GROUP';
data.targetName = 'Executives';
data.status = 'ACTIVE';
data.allowDuplicates = true;
data.useDefaultDevices = true;
data.observedByAll = 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);
}

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

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" : true,
    "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 = 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);
}
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',
        'id': '4888989a-3dd2-4edc-b0cd-ce4623cc454c',
        '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']

RESPONSE

{     
  "id": "4888989a-3dd2-4edc-b0cd-ce4623cc454c",
  "targetName": "Executives",
  "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-3dd2-4edc-b0cd-ce4623cc454c"
  }
}

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). After the group has been created you can build out the shift schedule and add members to the group roster.

See also Add a shift.

See also Add a member to a shift.

See also Add a member to the group roster.

DEFINITION

POST /groups

BODY PARAMETERS

   
allowDuplicates Boolean
optional True if recipients can receive more than one notification for the same event.
description string
optional A description of the group. The description can contain a maximum of 200 characters.
externalKey string
optional See externalKey.
externallyOwned Boolean
optional See externallyOwned.
observedByAll Boolean
optional True if all roles can view and target this group. If this value is false, you must log on to the xMatters user interface and set the roles that can target the group; otherwise this group will not be visible.
recipientType string
optional For groups, this value is “GROUP”. Providing this optional field allows xMatters to process your request more efficiently and improves performance.
id string
optional 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.
site string
optional 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
optional 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]
optional 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
optional 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 within the xMatters Integration Builder.
 * 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);
}
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 

headers = {'Content-Type': 'application/json'}

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

data = {'recipientType':'GROUP', 
        'id': '138e9245-bded-445f-916b-dda07932b679',
        '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 'Modified group ' + response.json()['targetName'] +  '. New description = ' + response.json()['description']

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

   
allowDuplicates Boolean
optional True if recipients can receive more than one notification for the same event.
description string
optional A description of the group. The description can contain a maximum of 200 characters.
externalKey string
optional See externalKey.
externallyOwned Boolean
optional See externallyOwned.
observedByAll Boolean
optional True if all roles can view and target this group. If this value is false, you must log on to the xMatters user interface and set the roles that can target the group; otherwise this group will not be visible to any roles.
recipientType string
optional The type of object. For groups, this value is “GROUP”. Providing this optional field allows xMatters to process your request more efficiently and improves performance.
id string
The unique identifier of the group.
site string
optional The identifier of the site that the group uses for holidays.
status string
optional Whether the group is active. Inactive groups cannot receive notifications. Use one of the following values:
  • “ACTIVE”
  • “INACTIVE”
supervisors array[string]
optional 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
optional The name of the group. Providing this value renames the group. The name can have a maximum of 100 characters.
useDefaultDevices Boolean
optional 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 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 within the xMatters Integration Builder.
 * Configure the "xMatters" endpoint to use a valid username and password.
 */
var request = http.request({ 
  "endpoint": "xMatters",
  "path": "/api/xm/1/groups/Oracle Administrators",
  /*"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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpointURL = '/groups/Oracle Administrators'
url = baseURL + endpointURL

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

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

responseCode = response.status_code
if (responseCode == 200):
    print 'Deleted group ' +  response.json()['targetName']

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 who is on call (deprecated)

Get who is on call (deprecated)

REQUEST (get who is on call)
This request does not ask for enhanced response data. The response includes the shift identifier but not the shift name.

curl --user username "https://acmeco.xmatters.com/api/xm/1/groups/IT/calendar" 
var request = http.request({ 
     "endpoint": "xMatters",
     "path": "/api/xm/1/groups/IT/calendar",
     "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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/groups/IT/calendar'

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    json = response.json();
    for d in json['data']:
        #shift does not include the name field, so use the id
        print '\nShift id = ' + d['shift']['id']
        print 'Shift members:'
        for md in d['members']['data']:
            print  md['member']['targetName']

REQUEST (get who is on call)
This request uses the query parameter ?embed=shift to request the name of the shift to be included in the response. This request also includes the members.owner query parameter to request extra information about the owner of device objects.

curl --user username "https://acmeco.xmatters.com/api/xm/1/groups/IT/calendar?embed=shift,members.owner" 
var request = http.request({ 
     "endpoint": "xMatters",
     "path": "/api/xm/1/groups/IT/calendar?embed=shift,members.owner",
     "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.name + " members:");
     var memberData = dd.members.data;
     for (var i in memberData)
     {
         console.log(memberData[i].member.targetName);
     }
  }
}

import requests
from requests.auth import HTTPBasicAuth

url = base_URL + '/groups/' + group_name + '/calendar?embed=shift,members.owner'

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    json = response.json();
    for d in json['data']:
        #the shift contains the name field because it was called with ?embed=shift
        print '\nShift name = ' + d['shift']['name']
        print 'Shift members:'
        for md in d['members']['data']:
            print  md['member']['targetName']

RESPONSE

{
  "count": 1,
  "total": 1,
  "data":
  [{
    "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":
      [{
        "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"
        }
      }],
      "links":
      {
        "self": "/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd/shifts/07ae192b-614d-4986-931e-2e163f8132ce?offset=0&limit=100"
      }
     }
  }],
  "links":
  {
    "self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd/calendar?offset=0&limit=100"
  }
}

DEPRECATED Use GET /on-call to retrieve the on-call schedule that includes more information about temporary replacements, including who is being replaced.

Returns the shifts and group members that are on call.

You can identify the group using either its name (targetName) or its unique identifier (id).

This endpoint returns the start and end time of each shift and a list of the members that are on call. If a timeframe is provided with the request, this endpoint returns all shifts occurrences that are active within the time frame. If no timeframe is specified it 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.

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.

DEFINITION

GET /groups/{groupID}/calendar

GET /groups/{groupID}/calendar?embed=shift,members.owner

GET /groups/{groupID}/calendar?at=2017-02-23T04:00:00Z

GET /groups/{groupID}/calendar?from=2017-02-23T04:00:00Z&to=2017-02-26T04:00:00Z

URL PARAMETERS

   
{groupID} string
The unique identifier (id) or name (targetName) of the group.

QUERY PARAMETERS

   
embed string
optional 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 the following fields.
    • name
    • group
  • 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
at string
optional A date time value in UTC format. When provided, the response shows the on-call schedule for the given time.
from string
optional 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. This value cannot be in the past.
Example:
2017-02-23T04:00:00Z
to string
optional 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. This value cannot be in the past and cannot be more than 30 days after the from value.
Example:
2017-02-26T04:00:00Z

RESPONSES

Success Response code 200 OK and a Pagination of ShiftOccurrence 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 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/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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/groups/DBAdmin/supervisors'
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']) + " supervisors.")
    for d in json['data']:
        print d['targetName']

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

Group Objects

Group object

Group Object

{
  "id": "438e9245-b32d-445f-916bd3e07932c892",
  "targetName": "Oracle Administrators",
  "recipientType": "GROUP",
  "status": "ACTIVE",
  "externallyOwned": false,
  "allowDuplicates": false,
  "useDefaultDevices": true,
  "observedByAll" : true,
  "description": "Oracle database administrators",
  "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 and group observers, log on to the xMatters user interface and view the group.

See also Recipient object.

   
allowDuplicates Boolean
True if recipients can receive more than one notification for the same event.
description string
A description of the group.
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. To view or set the list of group observer roles, log on to the xMatters user interface and edit the group.
recipientType string
For groups, the recipient type field is “GROUP”.
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.

GroupReference object

GroupReference object

{
  "id": "e953c223-dd60-45c2-8ebb-0b02845e5dbd",
  "targetName": "IT",
  "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.
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",
  "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.

   
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",
    "links":
    {
      "self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd"
    }
  },
  "member":
  {
    "id": "ceb08e86-2674-4812-9145-d157b0e24c17",
    "targetName": "mmcbride",
    "recipientType": "PERSON",
    "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 may optionally contain information about the specific shifts the member belongs to.

To include shift information when getting the group roster with Get the group roster, use the ?embed=shifts query parameter.

   
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
optional A list of the shifts the member belongs to.

GROUP ROSTER

The group roster defines the members of the group and which shifts they belong to.

Get the group roster

Get the group roster

REQUEST (get group roster, including embedded shift information)

curl --user username "https://acmeco.xmatters.com/api/xm/1/groups/IT/members?embed=shifts"
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.targetName);
     var shifts = json.data[d].shifts.data;
     for (var i in shifts)
     {
         console.log(shifts[i].name);
     }
  }
}
import requests
from requests.auth import HTTPBasicAuth

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/groups/IT/members?embed=shifts'

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    json = response.json();
    for d in json['data']:
        print '\nMember = ' + d['member']['targetName']

        #print shift names when using ?embed=shifts
        print 'Shifts for: ' + d['member']['targetName']
        for s in d['shifts']['data']:
            print  '\t' + s['name']       

RESPONSE

{
  "count": 1,
  "total": 1,
  "data":
  [
  {
    "group":
    {
      "id": "e953c223-dd60-45c2-8ebb-0b02845e5dbd",
      "targetName" : "IT",
      "links":
      {
        "self": "/api/xm/1/groups/e953c223-dd60-45c2-8ebb-0b02845e5dbd"
      }
    },
    "member":
    {
      "id": "ceb08e86-2674-4812-9145-d157b0e24c17",
      "targetName": "mmcbride",
      "recipientType": "PERSON",
      "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.

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

URL PARAMETERS

   
groupID string
The unique identifier (id) or name (targetName) of the group. This value must be URL-encoded.

QUERY PARAMETERS

   
embed string
optional Use the ?embed=shifts query parameter to include shift information in the response.
Example: /groups/IT/members?embed=shifts

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" 

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);
}
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 

headers = {'Content-Type': 'application/json'}
auth = HTTPBasicAuth('username', 'password')

data = {'recipientType':'PERSON', 
        'id': 'bab4a72f-e118-462d-ad87-ee8e28e722e0',
       }

data_string = json.dumps(data)

response = requests.post(url, headers=headers, data=data_string, auth=auth)

if (response.status_code == 200):
   rjson = response.json();
   print 'Added member: ' + rjson.get('targetName') + '. ID = ' + rjson.get('id')

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

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 to but do not know which shift the member should belong to. This allows you to add users to a group with the API and then later organize them into their specific shifts. 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
optional The type of the group member. Providing this optional field allows xMatters to process your request more efficiently and improves performance. Use one of the following values:
  • “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"
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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/groups/IT/members/mmcbride' 

response = requests.delete(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    json = response.json();
    print 'Removed member: ' + json['member']['id'] + 'from ' + json['group']['targetName']
elif (response.status_code == 204):
    print 'Member not found'

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 and its corresponding shifts. 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.

OAUTH

OAuth 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’ll need to obtain 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 using GET /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. See Authorize a request for more information about using the access token to authenticate a request.
  4. When an access token expires, obtain a new access token by using the refresh token and client ID as described in Refresh an access token.
  5. You can revoke the tokens at any time from the xMatters user interface.

Revoking Tokens

You can revoke all tokens assigned to a user by logging on to the xMatters UI, navigating to their profile, and clicking Revoke Authorization Tokens.

If you want to revoke your own tokens, you can revoke them from your own profile page or you can go to Developer > OAuth and click Revoke Authorization Tokens.

Revoking access to tokens revokes all tokens associated with a user’s account. If you are using multiple tokens and you want to revoke one of them, you must revoke all tokens and then reauthenticate the other applications.

Get access / refresh tokens

Get an access token and refresh token

curl --request POST 
'https://acmeco.xmatters.com/api/xm/1/oauth2/token?grant_type=password&client_id=7469ebe0-4dff-4a1b-84fe-0d1b3baf9dcf&username=username&password=password'
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')



/**
 * The Integration Builder currently uses HTTP Basic authentication
 * for xMatters endpoints.
 */

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

To authorize a request using an access token, see Authorize a request.

To refresh an expired access token, see Refresh an access token.

DEFINITION

POST /oauth2/token

QUERY PARAMETERS

   
grant_type string
The grant type. Use “password”.
client_id string
Your client ID. You can locate your client ID on the OAuth page of the Developer tab.
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
ErrorFor a list of response codes returned by the xMatters REST API, see HTTP Response Codes.

Authorize a request

Authorize a request with OAuth

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'

/**
 * The Integration Builder currently uses HTTP Basic authentication
 * for xMatters endpoints.
 */


    url = base_URL + '/people/mmcbride' 

    token = 'eyJhbGciOiJSUzI1NiJ9.eyJwIjoiMzEzalR2Ly8vLy8zLy8vLy82LzcvLy8vLy8vLytmLy8vLy8vLy9QLy8vLy8vLy8vQi83Ly8vLy8veC84Ly8vLy8vLy8vLy8vLy8vL0R3PT0iLCJhdWQiOlsiaWJhdXRvMS5iZXNwaW4uc2hhcmVkLWRldi54bWF0dGVycy5jb20iXSwic3ViIjoic2FuZHJhIiwiYXpwIjoiNzQ2OWViZTAtNGRmZi00YTFiLTg0ZmUtMGQxYjNiYWY5ZGNmIiwiaXNzIjoieG1hdHRlcnMiLCJzYmkiOjUxNDY0MiwiZXhwIjoxNDc5MzIzMzY0LCJpYXQiOjE0NzkzMjI0NjQsImFpZCI6MjAwMDIyLCJqdGkiOiI2ZjlkNGY0Yy1hZGJjLTQ3YzMtYjk5ZS00YjIzNWU1YTNkMzMifQ.5RQ7r8NQL_-_BO53T4ie_5a1MAISYDalmyVjzwZIUtadu8xd0WiFn2nFFlAZj9l6iFLxQuDbN8OVzh7jVB3pLu6EUKNO9V6_7woSycFq9iKGisO-QxKuG6eUPwSbRSwhVzqV8v3Zjcw2cpQAtZeTKmTUi8vma7dAKxq4cevSlcop2WZAHPckMI3lEFQ4CTT2_na11i55V8vdP54kRa95fLigDsDLt64gn6Xl5-kP-Z2FlZ8qy_gQ5GIf3iVXq3ASVmEq-93dPgpmSJOVXZGVG3zQIGt8706ofVvNmrGkUWpAKljo-A7IBhpMJFEex6grw35754v96VkSPdKzYSJ8KQ'
    bearer_token = 'Bearer '+ token
    headers = {'Authorization': bearer_token}
    response = requests.get(url, headers=headers)

    if (response.status_code == 200):
        print 'Retrieved person ' + response.json()['targetName'] + ', id= ' + response.json()['id']

    elif (response.status_code == 404):
        print 'The person could not be found' + person_name 

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 Get access / refresh tokens.

To obtain a new access token using your refresh token and client ID, 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'

/**
 * The Integration Builder 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
Use “refresh_token”.
client_id string
Your client ID.
Example: 1432ebe0-4dff-4c3b-84fe-0d1aa31f51ee
refresh_token string
The refresh token obtained from a call to GET /oauth2/token.
Example: 4a90179e-12e8-4965-bc0c-66c0f6b70458

RESPONSES

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

OAuth objects

AccessToken object

Example

    {
        "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"
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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/on-call?groups=IT'

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    json = response.json();
    for d in json['data']:
        #shift does not include the name field, so use the id
        print '\nShift id = ' + d['shift']['id']
        print 'Shift members:'
        for md in d['members']['data']:
            print  md['member']['targetName']

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



Returns who is currently on call for a group (or set of groups), including who is scheduled to be on call and any temporary replacements that are covering for them.

This endpoint replaces GET /groups/{groupId}/calendar.

You can identify groups by their name (targetName) or unique identifier (id).

This endpoint returns the start and end time of each shift and a list of the members that are on call. If a timeframe is provided with the request, this endpoint returns all shift occurrences that are active within the timeframe. If no timeframe is specified, it 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.

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.

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 identfy 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
optional 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.
from string
optional 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. This value cannot be more than one day in the past.
Example:
2017-02-23T04:00:00Z
to string
optional 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. This value cannot be in the past and cannot be more than 30 days in the future.
Example:
2017-02-26T04:00:00Z
embed string
optional 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 the following fields.
    • name
    • group
  • 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
A reference to the group.
shift ShiftReference
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.

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

PEOPLE

The /people endpoints allow you to work with users in xMatters.

Get a person

Get a person

REQUEST (get a person by their user name, including roles)

curl --user username "https://acmeco.xmatters.com/api/xm/1/people/mmcbride?embed=roles"

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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/people/' + 'mmcbride' + '?embed=roles'

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    print 'Retrieved person ' + response.json()['targetName'] + ', id= ' + response.json()['id']

elif (response.status_code == 404):
    print 'The person could not be found'


REQUEST (get a person by their identifier, including 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

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

url = base_URL + '/people/' + 'b2341d69-8b83-4660-b8c8-f2e728f675f9' +'?embed=roles'

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    print 'Retrieved person ' + response.json()['targetName'] + ', id= ' + response.json()['id']

elif (response.status_code == 404):
    print 'The person could not be found' 

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"
    }
  },
  "properties": 
  {
    "Building" : "Engineering Wing",
    "hasFirstAid" : true,
    "Level" : 7.4,
    "RoomNumber" : 422,
    "Post-secondary Degrees" : ["BA", "MA", "PhD"],
  },
  "roles": {
    "count": 2,
    "total": 2,
    "data": [
      {
        "id": "c2bdcd9e-1a18-0ff6-ffde-76e4022c94e6",
        "name": "Standard User"
      },
      {
        "id": "593433b0-e3b7-2e4c-f0cf-9faf2110b069",
        "name": "Group Monitor"
      }
    ]
  },
  "status": "ACTIVE"
}

Returns a Person object that represents a user in xMatters.

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=roles 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.

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

Get people

REQUEST (get all people)

curl --user username "https://acmeco.xmatters.com/api/xm/1/people"

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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/people' 

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    print 'Retrieved ' + str(response.json()['count']) + ' of ' + str(response.json()['total']) + " people."

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'
url = base_URL + '/people?offset=300&limit=100' 

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
   print 'Retrieved ' + str(response.json()['count']) + ' of ' + str(response.json()['total']) + " people."

REQUEST (get people with contact information “mmcbride@xmatters.com”)

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'
url = base_URL + '/people?search=mmcbride@xmatters.com'

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
   print 'Retrieved ' + str(response.json()['count']) + ' of ' + str(response.json()['total']) + " people."

REQUEST (getpeople with a custom field or attribute of “First Aid” that has the value “CPR”)

curl --user username 
"https://acmeco.xmatters.com/api/xm/1/people/?propertyName=First%20Aid&propertyValue=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'
url = base_URL + '/people?propertyName=First Aid&propertyValue=CPR'

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
   print 'Retrieved ' + str(response.json()['count']) + ' of ' + str(response.json()['total']) + " people."

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"}
       },
       "status":"ACTIVE"
    },

 ...

  "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. Use the propertyName/propertyValue query parameters to return users that have matching custom fields and attributes. When two or more search terms are present, the result includes people that match either search term.

DEFINITION

GET /people
GET /people?search={term}
GET /people?propertyName={name}&propertyValue={value}
GET /people?embed=roles

QUERY PARAMETERS

   
search string
A list of search terms separated by the + sign or a space. Searches are case-insensitive and must contain a total of at least two characters. Searches cannot contain whitespace characters within an individual search term. The result set includes people 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
Example: 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.
propertyName, propertyValue string, value
A list of name/value pairs that represent custom fields and attributes. 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).
Example: GET people/?propertyName=First%20Aid&propertyValue=CPR
returns a list of users that have a custom field or custom attribute named “First Aid” with the value “CPR”.
embed string
Use ?embed=roles to include a list of each person’s roles in the result.

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 -H "Content-Type: application/json" --user username -X POST -d 
'{
  "targetName":"mmcbride",
  "firstName" : "Mary",
  "lastName": "McBride",
  "recipientType" : "PERSON",
  "language": "en",
  "timezone": "US/Pacific",
  "webLogin": "mmcbride",
  "phoneLogin" : "23423",
  "roles":  ["Standard User"],
  "site": "671b58b4-9b8b-4b79-8801-8d9001dc180f",
  "status" : "ACTIVE",
  "supervisors": 
  [
    "481086d8-357a-4279-b7d5-d7dce48fcd12"
  ], 
  "properties": 
  {
    "Building" : "Engineering Wing",
    "hasFirstAid" : true,
    "Level" : 7.4,
    "RoomNumber" : 422,
    "Post-secondary Degrees" : ["BA", "MA", "PhD"]
  }
 }
' 
 "https://acmeco.xmatters.com/api/xm/1/people" 

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.language = 'en';
data.timezone = 'US/Pacific';
data.webLogin = 'mmcbride';
data.phoneLogin = '23423';
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.Building = 'Engineering Wing';
properties.hasFirstAid = true;
properties.level = 7.4;
properties['Post-secondary Degrees'] = ['BA', 'MA', 'PhD'];
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 exits");
}
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 

headers = {'Content-Type': 'application/json'}

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

properties = 
{
    'Building' : 'Engineering Wing',
    'hasFirstAid' : True,
    'Level' : 7.4,
    'RoomNumber' : 422,
    'Post-secondary Degrees' : ['BA', 'MA', 'PhD']
}

data = 
{ 
     'targetName' : 'mmcbride',
     'firstName' : 'Mary',
     'lastName': 'McBride',
     'recipientType' : 'PERSON',
     'status' : 'ACTIVE',
     'language': 'en',
     'timezone': 'US/Pacific',
     'webLogin': 'mmcbride',
     'phoneLogin' : '23423',
     '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)

if (response.status_code == 201):
   rjson = response.json();
   print 'Created person ' + rjson.get('targetName') + '. id = ' + rjson.get('id')

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"
    }
  },
 "properties": 
  {
    "Building" : "Engineering Wing",
    "hasFirstAid" : true,
    "Level" : 7.4,
    "RoomNumber" : 422,
    "Post-secondary Degrees" : ["BA", "MA", "PhD"],
  },
  "status": "ACTIVE"
}

Creates a new user in xMatters.

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
optional See externalKey.
externallyOwned Boolean
optional See externallyOwned.
firstName string
The first name of the user. This value can be a maximum of 100 characters.
id string
optional 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.
language string
optional The person’s preferred language.
lastName string
The last name of the person. This value can be a maximum of 100 characters.
phoneLogin string
optional 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 lenght of 30 characters.
properties Properties object
optional Values of custom fields and custom attributes for this person.
recipientType string
optional 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"]
site string
optional The unique identifier of the site to assign the user to. This value is optional, and if not provide the user is assigned to your company’s default site.
Example:
"671b58b4-9b8b-4b79-8801-8d9001dc180f"
status string
optional Whether the person is active. Inactive people cannot receive notifications. Use one of the following values:
  • “ACTIVE”
  • “INACTIVE”
supervisors array[string]
optional A list of unique identifiers that identify 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.
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
optional The person’s time zone.
Example:
US/Pacific
webLogin string
optional 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" 


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);
}
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 

headers = {'Content-Type': 'application/json'}

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

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)

if (response.status_code == 200):
   rjson = response.json();
   print 'Modified person ' + rjson.get('targetName') + '. status = ' + rjson.get('status')

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

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 you do not include the id field, xMatters treats this as a request to create a new person.

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"

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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/people/'
url = base_URL + endpoint_URL + 'mmcbride'

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

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

if (response.status_code == 200):
     print 'Deleted person ' +  response.json().get('targetName')
elif (response.status_code == 204):
        print 'The person could not be found.' 

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)

curl --user username "https://acmeco.xmatters.com/api/xm/1/people/akaur/devices?embed=timeframes"
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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/people/akaur/devices?embed=timeframes'

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
   print 'Retrieved ' + str(response.json()['count']) + ' of ' + str(response.json()['total']) + " devices."


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.

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
optional 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
optional 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"
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 belongss 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'

url = base_URL + '/people/' + person_name + '/group-memberships'

response = requests.get(url, auth=HTTPBasicAuth(username, password))

if (response.status_code == 200):
    json = response.json()
    print 'Retrieving group memberships for ' + person_name 
    for d in json['data']:
        print 'User "' + person_name + '" belongs to group "' + d['group']['targetName'] + '" as a "' + d['member']['recipientType'] + '" named "' +  d['member']['targetName'] +'"'

elif (response.status_code == 404):
    print 'The person could not be found' + person_name 

RESPONSE The response shows that aalbaf is a member of the Operations group and that his work email device is a member of the Database Administrators group.


{
    "count": 2,
    "total": 2,
    "data":
    [
        {
            "group":
            {
                "id": "4eee0564-adcd-4d3a-84de-da3b7bd14898",
                "targetName": "Database Administrators",
                "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",
                "links":
                {
                    "self": "/api/xm/1/groups/857a341a-487a-47d6-a540-857f25854e2d"
                }
            },
            "member":
            {
                "id": "48244154-b9df-4397-b91f-ee5b67dc485f",
                "targetName": "mmcbride",
                "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 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/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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/people/jsmith/supervisors'
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']) + " supervisors.")
    for d in json['data']:
        print d['targetName']

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"
        }
      },
      "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 /person 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

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",
  "externallyOwned":false,
  "links":    
  {
    "self":"/api/xm/1/people/9407eb2e-8eb2-43d9-88a8-875237af941d"
  },
  "firstName":"Mary",
  "lastName":"McBride",
  "language":"en",
  "timezone":"US/Pacific",
  "webLogin":"mmcbride",
  "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"
      }
    ]
  },
  "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.
phoneLogin string
An access code that the person can use to identify themselves when they phone in to xMatters to retrieve messages.
properties Properties object
A list of the custom fields and attributes that are defined for this person.
roles Pagination of Role object
optional 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 Pagination of Person objet
optional A list of the user’s supervisors. This optional field is included when the request uses the ?embed=supervisors query parameter.
timezone string
The person’s time zone.
Example: “US/Eastern”
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, 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",
"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.
links SelfLink object
A link that can be used to retrieve the person using this API.

Role object

Role object

{
  "id" : "321086d8-928a8-4279-b715-d7dce48f27a8e9b",
  "name": "Company Supervisor"
}

Refers to a role in xMatters.

   
id string
The unique identifier of the role.
name string
The name of the role.

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" 
var parameters = request.parameters;

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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/groups/IT/shifts/24x7'

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    print 'Retrieved shift ' + response.json()['name'] + ', id= ' + response.json()['id']              

REQUEST (get a shift by identifier)

curl --user username "https://acmeco.xmatters.com/api/xm/1/groups/1bad48fa-5eac-4c2e-aed4-fd7d4ca3f538/shifts/8a63013a-870c-4f02-8afc-c174a235318d" 
var request = http.request({ 
     "endpoint": "xMatters",
     "path": "/api/xm/1/groups/1bad48fa-5eac-4c2e-aed4-fd7d4ca3f538/shifts/8a63013a-870c-4f02-8afc-c174a235318d",
     "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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/groups/1bad48fa-5eac-4c2e-aed4-fd7d4ca3f538/shifts/8a63013a-870c-4f02-8afc-c174a235318d'

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    print 'Retrieved shift ' + response.json()['id']

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 for a group, see Get a group. You can locate the name of a group or a shift in the user interface.

DEFINITION

GET /groups/{groupID}/shifts/{shiftID}

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

{shiftID} string
The id or targetName of the shift.
Example:24x7
Example:8a63013a-870c-4f02-8afc-c174a235318d

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)

curl --user username "https://acmeco.xmatters.com/api/xm/1/groups/IT/shifts"
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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/groups/IT/shifts'

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    print 'Retrieved ' + str(response.json()['count'] + ' of ' + str(response.json()['total']) + "shifts"              

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 for a group, see Get groups. You can locate the name of a group in the web user interface.

DEFINITION

GET /groups/{groupID}/shifts

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

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.

Add a shift

Add a shift

REQUEST (add a shift)
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": "Weekends"
}'
"https://acmeco.xmatters.com/api/xm/1/groups/Database%20Administrators/shifts" 
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 = "Weekends";

response = request.write(data);

if (response.statusCode == 201) {
   json = JSON.parse(response.body);
   console.log( "Created shift: " + json.name + ". ID = "+ json.id);
}
import requests
from requests.auth import HTTPBasicAuth
import json

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/groups/Database Administrators/shifts'  

headers = {'Content-Type': 'application/json'}
auth = HTTPBasicAuth('username', 'password')

data = {'name': 'Weekends'}
data_string = json.dumps(data)

response = requests.post(url, headers=headers, data=data_string, auth=auth)

if (response.status_code == 201):
   print 'Created shift ' + response.json().get('name') + '. ID = ' + response.json().get('id')

RESPONSE

{
  "id": "8d3bb1e5-d97b-4e1d-80d7-b0696b9645ac",
  "name": "Weekends",
  "group":
  {
    "id": "d9e6be4c-684b-4b3e-9995-d7f606804bbb",
    "targetName": "Database Administrators",
    "links":
    {
      "self": "/api/xm/1/groups/d9e6be4c-684b-4b3e-9995-d7f606804bbb"
    }
  },
  "links":
  {
    "self": "/api/xm/1/groups/d9e6be4c-684b-4b3e-9995-d7f606804bbb/shifts/8d3bb1e5-d97b-4e1d-80d7-b0696b9645ac"
  }
}

Adds an empty shift to a group.

The shift is configured to always be on duty (24x7) and does not contain any members.

See Add a member to a shift for more information about adding a member to a shift with the xMatters REST API. You can modify the shift in the xMatters user interface to change its duration and recurrence pattern and configure the escalation timeline.

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

   
name string
The name of the shift. The name can contain a maximum of 100 characters.

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" 
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);
}

import requests
from requests.auth import HTTPBasicAuth
import json

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
url = base_URL + '/groups/IT/shifts/24x7/members'
headers = {'Content-Type': 'application/json'}
auth = HTTPBasicAuth('username', 'password')
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)

if (response.status_code == 200):
   rjson = response.json();
   print 'Added member ' + rjson.get('recipient').get('id') 

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
optional 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
optional 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
optional 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
optional 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 within the xMatters Integration Builder.
 * Configure the "xMatters" endpoint to use a valid username and password.
 */
var request = http.request({ 
  "endpoint": "xMatters",
  "path": "/api/xm/1/groups/Oracle Administrators/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

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpointURL = '/groups/Oracle Administrators/shifts/Evenings'
url = baseURL + endpointURL

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

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

responseCode = response.status_code
if (responseCode == 200):
    print 'Deleted shift ' +  response.json()['targetName']
elif (response.status_code == 204):
    print 'The shift could not be found.'

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",
  "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, and the group to which it belongs.

   
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.

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 within the xMatters Integration Builder.
 * 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

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

site_name = 'San Ramon'

base_URL = 'https://acmeco.xmatters.com/api/xm/1'
endpoint_URL = '/sites'

url = base_URL + endpoint_URL + '/' + site_name

response = requests.get(url, auth=HTTPBasicAuth('username', 'password'))

if (response.status_code == 200):
    print 'Retrieved site ' + response.json()['name']

elif (response.status_code == 404):
    print 'The site could not be found: ' + site_name


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/Pacific",
  "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, see Locate the identifier for a site. You can access site information if you have permission to either view sites or your own devices in the xMatters user interface.

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

To get a list of sites in the system, use Get sites from the previous version of the REST API.

The linked endpoint will eventually be deprecated and replaced with an endpoint in this API.

Create a site

To create a site, use Post site from the previous version of this API.

The linked endpoint will eventually be deprecated and replaced with an endpoint in this API.

Modify a site

To modify the properties of a site, use Post site from the previous version of this API.

The linked endpoint will eventually be deprecated and replaced with an endpoint in this API.

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/Pacific",
  "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.

   
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.
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.
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.
Example: “US/Pacific”

SUBSCRIPTIONS

Subscriptions allow you to notify users even when they are not targeted as a recipient of the event.

Subscribe to an event

The previous version of the REST API allows you to subscribe to an existing subscription.

This method will eventually be deprecated and replaced with a method in this API.

See Post feed.