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.
Example response:
response = {
  'total_count': 77,
  'next': "https://api.smartplanapp.io/api/v2/accounts/<UUID>/shifts/?limit=50&offset=50",
  '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 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.
Example response:
response = {
  'total_count': 77,
  'next': "https://api.smartplanapp.io/api/v2/accounts/<UUID>/worklogs/?limit=50&offset=50",
  '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,
  }
}