Shifts/Worklogs

Important note about Shifts data

When a Shift begins (according to its start time), it's archived as a WorkLog (and thus deleted as a Shift). WorkLogs contains attendance info, among other things.

Shift

Shift data

Attribute	Value type	Description
uuid	str	Shift UUID
start_dt	str(isoformat)	Start datetime, in iso-format
end_dt	str(isoformat)	End datetime, in iso-format
jobtype	dict(jobtype)	Jobtype
ending_shift	bool	Shift is an "ending/closing" shift
owner	dict(member)	Owner
location	dict(location)	Location
display_date	str(isoformat)	Display date (can be the date before start_dt - see note)
planned_break	int	Planned break (in seconds)
status	str	Status (Allocated, for sale or empty)
note	str	Note on the shift(optional)
planned_shift_duration	int	Planned duration, minus break (in seconds)

Endpoint: shifts/

GET https://api.smartplanapp.io/v2/accounts/UUID/shifts/

Returns all shifts for the specified account (50 at a time).

Limited to 50 objects per page. In the response dataset; 'total_count' will be the total number of available objects. To fetch the next 'page' you can use the url in the 'next' param. Likewise you can use the url in the 'previous' for the previous 50 objects.

Available filters

Use simple GET params for the filters. Chain filters if you want;

start_date (in iso_format; YYYY-MM-DD) Return all shifts with a start date greater than(or equal) to the specified date
end_date (in iso_format; YYYY-MM-DD) Return all shifts with an end date less than(or equal) to the specified date
owner (member.UUID) Return all Shifts belonging this this Member
location (location.UUID or "false") Return all Shifts belonging this Location. ~~Or filter by Shifts not belonging to a location~~*
jobtypes (jobtype.UUID) Return all Shifts that matches this Jobtype; You can filter by multiple jobtype UUIDs by comma-separating them, will then return if a Shift matches one of the provided jobtypes.

Ordering

Use the GET param 'ordering' to sort the returned shifts. You can order by 'location', 'start_dt' & 'end_dt'. ordering can be chained aswell. Like so; "-location,start_dt", "location,-start_dt" etc.

* all shifts now belong to a location. Previously the initial shifts on an account did not belong to a location for various reasons(technical debt and poor decisions years ago); A new "initial" Location has been added for these shifts. See 'Locations'. using "false" in the location filter will now return shifts assigned to this new location. This means that nothing has changed in way the data is returned, but now all shifts belong to a location.

Example response:

response = {
  'total_count': 77,
  'next': "https://api.smartplanapp.io/api/v2/accounts/<UUID>/shifts/?limit=50&offset=50&ordering=start_dt",
  'previous': None,
  'results': [{
    'uuid': '1234-1234-1234',
    'start_dt': '2021-03-27T14:00:00', 
    'end_dt': '2021-03-27T20:00:00', 
    'jobtype': {
      'title': 'Chef', 
      'uuid': '1234-1234-1234', 
    }, 
    'ending_shift': False, 
    'owner': {
      'uuid': '1234-1234-1234',
      'first_name': 'John', 
      'last_name': 'Doe', 
      'initials': 'JD', 
      'is_admin': True, 
      'user_type': 'active', 
      'alive': True
    },
    'location': {
      'uuid': '1234-1234-1234', 
      'title': 'Warehouse', 
      'alive': True, 
      'is_hidden': False
    }, 
    'display_date': '2021-03-27', 
    'planned_break': 0, 
    'status': 'Allocated', 
    'note': '', 
    'planned_shift_duration': 21600
  },
  //(49 more...)
  ]
}

example 2: All Shifts for a specific owner matching either one of two different jobtypes: https://api.smartplanapp.io/api/v2/accounts/<UUID>/shifts/?owner=UUID&jobtypes=2345,2346

Important notes

uuid is not set in stone for Shift objects. They can change if a schedule is bulk edited through the planning-tool. When a Shift is archived(see description above) as a WorkLog, then it will receive a new UUID aswell.
start_date and end_date filter are for the date upon which the shift is displayed in Smartplan. A shift start starts friday at 24:00 and ends saturdat at 03:00, is displayed friday and will not be returned by a filter that filters by saturday(although the shift is technically a saturday shift) So, In general; be aware of shifts crossing midnight when using the date filters; the filters are for when the shift starts, not when it ends.
If you want to return all shifts on a specific date, then you have to filter by that date as both start_date and end_date, since start_date works as "greater than or equal to" and end_date works as "less than or equal to"

Endpoint: shifts/UUID/

GET https://api.smartplanapp.io/v2/accounts/UUID/shifts/UUID/

Returns the data for the specified shift

Example response:

response = {
  'results': {
    'uuid': '1234-1234-1234',
    'start_dt': '2021-03-27T14:00:00', 
    'end_dt': '2021-03-27T20:00:00', 
    'jobtype': {
      'title': 'Chef', 
      'uuid': '1234-1234-1234', 
    }, 
    'ending_shift': False, 
    'owner': {
      'uuid': '1234-1234-1234',
      'first_name': 'John', 
      'last_name': 'Doe', 
      'initials': 'JD', 
      'is_admin': True, 
      'user_type': 'active', 
      'alive': True
    },
    'location': {
      'uuid': '1234-1234-1234', 
      'title': 'Warehouse', 
      'alive': True, 
      'is_hidden': False
    }, 
    'display_date': '2021-03-27', 
    'planned_break': 0, 
    'status': 'Allocated', 
    'note': '', 
    'planned_shift_duration': 21600
  }
}

Worklog

Worklog data

Attribute	Value type	Description
uuid	str	Worklog UUID
planned_start_dt	str(isoformat)	Planned start datetime, in iso-format
planned_end_dt	str(isoformat)	Planned end datetime, in iso-format
planned_break	int	Planned break duration (in seconds)
planned_shift_duration	int	Planned shift duration, minus break (in seconds)
attendance_start_dt	str(isoformat)	Attended end datetime, in iso-format
attendance_end_dt	str(isoformat)	Attended start datetime, in iso-format
attendance_break	int	Attended brea duration (in seconds)
attendance_breaks_specified	None/list[datetime sets]	If break is specifed(could be from punchclock), then the breaks will be here in sets of datetimes(isoformat)
attendance_status	str	attended/not_attended
attendance_edit_status	str	"not_changed": no changes from the planned data. "changed": has unapproved changes(could be from punchclock events). "confirmed": all changes confirmed by an admin.
attendance_shift_duration	int	Attended shift duration, minus break (in seconds)
jobtype	dict(jobtype)	Jobtype
ending_shift	bool	Worklog is an "ending/closing" shift
owner	dict(member)	Owner
location	dict(location)	Location
display_date	str(isoformat)	Display date (can be the date before start_dt - see note)
planned_break	int	Planned break (in seconds)
note	str	Note on the Worklog(optional)
edit_message	str	Edit message on the Worklog, when editing attendance(optional)

Endpoint: Worklogs/

GET https://api.smartplanapp.io/v2/accounts/UUID/worklogs/

Returns all worklogs for the specified account (50 at a time).

Limited to 50 objects per page. In the response dataset; 'total_count' will be the total number of available objects. To fetch the next 'page' you can use the url in the 'next' param. Likewise you can use the url in the 'previous' for the previous 50 objects.

Available filters

Use simple GET params for the filters. Chain filters if you want;

start_date (in iso_format; YYYY-MM-DD)
end_date (in iso_format; YYYY-MM-DD)
owner (member.UUID) Return all WorkLogs belonging this this Member
location (location.UUID or "false") Return all WorkLogs belonging this Location. ~~Or filter by WorkLogs not belonging to a location.~~
jobtypes (jobtype.UUID) Return all WorkLogs that matches this Jobtype; You can filter by multiple jobtype UUIDs by comma-separating them, will then return if a WorkLog matches one of the provided jobtypes.

* all WorkLogs now belong to a location. Previously the initial shifts on an account did not belong to a location for various reasons(technical debt and poor decisions years ago); A new "initial" Location has been added for these WorkLogs. See 'Locations'. using "false" in the location filter will now return WorkLogs assigned to this new location. This means that nothing has changed in way the data is returned, but now all WorkLogs belong to a location.

Ordering

Use the GET param 'ordering' to sort the returned shifts. You can order by 'location', 'planned_start_dt' & 'planned_end_dt'. ordering can be chained aswell. Like so; "-location,planned_start_dt", "location,-planned_start_dt" etc.

Example response:

response = {
  'total_count': 77,
  'next': "https://api.smartplanapp.io/api/v2/accounts/<UUID>/worklogs/?limit=50&offset=50&ordering=planned_start_dt",
  'previous': None,
  'results': [{
    'uuid': '1234-1234-1234',
    'planned_start_dt': '2021-03-23T14:00:00', 
    'planned_end_dt': '2021-03-23T20:00:00', 
    'planned_break': 0, 
    'jobtype': {
      'title': 'Chef', 
      'uuid': '1234-1234-1234',
    }, 
    'ending_shift': False, 
    'owner': {
      'uuid': '1234-1234-1234',
      'first_name': 'John', 
      'last_name': 'Doe', 
      'initials': 'JD', 
      'is_admin': True, 
      'user_type': 'active', 
      'alive': True
    },
    'location': {
      'uuid': '1234-1234-1234',
      'title': 'Warehouse',
      'alive': True,
      'is_hidden': False
    }, 
    'display_date': '2021-03-23',
    'attendance_start_dt': '2021-03-23T14:00:00',
    'attendance_end_dt': '2021-03-23T20:00:00',
    'attendance_break': 0,
    'attendance_breaks_specified': None,
    'attendance_status': 'attended',
    'attendance_edit_status': 'not_changed',
    'note': '',
    'edit_message': '',
    'attendance_shift_duration': 21600,
    'planned_shift_duration': 21600,
  },
  //(49 more...)
  ]
}

Important notes

start_date and end_date filters are for the date upon which the shift/worklog is displayed in Smartplan. A worklog start starts friday at 24:00 and ends saturdat at 03:00, is displayed friday and will not be returned by a filter that filters by saturday(although the worklog is technically a saturday worklog) So, In general; be aware of shifts/worklogs crossing midnight when using the date filters; the filters are for when the shift/worklog starts, not when it ends.

Endpoint: worklogs/UUID/

GET https://api.smartplanapp.io/v2/accounts/UUID/worklogs/UUID/

Returns the data for the specified Worklog(archived Shift)

Example response:

response = {
  'results': {
    'uuid': '1234-1234-1234',
    'planned_start_dt': '2021-03-23T14:00:00', 
    'planned_end_dt': '2021-03-23T20:00:00', 
    'planned_break': 0, 
    'jobtype': {
      'title': 'Chef', 
      'uuid': '1234-1234-1234',
    }, 
    'ending_shift': False, 
    'owner': {
      'uuid': '1234-1234-1234',
      'first_name': 'John', 
      'last_name': 'Doe', 
      'initials': 'JD', 
      'is_admin': True, 
      'user_type': 'active', 
      'alive': True
    },
    'location': {
      'uuid': '1234-1234-1234',
      'title': 'Warehouse',
      'alive': True,
      'is_hidden': False
    }, 
    'display_date': '2021-03-23',
    'attendance_start_dt': '2021-03-23T14:00:00',
    'attendance_end_dt': '2021-03-23T20:00:00',
    'attendance_break': 0,
    'attendance_breaks_specified': None,
    'attendance_status': 'attended',
    'attendance_edit_status': 'not_changed',
    'note': '',
    'edit_message': '',
    'attendance_shift_duration': 21600,
    'planned_shift_duration': 21600,
  }
}

Shifts/Worklogs

Important note about Shifts data

** Shift **

Shift data

** Endpoint: shifts/ **

Available filters

Ordering

Example response:

Important notes

** Endpoint: shifts/UUID/ **

Example response:

** Worklog **

Worklog data

** Endpoint: Worklogs/ **

Available filters

Ordering

Example response:

Important notes

** Endpoint: worklogs/UUID/ **

Example response:

Shift

Endpoint: shifts/

Endpoint: shifts/UUID/

Worklog

Endpoint: Worklogs/

Endpoint: worklogs/UUID/