/shifts Permission level: 7

get/shifts

Request

  • Base URL
    https://www.humanity.com/api/v2
  • Auth
    API key in query parameter access_token

Query parameters

overnightinteger
start_limitinteger

Works only with mode : Open, it behaves like offset in this case.

end_limitinteger

Works only with mode : Open, it behaves like limit in a combination with start_limit parameter

start_datestring
end_datestring
modestring

Can be one of the following: overview, location, schedule, incomplete, employees, employee, open, openapproval, confirm, onnow, late, upcoming, recent, multiple.<br> If mode is not set, it defaults to 'employee'.

schedulestring

Works only with modes: confirm, location, schedule, employees, where it acts as a position filter. Accepts a string with comma-separated Position IDs

locationinteger

Works only with modes: confirm, employees, where it acts as a location filter. Accepts an integer which represents a Location ID

employeesstring

Works with modes: confirm, employees, where it accepts a string with comma-separated Employee IDs.<br>With modes upcoming, recent, or employee, it accepts only one Employee ID. In all cases it behaves like a filter by employee(s).

detailedinteger

If set to 1, the response will have additional information regarding employees, their conflicts, availability to work, count of shifts in a series if they are part of a series.<br>It's recommended not to use this parameter if not needed because it will make request noticeably slower.

budgetinteger

Works with all modes except for "multiple". Accepted values: 0 or 1. If set to 1, the response will have extra information about budget data entered for the date range between provided start_date and end_date

vacationinteger

[0, 1]

filter_by_sitestring
filter_by_employeestring
filter_by_skillstring
filledinteger

[0, 1]

include_ghost_shiftsboolean

Works only with modes location and schedule. If set to true, the response will include shifts of employees which are assigned to positions listed with the parameter "schedule" or all positions under a location provided with the parameter "location".

fields[shift]string

Use this parameter to return only specific fields in the response, reducing payload size. Pass the resource type in brackets and a comma-separated list of the fields you want included.

Example: https://www.humanity.com/api/v2/shifts?mode=overview&start_date=2026-02-01&end_date=2026-03-01&fields[shift]=employees,schedule,schedule_name,start_timestamp,end_timestamp

Response

200

statusinteger
tokenstring

Example response

{
  "status": 1,
  "data": [
    {
      "id": "321823010",
      "created": "1472128649",
      "published": "1472128658",
      "edited": "1472128649",
      "deleted": "0",
      "schedule": "1324363",
      "type": "0",
      "needed": "0",
      "working": "1",
      "user": "2736727",
      "start_date": {
        "id": 2676,
        "month": 8,
        "day": 26,
        "wday": 5,
        "year": 2016,
        "weekday": "Fri",
        "mname": "Aug",
        "week": 34,
        "dayid": 6,
        "timeid": 45,
        "timeid_exact": 45,
        "formatted": "Aug 26, 2016",
        "time": "11:00am",
        "timestamp": 1472202000,
        "hours": 11,
        "date": "2016-08-26 11:00:00",
        "day_of_year": "238",
        "week_adjusted": 34,
        "sp_wday": 6
      },
      "end_date": {
        "id": 2676,
        "month": 8,
        "day": 26,
        "wday": 5,
        "year": 2016,
        "weekday": "Fri",
        "mname": "Aug",
        "week": 34,
        "dayid": 6,
        "timeid": 73,
        "timeid_exact": 73,
        "formatted": "Aug 26, 2016",
        "time": "6:00pm",
        "timestamp": 1472227200,
        "hours": 18,
        "date": "2016-08-26 18:00:00",
        "day_of_year": "238",
        "week_adjusted": 34,
        "sp_wday": 6
      },
      "length": 7,
      "location": "0",
      "confirmed": "0",
      "ref": "0",
      "start_timestamp": "2016-08-26 11:00:00",
      "end_timestamp": "2016-08-26 18:00:00",
      "traded": "0",
      "absent": "0",
      "perms": "2",
      "schedule_name": "Shop Manager",
      "schedule_color": "29",
      "schedule_location_id": "542311",
      "cost": {
        "staff": 1,
        "hours": 7
      },
      "start_time": {
        "id": 45,
        "time": "11:00am"
      },
      "end_time": {
        "id": 73,
        "time": "6:00pm"
      },
      "paidtime": 7,
      "employees": [
        {
          "id": "2744096",
          "avatar": "0",
          "name": "Michael Rivas",
          "status": "1",
          "notified_day": "0",
          "notified_hour": "0",
          "last_active": "0",
          "ratecard": "0",
          "absent": "0"
        }
      ]
    }
  ],
  "token": "xxxxxxx"
}

Changes