Alerts


Note: currently alerts for clients can only be created where the client is attached to a Xero Organisation.

Overview

URL https://api.xero.com/xero.hq/1.0/Alerts
Methods Supported GET, POST, PUT, DELETE
Description Allows you to retrieve, add, update and delete alerts.

GET Alerts

The following elements are returned in a Alerts response

id The Alert Id
type Classifies the type of data contained in the alert. The Alert Type will define the “template” associated to the alert. See Alert Types
targetType Specifies the target for the alert. See Target Types
targetId The Id based on the targetType to create the alert against i.e. when targetType is CLIENT value will be ClientId. This field is not required when targetType is PRACTICE.
dueAt The date the alert is due to be actioned (timestamp) e.g. 2014-04-14T02:15:15Z
activeDate The date at which the alert should become active i.e. be made visible to the user (timestamp) e.g. 2016-02-14T05:00:00Z. If not supplied will default to the current date and time which will set this alert as active immediately.
access Access object that specifies the users that will see the alert. See access
addtionalData Additional Data object matching the template associated with the specified alert type. See additionalData
actions A collection of Actions Objects. Will contain a link (URL) to the relevant action. See actions
Elements for access
to Indicates that the alert should be assigned to all the users that have access to the TargetId e.g. ALL-USERS
Elements for additionalData
appName Name of your application.
date e.g. 2017-04-05T00:00:00Z
Elements for actions
label The text to display the alert action
link A URL link for the alert action in the partner application

Additional Data

This object is contextual to the type of alert being created. This is used by consuming clients to render the alerts in their user interface.

For example, the template associated to the Alert Type CLIENT_ALERT_TEST is:

Template Field Template Text
Title {appName} has triggered this test alert
Description Generated on {date}

With the additionalData object:

"additionalData": {
  "appName": "Acme Reporting",
  "date": "2017-04-05T00:00:00Z"
}

The alert in the activity feed will resemble:

Acme Reporting has triggered this test alert
Generated on 05 Apr 2017

Example of retrieving an alert by id

GET https://api.xero.com/xero.hq/1.0/alerts/id
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "type": "CLIENT_ALERT_TEST",
  "targetType": "CLIENT",
  "targetId": "06953ddc-9e92-49e1-aa8d-9fff61c7872a",
  "dueAt": "2014-04-14T02:15:15Z",
  "activeDate": "2016-02-14T05:00:00Z",
  "additionalData": {
    "appName": "Acme Reporting",
    "date": "2017-04-05T00:00:00Z"
  },
  "actions": [
    {
      "label": "View",
      "link": "https://www.yourapp.com/#/client/123"
    }
  ]
}

POST Alerts

Use this method to create alerts
The following is required when creating an alert
type Classifies the type of data contained in the alert. The Alert Type will define the “template” associated to the alert. See Alert Types
targetType Specifies the target for the alert. See Target Types
access Access object that specifies the users that will see the alert. See access
actions A collection of Actions Objects. Will contain a link (URL) to the relevant action. See actions
The following are optional when creating an alert
targetId The Id based on the targetType to create the alert against i.e. when targetType is CLIENT value will be ClientId. This field is not required when targetType is PRACTICE.
dueAt The date the alert is due to be actioned (timestamp) e.g. 2014-04-14T02:15:15Z
activeDate The date at which the alert should become active i.e. be made visible to the user (timestamp) e.g. 2016-02-14T05:00:00Z. If not supplied will default to the current date and time which will set this alert as active immediately.
addtionalData Additional Data object matching the template associated with the specified alert type. See additionalData
Elements for access
to Indicates that the alert should be assigned to all the users that have access to the TargetId e.g. ALL-USERS
Elements for additionalData
appName Name of your application.
date e.g. 2017-04-05T00:00:00Z
Elements for actions
label The text to display the alert action
link A URL link for the alert action in the partner application

Example request to create an alert

POST https://api.xero.com/xero.hq/1.0/alerts
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "type": "CLIENT_ALERT_TEST",
  "targetType": "CLIENT",
  "targetId": "06953ddc-9e92-49e1-aa8d-9fff61c7872a",
  "dueAt": "2014-04-14T02:15:15Z",
  "activeDate": "2016-02-14T05:00:00Z",
  "additionalData": {
    "appName": "Acme Reporting",
    "date": "2017-04-05T00:00:00Z"
  },
  "actions": [
    {
      "label": "View",
      "link": "https://www.yourapp.com/#/client/123"
    }
  ]
}
		

PUT Alerts

Use this method to update alerts.

Example request to update an alert

PUT https://api.xero.com/xero.hq/1.0/alerts/01234567-89ab-cdef-0123-456789abcdef
{
  "type": "CLIENT_ALERT_TEST",
  "targetType": "CLIENT",
  "targetId": "06953ddc-9e92-49e1-aa8d-9fff61c7872a",
  "dueAt": "2014-04-14T02:15:15Z",
  "activeDate": "2016-02-14T05:00:00Z",
  "access": {
    "to": "ALL-USERS"
  },
  "additionalData": {
    "appName": "Acme Reporting",
    "date": "2017-04-05T00:00:00Z"
  },
  "actions": [
    {
      "label": "View",
      "link": "https://www.yourapp.com/#/client/123"
    }
  ]
}

DELETE Alerts

Deletes an Alert permanently. This alert will no longer be returned by any get requests.

Example of deleting an alert

DELETE https://api.xero.com/xero.hq/1.0/alerts/01234567-89ab-cdef-0123-456789abcdef