Projects

Jobs or cost centres that shifts and timesheets are recorded against. The business may call them something else in Shiftly. Archive a project by changing its status; projects are not deleted.

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

Fields

Project fields
Field	Type	Access	Meaning
id	string	Read-only	The project.
name	string	Writable	The project's name.
code	string	Writable	A short code, unique in the business.
colour	string, may be null	Writable	The colour Shiftly shows it in, as #RRGGBB.
status	"active", "archived"	Writable	active, or archived when it can no longer be picked for new work. Archived projects keep their history.
employee_ids	array of string	Writable	Staff assigned to the project. A manager limited to some locations sees only their own staff here, and a change they make keeps the others.
budget	number, may be null	Read-only	The budget, in dollars. Set in Shiftly. Returned only with pay:read.
linked_to_payroll_tracking	boolean	Read-only	True when the project is linked to a tracking category in the business's payroll.
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 projects

GET/v1/projects

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.
status	"active", "archived"	Optional	Only records in this status.

200 response

{
  "data": [
    {
      "id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "name": "text",
      "code": "text",
      "colour": "text",
      "status": "active",
      "employee_ids": [],
      "budget": 1.5,
      "linked_to_payroll_tracking": true,
      "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.

Create a project

POST/v1/projects

Permission: projects:write

Request body
Field	Type	Required	Meaning
name	string	Required	The project's name.
code	string	Required	A short code, unique in the business.
colour	string	Optional	The colour Shiftly shows it in, as #RRGGBB.
employee_ids	array of string	Optional	Staff assigned to the project. A manager limited to some locations sees only their own staff here, and a change they make keeps the others.

Request body

{
  "name": "text",
  "code": "text",
  "colour": "text",
  "employee_ids": [
    "66f1c2a4b3d9e8f7a6b5c4d3"
  ]
}

201 response

{
  "id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "name": "text",
  "code": "text",
  "colour": "text",
  "status": "active",
  "employee_ids": [
    "66f1c2a4b3d9e8f7a6b5c4d3"
  ],
  "budget": 1.5,
  "linked_to_payroll_tracking": true,
  "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.
409	The error's code is conflict, idempotency_key_reused or request_in_progress. The Errors page describes each code.
422	A field is wrong. The field property names it.
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 project

GET/v1/projects/{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",
  "code": "text",
  "colour": "text",
  "status": "active",
  "employee_ids": [
    "66f1c2a4b3d9e8f7a6b5c4d3"
  ],
  "budget": 1.5,
  "linked_to_payroll_tracking": true,
  "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.

Change or archive a project

PATCH/v1/projects/{id}

Permission: projects:write

Request body
Field	Type	Required	Meaning
name	string	Optional	The project's name.
code	string	Optional	A short code, unique in the business.
colour	string, may be null	Optional	The colour Shiftly shows it in, as #RRGGBB.
employee_ids	array of string	Optional	Staff assigned to the project. A manager limited to some locations sees only their own staff here, and a change they make keeps the others.
status	"active", "archived"	Optional	active, or archived when it can no longer be picked for new work. Archived projects keep their history.

Request body

{
  "name": "text",
  "code": "text",
  "colour": "text",
  "employee_ids": [
    "66f1c2a4b3d9e8f7a6b5c4d3"
  ],
  "status": "active"
}

200 response

{
  "id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "name": "text",
  "code": "text",
  "colour": "text",
  "status": "active",
  "employee_ids": [
    "66f1c2a4b3d9e8f7a6b5c4d3"
  ],
  "budget": 1.5,
  "linked_to_payroll_tracking": true,
  "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.
409	The error's code is conflict, idempotency_key_reused or request_in_progress. The Errors page describes each code.
422	A field is wrong. The field property names it.
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.