Sign in

v1

latestOpenAPI 3.0.32026-08-0613775357.6 KB
phases

Create phase

Creates a project phase.

Note: If you want the phase to inherit the parent project bill rates, set use_parent_bill_rates to true in your request body.

post/projects/{project_id}/phases

Request body

idinteger

Unique identifier for the phase instance.

archivedboolean

true if the phase is archived; false otherwise.

archived_atstring date-time

Date the phase was archived.

descriptionstring

Describes the phase.

guidstring

Globally Unique Identifier for the user.

namestring

Phase name.

parent_idinteger

If this project has a parent project, this is the parent project ID; otherwise, null.

project_codestring

A code for referencing the project phase.

secureurlstring

A secure URL to the parent project.

secureurl_expirationstring date-time

The date (in UTC) when the secure URL expires.

timeentry_lockoutinteger

The lockout indicates whether the project locks out new time entries and, if so, the number of days previous that entries are locked.

Valid values:

ValueDescription
-1Not locked
0Locked for all entries
Integer greater than or equal to 1. For example, 7.If 7, for example, then the project is locked for entries more than 7 calendar days older than the date when this value was set.

Note: We don't support setting this property to a date.

Note: A project's phases inherit the project's timeentry_lockout.

ends_atstring date

The phase's ending date.

starts_atstring date

The phase's starting date.

deleted_atstring date-time

If set, it's the date and time the user was archived; otherwise, the user is active.

created_atstring date-time

The phase's creation date.

updated_atstring date-time

Date of the most recent modification.

use_parent_bill_ratesboolean

If true, the phase uses the parent project's bill rates.

typestring

The object type.

project_state_idinteger
thumbnailstring

A thumbnail image for the project.

Note: you can't set a thumbnail for a project via the API -- to add a thumbnail, use the application UI.

owner_idinteger

Phase owner ID.

owner_namestring

Phase owner name.

phase_namestring required

Name of the phase.

has_pending_updatesboolean

true if the phase has pending updates; false otherwise.

clientstring

Client name.

project_state'Confirmed' | 'Tentative' | 'Internal'

Describes the state of the project.

bounding_startdatestring date

The earliest date (start date or date) across all project-related activities and data, including assignables, expense items, assignments, and time entries. The date may precede the project start date.

Note: This property is only included if the fields query parameter includes bounding_dates or summary.

bounding_enddatestring date

The latest date (end date or date) across all project-related activities and data, including assignables, expense items, assignments, and time entries. The date may follow the project end date.

Note: This property is only included if the fields query parameter includes bounding_dates or summary.

bounding_startdate_assignablesstring date

The earliest start date of all phases (if any) in the project. The date may precede the project start date. If there are no phases, this date is the project start date.

Note: This property is only included if the fields query parameter includes bounding_dates or summary.

bounding_enddate_assignablesstring date

The latest end date of all phases (if any) in the project. The date may follow the project end date. If there are no phases, this date is the project end date.

Note: This property is only included if the fields query parameter includes bounding_dates or summary.

bounding_startdate_expense_itemsstring date

The earliest date of all expense items (if any) in the project. The date may precede the project start date.

Note: This property is only included if the fields query parameter includes bounding_dates or summary.

bounding_enddate_expense_itemsstring date

The latest date of all expense items (if any) in the project. The date may follow the project end date.

Note: This property is only included if the fields query parameter includes bounding_dates or summary.

bounding_startdate_time_entriesstring date

The earliest date of all time entries (if any) in the project. The date may precede the project start date.

Note: This property is only included if the fields query parameter includes bounding_dates or summary.

bounding_enddate_time_entriesstring date

The latest date of all time entries (if any) in the project. The date may follow the project end date.

Note: This property is only included if the fields query parameter includes bounding_dates or summary.

bounding_startdate_assignmentsstring date

The earliest start date a user is assigned to the project. The date may precede the project start date.

Note: This property is only included if the fields query parameter includes bounding_dates or summary.

bounding_enddate_assignmentsstring date

The latest end date a user is assigned to the project. The date may follow the project end date.

Note: This property is only included if the fields query parameter includes bounding_dates or summary.

confirmed_dollarsnumber float
approved_hoursinteger
approved_dollarsnumber
unconfirmed_hoursnumber double
unconfirmed_dollarsnumber float
scheduled_hoursnumber double
scheduled_dollarsnumber float
future_hoursinteger
future_dollarsnumber

Example request

{
  "id": 45678901,
  "description": "Plan everything we must do to get this project done.",
  "guid": "d9d0de8f-32cc-4c0b-8af1-648ce039e3f6",
  "name": "PH001: Plan Phase",
  "parent_id": 821065,
  "project_code": "PH001",
  "secureurl": "https://smartsheet.com/some/path",
  "secureurl_expiration": "3000-01-01T00:00:00Z",
  "ends_at": "2025-05-29",
  "starts_at": "2025-01-27",
  "created_at": "2025-01-22T06:00:30Z",
  "updated_at": "2025-01-22T06:13:40Z",
  "type": "Project",
  "project_state_id": 8544040,
  "thumbnail": "https://10kftprojectimages.s3.amazonaws.com/a62ffd30-316f-4cb6-9c7f-eca45d07a35d/499af1a7-bc6b-446f-8535-4472e6159246.png",
  "owner_id": 11223344,
  "owner_name": "Jane Doe",
  "phase_name": "Plan",
  "client": "Your Client",
  "tags": {
    "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"
    },
    "data": [
      {
        "id": 1234567,
        "value": "New"
      }
    ]
  },
  "bounding_startdate": "2025-01-01",
  "bounding_enddate": "2025-07-01",
  "bounding_startdate_assignables": "2025-01-01",
  "bounding_enddate_assignables": "2025-07-01",
  "bounding_startdate_expense_items": "2025-01-01",
  "bounding_enddate_expense_items": "2025-07-01",
  "bounding_startdate_time_entries": "2025-01-01",
  "bounding_enddate_time_entries": "2025-07-01",
  "bounding_startdate_assignments": "2025-01-01",
  "bounding_enddate_assignments": "2025-07-01",
  "custom_field_values": {
    "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"
    },
    "data": [
      {
        "id": 9996277,
        "custom_field_name": "FY Goals",
        "custom_field_id": 23654,
        "value": "Effective Growth",
        "created_at": "2025-04-11T23:37:21Z",
        "updated_at": "2025-04-11T23:37:21Z"
      }
    ]
  },
  "confirmed_dollars": 160450,
  "unconfirmed_hours": 87.60000000000002,
  "unconfirmed_dollars": 10950,
  "scheduled_hours": 1322.400000000003,
  "scheduled_dollars": 165300
}

Response

The new project phase.

idinteger

Unique identifier for the phase instance.

archivedboolean

true if the phase is archived; false otherwise.

archived_atstring date-time

Date the phase was archived.

descriptionstring

Describes the phase.

guidstring

Globally Unique Identifier for the user.

namestring

Phase name.

parent_idinteger

If this project has a parent project, this is the parent project ID; otherwise, null.

project_codestring

A code for referencing the project phase.

secureurlstring

A secure URL to the parent project.

secureurl_expirationstring date-time

The date (in UTC) when the secure URL expires.

timeentry_lockoutinteger

The lockout indicates whether the project locks out new time entries and, if so, the number of days previous that entries are locked.

Valid values:

ValueDescription
-1Not locked
0Locked for all entries
Integer greater than or equal to 1. For example, 7.If 7, for example, then the project is locked for entries more than 7 calendar days older than the date when this value was set.

Note: We don't support setting this property to a date.

Note: A project's phases inherit the project's timeentry_lockout.

ends_atstring date

The phase's ending date.

starts_atstring date

The phase's starting date.

deleted_atstring date-time

If set, it's the date and time the user was archived; otherwise, the user is active.

created_atstring date-time

The phase's creation date.

updated_atstring date-time

Date of the most recent modification.

use_parent_bill_ratesboolean

If true, the phase uses the parent project's bill rates.

typestring

The object type.

project_state_idinteger
thumbnailstring

A thumbnail image for the project.

Note: you can't set a thumbnail for a project via the API -- to add a thumbnail, use the application UI.

owner_idinteger

Phase owner ID.

owner_namestring

Phase owner name.

phase_namestring

Name of the phase.

has_pending_updatesboolean

true if the phase has pending updates; false otherwise.

clientstring

Client name.

project_state'Confirmed' | 'Tentative' | 'Internal'

Describes the state of the project.

Example response

{
  "id": 45678901,
  "description": "Plan everything we must do to get this project done.",
  "guid": "d9d0de8f-32cc-4c0b-8af1-648ce039e3f6",
  "name": "PH001: Plan Phase",
  "parent_id": 821065,
  "project_code": "PH001",
  "secureurl": "https://smartsheet.com/some/path",
  "secureurl_expiration": "3000-01-01T00:00:00Z",
  "ends_at": "2025-05-29",
  "starts_at": "2025-01-27",
  "created_at": "2025-01-22T06:00:30Z",
  "updated_at": "2025-01-22T06:13:40Z",
  "type": "Project",
  "project_state_id": 8544040,
  "thumbnail": "https://10kftprojectimages.s3.amazonaws.com/a62ffd30-316f-4cb6-9c7f-eca45d07a35d/499af1a7-bc6b-446f-8535-4472e6159246.png",
  "owner_id": 11223344,
  "owner_name": "Jane Doe",
  "phase_name": "Plan",
  "client": "Your Client",
  "tags": {
    "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"
    },
    "data": [
      {
        "id": 1234567,
        "value": "New"
      }
    ]
  }
}