Resource Management by Smartsheet API (2024)

The Resource Management by Smartsheet API provides programmatic access to projects, users and time entries in your account, commonly referred to as resources in the rest of this API documentation. The API implements a standard HTTP REST pattern and allows callers with appropriate authentication and authorization to programmatically create, read, update and delete these resources.

API access is available on Pro, Enterprise and Business plans of Resource Management by Smartsheet. As of June 2019, all new plans purchased are Business, and include API access. For customers prior to this date, API access is based on your current plan.

• General information (read first)
  • Pagination
  • Authentication
  • Optional Fields
  • Date/Time Formatting
  • Error Handling
  • Throttling/Rate-limiting

• Contact us via our Support Page
  • Read more on how to report a problem here.
• Have a suggestion for improving our API documentation? Send us a pull-request or email support.

The API provides access to the following data collections in your account via RESTful endpoints.

• Users
  • User Tags
  • Availabilities
• Placeholder Resources
• Assignables
  • Projects
    • Users by Project
    • Project Tags
    • Phases
  • Leave Types
• Custom Fields
• Project Budgets
• Assignments
• Subtasks
• Time Entries
• Expense Etems
• Bill Rates
• Statuses (deprecated)
• Holidays
• Reports
• Status Options
• API Token Management

The Resource Management by Smartsheet API supports webhooks for certain events. See the webhooks section for details.

Our Zapier integration helps you integrating with the Resource Management by Smartsheet API in convenient and powerful ways and connect many other apps and services used by yor team.

• Resource Management by Smartsheet on Zapier
• Getting started with Zapier

A few of our customers have implemented and shared API client libraries to help using the Resource Management by Smartsheet API easier. Depending on your scenario, you may benefit from adopting and improving on them. Here are a couple of references,

• Revelry Labs / ruby / https://github.com/revelrylabs/tenk
• Spindance / ruby / https://github.com/spindance/ten_thousand_feet

Questions or feedback about our API, please submit a support ticket at our Support Page

This documentation assumes that you have either signed up for a Resource Management by Smartsheet trial or you have an active subscription, and that you are familiar with the basic features of the application. The information that follows give you an overview of accessing the same functionality, from an API, so that you can implement additional functionality and custom integrations that meet your specific business needs.

We also assume that you are familiar with basic RESTful API concepts.

 IMPORTANT Do not perform stress or performance testing in any account without informing Resource Management by Smartsheet support and obtaining explicit approval. Violation of this may result in your account being suspended.

Being notified about important changes

There are several ways in which you can stay informed about important changes to the API.

• Ask your friendly account Administrator to add your email as the developer contact for your account.
• Subscribe to be notified when updates are made to this github repo by following it or using the watch feature.

Collections & Objects

The API follows a typical RESTful pattern where it allows you to access collections of objects via HTTP. These Collections are paginated, and are always delivered in a structure that has a ‘data’ array and 'paging’ meta-data, as shown below. This is true top level as well as nested collections.

Some objects returned by the API may have sub-collections. For example, a tags collection for a given user object. These sub-collections are paginated in the same manner as top level collections.

curl -X GET https://api.rm.smartsheet.com/api/v1/users \ -H "Content-Type: application/json" -H "auth: TOKEN"

Will get a JSON response like,

{ "data" : [ { "id" : 1, "first_name" : "Tom", "last_name" : "Perera" }, { "id" : 2, "first_name" : "Jane", "last_name" : "Albert" }, ... ], "paging": { "page": 1, "per_page": 20, "previous": null, "self": "/api/v1/users/1/statuses?user_id=1&per_page=20&page=1", "next": null }}

Unless otherwise noted, the API always responds with JSON.

Pagination

The pagination section in collections provide mechanisms to fetch additional data. The previous and next links provide access to the corresponding pages in the collection. You can override the default per_page value by providing an appropriate value in the URL query parameter. For example,

GET https://api.rm.smartsheet.com/api/v1/users?per_page=100&page=3

per_page should not exceed 1000 rows.

Filtering

Some resources in the Resource Management by Smartsheet API respect certain filtering parameters. Those optional parameters are as follows:

• filter_field - The property to filter on.
• filter_list - The value of filter_field to match.

Authentication

The API currently supports service token based authentication. This can be sent as a query parameter named auth, or as an HTTP header with the same name.

# Token in http header (recommended)curl -X GET https://api.rm.smartsheet.com/api/v1/users \ -H "Content-Type: application/json" -H "auth: TOKEN"# Token on URLcurl -X GET https://api.rm.smartsheet.com/api/v1/users?auth=URL-ENCODED-TOKEN \ -H "Content-Type: application/json"

Account administrators can obtain the API token from Settings > Developer API in the application.

Optional Fields

To reduce the number of roundtrips that might be required to fetch all related data for a given collection or resource (e.g. fetching a user and all their tags), the API supports a concept of optional fields. These fields are a comma separated list of field names that are supported as a URL parameter when making a request to fetch a resource or a resource collection.

curl -X GET https://api.rm.smartsheet.com/api/v1/users?fields=tags \ -H "Content-Type: application/json" -H "auth: TOKEN"

Each field requested is included in the response as nested collections. The page size for these nested collections will be the same as the page size used for the parent API request.

{ "data" : [ { "id" : 1, "first_name" : "Tom", "last_name" : "Perera", "tags": { "data" : [ { "id" : 1, "value" : "developer" }, { "id" : 2, "value" : "javascript" }, ], "paging" : { ... } } }, ... ], "paging": { ... }}

Multiple optional fields can be requested in a single API call like fields=f1,f2.

Date & Time Formatting

The API handles or expects dates and date-time values in various scenarios, and expects the values to be in specific formats.

Date values provided as query parameters when making API calls must be in the 2013-01-31 format.

Time values are accepted in the 2013-09-31T22:10:24Z format, which is a date and time value in UTC time.

Error Handling

Respond with standard HTTP error messages, with 4XX codes to indicate client (caller) errors. There may be an optional response body with a message that has details for debugging / error logging. This message is not meant to end user display or consumption.

HTTP/1.1 400 Bad Request { "message" : "The request body had invalid json" }

Throttling & Rate-Limiting

The API throttles incoming requests to prevent abuse and ensure fair use.

When an application exceeds the rate limit, the API will return a standard HTTP 429 Too Many Requests response.

How to handle being throttled

The specific details of rate limit policies in effect may vary without notice. Application developers should implement detection and handling of rate-limiting behavior using X-Ratelimit-* headers described below.

When a request from your application receives a 429 Too many Requests response, you can check the returned HTTP headers to see your current rate limit status:

X-RateLimit-Limit:120X-RateLimit-Remaining:0X-RateLimit-Reset:1482966442

The X-RateLimit-Reset provides the time at which the current rate limit window resets in UTC epoch seconds.

// pseudo-codeMAX_RETRIES = 25retry_count = 0while(running == true) { response = get_api_response(request_params) // if the server throttled the request, re-try until a valid // response is received or a maximum number of re-try attempts // have been reached // while(response.status == 429 && retry_count < MAX_RETRIES) { // extract the Time in X-RateLimit-Reset x_rate_limit_reset_time = get_x_rate_limit_reset(response) // wait until the rate limit time window has been reset wait_until(x_rate_limit_reset_time) // retry the call response = get_api_response(request_params) retry_count += 1 } handle_response(response) retry_count = 0}

There are several ways you can ask for help or report a problem with using the API.

• For issues that require immediate attention, contact us via our Support Page

When contacting support for assistance with using the API, please provide example API calls where possible. This greatly speeds up the time to resolve support requests. You can use cURL, available on unix platforms as well as windows, to create an example of your scenario, and including the curl command(s) along with your request for support.

Here are some example curl commands;

# get the collection of userscurl -X GET https://api.rm.smartsheet.com/api/v1/users?auth=TOKEN \ -H "Content-Type: application/json"# update user 100 with a new last_namecurl -X PUT https://api.rm.smartsheet.com/api/v1/users/100?auth=TOKEN \ -H "Content-Type: application/json" \ -d '{"last_name":"Silva"'}'

Resource Management by Smartsheet API Tokens are used to authenticate requests to Resource Management by Smartsheet APIs. 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 will have a set “primary” title.

Get tokens

Returns list of tokens for your organization.

Endpoint

GET /api/api_tokens

Sample Response

[ { "id": 1, "title": "primary", "token": <token_string> }, { "id": 2, "title": "secondary", "token": <token_string> }, { "id": 3, "title": null, "token": <token_string> }]

Create token

Create additional tokens for your organization.

Endpoint

POST /api/api_tokens

Optional Query Parameter

Delete token

Deletes the given token.

Endpoint

DELETE /api/api_tokens/<id>

Renew token

Deletes the given token and creates a new token.

Endpoint

POST /api/api_tokens/renew/<id>

Update token title

Update the title of the given token.

Endpoint

PUT /api/api_tokens/<id>

Query Parameter

Endpoint: /api/v1/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.”

List Approvals

GET /api/v1/approvals

While you can get approvals directly from /api/v1/approvals, a more typical scenario is to include approvals when getting time entries or expense items by specifying “approvals” as a field. One advantage of this is that you also get “unsubmitted” records that do not yet have an associated approval record.

Example

GET /api/v1/users/<user_id>/time_entries# note "fields=approvals"curl 'https://api.rm.smartsheet.com/api/v1/users/1/time_entries?fields=approvals&auth=..'

Response

{ "paging": { ... }, "data": [ { "id": 123, "user_id": 1, "hours": 8, "scheduled_hours": null, ... "approvals": { "paging": { ... }, "data": [ { "id": 789, "status": "pending", "approvable_id": 123, "approvable_type": "TimeEntry", "submitted_by": 1, "submitted_at": "2016-10-13T01:52:09Z", "approved_by": null, "approved_at": null, "created_at": "2016-10-13T01:52:09Z", "updated_at": "2016-10-13T01:52:09Z" } ] } }, ... ]}

If you do get approvals from /api/v1/approvals, you can similarly specify “approvables” as a field.

Submitting and Approving Approvables

POST /api/v1/approvals

Approvals are not created or updated directly. Rather, approvable records are submitted or approved through a POST request to /api/v1/approvals. Note that only administrators and portfolio editors can approve time and expenses, which means that API users can only submit time and expenses, but not approve.

Required parameters:

Approvable object:

updated_at is required to ensure that the time entry or expense item has not changed since the submitter or approver has viewed it. For example, if an approver views a time entry of 4 hours and intends to approve that time, but meanwhile someone else updates the time entry to be 5 hours instead of 4, the approver might unintentionally approve a 5 hour time entry while believing they are approving a 4 hour time entry. For this reason, approvals will only be created or updated for approvables that have the correct updated_at value.

Example

POST /api/v1/approvals# request body{ "approvables": [ { "id": 123, "type":"TimeEntry", "updated_at": "2016-10-04T15:33:32Z" } ], "status": "pending"}

Response

{ "paging": { ... }, "data": [ { "id": 890, "status": "pending", "approvable_id": 123, "approvable_type": "TimeEntry", "submitted_by": 8, "submitted_at": "2016-10-13T20:16:40Z", "approved_by": null, "approved_at": null, "created_at": "2016-10-13T20:16:40Z", "updated_at": "2016-10-13T20:16:40Z" } ]}

Deleting Approvals

DELETE /api/v1/approvals/<approval_id>

Approvals can only be deleted if the status is “pending”.

Endpoint: /api/v1/assignables

An assignable in Resource Management by Smartsheet Plans is an object to which an assignment can be made, i.e. a person, placeholder, etc. can be assigned to this object. Currently, there are two types of assignables in Resource Management by Smartsheet Plans, Projects and Leave Types. Phases are also an assignable, but they can be accessed through the projects endpoint.

It is useful to have an understanding of Assignables as an API entity because the Assignments endpoint returns an assignable-id to indicate the object to which the assignment is made, but without knowing the type of that object, it is not clear which endpoint to use to get more details about the object if desired. The assignables endpoint allows you to query directly using the assignable-id from an assignment.

The endpoint supports two actions, index and show. It is not possible to create a generic assignable or to delete one, the Projects/LeaveTypes endpoints should be used for those actions.

List Assignables (index)

GET /api/v1/assignables curl 'https://api.rm.smartsheet.com/api/v1/assignables?auth=...'

Show an Assignable

GET /api/v1/assignables/<assignable-id> curl 'https://api.rm.smartsheet.com/api/v1/assignables/12345?auth=...'

Return values based on type

The format returned by this endpoint depends on the type of the object returned. If a project, the return value will look exactly like what is returned by the Projects endpoint, and if a LeaveType, the return value looks exactly like what is returned by the LeaveTypes endpoint. In both cases, the return value has a type property, which will be Project or LeaveType, respectively (phases also have the type Project).

Sample Response

{"paging": { "per_page":20, "page":1,"previous":null, "self":"/api/v1/assignables?&page=1", "next":null },"data": [ { "id":1, "description":null, "guid":"bd5fa048-b3f4-467a-a3b5-18211d488d21", "name":"Vacation", "deleted_at”:null, "type":"LeaveType", }, { "id":4, "description":null, "guid":"76c4d8d0-4351-4842-8da2-de715d3a37e5", "name":"Project A", "deleted_at":null, "type":"Project", "starts_at":"2018-09-15", "ends_at":"2018-09-19", "parent_id":null, "phase_name":null, "thumbnail":null, "project_code":"", "timeentry_lockout":-1, "client":"" }]}

Endpoint: /api/v1/assignments

Endpoint: /api/v1/users/<user_id>/assignments

Endpoint: /api/v1/projects/<project_id>/assignments

Assignments connect a User to a Project or a Phase (part of a project) or a LeaveType.

List all assignments

Optional parameters:

GET /api/v1/assignments curl 'https://api.rm.smartsheet.com/api/v1/assignments?auth=..'

List assignments for a User or Project

Optional parameters:

GET /api/v1/users/<user_id>/assignments curl 'https://api.rm.smartsheet.com/api/v1/users/<user_id>/assignments?auth=..'

GET /api/v1/projects/<project_id>/assignments curl 'https://api.rm.smartsheet.com/api/v1/projects/<project_id>/assignments?auth=..'

Show an Assignment

GET /api/v1/assignments/<assignment_id> curl 'https://api.rm.smartsheet.com/api/v1/assignments/<assignment_id>?auth=..'

Show an Assignment for a User or Project

GET /api/v1/users/<user_id>/assignments/<assignment_id> curl 'https://api.rm.smartsheet.com/api/v1/users/<user_id>/assignments/<assignment_id>?auth=..'

GET /api/v1/projects/project_id/assignments/<assignment_id> curl 'https://api.rm.smartsheet.com/api/v1/projects/<project_id>/assignments/<assignment_id>?auth=..'

Similarly, in the create and delete examples below, you can call the assignments API on projects specifying a user_id to create an assignment for that user, or to delete an assignment.

Create an Assignment

Typical parameters: starts_at, ends_at, allocation_mode (percent, hours_per_day, fixed), percent, hours_per_day, fixed_hours

POST /api/v1/users/<user_id>/assignments curl -d 'leave_id=<leave_id>&starts_at=<YEAR-MO-DAY>&ends_at=<YEAR-MO-DAY>' \ 'https://api.rm.smartsheet.com/api/v1/users/<user_id>/assignments?auth=...' curl -d 'leave_id=<leave_id>&starts_at=<YEAR-MO-DAY>&ends_at=<YEAR-MO-DAY>&percent=0.25' \ 'https://api.rm.smartsheet.com/api/v1/users/<user_id>/assignments?auth=...' curl -d 'leave_id=<leave_id>&starts_at=<YEAR-MO-DAY>&ends_at=<YEAR-MO-DAY>&allocation_mode=hours_per_day&hours_per_day=<hours>' \ 'https://api.rm.smartsheet.com/api/v1/users/<user_id>/assignments?auth=...'

Update an Assignment

Typical parameters: starts_at, ends_at, allocation_mode (percent, hours_per_day, fixed), percent, hours_per_day, fixed_hours, status_option_id, description, note

curl -XPUT -d 'description=<description>&percent=<DECIMAL>&starts_at=<YEAR-MO-DAY>' \ 'https//api.rm.smartsheet.com/api/v1/assignments/<assignment_id>?auth=...'

Remove an Assignment for a User

DELETE /api/v1/users/<user_id>/assignments/<assignment_id> curl -XDELETE 'https://api.rm.smartsheet.com/api/v1/users/<user_id>/assignments/<assignment_id>?auth=...'

Sample Response

{ "data": [ { "id":889, "allocation_mode":"percent", "percent":1.0 /* only present when allocation_mode is percent */, "hours_per_day":8 /* only present when allocation_mode is hours_per_day */, "fixed_hours":8 /* only present when allocation_mode is fixed */, "user_id":5612, "assignable_id":123, "ends_at":"2013-10-07", "starts_at":"2013-10-03", "bill_rate":1.0, "bill_rate_id":0 "repetition_id:" 886, }, ... ], "paging": { "next": null, "page": 1, "per_page": 20, "previous": null, "self": "/api/v1/users/1/assignments?user_id=1&per_page=20&page=1" }}

Notes: repetition_id is used for repeated assignments. The value will be NULL when the assignment is not part or a repeating series. repetition_id is equal to the parent assignment.

Endpoint: /api/v1/assignments

This endpoint allows an assignment to be created with subtasks. It takes all the same post parameters as a regular assignment create with the addition of the subtasks POST parameter. This endpoint returns the assignment object created with the nested subtasks created within it.

Endpoint

POST /api/v1/assignments

Params

Example POST params

POST { "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 } ]}

Example JSON Response

{ "data": [ { "id": 12345, "allocation_mode": "percent", "percent": 1, "user_id": null, "assignable_id": 123, "ends_at": "2018-06-27", "starts_at": "2018-06-21", "bill_rate": null, "bill_rate_id": null, "repetition_id": null, "created_at": "2018-06-21T23:01:09Z", "updated_at": "2018-06-21T23:01:09Z", "all_day_assignment": true, "resource_request_id": null, "status": null, "status_option_id": 1, "description": "Build wireframes", "note": null, "subtasks": { "paging": { "self": "/api/v1/assignments/12345/subtasks?per_page=20&page=1", "next": null, "previous": null, "page": 1, "per_page": 20 }, "data": [ { "id": 436, "assignment_id": 12345, "assignable_id": 123, "description": "New Task", "completed": false, "updated_at": "2018-11-01T20:00:34Z", "created_at": "2018-11-01T20:00:34Z", "updated_by": 1 } ] } }, ...}

Endpoint: /api/v1/projects/<project_id>/assignments?fields=subtasks_counts

This endpoint returns an array of subtasks counts for completed and total subtasks under each assignment record. This endpoint is a view-only endpoint.

Example JSON Response

{ "data": [ { "id": 12345, "allocation_mode": "percent", "percent": 1, "user_id": null, "assignable_id": 123, "ends_at": "2018-06-27", "starts_at": "2018-06-21", "bill_rate": null, "bill_rate_id": null, "repetition_id": null, "created_at": "2018-06-21T23:01:09Z", "updated_at": "2018-06-21T23:01:09Z", "all_day_assignment": true, "resource_request_id": null, "status": null, "status_option_id": 1, "description": "Build wireframes", "note": null, "subtask_counts": { "completed": 5, "total": 10 } }, ...}

Bill rates in Resource Management by Smartsheet 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 and discipline specific rates and matching them up with the user’s role and discipline to find the best match.

A phase is a child project and 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 directly manipulate project and phase specific bill rates. Changing account default bill rates are restricted to Administrators.

Endpoints:

Account specific bill rates

GET /api/v1/bill_rates

Project specific bill rates

GET /api/v1/projects/<project_id>/bill_ratesGET /api/v1/projects/<project_id>/bill_rates/<id>PUT /api/v1/projects/<project_id>/bill_rates/<id>POST /api/v1/projects/<project_id>/bill_rates

Optional Query Parameters

Fields:

Project-specific bill rates editable via the API require a valid assignable_id attribute value.

Project and user specific bill rate must not specify a role_id or discipline_id, because a specific user has been chosen and role and discipline do not apply for such a bill rate.

See more examples below.

Examples

A bill rate should have the following JSON structure:

/* project default rate */{ "id":991618, "rate":100.0, "discipline_id":null, "role_id":30, "assignable_id":1234, "user_id":null, "starts_at":null, "ends_at":null, "created_at":"2013-09-27T22:10:24Z", "updated_at":"2013-09-27T22:10:24Z"}/* project rate for discipline id 15 */{ "id":991618, "rate":100.0, "discipline_id":15, "role_id":30, "assignable_id":1234, "user_id":null, "starts_at":null, "ends_at":null, "created_at":"2013-09-27T22:10:24Z", "updated_at":"2013-09-27T22:10:24Z"}

Account-specific bill rates will not have an assignable_id or a user_id, and will look like below. They may optionally have a role_id or discipline_id, to indicate a default rate for that role and/or discipline.

{ "id":991618, "rate":200.0, "discipline_id":null, "role_id":null, "assignable_id":null, "user_id":null, "starts_at":null, "ends_at":null, "created_at":"2013-09-27T22:10:24Z", "updated_at":"2013-09-27T22:10:24Z"}

User-specific bill rates on a project will have an assignable_id and a user_id. They may optionally also have a starts_at and ends_at values to indicate that the particular rate is applicable to a specific date range. When date range-specific bill rates are added via the API, they will be preferred over the default rate for the same user. This preference is determined based on the start date of the assignment or time entry in question.

{ "id":991618, "rate":100.0, "discipline_id":null, "role_id":null, "assignable_id":123, "user_id":1001, "starts_at":"2013-09-27T00:00:00Z", "ends_at":null, "created_at":"2013-09-27T22:10:24Z", "updated_at":"2013-09-27T22:10:24Z"}

Budget item categories are a set of lookup values for your organization which can be used for specifying project specific budgets. These categories may represent a fee budget, a time budget, or an expense budget. The same categories may be used when reporting time or expenses to classify the budget line item the entry is to be counted against.

There is an account level definition of budget categories, made available via:

/api/v1/time_entry_categories

or

/api/v1/expense_item_categories 

in the format:

{ "data": [ { "category": "Time Fees Category 1", "id": 1083 }, { "category": "Time Fees Category 2", "id": 1084 } ], "paging": { "next": null, "page": 1, "per_page": 20, "previous": null, "self": "/api/v1/time_entry_categories?per_page=20&page=1" }}

Project Specific

There is also a set of budget item categories defined at each project level, available via:

/api/v1/projects/<project_id>/time_entry_categories

or

/api/v1/projects/<project_id>/expense_item_categories

Here you get the actual budget line items defined for the project. The specific categories applicable to the project can be extracted through these.

{ "id": 1132, "assignable_id": null, "assignable_parent_id": null, "category": 'Printing Material', "amount": 123, "item_type": "TimeFees", "peritem_amount": null, "peritem_label": null, "created_at": "2013-09-26T20:35:14Z", "updated_at": "2013-09-26T20:35:14Z"}

Note that at the project level, category may also be null. This implies a project budget line item that is not assigned any particular category.

Fetching a Collection

GET /api/v1/time_entry_categories

or

GET /api/v1/expense_item_categories

Sample Response

{ "data": [ { "category": “Design Fees", "id": 1083 }, { "category": “Stationary", "id": 1084 } ], "paging": { "next": null, "page": 1, "per_page": 20, "previous": null, "self": “/api/v1/time_entry_categories?per_page=20&page=1" }}

Endpoint: /api/v1/projects/<project_id>/budget_items?item_type=...

Budget items are always specified with an “item_type” when accessed through the api. This is to keep from mixing amount and hours.

Value for item_type could be one of TimeFees / TimeFeesDays / Expenses

TimeFeesDays are actually in unit hours.

List Budget Items

Required Parameters:

item_type: (one of TimeFees / TimeFeesDays / Expenses)

GET /api/v1/projects/<project_id>/budget_items curl "https://api.rm.smartsheet.com/api/v1/projects/12345/budget_items?item_type=TimeFees&auth=..

Show Budget Item by id

curl "https://api.rm.smartsheet.com/api/v1/budget_items/6789?auth=... curl "https://api.rm.smartsheet.com/api/v1/projects/12345/budget_items/6789?auth=...

Create a Budget Item

Required Parameters:

item_type: (one of TimeFees / TimeFeesDays / Expenses)amount: value

curl -d "amount=5000&item_type=TimeFees" \ "https://api.rm.smartsheet.com/api/v1/projects/4/budget_items?auth=..."

Update Budget Item by id

curl -XPUT -d "amount=567" \ "https://api.rm.smartsheet.com/api/v1/budget_items/6789?auth=..." or curl -XPUT -d "amount=567" \ "https://api.rm.smartsheet.com/api/v1/projects/12345/budget_items/6789?auth=..."

Delete a Budget Item

curl -XDELETE "https://api.rm.smartsheet.com/api/v1/budget_items/6789?auth=..."

Sample Response

{ "data": [ { "amount": 20.0, "assignable_id": 4, "assignable_parent_id": null, "category": "Dragging our Feet", "created_at": "2013-09-12T20:09:46Z", "id": 4, "item_type": "TimeFeesDays", "peritem_amount": null, "peritem_label": null, "updated_at": "2013-09-12T20:09:46Z" } ], "paging": { "next": null, "page": 1, "per_page": 20, "previous": null, "self": "/api/v1/projects/4/budget_items?item_type=TimeFeesDays&project_id=4&per_page=20&page=1" }}

Custom Fields

Endpoint /api/v1/custom_fields

Fields:

Creating Custom Fields

POST /api/v1/custom_fields

Required parameters:

Optional parameters:

Example:POST /api/v1/custom_fields{ "name": "Skills", "namespace": "users", "is_visible_on_info_page": true, "is_visible_as_filter": true, "data_type": "multiple_choice_selection_list", "options": [ "Audio/Video", "Graphic Design", "UX", "Analytics", "Python", "Ruby", "JavaScript" ]}

Updating Custom Fields

PUT /api/v1/custom_fields/<custom_field_id>

Editable parameters:

:warning: When removing a value from options that is also the default_value, the default_value needs to be updated as well.

Getting Custom Fields

GET /api/v1/custom_fieldsGET /api/v1/custom_fields/<custom_field_id>

Deleting Custom Fields

DELETE /api/v1/custom_fields/<custom_field_id>

Deleting a custom field will also delete all of its associated custom field values.

Custom Field Values

Endpoints

/api/v1/projects/<project_id>/custom_field_values/api/v1/users/<user_id>/custom_field_values

Fields:

Creating Custom Field Values

POST /api/v1/projects/<project_id>/custom_field_valuesPOST /api/v1/users/<user_id>/custom_field_values

Required parameters:

Note: Only custom fields with a data_type of multiple_choice_selection_list can accept an array with multiple values as its value in a POST request. Note that this array is treated as the complete set of values for the given custom field and project/user. Subsequent POST requests for the same custom field and project/user will result in the deletion of previous values if those values are not also included in the value array. In other words, subsequent POST requests do not append new values, but rather replace the set of values as a whole.

Updating Custom Field Values

PUT /api/v1/projects/<project_id>/custom_field_values/<id>PUT /api/v1/users/<user_id>/custom_field_values/<id>

Editable parameters:

Getting Custom Field Values

GET /api/v1/projects/<project_id>/custom_field_valuesGET /api/v1/users/<user_id>/custom_field_values

In addition to getting custom field values directly, you can also include custom field values as a nested collection when getting users or projects by specifying custom_field_values in the fields parameter.GET /api/v1/projects/<project_id>?fields=custom_field_valuesGET /api/v1/users/<user_id>?fields=custom_field_values

Deleting Custom Field Values

Custom field values cannot be deleted directly. To delete all custom field values that belong to a specific custom field, you can delete that custom field itself, and all associated values will be deleted as well.

Disciplines currently must be created and assigned through the UI.

Endpoints:

• Get Disciplines
• Get a Discipline

Get Disciplines

• GET /api/v1/disciplines will return a paginated list of Disciplines.

Optional parameters:

• Respects filtering parameters

Example JSON Response

{ "paging": { "per_page": 20, "page": 1, "previous": null, "self": "/api/v1/disciplines?&page=1", "next": null }, "data": [ { "id": 1, "value": "JavaScript Developer" }, { "id": 2, "value": "Ruby Developer" } ]}

Get a Discipline

• GET /api/v1/disciplines/1 will return the role with the ID of 1.

Example JSON Response

{ "id": 1, "value": "Developer"}

Endpoint: /api/v1/users/<user_id>/expense_items

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

List Expense Items for a User

Optional parameters:

Expenses by User

GET /api/v1/users/<user_id>/expense_itemsGET /api/v1/users/<user_id>/expense_items/<id>

Expenses by Project

GET /api/v1/projects/<project_id>/expense_itemsGET /api/v1/projects/<project_id>/expense_items/<id>

Create Expense Item

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.

| date | amount | leave_type_id | project_id | assignable_id |

POST /api/v1/users/<user_id>/expense_items

Update an Expense Item

PUT /api/v1/projects/<project_id>/users/<user_id>/expense_items/<expense_item_id>

Delete an Expense Item

DELETE /api/v1/users/<user_id>/expense_items/<expense_items_id>

Sample Response

{ "data": [ { "id": 1, "assignable_id": 32, "assignable_type": "Project", "user_id": 2, "amount": 10, "date": "2015-04-09", "category": null, "notes": "Testing exp", "created_at": "2015-04-09T21:54:13Z", "updated_at": "2015-04-09T21:54:13Z" } ] { "paging": { "per_page": 100, "page": 1, "previous": null, "self": "/api/v1/users/2/expense_items?per_page=100&user_id=2&page=1", "next": null }}

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.

Endpoints:

GET /api/v1/holidays

Optional Query Parameters

Fields:

Examples

A holiday has the following JSON structure:

{ "id": 20019, "date": "2015-01-01", "name": "New Years Day", "created_at": "2015-10-23T04:16:36Z", "updated_at": "2016-08-24T23:44:16Z"}

Endpoint: /api/v1/leave_types

LeaveType is a subclass of Assignable. You will see the id refering 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.

List Leave Types (index)

GET /api/v1/leave_types curl 'https://api.rm.smartsheet.com/api/v1/leave_types?auth=...'

Show a LeaveType

GET /api/v1/leave_types/<leave_type_id> curl 'https://api.rm.smartsheet.com/api/v1/leave_types/12345?auth=...'

Sample Response

{ "data": [ { "id": 2, "name": "Sick", "description": null, "guid": "FAFC777B-8CD2-4434-9C0E-59366A1A65B9", "deleted_at": null, "created_at": "2013-09-10T21:31:06Z", "updated_at": "2013-09-10T21:31:06Z" } ], "paging": { "next": null, "page": 1, "per_page": 20, "previous": null, "self": "/api/v1/leave_types?per_page=20&page=1" }}

Endpoint: /api/v1/projects/<project_id>/phases

Phase is a subclass of Project which is a subclass of Assignable. You will see the id refering to a project as assignable_id in other models. A Phase always has a parent_id set to the id of the parent Project.

List Phases for a Project

GET /api/v1/projects/<project_id>/phases curl 'https://api.rm.smartsheet.com/api/v1/projects/[project_id]/phases?auth=...'

Create a Phase for a Project

curl -d "phase_name=Winding%20up&starts_at=2013-09-15&ends_at=2013-09-16" \ "https://api.rm.smartsheet.com/api/v1/projects/[project_id]/phases?auth=..."

Update a Phase for a Project

curl -XPUT -d "phase_name=Another%20Name&" \ "https://api.rm.smartsheet.com/api/v1/projects/[project_id]/phases/456?auth=..."

Bill Rates

If you wish for the phase to inherit the parent project’s bill rates after create, the use_parent_bill_rates flag can be passed with a PUT request as follows:

curl -XPUT -d "use_parent_bill_rates=true" \ "https://api.rm.smartsheet.com/api/v1/projects/[project_id]/phases/456?auth=..."

Delete a Phase for a Project

curl -i -X DELETE "https://api.rm.smartsheet.com/api/v1/projects/[project_id]/phases/[phase_id]?auth=..."

NOTE: A phase cannot be deleted unless it contains no assignments.

Endpoint: /api/v1/placeholder_resources

Placeholder resources can be used for temporary resourcing on projects where the final resources are not yet known. Placeholders behave quite similarly to users, with a few differences discussed below.

List Placeholder Resources (index)

Optional Parameters:

GET /api/v1/placeholder_resources curl 'https://api.rm.smartsheet.com/api/v1/placeholder_resources?fields=assignments,custom_field_values&auth=...'

Note that custom field values can only be accessed if custom fields are enabled for the account. This is only possible for pro plans and up. See custom fields for details.

Show Placeholder

Optional Parameters:

GET /api/v1/placeholder_resources/<placeholder_resource_id> curl 'https://api.rm.smartsheet.com/api/v1/placeholder_resources/12345?fields=assignments&auth=...'

Create a Placeholder Resource

Required Parameters

• title

POST /api/v1/placeholder_resources curl -d 'title=Designer' \ 'https://api.rm.smartsheet.com/api/v1/placeholder_resources?auth=...'

Placeholders are referred to by title. The title is displayed wherever placeholders appear in the application e.g., on projects, the schedule, etc. Therefore, it is required to specify this parameter.

Optional Parameters:

Parameters not exposed through the API

In the application’s user interface, there are certain options available when creating and editing placeholder resources. For example, if a role and discipline are selected, the placeholder title is auto-populated as a combination of discipline and role. For example, a placeholder with discipline ‘Engineering’ and role 'Director’ would be auto-assigned the title 'Engineering, Director’. Options also exist to upload a thumbnail image for the placeholder, or to choose a color and abbreviation and then auto-generate a thumbnail. These options are currently not available through the API, and can only be used via the user interface.

Update a Placeholder

Placeholder specified by id

PUT /api/v1/placeholder_resources/<placeholder_resource_id> curl -XPUT -d 'title=Senior Designer' \ 'https://api.rm.smartsheet.com/api/v1/placeholder_resources/12345?auth=...'

Delete a Placeholder

Placeholder resources may be deleted via the API, as follows.

DELETE /api/v1/placeholder_resources/<placeholder_resource_id> curl -XDELETE \ 'https://api.rm.smartsheet.com/api/v1/placeholder_resources/12345?auth=...'

Placeholders and Users/People

As noted above, placeholders behave similarly to real users in certain cases. However, there are some key differences. Here we discuss ways in which placeholders can be used similar to users in the API, and ways they are different.

Placeholder Assignments

Assignments can be made, updated, and removed via the Assignments API just as they can for users.The only difference is that this is accessed through the placeholder_resources endpoint. In general, for the Assignments API, a placeholder resource ID can be used as the user_id parameter.

GET /api/v1/placeholder_resources/<placeholder_resource_id>/assignments curl 'https://api.rm.smartsheet.com/api/v1/placeholder_resources/12345/assignments?&auth=...'

Placeholder Bill Rates

If a placeholder is given a role/discipline, they will inherit account default bill rates for that role/discipline. Specific bill rates can also be created for placeholders using the bill rates API. A placeholder ID can be specified as the user_id parameter. No additional parameters are required.

Placeholder Custom Fields

Custom fields can be created for placeholders through the application UI. API docs coming soon.

Placeholder Time Entries

Time tracking for placeholders is not supported - i.e. it is not possible to create or edit time entries for a placeholder. However, system-generated suggested entries are supported for placeholders. When a placeholder is assigned to a project, the system will generate scheduled hours based on the type of assignment and update budget projections, so that placeholders can be used for forecasting/projection. However, placeholders do not incur time, and no explicit time entry changes can be made for them. System-generated time entries for placeholders can be viewed via the time entries API, by passing in the placeholder ID as the user_id parameter, similar to assignments.

Not Supported: Expense Items and Tags

Expense items are not available for placeholders.

Tags for placeholders are also not supported. Custom fields should be used instead.

Placeholders on a Project

Similar to users on a project, you can get the placeholder resources assigned to a project using the following API endpoint:

/api/v1/projects/<project_id>/placeholder_resources

Endpoint: /api/v1/projects/<project_id>/tags

There are two ways to list project tags:

• Get a list of tags for a single project using the /api/v1/projects/<project_id>/tags endpoint.
• Adding the parameter fields=tags when listing/viewing through /api/v1/projects

Attaching a tag to a project is technically a “find-or-create” operation. If you post a tag with information that does not exist for your organization it will be created and attached to the project specified. If the tag already exists, it will just be attached. If you try to create the same tag multiple times, it will just be attached once.

curl -d "value=Awesome" "https://api.rm.smartsheet.com/api/v1/projects/1/tags?auth=..."

Disconnect a tag from a project

You can remove a tag from a project without deleting it from your account settings by using the /api/v1/projects endpoint.

curl -XDELETE "https://api.rm.smartsheet.com/api/v1/projects/1/tags/456?auth=..."

{ "data": [ { "id": 31, "value": "MyFirstTag" } ], "paging": { "next": null, "page": 1, "per_page": 20, "previous": null, "self": "/api/v1/projects/1/tags?project_id=1&per_page=20&page=1" }}

Endpoint: /api/v1/users/:id/project_memberships

Endpoint: /api/v1/projects/:id/project_members

The first endpoint will return a set of project_ids given a user_id. The second endpoint will return a set of user_ids given a single project_id.

Project Memberships

List

GET /api/v1/users/:id/project_memberships?membership=level

GET|POST /api/v1/relationships/project_memberships?user_ids=id,id,id&membership=level

Both will get a list of Projects which the user or users are a member of, at the provided level.In the case where no membership level is given, the GET defaults to member ie. any level. Valid membership levels include: member, viewer, reporter, scheduler, and editor.

Result: Paginated API result, data field will consist of tuples that look similar to the following:{"id": 1234, uid: "Project-1234", name: "Project Name"}

Set

POST /api/v1/users/:id/project_memberships

This API call replaces the user’s project memberships. JSON body should include a relationships field with [project_id, membership_level] tuples.

NOTE: This replaces the membership list. If you leave off a project, the user will be REMOVED from that project. If the user was already a member of a project, their membership will be changed to the level specified. If the user was not previously a member of a project, they will be added with the level specified.

PUT /api/v1/users/:id/project_memberships

This API call updates the user’s project memberships. JSON body should include a relationships field with [project_id, membership_level] tuples.

NOTE: This updates the membership list. If you leave off a project, the user’s relationship to that project will be unchanged. If the user was already a member of a project, their membership will be changed to the level specified. If the user was not previously a member of a project, they will be added with the level specified.

Remove

DELETE /api/v1/users/:id/project_memberships

This API call removes the single user from the project’s membership list. JSON body should include a project_ids field, which is an array of [project_id, project_id, ...].

Project Members

This section contains endpoints pertaining to the members of a particular project.

List

GET /api/v1/projects/:id/project_members?membership=level

GET|POST /api/v1/relationships/project_members?project_ids=id,id,id&membership=level

Both will get a list of Users who are members of the project or projects, at the provided level.In the case where no membership level is given, the GET defaults to member ie. any level. Valid membership levels include: member, viewer, reporter, scheduler, and editor.

Result: Paginated API result, data field will consist of tuples that look similar to the following:{"id": 1234, uid: "User-1234", name: "User's Name"}

Set

POST /api/v1/projects/:id/project_members

This API call replaces the project’s membership list. JSON body should include a relationships field with [user_id, membership_level] tuples.

NOTE: This replaces the membership list. If you leave off a project, the user will be REMOVED from that project. If the user was already a member of a project, their membership will be changed to the level specified. If the user was not previously a member of a project, they will be added with the level specified.

PUT /api/v1/projects/:id/project_members

This API call updates the project’s membership list. JSON body should include a relationships field with [user_id, membership_level] tuples.

NOTE: This updates the membership list. If you leave off a project, the user’s relationship to that project will be unchanged. If the user was already a member of a project, their membership will be changed to the level specified. If the user was not previously a member of a project, they will be added with the level specified.

Remove

DELETE /api/v1/projects/:id/project_members

This API call removes users from the project’s membership list. JSON body should include a user_ids field, which is an array of [user_id, user_id, ...].

Endpoint: /api/v1/projects/<project_id>/users

List Users for a given Project

Users are associated to a project by Assignments.

Optional Parameters:

List Users

GET /api/v1/projects/<project_id>/users curl 'https://api.rm.smartsheet.com/api/v1/projects/project_id/users?fields=tags,assignments&auth=...'

Endpoint: /api/v1/projects

Project is a subclass of Assignable. You will see the id referring to a project as assignable_id in other models. Sub-projects are called phases and share the same data model. A Phase has a parent_id that is not null. A project or phase can be deleted by setting the optional archived parameter to true, it can also be unarchived by setting archived to false.

Projects where archived is set to true cannot be updated. You must first unarchive (set archived to false) before updating the project.

Project State

project_state describes the state of the project:

• Confirmed
• Tentative
• Internal

List Projects (index)

Optional Parameters:

List projects

GET /api/v1/projects?fields=tags,budget_items

List projects with archived

GET /api/v1/projects?fields=tags,budget_items&with_archived=true

Notes: Set with_archived to true to include archived projects in searches. Set archived to true to archive a project. Set archived to false to unarchive a project.

List projects with sorting

GET /api/v1/projects?sort_field=created&sort_order=ascending

Filter projects

GET /api/v1/projects?filter_field=project_state&filter_list=Confirmed

Notes: project_state is the only supported filter field at present.

Show a project

GET /api/v1/projects/<project_id>

Show a project with its phases

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

Create a project

Note: You cannot add thumbnails to the project through the API

POST /api/v1/projects{"name": "My Project","starts_at": "2015-03-01","ends_at": "2015-06-01"}

Update a Project

Note: You cannot add thumbnails to the project through the API

PUT /api/v1/projects/1245{ "id": 1245, "name": "New Project Name", "ends_at": "2015-05-31"}

Locking Time Entries

timeentry_lockout is used to control when new time entries are no longer accepted to a project.

Note that positive integer values in this attribute are numbers of days relative to today’s date on the calendar. We do not support setting this lockout value to a specific date.

If your project has phases, note that this must also be set for each phase assignable_id for it to take effect as intended.

Delete a Project

DELETE /api/v1/projects/1245

Notes:

Dates need to be in UTC

Sample Response

GET https://api.rm.smartsheet.com/api/v1/projects/<project_id>?fields=tags,summary,children,has_pending_updates&today=27-07-2016&per_page=100&auth=<token>

{ "id":821065, "archived":false, "archived_at":null, "description":"", "guid": "xxxx-xxxx-xxxx-xxxx-xxxx-xxxx", "name":"Resource Management by Smartsheet Example for Wayne", "parent_id":null, "phase_name":null, "project_code":"", "secureurl":"https://10kftprojectimages.s3.amazonaws.com/a62ffd30-316f-4cb6-9c7f-eca45d07a35d/499af1a7-bc6b-446f-8535-4472e6159246.png", "secureurl_expiration":"3000-01-01T00:00:00Z", "settings":0, "timeentry_lockout":-1, "ends_at":"2015-12-31", "starts_at":"2015-01-01", "deleted_at":null, "created_at":"2015-11-06T18:00:40Z", "updated_at":"2016-04-19T18:21:16Z", "use_parent_bill_rates":false, "thumbnail":"https://10kftprojectimages.s3.amazonaws.com/a62ffd30-316f-4cb6-9c7f-eca45d07a35d/499af1a7-bc6b-446f-8535-4472e6159246.png", "type":"Project", "has_pending_updates":false, "client":null, "project_state":"Internal", "tags":{ "paging":{ "self":"/api/v1/projects/821065/tags?per_page=1&page=1", "next":null, "previous":null, "page":1, "per_page":1 }, "data":[ { "id":1207009, "value":"Sales" } ] }, "children":{ "paging":{ "self":"/api/v1/projects/821065/tags?per_page=100&page=1", "next":null, "previous":null, "page":1, "per_page":100 }, "data":[ ] }, "bounding_startdate":"2015-01-01", "bounding_enddate":"2016-07-01", "confirmed_hours":1283.600000000003, "confirmed_dollars":160450.0, "approved_hours":0, "approved_dollars":0, "unconfirmed_hours":87.60000000000002, "unconfirmed_dollars":10950.0, "scheduled_hours":1322.400000000003, "scheduled_dollars":165300.0, "future_hours":0, "future_dollars":0}

The reports endpoints allow you to generate report rows or totals by specifying the parameters of a report in the JSON payload of a POST request. The response is a JSON representation of the report rows or totals as seen in the reports UI.

Endpoints

• /api/v1/reports/rows
• /api/v1/reports/totals

Parameters

With the exception of today and calc_incurred_using, each of the following parameters has a corresponding menu in the reports UI.

Example Request Params:

// POST /api/v1/reports/rows{ "view": "time_fees_hours", "time_frame": "this_week", "group_by": ["project_id", "user_id"], "filters": { "client": { "operation": "inclusion", "values": ["Mango Inc."] }, "people_tags": { "operation": "exclusion", "values": ["intern"] } }, "today": "2018-03-28", "calc_incurred_using": "confirmed-unconfirmed"}

Example Response:

{ "params": { "view": "time_fees_hours", // ... Other request params }, "dates": { "today": "2018-03-28", "range": { "from": "2018-03-26", "to": "2018-04-01" } }, "rows": [ { "project_id": 1771900, "project_name": "Design Planning & Management", "user_id": 200088, "user_name": "Bobby Taleb", "incurred_hours": 6, "scheduled_hours": 10, "difference_from_past_scheduled_hours": 0, "future_scheduled_hours": 4, "total_hours": 10 }, // ... More rows ]}

view

There are currently ten supported views, which correspond to the reports available in the reports UI. The view determines which columns are returned.

Time and Fees

• time_fees_hours
• time_fees_days
• time_fees_amounts
• time_fees_hours_and_amounts
• time_fees_days_and_amounts

Budgets

• budgets_hours
• budgets_days
• budgets_amounts

Utilization, Expenses

• utilization
• expenses

time_frame

The time frame of a report is specified as an object with “from” and “to” attributes that each specify a date in the format YYYY-MM-DD.

"time_frame": { "from": "2018-01-01", "to": "2018-12-31"}

There are also several shortcut strings for common time frames.

• this_week
• this_month
• this_quarter
• this_year
• last_week
• last_month
• last_quarter
• last_year
• next_30
• next_60
• next_90
• last_30
• last_60
• last_90
• last_and_next_90

group_by

The group_by param is an array of strings that specify which attributes to group and sort rows by. Note that, while the reports UI restricts grouping to 2 levels, the API currently allows up to 5 levels.

"group_by": ["client", "phase_name", "user_id", "date"]

The following are all the valid attributes that rows can be grouped by. Note that utilization reports have an additional restriction such that rows can only be grouped by user attributes or date attributes.

User Attributes

• user_id
• role
• discipline
• location
• assignment_status

Date Attributes

• date
• week
• month

Assignable Attributes

• project_id
• client
• leave_type
• project_type
• project_state
• phase_name

Time Entry or Expense Attributes

• record_type
• entry_type
• category
• approval_status
• approved_by

filters

Attributes that can be used as grouping values can also be used as filters. Additionally, the following attributes can be used as filters as well.

• people_tags
• project_tags
• custom_fields

The filters parameter is expected to be an object where the keys are the attribute names, and the values are objects that specify what to filter on. The filter objects are expected to specify an operation and an array of values. operation can be either inclusion or exclusion. The values array may contain either integers or strings, depending on the attribute.

"filters": { "project_id": { "operation": "inclusion", "values": [432, 561, 642] }, "people_tags": { "operation": "exclusion", "values": ["intern"] }}

Filtering on custom_fields is slightly different in that, instead of a single object with an operation and values, the expectation is an array of objects, each with an operation, values, and id, which is the custom field id.

"filters": { "custom_fields": [ { "id": 4321, "operation": "inclusion", "values": ["E", "S", "R"] }, { "id": 5678, "operation": "exclusion", "values": ["tentative"] } ]}

today

The today param is the date on which past/incurred time ends and future scheduled time begins. The expected format is “YYYY-MM-DD”.

calc_incurred_using

There are 3 options for calculating incurred time:

• confirmed-unconfirmed (default, always used in reports UI)
• confirmed
• approved

The reports UI always uses confirmed-unconfirmed. If your account settings specify that incurred time should use confirmed time only, the reports UI will still use the confirmed-unconfirmed option, but will additionally apply a default filter on entry_type, removing unconfirmed time, which has the same effect with regards to incurred calculations.

"calc_incurred_using": "confirmed-unconfirmed","filters": { "entry_type": { "operation": "exclusion", "values": ["Unconfirmed"] }}

The only difference between the two methods (filtering out unconfirmed time vs specifying calc_incurred_using as confirmed) is in how past scheduled time is calculated in the case where no corresponding confirmed time exists for a given day of an assignment. Filtering out unconfirmed time affects both incurred and past scheduled time, whereas specifying calc_incurred_using as confirmed does not affect past scheduled time. One way to think about it is, when calc_incurred_using is set to confirmed, the report is calculated as if the “clear suggestions” button was pushed on everyone’s timesheets.

Roles currently must be created and assigned through the UI.

Endpoints:

• Get Roles
• Get a Role

Get Roles

• GET /api/v1/roles will return a paginated list of Roles.

Optional parameters:

• Respects filtering parameters

Example JSON Response

{ "paging": { "per_page": 20, "page": 1, "previous": null, "self": "/api/v1/roles?&page=1", "next": null }, "data": [ { "id": 1, "value": "Senior" }, { "id": 2, "value": "Junior" } ]}

Get a Role

• GET /api/v1/roles/1 will return the role with the ID of 1.

Example JSON Response

{ "id": 1, "value": "Senior"}

Endpoint: /api/v1/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 do not belong to any assignable, user, or assignment.

Create a status option

POST /api/v1/status_options

Required params

Valid colors

• blue_bright
• blue_dark
• green_bright
• green_dark
• yellow
• orange
• red
• purple

Valid stages

• planned
• in_progress
• done

Example

POST { "color": "green_bright", "label": "On Track", "stage": "in_progress", "order": 100.0}

List status options

GET /api/v1/status_options

Get list with deleted options.GET /api/v1/status_options?with_deleted=true

Show a single status option

GET /api/v1/status_options/<status_option_id>

Update a status option

PUT /api/v1/status_options/<status_option_id>

Delete a status option

DELETE /api/v1/status_options/<status_option_id>

In order to maintain consistency with historical data, deleting a status option only flags the resource as deleted. It does not permanently destroy the record.

Endpoint: /api/v1/projects/<project_id>/assignments/<assignment_id>/subtasks

Subtasks belong to assignments. They correspond to the checklist of items called a tasklist listed under work items/assignments in the worklist. Tasks are an optional addition to any work item/assignment.

Create a subtask

POST /api/v1/projects/<project_id>/assignments/<assignment_id>/subtasks

Required params

Optional params

Example

POST { "description": "Create wireframe", "completed": true,}

List subtasks

GET /api/v1/projects/:project_id/assignments/:assignment_id/subtasks

Show a single subtask

GET /api/v1/projects/:project_id/assignments/:assignment_id/subtasks/<subtask_id>

Update a subtask

PUT /api/v1/projects/:project_id/assignments/:assignment_id/subtasks/<subtask_id>

Delete a subtask

DELETE /api/v1/projects/:project_id/assignments/:assignment_id/subtasks/<subtask_id>

Deleting a subtask will permantently destroy the record. For updates to subtasks we record the user_id of the last update and the time of the last update.

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 know 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 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.

Suggested time entries are read-only and are kept up to date by Resource Management by Smartsheet as the corresponding assignments are updated.

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.

Fields

Endpoints:

# Time entries by userGET /api/v1/users/<user_id>/time_entriesGET /api/v1/users/<user_id>/time_entries/<id># Time entries for given date-rangeGET /api/v1/users/<user_id>/time_entries?from=2017-03-14&to=2017-03-21# Time entries by projectGET /api/v1/projects/<project_id>/time_entriesGET /api/v1/projects/<project_id>/time_entries/<id># All time entries in the accountGET /api/v1/time_entriesGET /api/v1/time_entries/<id># Time entries for given date-rangeGET /api/v1/time_entries?from=2017-03-14&to=2017-03-21# Updating a time entryPUT /api/v1/users/<user_id>/time_entries/id# Deleting a time entryDELETE /api/v1/users/<user_id>/time_entries/id

Optional Query Parameters:

IMPORTANT: to and from must be a valid date formatted as yyyy-mm-dd

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.

Creating Time Entries

When creating time entries, a valid user_id, assignable_id, date and hours must be supplied. Assignable id can be assignable_id, project_id or leave_type_id.

You can optionally specify values for task and notes, which must be fewer than 256 characters in length. If you know a valid bill_rate_id matching the user and project of the time entry, you can specify that at the time of creating a time entry as well.

POST /api/v1/users/<user_id>/time_entries{ "user_id": <user_id>, "assignable_id": 1001, "date": "2012-01-21", "hours": 0.5, "task": 'Travel', "notes": 'Drive to Seattle, WA to meet with Resource Management by Smartsheet'}

Note that the user_id in the URL must match the user_id in the POST data in the above example. In this example, the user_id in post data is optional. Similar rules apply when you manipulate time entries within a project time entries collection, like below

POST /api/v1/projects/<project_id>/time_entries{ "user_id": 123, "assignable_id": <project_id>, "date": "2012-01-01", "hours": 4.0,}

Examples

A confirmed time entry (note is_suggestion is false).

{ "id":100001, "user_id": 123, "assignable_id": 1001, "assignable_type": "Project", "date": "2013-09-11", "hours": 8.0, "is_suggestion": false, "scheduled_hours": null, "task": null, "bill_rate": 150, "bill_rate_id": 4, "created_at": "2013-09-12T04:32:28Z", "updated_at": "2013-09-18T04:32:28Z"}

A suggested time entry (note is_suggestion is true) and hours are given in scheduled_hours instead of hours. Task and notes are null in suggested time entries as well.

{ "id":100000, "user_id": 123, "assignable_id": 1001, "assignable_type": "Project", "date": "2013-09-11", "hours": null, "is_suggestion": true, "scheduled_hours": 8.0, "task": null, "notes": null, "bill_rate": 150, "bill_rate_id": 4, "created_at": "2013-09-12T04:32:28Z", "updated_at": "2013-09-18T04:32:28Z"}

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 are 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 has one or more availability time blocks specified, Resource Management by Smartsheet will always take those into consideration in addition to the normal work week information of the company.

NB: In the current version of the API, updating part time availabilities will NOT automatically update existing assignments and their suggested time entries to match.

Days 0

Day0 represents Sunday of the week, day1 Monday and so on. This is irrespective of the values of start and end dates for a given availability block.

Start and End

Availability block start and end dates specify a date range during which the given custom available hours apply. Both starts_at and ends_at values are optional. If starts_at is nil, it implies that the given availabilities are to be used infinitely into the past. Similarly a null ends_at implies that the values are to be used infinitely into the future.

Overlapping date ranges in multiple availability blocks for the same user are accepted but will produce unpredictable results.

Endpoints:

GET /api/v1/users/<user_id>/availabilitiesGET /api/v1/users/<user_id>/availabilities/<id>PUT /api/v1/users/<user_id>/availabilities/<id>DELETE /api/v1/users/<user_id>/availabilities/<id>POST /api/v1/users/<user_id>/availabilities

Fields:

See more examples below.

Examples

An availability block should have the following JSON structure:

{ "id": 52, "user_id": 269, "starts_at": "2017-01-30", "ends_at": "2017-07-28", "day0": 0, "day1": 8, "day2": 8, "day3": 4, "day4": 8, "day5": 8, "day6": 0,}

Endpoint: /api/v1/users/<user_id>/statuses

Current status for a user is a collection of Statuses.

Valid statuses are:

• ITO (In the Office)
• WFH (Working from home)
• SIC (Sick)
• OOO ( On the Road)
• VAC (Vacation)
• OOF (Out of office)

A new “current status” is set by simply creating a new status for the user.

Show List of Statuses For a User

GET /api/v1/users/statuses curl "https://api.rm.smartsheet.com/api/v1/users/7/statuses?auth=..."

Create/update status for a user

Required Parameter:

| status |

Optional parameters:

| assignable_id | current_task | status | end | message |

Usage

POST /api/v1/users/<user_id>/statuses curl -d 'status=OOO' \ 'https://api.rm.smartsheet.com/api/v1/users/12345/statuses?auth=...''

Sample Response

{ "data": [ { "assignable_id": 4, "created_at": "2013-09-12T14:33:05Z", "current_task": null, "end": null, "id": 1, "message": "Hacking away", "start": null, "status": "ITO", "updated_at": "2013-09-12T14:33:05Z", "user_id": 1 } ], "paging": { "next": null, "page": 1, "per_page": 20, "previous": null, "self": "/api/v1/users/1/statuses?user_id=1&per_page=20&page=1" }}

Endpoint: /api/v1/users/<user_id>/tags

There are two ways to list user tags:

• Get a list of tags for a single user using the /api/v1/user/<user_id>/tags endpoint.
• Adding the parameter fields=tags when listing/viewing through /api/v1/users

Attaching a tag to a user is technically a “find-or-create” operation. If you post a tag with information that does not exist for your organization it will be created and attached to the user specified. If the tag already exists, it will just be attached. If you try to create the same tag multiple times, it will just be attached once.

curl -d "value=Awesome" "https://api.rm.smartsheet.com/api/v1/users/1/tags?auth=..."

Disconnect a tag from a user

You can remove a tag from a user without deleting it from your account settings by using the /api/v1/users endpoint.

curl -XDELETE "https://api.rm.smartsheet.com/api/v1/users/1/tags/456?auth=..."

{ "data": [ { "id": 31, "value": "MyFirstTag" } ], "paging": { "next": null, "page": 1, "per_page": 20, "previous": null, "self": "/api/v1/users/1/tags?user_id=1&per_page=20&page=1" }}

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

Optional parameters:

Endpoints

GET /api/v1/usersGET /api/v1/users/<id>PUT /api/v1/users/<id>POST /api/v1/users

Fields:

Deleting vs Archiving

A user cannot be deleted via the API but they may be archived by setting the optional parameter archived to true while updating a user. It can also be unarchived by setting the optional parameter archived to false. You cannot archive the account owner.

User Type

Information about a user’s role is contained in the user_type_id property.

Values not described in this list are reserved for internal/future use.

API users may set the user_type_id of a user to any value except 1 (Administrator). Updating a user to be an administrator must be done through the app.

License Type

Information about the user’s license type is contained in the license_type property. Accepted values are currently licensed and managed_resource. Both types count toward the applicable limits on your plan. See Settings > People in Resource Management by Smartsheet for more information.

Sample Response

{ "id": 1, "first_name": "Chris", "last_name": "James", "display_name": "Chris James", "email": "chris@example.com", "user_type_id": 1, "billable": true, "hire_date": null, "termination_date": null, "mobile_phone": null, "office_phone": null, "archived": false, "archived_at": null, "deleted": false, "deleted_at": null, "account_owner": false, "invitation_pending": false, "user_settings": 1376392, "guid": "96d769c7-1b4e-4b07-8baf-5ed6f2b915aa", "employee_number": null, "role": "Senior", "discipline": "Program Management", "location": "Seattle", "type": "User", "license_type": "licensed", "billability_target": 100, "billrate": -1, "has_login": true, "login_type": "saml", "thumbnail": "", "approver_user_ids": [123, 456, 789], "approvee_user_ids": [222, 333, 444], "last_login_time": "2022-02-17T19:12:36Z", "created_at": "2015-11-13T20:38:10Z", "updated_at": "2015-11-13T20:38:10Z"}

Endpoint: /api/v1/webhooks

Webhooks allow users to register, via the API, a webhookthat they can use to receive notifications about key events in their account.Currently, webhooks are supported for the following events.

List Webhooks

GET /api/v1/webhooks

Lists all the webhooks for your organization.

Example

GET /api/v1/webhooks/curl 'https://api.rm.smartsheet.com/api/v1/webhooks?&auth=..'

Response

{ "paging": { ... }, "data": [ { "id":1, "organization_id":1, "url":"https://hooks.example.com/process_webhooks", "status":"active", "event_type":"project.created" } ]}

Response Fields

Webhook Status

Currently, the only valid status for a webhook is ‘active’. This field is reserved for future extensions of the webhooks API.

Creating a webhook

POST /api/v1/webhooks

Required parameters:

Both parameters are required. The 'event_type’ must be one of the supported types mentioned above.The url must be https with a valid host.

Deleting a webhook

DELETE /api/v1/webhooks/<webhook_id>

Updating a webhook

This is currently not permitted.

Webhook Limits

To prevent repetitive posting of the same webhook payload, no more than 10 webhooks per event type are permitted.

Webhook Payloads

When a webhook is registered for a particular event type with the Resource Management by Smartsheet API,every time an event of that type occurs, a POST is made to the webhook URL containingdata about the affected object. For example, if a webhook is registered for the project.createdevent, every time a new project is created, a POST with the details of the created project is made to thewebhook’s URL. This POST data is known as the webhook payload. A webhook payload looks like this:

{ "data": { [ data about the object] }, "type": [event type]}

The “type” field indicates what type of event occurred, and is always one of the event types listed above.The “data” field is exactly the same as what would be returned if the actual objectwere fetched through the API via a GET call. Refer to the Projects, Users,Time Entries and Assignments documentation for the exact format and return valuesfor the GET output. The data is exactly the same as a simple GET call output, with no additional fieldsrequested. It is not possible to request additional fields in the webhook payload, e.g. to request custom field valuesor bill rates or other data that can be requested through the 'fields’ parameter in typical API calls. If such additionaldata is needed when processing a webhook, it is recommended that you make a GET request using the object ID returned inthe webhook payload, and specify any additional fields there.

When do Updated Events fire?

Some of our data types, such as projects and users, are fairly complex and have other 'associated’ data types such as bill rates, custom fields, etc. that are not direct properties of the object itself. We explain here what types of changes will cause updated events to trigger. Note that when an updated event fires, the payload is the same as a created event i.e. it contains data describing the object, but no specific information as to what changed. In the future, more information may be added, but currently, it is not supported.

Assignments

For assignments, any permitted change to an assignment (dates, allocation mode, percent, etc.) will trigger an updated event. Note: Changing the assignee will trigger an assignment.deleted followed by an assignment.created event. We handle assignee changes differently than other attributes internally.

Time Entries

For time entries, any permitted change such as (hours, notes, etc.) will trigger an updated event.

Projects

For projects, the following changes will trigger update events.

• Basic project property changes: name, start date, end date, project type, etc.

The following changes do not trigger updated events.

• Creating assignments for users on a project (though these are reported as assignment events)
• Changing or adding project budgets
• Changing or adding project bill rates
• Adding/editing tags or custom fields to a project
• Adding or change project custom fields

Some of these triggers do not exist yet because this is a newer feature. We expect update support to improve.Adding phases to a project does trigger an event, but it is a separate event for phase creation, not a project update event (see the section on phases below).

Phases

While separate webhooks for phase events do not exist, phase create and update events will be reported onproject.created and project.updated webhooks.

Users

For users, the following changes will trigger update events.

• Basic property changes: name, email, etc.
• Role, discipline and location changes
• Availability and bill rate changes
• Tag and custom field changes

The following changes do not trigger updated events.

• Creating assignments for users on a project (though these are reported as assignment events)

What should you return from your webhook processing code?

Resource Management by Smartsheet keeps track of return values from webhook processing code, and if a webhook is behaving poorly e.g. consistentlyunreachable or in error, it may be automatically unsubscribed. Further, returning a 410 code on a webhook will also automatically unsubscribe it.

Can Webhooks be viewed or edited from the application front-end?

At the moment there is no front end support for webhooks, they exist only as an API feature.

Zapier is a web automation service that lets you integrate Resource Management by Smartsheet with thousands of other apps. You can read more details on the Resource Management by Smartsheet + Zapier integrations page.

Requirements

• A Resource Management by Smartsheet account
• A Zapier account
• Optionally, an account with each service that will be connected with Resource Management by Smartsheet via Zapier

Zapier provides free and paid plans. See the Zapier pricing page for more info.

Connecting Resource Management by Smartsheet with Zapier

• This step is only required when connecting Resource Management by Smartsheet with your Zapier account for the first time
• Start by making a new Zap in your Zapier account
• Find the Resource Management by Smartsheet app and pick any trigger to initiate the setup

• When prompted, add the Resource Management by Smartsheet API Token into Zapier, test and save your connection

  

Once the connection is setup and tested, you can use it to make new Zap. Lets go through the steps and setup an example Zap.

Configuring a Zap

Configuring a Resource Management by Smartsheet Zap typically involves,

• Connecting your Resource Management by Smartsheet account with Zapier
• Selecting a Resource Management by Smartsheet trigger
• Optionally, configure one or more Search steps to look up additional details
  • Resource Management by Smartsheet Triggers typically return user or assignable IDs
  • We provide find actions so you can get additional details (e.g. a user’s email address) given their ID
  • This allows you to combine attributes you get from the trigger with additional attributes you get via searching to create Zaps that are rich in details and provide higher value.
• Choosing an app to connect with (e.g. Email)
• Configure, test and enable your Zap

Example: Send an email when a new assignment is made in Resource Management by Smartsheet

Lets try a specific example. In the steps below we will make a Zap that will send an email to when one of your team members are assigned to a project. When you are done, this is what the outline of your Zap will look like,

And here are the steps in detail,

• Sign in to your Zapier account
• Start a Zap
• Search for the Resource Management by Smartsheet app and select it
• Select a Resource Management by Smartsheet Trigger (e.g. New Assignment)

• Connect your Resource Management by Smartsheet app if prompted by supplying your Resource Management by Smartsheet API token
• Add a step to search Resource Management by Smartsheet and lookup details for the user_id in the assignment

• Add a step and select Resource Management by Smartsheet as the app
• Search and select the Find User by ID action

• Configure it to find the user for the user_id from the New Assignment trigger we setup above

  • Add a step to search Resource Management by Smartsheet and lookup details for the assignable_id in the assignment

• Add a step and select Resource Management by Smartsheet as the app

• Search and select the Find Assignable by ID action

• Configure it to find the assignable for the assignable_id from the New Assignment trigger we setup above

  • Add a step to send an email

• Select the Email by Zapier app
• Configure it to send an email to user in the New Assignment

• When you are done, the email template will look like this,

  • Test and enable your Zap.

Now, when a new assignment is made on the Resource Management by Smartsheet schedule, the person who was assigned will be sent an email with the name of the Project (or Leave) that they were assigned to and the start date of that assignment.

Filters & additional considerations

Zapier Filters are useful when building integrations with Resource Management by Smartsheet. You can use any attribute from a trigger of search action when implementing a filter. The Type attribute available in Resource Management by Smartsheet users and assignabled are particularly useful. For example, in the example above your Zap would typically exclude Placeholder users. This would be implemented by adding a FIlter to you Zap as shown below.

Familiarize yourself with the different types of users and assignables available in Resource Management by Smartsheet when designing your Resource Management by Smartsheet Zaps so you can get the result you are trying to achive with your integration. See Resource Management by Smartsheet API documentation for more details on specific attributes.

Triggers

Resource Management by Smartsheet provides the following Triggers

• New Assignment Triggers when a new assignment is created.
• New User Triggers when a new user is created.
• New Project Triggers when a new project gets created.
• New Time Entry Triggers when a new time entry is created.
• Assignment Updated Triggers when an assignment is updated.
• User Updated Triggers when a new user is updated.
• Project Updated Triggers when a project gets updated.
• Time Entry Updated Triggers when a new time entry is updated.

Actions

Resource Management by Smartsheet provides the following actions for creating or updating information in your Resource Management by Smartsheet account via Zapier

• Create Project Create a new project.
• Create User Create a new team member.
• Create Time Entry Create a new time entry.
• Update Project Updates a project.
• Update User Updates a team member.
• Update Time Entry Update a time entry.

Searches

• Find Assignable by ID Finds an existing assignable by the assignable’s ID. An assignable is anything that can be assigned to a user such as a Project or Leave type.
• Find Project by ID Finds an existing project using the project’s ID.
• Find User by ID Finds an existing user by their ID.
• Find User by Email Finds an existing user by their email.
• Find User by Name Finds an existing user by their name.
• Find Assignable by Name Finds an existing assignable by name.
• Find Project by Name Finds an existing project by name.

More details about the Resource Management by Smartsheet API

Zapier is a convenient and powerful way to consume the Resource Management by Smartsheet API. The triggers, actions and searches listed above allow you to access commonly used API functionality without having to develop custom API integrations or write software code.

The Resource Management by Smartsheet API provides access to a number of advanced features that are not currently supported with our Zapier triggers and actions.

Have a question? Contact us via our Support Page. We are here to help!