REST API: Add Reminders

Last Updated: July 20, 2015

Description

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

Resource Information

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

Required Reminder Properties

user_id:
Integer. Read-only. Id of the user that this reminder pertains to. A user_id of 0 indicates that this is a company-wide reminder.
reminder_type:
String. The type of this reminder object. Supported reminder_types are 'clock-in' and 'clock-out'.
due_time:
String. The 24-hour time that the reminder should be sent, expressed as "hh:mm:ss". The time should be in the user's local time and must be in even 5 minute increments. For example: 13:45:00 or 08:00:00.
due_days_of_week:
String. A comma-separated list of the days of the week when the reminder should be sent. The value can be any combination of 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri' and 'Sat'. For example: 'Mon,Tue,Wed,Thu,Fri' or 'Tue,Sat'.
distribution_methods:
A comma-separated list of the transport method(s) indicating how the reminder message should be sent. The value can be any combination of 'Push', 'SMS' and 'Email'. For example: "Push,SMS". The 'Push' method utilizes the TSheets mobile app to deliver the notification to a mobile device. The 'SMS' method requires that the 'Text Messaging' Add-On be installed and that a 'Cell Number' is registered for each employee.
active:
Boolean. true or false. If true, this reminder is active and will be evaluated at the 'due_time' and 'due_days_of_week'. If false, this reminder is inactive and will not be evaluated. If active = false for user-specific reminders, then the company-wide reminder (of the same reminder type) will apply.
enabled:
Boolean. true or false. If true, the reminder is enabled and will be sent at the 'due_time' and 'due_days_of_week'. If false, the reminder is disabled and will not be sent. A user with an active (active = true) but disabled (enabled = false) reminder will not receive that reminder type regardless of how company-wide reminders are configured.

Optional Reminder Properties

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

Status Codes

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

_status_code Meaning
200 OK. Reminder was created successfully.
202 OK. Reminder accepted but not created because this reminder_type exists for the specified user.
417 Expectation Failed. Something was wrong or missing with the properties supplied for this reminder. See the _status_extra value for more detail.

Examples

Create user-specific clock-in and clock-out reminders for a user.

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

## contents of the post_data.json file are:
{
    "data":
    [
        {
            "user_id":37, 
            "reminder_type":"clock-in", 
            "due_time":"08:10:00", 
            "due_days_of_week":"Mon,Tue,Sat,Sun", 
            "distribution_methods":"Push,SMS,Email", 
            "active":true,
            "enabled":true            
        },
        {
            "user_id":37, 
            "reminder_type":"clock-out", 
            "due_time":"18:20:00", 
            "due_days_of_week":"Mon,Tue,Sat,Sun", 
            "distribution_methods":"Push,SMS,Email", 
            "active":true,
            "enabled":false
        }
    ]
}



## RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json
{
 "results": {
  "reminders": {
   "1": {
    "_status_code": 200,
    "_status_message": "Created",
    "user_id": 37,
    "reminder_type": "clock-in",
    "due_time": "08:10:00",
    "due_days_of_week": "Mon,Tue,Sat,Sun",
    "distribution_methods": "Push,SMS,Email",
    "active": true,
    "enabled": true,
    "id": "73033"
   },
   "2": {
    "_status_code": 200,
    "_status_message": "Created",
    "user_id": 37,
    "reminder_type": "clock-out",
    "due_time": "18:20:00",
    "due_days_of_week": "Mon,Tue,Sat,Sun",
    "distribution_methods": "Push,SMS,Email",
    "active": true,
    "enabled": false,
    "id": "73035"
   }
  }
 }
}