Deprecated REST API methods

These REST API methods are deprecated and have been replaced by methods in the xMatters REST API.

GET events (deprecated)

Returns a list of event resources in the xMatters system. You can use the provided URLs with the PUT method to modify individual events.

You can retrieve events based on their date, status, or properties by specifying these values with URL parameters.

Specification
HTTP Method	GET
URL Path	https://<company>.<deployment>.xmatters.com/reapi/2015-01-01/events
Parameters	Yes. For more information, see the "URL Parameters" section below.
Data	None.
Response	200 OK returned if no errors. 400 Returned if the passed parameters are not valid. The JSON response describes the error. 401 Returned if the user is not authenticated. 403 Returned if the user does not have permission to access the service. The response header describing the details of the error. 404 Returned if the server is unavailable. 500 Returned if the operation failed for any reason. The JSON response describes the nature of the error.
Pagination	The results are paginated.
Supported API Versions	2013-12-01, 2014-06-01, 2015-01-01

URL Parameters

You can use the following URL parameters to refine the list of returned events.

Parameters
Name	Required	Description
status	optional	The status of the events to return. Values must be one of "ACTIVE", "SUSPENDED", or "TERMINATED".
range	optional	The date range of events to return. The start date must be before the end date. Dates must be formatted as start_date/end_date , where start_date and end_date are formatted in the ISO 8601 date format and are URL-encoded. Example format: yyyy-MM-dd'T'HH:mm:ssZ/yyyy-MM-dd'T'HH:mm:ssZ Example (before URL-encoding): 2013-03-12T14:45:48.011/2013-03-12T15:00:48.011 Example (URL-encoded): range%3D2013-03-12T14%3A45%3A48.011%2F2013-03-12T15%3A00%3A48.011
properties["property name"]	optional	Properties of events to return. You can specify multiple properties parameters. Properties must be formatted as a list of key/value pairs that are separated by the = sign. The key value pairs must be URL-encoded. Example (before URL-encoding): properties=key1=value1,key2=value2 properties=reason=Pilot error,EOC activated=true Example (after URL-encoding of the key/value pairs): properties=key1%3Dvalue1%2Ckey2%3Dvalue2 properties=reason%3DPilot%20error%2CEOC%20activated%3Dtrue
startAfterEvent	optional	When the startAfterEvent parameter is specified, this method returns events with an event ID lower than the startAfterEvent value. For example, if you specify startAfterEvent=2493014, only events with an event ID lower than 2493014 are returned. When a request to GET events returns more than one page of records, the response body includes a value for the nextRecordsUrl property that uses the startAfterEvent parameter to define the next page of results.

Example Request

The following request asks for ACTIVE events with HIGH severity that have occurred on March 12, 2013 between 14:45:48.011 and 15:00:40.011.

curl --user username https://acme.na1.xmatters.com/reapi/2015-01-01/events?status=ACTIVE&range=2013-03-12T14:45:48.011/2013-12-12T15:00:48.011&properties=incident%3DINC-2039482%2Cseverity%3DHIGH

Example Response

The response body includes the total number of matching events and a list of URLs that contain event identifiers. If there is more than one page of results, the response body includes a link to the next page of events in the nextRecordsUrl property.

{
  "total": 231,
  "nextRecordsUrl":"/reapi/2015-01-01/events?status=ACTIVE&range=2013-03-12T14:45:48.011/2013-03-01T15:00:48.011&properties=incident%3DINC-2039482%2Cseverity%3DHIGH&startAfterEvent=230183",
  "records": 
  [
    {"href":"/reapi/2015-01-01/events/23430"},
    {"href": "/reapi/2015-01-01/events/23431"}
  ]

...

PUT event (deprecated)

Changes the status of an existing event to TERMINATED, SUSPENDED, or ACTIVE.

Specification
HTTP Method	PUT
URL Path	https://<company>.<deployment>.xmatters.com/reapi/2015-01-01/events/<eventID>
Response	200 OK 400 Bad Request returned if malformed or event not found 401 Returned if the user is not authenticated. 403 Returned if the user does not have permission to access the service, with the response header describing the details of the error 404 Returned if the event is not found 500 Returned if the operation failed for any reason, with the JSON response describing the nature of the error
Parameters	None
Supported API Versions	2012-03-01, 2013-12-01, 2014-06-01, 2015-01-01

Example Requests

curl -H "Content-Type: application/json" --user username -X PUT -d '{ "status":"terminated" }' "https://acme.na1.xmatters.com/reapi/2015-01-01/events/2489027"

Response Body

None if successful.

Sample Request Failure

{
  "type":"DATA_VALIDATION_ERROR",
  "message":"There are data validation errors in the form",
  "details":
  [
    {"$.status":"Value must be one of: TERMINATED, SUSPENDED, ACTIVE"}
  ]
}

POST event (deprecated)

This method has been deprecated. This method is replaced by POST trigger, which identifies forms by a unique identifier instead of by name.

Creates a new event and optionally includes response callback URLs (webhooks) that can update third-party systems.

If the event is not preconfigured with recipients, you must specify at least one recipient. If the event has preconfigured recipients, you can either use the existing recipients or you can overwrite them.

Specification
HTTP Method	POST
URL Path	Deprecated: https://<company>.<deployment>.xmatters.com/reapi/2014-06-01/engines/<engine>/<form>/events Note: the latter URL path originally ended with /{form}. This syntax has be deprecated but can still be used.
Request	Form Object
Response	200 - OK returned if no errors with an Event Object 400 - Bad Request returned if malformed (e.g., missing required parameters, unsupported syntax, etc.) 401 - Returned if the user is not authenticated 403 - Returned if the user does not have permission to access the service, with the response header describing the details of the error 404 - Returned if the plan or form is not found or not deployed as web service 500 - Returned if the operation failed for any other reason, with the JSON response describing the nature of the error
Supported API Versions	Deprecated. Available in 2012-03-01, 2013-12-01, 2014-06-01

JSON Objects
Object	Properties	Required	Description
Form	properties	No	Map of property names and values. The following example shows how to format properties, where the name of the property shows how to format properties of that type. For example, the "Boolean" property demonstrates how to format Boolean properties. "properties": { "Boolean": true, "combo box": "combo box value", "hierarchy": ["Level 1 value", "Level 2 value"], "list": ["list value 1", "list value 2"], "number": 14, "password": "password value", "text": "text value" }
	recipients	Yes	Note: required if preconfigured recipients do not exist. Unordered list of User Objects
	callbacks	No	List of Event Update Callback Objects. For more information, see Overriding outbound integrations on a per-event basis.
	priority	No	The priority of the event. Valid values are low, medium, and high. If the priority field is not included, the message is sent with the default priority specified by the form.
	conferences	Yes	Note: This field is required if form includes Conference section. Unordered list of ConferenceBridge Objects Set this value to the name of an existing conference bridge, or leave it null to create a new xMatters-hosted conference bridge. Depending on how the form is configured, it may allow xMatters-hosted conference bridges, externally-hosted conference bridges, or both. To join an externally-hosted conference bridge, use the name of the conference bridge: "conferences": [{"name": "P1M1"}] To create a new xMatters-hosted conference bridge, use null: "conferences": [{"name": null}]
	responses	No	A list of the response options to be displayed for the event. Response options are identified by a Universally Unique Identifier (UUID). For more information about viewing the location of these UUIDs in the xMatters user interface, see Locate identifiers for forms, properties, and other elements in xMatters. "responses": [ "a1b73279-465f-4f18-a44b-47993c3f75b9", "75f789c2-87b2-4c63-91de-ea6e5834e91d" ]
User	targetName	Yes	Unique target name of the recipient (User ID, Group Name, or Dynamic Team Name)
User	devices	No	Devices to target if the recipient is a User
Error	type	Yes	Enum error type: DATA_FORMAT_ERROR DATA_VALIDATION_ERROR UNAUTHORIZED_ACCESS_ERROR INTERNAL_SERVER_ERROR
	message	Yes	General description of error
	details	No	Array of Error Details Objects
Error Details	[JSONPath]	Yes	Custom JSON Path of the argument that caused the problem; for example: $.recipients[0].name
Error Details	[detailmessage]	Yes	Detailed message about the problem with the corresponding JSONPatch
Event Update Callback	See Overriding outbound integrations on a per-event basis.

Working with event update callbacks

xMatters uses outbound integration webhooks to notify web applications and integrations when certain actions occur, such as when an events status changes, a notification is delivered, or a user responds to a notification. Outbound integrations can target integrations that use the Integration Agent or any web application that can be accessed over HTTP/HTTPS. Webhook payloads include the following information:

HTTP/HTTPS: a POST request is sent to the specified URL. The payload contains a JSON object that describes the event.
Integration Agent: Information about the event is sent to the integration defined by the url and ia properties.

Note: Prior to the xMatters TFX release, callbacks were configured on communication plan forms. The TFX release improved and enhanced the callback functionality and incorporated it into the Integration Builder's outbound integrations.

Outbound integrations are defined in the web user interface, but you can override outbound integration webhooks by specifying callbacks to use for the duration of an event during a call to POST trigger. For form properties to be included in callback data, they must still be marked for inclusion in outbound integrations. For more information about including form properties in outbound integrations, see Define form properties.

For information about how your web application can consume the JSON objects included in the HTTP/HTTPS callbacks, see Outbound integration triggers. For information about using the Integration Agent with webhooks, see Outbound integrations to the Integration Agent.

To specify a callback with POST event:

To specify callbacks for an event, include the Events Update Callback object in the request body. The callbacks are used for the duration of the event but are not used by other events created from the same form.
To create an event without callbacks from a form that has defined callbacks, include an empty Event Update Callback in the request body. This removes the callbacks for the duration of the event but does not affect other events created from the same form.

Event Update Callback JSON Object
Object	Properties	Required	Description
Event Update Callback	url	Yes	Callback URL to which event updates can be posted. This can be an HTTP (or HTTPS) URL for callbacks to web applications or an integration service when used with the Integration Agent. Integration service URLs are formatted as "ia://<servicename>", e.g., "ia://myService". Examples: https://mydomain.com/path/to/my/service/event/eventStatusUpdate http://mydomain.com/path/to/my/service/eventd/deliveryStatusUpdate.jsp ia://myService
	type	Yes	The type of action that triggers the callback: status: an event is initiated or the event status changes deliveryStatus: a notification is delivered to a recipient response: a user responds to a notification
	authType	No	The type of authentication is used to authenticate HTTP requests with the remote server. This field is ignored for Integration Agent URLs (e.g., URLs that start with ia://). none: no authentication (default) basic: HTTP Basic Authentication
	authUserName	No	The user name used to authorize HTTP callbacks with basic authentication. Ignored when authType is set to none.
	authPassword	No	The password used to authorize HTTP callbacks with basic authentication. Ignored when authType is set to none.
	iaid	No	This optional property targets a specific Integration Agent by its ID. Ignored by HTTP callbacks. For more information about when to specify this identifier, see Outbound integrations to the Integration Agent.

Example

Request for creating an event:

curl -H "Content-Type: application/json" --user username -X POST -d '{
  "properties": {
    "Building":["Building A", "Building B"], 
    "City":"Victoria",
    "State":"BC",
    "Street Number": 2453, 
    "Is PO Box?": true,   
    "Disaster Category":["Mass Movement", "Earthquake"] 
  },

  "recipients": 
  [
    {"targetName": "bsmith"},
    {"targetName": "Operations"},
    {"targetName": "tsanderson",
     "devices": ["Email", "Voice Phone"]}
  ],
  "conferences": 
  [
    {"name":"P1M1"}
  ],
  "responses":
  [
    "a1b73279-465f-4f18-a44b-47993c3f75b9",
    "75f789c2-87b2-4c63-91de-ea6e5834e91d"
  ],

  "priority": "high",
  "callbacks": 
  [

    {
      "url":"https://mydomain.com/path/to/my/service/event/status",
      "type":"status",
      "authType":"basic",
      "authUserName":"mmcbride",
      "authPassword":"password123"
    },
    {                  
      "url":"http://mydomain.com/path/to/my/service/event/deliveryStatus",
      "type":"deliveryStatus"
    },

    {        
      "url":"ia://myagentID", 
      "iaid":"lugh-ia-512" 
      "type":"response",
   
    }
  ]
}' "https://acme.na1.xmatters.com/reapi/2014-06-01/engines/forms/e5de7dd5-9170-48b0-abd7-14aa824848c8/triggers"

Response for creating an event:

Success

{
  "id":"1234"
}

Failure

{
  "type":"DATA_VALIDATION_ERROR",  
  "message": "There are validation errors in the form",
  "details":
  [
    {"$.recipients[0].devices[1]":"Value provided not found in the configured values: Email, Work Phone"},
    {"$.properties[0]":"Required field"}
  ]
}

Request for creating an event with preconfigured recipients

Specifying the recipients property is optional for forms that have preconfigured recipients.

You can use preconfigured recipients by omitting the recipients property from the request body. The following example uses the preconfigured recipients:

curl -H "Content-Type: application/json" --user username -X POST -d '{}'"https://acme.na1.xmatters.com/reapi/2014-06-01/engines/forms/e5de7dd5-9170-48b0-abd7-14aa824848c8/triggers"

The next example overwrites the preconfigured recipients with the recipient bsmith:

curl -H "Content-Type: application/json" --user admin2:complex2 -X POST -d ' 
{
  "recipients": 
  [
    {"targetName": "bsmith"}
  ]
}'"https://acme.na1.xmatters.com/reapi/2014-06-01/engines/forms/e5de7dd5-9170-48b0-abd7-14aa824848c8/triggers"

POST feed (deprecated)

This method has been deprecated and replaced with Create a subscription in the xMatters REST API.

This method enables you to create a new subscription (feed) to an existing subscription form (feed form). You can view your subscriptions in the user interface by clicking your user name and then clicking Subscriptions.

To identify the subscription form and the properties you want to subscribe to, you need to locate their UUIDs (Universally Unique Identifiers), which are visible in the xMatters user interface. For more information about locating UUIDs in the xMatters user interface, see Locate identifiers for forms, properties, and other elements in xMatters.

To access this REST API resource, the authenticating user must be a Company Administrator or have the permission to access the subscription form.

The terminology around subscriptions is currently evolving. Subscriptions may be referred to as feeds, and subscription forms may be referred to as feed forms.

Specification
HTTP Method	POST
HTTP headers	Content-Type : application/json
URL	https://<company>.<deployment>.xmatters.com/reapi/2015-01-01/feeds
Parameters	None
Data	Form object
HTTP Response codes	201 Returned if the subscription is successfully created. 400 Returned if there is a validation error in the input. 401 Returned if the user is not authenticated. 403 Returned if the user does not have permission to access the service, with the response header describing the details of the error. 404 Returned if the requested subscription form is not found. 500 Returned if the operation failed for any other reason.
Supported API Versions	2013-12-01, 2014-06-01, 2015-01-01

JSON objects

Form Object

The Form object describes the subscription that is being created.

formUuid	Required	The UUID of the subscription form. For more information about locating this UUID, see Locate identifiers for forms, properties, and other elements in xMatters.
name	Required	The name of the subscription that you are creating.
description	Optional	The description of the subscription that you are creating. This description may be up to 200 characters.
owner	Optional	The owner of the subscription. If this value is omitted, the owner is set to the user who created the subscription.
devices	Optional if already specified	The device filter for the subscription. If this value is omitted, the subscription uses the device filter defined by the subscription form. If the subscription form does not contain a device filter, this value is required.
subscriptions	Optional	An array of Subscription objects. Subscription objects can be Device, Person, Group or Dynamic Team. See the Subscription Object section for details.
properties	Required	An array of the matching properties that you want to subscribe to. You must specify at least one property. See the Property Object section for details.
notificationDelay	Optional	The notification delay in minutes. If this value is not specified, the notification delay is set to the subscription form's default value.

Subscription Object

The subscription object defines who is subscribing to this subscription.

targetName

Required

The target name of the Person, Group or Dynamic Team that is subscribing to the event. For devices, specify the targetName in the format targetName|deviceName, e.g., admin|Home Email.

Property Object

The property object defines the matching criteria for a subscription. When an event occurs that has matching properties the subscribers are notified of the event. For example, you can subscribe to be notified about events where the EOC Activated property value is TRUE.

uuid	Required	The UUID of the property you want to subscribe to. For more information about locating the UUID of a property, see Locate identifiers for forms, properties, and other elements in xMatters.
operator	Required	The operator that is used to subscribe to the property. Available operators include CONTAINS, ENDS_WITH, STARTS_WITH, MATCHES, IS_ONE_OF, IS_ONE_OR_MORE_OF, IS_ONE_TYPE_OF, IS. The operators that you can use with a property depend on the type of the property. For example, you can use the IS operator with a Boolean property but it does not make sense to use STARTS_WITH with a Boolean property. See Available Operators by Property Type to view which operators can be used with each type of property.
value	Required for certain property types	The matching property value. Use this field to specify the values of Boolean, Number, Password and Text properties. Boolean properties must be one of TRUE, FALSE or TRUE_OR_FALSE.
values	Required for certain property types	The matching property values. Use this field to specify the values of Combo Box, List and Hierarchy properties. For Hierarchy properties, specify the path from the root to the leaf using the delimiter '->. For example, use USA -> California to specify the USA and California in a 2-level heirarchy.

Available Operators by Property Type

The following table shows the operators that you can use with each property type.

Boolean	IS
Number	CONTAINS, STARTS_WITH, ENDS_WITH, MATCHES
Password	CONTAINS, STARTS_WITH, ENDS_WITH, MATCHES
Text	CONTAINS, STARTS_WITH, ENDS_WITH, MATCHES
Combo	IS_ONE_OF, CONTAINS, STARTS_WITH, ENDS_WITH
List	IS_ONE_OR_MORE_OF, CONTAINS, STARTS_WITH, ENDS_WITH
Hierarchy	IS_ONE_TYPE_OF, IS_ONE_OR_MORE_OF, CONTAINS, STARTS_WITH, ENDS_WITH, MATCHES

Example Request

The following example creates a new subscription based off the subscription form identified by the UUID aac31350-e625-7433-6247-474ec0e17eb5.

curl -H "Content-Type: application/json" --user username -X POST -d \
'{
"formUuid": "96234526-9498-4b71-a3ce-4e20877b7835",

  "name": "Fire alarm",
  "description": "fire alert",
  "subscriptions": [
    {"targetName": "admin|Work Email"},
    {"targetName": "admin|Home Phone"},
    {"targetName": "Fire Department"}
  ],
  "properties": [
  {
    "uuid": "a6101dc6-09d8-41c5-bedc-84b75455632e",
    "operator": "IS",
    "value": "TRUE_OR_FALSE"
  },
  {
    "uuid": "b9c231c4-abdf-48bc-951f-4f4738d376d6",
    "operator": "IS_ONE_OF",
    "values": ["Value A", "Value B"]
  },
  {
    "uuid": "0aaa6e49-d7d6-4430-9a10-c1620201396f",
    "operator": "IS_ONE_OR_MORE_OF",
    "values": ["1", "2", "3"]
  },
  {
    "uuid": "fbad75cf-4084-4e7c-8d9b-08d318922d8c",
    "operator": "IS_ONE_TYPE_OF",
    "values": ["Root A -> Level 2 -> Leaf A"]
  },
  {
    "uuid": "e56f2447-160c-45b9-8005-18b36b78a5d1",
    "operator": "CONTAINS",
    "value": "123"
  },
  {
    "uuid": "349ebf85-693e-495c-a5df-db4003855576",
    "operator": "STARTS_WITH",
    "value": "pass"
  },
  {
    "uuid": "b362f639-faad-4af8-80c7-493bb76aa092",
    "operator": "ENDS_WITH",
    "value": "abc"
  }
  ],
  "devices": [
    "Work Email",
    "SMS Phone"
  ],
  "owner": "admin"
}' \
"https://acme.na1.xmatters.com/reapi/2015-01-01/feeds"

Response Body

The response body contains a link to the new subscription.

Example:

{"href":"/feeds/697a7ff1-3558-4f89-a976-20af10c28e1c"}

GET groups (deprecated)

Returns a list of groups, in sets of up to 100 per response. Groups are returned ordered from oldest to newest. When there are more than 100 groups, use the startAfter parameter to specify the beginning of the next batch of groups.

Specification
HTTP Method	GET
URL Path	https://<company>.<deployment>.xmatters.com/reapi/2015-01-01/groups
Response	200 OK 400 Returned if the passed parameters are not valid, with the JSON response describing the nature of the error 401 Returned if the user is not authenticated. 403 Returned if the user does not have permission to access the service, with the response header describing the details of the error 404 Returned if the requested URL is not found 500 Returned if the operation failed for any reason, with the JSON response describing the nature of the error
Parameters	startAfter (optional): Used for pagination, this value represents the ID of the last returned group and is set in the nextRecordsUrl parameter of the returned JSON.
Supported API Versions	2014-06-01, 2015-01-01

Example Request

curl --user username "https://acme.na1.xmatters.com/reapi/2015-01-01/groups"

Sample Response

A successful response returns a list of group objects that describe each group.

  "total": 231,

  "nextRecordsUrl": "https://acme.na1.xmatters.com/reapi/2015-01-01/groups?startAfter=230183",

  "records":

  [
    {
      "name": "My First Group",
      "description": "My first group's description",
      "active": true,
      "externalKey": null
    },
    {
      "name": "My Second Group",
      "description": "My second group's description",
      "active": false,
      "externalKey": "fa66b7c0-d188-11e3-9c1a-0800200c9a66"
    },
    ...
  ]

GET notifications (deprecated)

Specification
HTTP Method	GET
URL Path	https://<company>.<deployment>.xmatters.com/reapi/2015-01-01/notifications
Response	200 OK returned if no errors with a Notification Object 400 Returned if the date range is not valid 401 Returned if the user is not authenticated. 403 Returned if the user does not have permission to access the service, with the response header describing the details of the error 404 Returned if the server is unavailable 500 Returned if the operation failed for any reason, with the JSON response describing the nature of the error
Parameters	status: (optional) Valid values are any one of ALL, DELIVERED, PENDING, FAILED, or RESPONDED. If unspecified, will return ALL range: (optional) ISO 8601 start/end date range for which to return notifications, where dates cannot be in the future and the start date must be before the end date. If unspecified, will return notifications from the last 15 minutes. Format: yyyy-MM-dd'T'HH:mm:ssZ/yyyy-MM-dd'T'HH:mm:ssZ startAfterNotification: (optional) Used for pagination, this value represents the ID of the last returned notification and is set in the nextRecordsUrl parameter of the returned JSON. Note that if you specify this parameter, only records previous to the ID provided will be returned; for example, if you specify "7890", only records 7889 and prior are returned.
Pagination	The results are paginated.
Supported API Versions	2012-03-01, 2013-12-01, 2014-06-01, 2015-01-01

JSON Object
Properties	Description
total	Total number of records that the query will return. If the query results in more than 100 records, the response will include the nextRecordsUrl, which can be used to retrieve the next page of records.
nextRecordsUrl	URL that can be used to retrieve the next page of records; included in each response that includes 100 records. Note: If the value of total is divisible by 100, the nextRecordsUrl parameter will still be returned, even though there are no further notifications to retrieve. For example, if a query returns exactly 200 records, nextRecordsUrl will be included with both the first 100 and the second 100 notifications retrieved. However, if nextRecordsUrl is used after the 200th record to retrieve further results, an empty list will be returned.
notifications	Notification data including: identifier - Notification ID user lastName targetName firstName incident - Incident identifier deviceName - Device targeted event - Event ID domain - Event Domain created - Date and time the notification was created delivered - Date and time the notification was delivered responded - Date and time the targeted user responded to the notification response - User's response to the notification sender - Username used to send the notification deviceType - Type of device targeted by the notification protocol - Protocol used to send the notification protocolProvider - Protocol provider used to send the notification subscription - Subscription domain that generated the notification (if a subscription generated the notification) subscriptionName - Name of the subscription (if any) that generated the notification

Example Requests

To get notifications from the last 15 minutes:

curl --user username "https://acme.na1.xmatters.com/reapi/2015-01-01/notifications"

To get failed notifications from Nov. 12, 2013 to Nov. 25th 2013:

curl --user username "https://acme.na1.xmatters.comreapi/2015-01-01/notifications?range=2013-11-12T14:45:48.011/2013-11-24T15:00:48.011&status=failed"

Example Response

  "total": "112",

  "nextRecordsUrl":"/reapi/2015-01-01/notifications?status=ALL&range=2013-03-12T14:45:48.011/2013-03-12T15:00:48.011&startAfterNotification=242010",

  "notifications": [

    "identifier": 242037,

    "user": {

      "lastName": "Smith",

      "targetName": "bsmith",

      "firstName": "Bob"

},

    "incident": "WEB_MESSAGE_1363125608316",

    "deviceName": "Home Email",

    "event": 243000,

    "domain": "messaging",

    "created": "2013-03-12T15:00:17-0700",

    "delivered": "2013-03-12T15:00:19-0700",

    "responded": "",

    "response": "",

    "sender": "admin",

    "deviceType": "Email",

    "protocol": "VDEVICE",

    "protocolProvider": "MY_VDEVICE_PROVIDER",

    "subscription": "",

    "subscriptionName": ""

},

     "identifier": 242036,

     "user": {

       "lastName": "Smith",

       "targetName": "bsmith",

       "firstName": "Bob"

},

     "incident": "WEB_MESSAGE_1363125608316",

     "deviceName": "Pager",

     "event": 243000,

     "domain": "messaging",

     "created": "2013-03-12T15:00:17-0700",

     "delivered": "2013-03-12T15:00:17-0700",

     "responded": "",

     "response": "",

     "sender": "admin",

     "deviceType": "Text Pager",

     "protocol": "VDEVICE",

     "protocolProvider": "MY_VDEVICE_PROVIDER",

     "subscription": "",

     "subscriptionName": ""

},

...

]}

GET person (deprecated)

This method has been deprecated and replaced with Get a person in the new xMatters REST API. For information about using the new xMatters REST API, see xMatters REST API.

Returns details for the targeted xMatters person ID (which can then be used to synchronize with third-party systems).

You can specify a person by using their user ID or by using a unique identifier. Unique identifiers do not change when the user ID of the person changes. To locate the unique identifier for a person, see Locate the identifier for a person.

Specification
HTTP Method	GET
URL Path	https://<company>.<deployment>.xmatters.com/reapi/2015-04-01/<uuid> https://<company>.<deployment>.xmatters.com/reapi/2015-04-01/people?targetName=<userID>
Response	200 OK 401 Returned if the user is not authenticated. 403 Returned if the user does not have permission to access the service, with the response header describing the details of the error 404 Returned if the requested person is not found 500 Returned if the operation failed for any reason, with the JSON response describing the nature of the error
Parameters	None
Supported API Versions	Supported in 2015-04-01 Returns both targetName and shortName. Deprecated in 2012-03-01, 2013-12-01, 2014-06-01, 2015-01-01 As of version 2015-04-01, the returned JSON object uses UUIDs to identify the user in the "identifier" field and returns the user ID in the "targetName" field instead of the "shortName" field, which as been removed. As of version 2014-06-01 the returned JSON object contains a UUID in the "identifier" field instead of a name. A new field, "shortName" has been added to return the name. As of xMatters 5.5.56, all responses include the new field "shortName" for all versions of the API. The shortName field is not included in responses from the 2012-03-01 and 2013-12-01 APIs run against xMatters prior to xMatters 5.5.56.

Example Request (xMatters 5.5.70 and later, using API version 2015-04-01 and later)

curl --user username "https://acme.na1.
xmatters.com/reapi/2015-04-01/people/481086d8-357a-4279-b7d5-d7dce48fcd12"

curl --user username "https://acme.na1.
xmatters.com/reapi/2015-04-01/people?targetName=bsmith"

Sample Response(xMatters 5.5.70 and later, using API version 2015-04-01and later)

{
"identifier": "c04d43ef-2153-41de-b3f9-1be359509681",

  "shortName": "bsmith",
"targetName": "bsmith",
  "firstName": "Bob",
  "lastName": "Smith",
  "status": "active",
  "language": "en",
  "timezone": "US/Pacific",
  "externallyOwned", "false",

  "externalKey": null,
  "webLogin", "bsmith",
  "phoneLogin", "30105",
  "site": { "name": "Headquarters", "href": "/reapi/2015-04-01/sites/1017c0a1282-f1d7-429e-8a9c-1caea9fbae2c" },
  "profiles": { "href": "/reapi/2015-04-01/people/c04d43ef-2153-41de-b3f9-1be359509681/profiles" }
}

Deprecated versions

Example Request (xMatters 5.5.56 to 5.5.69, using API version 2014-06-01 and 2015-01-01)

curl --user username "https://acme.na1.
xmatters.com/reapi/2015-01-01/people/bsmith"

Sample Response (xMatters 5.5.56 to 5.5.69, using API version 2014-06-01 and and 2015-01-01)

As of xMatters 5.5.56, the identifier field returns a UUID, and the name is returned in the "shortName" field.

{
  "identifier": "481086d8-357a-4279-b7d5-d7dce48fcd12"

  "shortName": "bsmith"

  "firstName": "Bob",
  "lastName": "Smith",
  "status": "active",
  "language": "en",
  "timezone": "US/Pacific",
  "externallyOwned": false,
  "webLogin", "bsmith",
  "phoneLogin": "1234",
  "site": 
  { 
    "name": "Headquarters",     
    "href":"/reapi/2015-01-01/sites/101" 
  },
  "profiles": 
  {
    "href":"/reapi/2015-01-01/people/bsmith/profiles" 
  }
}

Example Request (xMatters 5.5.56 and later, using API version 2012-03-01 or 2013-12-01)

curl --user username "https://acme.na1.
xmatters.com/reapi/2013-12-01/people/bsmith"

Sample Response xMatters5.5.56 and later, using API version 2012-03-01 or 2013-12-01)

Responses from xMatters 5.5.56 and later include the "shortName" field.

{
  "identifier": "bsmith"

  "shortName": "bsmith"

  "firstName": "Bob",
  "lastName": "Smith",
  "status": "active",
  "language": "en",
  "timezone": "US/Pacific",
  "externallyOwned": false,
  "webLogin", "bsmith",
  "phoneLogin": "1234",
  "site": 
  { 
    "name": "Headquarters",     
    "href":"/reapi/2013-12-01/sites/101" 
  },
  "profiles": 
  {
    "href":"/reapi/2013-12-01/people/bsmith/profiles" 
  }
}

Sample Response (xMatters 5.5.55 and earlier, using API version 2012-03-01 or 2013-12-01)

Responses from xMattersxMatters 5.5.55 and earlier do not include the "shortName" field.

{
  "identifier": "bsmith",
  "firstName": "Bob",
  "lastName": "Smith",
  "status": "active",
  "language": "en",
  "timezone": "US/Pacific",
  "externallyOwned": false,
  "webLogin", "bsmith",
  "phoneLogin": "1234",
  "site": 
  { 
    "name": "Headquarters",     
    "href":"/reapi/2013-12-01/sites/101" 
  },
  "profiles": 
  {
    "href":"/reapi/2013-12-01/people/bsmith/profiles" 
  }
}

POST person (deprecated)

This method has been deprecated and replaced with Create a person and Modify a person in the new xMatters REST API. For information about using the new xMatters REST API, see xMatters REST API.

Adds a new user to xMatters.

Required permissions

To access this REST API resource, the authenticating user must have the view.menu.Users permission assigned to one of their roles. To configure the supervisors of the new user, the authenticating user must have permission to access the supervisors in xMatters. Supervisors must also have the view.menu.Users permission.

Specification
HTTP Method	POST
URL Path	https://<company>.<deployment>.xmatters.com/reapi/2015-04-01/people
Response	201 Returned if the user was created successfully 400 Returned if there is a formatting error in the JSON object or it contains invalid data, or the user already exists. 401 Returned if the user is not authenticated. 403 Returned if the user does not have permission to access the service, with the response header describing the details of the error 404 Returned if the requested URL is not found 500 Returned if the operation failed for any reason, with the JSON response describing the nature of the error
Parameters	None
Supported API Versions	2015-04-01

JSON Objects
Object	Properties	Required	Description
Person	targetName	yes	The user ID of the user. This value must be unique within the company. Example: "targetName": "bsmith"
	firstName	yes	The first name of the user. Example: "firstName": "Bob"
	lastName	yes	The last name of the user. Example: "lastName": "Smith"
	status	no	The status of the user. Valid values include "active" and "inactive". If this value is not provided, it defaults to "active". Example: "status": "active"
	language	no	The user's language. This two-letter language code must already be active for the company. If this value is not provided, the user's language is set to the default company language. Example: "language": "en"
	timezone	no	The user's timezone. If this value is not provided, the user's timezone is set to the default company timezone. Example: "timezone": "US/Pacific"
	externallyOwned	yes	A Boolean value (true or false) that denotes whether the user was added to xMatters through a data synchronization process. Externally owned users are managed by an external system and are not generally updated or deleted through the user interface or the REST API. If your system does not using a data synchronization process, set this value to false. Example: "externallyOwned": false
	webLogin	no	The web login ID of the user. This value must be unique within the company. This is the user name that the user can use to log in to the web user interface. If not provided, this value is set to be the same as the targetName. Example: "webLogin": "bsmith"
	phoneLogin	no	The phone login ID of the user. This value must be unique within the company. This values is a string that may contain only digits. If this value is not provided, xMatters does not generate a phone login ID for the user. Example: "phoneLogin": "1234"
	roles	yes	A list of Role objects that define the user's roles. Each user must have at least one role. Example: "roles": [ { "id": "4c5be5ab-eb4d-44cd-baec-5fed0a20dceb" }, { "id": "74fe76c8-26e1-4740-9203-5486118affb8" } ]
	site	no	A Site object that defines the site the user belongs to. Example: "site": { "id": "0e840a35-f27b-400e-ab03-f29ca447c8df" }
	supervisors	no	A list of Supervisor objects that define the user's supervisors. Supervisors must have permission to supervise users; they require the view.menu.Users permission to be assigned to one of their roles. If this list is not provided, the user's supervisor is set to be the authenticated user that is making this REST API call. Example: "supervisors": [ { "id": "198503bf-a567-4807-b66c-320c5976c07c" }, { "id": "c5760a6d-d036-4631-a86e-a9e39cc2ff0e" } ]
Role	id	yes	A unique identifier that defines a role. Example: "id": "c5760a6d-d036-4631-a86e-a9e39cc2ff0e"
Site	id	yes	A unique identifier that defines a site. For more information about locating UUIDs for sites, see Locate the identifier for a site. Example: "id": "0e840a35-f27b-400e-ab03-f29ca447c8df"
Supervisor	id	yes	A unique identifier that defines another user. For more information about locating UUIDs for users, see Locate the identifier for a person. Example: "id": "c5760a6d-d036-4631-a86e-a9e39cc2ff0e"

Example Request

curl -H "Content-Type: application/json" --user apidev -X POST -D
'{
  "targetName": "bsmith",
  "firstName": "Bob",
  "lastName": "Smith",
  "status": "active",
  "language": "en",
  "timezone": "US/Pacific",
  "externallyOwned": false,
  "webLogin": "bsmith",
  "phoneLogin": "1234",
  "roles": [
    { "id": "4c5be5ab-eb4d-44cd-baec-5fed0a20dceb" },
    { "id": "74fe76c8-26e1-4740-9203-5486118affb8" }
  ],
  "site": { "id": "0e840a35-f27b-400e-ab03-f29ca447c8df" },
  "supervisors": [
    { "id": "198503bf-a567-4807-b66c-320c5976c07c" },
    { "id": "c5760a6d-d036-4631-a86e-a9e39cc2ff0e" }
  ]
}'
"https://acme.na1.xmatters.com/reapi/2015-04-01/people"

Example Responses

Successful Response:

{
"id": "1d8cf49b-cc8d-468f-a238-cf9f7af274ac"
}

Unsuccessful Response:

{
"type": "DATA_VALIDATION_ERROR",

  "message": "There are data validation errors in the form.",
"errorDetails":
  [
   {
     "jsonPath":"person/targetName"
      "details": "Target name bsmith already exists."
    },
    {
      "jsonPath":"person/webLogin"
      "details": "Web login bsmith already exists."
    }
  ]
}

PUT property values (deprecated)

Modifies the Values field of existing combo box, list, and hierarchical properties. Use this method to change the choices displayed in combo box, list, and hierarchy properties when message senders complete a form.

To use this method, you must make the REST API call with a user account that has permission to modify workflow properties. More specifically, the user account used to authenticate the REST call requires the ability.act.EditProperty permission assigned to one of its roles.

Properties are identified by a Universally Unique Identifier (UUID), which is visible in the xMatters user interface. For more information about locating UUIDs in the xMatters user interface, see Locate identifiers for forms, properties, and other elements in xMatters.

Specification
HTTP Method	PUT
URL Path	https://<company>.<deployment>.xmatters.com/reapi/2015-01-01/properties/<property UUID>/values
Response	200 OK 204 No content returned if the property values are successfully updated 400 Bad Request returned if malformed or event not found 401 Returned if the user is not authenticated. 403 Returned if the user does not have permission to access the service, with the response header describing the details of the error 404 Returned if the requested property is not found 413 Request entity too large returned if the request has more entries than the maximum allowed. (10,000) 500 Returned if the operation failed for any reason, with the JSON response describing the nature of the error
Parameters	None
Supported API Versions	2014-06-01, 2015-01-01

List and combo box properties

Use a comma-separated list of strings to define the choices that are displayed in list and combo box properties. Enclose each item in double quotes and use an asterisk to denote the default value. List items can have more than one default value; combo box properties have one default value. The following JSON object defines a set of list values and sets the default value to None:

["Shelter", "Evacuate", "Avoid area", "None*"]

Hierarchy properties

Use a JSON object to define the hierarchy property. The JSON object defines a list of child nodes for each parent value.

JSON Hierarchy Property Object
Properties	Required	Description
name	required	Value of the hierarchy item. This value is displayed as a choice to message senders.
isDefault	optional	Set to true if this is the default value, false otherwise.
childNodes	optional	A recursive list of the children of this value, enclosed in square brackets and separated by commas. Child nodes may use the isDefault property to define default values, and the childNodes property to define their own child nodes. The following example shows how to define three child nodes. "childNodes": [{"name": "San Fransisco"}, {"name": "Los Angeles"}, {"name": "San Diego", "isDefault": true}]

Example hierarchy property

Consider the case where you want to configure a hierarchy property to contain the following countries, states, and cities:

Canada
USA
    California
        San Francisco
        Los Angeles
        San Diego
   Oregon
    Washington

You can use the following JSON object to define the hierarchy described above:

[
  {"name": "Canada"},
  {"name": "USA", "isDefault": false, "childNodes":
     [{"name": "California", "childNodes": [
        {"name": "San Fransisco"},
        {"name": "Los Angeles"},
        {"name": "San Diego"}]},
     {"name": "Washington"},
     {"name": "Oregon"}]
  }
]

Example Requests

Set the properties of a list or combo box.

curl -H "Content-Type: application/json" --user username -X PUT -d '["Shelter", "Evacuate", "Avoid area", "None*"]' "https://myco.na1.xmatters.com/reapi/2015-01-01/properties/b9c431c4-abdf-98bc-951f-4f4738c376d6/values

Set the properties of hierarchical data.

curl -H "Content-Type: application/json" --user username -X PUT -d '[{"name": "Canada"}, {"name": "USA", "isDefault":true, "childNodes": [{"name": "California", "childNodes":[{"name": "San Fransisco"}, {"name": "Los Angeles"}, {"name": "San Diego"}]}]}]' "http://myco.na1.xmatters.com/reapi/2015-01-01/properties/1cf7a10a-89d0-482d-a2c0-522af5b70fb6/values"

Response Body

None if successful.

GET site (deprecated)

This method has been deprecated and replaced with Get a site in the new xMatters REST API. For information about using the new xMatters REST API, see xMatters REST API.

Returns information for a specific site based on its unique identifier. You can locate the unique identifier of a site in the user interface, or you can retrieve it with the GET sites method. For more information about locating the unique identifier for a site in the user interface, see Locate the identifier for a site.

Specification
HTTP Method	GET
URL Path	https://<company>.<deployment>.xmatters.com/reapi/2015-04-01/sites/<site_uuid>
Response	200 OK 401 Returned if the user is not authenticated. 403 Returned if the user does not have permission to access the service, with the response header describing the details of the error 404 Returned if the requested URL is not found 500 Returned if the operation failed for any reason, with the JSON response describing the nature of the error
Parameters	None
Supported API Versions	2015-04-01 Deprecated: 2012-03-01, 2013-12-01, 2014-06-01, 2015-01-01

Example Request

curl --user username "https://acme.na1.xmatters.com/reapi/2015-04-01/sites/84457abd-9c64-468b-b0f5-37bbd448088c""

Sample Response

A successful response returns a JSON Site object that describes the site.

{
  "identifier": "84457abd-9c64-468b-b0f5-37bbd448088c",
  "name": "Retail Store 1",
  "status": "ACTIVE",
  "language": "English",
  "timezone": "US/Pacific",
  "address1": "12647 Alcosta Blvd",
  "address2": "",
  "city": "San Ramon",
  "state": "California",
  "country": "United States",
  "postalCode": "94583",       
  "latitude": "37.773085",
  "longitude": "-121.959379"
}

Deprecated versions

Example Request (2015-01-01 and earlier)

curl --user username "https://acme.na1.xmatters.com/reapi/2015-01-01/sites/2038103"

Sample Response (2015-01-01 and earlier)

A successful response returns a JSON Site object that describes the site.

{
  "identifier": "2038103",
  "name": "Retail Store 1",
  "status": "ACTIVE",
  "language": "English",
  "timezone": "US/Pacific",
  "address1": "12647 Alcosta Blvd",
  "address2": "",
  "city": "San Ramon",
  "state": "California",
  "country": "United States",
  "postalCode": "94583",       
  "latitude": "37.773085",
  "longitude": "-121.959379"
}

GET sites (deprecated)

Returns a list of sites in paginated groups of up to 100 per response. Each site contains a unique identifier in the "identifier" field. You can later use this identifier with the GET site and POST site methods to identify the site. To learn how you can locate this identifier in the user interface, see Locate the identifier for a site.

Specification
HTTP Method	GET
URL Path	https://<company>.<deployment>.xmatters.com/reapi/2015-04-01/sites
Response	200 OK 401 Returned if the user is not authenticated. 403 Returned if the user does not have permission to access the service, with the response header describing the details of the error 404 Returned if the requested URL is not found 500 Returned if the operation failed for any reason, with the JSON response describing the nature of the error
Parameters	name (optional): If specified, this parameter limits the returned list to Sites that exactly match the parameter (matching is case-insensitive). For example, if name=UK, possible results might include uK, UK, Uk, and uk. You can also use an asterisk for wildcard searches (e.g., UK_, east). For example, if name=UK, then the returned Sites list might include "UK London", "UK Manchester", etc. startAfterSite (optional):* Used for pagination, this value represents the ID of the last returned site and is set in the nextRecordsUrl parameter of the returned JSON. Note that if you specify this parameter, only records previous to the ID provided will be returned; for example, if you specify "7890", only records 7889 and prior are returned. Also, the returned JSON "total" value will display an empty string ("").
Pagination	The results are paginated.
Supported API Versions	2015-04-01 Deprecated: 2012-03-01, 2013-12-01, 2014-06-01, 2015-01-01

JSON Object
Properties	Description
total	Total number of records that the query will return. If the query results in more than 100 records, the response will include the nextRecordsUrl, which can be used to retrieve the next page of records.
nextRecordsUrl	URL that can be used to retrieve the next page of records; included in each response that includes 100 records. Note: If the value of total is divisible by 100, the nextRecordsUrl parameter will still be returned, even though there are no further notifications to retrieve. For example, if a query returns exactly 200 records, nextRecordsUrl will be included with both the first 100 and the second 100 notifications retrieved. However, if nextRecordsUrl is used after the 200th record to retrieve further results, an empty list will be returned.
site	Site data including: identifier: System-generated unique identifier for a Site (read-only) name: User-defined Site identifier; must be unique within the xMatters Company (100 character maximum) status: ACTIVE or INACTIVE language: Default Site language inherited by Users when they are created (other functions TBD); e.g., English, French, Italian. Language must be defined in the target Company. timezone: Default Site timezone inherited by Users and Groups when they are created (other functions TBD); e.g., US/Pacific, Europe/Amsterdam. Timezone must be defined in the target Company. address1 (optional): First line of Site address; e.g., 925 Fort Street (100 character maximum) address2 (optional): Second line of site address, e.g., Suite 234 (100 character maximum) city (optional): City where Site is located; e.g., San Francisco (100 character maximum) state (optional): State (or similar jurisdiction) where Site is located; e.g., California, British Columbia, Essex (100 character maximum) postalCode (optional): Postal code or zip code of site; e.g., 92042, V8P 1N6 (10 character maximum) latitude (optional): Site latitude used for location-based notifications; e.g., 49.285286 (100 character maximum) longitude (optional): Site longitude used for location-based notifications; e.g., -123.1158393 (100 character maximum)

Example request (2015-04-01 and later)

curl --user username "https://acme.na1.
xmatters.com/reapi/2015-04-01/sites/?name=retail"

Example response (2015-04-01 and later)

{
  "total": "112", 
						 "nextRecordsUrl": "/reapi/2015-04-01/sites/?name=retail&startAfterSite=7c0a1282-f1d7-429e-8a9c-1caea9fbae2c", 
						 "sites": [
						{
						"identifier": "cd6f6ac6-a03d-461f-a472-c9550859bddd",
						"name": "Retail Store 1",
						"status": "ACTIVE",
						"language": "English",
						"timezone": "US/Pacific",
						"address1": "12647 Alcosta Blvd",
						"address2": "",
						"city": "San Ramon",
						"state": "California",
						"country": "United States",
						"postalCode": "94583",       
						"latitude": "",
						"longitude": ""
						}, 
						{
						"identifier": "6f4fdac4-6c49-4fb0-a60a-071bcbbe2faa",
						"name": "Retail Store 2",
						"status": "INACTIVE",
						"language": "English",
						"timezone": "US/Pacific",
						"address1": "12647 Alcosta Blvd",
						"address2": "",
						"city": "Pleasanton",
						"state": "California",
						"country": "United States",
						"postalCode": "94566",       
						"latitude": "",
						"longitude": ""
						},
						...
					]}

Deprecated versions

Example Request (2015-01-01 and earlier)

curl --user username "https://acme.na1.
xmatters.com/reapi/2015-01-01/sites/?name=retail"

Sample Response (2015-01-01 and earlier)

{
  "total": "112", 
						 "nextRecordsUrl": "/reapi/2015-01-01/sites/?name=retail&startAfterSite=2038104", 
						 "sites": [
						{
						"identifier": "2038103",
						"name": "Retail Store 1",
						"status": "ACTIVE",
						"language": "English",
						"timezone": "US/Pacific",
						"address1": "12647 Alcosta Blvd",
						"address2": "",
						"city": "San Ramon",
						"state": "California",
						"country": "United States",
						"postalCode": "94583",       
						"latitude": "",
						"longitude": ""
						}, 
						{
						"identifier": "2038104",
						"name": "Retail Store 2",
						"status": "INACTIVE",
						"language": "English",
						"timezone": "US/Pacific",,
						"address1": "12647 Alcosta Blvd",
						"address2": "",
						"city": "Pleasanton",
						"state": "California",
						"country": "United States",
						"postalCode": "94566",       
						"latitude": "",
						"longitude": ""
						},
						...
					]}

POST site (deprecated)

Creates a new site or updates an existing site.

To create a new site, make a POST request to /sites and include a Site object in the request body. A new site is created with the properties defined by the Site object. Responses to site creation requests return a JSON object that includes the ID of the newly created site.

To update an existing site, make a POST request to /sites/<site_uuid>, where <site_uuid> is the unique identifier of the site you want to update, and include a Site object in the request body. The site is updated with the properties defined in the Site object. Site properties that are not included in the Site object are not modified. Responses to site update requests return a Site object that contains the details of the updated site.

The unique identifier for a site is included in the response of the GET sites method and is displayed in the xMatters web user interface. For more information about locating this identifier in the user interface, see Locate the identifier for a site.

Specification
HTTP Method	POST
HTTP headers	Content-Type : application/json
URL	To create a site: https://<company>.<deployment>.xmatters.com/reapi/2015-04-01/sites To modify a site: https://<company>.<deployment>.xmatters.com/reapi/2015-04-01/sites/<site_uuid>
Parameters	None.
Data	JSON site object. For more information, see the "JSON Site Object" table below.
HTTP Response codes	200 OK 401 Returned if the user is not authenticated. 403 Returned if the user does not have permission to access the service, with the response header describing the details of the error. 500 Returned if the operation failed for any reason, with the JSON response describing the nature of the error.
Supported API Versions	2015-04-01 Deprecated: 2013-12-01, 2014-06-01,2015-01-01

JSON Site Object
Properties	Required	Description
identifier	(read-only)	System-generated unique numeric identifier for a site.
name	required (for site creation) optional (for site modification)	The name of the site. This name must be unique within the Company (100 character maximum). This field is required when you create a new site. If you include this value when you modify a site, the site is renamed.
status	optional	Status of the company. Must be one of "ACTIVE" or "INACTIVE". If omitted, defaults to "ACTIVE".
language	optional	Default site language inherited by users when they are created. The language must be defined in the target company.
timezone	optional	Default site timezone inherited by users and groups when they are created. The timezone must be defined in the target company.
address1	optional	First line of site address (100 character maximum).
address2	optional	Second line of site address (100 character maximum).
city	optional	City where site is located (100 character maximum).
state	optional	State (or similar jurisdiction) where site is located (100 character maximum).
country	optional	Country where the site is located.
postalCode	optional	Postal code or zip code of site (10 character maximum).
latitude	optional	Site latitude used for location-based notifications (100 character maximum). Values must be between -90 and 90.
longitude	optional	Site longitude used for location-based notifications (100 character maximum). Values must be between -180 and 180.

Example - create a new site

Example Request - Create a new site:

curl -H "Content-Type: application/json" --user  username -X POST -d ' 
						{ 
  "name": "Retail Store 1", 
  "status": "ACTIVE",
  "language": "English",
  "timezone": "US/Pacific",
  "address1": "12647 Alcosta Blvd",
  "address2": "Suite 245",
  "city": "San Ramon",
  "state": "California",
  "country": "United States",
  "postalCode": "94583",
  "latitude": "37.773085",
  "longitude": "-121.959379"
}'
"https://acme.na1.xmatters.com/reapi/2015-04-01/sites"

Example Response (successful 2015-04-01)

{
						"uuid": "29ecfda1-f4f8-4417-a04a-13640dc10102"
					}

Example Response (failure)

					{
  "type":"DATA_VALIDATION_ERROR",
  "message": "There are validation errors in the form.",
  "errorDetails":[{
    "jsonPath": "sites/name",
    "details": "Name already in use"
  }]
}

Example - update a site

Example Request - Update a site

This example updates the address of the site "Retail Store 1". The UUID for this site is 0fb68702-9476-4e77-8cb8-9a961ff8ffb1. For more information about locating the UUID of a site, see Locate the identifier for a site.

curl -H "Content-Type: application/json" --user  username -X POST -d ' 
					{ 
  "address1": ""2226 Camino Ramon",
  "address2": "",
  "city": "San Ramon",
  "state": "California",
  "country": "United States",
  "postalCode": "94583",
  "latitude": "37.77628",
  "longitude": "-121.967892"
}'
"https://acme.na1.xmatters.com/reapi/2015-04-01/sites/0fb68702-9476-4e77-8cb8-9a961ff8ffb1"

Example Request - Rename a site

This example renames the site "Retail Store 1" to "Head Office".

curl -H "Content-Type: application/json" --user  username -X POST -d ' 
					{ 
  "name": "Head Office"
}'
"https://acme.na1.xmatters.com/reapi/2015-04-01/sites/0fb68702-9476-4e77-8cb8-9a961ff8ffb1"

Deprecated versions

Example Request - Update a site (2015-01-01 and earlier)

This example updates the address of the site "Retail Store 1".

curl -H "Content-Type: application/json" --user  username -X POST -d ' 
					{ 
  "address1": ""2226 Camino Ramon",
  "address2": "",
  "city": "San Ramon",
  "state": "California",
  "country": "United States",
  "postalCode": "94583",
  "latitude": "37.77628",
  "longitude": "-121.967892"
}'
"https://acme.na1.xmatters.com/reapi/2015-01-01/sites/Retail%20Store%201"

Example Request - Rename a site (2015-01-01 and earlier)

This example renames the site "Retail Store 1" to "Head Office".

curl -H "Content-Type: application/json" --user  username -X POST -d ' 
					{ 
  "name": "Head Office"
}'
"https://acme.na1.xmatters.com/reapi/2015-01-01/sites/Retail%20Store%201"

Once the site has been renamed, the URL for site modification becomes https://acme.na1.xmatters.com/reapi/2015-01-01/sites/Head%20Office.

POST trigger (deprecated)

This method replaces POST event.

Creates a new event and optionally includes response callback URLs (webhooks) that can update third-party systems.

Specification
HTTP Method	POST
URL Path	https://<company>.<deployment>.xmatters.com/reapi/2015-01-01/forms/<form-uuid>/triggers Replace <company> and <deployment> with the address of your xMatters deployment, and replace <form-uuid> with the identifier of the form to use for the event. For more information about locating form identifiers in the xMatters user interface, see Locate identifiers for forms, properties, and other elements in xMatters.
Request	Trigger Object
Response	200 - OK returned if no errors with an Event Object 400 - Bad Request returned if malformed (e.g., missing required parameters, unsupported syntax, etc.) 401 - Returned if the user is not authenticated 403 - Returned if the user does not have permission to access the service, with the response header describing the details of the error 404 - Returned if the plan or form is not found or not deployed as web service 500 - Returned if the operation failed for any other reason, with the JSON response describing the nature of the error
Supported API Versions	2014-06-01, 2015-01-01

JSON Objects
Object	Properties	Required	Description
Trigger	properties	No	Map of property names and values. The following example shows how to format properties, where the name of the property shows how to format properties of that type. For example, the "Boolean" property demonstrates how to format Boolean properties. "properties": { "Boolean": true, "combo box": "combo box value", "hierarchy": ["Level 1 value", "Level 2 value"], "list": ["list value 1", "list value 2"], "number": 14, "password": "password value", "text": "text value" } Text-based property types support a limited subset of HTML tags. For more information, see HTML in text form properties.
	recipients	Yes	Note: required if preconfigured recipients do not exist. Unordered list of User Objects
	callbacks	No	List of Event Update Callback Objects. For more information, see Overriding outbound integrations on a per-event basis.
	priority	No	The priority of the event. Valid values are low, medium, and high. If the priority field is not included, the message is sent with the default priority specified by the form.
	conferences	Yes for external bridges No for xMatters bridges	Unordered list of conference bridges. Set this value to the name of an existing xMatters or external conference bridge, or leave it empty to create a new xMatters-hosted bridge. Depending on how the form is configured, it may allow xMatters-hosted conference bridges, externally-hosted conference bridges, or both. This section is mandatory when a form is configured to only use external conference bridges. This section is optional when the form is configured to use xMatters-hosted conference bridges or both. To join an existing xMatters-hosted conference bridge, set the conference name to the bridge ID: "conferences": [{"name": "31582159"}] To create a new xMatters-hosted conference bridge, omit the conferences section, or set the conference name to null: "conferences": [{"name": null}] To join an externally-hosted conference bridge, specify the name of the conference bridge: "conferences": [{"name": "P1M1"}] To join an externally-hosted conference bridge that requires you to set the bridge number, specify the name of the conference bridge and the bridge number: "conferences":[ { "name": "P1M1", "bridgeNumber": "3372791" }]
	responses	No	A list of the response options to be displayed for the event. Response options are identified by a Universally Unique Identifier (UUID). For more information about viewing the location of these UUIDs in the xMatters user interface, see Locate identifiers for forms, properties, and other elements in xMatters. "responses": [ "a1b73279-465f-4f18-a44b-47993c3f75b9", "75f789c2-87b2-4c63-91de-ea6e5834e91d" ]
User	targetName	Yes	Unique target name of the recipient (User ID, Group Name, or Dynamic Team Name)
User	devices	No	Devices to target if the recipient is a User
Error	type	Yes	Enum error type: DATA_FORMAT_ERROR DATA_VALIDATION_ERROR UNAUTHORIZED_ACCESS_ERROR INTERNAL_SERVER_ERROR
	message	Yes	General description of error
	details	No	Array of Error Details Objects
Error Details	[JSONPath]	Yes	Custom JSON Path of the argument that caused the problem; for example: $.recipients[0].name
Error Details	[detailmessage]	Yes	Detailed message about the problem with the corresponding JSONPatch
Event Update Callback	See Overriding outbound integrations on a per-event basis.

Overriding outbound integrations on a per-event basis

HTTP/HTTPS: a POST request is sent to the specified URL. The payload contains a JSON object that describes the event.
Integration Agent: Information about the event is sent to the integration defined by the url and ia properties.

To specify a callback with POST triggers:

To specify callbacks for an event, include the Events Update Callback object in the request body. The callbacks are used for the duration of the event but are not used by other events created from the same form.
To create an event without callbacks from a form that has defined callbacks, include an empty Event Update Callback in the request body. This removes the callbacks for the duration of the event but does not affect other events created from the same form.

Event Update Callback JSON Object
Object	Properties	Required	Description
Event Update Callback	url	Yes	Callback URL to which event updates can be posted. This can be an HTTP (or HTTPS) URL for callbacks to web applications or an integration service when used with the Integration Agent. Integration service URLs are formatted as "ia://<servicename>", e.g., "ia://myService". Examples: https://mydomain.com/path/eventStatusUpdate http://mydomain.com/path/deliveryStatusUpdate.jsp ia://myService
	type	Yes	The type of action that triggers the callback: status: an event is initiated or the event status changes deliveryStatus: a notification is delivered to a recipient response: a user responds to a notification
	authType	No	The type of authentication is used to authenticate HTTP requests with the remote server. This field is ignored for Integration Agent URLs (e.g., URLs that start with ia://). none: no authentication (default) basic: HTTP Basic Authentication
	authUserName	No	The user name used to authorize HTTP callbacks with basic authentication. Ignored when authType is set to none.
	authPassword	No	The password used to authorize HTTP callbacks with basic authentication. Ignored when authType is set to none.
	iaid	No	This optional property targets a specific Integration Agent by its ID. Ignored by HTTP callbacks. For more information about when to specify this identifier, see Outbound integrations to the Integration Agent.

Example

Request for creating an event:

curl -H "Content-Type: application/json" --user username -X POST -d '{
  "properties": {
    "Building":["Building A", "Building B"], 
    "City":"Victoria",
    "State":"BC",
    "Street Number": 2453, 
    "Is PO Box?": true,   
    "Disaster Category":["Mass Movement", "Earthquake"] 
  },

  "recipients": 
  [
    {"targetName": "bsmith"},
    {"targetName": "Operations"},
    {"targetName": "tsanderson",
     "devices": ["Email", "Voice Phone"]}
  ],
  "conferences": 
  [
    {"name":"P1M1"}
  ],
  "responses":
  [
    "a1b73279-465f-4f18-a44b-47993c3f75b9",
    "75f789c2-87b2-4c63-91de-ea6e5834e91d"
  ],

  "priority": "high",
  "callbacks": 
  [

    {
      "url":"https://mydomain.com/path/to/my/service/event/status",
      "type":"status",
      "authType":"basic",
      "authUserName":"mmcbride",
      "authPassword":"password123"
    },
    {                  
      "url":"http://mydomain.com/path/to/my/service/event/deliveryStatus",
      "type":"deliveryStatus"
    },

    {        
      "url":"ia://myagentID", 
      "iaid":"lugh-ia-512", 
      "type":"response"
   
    }
  ]
}' "https://acme.na1.xmatters.com/reapi/2015-01-01/engines/forms/e5de7dd5-9170-48b0-abd7-14aa824848c8/triggers"

Response for creating an event:

Success

{
  "id":"1234"
}

Success with fast resolution

When a large number of people are targeted by an event, xMatters ignores certain advanced settings such as schedules, escalations and rotations to ensure that people are notified quickly. If fast resolution is activated for this notification, the response includes the number of recipients in the "numberResolvedPeople" field.

{
  "id":"1234
  "numberResolvedPeople": "1439"
}

Failure

{
  "type":"DATA_VALIDATION_ERROR",  
  "message": "There are validation errors in the form",
  "details":
  [
    {"$.recipients[0].devices[1]":"Value provided not found in the configured values: Email, Work Phone"},
    {"$.properties[0]":"Required field"}
  ]
}

Request for creating an event with preconfigured recipients

Specifying the recipients property is optional for forms that have preconfigured recipients.

You can use preconfigured recipients by omitting the recipients property from the request body. The following example uses the preconfigured recipients:

curl -H "Content-Type: application/json" --user username -X POST -d '{}'"https://acme.na1.xmatters.com/reapi/2015-01-01/engines/forms/e5de7dd5-9170-48b0-abd7-14aa824848c8/triggers"

The next example overwrites the preconfigured recipients with the recipient bsmith:

curl -H "Content-Type: application/json" --user admin2:complex2 -X POST -d ' 
{
  "recipients": 
  [
    {"targetName": "bsmith"}
  ]
}'"https://acme.na1.xmatters.com/reapi/2015-01-01/engines/forms/e5de7dd5-9170-48b0-abd7-14aa824848c8/triggers"