REST API: Add Notifications

Last Updated: July 08, 2015

Description

Add one or more notifications. We will handle batches of up to 50 notifications at a time. More than 50 notifications will result in a 413 - Request entity too large error.

Resource Information

HTTP Method POST
Endpoint https://rest.tsheets.com/api/v1/notifications
Authentication Token header required. See authentication section
Request format json object. Pass an array of notification objects as the value to a 'data' property (see example below).
Response format json
Response object Notification

Required Notification properties

message:
String. The message text of the notification. The maximum message length is 2000 characters.

Optional Notification Properties

For a full list of the properties that may be set on a notification, see the Notification object.

user_id:
optional
Integer. Defaults to the requesting user (based on the Access Token). Only administrators may add notifications for users other than themselves. Furthermore, administrators may only add notifications for users that belong to their company.

Status Codes

Each notification that is created will come back with a _status_code and _status_message that will indicate whether the notification was created successfully. If there was a problem creating a notification, there may also be an additional field, _status_extra, which will contain more details about the failure.

_status_code Meaning
200 OK. notification was created successfully.
417 Expectation Failed. Something was wrong or missing with the properties supplied for this notification. See the _status_extra value for more detail.

General Notes

  • Frequent notifications to the same device may overwrite each other. Some notifications in quick succession may not be delivered.
  • Notifications are not guaranteed to be delivered. They are dependent on the device's notification provider.
  • The actual delivery time is also dependent on the device's notification provider.

Examples

Create two new notifications.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -X POST -i -H "Content-Type: application/json" -d @notification_create.json "https://rest.tsheets.com/api/v1/notifications"

## contents of the notification_create.json file are:
{
 "data":
  [
    {
     "user_id": 1242515,
     "method": "push",
     "delivery_time":"2015-06-19T14:00:00+00:00",
     "precheck":"off_the_clock",
     "message":"Please clock in!"
    },
    {
     "user_id": 1242515,
     "method": "push",
     "delivery_time":"2015-06-19T23:00:00+00:00",
     "precheck":"on_the_clock",
     "message":"Please clock out!"
    }
  ]
}



## RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json

{
 {
 "results": {
  "notifications": {
   "1": {
    "_status_code": 200,
    "_status_message": "Created",
    "id": 94140223,
    "msg_tracking_id": "baabeb0ab03d62ce",
    "user_id": 1242515,
    "message": "Please clock in!",
    "method": "push",
    "delivery_time": "2015-06-24T15:00:00+00:00",
    "created": "2015-06-23T14:17:57+00:00",
    "precheck": "off_the_clock"
   },
   "2": {
    "_status_code": 200,
    "_status_message": "Created",
    "id": 94140225,
    "msg_tracking_id": "3ce75c1b7de6598a",
    "user_id": 1242515,
    "message": "Please clock out!",
    "method": "push",
    "delivery_time": "2015-06-24T23:00:00+00:00",
    "created": "2015-06-23T14:17:57+00:00",
    "precheck": "on_the_clock"
   }
  }
 }
}