Migrating to V2 endpoints

V2 endpoints introduce a number of significant breaking changes and are mostly incompatible with V1 endpoints. This guide will outline the differences between V1 and V2 endpoints to help you make it an easier transition.

V1 Endpoint Deprecation

On September 30, 2022, 7shifts is no longer recommending using API V1 endpoints to access API resources if an equivalent V2 endpoint exists. You can continue to use V1 endpoints during the deprecation period until is is EOL on May 31, 2023.

Why are V1 endpoints being phased out?

V1 endpoints are being phased out to increase standardization, security and add additional functionality to our API resources. At a high level the we V1 endpoints lack the security, versioning and standardization we've introduced for V2 endpoints.

V2 endpoints use the OpenAPI Specification for describing and validating the endpoints, making it easier to implement integrations.

Important Dates Timelines

The following timeline explains in detail each period of the V1 endpoint lifecycle and when it will become End of Life (EOL):

2022-08-31 API keys are deprecated and no longer recommended
2022-08-31 Access Tokens are supported
2022-09-30 API V1 endpoints are deprecated and no longer recommended
2023-03-31 API keys are EOL and no longer supported
2023-05-31 API V1 endpoints are EOL and no longer supported

Plan Requirements

Please be aware that V2 endpoints are restricted based on the company plan. Please refer to our Plan Requirements Guide for more information on which endpoints are available based on the plan a company subscribes to.

Authentication

V2 endpoints can only be accessed via OAuth or Access Tokens; API keys only support V1 endpoints. If you are a partner and wish to use V2 endpoints via an OAuth client contact [email protected]. If you already have an OAuth Client or Access Token refer to the Authentication guide..

❗️

This recent API version does not support API keys

API keys only support V1 endpoints. If you wish to use any V2 endpoint you will need to acquire an OAuth client or an Access Token.

If you require access to V2 endpoints please contact [email protected] to acquire an Access Token. Self-provisioning of Access Tokens is coming soon.

API Versions

API version control has been introduced with all V2 endpoints. API versioning allows us to continually improve our API endpoints and provide you with predictable endpoint behaviour. Additionally, you will be able to specify different versions by endpoint to best suit your needs. To specify a version we've added a version header like the example below.

curl --request --url GET 'https://api.7shifts.com/v2/company/1234/users \
--header "Authorization: Bearer ISSUED_TOKEN" \
--header "x-api-version: 2022-05-01" \
--header "x-company-guid: GUID"'

For full details please refer to the Versioning guide.

Pagination Changes

Most V2 endpoints that return a list of results will include a cursor. You can specify the number of results using the limit URL parameter to specify the size of the cursor. The response payload will include a prev or next cursor value which can be passed in to retrieve the next or previous set of results. For more details see pagination in our reference section. For example a sample response from LIST /time_punches

{
    "data": [
        {...
        }
    ],
    "meta": {
        "cursor": {
            "current": "eyJpZCI6Ijg1Njg1NjYwIiwibmV4dCI6dHJ1ZX0=\n",
            "prev": "eyJpZCI6Ijg1NzgxNzY4IiwibmV4dCI6ZmFsc2V9",
            "next": "eyJpZCI6Ijg2MDIzMDM2IiwibmV4dCI6dHJ1ZX0=",
            "count": 20
        }
    },
    "object": "time_punches"
}

To retrieve the next set of results:

curl --request GET --url 'https://api.7shifts.com/v2/company/1234/time_punches?cursor=eyJpZCI6Ijg2MDIzMDM2IiwibmV4dCI6dHJ1ZX0=&limit=20' \
--header 'Authorization: Bearer ISSUED_TOKEN' \
--header 'x-api-version: 2022-05-01' \
--header 'x-company-guid: GUID''

Parameters Changes

All V2 endpoints will remove inconsistencies with timezones, value types and format for parameters and will be consistent between request and response bodies. The following are notable changes:

Dates Time

All date and date time parameters will be in ISO 8601 format.

All date time values must specify Z (zero time) or a time offset. Example: 2022-05-01T13:00:00Z. If a date time value is passed in with a time offset it will be converted to UTC for local storage.

Example v1 POST /shift payload

{
     "shift": {
          "location_id": 7890,
          "user_id": 1111,
          "role_id": 1234,
          "station": 1,
          "department_id": 556,
          "start": "2021-12-31 10:00:00",
          "end": "2021-08-14 18:00:00",
     }
}

Example v2 POST /shift payload

{
     "location_id": 7890,
     "department_id": 3,
     "role_id": 1234,
     "station_id": 1,
     "user_id": 1111,
     "start": "2021-12-31T10:30:00Z",
     "end": "2021-12-31T18:00:00Z",

}

Wage, Tips and Sales

All parameters specifying money such as wage, tips and sale values will an integer specified in cents.

Example v1 POST /time_punch payload

{
    "time_punch": {
        "location_id": 7890,
        "department_id": 3,
        "role_id": 1234,
        "user_id": 1111,
        "clocked_in": "2022-01-31 08:00:00",
        "clocked_out": "2022-01-31 16:00:00",
        "tips": 32.50
    }
}

Example v2 POST /time_punch payload

{
     "location_id": 7890,
     "department_id": 3,
     "role_id": 1234,
     "user_id": 1111,
     "clocked_in": "2022-01-31T08:00:00Z",
     "clocked_out": "2022-01-31T16:00:00Z",
     "tips": 3250
}

Response Body

All response bodies now have a standard format.

Single resource response body

If the response is for a single resource, the payload will include:

• An object attribute specifying the type of data
• A data attribute containing the response data

Example request to GET v2/departments/789654:

curl --request GET --url https://api.7shifts.com/v2/company/1234/departments/789654

Example V2 response:

{
    "data": {
        "id": 789654,
        "company_id": 1234,
        "location_id": 8520,
        "name": "Back of House",
        "default": false,
        "deleted": null,
        "created": "2022-05-10T03:55:42Z",
        "modified": "2022-05-10T03:55:42Z"
    },
    "object": "department"
}

List resource response body

If the response include a list of resources, the payload will include:

• an object attribute specifying the type
• A data attribute containing the list of response data
• A meta tag containing pagination data

Example request to GET v2/departments:

curl --request GET --url https://api.7shifts.com/v2/company/1234/departments

Example V2 response:

{
    "data": [
        {
        "id": 789654,
        "company_id": 1234,
        "location_id": 8520,
        "name": "Back of House",
        "default": false,
        "deleted": null,
        "created": "2022-05-10T03:55:42Z",
        "modified": "2022-05-10T03:55:42Z"
        },
        {
        "id": 789655,
        "company_id": 1234,
        "location_id": 8520,
        "name": "Front of House",
        "default": false,
        "deleted": null,
        "created": "2022-05-10T03:55:42Z",
        "modified": "2022-05-10T03:55:42Z"
        }
    ],
    "meta": {
        "cursor": {
            "current": "eyJsaW1pdCI6MTAwLCJvZmZzZXQiOjB9",
            "prev": null,
            "next": null,
            "count": 2
        }
    },
    "object": "departments"
}

Response codes

Endpoints will now consistently response with HTTP codes as outlined in the API reference. Check each endpoint definition for possible response codes.

Booleans

All parameters that are boolean or have boolean like behaviours will be specified as boolean. In V1 endpoints there was a mix of using booleans and 0,1 for parameter values. Example:
In V1 "open_offer_type": 0 is now "open_offer_type": true in V2

Enum types

All parameters that previously had enum behavior but used integers for values will now use descriptive enum options. Example: in V1 "user_type_id": 1 is now in V2 "type": "employee"

Response Status Codes

We have expanded the types of HTTP response codes for endpoints. Where some endpoints in the past would only return 200 OK for all responses they may now return 201 Created for POST requests. Please refer to the response section in each endpoint definition for the possible HTTP response codes to expect.