REST API: List Schedule Events

Last Updated: February 21, 2017

Description

Retrieves a list of schedule events associated with your employees, with filters to narrow down the results.

Resource Information

HTTP Method GET
Endpoint https://rest.tsheets.com/api/v1/schedule_events
Authentication Token header required. See authentication section
Request format Everything is handled through the request uri on a GET.
Response format json
Response object Schedule Event

Available Filters

ids:
required - unless modified_before, modified_since, or start are set
Integer. Comma separated list of one or more schedule event ids you'd like to filter on. Only schedule events with an id set to one of these values will be returned.
user_ids:
optional
Integer. Comma-separated list of one or more user ids to retrieve schedule events for.
schedule_calendar_ids:
required
Integer. Comma separated list of one or more schedule calendar ids you'd like to filter on. Only schedule events with a schedule calendar id set to one of these values will be returned.
jobcode_ids:
optional
Integer. A comma-separated string of jobcode ids. Only schedule events with these jobcodes will be returned.
start:
required - unless ids, modified_before, or modified_since are set
String (ISO8601 format). Only schedule events starting on or after this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
end:
optional
String (ISO8601 format). Only schedule events ending on or before this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
active:
optional
String. 'yes', 'no' or 'both'. Default is 'both'. Only schedule events whose active state match the requested filter will be returned.
draft:
optional
String. 'yes', 'no' or 'both'. Default is 'no'. Only schedule events whose draft state match the requested filter will be returned.
team_events:
optional
String. 'base' or 'instance'. Default is 'instance'. If 'instance' is specified, events that are assigned to multiple users will be returned as individual single events for each assigned user. If 'base' is specified, events that are assigned to multiple users will be returned as one combined event for all assignees.
modified_before:
required - unless ids, modified_since, or start are set
String (ISO8601 format). Only schedule events modified before this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
modified_since:
required - unless ids, modified_before, or start are set
String (ISO8601 format). Only schedule events modified since this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
supplemental_data:
optional
String. 'yes' or 'no'. Default is 'yes'. Indicates whether supplemental data should be returned.
per_page:
optional
Integer. Represents how many results you'd like to retrieve per request (page). Default is 50. Max is 50.
page:
optional
Integer. Represents the page of results you'd like to retrieve. Default is 1.

Examples

Retrieve schedule events from a calendar.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/schedule_events?schedule_calendar_ids=72595&modified_since=2017-01-01T13:00:00+06:00"

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

{
 "results": {
  "schedule_events": {
   "894562": {
    "id": 894562,
    "user_id": 1283037,
    "unassigned": false,
    "schedule_calendar_id": 72595,
    "jobcode_id": 17285791,
    "start": "2013-08-08T08:00:00-06:00",
    "end": "2013-08-08T14:00:00-06:00",
    "timezone": "tsMT",
    "notes": "Some Custom Notes",
    "last_modified": "2013-08-09T17:30:54-06:00",
    "created": "2015-07-15T19:08:33-06:00",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    }    
   },
   "894588": {
    "id": 894588,
    "user_id": 1283037,
    "unassigned": true,
    "schedule_calendar_id": 72595,
    "jobcode_id": 17285791,
    "start": "2013-08-09T08:00:00-06:00",
    "end": "2013-08-09T14:00:00-06:00",
    "timezone": "tsMT",
    "notes": "Some More Custom Notes",
    "last_modified": "2013-08-09T17:31:23-06:00",
    "created": "2015-07-15T19:08:34-06:00"
   }
  },
  "more": false,
  "supplemental_data": {
   "jobcodes": {
    "17285791": {
     "id": 17285791,
     "parent_id": 0,
     "assigned_to_all": false,
     "billable": false,
     "active": true,
     "type": "regular",
     "has_children": false,
     "billable_rate": 0,
     "short_code": "dev",
     "name": "Development Team",
     "last_modified": "2013-07-24T19:05:53+00:00",
     "created": "2013-05-28T20:19:33+00:00"
    }
   },
   "users": {
    "1283037": {
     "id": 1283037,
     "first_name": "Alexander",
     "last_name": "Luzzana",
     "group_id": 144959,
     "active": true,
     "employee_number": 4,
     "salaried": true,
     "exempt": false,
     "username": "aluzzana",
     "email": "garrett@tsheets.com",
     "payroll_id": "4",
     "hire_date": "2012-07-01",
     "term_date": "0000-00-00",
     "job_title": "",
     "gender": "",
     "last_modified": "2013-07-12T15:52:00+00:00",
     "last_active": "2013-07-30T20:06:13+00:00",
     "created": "2013-05-28T20:23:44+00:00",
     "mobile_number": ""
    },
   "customfields": {
    "19142": {
     "id": 19142,
     "required": false,
     "type": "timesheet",
     "ui_preference": "managed-list",
     "short_code": "cf1",
     "regex_filter": "",
     "name": "Custom Field 1",
     "last_modified": "2013-07-26T18:58:23+00:00",
     "created": "2013-07-23T23:09:14+00:00"
    },
    "19144": {
     "id": 19144,
     "required": false,
     "type": "timesheet",
     "ui_preference": "managed-list",
     "short_code": "cf2",
     "regex_filter": "",
     "name": "Custom Field 2",
     "last_modified": "2013-07-26T18:58:32+00:00",
     "created": "2013-07-23T23:09:32+00:00"
    }    
   }
  }  
 }
}