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.
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 pleases 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.
Updated about 2 years ago