REST API: Add Schedule Events

Last Updated: May 16, 2017

Description

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

Resource Information

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

Required Schedule Event Properties

schedule_calendar_id:
Integer. Id of the Schedule Calendar that contains this event.
start:
String (ISO8601 format). Date/time that represents the start time of this event (i.e. 2004-02-12T15:19:21+00:00).
end:
String (ISO8601 format). Date/time that represents the end time of this schedule event (i.e. 2004-02-12T15:19:21+00:00).
all_day:
Boolean. If true, the event duration is all day on the day specified in start. If false, the event duration is determined by date/time specified in end.

Optional Schedule Event Properties

For a full list of the properties that may be set on an event, see the Schedule Event object.

Optional Request Properties

team_events:
String. 'base' or 'instance'. Default is 'instance'. If 'instance' is specified, supplemental events that are created for multiple users will be returned as individual single events for each assigned user. If 'base' is specified, supplemental events that are created for multiple users will be returned as one combined event for all assignees.

Status Codes

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

_status_code Meaning
200 OK. Event was created successfully.
201 Fulfilled. Event was created successfully and additional events that were created as a result are included in the supplemental data section of the response.
403 Permission Denied. The requesting user did not have high enough manage schedule permissions to create the event.
417 Expectation Failed. Something was wrong or missing with the properties supplied for this event. See the _status_extra value for more detail.

Examples

Create two new events: one unassigned, and the second assigned to two users.

## 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/schedule_events"

## contents of the post_data.json file are:
{
    "data":
    [
        {
            "schedule_calendar_id":5,
            "start":"2016-12-05T16:00:00+00:00",
            "end":"2016-12-05T18:00:00+00:00",
            "assigned_user_ids":"",
            "title":"unassigned event",
            "draft":true,
            "active":true
        },
        {
            "schedule_calendar_id":5,
            "start":"2016-12-05T16:00:00+00:00",
            "end":"2016-12-05T18:00:00+00:00",
            "assigned_user_ids":[11, 1365],
            "title":"assigned to multiple",
            "draft":true,
            "active":true
        }
    ],
    "team_events": "base"
}



## RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json
{
 "results": {
  "schedule_events": {
   "1": {
    "_status_code": 200,
    "_status_message": "Created",
    "id": 2816373,
    "user_id": 11,
    "unassigned": true,
    "schedule_calendar_id": 5,
    "jobcode_id": 0,
    "all_day": false,
    "start": "2016-12-05T16:00:00+00:00",
    "end": "2016-12-05T18:00:00+00:00",
    "active": true,
    "draft": true,
    "timezone": "UTC",
    "title": "unassigned event",
    "notes": "",
    "color": "#888888",
    "last_modified": "2016-12-07T17:47:37+00:00",
    "created": "2016-12-07T17:47:37+00:00",
    "customfields": "",
    "location": ""
   },
   "2": {
    "_status_code": 200,
    "_status_message": "Created",
    "id": 2816375,
    "user_id": 11,
    "unassigned": false,
    "schedule_calendar_id": 5,
    "jobcode_id": 0,
    "all_day": false,
    "start": "2016-12-05T16:00:00+00:00",
    "end": "2016-12-05T18:00:00+00:00",
    "active": true,
    "draft": true,
    "timezone": "UTC",
    "title": "assigned to multiple",
    "notes": "",
    "color": "#888888",
    "last_modified": "2016-12-07T17:47:37+00:00",
    "created": "2016-12-07T17:47:37+00:00",
    "customfields": "",
    "assigned_user_ids": "11,1365",
    "location": ""
   }
  }
 },
 "supplemental_data": {
  "users": {
   "11": {
    "id": 11,
    "first_name": "Joni",
    "last_name": "Smith",
    ...
    }
   }
  },
  "calendars": {
   "5": {
    "id": "5",
    ...
   }
  }
 }
}