Synchronizing Shifts for Data Warehousing

This guide is intended to help developers integrate with the 7shifts List Shifts endpoint, particularly for synchronizing shift data with a data warehouse. The focus is on ensuring that only relevant shift data is retrieved, with considerations for handling published, deleted, and unpublished shifts.

Syncing Published Shifts

By default, the List Shifts endpoint returns only published shifts. Published shifts are those that are finalized and reflect the actual scheduled work.

Note: In most cases, you will only need to sync these published shifts, as they represent the final state of the schedule.

curl --request GET \
     --url 'https://api.7shifts.com/v2/company/1234/shifts?limit=250&start[lte]=2024-08-20T00%3A00%3A00Z&start[gte]=2024-08-21T00%3A00%3A00Z

Handling Deleted Shifts

Shifts that have been deleted will not be returned by the endpoint unless explicitly requested.
Query Filter: Use the deleted=true query filter to retrieve shifts that were published but have since been deleted. Deleted shifts in the response will include the deleted: true property.

Note: It's essential to use this filter when you need to track or audit shifts that were initially published but later removed.

curl --request GET \
     --url 'https://api.7shifts.com/v2/company/1234/shifts?limit=250&start[lte]=2024-08-20T00%3A00%3A00Z&start[gte]=2024-08-21T00%3A00%3A00Z&deleted=true

Managing Unpublished Shifts

During schedule creation or editing, shifts can be in an unpublished state. These shifts may be new, edited, or deleted, but they are not yet finalized.

Use the draft=true query filter to retrieve unpublished shifts. The following scenarios will be returned:

New Unpublished Shifts: These will have publish_status: draft and draft: true.
Edited Unpublished Shifts: Previously published shifts that have been edited but not yet re-published will show publish_status: published and draft: true.
Deleted Unpublished Shifts: Previously published shifts that have been deleted will have publish_status: published and deleted: true.

curl --request GET \
     --url 'https://api.7shifts.com/v2/company/1234/shifts?limit=250&start[lte]=2024-08-20T00%3A00%3A00Z&start[gte]=2024-08-21T00%3A00%3A00Z&draft=true

Important Considerations

Do not combine the deleted=true and draft=true query filters in a single request, as this may lead to inconsistent results.

The include_draft query filter is intended for internal use only and should not be used in your integration.