Positions

The jobs people are rostered into at a location.

Needs one of the settings:read or roster:read or timesheets:read or people:read or leave:read permissions, depending on the operation. The business sees it as "Business details and locations".

Fields

Position fields
Field	Type	Access	Meaning
id	string	Read-only	The position.
name	string	Read-only	The position's name.
description	string, may be null	Read-only	What the position does.
location_id	string	Read-only	The location the position belongs to.
award_id	string, may be null	Read-only	The award shifts in this position are paid under.
group	object, may be null	Read-only	The position group.
active	boolean	Read-only	False when the position is switched off for rostering.
rate_modifier	number, may be null	Read-only	Dollars added to the hourly rate for this position. Returned only with pay:read.
archived	boolean	Read-only	True when the record has been removed in Shiftly.
created_at	timestamp	Read-only	When the record was created.
updated_at	timestamp	Read-only	When the record last changed.

Operations

List positions

GET/v1/positions

Permission: settings:read, roster:read, timesheets:read, people:read, leave:read Needs any one of: settings:read, roster:read, timesheets:read, people:read, leave:read.

Query parameters
Parameter	Type		Meaning
limit	integer, default 50, up to 200	Optional	How many records per page. Up to 200.
after	string	Optional	The next_cursor from the previous page.
updated_since	timestamp	Optional	Only records changed at or after this moment. Pair it with include_archived to see removals.
include_archived	"true", "false"	Optional	Include records that have been archived.
location_id	string	Optional	Only this location.

200 response

{
  "data": [
    {
      "id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "name": "text",
      "description": "text",
      "location_id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "award_id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "group": {
        "id": null,
        "name": null,
        "award_code": null
      },
      "active": true,
      "rate_modifier": 1.5,
      "archived": true,
      "created_at": "2026-10-06T09:00:00+11:00",
      "updated_at": "2026-10-06T09:00:00+11:00"
    }
  ],
  "has_more": true,
  "next_cursor": "text"
}

Refusals
Status	When
400	The error's code is invalid_request or range_too_long. The Errors page describes each code.
401	The error's code is invalid_token or token_expired. The Errors page describes each code.
403	The error's code is origin_not_allowed, permission_denied, not_available, connection_disconnected, connection_suspended or app_suspended. The Errors page describes each code.
404	There is nothing at this address, or no such record in this business.
429	Too many requests. Retry-After says when to try again.
500	Something went wrong at Shiftly. Quote the request id.
503	This environment is not set up for partner apps yet.

Get one position

GET/v1/positions/{id}

Permission: settings:read, roster:read, timesheets:read, people:read, leave:read Needs any one of: settings:read, roster:read, timesheets:read, people:read, leave:read.

200 response

{
  "id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "name": "text",
  "description": "text",
  "location_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "award_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "group": {
    "id": "66f1c2a4b3d9e8f7a6b5c4d3",
    "name": "text",
    "award_code": "text"
  },
  "active": true,
  "rate_modifier": 1.5,
  "archived": true,
  "created_at": "2026-10-06T09:00:00+11:00",
  "updated_at": "2026-10-06T09:00:00+11:00"
}

Refusals
Status	When
400	The error's code is invalid_request or range_too_long. The Errors page describes each code.
401	The error's code is invalid_token or token_expired. The Errors page describes each code.
403	The error's code is origin_not_allowed, permission_denied, not_available, connection_disconnected, connection_suspended or app_suspended. The Errors page describes each code.
404	There is nothing at this address, or no such record in this business.
429	Too many requests. Retry-After says when to try again.
500	Something went wrong at Shiftly. Quote the request id.
503	This environment is not set up for partner apps yet.