curl

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.

Note: To access the 7shifts Partner API you will require a subscription to 'The Works' package or greater.

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.

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.

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).

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.

The object

status string

Always returns 'error' when an error occurs

message string

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

type string

The type of error that occurred.

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

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

Often missing a required parameter.
500, 502, 503, 504

Server errors

Something went wrong on 7shifts' end.

Example

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

Partner API - Methods

Companies

The object

id integer

The id of the company

name string

The name of the company

country string

The 2 letter uppercased country code

photo string

Full URL to the uploaded company photo

created string

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

modified string

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

Companies Create

Not available through the API.

Companies 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
}

Companies 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."
}

Companies Delete

Not available through the API.

Companies List

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

Arguments

limit integer

The limit of results that will be returned.

offset integer

Return results starting from an offset.

order_field string

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

order_dir string

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

id integer

The id of the department

name string

The name of the department

created string

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

modified string

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

Departments 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."
}

Departments 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": ""
}

Departments 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."
}

Departments 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."
}

Departments List

Arguments

limit integer

The limit of results that will be returned.

offset integer

Return results starting from an offset.

order_field string

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

order_dir string

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

id integer

The id of the location.

address string

The address/name of the location.

country string

A 2 letter country code for the location.

timezone string

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

hash string

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

created string

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

modified string

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

Locations 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."
}

Locations 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": ""
}

Locations 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."
}

Locations 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."
}

Locations List

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

Arguments

limit integer

The limit of results that will be returned.

offset integer

Return results starting from an offset.

order_field string

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

order_dir string

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

id integer

The id of the role.

name string

The name of the role.

color string

6 character hex color of the role

created string

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

modified string

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

Roles 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."
}

Roles 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": ""
}

Roles 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."
}

Roles 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."
}

Roles List

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

Arguments

limit integer

The limit of results that will be returned.

offset integer

Return results starting from an offset.

order_field string

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

order_dir string

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

id integer

The id of the shift.

start string

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

end string

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

location_id integer

The id of the location assigned to this shift.

user_id integer

The id of the user assigned to this shift.

role_id integer

The id of the role assigned to this shift.

department_id integer

The id of the department assigned to this shift.

close boolean

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

notes string

Any notes specific to this shift.

hourly_wage float

The hourly wage for this shift

open boolean

Whether or not this is an "Open Shift"

notified boolean

Notifications have been sent out regarding this shift.

open_offer_type integer

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

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

draft boolean

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

deleted boolean

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

bd boolean

If the shift ending time was scheduled until business decline.

status integer

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_minutes integer

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

created string

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

modified string

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

Shifts 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."
}

Shifts Read

Retrieves the details from a specific shift.

» 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": ""
}

Shifts 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."
}

Shifts 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."
}

Shifts List

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

Arguments

location_id integer

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_id integer

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

user_id integer

Shifts you wish to retrieve by a specific user.

deleted integer

Retrieve shifts that were deleted. Either 0 or 1.

draft integer

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

open integer

Retrieve only open shifts.

limit integer

The limit of results that will be returned.

offset integer

Return results starting from an offset.

order_field string

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

order_dir string

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
}

Shifts 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

id integer

The id of the event.

title string

The title of the event.

description string

The description of the event.

date string

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

start string

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

color string

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

location array

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

created string

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

modified string

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

Events 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."
}

Events Read

Retrieves the details from a specific event.

Arguments

date string

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

» 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": ""
}

Events 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."
}

Events 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."
}

Events List

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

Arguments

date string

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

limit integer

The limit of results that will be returned.

offset integer

Return results starting from an offset.

order_field string

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

order_dir string

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

id integer

The id of the time punch.

shift_id integer

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

user_id integer

The user associated to the time punch.

location_id integer

The location associated to the time punch.

department_id integer

The department associated to the time punch.

approved bool

If the punch has been approved by a manager.

clocked_in string

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

clocked_out string

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

auto_clocked_out bool

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

clocked_in_offline bool

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

clocked_out_offline bool

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

created string

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

modified string

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

Time Punches 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"
}

Time Punches 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": ""
}

Time Punches 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."
}

Time Punches 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"
}

Time Punches 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_id integer

Time punches you wish to retrieve by a specific location.

department_id integer

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

limit integer

The limit of results that will be returned.

offset integer

Return results starting from an offset.

order_field string

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

order_dir string

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
}

Time Punches 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

id integer

The id of the user.

mapping_id string

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

company_id integer

The company id that this user belongs to.

firstname string

The user's first name.

lastname string

The user's last name.

user_type_id integer

The user type. Possibilities include:

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

email string

The user's email.

photo string

A full URL to the user's profile photo.

mobile_phone string

The user's mobile number.

home_phone string

The user's phone number,

hourly_wage float

The user's hourly wage,

skill_level integer

The user's skill level. Possibilities are:

  • 1
  • 2
  • 3

wage_type string

Possibilities are:

  • hourly
  • salaried

max_weekly_hours string

Maximum weekly hours they're set to work.

employee_id string

The punch ID that they punch in/out with.

notes string

Any notes around that employee.

lang string

The language set in their profile.

address string

The address in their profile.

city string

The city in their profile.

prov_state string

The province/state in their profile.

postal_zip string

The postal code/zip code in their profile.

appear_as_employee boolean

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

sort integer

What order they appear in on the schedules page.

active boolean

Are they enabled/active in the system.

push boolean

If the user has push notifications turned on.

hire_date string

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
created string

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

modified string

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

Users 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."
}

Users Read

Retrieves the details from a specific user.

» 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": ""
}

Users 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."
}

Users 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."
    }

Users List

Coming soon.