Skip to content

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,
  }
}