Employees

The people who work at the business. A person is added in Shiftly, not through the API. Someone who has left is an archived employment; their own record is no longer shared with the business.

Needs the people:read permission, depending on the operation. The business sees it as "Staff details".

Fields

Employee fields
Field	Type	Access	Meaning
id	string	Read-only	The person.
first_name	string	Read-only	First name.
last_name	string	Read-only	Last name.
middle_names	string, may be null	Read-only	Middle names.
preferred_name	string, may be null	Read-only	The name they go by.
email	string	Read-only	Sign-in email. Read only.
phone_number	string, may be null	Read-only	Australian phone number.
date_of_birth	date, may be null	Read-only	Date of birth.
gender	"M", "F", "I", "N", may be null	Read-only	M, F, I (indeterminate) or N (not stated).
emergency_contact	object, may be null	Read-only	Who to call in an emergency.
address	object, may be null	Read-only	Home address.
employment_id	string, may be null	Read-only	Their employment at this business.
excluded_position_ids	array of string	Read-only	Positions at this business the person may not be rostered to.
location_ids	array of string	Read-only	The locations the person is assigned to. Empty when they can be rostered at any location.
created_at	timestamp	Read-only	When the person's record was created.
updated_at	timestamp	Read-only	When the person's own details last changed.

Operations

List employees

GET/v1/employees

Permission: people: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.

200 response

{
  "data": [
    {
      "id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "first_name": "text",
      "last_name": "text",
      "middle_names": "text",
      "preferred_name": "text",
      "email": "text",
      "phone_number": "text",
      "date_of_birth": "2026-10-06",
      "gender": "M",
      "emergency_contact": {
        "name": null,
        "phone": null,
        "relationship": null
      },
      "address": {
        "street": null,
        "city": null,
        "state": null,
        "post_code": null,
        "country": null
      },
      "employment_id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "excluded_position_ids": [],
      "location_ids": [],
      "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 employee

GET/v1/employees/{id}

Permission: people:read

200 response

{
  "id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "first_name": "text",
  "last_name": "text",
  "middle_names": "text",
  "preferred_name": "text",
  "email": "text",
  "phone_number": "text",
  "date_of_birth": "2026-10-06",
  "gender": "M",
  "emergency_contact": {
    "name": "text",
    "phone": "text",
    "relationship": "text"
  },
  "address": {
    "street": "text",
    "city": "text",
    "state": "text",
    "post_code": "text",
    "country": "text"
  },
  "employment_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "excluded_position_ids": [
    "66f1c2a4b3d9e8f7a6b5c4d3"
  ],
  "location_ids": [
    "66f1c2a4b3d9e8f7a6b5c4d3"
  ],
  "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.

Not available to partner apps

PATCH /v1/employees/{id}
Staff details are changed in Shiftly, not by partner apps.