Assignments

Resource Management OpenAPI Reference (v1)

Welcome to the OpenAPI reference documentation for Resource Management by Smartsheet!

Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL https://help.smartsheet.com/contact
Languages
Servers
https://api.rm.smartsheet.com/api/v1/

API tokens

Resource Management by Smartsheet API Tokens are used to authenticate requests to Resource Management by Smartsheet APIs.

Note: Organizations can manage up to 20 API tokens. Contact us via our Support Page if API Token Management is not enabled for your organization. The first generated token for an organization has a set “primary” title.

Operations

Approvals

In Resource Management by Smartsheet, certain record types are considered “approvable.” Currently, these record types are time entries and expense items. Approvals are created when time entries or expense items are “submitted for approval.”

Operations

Assignables

An assignable in Resource Management by Smartsheet is an object to which an assignment can be made. For example, you can assign a person or placeholder to this object. The following assignable types are accessible from the assignables endpoints:

Note: Although Phases are projects and are assignable, they are inaccessible from the assignables endpoints. Instead, you must access Phases the Projects endpoints or Phases endpoints.

It is useful to understand the Assignables API entity because the Assignments endpoints return an assignable_id to indicate the object to which the assignment is made. Without knowing the object's type, however, it is unclear which endpoint to use to get more details about the object. The assignables endpoints allow you to query directly using the assignable_id from an assignment.

The endpoints supports two actions: index and show.

Note: You can't create a generic assignable or delete one; use the Projects/LeaveTypes endpoints for those actions.

The format of the data objects returned by these endpoints depends on each object's type. If a project, the return value looks exactly like what is returned by the Projects endpoint, and if a LeaveType, the return value looks exactly like what is returned by the Leave types endpoints. In both cases, the return value has a type property, which will be either Project or LeaveType, respectively (phases also have the type Project).

Operations

Assignments

Operations

List assignments

Request

Lists the accessible assignments.

Query
per_pageinteger(int32)(per_page)<= 1000

The maximum number of items to show per response page.

Default 20
Example: per_page=100
pageinteger(int32)(page)>= 1

The response page to return.

Default 1
Example: page=2
fromstring(date)

Filter on assignments that end after this date.

tostring(date)

Filter on assignments that start before this date.

with_phasesboolean

If true, include assignments to phases. Otherwise, exclude them.

Default false
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Acceptstringrequired
Value"application/json"
Example: application/json
curl -i -X GET \
  'https://api.rm.smartsheet.com/api/v1/assignments?from=2019-08-24&page=2&per_page=100&to=2019-08-24&with_phases=false' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'auth: YOUR_API_KEY_HERE'

Responses

The accessible assignments.

Bodyapplication/json
pagingobject(Paging metadata)required
paging.​per_pageinteger(int32)(per_page)<= 1000

The maximum number of items to show per response page.

Default 20
Example: 100
paging.​pageinteger(int32)>= 1

The current response page number.

Default 1
Example: 1
paging.​previousstring or nullread-only

If you're on the first page, this value is null; otherwise the value is the path and query parameters to get the previous page of items.

Example: "/api/v1/users?per_page=1000&page=1"
paging.​selfstringread-only

The path and query parameters to get the current page of items.

Example: "/api/v1/users?per_page=1000&page=2"
paging.​nextstring or nullread-only

If there are more items, this value is the path and query parameters to get the next page of items; otherwise, it's null.

Example: "/api/v1/users?per_page=1000&page=3"
paging.​countinteger or null(int64)>= 0

The total number of items in all the pages.

dataArray of Assignment - percent-based allocation (object) or Assignment - fixed-hours-based allocation (object) or Assignment - hours-per-day-based allocation (object)required
One of:

An assignment set to a percentage of the resource's time.

data[].​allocation_modestringrequired

This indicates that a percentage of the resource's time is allocated to the corresponding assignment.

Value"percent"
Example: "percent"
data[].​percentnumber[ 0 .. 1 ]required

The percentage of time the resource is allocated to the corresponding assignment.

Note: This property is only present when allocation_mode is "percent".

Example: 0.2
data[].​idinteger(int64)>= 1read-only

The unique identifier for the assignment.

Example: 889
data[].​user_idinteger(int64)>= 1

The ID of the user this assignment belongs to.

Example: 5612
data[].​assignable_idinteger(int64)>= 1

The ID of the project, phase, or leave type to which the the assignment applies.

Example: 1234
data[].​starts_atstring(date)required

The assignment's effective start date.

Example: "2025-09-17"
data[].​ends_atstring(date)required

The assignment's effective end date.

Example: "2025-12-17"
data[].​repetition_idinteger or null(int64)>= 1

A unique identifier for a series of repeating assignments. If the assignment is part of a repeating series, this is the parent assignment's unique ID. Otherwise, it's null.

Note: This ID is the same for all assignments within the same repeating series.

Example: 886
data[].​created_atstring(date-time)read-only

The time of creation.

Example: "2025-08-27T12:00:00Z"
data[].​updated_atstring(date-time)read-only

The time of the last update.

Example: "2025-08-27T12:00:00Z"
data[].​all_day_assignmentbooleanread-only
Example: true
data[].​resource_request_idinteger or null(int64)>= 1
Example: null
data[].​bill_ratenumber or null(number)read-only

The cost value.

Example: 100
data[].​bill_rate_idinteger or null(int64)>= 1
Example: 58776516
data[].​statusany or null
data[].​status_option_idinteger or null(int64)>= 1

The ID of the status option associated with the assignment.

Example: 1234567890
data[].​descriptionstring

Describes the assignment.

Example: ""
data[].​noteboolean or null

Calls out ancillary information about the assignment.

Example: null
data[].​subtasksobject
Response
application/json
{
  "paging": {
    "per_page": 100,
    "page": 1,
    "previous": "/api/v1/users?per_page=1000&page=1",
    "self": "/api/v1/users?per_page=1000&page=2",
    "next": "/api/v1/users?per_page=1000&page=3",
    "count": 0
  },
  "data": [
    { … }
  ]
}

Create assignment

Request

Creates an assignment.

Typical parameters:

  • user_id
  • assignable_id
  • starts_at
  • ends_at
  • allocation_mode (percent, hours_per_day, fixed) and a value for the respective mode-named property (that is, a property named percent, hours_per_day, or fixed_hours)

Note: You can create subtasks within the assignment by including them in a subtasks array property, like the one in the request body object below.

For subtask-specific operations, see Subtasks.

{
 "user_id": null,
 "assignable_id": 123,
 "ends_at": "2018-06-27",
 "starts_at": "2018-06-21",
 "status_option_id": 1,
 "description": "Build wireframes",
 "note": null,
 "subtasks": [
   {
     "description": "New Task",
     "completed": false
   }
 ]
}
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Acceptstringrequired
Value"application/json"
Example: application/json
Bodyapplication/json

The property values to apply to a new assignment.

One of:

An assignment set to a percentage of the resource's time.

allocation_modestringrequired

This indicates that a percentage of the resource's time is allocated to the corresponding assignment.

Value"percent"
Example: "percent"
percentnumber[ 0 .. 1 ]required

The percentage of time the resource is allocated to the corresponding assignment.

Note: This property is only present when allocation_mode is "percent".

Example: 0.2
user_idinteger(int64)>= 1required

The ID of the user this assignment belongs to.

Example: 5612
assignable_idinteger(int64)>= 1required

The ID of the project, phase, or leave type to which the the assignment applies.

Example: 1234
starts_atstring(date)required

The assignment's effective start date.

Example: "2025-09-17"
ends_atstring(date)required

The assignment's effective end date.

Example: "2025-12-17"
repetition_idinteger or null(int64)>= 1

A unique identifier for a series of repeating assignments. If the assignment is part of a repeating series, this is the parent assignment's unique ID. Otherwise, it's null.

Note: This ID is the same for all assignments within the same repeating series.

Example: 886
resource_request_idinteger or null(int64)>= 1
Example: null
bill_rate_idinteger or null(int64)>= 1
Example: 58776516
statusany or null
status_option_idinteger or null(int64)>= 1

The ID of the status option associated with the assignment.

Example: 1234567890
descriptionstring

Describes the assignment.

Example: ""
noteboolean or null

Calls out ancillary information about the assignment.

Example: null
subtasksArray of objects
curl -i -X POST \
  https://api.rm.smartsheet.com/api/v1/assignments \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'auth: YOUR_API_KEY_HERE' \
  -d '{
    "allocation_mode": "percent",
    "percent": 0.2,
    "starts_at": "2025-09-17",
    "ends_at": "2025-12-17",
    "user_id": 5612,
    "assignable_id": 1234
  }'

Responses

The new assignment.

Bodyapplication/json
One of:

An assignment set to a percentage of the resource's time.

allocation_modestringrequired

This indicates that a percentage of the resource's time is allocated to the corresponding assignment.

Value"percent"
Example: "percent"
percentnumber[ 0 .. 1 ]required

The percentage of time the resource is allocated to the corresponding assignment.

Note: This property is only present when allocation_mode is "percent".

Example: 0.2
idinteger(int64)>= 1read-only

The unique identifier for the assignment.

Example: 889
user_idinteger(int64)>= 1

The ID of the user this assignment belongs to.

Example: 5612
assignable_idinteger(int64)>= 1

The ID of the project, phase, or leave type to which the the assignment applies.

Example: 1234
starts_atstring(date)required

The assignment's effective start date.

Example: "2025-09-17"
ends_atstring(date)required

The assignment's effective end date.

Example: "2025-12-17"
repetition_idinteger or null(int64)>= 1

A unique identifier for a series of repeating assignments. If the assignment is part of a repeating series, this is the parent assignment's unique ID. Otherwise, it's null.

Note: This ID is the same for all assignments within the same repeating series.

Example: 886
created_atstring(date-time)read-only

The time of creation.

Example: "2025-08-27T12:00:00Z"
updated_atstring(date-time)read-only

The time of the last update.

Example: "2025-08-27T12:00:00Z"
all_day_assignmentbooleanread-only
Example: true
resource_request_idinteger or null(int64)>= 1
Example: null
bill_ratenumber or null(number)read-only

The cost value.

Example: 100
bill_rate_idinteger or null(int64)>= 1
Example: 58776516
statusany or null
status_option_idinteger or null(int64)>= 1

The ID of the status option associated with the assignment.

Example: 1234567890
descriptionstring

Describes the assignment.

Example: ""
noteboolean or null

Calls out ancillary information about the assignment.

Example: null
subtasksobject
Response
application/json
{
  "allocation_mode": "percent",
  "percent": 0.2,
  "id": 889,
  "user_id": 5612,
  "assignable_id": 1234,
  "starts_at": "2025-09-17",
  "ends_at": "2025-12-17",
  "repetition_id": 886,
  "created_at": "2025-08-27T12:00:00Z",
  "updated_at": "2025-08-27T12:00:00Z",
  "all_day_assignment": true,
  "resource_request_id": null,
  "bill_rate": 100,
  "bill_rate_id": 58776516,
  "status": null,
  "status_option_id": 1234567890,
  "description": "",
  "note": null,
  "subtasks": {
    "paging": { … },
    "data": [ … ]
  }
}

Fetch assignment

Request

Returns the matching assignment.

Path
assignment_idinteger(int64)>= 1required

Unique identifier for the resource instance.

Example: 889
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
curl -i -X GET \
  https://api.rm.smartsheet.com/api/v1/assignments/889 \
  -H 'Content-Type: application/json' \
  -H 'auth: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
One of:

An assignment set to a percentage of the resource's time.

allocation_modestringrequired

This indicates that a percentage of the resource's time is allocated to the corresponding assignment.

Value"percent"
Example: "percent"
percentnumber[ 0 .. 1 ]required

The percentage of time the resource is allocated to the corresponding assignment.

Note: This property is only present when allocation_mode is "percent".

Example: 0.2
idinteger(int64)>= 1read-only

The unique identifier for the assignment.

Example: 889
user_idinteger(int64)>= 1

The ID of the user this assignment belongs to.

Example: 5612
assignable_idinteger(int64)>= 1

The ID of the project, phase, or leave type to which the the assignment applies.

Example: 1234
starts_atstring(date)required

The assignment's effective start date.

Example: "2025-09-17"
ends_atstring(date)required

The assignment's effective end date.

Example: "2025-12-17"
repetition_idinteger or null(int64)>= 1

A unique identifier for a series of repeating assignments. If the assignment is part of a repeating series, this is the parent assignment's unique ID. Otherwise, it's null.

Note: This ID is the same for all assignments within the same repeating series.

Example: 886
created_atstring(date-time)read-only

The time of creation.

Example: "2025-08-27T12:00:00Z"
updated_atstring(date-time)read-only

The time of the last update.

Example: "2025-08-27T12:00:00Z"
all_day_assignmentbooleanread-only
Example: true
resource_request_idinteger or null(int64)>= 1
Example: null
bill_ratenumber or null(number)read-only

The cost value.

Example: 100
bill_rate_idinteger or null(int64)>= 1
Example: 58776516
statusany or null
status_option_idinteger or null(int64)>= 1

The ID of the status option associated with the assignment.

Example: 1234567890
descriptionstring

Describes the assignment.

Example: ""
noteboolean or null

Calls out ancillary information about the assignment.

Example: null
Response
application/json
{
  "allocation_mode": "percent",
  "percent": 0.2,
  "id": 889,
  "user_id": 5612,
  "assignable_id": 1234,
  "starts_at": "2025-09-17",
  "ends_at": "2025-12-17",
  "repetition_id": 886,
  "created_at": "2025-08-27T12:00:00Z",
  "updated_at": "2025-08-27T12:00:00Z",
  "all_day_assignment": true,
  "resource_request_id": null,
  "bill_rate": 100,
  "bill_rate_id": 58776516,
  "status": null,
  "status_option_id": 1234567890,
  "description": "",
  "note": null
}

Update assignment

Request

Updates an assignment.

Typical parameters:

  • user_id
  • assignable_id
  • starts_at
  • ends_at
  • allocation_mode (percent, hours_per_day, fixed) and a value for the respective mode-named property (that is, a property named percent, hours_per_day, or fixed_hours)
  • status_option_id
  • description
  • note
Path
assignment_idinteger(int64)>= 1required

Unique identifier for the resource instance.

Example: 889
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Bodyapplication/json

The property values to apply to the assignment.

One of:

An assignment set to a percentage of the resource's time.

allocation_modestringrequired

This indicates that a percentage of the resource's time is allocated to the corresponding assignment.

Value"percent"
Example: "percent"
percentnumber[ 0 .. 1 ]required

The percentage of time the resource is allocated to the corresponding assignment.

Note: This property is only present when allocation_mode is "percent".

Example: 0.2
user_idinteger(int64)>= 1

The ID of the user this assignment belongs to.

Example: 5612
assignable_idinteger(int64)>= 1

The ID of the project, phase, or leave type to which the the assignment applies.

Example: 1234
starts_atstring(date)required

The assignment's effective start date.

Example: "2025-09-17"
ends_atstring(date)required

The assignment's effective end date.

Example: "2025-12-17"
repetition_idinteger or null(int64)>= 1

A unique identifier for a series of repeating assignments. If the assignment is part of a repeating series, this is the parent assignment's unique ID. Otherwise, it's null.

Note: This ID is the same for all assignments within the same repeating series.

Example: 886
resource_request_idinteger or null(int64)>= 1
Example: null
bill_rate_idinteger or null(int64)>= 1
Example: 58776516
statusany or null
status_option_idinteger or null(int64)>= 1

The ID of the status option associated with the assignment.

Example: 1234567890
descriptionstring

Describes the assignment.

Example: ""
noteboolean or null

Calls out ancillary information about the assignment.

Example: null
curl -i -X PUT \
  https://api.rm.smartsheet.com/api/v1/assignments/889 \
  -H 'Content-Type: application/json' \
  -H 'auth: YOUR_API_KEY_HERE' \
  -d '{
    "allocation_mode": "percent",
    "percent": 0.2,
    "starts_at": "2025-09-17",
    "ends_at": "2025-12-17"
  }'

Responses

The updated assignment.

Bodyapplication/json
One of:

An assignment set to a percentage of the resource's time.

allocation_modestringrequired

This indicates that a percentage of the resource's time is allocated to the corresponding assignment.

Value"percent"
Example: "percent"
percentnumber[ 0 .. 1 ]required

The percentage of time the resource is allocated to the corresponding assignment.

Note: This property is only present when allocation_mode is "percent".

Example: 0.2
idinteger(int64)>= 1read-only

The unique identifier for the assignment.

Example: 889
user_idinteger(int64)>= 1

The ID of the user this assignment belongs to.

Example: 5612
assignable_idinteger(int64)>= 1

The ID of the project, phase, or leave type to which the the assignment applies.

Example: 1234
starts_atstring(date)required

The assignment's effective start date.

Example: "2025-09-17"
ends_atstring(date)required

The assignment's effective end date.

Example: "2025-12-17"
repetition_idinteger or null(int64)>= 1

A unique identifier for a series of repeating assignments. If the assignment is part of a repeating series, this is the parent assignment's unique ID. Otherwise, it's null.

Note: This ID is the same for all assignments within the same repeating series.

Example: 886
created_atstring(date-time)read-only

The time of creation.

Example: "2025-08-27T12:00:00Z"
updated_atstring(date-time)read-only

The time of the last update.

Example: "2025-08-27T12:00:00Z"
all_day_assignmentbooleanread-only
Example: true
resource_request_idinteger or null(int64)>= 1
Example: null
bill_ratenumber or null(number)read-only

The cost value.

Example: 100
bill_rate_idinteger or null(int64)>= 1
Example: 58776516
statusany or null
status_option_idinteger or null(int64)>= 1

The ID of the status option associated with the assignment.

Example: 1234567890
descriptionstring

Describes the assignment.

Example: ""
noteboolean or null

Calls out ancillary information about the assignment.

Example: null
Response
application/json
{
  "allocation_mode": "percent",
  "percent": 0.2,
  "id": 889,
  "user_id": 5612,
  "assignable_id": 1234,
  "starts_at": "2025-09-17",
  "ends_at": "2025-12-17",
  "repetition_id": 886,
  "created_at": "2025-08-27T12:00:00Z",
  "updated_at": "2025-08-27T12:00:00Z",
  "all_day_assignment": true,
  "resource_request_id": null,
  "bill_rate": 100,
  "bill_rate_id": 58776516,
  "status": null,
  "status_option_id": 1234567890,
  "description": "",
  "note": null
}

Delete assignment

Request

Deletes the matching assignment.

Path
assignment_idinteger(int64)>= 1required

Unique identifier for the resource instance.

Example: 889
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
curl -i -X DELETE \
  https://api.rm.smartsheet.com/api/v1/assignments/889 \
  -H 'Content-Type: application/json' \
  -H 'auth: YOUR_API_KEY_HERE'

Responses

An empty object.

Bodyapplication/json
object
Response
application/json
{}

Assignments per project

Operations

Assignments per user

These assignment operations center on the assignee.

Operations

Assignments with subtasks

These assignment operations support adding assignments with subtasks and showing subtask completion counts.

Operations

Availabilities

In Resource Management by Smartsheet, we have the concept of a work week. It defines the days of the week that are to be considered work days and the number of work hours for those days. Given this work week, you can determine the number of work hours per day in any given date range. The work week is configurable by an account administrator via the account settings pages.

User availabilities are a mechanism by which you can further customize the work days for individuals in your team. When an individual has a work schedule that deviates from the normal work week observed by your team, say, because they're working part-time during some time period, an administrator can specify that by adding one or more availability time blocks to that user’s profile.

When a user specifies one or more availability time blocks, Resource Management by Smartsheet always considers those in addition to the company's normal work week information.

Operations

Bill rates

Bill rates are maintained at both the account level (defaults) and project level. When a new project is created, the account-level bill rates are used as a template for setting up initial bill rates for the project. Adding a user to the project (for example, by making an assignment) causes additional user-specific rates to be created in the project. These user-specific bill rates are determined by looking up the existing role-specific and discipline-specific rates and matching them up with the user's role and discipline to find the best match.

A phase may have its own bill rate or refer to the parent project. You can add and edit phase-specific bill rates through the user interface of the application. When setting up a phase to have its own bill rate, the parent project bill rates are used as a template, much like the way account default bill rates are used as a template when setting up project bill rates. If a phase is set up to have its own bill rate, adding users to the phase results in user-specific rates being created for the phase, just like it does for projects.

The API allows you to manipulate bill rates directly for projects and phases. However, changing account default bill rates is restricted to Administrators.

Operations

Budget item categories

Budget item categories are lookup value sets for project-specific budgets.

Each category belongs to to one of the following budget types:

  • Expense budget is for non-time-related, currency-based budgeting ($).
  • Fee budget is for currency-based budgeting ($).
  • Time budget is for time-based budgeting (hours).

You can use these categories to classify time entry or expense entry budget line items.

Operations

Budget items

Budget items are always specified with an item_type when accessed through the API. This prevents mixing currency amounts and hours.

A value for item_type could be one of these:

  • Expenses
  • TimeFees
  • TimeFeesDays

Note: TimeFeesDays are actually in unit hours.

Operations

Custom fields

Use custom fields to add properties that provide helpful insights for scheduling, planning, and reporting.

You can use custom fields for people or projects.

  • People: Add properties, including skills, certifications, managers, and organization structure.

  • Projects: Add business-specific criteria to specify properties such as Portfolio Editor, project priority, the likelihood of closing, business unit, project IDs, and location.

You can add multiple custom fields to projects and people and use them as filters on the schedule page, project portfolio page, or reports.

Operations

Custom field values per project

These operations support creating, reading, updating, and deleting custom field values with respect to projects.

Note: In addition to getting custom field values directly, you can also include custom field values as a nested collection when getting projects by specifying custom_field_values in the fields parameter.

For example,

GET /api/v1/projects/<project_id>?fields=custom_field_values

Operations

Custom field values per user

These operations support creating, reading, updating, and deleting custom field values with respect to users.

Note: In addition to getting custom field values directly, you can also include custom field values as a nested collection when getting projects by specifying custom_field_values in the fields parameter.

For example,

GET /api/v1/users/<user_id>?fields=custom_field_values

Operations

Disciplines

Endpoints for reading organization-defined resource disciplines. You must create and manage disciplines via the application UI.

Operations

Expense items

Expense items are reported by a user on a project or leave type.

Note: When creating expense items, at least date and amount need to be specified. Project/Leave Type can be specified by one of project_id, leave_type_id, or an assignable_id. These three parameters refer to the same and are interchangeable. You should only specify one project/leave type parameter per expense item call.

Operations

Holidays

Holidays are dates that your organization treats as non-working days, and entered into Resource Management by Smartsheet by an account administrator. The API provides an endpoint for reading this information.

Operations

Leave types

LeaveType is a subclass of Assignables. You can see the id referring to a project as assignable_id in other models. LeaveType is an assignable that you can assign time to, not being part of a project, such as Vacation.

Find operations for managing and retrieving different types of leave.

Operations

Phases

Phases are a flexible way to break a project into different work stages.

The Phase class is a subclass of Project, which is a subclass of Assignable.

Note: Every phase has a parent project; therefore, the parent_id for a phase is never null. A project's parent_id is always null.

Operations

Placeholder resources

Placeholder resources serve temporary roles on projects where the final resources remain unknown. Placeholders behave similarly to users, with a few differences discussed below.

Bill rates

If you assign a role or discipline to a placeholder, they inherit the account's default bill rates for that role or discipline. You can also create specific bill rates for placeholders using the bill rates API. Specify a placeholder_resource_id as the user_id parameter; no additional parameters are required.

Custom fields

You can create custom fields for placeholders through the application UI.

Time entries

Time tracking for placeholders is not available, meaning it's not possible to create or edit time entries for a placeholder. However, system-generated suggested entries are available for placeholders. When a placeholder is assigned to a project, the system generates scheduled hours based on the type of assignment and updates budget projections, allowing placeholders to be used for forecasting or projection.

Nevertheless, placeholders don't record time, and you can't make explicit time entry modifications for them. You can view system-generated time entries for placeholders through the time entries API by passing the placeholder_resource_ID as the user_id parameter, similar to assignments.

Note: Expense items aren't available for placeholders. Tags for placeholders are also not supported. Use custom fields instead.

Operations

Project members

These operations support setting, viewing, updating, and removing a project's members.

Operations

Project memberships

These operations support setting, viewing, updating, and removing user membership to projects.

Operations

Projects

Projects are the foundation for managing and planning your team's workload.

In the API, each project is a Project object, which is a subclass of Assignable. Sub-projects share the same data model and are called phases.

Note: Every phase has a parent project; therefore, the parent_id for a phase is never null. A project's parent_id is always null.

Note: Other models, such as users, assigned to a project reference that project's id value in via their assignable_id property.

Note: You can use the timeentry_lockout parameter to control whether a project accepts new time entries. For details, see the timeentry_lockout parameter in Create project or Update project.

Operations

Reports API

The reports API allows you to generate custom reports (rows or totals) by defining parameters in the JSON request body.

Incurred time calculation The calc_incurred_using parameter affects how past scheduled time is calculated. When set to confirmed, the report is calculated as if all suggestions were cleared from timesheets. If confirmed-unconfirmed is used (default), filtering out unconfirmed time manually is necessary for accurate incurred calculations.

Note: To include or exclude null values in your filter, specify the string [none] as an element in your filter’s values array.

Operations

Roles

Endpoints for reading organization-defined resource roles. Roles must be created and managed via the application UI.

Operations

Status options

Status options are required in order to set the status_option_id on assignments. This corresponds to the work status in the work list. Status options are account level resources and don't belong to any assignable, user, or assignment.

Operations

Subtasks

Subtasks belong to assignments. They correspond to the checklist of items called a task list, located under work items/assignments in the worklist in the Resource Management application. Subtasks (tasks) can be added to any work item/assignment.

Note: For assignment subtask counts, see the List project assignments operation.

Operations

Tags per project

These endpoints allow you to manage and organize projects by attaching tags. You can perform a "find-or-create" operation to add new tags to a project, or simply link existing tags. You can also disconnect tags from a project without deleting them from your organization. This functionality provides a flexible way to categorize and track projects based on your needs.

Operations

Tags per user

These endpoints allow you to manage and organize users by attaching tags. The API supports a "find-or-create" operation for adding new tags to a user, as well as a way to link existing tags. You can also disconnect a tag from a user without deleting it from your account. This functionality provides a flexible way to categorize and manage users based on their roles, teams, or other criteria.

Operations

Time entries

Time entries are a collection of hours tracked per project and user. There are two types of time entries: suggested and confirmed.

Suggested (unconfirmed) time entries

Suggested time entries (also known as unconfirmed time entries) are created by Resource Management by Smartsheet as a result of resources being assigned to a project. These are identifiable by the is_suggestion: true attribute on the time entry objects. Suggested time entries are read-only and are kept up to date by Resource Management by Smartsheet as the corresponding assignments are updated. They are not returned by the API by default and must be requested using the with_suggestions=true parameter on the GET API call to fetch time entries.

Confirmed time entries

Confirmed time entries are what a user (or the API) has explicitly created to indicate that they have spent some time working on a project. Note that just like in the application UI, you cannot create new confirmed time entries for managed resources via the API. You can read suggested time entries for all users via the API.

Bill rates

Time entries have an associated bill rate attached to them. When a new time entry is created, Resource Management by Smartsheet will determine the appropriate bill rate for it (based on your account and project settings) and assign a values. When reading time entries, you can see this assigned bill rate.

Operations

User status

The User status endpoints provide a comprehensive way to manage and track the current status of team members. This set of endpoints allows you to retrieve a paginated list of all statuses for a specific user, as well as create and update their current status. This helps administrators and team members maintain visibility into who is working, on vacation, or out of the office.

Valid statuses are:

  • ITO: In the office
  • WFH: Working from home
  • SIC: Sick
  • OOO: On the road
  • VAC: Vacation
  • OOF: Out of office
Operations

Users

The users collection allows you to access information about all users in the account.

Operations

Users per project

The Users per project endpoint allows you to retrieve and manage the users who are associated with a specific project. This functionality is essential for project management, as it provides visibility into team composition and allows you to view detailed information about each user's status and assignments within a given project. The API supports a comprehensive set of optional query parameters that enable you to filter and sort the user list to meet your specific needs.

Operations

Webhooks

Webhooks allow you to register, via the API, a webhook that you can use to receive notifications about key events in your account.

Note: For more information on configuring and using webhooks, including details on webhook payloads and update triggers, refer to our detailed Webhooks guide.

Operations

Schemas