Questions? 1-888-979-5877 · Webinar · Blog · Help
Login
See how easy it is.
You'll be scheduling staff in minutes.

Partner API

API

Introduction

The 7shifts API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients, and we support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your API key in any public website's client-side code). JSON will be returned in all responses from the API, including errors.

Authentication

You authenticate to the 7shifts API by providing your API key in the request.

Don't have an API key?

Generate an API key by first creating a 7shifts account. Once it's created, navigate to "Company Settings", then "API" and click "Generate".

Your API key carries many privileges, so be sure to keep them secret! Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

curl

curl https://api.7shifts.com/{VERSION}/{METHOD} \
   -u {API_KEY}:

curl uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password).

VERSION requireddefault is v1

The version of the API to use.

METHOD required

The type of request you're making. Whether it be 'users', 'locations' etc.

API_KEY required

The API key that you've received to access the data.

Definition

GET https://api.7shifts.com/v1/locations

Example request

curl https://api.7shifts.com/v1/locations \
   -u h33Ndi3h23o1mvVoaalLpdH:

Example response

{
    "status": "success",
    "data": [
        {
            "location": {
                "address": "Westhill Cafe",
                "hash": "685a93bb4b728af1a7b1f7da5cfce896",
                "country": "CA",
                "id": "408",
                "timezone": "America/Regina"
            }
        },
        {
            "location": {
                "address": "153 B st",
                "hash": "923a603f068bb17d43639e1e480efb04",
                "country": "CA",
                "id": "3557",
                "timezone": "America/Regina"
            }
        }
    ],
    "message": ""
}

Errors

7shifts uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with 7shifts' servers.

200 OK - Everything worked as expected.
400 Bad Request - Often missing a required parameter.
401 Unauthorized - No valid API key provided.
402 Request Failed - Parameters were valid but request failed.
404 Not Found - The requested item doesn't exist.
500, 502, 503, 504 Server errors - something went wrong on 7shifts' end.

The object

statusstring

Always returns 'error' when an error occurs

messagestring

A human-friendly message about what type of error occurred.

typestring

The type of error that occurred.

  • missing_parameter
  • unauthorized
  • invalid_id
  • invalid_json
  • save_error
  • delete_error
  • access_denied
  • validation_error
  • missing_header
  • unknown

Example

{
  "status" : "error",
  "message" : "You are not authorized to access this account",
  "type" : "unauthorized"
}

Deep Expanding

Many objects contain the id of another object in their response properties. Those objects can be expanded inline with the deep=1 request parameter. Objects that can be expanded are noted in this documentation. This parameter is available on all list GET API requests, and applies to the response of that request only. For example, requesting /v1/shifts will return a list and each item will contain a full shift object, that shift object will have foreign keys "location_id", "role_id", "user_id". If you want to have it return the location object, role object and user object, simply pass "deep=1" in the query string.

Example without deep=1

GET https://api.7shifts.com/v1/shifts/342641
{
    "status": "success",
    "data": {
        "shift": {
            "id": 342641,
            "start": "2014-01-06 15:00:00",
            "modified": "2014-01-07 19:34:01",
            "close": false,
            "user_id": 14950,
            "location_id": 5015,
            "notes": "",
            "hourly_wage": 10,
            "open": false,
            "created": "2014-01-07 19:32:51",
            "notified": false,
            "end": "2014-01-07 00:00:00",
            "open_offer_type": 0,
            "department_id": 2301,
            "draft": false
        }
    },
    "message": ""
}

Example with deep=1

GET https://api.7shifts.com/v1/shifts/342641?deep=1
{
    "status": "success",
    "data": {
        "location": {
            "address": "4th Ave",
            "hash": "4ff047efdsf7e9cf07acd49f632a7e0e0bf0",
            "country": "US",
            "id": 5015,
            "timezone": "America/Toronto",
            "created": "2014-01-07 05:34:58",
            "modified": "2014-01-19 20:28:07"
        },
        "role": {
            "color": "f6a94e",
            "id": 6050,
            "created": "2014-01-07 02:10:50",
            "modified": "2014-02-14 01:30:54",
            "name": "Cook"
        },
        "shift": {
            "id": 342641,
            "start": "2014-01-06 15:00:00",
            "modified": "2014-01-07 19:34:01",
            "close": false,
            "user_id": 14950,
            "location_id": 5015,
            "notes": "",
            "hourly_wage": 10,
            "open": false,
            "created": "2014-01-07 19:32:51",
            "notified": false,
            "end": "2014-01-07 00:00:00",
            "open_offer_type": 0,
            "department_id": 2301,
            "draft": false
        },
        "department": {
            "id": 2301,
            "created": "0000-00-00 00:00:00",
            "modified": "0000-00-00 00:00:00",
            "name": "Back of House"
        },
        "user": {
            "id": 14950,
            "lastname": "McDonald",
            "firstname": "Terry",
            "company_id": 1932,
            "email": "terry@mcdonald.com",
            "created": "2013-12-18 00:07:18",
            "photo": "http://full-path-to/photo.png",
            "modified": "2014-02-24 21:25:38",
            "user_type_id": 1
        }
    },
    "message": ""
}

Methods

Companies

The object

idinteger

The id of the company

namestring

The name of the company

countrystring

The 2 letter uppercased country code

photostring

Full URL to the uploaded company photo

createdstring

A UTC timestamp of when the record was created: 2013-01-01 10:00:00

modifiedstring

A UTC timestamp of when the record was last modified: 2013-01-01 10:00:00

Create

Not available through the API.

Read

Retrieves the details of your authenticated company. You are only allowed to supply your authenticated company id to retrieve company details. Will only ever return 1 result.
» Definition
GET https://api.7shifts.com/v1/companies/{id}
» Request
curl https://api.7shifts.com/v1/companies/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "company": {
            "country": "US",
            "id": 374,
            "created": "2012-02-01 05:41:08",
            "photo": "http://path-to-company-photo.png",
            "modified": "2014-02-13 00:24:14",
            "name": "ABC Company"
        }
    },
    "total": 1
}

Update

Update the details of your authenticated company. You are only allowed to update certain fields for your company.
» Definition
PUT https://api.7shifts.com/v1/companies/{id}
» Request
curl -X PUT -d '{ "company": { "name": "Joes new company name" } }' https://api.7shifts.com/v1/companies/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "company": {
            "id": 1932
        }
    },
    "message": "Company saved."
}

Delete

Not available through the API.

List

Get details of the company you're authenticated with. In the case of companies, you will only ever get 1 result back.

Arguments

limitinteger

The limit of results that will be returned.

offsetinteger

Return results starting from an offset.

order_fieldstring

The field you would like the results to be ordered by. Format is {lowercased-singular-method}.{field}. Example: /shifts/?order_field=shift.modified

order_dirstring

The direction you want the results ordered by. Accepted values are "asc" or "desc". Example: /shifts/?order_dir=desc

» Definition
GET https://api.7shifts.com/v1/companies
» Request
curl https://api.7shifts.com/v1/companies \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [{
        "company": {
            "country": "US",
            "id": "374",
            "created": "2012-02-01 05:41:08",
            "photo": "http://path-to-company-photo.png",
            "modified": "2014-02-13 00:24:14",
            "name": "ABC Company"
        }
    }],
    "total": 1
}

Departments

The object

idinteger

The id of the department

namestring

The name of the department

createdstring

A UTC timestamp of when the record was created: 2013-01-01 10:00:00

modifiedstring

A UTC timestamp of when the record was last modified: 2013-01-01 10:00:00

Create

Creates a department.
» Definition
POST https://api.7shifts.com/v1/departments
» Request
curl -X POST -d '{ "department": { "name": "Back of House" } }' https://api.7shifts.com/v1/departments \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "department": {
            "id": 3267
        }
    },
    "message": "Department added."
}

Read

Retrieves the details of one of your departments.
» Definition
GET https://api.7shifts.com/v1/departments/{id}
» Request
curl https://api.7shifts.com/v1/departments/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "department": {
            "id": 1925,
            "created": "2014-01-14 15:12:17",
            "modified": "2014-01-14 17:56:40",
            "name": "Front of House"
        }
    },
    "message": ""
}

Update

Updates a department.
» Definition
PUT https://api.7shifts.com/v1/departments/{id}
» Request
curl -X PUT -d '{ "department": { "name": "Kitchen" } }' https://api.7shifts.com/v1/departments/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "department": {
            "id": 3267
        }
    },
    "message": "Department saved."
}

Delete

Deletes a department.
» Definition
DELETE https://api.7shifts.com/v1/departments/{id}
» Request
curl -X DELETE https://api.7shifts.com/v1/departments/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [],
    "message": "Department deleted."
}

List

Retrieves a list of departments belonging to the company you've authenticated with.

Arguments

limitinteger

The limit of results that will be returned.

offsetinteger

Return results starting from an offset.

order_fieldstring

The field you would like the results to be ordered by. Format is {lowercased-singular-method}.{field}. Example: /shifts/?order_field=shift.modified

order_dirstring

The direction you want the results ordered by. Accepted values are "asc" or "desc". Example: /shifts/?order_dir=desc

» Definition
GET https://api.7shifts.com/v1/departments
» Request
curl https://api.7shifts.com/v1/departments \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [
        {
            "location": {
                "address": "3rd Ave",
                "hash": "4c51fb6386d03ea86f7bc79acb6951a3",
                "country": "US",
                "id": 5002,
                "timezone": "America/Toronto"
            }
        },
        {
            "location": {
                "address": "5th Ave",
                "hash": "d9c006e2451c98b5c3ab916e1063f0de",
                "country": "US",
                "id": 5001,
                "timezone": "America/Toronto"
            }
        }
    ],
    "total": 2
}

Locations

The object

idinteger

The id of the location.

addressstring

The address/name of the location.

countrystring

A 2 letter country code for the location.

timezonestring

The timezone this location is in. Example 'America/Toronto' would be EST.

hashstring

A unique identifier for the location used for querying various other end-points.

createdstring

A UTC timestamp of when the record was created: 2013-01-01 10:00:00

modifiedstring

A UTC timestamp of when the record was last modified: 2013-01-01 10:00:00

Create

Creates a location.
» Definition
POST https://api.7shifts.com/v1/departments
» Request
curl -X POST -d '{ "location": { "address": "3rd Ave" } }' https://api.7shifts.com/v1/departments \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "location": {
            "id": 3267
        }
    },
    "message": "Location added."
}

Read

Retrieves the details from a specific location.
» Definition
GET https://api.7shifts.com/v1/locations/{id}
» Request
curl https://api.7shifts.com/v1/locations/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "location": {
            "address": "3rd Ave",
            "hash": "sdfsohdfh9723ho2uh4",
            "country": "CA",
            "id": 5881,
            "timezone": "America/Regina",
            "created": "2013-01-01 10:00:00",
            "modified": "2014-04-03 10:30:00"
        }
    },
    "message": ""
}

Update

Updates a location.
» Definition
PUT https://api.7shifts.com/v1/location/{id}
» Request
curl -X PUT -d '{ "location": { "timezone": "America/Toronto", "address": "4th Ave" } }' https://api.7shifts.com/v1/location/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "location": {
            "id": 5881
        }
    },
    "message": "Location saved."
}

Delete

Deletes a location.
» Definition
DELETE https://api.7shifts.com/v1/locations/{id}
» Request
curl -X DELETE https://api.7shifts.com/v1/locations/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [],
    "message": "Location deleted."
}

List

Retrieves a list of locations belonging to the company you've authenticated with.

Arguments

limitinteger

The limit of results that will be returned.

offsetinteger

Return results starting from an offset.

order_fieldstring

The field you would like the results to be ordered by. Format is {lowercased-singular-method}.{field}. Example: /shifts/?order_field=shift.modified

order_dirstring

The direction you want the results ordered by. Accepted values are "asc" or "desc". Example: /shifts/?order_dir=desc

» Definition
GET https://api.7shifts.com/v1/locations
» Request
curl https://api.7shifts.com/v1/locations \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [
        {
            "location": {
                "address": "4th Ave",
                "hash": "4c51fb6386d03ea86f7bc79acb6951a3",
                "country": "US",
                "id": 5002,
                "timezone": "America/Toronto",
                "created": "2013-01-01 10:00:00",
                "modified": "2014-04-03 10:30:00"
            }
        },
        {
            "location": {
                "address": "5th Ave",
                "hash": "d9c006e2451c98b5c3ab916e1063f0de",
                "country": "US",
                "id": 5001,
                "timezone": "America/Toronto",
                "created": "2013-01-01 10:00:00",
                "modified": "2014-04-03 10:30:00"
            }
        }
    ],
    "total": 2
}

Roles

The object

idinteger

The id of the role.

namestring

The name of the role.

colorstring

6 character hex color of the role

createdstring

A UTC timestamp of when the record was created: 2013-01-01 10:00:00

modifiedstring

A UTC timestamp of when the record was last modified: 2013-01-01 10:00:00

Create

Creates a role.
» Definition
POST https://api.7shifts.com/v1/roles
» Request
curl -X POST -d '{ "role": { "name": "Bartender", "color": "00ff00" } }' https://api.7shifts.com/v1/roles \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "role": {
            "id": 3267
        }
    },
    "message": "Role added."
}

Read

Retrieves the details from a specific role.
» Definition
GET https://api.7shifts.com/v1/roles/{id}
» Request
curl https://api.7shifts.com/v1/roles/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "role": {
            "color": "08897d",
            "id": 6007,
            "name": "Cook",
            "created": "2013-01-01 10:00:00",
            "modified": "2014-04-03 10:30:00"
        }
    },
    "message": ""
}

Update

Updates a role.
» Definition
PUT https://api.7shifts.com/v1/roles/{id}
» Request
curl -X PUT -d '{ "role": { "color": "ff0000" } }' https://api.7shifts.com/v1/roles/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "role": {
            "id": 6007
        }
    },
    "message": "Role saved."
}

Delete

Deletes a role.
» Definition
DELETE https://api.7shifts.com/v1/roles/{id}
» Request
curl -X DELETE https://api.7shifts.com/v1/roles/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [],
    "message": "Role deleted."
}

List

Retrieves a list of roles belonging to the company you've authenticated with.

Arguments

limitinteger

The limit of results that will be returned.

offsetinteger

Return results starting from an offset.

order_fieldstring

The field you would like the results to be ordered by. Format is {lowercased-singular-method}.{field}. Example: /shifts/?order_field=shift.modified

order_dirstring

The direction you want the results ordered by. Accepted values are "asc" or "desc". Example: /shifts/?order_dir=desc

» Definition
GET https://api.7shifts.com/v1/roles
» Request
curl https://api.7shifts.com/v1/roles \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [
        {
            "role": {
                "color": "ff0000",
                "id": 6007,
                "name": "Bartender",
                "created": "2013-01-01 10:00:00",
                "modified": "2014-04-03 10:30:00"
            }
        },
        {
            "role": {
                "color": "28b633",
                "id": 6006,
                "name": "Chef",
                "created": "2013-01-01 10:00:00",
                "modified": "2014-04-03 10:30:00"
            }
        }
    ],
    "total": 2
}

Shifts

The object

idinteger

The id of the shift.

startstring

The date/time (UTC) of when the shift starts:
'2013-03-01 10:30:00'

endstring

The date/time (UTC) of when the shift ends:
'2013-03-01 17:30:00'

location_idinteger

The id of the location assigned to this shift.

user_idinteger

The id of the user assigned to this shift.

role_idinteger

The id of the role assigned to this shift.

department_idinteger

The id of the department assigned to this shift.

closeboolean

Whether or not this shift is going until close (thus, 'end' would not be used)

notesstring

Any notes specific to this shift.

hourly_wagefloat

The hourly wage for this shift

openboolean

Whether or not this is an "Open Shift"

notifiedboolean

Notifications have been sent out regarding this shift.

open_offer_typeinteger

If open=true, then we either offered it to:

  • 0: Offered to everyone
  • 1: Offered to a specific role

draftboolean

If this shift is still in draft mode (not published).

deletedboolean

Whether or not the shift was deleted. We do "soft-deletes" on shifts.

bdboolean

If the shift ending time was scheduled until business decline.

statusinteger

Whether or not the shift was marked as sick, no-show or late. Defaults to 0:

  • 0: No status
  • 1: Sick
  • 2: No-show
  • 3: Late

late_minutesinteger

If status=3 (Late), then we track how late that employee was when it came time to show up for their shift.

createdstring

A UTC timestamp of when the record was created: 2013-01-01 10:00:00

modifiedstring

A UTC timestamp of when the record was last modified: 2013-01-01 10:00:00

Create

Creates a shift.
» Definition
POST https://api.7shifts.com/v1/shifts
» Request
curl -X POST -d '{ "shift": { "start": "2013-03-03 10:00:00", "end": "2013-03-03 11:00:00", "user_id": 15, "role_id": 33, "location_id": 56 } }' https://api.7shifts.com/v1/shifts \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "shift": {
            "id": 506801
        }
    },
    "message": "Shift added."
}

Read

Retrieves the details from a specific shift.

Arguments

deepinteger

When set to 1, the request will return the following associated objects:

  • location
  • user
  • role
  • department

» Definition
GET https://api.7shifts.com/v1/shifts/{id}
» Request
curl https://api.7shifts.com/v1/shifts/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "shift": {
            "id": 504756,
            "start": "2014-03-30 07:15:00",
            "modified": "2014-03-20 12:43:24",
            "close": false,
            "user_id": 16114,
            "location_id": 5002,
            "notes": "",
            "hourly_wage": 11,
            "open": false,
            "created": "2014-03-20 12:43:20",
            "notified": true,
            "end": "2014-03-30 15:30:00",
            "open_offer_type": 0,
            "department_id": 3000,
            "draft": false,
            "deleted": false,
            "bd": false,
            "status": 0,
            "late_minutes": 0
        }
    },
    "message": ""
}

Update

Updates a shift.
» Definition
PUT https://api.7shifts.com/v1/shifts/{id}
» Request
curl -X PUT -d '{ "shift": { "start": "2013-03-04 09:30:00" } }' https://api.7shifts.com/v1/shifts/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "shift": {
            "id": 5881
        }
    },
    "message": "Shift saved."
}

Delete

Deletes a shift.
» Definition
DELETE https://api.7shifts.com/v1/shifts/{id}
» Request
curl -X DELETE https://api.7shifts.com/v1/shifts/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [],
    "message": "Shift deleted."
}

List

Retrieves a list of shifts belonging to the company you've authenticated with.

Arguments

location_idinteger

Shifts you wish to retrieve by a location id.

start[gte]string

Shifts you wish to retrieve greater than or equal to the passed date/time. Either '2014-01-01 10:00:00' or just a date '2014-01-01'.

start[lte]string

Shifts you wish to retrieve less or equal to than the passed date/time. Either '2014-01-01 10:00:00' or just a date '2014-01-01'.

start[date]string

Shifts you wish to retrieve that start on the specified date. Format it Y-m-d: '2014-01-01'.

department_idinteger

Shifts you wish to retrieve that fall under a department id.

user_idinteger

Shifts you wish to retrieve by a specific user.

deletedinteger

Retrieve shifts that were deleted. Either 0 or 1.

draftinteger

Retrieve shifts that are in draft mode (not published). Either 0 or 1.

openinteger

Retrieve only open shifts.

deepinteger

When set to 1, the request will return the following associated objects:

  • location
  • user
  • role
  • department

limitinteger

The limit of results that will be returned.

offsetinteger

Return results starting from an offset.

order_fieldstring

The field you would like the results to be ordered by. Format is {lowercased-singular-method}.{field}. Example: /shifts/?order_field=shift.modified

order_dirstring

The direction you want the results ordered by. Accepted values are "asc" or "desc". Example: /shifts/?order_dir=desc

» Definition
GET https://api.7shifts.com/v1/shifts
» Request
curl https://api.7shifts.com/v1/shifts \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [
        {
            "shift": {
                "id": 506809,
                "start": "2010-10-10 10:00:00",
                "modified": "2014-03-21 23:25:46",
                "close": false,
                "user_id": 15065,
                "location_id": 5002,
                "notes": "",
                "hourly_wage": 0,
                "open": false,
                "created": "2014-03-21 23:25:46",
                "notified": false,
                "end": "0000-00-00 00:00:00",
                "open_offer_type": 0,
                "department_id": 0,
                "draft": false,
                "deleted": false,
                "bd": false,
                "status": 0,
                "late_minutes": 0
            }
        },
        {
            "shift": {
                "id": 506810,
                "start": "2010-10-10 10:00:00",
                "modified": "2014-03-21 23:26:52",
                "close": false,
                "user_id": 15065,
                "location_id": 5002,
                "notes": "",
                "hourly_wage": 0,
                "open": false,
                "created": "2014-03-21 23:26:52",
                "notified": false,
                "end": "0000-00-00 00:00:00",
                "open_offer_type": 0,
                "department_id": 0,
                "draft": false,
                "deleted": false,
                "bd": false,
                "status": 0,
                "late_minutes": 0
            }
        }
    ],
    "total": 2
}

Scheduled

Check to make sure an employee is scheduled to work the shift they're punching in for.
» Definition
POST https://api.7shifts.com/v1/shifts/scheduled
» Request
curl -X POST -d '{ "punch_id": 1234 }' https://api.7shifts.com/v1/shifts/scheduled \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "shift": {
            "id": 6410270
        },
        "scheduled": true,
        "role": {
            "id": 750,
            "name": "Barback"
        }
    },
    "message": ""
}

Events

The object

idinteger

The id of the event.

titlestring

The title of the event.

descriptionstring

The description of the event.

datestring

The date of the event (YYYY-MM-DD).

startstring

The time that the event starts (24 hour format).
'16:30:00'

colorstring

The 6 character hex color code for the event.
'00ff00'

locationarray

The location id's that are tied to this event.

createdstring

A UTC timestamp of when the record was created: 2013-01-01 10:00:00

modifiedstring

A UTC timestamp of when the record was last modified: 2013-01-01 10:00:00

Create

Creates an event.
» Definition
POST https://api.7shifts.com/v1/events
» Request
curl -X POST -d '{"event": {"title": "Some title", "description": "The event description", "date": "2015-12-30", "start": "16:00:00", "color": "00ff00"}, "location": [234, 324]}' https://api.7shifts.com/v1/events \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "event": {
            "id": 506801
        }
    },
    "message": "Event added."
}

Read

Retrieves the details from a specific event.

Arguments

datestring

Allowing querying all events by a specific date: YYYY-MM-DD

date[gte]string

Grab events where date is greater than equal to a date: YYYY-MM-DD

date[lte]string

Grab events where date is less than equal to a date: YYYY-MM-DD

deepinteger

When set to 1, the request will return the following associated objects:

  • location

» Definition
GET https://api.7shifts.com/v1/events/{id}
» Request
curl https://api.7shifts.com/v1/events/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "event": {
            "id": 504756,
            "title": "Great event",
            "description": "An amazing event where everybody wears green",
            "color": "00ff00",
            "date": "2014-03-30",
            "start": "07:15:00",
            "modified": "2014-03-20 12:43:24"
        }
    },
    "message": ""
}

Update

Updates an event.
» Definition
PUT https://api.7shifts.com/v1/events/{id}
» Request
curl -X PUT -d '{ "event": { "title": "New title" } }' https://api.7shifts.com/v1/events/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "event": {
            "id": 5881
        }
    },
    "message": "Event saved."
}

Delete

Deletes an event.
» Definition
DELETE https://api.7shifts.com/v1/events/{id}
» Request
curl -X DELETE https://api.7shifts.com/v1/events/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [],
    "message": "Event deleted."
}

List

Retrieves a list of events belonging to the company you've authenticated with.

Arguments

datestring

Allowing querying all events by a specific date: YYYY-MM-DD

date[gte]string

Grab events where date is greater than equal to a date: YYYY-MM-DD

date[lte]string

Grab events where date is less than equal to a date: YYYY-MM-DD

deepinteger

When set to 1, the request will return the following associated objects:

  • location

limitinteger

The limit of results that will be returned.

offsetinteger

Return results starting from an offset.

order_fieldstring

The field you would like the results to be ordered by. Format is {lowercased-singular-method}.{field}. Example: /shifts/?order_field=shift.modified

order_dirstring

The direction you want the results ordered by. Accepted values are "asc" or "desc". Example: /shifts/?order_dir=desc

» Definition
GET https://api.7shifts.com/v1/events
» Request
curl https://api.7shifts.com/v1/events \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [
        {
            "event": {
                "id": 504756,
                "title": "Great event",
                "description": "An amazing event where everybody wears green",
                "color": "00ff00",
                "date": "2014-03-30",
                "start": "07:15:00",
                "modified": "2014-03-20 12:43:24"
            }
        },
        {
            "event": {
                "id": 123,
                "title": "Another great event",
                "description": "Even better than the first one!",
                "color": "ffff00",
                "date": "2014-03-30",
                "start": "07:15:00",
                "modified": "2014-03-20 12:43:24"
            }
        }
    ],
    "total": 2
}

Time Punches

If the account you're accessing has the 7punches time clocking add-on enabled, then you will be able to take advantage of the time punch API.

The object

idinteger

The id of the time punch.

shift_idinteger

If the punch is tied to a shift, a shift_id will be present.

user_idinteger

The user associated to the time punch.

location_idinteger

The location associated to the time punch.

department_idinteger

The department associated to the time punch.

approvedbool

If the punch has been approved by a manager.

clocked_instring

The time of the clocked in punch. In a datetime format: 2014-07-01 10:00:00.

clocked_outstring

The time of the clocked out punch. In a datetime format: 2014-07-01 11:30:00.

auto_clocked_outbool

If this time punch was auto clocked out by our system.

clocked_in_offlinebool

If this clock in occurred when the punch pad was in offline mode.

clocked_out_offlinebool

If this clock out occurred when the punch pad was in offline mode.

createdstring

A UTC timestamp of when the record was created: 2013-01-01 10:00:00

modifiedstring

A UTC timestamp of when the record was last modified: 2013-01-01 10:00:00

Create

Creates a time punch. This method does not validate based on company settings. If you're looking to simulate a punch via the terminal, see the /punch method. Returns the newly added punch id if it was successful.
» Definition
POST https://api.7shifts.com/v1/time_punches
» Request
curl -X POST -d '{ "time_punch": { "user_id": 2669, "location_id": 408, "clocked_in": "2014-04-05 06:30:00", "clocked_out": "2014-04-05 10:00:00" } }' https://api.7shifts.com/v1/time_punches \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "time_punch": {
            "id": 43757
        }
    },
    "message": "Punch has been added"
}

Read

Retrieves the details from a time punch.
» Definition
GET https://api.7shifts.com/v1/time_punches/{id}
» Request
curl https://api.7shifts.com/v1/time_punches/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "location": {
            "address": "Westhill ",
            "hash": "685a93bb4b728af1a7b1f7da5cfce896",
            "country": "",
            "id": 408,
            "timezone": "America/Regina",
            "created": "2012-02-21 20:57:33",
            "modified": "2014-06-26 19:40:24"
        },
        "time_punch": {
            "id": 43757,
            "modified": "2014-07-16 00:17:12",
            "auto_clocked_out": false,
            "approved": true,
            "clocked_in": "2014-04-05 07:30:00",
            "user_id": 2669,
            "location_id": 408,
            "shift_id": 0,
            "clocked_out": "2014-04-05 10:00:00",
            "clocked_out_offline": false,
            "created": "2014-07-16 00:12:59",
            "clocked_in_offline": false,
            "department_id": 0
        },
        "department": {
            "id": null,
            "created": null,
            "modified": null,
            "name": null
        },
        "shift": {
            "id": null,
            "start": null,
            "modified": null,
            "department_id": null,
            "close": null,
            "user_id": null,
            "location_id": null,
            "notes": null,
            "deleted": null,
            "hourly_wage": null,
            "open": null,
            "open_offer_type": null,
            "notified": null,
            "end": null,
            "created": null,
            "role_id": null,
            "bd": null,
            "draft": null
        },
        "user": {
            "modified": "2014-07-15 22:23:57",
            "lastname": "Laing",
            "mobile_phone": "",
            "lang": "en",
            "firstname": "Sam",
            "sms_me_shiftpool": false,
            "sms_me_schedules": true,
            "email_me_new_wall_posts": 1,
            "email_me_punch_errors": 1,
            "email_me_schedules": true,
            "home_phone": "",
            "user_type_id": 2,
            "email_me_timeoff_requests": true,
            "id": 2669,
            "company_id": 384,
            "email": "demo@7shifts.com",
            "appear_as_employee": false,
            "email_me_shiftpool_requests": true,
            "email_me_availability_changes": true,
            "email_me_shiftpool": true,
            "sms_me_global_messages": true,
            "notes": "",
            "photo": "http://c3d271dfdd118e5c3eb9-a96684cd08b9718f10ae2fcce5337eaa.r74.cf1.rackcdn.com/0584ce565c824b7b7f50282d9a19945b/9e116bb3d2b70af89aa3e245f28eb7a1.jpg",
            "created": "0000-00-00 00:00:00",
            "sms_me_timeoff_requests": true
        }
    },
    "message": ""
}

Update

Updates a time punch.
» Definition
PUT https://api.7shifts.com/v1/time_punches/{id}
» Request
curl -X PUT -d '{ "time_punch": { "clocked_in": "2014-04-05 07:30:00"} } ' https://api.7shifts.com/v1/time_punches/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "time_punch": {
            "id": 43757
        }
    },
    "message": "Time punch saved."
}

Delete

Deletes a time punch.
» Definition
DELETE https://api.7shifts.com/v1/time_punches/{id}
» Request
curl -X DELETE https://api.7shifts.com/v1/time_punches/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [],
    "message": "Time punch deleted"
}

List

Retrieves a list of time punches belonging to the company you've authenticated with.

Arguments

clocked_in[gte]string

UTC date/time. Time punches you wish to retrieve with the clock in greater than or equal to the date/time value provided. '2013-03-01 10:00:00'

clocked_in[lte]string

UTC date/time. Time punches you wish to retrieve with the clock in less than or equal to the date/time value provided. '2013-03-01 10:00:00'

clocked_out[gte]string

UTC date/time. Time punches you wish to retrieve with the clock out greater than or equal to the date/time value provided. '2013-03-02 10:00:00'

clocked_out[lte]string

UTC date/time. Time punches you wish to retrieve with the clock out less than or equal to the date/time value provided. '2013-03-02 10:00:00'

location_idinteger

Time punches you wish to retrieve by a specific location.

department_idinteger

Time punches you wish to retrieve that fall under a department.

limitinteger

The limit of results that will be returned.

offsetinteger

Return results starting from an offset.

order_fieldstring

The field you would like the results to be ordered by. Format is {lowercased-singular-method}.{field}. Example: /shifts/?order_field=shift.modified

order_dirstring

The direction you want the results ordered by. Accepted values are "asc" or "desc". Example: /shifts/?order_dir=desc

» Definition
GET https://api.7shifts.com/v1/time_punches
» Request
curl https://api.7shifts.com/v1/time_punches \
   -u {API_KEY}:
» Response
{
  "status": "success",
  "data": [
    {
      "time_punch": {
        "id": 25,
        "modified": "2013-12-14 03:10:14",
        "auto_clocked_out": false,
        "approved": true,
        "clocked_in": "2013-12-14 03:10:00",
        "user_id": 2676,
        "location_id": 408,
        "shift_id": 298982,
        "clocked_out_offline": false,
        "tips": 0,
        "notes": "",
        "clocked_out": "2013-12-19 04:40:00",
        "clocked_in_offline": false,
        "created": "2013-12-14 03:10:14",
        "department_id": 21595,
        "role_id": 748
      }
    },
    {
      "time_punch": {
        "id": 77,
        "modified": "2013-12-26 23:28:11",
        "auto_clocked_out": false,
        "approved": true,
        "clocked_in": "2013-12-17 22:15:00",
        "user_id": 13456,
        "location_id": 408,
        "shift_id": 0,
        "clocked_out_offline": false,
        "tips": 0,
        "notes": "",
        "clocked_out": "2013-12-26 23:28:00",
        "clocked_in_offline": false,
        "created": "2013-12-17 22:15:48",
        "department_id": 21595,
        "role_id": 0
      }
    }
  ],
  "offset": 0,
  "total": 195,
  "limit": 20
}

Punches

Simulates a punch. In the example below, we're punching in. The location_hash key can be found in the "locations" object under the field named "hash". The "employee_id" field is the punch id that gets entered under the user profile. This method is used for punching in as well as out. It contains validation and will either accept or reject the punch depending on what preferences have been set for the company.
» Definition
POST https://api.7shifts.com/v1/time_punches/punch
» Request
curl -X POST -d '{ "location_hash": "685a93bb8afgg1a7b1f7da5cf34ce896", "employee_id": 1234 }' https://api.7shifts.com/v1/time_punches/punch \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "punched": "in",
        "message": "Welcome Joan Binfrey",
        "user": {
            "photo_url": "http://c3d271dfdd118e5c3eb9-a96684cd08b9718f10ae2fcce5337eaa.r74.cf1.rackcdn.com/0584ce565c824b7b7f50282d9a19945b/d1b001cc10ebff55686bae2bfcbd26a4.jpg"
        }
    },
    "message": ""
}

Users

The object

idinteger

The id of the user.

mapping_idstring

An optional field to be used for 3rd party integrations.

company_idinteger

The company id that this user belongs to.

firstnamestring

The user's first name.

lastnamestring

The user's last name.

user_type_idinteger

The user type. Possibilities include:

  • 1 (Employee)
  • 3 (Manager)
  • 4 (Assistant manager)

emailstring

The user's email.

photostring

A full URL to the user's profile photo.

mobile_phonestring

The user's mobile number.

home_phonestring

The user's phone number,

hourly_wagefloat

The user's hourly wage,

skill_levelinteger

The user's skill level. Possibilities are:

  • 1
  • 2
  • 3

wage_typestring

Possibilities are:

  • hourly
  • salaried

max_weekly_hoursstring

Maximum weekly hours they're set to work.

employee_idstring

The punch ID that they punch in/out with.

notesstring

Any notes around that employee.

langstring

The language set in their profile.

addressstring

The address in their profile.

citystring

The city in their profile.

prov_statestring

The province/state in their profile.

postal_zipstring

The postal code/zip code in their profile.

appear_as_employeeboolean

If they're appearing in the system as an employee (only for admins).

sortinteger

What order they appear in on the schedules page.

activeboolean

Are they enabled/active in the system.

pushboolean

If the user has push notifications turned on.

hire_datestring

The date the user was hired (YYYY-MM-DD).

sms_me_schedules
sms_me_shiftpool
sms_me_shiftpool_requests
sms_me_timeoff_requests
sms_me_global_messages
mobile_me_wall_posts
mobile_me_logbook_posts
email_me_schedules
email_me_shiftpool
email_me_new_wall_posts
email_me_timeoff_requests
email_me_availability_changes
email_me_shiftpool_requests
email_me_punch_errors
email_me_logbook_posts
createdstring

A UTC timestamp of when the record was created: 2013-01-01 10:00:00

modifiedstring

A UTC timestamp of when the record was last modified: 2013-01-01 10:00:00

Create

Creates a user. In the example below, we're creating a user and assigning this user to a role and multiple locations. This is denoted by passing an array of location ids and/or role ids to the appropriate location and role keys.
» Definition
POST https://api.7shifts.com/v1/users
» Request
curl -X POST -d '{ "user": { "firstname": "Bob", "lastname": "Johnson" }, "location": [{ "id": 1 }, { "id": 3 }], "role": [{ "id": 1, "skill_level": 1, "hourly_wage": 5.00, "primary": 1 }] }' https://api.7shifts.com/v1/users \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "user": {
            "id": 506801
        }
    },
    "message": "User added."
}

Read

Retrieves the details from a specific user.

Arguments

deepinteger

When set to 1, the request will return the following associated objects:

  • company
  • location
  • role
  • department

» Definition
GET https://api.7shifts.com/v1/users/{id}
» Request
curl https://api.7shifts.com/v1/users/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "user": {
            "id": 20645,
            "lastname": "Swanson",
            "firstname": "Joe",
            "company_id": 1932,
            "email": "no@email.com",
            "created": "2014-03-22 00:00:03",
            "photo": "http://path-to-profile/photo.png",
            "modified": "2014-03-22 00:00:03",
            "user_type_id": 1
        }
    },
    "message": ""
}

Update

Updates a user. You can pass location and role keys here as well. NOTE: Whenever you pass an array of location ids and/or role ids, you must re-pass the existing ids they're assigned to. If you forget to, it will remove the existing ids.
» Definition
PUT https://api.7shifts.com/v1/users/{id}
» Request
curl -X PUT -d '{ "user": { "email": "changed@myemail.com" }, "location": [{ "id": 1 }, { "id": 3 }], "role": [{ "id": 1, "skill_level": 1, "hourly_wage": 5.00, "primary": 1 }] }' https://api.7shifts.com/v1/users/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": {
        "user": {
            "id": 5881
        }
    },
    "message": "User saved."
}

Delete

Deletes a user.
» Definition
DELETE https://api.7shifts.com/v1/users/{id}
» Request
curl -X DELETE https://api.7shifts.com/v1/users/{id} \
   -u {API_KEY}:
» Response
{
    "status": "success",
    "data": [],
    "message": "User deleted."
}

List

Coming soon.

We provide phone support to help you get SETUP IN MINUTES

Start Your FREE Trial

Have questions? Chat with us.